docs/四期/README.md

# 四期范围与快速索引

## 已确认业务边界

- 一期、二期、三期覆盖国内头程仓内操作，三期完成装柜及国内出仓交接；柜子确认离开国内仓库后的节点查询不属于三期。
- 四期从柜子确认国内出仓后开始定时查询船节点，持续跟踪国内出仓、港口、开航及海运在途节点，直到目的港到达并为海外提柜提供依据；海外仓作业继续覆盖安排车辆提柜、运抵合作海外仓、卸货、入库、形成库存和库内操作。
- 四期止于海外仓库存和库内作业，不包含海外仓出库单、出库履约、海外派送或其他库存离仓业务。
- “尾程订单”属于本期已确认的订单管理范围，但不得据此把海外仓出库、派送履约或 `海外派送` 原型模块整体纳入四期。
- 历史文档中把高级 BI、开放平台、移动端或性能优化称为“四期”的内容不再作为当前四期范围依据。

## 功能快速路由

| 业务域 | 本期范围 | 原型入口 |
|---|---|---|
| 海外仓 | 尾程订单、入库单、换标单、托盘管理、箱号管理、产品库、库存管理；Admin 入口 `../../apps/admin-web/src/modules/overseas-warehouse/` | 原型 `../悦/货代SAAS平台后台/prototype-src/modules/03-overseas-warehouse.html`；Backend `../../baiyue-firstleg/lastleg-service/`、`../../baiyue-firstleg/warehouse-overseas-service/`，经 `gateway-overseas/` |
| 海外业务 | 本土散板、采购订单、本土卡车；Admin 入口 `../../apps/admin-web/src/modules/overseas-business/` | 原型 `../悦/货代SAAS平台后台/prototype-src/modules/07-overseas-business.html`；Backend `../../baiyue-firstleg/lastleg-service/` 的 `procurement/`、`trucking/` 及后续本土散板子域 |
| 头程仓库主数据 | 在现有仓库类型中增加“海外仓合作仓”；实际海外仓资源独立维护 | Admin `../../apps/admin-web/src/modules/warehouses/`；国内公共主数据 `../../baiyue-firstleg/warehouse/`；海外仓资源 `../../baiyue-firstleg/warehouse-overseas-service/` |
| 通用资料 | 海外仓报价、汇率管理、车辆列表；Admin 入口 `../../apps/admin-web/src/modules/overseas-master-data/` | `../悦/货代SAAS平台后台/prototype-src/modules/10-general.html` |
| 国内出仓后船节点 | 对已确认离开国内仓库的订舱/柜次定时查询船节点，保存最新节点和查询历史，并衔接目的港提柜 | Admin `../../apps/admin-web/src/modules/port-schedules/`、`ocean-bookings/` 及货柜详情；Backend `../../baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/portschedule/`、`../../baiyue-firstleg/integration-service/` |

## 原型页面定向索引

原型本地完整入口为 `../悦/货代SAAS平台后台/index.html`。页面任务优先读取下列命中模块和页面 ID，不先加载完整原型。

### 海外仓

- 尾程订单：`last-mile-orders`、`last-mile-order-detail`。
- 入库单：`fba-inbound-order`、`fba-inbound-order-detail`；入库和退货入库相关库存视图按任务联查 `overseas-inbound`、`fba-return-inbound`。
- 换标单：`fba-relabel-order`、`fba-relabel-order-detail`；换标库存视图按任务联查 `overseas-relabel`、`fba-return-relabel`。
- 托盘管理：`fba-pallet`、`fba-pallet-detail`。
- 箱号管理：`fba-carton`、`fba-carton-detail`。
- 产品库：`fba-product`、`fba-product-detail`。
- 库存管理：`fba-stock-management`、`overseas-location`、`inventory-overview`、`warehouse-stock`、`overseas-stock`、`warehouse-stock-detail`、`inventory-transactions`、`purchase-stock`、`purchase-stock-detail`、`fba-return-stock`。

