html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
09ef136d718d9cf21572a20db83eb8431cb0e3fd
docs/四期
T
History
ouyangxq 2d4b8befe2 优化
2026-08-28 13:54:35 +08:00
..
README.md
优化
2026-08-28 13:54:35 +08:00
三期装柜完成后至四期人工验收手册.md
优化
2026-08-26 14:56:36 +08:00
四期后端缺口清单.md
优化
2026-08-21 16:04:21 +08:00
海外仓PDA接柜入库全流程图-20260828.png
优化
2026-08-28 10:03:35 +08:00
船节点标准化契约.md
优化
2026-08-21 16:04:21 +08:00

README.md

四期范围与快速索引

已确认业务边界

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

人工验收入口

  • 国内装柜完成后的三期尾端至四期完整人工验收，统一使用《三期装柜完成后至四期人工验收手册》。手册从 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
国内出仓后船节点 对已确认离开国内仓库的订舱/柜次定时查询船节点，保存最新节点、异常和查询历史，贯通目的港提柜至还柜事实 标准语义见船节点标准化契约；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-service 是仓库主数据唯一权威，warehouse-overseas-service/ 只拥有库位、托盘及资源锁并引用国内 warehouseId。不得把海外库存业务塞入国内 firstleg/ 或 warehouse/。
  • 国内装柜完成事件只在海外生成 PENDING_ASSIGNMENT 尾程订单、冻结快照和 FIRST_LEG 在途库存，不自动生成入仓计划。平台通过 GET /api/platform/v1/last-leg/orders/container-summaries 按稳定 sourceContainerBookingId 服务端聚合全柜订单、入仓码、计划数、未操作数和 allPlansReady，详情 /{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 和本文件；不把排期、完成比例或临时任务状态写入快速索引。
Reference in New Issue View Git Blame Copy Permalink