html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ab2313674880c88c1c7237e872c0cf060c853732
docs/海外仓业务
T
History

README.md

海外仓业务范围与快速索引

已确认业务边界

  • 当前开发环境按端到端全流程交付，不再用开发批次切断上下游。订单与客户、入库测量与计费、国内货柜履约、海外仓业务和财务共同组成一条连续业务链。
  • 海外仓业务从国内装柜完成及确认出仓后的船节点开始，覆盖海运在途、海外接柜、卸货入仓、库存与托盘、换标、转运、废弃、退货、排车、PDA 拣货与出库、发车、转派送、派送完成、异常退回、客户回访和一件代发。
  • 海外采购、本土卡车、本土散板、海外仓报价、汇率和车辆主数据属于同一海外业务域，并统一经 gateway-overseas/ 访问。
  • 功能是否可用以正式路由、Controller/OpenAPI、权限、数据库结构和验收证据为准；历史规划只用于追溯，不再用于排除已经纳入全流程的能力。

人工验收入口

  • 端到端人工验收统一使用《虫虫出海全流程人工验收手册》。手册覆盖客户与订单、国内履约、跨区事件、海外 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/
海外仓排车与智能预排 平台查看排车列表/详情，按入仓计划或已收托盘创建预排，并完成编辑、取消、拣货、出库、发车和转派送 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/
海外仓客户自助服务 客户工作台正式开放贴标申请、仓储转运、货物废弃和退货换标；所有查询和写入只使用登录态客户范围 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/；拆柜收货完成柜号认领、三类照片、按目的类型实收与全柜完成；退货入库支持扫描退货单号或 SKU 候选并按本包实收生成退货箱和计费批次，签收后可按同客户退货单合箱 拆柜前端 src/api/inbound.js、receiving-adapter.js、pages/operation/operation.vue；退货前端 src/api/return-receipt.js、src/api/return-packing.js、pages/return-receipt/return-receipt.vue、pages/return-packing/return-packing.vue；Backend 分别为 inboundplan/pda/ 与 returnreceipt/controller/PdaReturnReceiptController.java、PdaReturnInventoryController.java，经 gateway-overseas/
海外仓 PDA 库内、托盘、换标与查询 Lastleg 提供盘点、同仓整托移库、托盘组拆换绑、换标和库存/库位/托盘查询能力；当前终端入口按工作台能力开关启用，未进入 PDA 的操作由 Admin/Client 正式页面承载 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
海外仓出库与派送 排车编辑/取消、PDA 排车拣货、出库任务、发车门禁、转派送、客户派送单和派送完成 Admin ../../apps/admin-web/src/modules/overseas-warehouse/；Overseas PDA ../../apps/pda-overseas-uniapp/src/pages/dispatch/、src/pages/outbound/；Backend ../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/、delivery/
异常退回与客户回访 异常建档、派送退回入仓、派送状态、签收/回访附件和客户回访 Admin ExceptionOrdersView.vue、CustomerVisitsView.vue；Backend exceptionorder/、customervisit/
一件代发 国内订单强制 SKU 快照、装柜工作托盘、海外 SKU/箱唛库存和一件代发出库 Backend order/、firstleg/、lastleg-service/dropship/；跨区事件见 common-event-contract/
海外业务 本土散板、采购订单、本土卡车；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。

终端与模块边界

  • 海外仓出库、派送、异常退回和一件代发已经纳入全流程，不再作为海外入仓之后的独立开发批次。
  • 派送业务由 Admin/Client 承载，不进入海外 PDA；海外 PDA 负责现场入仓、托盘、排车拣货和出库等已注册作业。
  • 箱号和产品信息作为入仓、库存、箱唛及 SKU 快照的一部分使用；是否提供独立维护页面由正式路由决定，不影响全流程状态推进。
  • 高级 BI、开放平台和独立移动 APP 属于独立产品能力，不与现有业务全流程完成状态混为一谈。