### 海外业务

- 采购订单：`overseas-purchase`、`overseas-purchase-edit`、`overseas-purchase-detail`。
- 本土卡车：`overseas-truck`、`overseas-truck-add`、`overseas-truck-edit`。
- 本土散板：`overseas-looseboard`、`overseas-looseboard-add`、`overseas-looseboard-edit`。
- `domestic-*` 和 `legacy-*` 页面不是四期默认入口；只有实际流程明确复用时才联查。

### 仓库与通用资料

- 海外仓合作仓：优先核对 `gen-partner-warehouse`，并同步核对现有平台仓库类型、接口和初始化 SQL。
- 海外仓报价：`gen-overseas-quote`；涉及车队报价时再联查 `delivery-fleet-quote`。
- 汇率管理：`gen-exchange-rate`。
- 车辆列表与详情：`vehicle`、`vehicle-detail`。

## 明确排除

- 海外仓出库及退货出库：`overseas-outbound`、`fba-outbound-order`、`fba-outbound-order-detail`、`fba-return-outbound`。
- `prototype-src/modules/04-overseas-delivery.html` 中的海外派送、出库派车、自提和其他离仓履约页面。
- 未经后续确认的财务扩展、高级 BI、开放平台、移动端、完整海外 WMS 或四期之后的出库业务。

## 船节点定时查询边界

- 现有 `CarrierScheduleQuery` 查询任务及其查询尝试、历史、来源、过期标识和频率约束整体重新归入四期；不再把它列作三期港务/船期查询能力，也不得另建一套重复任务。
- 定时查询对象必须关联真实订舱、柜次以及可用的船司/船名航次或跟踪标识，不建立脱离业务单据的孤立轮询任务。
- Firstleg `portschedule/` 负责任务编排、业务关联、最新节点、节点历史、幂等和停止条件；`integration-service/` 只负责船司或轨迹供应商适配、限流、超时、重试和错误归一化，不保存业务主数据。
- 查询从确认柜子离开国内仓库后开始，到确认目的港到达并完成海外提柜衔接后停止；失败不能伪造成功节点，需保留来源、观测时间、最近成功时间和失败原因。
- 现有“每 3 天一次、窗口最多 3 次”、六家船公司来源、最近有效结果和过期标识是同一查询能力的既有约束，归四期继续核对；后续若调整自动轮询频率、供应商额度、退避或停止规则，应只修改四期契约和这套任务。
- 当前原型没有独立的“船节点定时查询”页面；涉及页面展示时从订舱、船期或货柜详情进入，不得为了匹配原型菜单把它归入海外派送。

## 系统边界与索引维护

- 海外仓合作仓是现有头程仓库主数据的类型扩展，需同步核对 Admin `warehouses`、Warehouse Service 的 DTO/Controller/OpenAPI/SQL 及实际消费者；不得因此把海外库存业务写入国内 Warehouse Service。
- 海外库存、库内作业和海外本土业务已有明确服务入口：`gateway-overseas/` 是海外 API 网关，`lastleg-service/` 拥有尾程订单、入仓计划、换标、库存业务、采购和本土卡车，`warehouse-overseas-service/` 拥有海外仓库、库位、托盘及资源锁。不得把这些能力塞入国内 `firstleg/` 或 `warehouse/`。
- 船节点是头程海运在途事实与四期海外接柜之间的衔接能力，业务聚合继续由 Firstleg 持有；到港/可提柜结果通过明确契约或跨区域事件提供给海外区域，不复制第二套轮询任务。
- Admin、Client 仍使用统一账号体系，并按根 `AGENTS.md` 的双区域 API、海外 Token 和跨区域事件约定接入；业务页面不自行实现第二套登录。
- 新增实际代码模块、API、权限、OpenAPI 或数据库入口后，同步更新根 `AGENTS.md`、对应应用/服务 `AGENTS.md` 和本文件；不把排期、完成比例或临时任务状态写入快速索引。