docs/四期

四期范围与快速索引

已确认业务边界

• 一期、二期、三期覆盖国内头程仓内操作，三期完成装柜及国内出仓交接；柜子确认离开国内仓库后的节点查询不属于三期。
• 四期从柜子确认国内出仓后开始定时查询船节点，持续跟踪国内出仓、港口、开航、海运在途、到港、卸船、清关、提柜及还柜事实；统一语义和停止规则见船节点标准化契约。海外仓作业继续覆盖安排车辆提柜、运抵合作海外仓、卸货、入库、形成库存和库内操作。
• 四期止于海外仓库存和库内作业，不包含海外仓出库单、出库履约、海外派送或其他库存离仓业务。
• “尾程订单”属于本期已确认的订单管理范围，但不得据此把海外仓出库、派送履约或 海外派送 原型模块整体纳入四期。
• 历史文档中把高级 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/
海外仓排车查询与智能预排	平台查看排车列表/详情，按入仓计划或已收托盘筛选候选并创建待出库预排；不开放排车编辑、取消、发车、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/；四期工作台只进入到仓登记、卸柜收货、入仓上架、盘点、移库、托盘、换标和现场查询，不含出库与派送	页面/能力入口 src/data/overseas-workbench.js、src/pages/operation/operation.vue；入仓后端 ../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/pda/，仓储资源 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/ 只负责船司或轨迹供应商适配、限流、超时、重试和错误归一化，不保存业务主数据。

• 查询从确认柜子离开国内仓库后开始，贯通目的港到达、卸船、清关、提柜和还柜事实，默认在实际 EMPTY_RETURNED 后停止；这只扩展货柜轨迹事实，不纳入海外派送、海外仓出库或库存离仓业务。失败不能伪造成功节点，需保留来源、观测时间、最近成功时间和失败原因。

• 现有“每 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 和跨区域事件约定接入；业务页面不自行实现第二套登录。
• 海外仓 PDA 使用独立 apps/pda-overseas-uniapp/ 工程和发布身份，但账号仍由国内 Auth 唯一签发；真实作业请求必须经海外 Gateway 的显式 PDA 路由。当前工作台/通用作业页是静态原型时不得据此宣称 Lastleg 或 Warehouse Overseas 已完成设备联调。
• 海外 PDA 的实际收货仓是 warehouse-overseas-service 中 customer_id=0、类型为 OVERSEAS、启用 RECEIVING 能力的平台共享物理仓，并由 WAREHOUSE_PICKER 的 Token Claim 固定；PDA 不接收仓库 ID，也不能切换柜号。待收柜在首次准备时原子认领到该仓，入仓计划、尾程订单和收货会话冻结实际仓 ID/名称；国内装柜事件的仓库仅作为来源仓快照，目的仓/FBA 仓也不得冒充实际收货仓。
• 新增实际代码模块、API、权限、OpenAPI 或数据库入口后，同步更新根 AGENTS.md、对应应用/服务 AGENTS.md 和本文件；不把排期、完成比例或临时任务状态写入快速索引。