船节点定时查询边界

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

  • 现有 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，分页返回全部稳定来源柜，已生成计划的柜仍保留供接柜仓查询与修改；pendingPlanCount 区分待建计划，resourcePendingPlanCount 区分托盘资源待生成，后者仅用于自动生成异常后的重试；详情 /{sourceContainerBookingId} 返回柜内全部订单与计划且不受订单分页截断。plannedArrivalAt 只来自装柜完成事件 estimatedWarehouseArrivalAt 冻结到 Lastleg ll_order.estimated_warehouse_at 的计划到仓事实，不得使用创建时间、预计到港或当前时间替代，并按该时间升序、空值最后排序。确认后调用 POST /api/platform/v1/last-leg/inbound-plans/convert-container；服务端一次锁定整柜、每票独立生成一个计划，整批原子且幂等。转换成功才将尾程订单推进为 INBOUND_PLANNED，并把库存余额的来源入仓码展示快照替换为各自 planNo。
  • 尾程订单的 inboundCode 只保存并展示真实来源入仓码；换标申请、本土散板等没有入仓关系的海外本土业务保持为空，由页面显示 —，不得用换标单号、本土散板单号或内部 ID 冒充入仓码。
  • 平台可按单票尾程订单填写完整入库计划（入库仓、预计到仓日期、入仓码、托数、托盘类型、分配/可合托/加急和备注），写入时校验订单版本、客户归属、仓库主档和幂等键；一票柜保存后立即自动生成并绑定托盘码、海外仓托盘和资源锁，多票柜在最后一票计划齐全时自动为全柜完成同一动作。resourcePendingPlanCount 只用于自动生成失败后的显式重试，不是正常人工步骤。分配、可合托、加急必须随入库单列表和海外 PDA 入仓码作业返回并展示，其中“可合托”只向现场提供选择：合托时扫描同目的仓已使用的托盘码，独立收货时扫描新托盘码，不作为实收或完成门禁。暂扣也只作用于该票，暂扣期间该票不得进入排车或出库计划，同柜其他订单不受影响。
  • 头程散货在预装确认且真实集装箱号就绪后，按 集装箱号-FBA仓编码-三位序号 冻结托盘码；序号在当前柜、当前 FBA 仓内从 001 独立递增。送柜报关、清关提柜和预装清单共用同一按 FBA 仓分组的打印清单，可整柜打印或选择单仓前 N 张补打。该编号随装柜完成事件进入海外，生成入库计划与海外实体托盘时原样沿用；一件代发继续使用国内装箱打托形成的托盘号，不参与散货重新编号。
  • 尾程订单人工节点固定为国内报关完成、预计/实际开船、预计到港、国外清关完成、实际到港等待卸船、预约提柜和卸柜八行完整快照。第一次保存后该订单永久使用 MANUAL 来源，读取和页面展示不得再回退柜级节点，也不得反向修改货柜船节点。
  • 目的港码头拖车归 Firstleg 货柜聚合：平台从 Warehouse ACTIVE + TRUCKING 供应商中选择车队，依次记录预约提柜、实际提柜和实际还柜；实际提柜/还柜同时复用标准船节点服务写入 PICKED_UP/EMPTY_RETURNED。海外卸柜完成后由服务端以 unloadingCompletedAt + 72h 计算还柜截止时间和超时天/小时，Admin 只展示服务端预警，不在浏览器重复计算。
  • 手动还柜以真实海外卸柜完成且尚未还柜为准，仍校验独立还柜权限；无需事先存在车队、预约或提柜时间。首次命令使用版本 0 创建拖车记录，车队字段可为空，不补造提柜事实。还柜时间不得早于卸柜完成时间或已有提柜时间，成功后同步标准还柜节点并解除报空预警。
  • 船节点是头程海运在途事实与海外接柜之间的衔接能力，业务聚合继续由 Firstleg 按 containerBookingId 柜级持有，不绑定客户；跨区域事件使用 tenantId=0 平台技术范围，到港/可提柜结果通过明确契约提供给海外区域，不复制第二套轮询任务。
  • Admin、Client 仍使用统一账号体系，并按根 AGENTS.md 的双区域 API、海外 Token 和跨区域事件约定接入；业务页面不自行实现第二套登录。
  • 海外仓 PDA 使用独立 apps/pda-overseas-uniapp/ 工程和发布身份，但账号仍由国内 Auth 唯一签发；真实作业请求必须经海外 Gateway 的显式 PDA 路由。工作台只展示已注册并启用的现场作业，其他业务通过 Admin/Client 完成，不以某个终端是否承载全部操作判断端到端流程是否完成。
  • 海外 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 仓也不得冒充实际收货仓。
  • 海外 PDA 接柜候选、认领会话、三类照片与整柜完成均按 sourceContainerBookingId + containerNo 聚合，不保存客户并允许同柜多个客户。签收后为柜内每个计划按其自身客户生成任务；入仓码解析、SKU 实收、托盘占用和库存入账继续按该票真实客户隔离，整柜完成需全部计划核平且只发布一次柜级完成事件。
  • 新增实际代码模块、API、权限、OpenAPI 或数据库入口后，同步更新根 AGENTS.md、对应应用/服务 AGENTS.md 和本文件；不把排期、完成比例或临时任务状态写入快速索引。

码头车队邮件

首次选择车队后从清关提柜列表发送请求，更换车队时原子保存原车队取消和新车队提柜两封邮件；同一车队重复选择不发信。邮箱读取供应商资料，缺失或无效时阻断发送或换队。邮件顺序投递，失败待人工核对后重试。接口、临时模板和启用方式见 Firstleg 车队邮件说明。

Reference in New Issue View Git Blame Copy Permalink