docs/四期/README.md

# 四期范围与快速索引

## 已确认业务边界

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

## 人工验收入口

- 国内装柜完成后的三期尾端至四期完整人工验收，统一使用[《三期装柜完成后至四期人工验收手册》](三期装柜完成后至四期人工验收手册.md)。手册从 `LOADED` 柜次开始，覆盖国内出仓、船节点、跨区建单、海外 PDA 入仓、库存/库内结果、海外主数据和海外业务，并明确区分当前可操作页面与仅后端自动化已通过的能力。

## 功能快速路由

| 业务域 | 本期范围 | 原型入口 |
|---|---|---|
| 海外仓 | 尾程订单、入库单、换标单、托盘管理、库存管理；箱号管理与产品库当前暂不进入四期正式入口；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/` |
| 海外仓排车查询与智能预排 | 平台查看排车列表/详情，按入仓计划或已收托盘筛选候选并创建待出库预排；不开放排车编辑、取消、发车、PDA 出库或派送 | Admin `../../apps/admin-web/src/modules/overseas-warehouse/pages/DispatchesView.vue`、`api/dispatches.ts`；Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/controller/DispatchQueryController.java`、`SmartDispatchController.java` |
| 海外仓客户自助服务 | 客户工作台正式开放贴标申请、仓储转运、货物废弃和退货换标；所有查询和写入只使用登录态客户范围 | Client `../../apps/client-web/src/modules/overseas-warehouse/routes.ts`、`views/WarehouseServiceView.vue`、`api/warehouseServices.ts`；Backend `../../baiyue-firstleg/lastleg-service/` 的 `relabel/`、`transfer/`、`discard/`，经 `gateway-overseas/` |
| 海外仓 PDA 柜号签收与入仓 | 独立应用 `../../apps/pda-overseas-uniapp/`；当前真实前端只开放拆柜收货，完成柜号认领、三类照片、FBA 按 SKU 箱数/OVERSEAS 逐箱实收与全柜完成 | 前端 `src/api/inbound.js`、`receiving-adapter.js`、`pages/operation/operation.vue`；Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/pda/controller/ReceivingContainerController.java`、`ReceivingContainerService.java`，经 `gateway-overseas/` |
| 海外仓 PDA 库内、托盘、换标与查询 | Lastleg 已提供 PDA 专用盘点、同仓整托移库、托盘组拆换绑、换标与库存/库位/托盘查询后端；海外 PDA 工作台入口仍禁用，前端接入前不得宣称全链路完成 | Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/pda/stocktake/`、`pda/move/`、`pda/warehouse/`、`palletops/`、`relabel/pda/`；契约 `src/main/resources/openapi/overseas-pda-operations-v1.yaml` |
| 海外业务 | 本土散板、采购订单、本土卡车；Admin 入口 `../../apps/admin-web/src/modules/overseas-business/` | 原型 `../悦/货代SAAS平台后台/prototype-src/modules/07-overseas-business.html`；Backend `../../baiyue-firstleg/lastleg-service/` 的 `procurement/`、`trucking/` 及后续本土散板子域 |
| 仓库主数据与海外资源 | 仓库 ID、类型、状态、地址、能力统一由国内仓库主数据维护；海外服务只维护库位、托盘和资源锁 | 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` |
| 国内出仓后船节点 | 对已确认离开国内仓库的订舱/柜次定时查询船节点，保存最新节点、异常和查询历史，贯通目的港提柜至还柜事实 | 标准语义见[船节点标准化契约](船节点标准化契约.md)；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 或四期之后的出库业务。

## 船节点定时查询边界

- 所有供应商统一节点、时间语义、异常事实、停止规则和新增船司接入门禁以[船节点标准化契约](船节点标准化契约.md)为准；供应商缺失的节点保持缺失，不推测补齐。

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

## 系统边界与索引维护

- 海外仓合作仓是现有头程仓库主数据的类型扩展，需同步核对 Admin `warehouses`、Warehouse Service 的 DTO/Controller/OpenAPI/SQL 及实际消费者；不得因此把海外库存业务写入国内 Warehouse Service。
- 海外库存、库内作业和海外本土业务已有明确服务入口：`gateway-overseas/` 是海外 API 网关，`lastleg-service/` 拥有尾程订单、入仓计划、换标、库存业务、采购和本土卡车；国内 `warehouse-service` 是仓库主数据唯一权威，`warehouse-overseas-service/` 只拥有库位、托盘及资源锁并引用国内 `warehouseId`。不得把海外库存业务塞入国内 `firstleg/` 或 `warehouse/`。
- 国内装柜完成事件只在海外生成 `PENDING_ASSIGNMENT` 尾程订单、冻结快照和 `FIRST_LEG` 在途库存，不自动生成入仓计划。平台通过 `GET /api/platform/v1/last-leg/orders/container-summaries` 按稳定 `sourceContainerBookingId` 服务端聚合全柜订单、入仓码和有效计划，在分页前排除全部入仓码均已生成有效独立计划的柜，仅向柜子工作台返回仍有入仓码待生成计划的柜；详情 `/{sourceContainerBookingId}` 返回柜内全部订单与计划且不受订单分页截断。`plannedArrivalAt` 只来自装柜完成事件 `estimatedWarehouseArrivalAt` 冻结到 Lastleg `ll_order.estimated_warehouse_at` 的计划到仓事实，不得使用创建时间、预计到港或当前时间替代，并按该时间升序、空值最后排序。确认后调用 `POST /api/platform/v1/last-leg/inbound-plans/convert-container`；服务端一次锁定整柜、每票独立生成一个计划，整批原子且幂等。转换成功才将尾程订单推进为 `INBOUND_PLANNED`，并把库存余额的来源入仓码展示快照替换为各自 `planNo`。
- 船节点是头程海运在途事实与四期海外接柜之间的衔接能力，业务聚合继续由 Firstleg 持有；到港/可提柜结果通过明确契约或跨区域事件提供给海外区域，不复制第二套轮询任务。
- Admin、Client 仍使用统一账号体系，并按根 `AGENTS.md` 的双区域 API、海外 Token 和跨区域事件约定接入；业务页面不自行实现第二套登录。
- 海外仓 PDA 使用独立 `apps/pda-overseas-uniapp/` 工程和发布身份，但账号仍由国内 Auth 唯一签发；真实作业请求必须经海外 Gateway 的显式 PDA 路由。当前拆柜收货已接真实 API；库内、托盘、换标和查询仍按工作台禁用状态管理，即使 Lastleg Controller 已存在也不得据此宣称设备端联调完成。
- 海外 PDA 的实际收货仓是国内 `warehouse-service` 中 `tenant_id=0`、类型为 `OVERSEAS`、状态 `ACTIVE` 且启用 `RECEIVING` 能力的平台共享物理仓，并由 `WAREHOUSE_PICKER` 的 Token Claim 固定；海外数据库只保存相同 `warehouseId` 引用。PDA 不接收仓库 ID，也不能切换柜号。海外 Gateway 对每个 `/api/pda/**` 请求在本地验签后向 Auth 实时核对账号 `token_version` 与当前仓绑定，换仓或清空绑定后旧 Token 立即失效，Auth 不可用时拒绝请求。待收柜在首次准备时原子认领到该仓，入仓计划、尾程订单和收货会话冻结实际仓 ID/名称；国内装柜事件的仓库仅作为来源仓快照，目的仓/FBA 仓也不得冒充实际收货仓。
- 新增实际代码模块、API、权限、OpenAPI 或数据库入口后，同步更新根 `AGENTS.md`、对应应用/服务 `AGENTS.md` 和本文件；不把排期、完成比例或临时任务状态写入快速索引。