html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
ouyangxq
2026-10-21 16:40:14 +08:00
parent 5aed9d0af0
commit 846d1ffcba
12 changed files with 1000 additions and 734 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+38 -77
View File
@@ -1,88 +1,49 @@
# 虫虫出海文档索引
# 虫虫出海文档入口
项目交付文档按业务域组织。当前只有测试环境，以端到端全流程为统一范围；历史规划、确认和验收记录保留在对应业务域目录，仅用于追溯决策，不构成功能边界。
本文件只负责选入口，不保存业务规则或部署进度。已知页面、文件、API 或当前正文时跳过本文件；未知代码入口查[业务索引](业务快速索引.md)的命中行，不沿所有 README 逐层读取。
- [测试环境单机部署与配置契约](测试环境单机部署与配置契约.md)：唯一环境、部署配置、整体切换与验收。
- [统一认证与服务通信契约](统一认证与服务通信契约.md)：统一入口、权限撤销、逐事件投递与幂等。
- [业务单据编号契约](业务单据编号契约.md)：单据前缀、北京时间日流水、唯一性及保留编号范围。
## 按任务选一种入口
## 业务域文档
| 任务 | 从哪里开始 |
|---|---|
| 改代码、文案或局部逻辑 | 已知目标文件及适用 `AGENTS.md`；业务语义不明才补一段正文 |
| 只有中文业务词或多义词 | [业务索引](业务快速索引.md)，代码入口与规则正文分开选择 |
| 跨阶段流程、节点关系或上下游交接 | [全流程维护入口](头程到尾程/README.md)，只查受影响阶段 |
| 已知某个业务域，需要找规则 | 下表选择该域；找到正文后停止扩展 |
| 运行、验证、部署或数据库操作 | 下方工程专题，按操作类型只选对应章节 |
- [业务快速索引](业务快速索引.md)：按关键词检索跨端代码入口与业务边界；含独立的按需原型入口表。先查根 AGENTS.md 短路由，只读命中行。
- 终端业务细则：[Admin](../apps/admin-web/docs/business-index.md)、[Client](../apps/client-web/docs/business-index.md)、[海外 PDA](../apps/pda-overseas-uniapp/docs/business-index.md)；先从各应用 AGENTS.md 短表定位，行为变更再核对受影响条款。
## 业务域入口
- [订单与客户](订单与客户/README.md)：登录认证、客户与企业、权限、头程订单和客户工作台。
- [入库测量与计费](入库测量与计费/README.md)：预约取货、到仓收货、箱码与箱唛、测量、尺寸策略、计价和入库费用。
- [Firstleg 按需业务索引](../baiyue-firstleg/firstleg/docs/business-index.md)：服务代码入口及测量、计价、装柜、PDA 资源结算细则；先读服务 AGENTS，再查受影响条款。
- [国内货柜履约](国内货柜履约/README.md)：分柜与同柜、智能排柜、订舱、拖车、PDA 拣货、装柜、报关和国内出仓。
- [船期日历功能规划](国内货柜履约/船期日历功能规划.md)：渠道、周模板、单次船期、收货截止时间和按渠道货量统计的独立日历规划。
- [海外仓业务](海外仓业务/README.md)：船节点、海外接柜、入仓、库存、托盘、换标、转运、废弃、退货、排车、PDA 出库、派送、异常退回、客户回访、一件代发及海外本土业务。
- [Lastleg 按需业务索引](../baiyue-firstleg/lastleg-service/docs/business-index.md)：服务代码入口及事件、查询、履约约束；先读服务 AGENTS，再查受影响条款。
- [排车列表统一作业改造契约](海外仓业务/排车列表统一作业改造契约.md)：五阶段排车、一单一趟、跨客户同车、派送安排及四块排车详情的当前改造入口。
- [外配业务首版开发契约](海外仓业务/外配业务首版开发契约.md)：原排车装车后的外配车辆视图、整车承运金额、到达时间和五个装车照片位。
- [排车流程修复规划](海外仓业务/排车流程修复规划.md)：取消释放、派送状态、换标全托、合托来源和前端草稿的修复边界、分工及回归要求。
- [采购订单样品履约流程变更需求](海外仓业务/采购订单样品履约流程变更需求.md)：采购样品购买、装箱、面单、交寄、国内核费与寄客户的变更入口。
- [船节点标准化契约](海外仓业务/船节点标准化契约.md)：统一船司原始状态、标准节点、预计/实际时间、异常事实、还柜停止规则和新增船司接入门禁。
- [美国预约管理统一总览与优化方案](海外仓业务/美国预约管理统一总览与优化方案.md)：美国段各类预约的范围、关联关系、表单精简及分步实施建议。
- [预约工作日历 V13 变更说明](海外仓业务/预约工作日历V13变更说明.md)：多客户共车、分批后送、改期取消、重新预约和未定日期跟进的正式业务规则与验收场景。
- [预约工作日历开发协作契约](海外仓业务/预约工作日历开发协作契约.md)：工作日历与完整待办的接口、数据归属和开发文件边界。
- [预约送仓](海外仓业务/README.md#预约送仓)：预约日历与跨客户同仓预约入口。
- [车辆管理原型梳理与任务规划](海外仓业务/车辆管理原型梳理与任务规划.md)：司机资质、车次、自有/外接承运、运维与报价的范围及契约入口。
- [内部拼车需求池首版开发契约](海外仓业务/内部拼车需求池首版开发契约.md)：车次余位发布、销售意向、承运占位、本土订单关联及我仓上车流程。
- [财务管理](财务管理/README.md)：应收、应付、费用池、账单、收款、成本、核销、凭证以及国内外业务费用来源。
- [自营业务](自营业务/README.md)：平台自营经营总览图表、SKU 销量、分仓产品库存、库存周转视图与数据采集；Admin 入口 `apps/admin-web/src/modules/self-operated/AGENTS.md`，业务设计、采集页面与进度图、查询性能优化及领星 API 联调依据见该业务域入口。
- [打印标签维护](打印标签维护/README.md)：箱唛、各类托盘标、HOLD、BOL 与其他单据的现状盘点、参考样张和逐项改版记录。
| 业务域 | 入口 |
|---|---|
| 客户、企业、权限与头程订单 | [订单与客户](订单与客户/README.md) |
| 到仓、测量、箱码、计价与入库费用 | [入库测量与计费](入库测量与计费/README.md) |
| 分柜、装柜、订舱、拖车、报关与国内出仓 | [国内货柜履约](国内货柜履约/README.md) |
| 接柜、库存、库内服务、排车、预约与海外本土业务 | [海外仓业务](海外仓业务/README.md) |
| 费用入池、账单、资金账户与收付款 | [财务管理](财务管理/README.md) |
| 自营经营、库存周转与领星采集 | [自营业务](自营业务/README.md) |
| 箱唛、托盘标、HOLD 与 BOL | [打印标签维护](打印标签维护/README.md) |
## 全流程公共契约
## 公共契约与工程专题（命中才读）
### 当前流程入口（收尾变更只看这里）
| 主题 | 当前入口 |
|---|---|
| 服务拓扑、环境配置、部署状态与验收项 | [部署主契约](测试环境单机部署与配置契约.md) |
| Gateway、Auth 会话、服务身份与可靠投递 | [认证与通信主契约](统一认证与服务通信契约.md) |
| 平台/客户、菜单与操作权限 | [层级与权限契约](平台客户层级与权限契约.md) |
| 单据编号、订单主状态与操作 | [编号契约](业务单据编号契约.md)、[订单状态契约](统一订单主状态与操作契约.md)，按问题选一项 |
| 本机资源、最小验证、工作区与协作执行 | [工程执行约束](AI工程执行与协作约束.md) |
| Admin 样式、Client 样式或视觉验收 | [Admin 样式](Admin高密度界面规范.md)、[Client 样式](Client界面样式规范.md)、[前端验收](Admin-Client前端原型还原验收规则.md)，不将三份作为共同必读 |
| 测试 Jenkins、数据库操作与中文注释 | [测试部署指南](测试环境Jenkins部署指南.md)、[数据库操作手册](../baiyue-firstleg/deploy/sql/数据库迁移操作手册.md)、[数据库注释规范](数据库注释维护规范.md)，按操作选读 |
| 测量设备上传 | [墨家接口说明](墨家设备测量上传接口说明-V3.md) |
- [头程到尾程当前维护入口](头程到尾程/README.md)：集中进入总览、六个阶段、货柜入口、报关专题，以及页面和需求参考。
## 方案、证据与历史（按需）
### 历史与参考（保留，不作为日常流程入口）
- 独立主题设计只在该任务触发：[数据库发布方案](数据库版本迁移与Jenkins自动发布方案.md)、[生产发布方案](生产服务监控告警与无停机发布方案.md)、[生产环境方案](阿里云生产环境选型压测与上线手册.md)、[OSS 设计](阿里云OSS文件中心接入设计与评审.md)、[看板规划](首页数据看板真实化与统计策略规划.md)。方案不证明已实现或已部署。
- 原型与截图按应用指引定向查找；样板、样式核对记录、进度表和验收报告不作为日常开发入口。
- [历史流程](归档/头程到尾程/README.md)、[货柜历史](国内货柜履约/归档/README.md)、[财务历史](财务管理/归档/财务闭环盘点历史记录.md)仅用于追溯；旧双区域架构不覆盖当前主契约。
- 只有独立任务协作才查[开发环境独立任务协作登记](开发环境独立任务协作登记.md)或[测试环境独立任务协作登记](独立任务协作登记.md)，不同时读取两表。
- [头程到尾程历史文档](归档/头程到尾程/README.md)：全流程操作手册、旧现状全景、AI 上下文和易用性方案。
- [国内货柜履约历史记录](国内货柜履约/归档/README.md)：开发规划、进度、门禁、验收矩阵、审计和旧确认材料。
## 维护边界
以上文件继续保留，分别用于历史现状、操作说明和方案追溯；开发规划、进度、门禁和验收记录也按业务域保留，不再与当前节点总表同步改写。
- [跨区域认证与服务通信契约](跨区域认证与服务通信契约.md)：统一账号、国内/海外 Token、双区域 API、JWKS、Outbox/Inbox 与服务身份边界。
- [双区域部署与 Nacos 规划](双区域部署与Nacos规划.md)：开发/测试同机共置、生产国内/海外独立控制面、Nacos、数据库及 Event Bridge 部署边界。
### 通用规则与专项入口
- [平台、客户层级与权限契约](平台客户层级与权限契约.md)：平台/客户两级产品语义、列表包含详情的只读权限和跨层同步要求。
- [统一订单主状态与操作契约](统一订单主状态与操作契约.md)：统一订单状态、操作编码、内部状态映射和可信履约回传边界。
- [Admin 界面规范（样式唯一入口）](Admin高密度界面规范.md)：按任务查列表、详情、弹窗、提示与加载、蓝白主题、密度及公共样式接入；现行样式只在本文维护。
- [Admin/Client 前端验收规则](Admin-Client前端原型还原验收规则.md)：逐操作承载核对、指定视口、自动检查及人工截图证据，不另定 Admin 样式。
- [蓝白样板目录与原图](界面参考/蓝白卡片式工作台风格参考.md)：需要查看参考页面或原始截图时再读，不是第二套规范。
- 模块范围与验收记录（按任务选读，不定义通用规则）：[客户管理](Admin客户管理样式核对记录.md)、[国内仓](Admin国内仓样式核对记录.md)、[货柜管理](Admin货柜管理样式核对记录.md)、[海外仓](Admin海外仓样式核对记录.md)、[列表推广](Admin列表样式推广核对记录.md)。
- [AI 工程执行与协作约束](AI工程执行与协作约束.md)：工作区、依赖、Git、部署、数据库、质量门禁、本机多对话重型检查限流和独立任务协作规则。
- [数据库中文注释维护规范](数据库注释维护规范.md)：数据库注释口径、职责、迁移流程、自动门禁与实值验收要求。
- [数据库版本迁移与 Jenkins 自动发布方案](数据库版本迁移与Jenkins自动发布方案.md)：两人团队自动迁移规划；统一工具入口、自动编号、开发/测试/生产执行分工、单服务迁移范围、漏写迁移检查、Flyway 校验、失败候选修订、发布证据保留、带数据升级演练及实施顺序。
- [数据库迁移操作手册](../baiyue-firstleg/deploy/sql/数据库迁移操作手册.md)：开发者和发布执行人日常使用说明；包含新建、检查、生成清单、测试执行、生产晋级、失败处理和维护规则。
- [生产服务监控告警与无停机发布方案](生产服务监控告警与无停机发布方案.md)：容器与外部可用性监控、部署期告警处理、自动恢复、发布通知及滚动/蓝绿发布演进方案。
- [测试环境 Jenkins 部署指南](测试环境Jenkins部署指南.md)：测试环境持续部署授权、Job 参数、健康检查与失败处理。
- [阿里云生产环境选型、压测与上线手册](阿里云生产环境选型压测与上线手册.md)：ECS/ALB、RDS MySQL、Redis、OSS、Nacos、RocketMQ、压测、高可用、监控、备份与上线清单。
- [阿里云 OSS 文件中心接入设计与评审](阿里云OSS文件中心接入设计与评审.md)：Admin、Client、国内/海外 PDA 文件接入 OSS 的区域拓扑、存储适配、权限、一致性、实施拆分、验收门禁和方案评审。
- [首页数据看板真实化与统计策略规划](首页数据看板真实化与统计策略规划.md)：首页指标、实时与缓存边界、统计口径和实施顺序。
- [墨家设备测量上传接口说明 V3](墨家设备测量上传接口说明-V3.md)：测量设备经 Gateway 上传箱码、尺寸、重量和图片的接口契约。
## 环境协作
- [开发环境独立任务协作登记](开发环境独立任务协作登记.md)：开发环境全流程总控与长期专项的稳定任务、职责及开发数据库/部署/HTTP 授权。
- [测试环境独立任务协作登记](独立任务协作登记.md)：测试环境独立任务的稳定身份、职责和协作边界。
- [测试任务盘点与需求台账](测试任务盘点与需求台账.md)：历史任务快照、未闭环需求、提交线索和待核实证据，不作为当前调度依据。
## 参考资料
- `悦/`：产品原型、流程图、历史架构资料和调研数据，只作为需求参考，不直接定义当前范围。
- `superpowers/`：按日期和主题保留的具体功能设计与实施记录。
## 维护规则
- 新文档按业务域归档，不新增以开发批次编号命名的目录、文件、标题、任务或范围标签。
- 已完成开发阶段的流程手册、规划、进度和验收资料统一放入 `归档/`；后续流程变更只从[头程到尾程当前维护入口](头程到尾程/README.md)进入。
- 当前交付范围始终按端到端全流程理解；业务域目录只用于检索和职责归属，不用于排除上下游流程。
- 范围、字段或流程冲突时遵循根 AGENTS.md 的事实优先级；归档确认记录不覆盖当前正式契约。文档角色按当前入口和明确标记判断，不只按文件名判断。
- 业务事实变化只修改其当前主文档及实际受影响的接口、权限、SQL、代码和测试；业务域 README 与索引仅在入口或职责变化时更新。历史规划、确认和验收记录冻结，不为追随当前规则批量改写。
- 原型中出现的功能不自动成为有效实现；必须由正式契约、代码和验收证据共同确认。
同一主题优先更新现行正文，不为每轮对话新增方案、总结、进度或交接文件。只有独立主题且现有正文无法承载时才新增，并在所属域登记角色、触发条件和替代关系。已完成的过程材料冻结归档；索引只同步路径或职责变化，不复制阶段数量、字段、状态、测试结果或完成进度。事实优先级及修改范围遵循工作区根指引。
业务实现边界.md
+277
View File
@@ -0,0 +1,277 @@
# 业务实现边界
角色：按主题读取的跨端实现约束正文，承接原业务快速索引中的边界说明；不作为启动必读或部署进度来源。已知目标代码时直接工作，只有接口、状态、权限或业务归属不明确时才读取命中章节。
用 `rg -n -F '主题词' docs/业务实现边界.md` 定位标题，只读该标题到下一个同级标题。路径从工作区根或文中注明的应用 `src/` 起算；专题正式契约优先，新增专题规则只在其主文档维护，本文件保留必要的实现引用。
公共架构按主题选择[部署契约](测试环境单机部署与配置契约.md)或[认证与通信契约](统一认证与服务通信契约.md)，不因读取本文件而同时加载两份契约，也不在本文另建环境、会话或投递规则。
## 登录认证
范围依据：`docs/订单与客户/README.md`。
Admin `modules/auth/`、`core/auth/`；Client `modules/auth/`；Backend `auth/`、`iam/`。统一 Token 不携带角色或权限集；各端读取 Auth 登录/刷新响应的顶层授权快照用于展示，Gateway 与业务服务通过统一会话及 Auth 权威校验执行授权，不再依赖 Lastleg 安全投影
## 客户与企业
范围依据：`docs/订单与客户/README.md`、`docs/订单与客户/订单与客户头程订单闭环设计.md`。
Admin `modules/customers/`；Client `modules/tenant-management/`、`modules/account/`；Backend `iam/`、`auth/`、`file/`。公司联系电话/邮箱是企业资料，不作为成员登录标识且不要求跨企业唯一；成员登录手机号归账号链路，修改时同步 Auth 并撤销该账号会话。审核必填资质仅营业执照与统一社会信用代码；法人身份证选填，可在已有营业执照后单独补传或替换，营业执照仍须与统一社会信用代码整包提交；默认尺寸配置由 IAM 持久任务异步调用 `firstleg/`，未就绪不得审核通过
## 供应商与国内整柜
范围依据：`docs/国内货柜履约/国内货柜履约需求确认表.md`。
Admin `modules/suppliers/`、`modules/domestic-containers/`；Backend `warehouse/`；OpenAPI `supplier-v1.yaml`、`domestic-container-v1.yaml`
## 平台收货仓
范围依据：`docs/订单与客户/订单与客户头程订单闭环设计.md`。
Admin `modules/warehouses/`；Client `modules/first-leg/`；Backend `warehouse/`
## 头程订单、批量审核预览与入仓码关系
范围依据：`docs/订单与客户/README.md`、头程订单闭环设计。
Admin `modules/first-leg-orders/`、`modules/unified-orders/`；Client `modules/first-leg/api/inboundCodeAssociations.ts`、`modules/first-leg/`；Backend `order/` 的 `InboundCodeAssociationService`、`UnifiedOrderQueryService`、`BatchOrderReviewPreviewService` 与 `firstleg/`。Order 为 `SUBMITTED` 时，即使 Firstleg 已存在准备中入库投影，统一列表仍固定显示 `PENDING_REVIEW` 并提供审核动作；批量审核弹框只调用 `/orders/first-leg/batch-review-preview` 一次获取按请求顺序返回的快照，不逐票查询详情，主要展示入仓码而非内部订单 ID
## 客户头程订单批量导入
范围依据：当前 Order 契约。
Client `modules/first-leg/views/FirstLegOrdersView.vue`、`api/firstLeg.ts`；Backend `order/` 的 `MerchantBatchImportService`、`MerchantWarehouseCatalogClient`、`MerchantPricingCatalogClient` 与 `order-v1.yaml`。中文 XLSX 模板按当前客户动态生成地址、全部有效仓库和渠道下拉；导入时重新校验动态选项与客户归属，最多 50 行，只创建草稿，支持部分成功或整批原子模式
## 平台旧系统订单导入
范围依据：当前 Order 契约。
Admin `modules/unified-orders/pages/UnifiedOrdersView.vue`、`api/unifiedOrders.ts`；Backend `order/` 的 `PlatformLegacyOrderImportService` 与 `/api/platform/v1/orders/first-leg/legacy-import`。固定归属启用客户“IT测试公司”，保留旧入仓码，按当前公共仓库和客户价格簿逐行校验，成功行进入待审核
## 平台修改客户原始申报与履约渠道
范围依据：当前 Order/Firstleg 契约。
Admin `modules/unified-orders/components/OrderDeclarationEditorDialog.vue`、`api/unifiedOrders.ts`；Backend `order/` 的 `OrderDeclarationUpdateService` 与 `order-v1.yaml`，通过 `ORDER_DECLARATION_UPDATED_V1` 同步 `firstleg/` 的 `OrderDeclarationSyncService`。只修改申报快照，不覆盖仓库/PDA 实测、测量审核、箱码或已确认费用；渠道变化额外校验分柜、同柜、装柜可逆性与重新计价，国内收货仓或中转仓变化必须重新下单
## 脚本管理、全量验证与测试造数
范围依据：`baiyue-firstleg/scripts/AGENTS.md`、`baiyue-firstleg/scripts/README.md`。
本机重型检查经 `scripts/local-check.ps1` 统一限流，规则见 `docs/AI工程执行与协作约束.md`；Backend `scripts/` 为仓库级入口，`scripts/admin-test-env-modules/` 为 Admin HTTP 内部模块；服务局部脚本留在 `<service>/scripts/`，不得散落到 `src/test/scripts/`；真实 HTTP、部署或环境写入仍须当前轮明确授权
## 平台/企业 RBAC
范围依据：订单与客户契约；公共语义见 `docs/平台客户层级与权限契约.md`。
Admin `modules/iam/`、`core/access/`；Client `modules/tenant-management/`；Backend `iam/`、`auth/`
## 消息中心与站内通知
范围依据：触发业务的阶段/专题契约，收件箱以 IAM OpenAPI 为准。
Admin/Client `modules/notifications/`；Backend `iam/.../notification/`；生产者留在所属服务
## PDA 拣货与柜级装柜证据
范围依据：国内 PDA README、拣货原型、国内货柜履约需求确认。
PDA `pages/picking/`、`stores/picking.js`、`api/pda-loading.js`；证据以 `taskId + warehouseId` 进入任务专用 API，业务所有权固定真实 `containerBookingId`，不得按入仓单或客户拆分；上传以幂等键绑定包含文件内容的请求哈希，完全重放直接返回已有结果且不得重复上传 File；Backend `firstleg/`、`warehouse/`、`file/`
## 到仓测量、测量库位、箱规策略与头程计费
范围依据：`docs/入库测量与计费/README.md`；规则查 `baiyue-firstleg/firstleg/AGENTS.md` 对应入口。
Admin `modules/inbounds/measurement/InboundMeasurementDialog.vue`、`InboundMeasurementPanel.vue`，称重 `modules/inbounds/weight/components/WeightOcrPanel.vue`；Backend `firstleg/` 的 `InboundMeasurementService`、`MeasurementLocationOccupationService`、`FbaPricingService`。库位归 `warehouse/`，图片归 `file/`，OCR 归 `integration-service/`；只按实际调用增加服务指引
## 客户专属报价、柜级阶梯运费与费用调整
范围依据：当前 Firstleg 计价契约、`docs/入库测量与计费/README.md`。
Admin `modules/fba-pricing/carrier-rates/`、`modules/inbounds/fee/`、`modules/unified-orders/components/InboundFeeDetailManager.vue`；Backend `firstleg/` 的 `PlatformPriceBookService`、`ActivePriceBookEstimator`、`FbaPricingService`、`ContainerTierAmountAllocator`、`InboundFeeDetailService` 与 `fba-pricing-v1.yaml`。公共报价使用 `customerId=0`，客户专属报价按客户独立版本化并优先于公共 ACTIVE 版本；柜级区域重量阶梯只聚合同柜同客户中费用快照同为 `REGION_WEIGHT_TIER` 的成员并守恒分摊，混柜的固定仓价等其他模型不参与阶梯且保持原费用，装柜成员变化只重算未锁定的区域阶梯费用。人工调整计费量限系统基准上下 10% 且必须带版本、原因和二次确认；`PRIVATE_LAST_MILE_DELIVERY` 只允许私人目的仓；一件代发在预装确认前完成计价，`WAIT_PALLETIZE` 试算不得回退托盘化状态
## 箱唛、箱码与单箱测量
范围依据：`docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`、`docs/墨家设备测量上传接口说明-V3.md`。
Admin `modules/inbounds/measurement/`；Client `modules/first-leg/`；Backend 按 `firstleg/AGENTS.md` 的箱唛与测量入口
## 称重确认、整票库位块与部分拣货资源结算
范围依据：`baiyue-firstleg/firstleg/AGENTS.md` 的称重入口、`baiyue-firstleg/warehouse/AGENTS.md` 的 A0/资源结算规则。
Admin `modules/inbounds/weight/components/WeightOcrPanel.vue`；Backend Firstleg `MeasurementLocationOccupationService`、`InboundMeasurementService`、`MeasurementSubmissionService` → Warehouse `LocationBlockService`。国内整票资源结算按 `reservationId` 定位；称重、槽位容量和部分拣货的详细门禁留在所属服务指引
## 入库扣货、解除与凭证
范围依据：入库测量与计费、国内货柜履约契约。
Admin `modules/unified-orders/pages/UnifiedOrdersView.vue`、`modules/inbounds/core/api.ts`；Backend `firstleg/` 的 `InboundHoldService`、`InboundHoldGuard`、`InboundHoldEvidenceService`，文件归 `file/` 的 `INBOUND_HOLD_EVIDENCE`。扣货状态必须阻断后续物理履约写入；已发生拣货、装柜或出仓时禁止手工扣货/解除，命令携带版本与幂等键，只有进入不可变历史的凭证可下载
## 财务管理与柜级公共费用分摊
范围依据：`docs/财务管理/` 产品确认、五页验收契约、Firstleg-Finance 跨服务契约。
Admin `modules/finance/`、`modules/loading-lists/components/ContainerFeesPanel.vue`；Client `modules/finance/views/FinanceBillsView.vue`，账单行按 `inboundCode` 复用头程入仓关系详情；Backend `finance/`、`firstleg/`，契约 `container-fees-v1.yaml`；导出与凭证归 `file/`。跨客户公共柜费按柜内真实客户与订单归属原子建组，金额合计等于柜费总额，审核、驳回、调整和作废整组处理，单行入口不得破坏组一致性
## 客户资金账户、充值、授信与业务扣费
范围依据：`docs/财务管理/README.md`、统一认证与服务通信契约。
Admin `modules/finance/pages/FinanceCustomerAccountsView.vue`；Client `modules/finance/views/FinanceAccountView.vue`；Backend `finance/` 的 `FinanceWalletService` 与三类 Wallet Controller。充值申请经 File 保存凭证，平台审核或手工充扣；余额、授信、冻结、结算和释放以 Finance 主账为准。海外业务经 `WALLET_COMMAND_REQUESTED/COMPLETED` Outbox 直接投递往返，不跨区同步调用钱包
## 订单编排、分柜、同柜不可拆组与柜次
范围依据：`docs/国内货柜履约/README.md`、`docs/国内货柜履约/国内货柜履约需求确认表.md`、`docs/统一订单主状态与操作契约.md`。
Admin `modules/unified-orders/api/coLoadGroups.ts`、`modules/unified-orders/`、`container-loading/`；Client `modules/first-leg/`；Backend `firstleg/loading/coload/`、`firstleg/split/`、`firstleg/loading/`、`order/`；同柜组按订单创建，由服务端冻结每票全部可用入仓片段，仅要求同国内仓、同渠道，允许跨客户及不同目的仓港
## 全局智能排柜、预装与真实集装箱号后补
范围依据：`docs/国内货柜履约/README.md`、`docs/国内货柜履约/国内货柜履约需求确认表.md`、`docs/统一订单主状态与操作契约.md`。
Admin `modules/container-loading/components/SmartLoadingDialog.vue` 内嵌 `pages/GlobalSmartLoadingView.vue`，柜次页 `SmartLoadingWorkbenchView.vue`，预装详情 `loading-lists/pages/PreloadPlanDetailView.vue`；PDA `pages/picking/`；Backend `firstleg/` 的 `PlatformSmartLoadingController`、`SmartLoadingService`、`PendingReviewOrderClient`、`loading/`，待审核事实来自 Order `PendingReviewOrderQueryService`。全局候选覆盖 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING`，状态只用于筛选展示，能否加入以服务端 `canAssign` 为准；待审核/待测量可提前占位，但确认预装或启动 PDA 前必须进入 `WAIT_SPLIT`。暂估明细的 `totalPackageCount/remainingPackageCount` 在测量前取 Order 原始申报箱数，测量完成后取最新已审核测量箱数，读取补充失败只回退当前已分配数，写入调整仍重新校验权威数量。同柜不可拆组仅在全员命中状态集合时作为一个分页与分配单元；人工加入允许跨渠道，智能推荐仍按柜次渠道。计划可一次性移除全部未拣明细，但任一成员已拣的同柜组必须整组保留。创建柜次时原子生成唯一预装计划，加入入仓码即建立关联；真实集装箱号不阻塞订舱关联，但确认预装和创建 PDA 任务前必须补齐。历史缺号任务允许在预装详情首次补录，保存后恢复 PDA 可进入状态
## 客户入库结果与头程费用确认
范围依据：入库测量与计费主流程、当前 Firstleg 契约。
Client `modules/first-leg/components/InboundBillingPanel.vue`、`api/inboundBilling.ts`；Backend `firstleg/` 的 `MerchantInboundBillingController`、`MerchantInboundBillingService`、`FbaPricingService` 与 `firstleg-v1.yaml`。客户仅能确认本客户 `SENT` 的最新费用版本，提交 `expectedFeeVersion` 与幂等键；确认记录当前成员和时间并永久锁定该版本，平台不得再修改
## 订舱资料、放舱、出仓前船期与订舱级拖车
范围依据：国内货柜履约 README、需求确认和实施边界。
Admin `modules/ocean-bookings/`、`port-schedules/`、`trucking/`；Backend `firstleg/oceanbooking/`、`firstleg/portschedule/`、`TruckAppointmentService`。拖车预约由 `RELEASED` 订舱拥有，不按客户、柜次、装柜计划或真实柜号归属；每个订舱最多一张非终态拖车单，创建候选由服务端排除缺提单/有效订舱文件或已有有效拖车单的订舱；PDA 装柜完成不推进拖车状态；全部要求货柜确认国内离仓后自动完成，人民币拖车费按实装体积分摊为柜次应付并经 Finance Outbox 入池
## 目的港码头拖车与还空预警
范围依据：`docs/海外仓业务/README.md`。
与订舱级拖车预约是不同生命周期。Admin 海外清关提柜列表/详情 `modules/container-loading/pages/OverseasContainersView.vue`、`modules/container-loading/pages/OverseasContainerDetailView.vue`；Firstleg 拖车 API `api/terminalDrayages.ts`，柜级到仓 API `api/containerArrivalTimes.ts`。原预约/实际提柜列改为预计/实际到仓：预计时间由平台在列表快捷选择并同步 Lastleg 整柜尾程订单，实际时间取海外 PDA 首次开始收货；车队、邮件、还柜与 `unloadingCompletedAt + 72h` 预警仍归 `firstleg/terminaldrayage/`。
## 整柜报关资料与完成文件
范围依据：国内货柜履约契约。
装柜完成后由 Admin `modules/container-loading/components/ContainerCustomsPanel.vue` 管理整柜报关，Client `modules/first-leg/components/CustomsDocumentsDialog.vue`、`api/customs.ts` 按订单处理本客户退税资料；Backend `firstleg/customs/container/`、`customs-v1.yaml`，文件归 `file/`。客户资料可覆盖同柜多个退税入仓码，开始报关后冻结；平台逐资料回传完成文件，全买单柜走平台确认与明细导出
## 国内出仓确认
范围依据：国内货柜履约契约。
Admin `modules/outbound-dispatch/`；Backend `firstleg/outbound/dispatch/`
## 客户统计与平台日志
范围依据：当前统计/审计契约。
Admin `modules/customers/`、`modules/audit/`；Backend `firstleg/customerstatistics/`、`audit-service/`
## 客户工作台账户与设置
范围依据：订单与客户契约。
Client `modules/account/`、`system/`、`tenant-management/`；Backend `iam/`、`auth/`
## 企业订单与跨境业务
范围依据：订单与客户、国内货柜履约契约。
Client `modules/order-management/`、`cross-border/`；Backend `order/`、`firstleg/`、`integration-service/`
## 海外接柜、入库与库内库存
范围依据：`docs/海外仓业务/README.md`。
Admin 按 `apps/admin-web/AGENTS.md` 海外模块入口；海外入口 `gateway/`；尾程/入仓/换标/库存 `lastleg-service/`；仓库主档归国内 `warehouse/`，库位/托盘/锁归 `warehouse-overseas-service/` 并只引用国内 warehouseId；与排车、出库、派送共同组成海外仓全流程
## 尾程订单控制与柜级入仓计划转换
范围依据：`docs/海外仓业务/README.md`。
Admin `modules/overseas-warehouse/pages/LastMileOrdersView.vue`、`LastMileOrderDetailView.vue`、`api/lastMileOrders.ts`；Backend `lastleg-service/` 的 `LastlegOrderController`、`LastlegOrderCommandService`、`InboundPlanService`、`ContainerInboundPlanConversionCoordinator`，资源归 `warehouse-overseas-service/` 的 `WarehousePalletBatchService`。`orders/container-summaries` 按 `sourceContainerBookingId` 跨客户聚合并分页返回全部稳定来源柜，已完成计划转换的柜仍保留用于接柜仓查询与修改；生成动作只消费 `allPlansReady/pendingPlanCount/resourcePendingPlanCount`，详情不受列表分页截断。确认前从 `/inbound-plans/container-preview` 读取服务端分组、托数、阻断项与 `snapshotVersion/snapshotHash`；`convert-container` 锁柜重算后先批量预留真实托盘，再本地原子生成剩余独立计划并确认资源，失败仅补偿未确认资源，同柜重放不得产生第二批资源。单票手工计划保存后，全柜计划齐全且预览就绪时自动生成并绑定托盘资源，一票柜立即触发；`resourcePendingPlanCount` 表示自动生成异常后的重试入口，资源未齐不得进入 PDA 接柜。自动入口见 Lastleg `ContainerInboundPlanConversionCoordinator.convertManualAndAutoMaterialize`。单票可维护完整入库计划、暂扣/解除及八行人工节点快照；命令提交订单版本与幂等键，新增暂扣只允许完成入库后执行并仅阻断该票后续排车/出库，不阻断入库计划或入库作业；人工节点首次保存后固定 `MANUAL` 来源且不得回退柜级节点
## 海外仓 PDA
范围依据：`apps/pda-overseas-uniapp/AGENTS.md`；执行规则查 `baiyue-firstleg/lastleg-service/AGENTS.md`，跨模块流程才查海外仓 README。
入仓 `src/pages/operation/`、`src/api/inbound.js`；排车与出库 `src/pages/dispatch/`、`src/pages/outbound/`、`src/api/fulfillment.js`。Backend `lastleg-service/inboundplan/pda/`、`dispatch/pda/`、`delivery/`；统一经 `gateway/`。柜级收货与单票客户隔离按 Lastleg“PDA 入仓”规则核对
## 海外采购、本土卡车与散板
范围依据：`docs/海外仓业务/README.md`。
Admin `modules/overseas-business/`；Client `modules/cross-border/`；Backend `lastleg-service/` 的 `procurement/`、`trucking/`、`looseboard/`；统一经 `gateway/`
## 采购样品、货款、装箱清单、面单、预估快递费、国内收货寄客户
范围依据：`docs/海外仓业务/采购订单样品履约流程变更需求.md`。
采购流程变更入口；代码从上述采购模块进入
## 海外仓库与通用资料
范围依据：`docs/海外仓业务/README.md`。
全部仓库主档进入 Admin `modules/warehouses/` 与国内 `warehouse/`；海外库位/托盘/锁进入 `warehouse-overseas-service/` 并引用国内 warehouseId；报价、汇率、车辆按海外服务实际契约
## 车辆管理、司机证照、保养加油、车辆维修/故障/救援/异常、外接货与车次
范围依据：`apps/admin-web/src/modules/overseas-master-data/AGENTS.md`、`baiyue-firstleg/lastleg-service/AGENTS.md`；原型范围有疑问时查 `docs/海外仓业务/车辆管理原型梳理与任务规划.md`。
Admin `modules/overseas-master-data/`；Backend `lastleg-service/fleet/`，接口 `lastleg-service/src/main/resources/openapi/fleet-drivers-v1.yaml`、`fleet-trips-v1.yaml`、`fleet-vehicle-records-v1.yaml`；证照与运维照片存储查 `file/AGENTS.md`
## 拼车需求池、车次余位、销售拼车意向
范围依据：`docs/海外仓业务/内部拼车需求池首版开发契约.md`、`apps/admin-web/src/modules/overseas-master-data/AGENTS.md`。
复用 Lastleg Fleet 与本土业务；区分车次余位发布和客户订单，不从需求池生成第二套库存或费用
## 国内出仓后船节点
范围依据：`docs/海外仓业务/README.md`。
Admin `modules/port-schedules/`、`ocean-bookings/`、货柜详情；Backend `firstleg/portschedule/`、`integration-service/`；从确认国内出仓查询至目的港到达、提柜和还柜。节点按 `containerBookingId` 柜级聚合，跨区事件使用 `tenantId=0` 平台技术范围，不携带或校验客户
## 海外出库、排车、派送、异常与回访
范围依据：排车改造查[排车列表统一作业改造契约](海外仓业务/排车列表统一作业改造契约.md)；既有缺陷修复查[排车流程修复规划](海外仓业务/排车流程修复规划.md)。
Admin `modules/overseas-warehouse/pages/DispatchesView.vue`、`DispatchDetailView.vue`、`OutboundsView.vue`、`DeliveryOrdersView.vue`、`ExceptionOrdersView.vue`、`CustomerVisitsView.vue`；Backend `lastleg-service/dispatch/`、`delivery/`、`dropship/`、`exceptionorder/`、`customervisit/`；统一经 `gateway/`
## 海外业务费用来源与客户财务
范围依据：当前实现查财务契约与统一认证与服务通信契约；阶段 0A—0E 开发再读 `docs/财务管理/海外仓费用统一接入阶段0技术契约.md`。
当前 V1 由 `lastleg-service/financefee/` 校验海外入仓、采购、美国卡车、本土散板和海外仓服务费，通过完整快照和 Outbox 直接投递 Finance 内部入口入池；阶段 0 目标改为收费身份/候选版本、Finance 接受或拒绝结果事件及版本化资金计划。必须沿代码确认落地范围，不把技术契约当成已实现状态；Client 仍只读取获准客户财务
## 自营销量与领星统计
范围依据：`docs/自营业务/README.md`。
领星 WMS 自研系统（OMP）、经营总览图表、自营 SKU 日销量、热销与滞销排行、分仓产品库存与可售天数、库存周转、数据采集：先读 `apps/admin-web/src/modules/self-operated/AGENTS.md`；查询与采集编排查 `baiyue-firstleg/lastleg-service/AGENTS.md` 的自营入口，签名/限流/供应商分页问题才读 `baiyue-firstleg/integration-service/AGENTS.md`。区别于整箱库存和客户 WMS 作业库存。
自营专题按任务选择：总览图形/下钻查 `docs/自营业务/经营总览图表设计.md`，库存周转查 `docs/自营业务/库存周转视图设计.md`，采集交互查 `docs/自营业务/数据采集页面设计.md`，查询性能查 `docs/自营业务/领星统计查询性能优化方案.md`，外部接口联调查 `docs/自营业务/领星WMS接口联调手册.md`。架构/表结构不明时从 `docs/自营业务/README.md` 定位一期方案，不默认同时读取所有专题。
## 预约管理与工作日历
范围依据：`docs/海外仓业务/预约工作日历V13变更说明.md`（业务规则）；`docs/海外仓业务/预约工作日历开发协作契约.md`（接口与文件边界），按本次问题选一项。
美国各类预约统一总览、提柜/用车/送仓预约梳理：`docs/海外仓业务/美国预约管理统一总览与优化方案.md`（设计建议）；实际维护仍按下述来源模块进入。
预约工作日历、多客户共车、中转分批后送、改期取消、重新预约和未定日期事项：先读 `docs/海外仓业务/预约工作日历V13变更说明.md`（正式业务规则与验收），再读 `docs/海外仓业务/预约工作日历开发协作契约.md`（接口与文件边界）；权威业务事实仍由下述来源模块维护。
预约管理、预约列表、到港/排车/还柜/计划到仓四类日历：Admin `apps/admin-web/src/modules/appointment-calendar/`，当前入口与日期规则见 `docs/海外仓业务/预约工作日历V13变更说明.md` 的“2026-10-19 当前预约列表收敛规则”；原送仓业务仍从 `docs/海外仓业务/README.md` 的“预约送仓”进入。排车只取海外仓送往 FBA/客户仓的真实车次，区别于订舱级拖车和港口提柜。
## 退货预报、签收、库存与合箱
范围依据：`baiyue-firstleg/lastleg-service/docs/business-index.md` 的退货入口。
退货预报、签收、库存与合箱：Client `modules/overseas-warehouse/views/ReturnOrdersView.vue`、`ReturnInventoryView.vue`；Admin `modules/overseas-warehouse/pages/ReturnInventoryManagementView.vue`；海外 PDA `src/pages/return-receipt/return-receipt.vue`、`src/pages/return-packing/return-packing.vue`，API 与检查入口见 `apps/pda-overseas-uniapp/AGENTS.md`；Backend `lastleg-service/returnreceipt/`，执行规则先读 `baiyue-firstleg/lastleg-service/AGENTS.md`，详细接口与状态按需查 `baiyue-firstleg/lastleg-service/docs/business-index.md` 的退货入口，OpenAPI 为 `overseas-business-v1.yaml`。客户预报 → 平台审核 → PDA 签收 → 退货箱/SKU 库存 → 同客户合箱 → `delivery/` 退货出库；两个 PDA 页面均在 `src/pages.json` 注册，由 `src/data/overseas-workbench.js` 提供入口，真机验收另取证。派送异常退回仍归 `exceptionorder/`。
## 散货托盘码生成、打印与跨区传递
范围依据：`docs/打印标签维护/README.md`；各应用/服务最近指引。
散货托盘码生成、打印与跨区传递：Admin `modules/loading-lists/components/PalletLabelPrintDialog.vue`；Firstleg `LoadingPalletLabelService`、`LoadingCompletedOutboxService`；Lastleg `LastlegSourcePalletMapper`、`InboundPlanService`。从各项目最近指引继续定位；散货 FBA 标签与一件代发实装托盘分别取各自冻结事实。
业务快速索引.md
+51 -95
View File
@@ -1,36 +1,12 @@
# 业务快速索引
本文件按需检索，不作为启动必读文档。以下路径均按工作区根目录或表内注明的应用源码根目录起算，不相对于 docs/。
本文件只负责消除歧义与定位，不是启动必读清单。已知文件、组件或 API 时跳过本文件；先按终端选应用，再用 `rg -n -F '组合词' docs/业务快速索引.md` 读取命中行。
Firstleg 代码从 `baiyue-firstleg/firstleg/AGENTS.md` 的短表定位；状态、计价、装柜和 PDA 资源规则按需查 `baiyue-firstleg/firstleg/docs/business-index.md` 对应条款，不全文加载其他业务。
Admin、Client、海外 PDA 从各应用 AGENTS.md 短表定位，行为变更按需查 [Admin 细则](../apps/admin-web/docs/business-index.md)、[Client 细则](../apps/client-web/docs/business-index.md)、[海外 PDA 细则](../apps/pda-overseas-uniapp/docs/business-index.md)；Lastleg 的事件、查询与履约细则见[服务业务索引](../baiyue-firstleg/lastleg-service/docs/business-index.md)，只读取受影响条款。
架构/环境/部署查[测试环境单机部署与配置契约](测试环境单机部署与配置契约.md)；网关/Token/会话撤销/事件通信查[统一认证与服务通信契约](统一认证与服务通信契约.md)。下文旧区域服务路径用于定位现有实现，目标规则以这两份主契约为准。
代码问题直接进入列出的模块并读适用指引；只有业务边界不清时才读“边界正文”的命中章节，不串读各层 README、其他应用索引或整个正文文件。表内代码入口相对工作区根，前端仍按任务终端分流；服务端入口不要求纯展示任务先读后端。
## 常用说法与歧义分流
仓储转运审核、转运驳回：Admin 尾程订单 `apps/admin-web/src/modules/overseas-warehouse/pages/LastMileOrdersView.vue` → `apps/admin-web/src/modules/overseas-warehouse/components/WarehouseTransferReviewDialog.vue`；权限、状态及 API 见该模块 `AGENTS.md` 的“仓储转运审核、通过与驳回”。不要把该入口当作头程订单审单，也不要按“转运”误入排车转派送。
先从任务中取“终端 + 业务对象 + 动作”，如“海外 PDA + 柜号 + 收货”。优先检索下面列出的组合词，不拿整句自然语言做精确匹配；命中后沿指定模块继续，不把所有含同一宽词的行全部读入。代码路径从工作区根起算，检索提示不替代业务契约。
- 审核：订单审核 / 测量审核 / 仓储转运审核，分别进入 Order / Firstleg / Admin 海外仓模块。
- 库位：海外库位 / 整票库位块，分别进入 Warehouse Overseas / 国内 Warehouse，按任务只选其一。
- 收货：柜号签收 / 到仓测量，分别进入 Lastleg `ReceivingContainerService` / Firstleg 测量入口。
- 拖车：订舱级拖车 / 目的港码头拖车，分别进入 Firstleg `TruckAppointmentService` / `TerminalDrayageService`。
- 托盘：自动生成托盘 / 托盘标签，前者进入 Lastleg `ContainerInboundPlanConversionCoordinator`；后者先区分国内散货、一件代发与海外资源。
先在本节定位组合词，再只查命中的一行或模块。仍无法区分且会改变修改范围时，补问终端、对象或操作阶段。
### 高频任务最小读取集
- 订单审核：根 `AGENTS.md` → `docs/业务快速索引.md` 本节 → `apps/admin-web/src/modules/unified-orders/` → `baiyue-firstleg/order/AGENTS.md`；只有审核门禁跨到履约时才增加 `firstleg/AGENTS.md`。不读海外仓审核或全量权限 SQL。
- PDA 出库：根 `AGENTS.md` → `apps/pda-overseas-uniapp/AGENTS.md` → `src/pages/dispatch/` 和 `src/api/fulfillment.js` → `lastleg-service/AGENTS.md`；只有网关路径或 Token 失败才增加 `gateway/AGENTS.md`。不读 Admin 排车配置，除非问题涉及平台转派送资格。
- 客户账单：根 `AGENTS.md` → Client `apps/client-web/AGENTS.md` → `src/modules/finance/` → `baiyue-firstleg/finance/AGENTS.md`；平台账单才切换 Admin Finance。不要因“账单”自动加载柜费分摊或海外费用契约。
- 退货、异常、拖车：先用终端、阶段和动作分流；无法确定时只读取本节对应行，不全文加载海外仓 README 或 Lastleg 全部业务索引。
- Admin 弹窗样式、统一弹窗：先读 [Admin 统一弹窗规范](Admin高密度界面规范.md#弹框与表单)，再进入当前大模块最近指引和实际弹窗组件；逐操作核对记录按 [Admin/Client 验收规则](Admin-Client前端原型还原验收规则.md) 维护。
每个入口标出业务边界，避免把相邻生命周期当作同一业务。读取量与适用指引层级统一遵循根 AGENTS.md；已提供的根规则不重复全文加载，跨服务只增加实际涉及的直接消费者或提供者。
取“终端＋对象＋动作”组合词；只读命中行。不同解释会改变范围且仍无法判断时再询问。
| 常用说法 | 区分依据 | 首个定位范围 |
|---|---|---|
@@ -58,76 +34,56 @@ Admin、Client、海外 PDA 从各应用 AGENTS.md 短表定位，行为变更
| 退货、退货预报、退货换标、退货签收、退货合箱 | 客户退货预报及签收库存，区别于派送异常退回 | Client `apps/client-web/src/modules/overseas-warehouse/views/ReturnOrdersView.vue`；Admin `apps/admin-web/src/modules/overseas-warehouse/pages/ReturnInventoryManagementView.vue`；PDA `apps/pda-overseas-uniapp/AGENTS.md`；Lastleg `returnreceipt/`，见下文“退货预报、签收、库存与合箱” |
| PDA 出库、PDA 发车、扫码出库、整托出库 | 海外 PDA 执行排车和出库，不是平台排车配置或客户派送查询 | 海外 PDA `apps/pda-overseas-uniapp/src/pages/dispatch/dispatch.vue`、`src/api/fulfillment.js`；Backend `baiyue-firstleg/lastleg-service/dispatch/pda/`；统一经 `gateway/` |
| 异常、退回、退仓、回访 | 派送异常退回与库存退货业务不可混用 | 派送查 `apps/admin-web/src/modules/overseas-warehouse/pages/ExceptionOrdersView.vue`；退货预报/库存查 Lastleg `returnreceipt/` |
## 定位步骤与反馈
- 已知文件、组件或请求路径：读取适用指引后直接进入该文件或限定服务搜索路由，无需经过词表。
- 页面问题：终端指引 → 命中页面 → 实际 import/API → 对应 Controller/Service。纯展示问题定位到相关组件即可；遇到后端业务判断再追踪调用链。
- 状态或权限问题：已知请求时先定位 Controller 的权限与 Service 的状态门禁，再核对前端消费；尚不知请求时从触发动作找到 API。不要先扫所有权限初始化 SQL。
- 无精确命中：从用户原话提取短词查本表；仍有歧义时利用页面标题、业务编号类型和国内/海外范围缩小。每次只扩展相邻业务范围。
- 实际任务若发生入口误导、路径失效或重复扩大搜索，在当次交付中简记“原说法 → 最终入口 → 绕路原因”，并修正命中的索引行；进度与临时结果不写回本文件。
- 评价检索质量看首次入口是否正确、扩大范围次数、找到目标前额外读取的无关文件数；文件存在或离线合同通过只能证明部分有效性，不能代替真实任务耗时。普通任务不额外建立计时脚本或登记台账。
| 仓储转运审核、转运驳回 | 平台转运审核，区别于头程审单和排车 | `apps/admin-web/src/modules/overseas-warehouse/components/WarehouseTransferReviewDialog.vue` |
## 业务快速路由表
领星 WMS 自研系统（OMP）、经营总览图表、自营 SKU 日销量、热销与滞销排行、分仓产品库存与可售天数、库存周转、数据采集：先读 `apps/admin-web/src/modules/self-operated/AGENTS.md`；查询与采集编排查 `baiyue-firstleg/lastleg-service/AGENTS.md` 的自营入口，签名/限流/供应商分页问题才读 `baiyue-firstleg/integration-service/AGENTS.md`。区别于整箱库存和客户 WMS 作业库存。
自营专题按任务选择：总览图形/下钻查 `docs/自营业务/经营总览图表设计.md`，库存周转查 `docs/自营业务/库存周转视图设计.md`，采集交互查 `docs/自营业务/数据采集页面设计.md`，查询性能查 `docs/自营业务/领星统计查询性能优化方案.md`，外部接口联调查 `docs/自营业务/领星WMS接口联调手册.md`。架构/表结构不明时从 `docs/自营业务/README.md` 定位一期方案，不默认同时读取所有专题。
美国各类预约统一总览、提柜/用车/送仓预约梳理：`docs/海外仓业务/美国预约管理统一总览与优化方案.md`（设计建议）；实际维护仍按下述来源模块进入。
预约工作日历、多客户共车、中转分批后送、改期取消、重新预约和未定日期事项：先读 `docs/海外仓业务/预约工作日历V13变更说明.md`（正式业务规则与验收），再读 `docs/海外仓业务/预约工作日历开发协作契约.md`（接口与文件边界）；权威业务事实仍由下述来源模块维护。
预约管理、预约列表、到港/排车/还柜/计划到仓四类日历：Admin `apps/admin-web/src/modules/appointment-calendar/`，当前入口与日期规则见 `docs/海外仓业务/预约工作日历V13变更说明.md` 的“2026-10-19 当前预约列表收敛规则”；原送仓业务仍从 `docs/海外仓业务/README.md` 的“预约送仓”进入。排车只取海外仓送往 FBA/客户仓的真实车次，区别于订舱级拖车和港口提柜。
退货预报、签收、库存与合箱：Client `modules/overseas-warehouse/views/ReturnOrdersView.vue`、`ReturnInventoryView.vue`；Admin `modules/overseas-warehouse/pages/ReturnInventoryManagementView.vue`；海外 PDA `src/pages/return-receipt/return-receipt.vue`、`src/pages/return-packing/return-packing.vue`，API 与检查入口见 `apps/pda-overseas-uniapp/AGENTS.md`；Backend `lastleg-service/returnreceipt/`，执行规则先读 `baiyue-firstleg/lastleg-service/AGENTS.md`，详细接口与状态按需查 `baiyue-firstleg/lastleg-service/docs/business-index.md` 的退货入口，OpenAPI 为 `overseas-business-v1.yaml`。客户预报 → 平台审核 → PDA 签收 → 退货箱/SKU 库存 → 同客户合箱 → `delivery/` 退货出库；两个 PDA 页面均在 `src/pages.json` 注册，由 `src/data/overseas-workbench.js` 提供入口，真机验收另取证。派送异常退回仍归 `exceptionorder/`。
本表只路由到范围依据和首个代码入口；Admin/Client 路径从对应应用的 `src/` 起算，国内 PDA 路径从 `apps/pda-uniapp/` 起算，海外 PDA 路径从 `apps/pda-overseas-uniapp/src/` 起算，Backend 路径从 `baiyue-firstleg/` 起算。进入目标后继续读最近的 `AGENTS.md`，不要把根表当作模块细节清单。
| 业务 | 范围依据 | 首个代码入口 |
| 业务 | 首个代码入口 | 边界正文（仅需要规则时读） |
|---|---|---|
| 登录认证 | `docs/订单与客户/README.md` | Admin `modules/auth/`、`core/auth/`；Client `modules/auth/`；Backend `auth/`、`iam/`。统一 Token 不携带角色或权限集；各端读取 Auth 登录/刷新响应的顶层授权快照用于展示，Gateway 与业务服务通过统一会话及 Auth 权威校验执行授权，不再依赖 Lastleg 安全投影 |
| 客户与企业 | `docs/订单与客户/README.md`、`docs/订单与客户/订单与客户头程订单闭环设计.md` | Admin `modules/customers/`；Client `modules/tenant-management/`、`modules/account/`；Backend `iam/`、`auth/`、`file/`。公司联系电话/邮箱是企业资料，不作为成员登录标识且不要求跨企业唯一；成员登录手机号归账号链路，修改时同步 Auth 并撤销该账号会话。审核必填资质仅营业执照与统一社会信用代码；法人身份证选填，可在已有营业执照后单独补传或替换，营业执照仍须与统一社会信用代码整包提交；默认尺寸配置由 IAM 持久任务异步调用 `firstleg/`，未就绪不得审核通过 |
| 供应商与国内整柜 | `docs/国内货柜履约/国内货柜履约需求确认表.md` | Admin `modules/suppliers/`、`modules/domestic-containers/`；Backend `warehouse/`；OpenAPI `supplier-v1.yaml`、`domestic-container-v1.yaml` |
| 平台收货仓 | `docs/订单与客户/订单与客户头程订单闭环设计.md` | Admin `modules/warehouses/`；Client `modules/first-leg/`；Backend `warehouse/` |
| 头程订单、批量审核预览与入仓码关系 | `docs/订单与客户/README.md`、头程订单闭环设计 | Admin `modules/first-leg-orders/`、`modules/unified-orders/`；Client `modules/first-leg/api/inboundCodeAssociations.ts`、`modules/first-leg/`；Backend `order/` 的 `InboundCodeAssociationService`、`UnifiedOrderQueryService`、`BatchOrderReviewPreviewService` 与 `firstleg/`。Order 为 `SUBMITTED` 时，即使 Firstleg 已存在准备中入库投影，统一列表仍固定显示 `PENDING_REVIEW` 并提供审核动作；批量审核弹框只调用 `/orders/first-leg/batch-review-preview` 一次获取按请求顺序返回的快照，不逐票查询详情，主要展示入仓码而非内部订单 ID |
| 客户头程订单批量导入 | 当前 Order 契约 | Client `modules/first-leg/views/FirstLegOrdersView.vue`、`api/firstLeg.ts`；Backend `order/` 的 `MerchantBatchImportService`、`MerchantWarehouseCatalogClient`、`MerchantPricingCatalogClient` 与 `order-v1.yaml`。中文 XLSX 模板按当前客户动态生成地址、全部有效仓库和渠道下拉；导入时重新校验动态选项与客户归属，最多 50 行，只创建草稿，支持部分成功或整批原子模式 |
| 平台旧系统订单导入 | 当前 Order 契约 | Admin `modules/unified-orders/pages/UnifiedOrdersView.vue`、`api/unifiedOrders.ts`；Backend `order/` 的 `PlatformLegacyOrderImportService` 与 `/api/platform/v1/orders/first-leg/legacy-import`。固定归属启用客户“IT测试公司”，保留旧入仓码，按当前公共仓库和客户价格簿逐行校验，成功行进入待审核 |
| 平台修改客户原始申报与履约渠道 | 当前 Order/Firstleg 契约 | Admin `modules/unified-orders/components/OrderDeclarationEditorDialog.vue`、`api/unifiedOrders.ts`；Backend `order/` 的 `OrderDeclarationUpdateService` 与 `order-v1.yaml`，通过 `ORDER_DECLARATION_UPDATED_V1` 同步 `firstleg/` 的 `OrderDeclarationSyncService`。只修改申报快照，不覆盖仓库/PDA 实测、测量审核、箱码或已确认费用；渠道变化额外校验分柜、同柜、装柜可逆性与重新计价，国内收货仓或中转仓变化必须重新下单 |
| 脚本管理、全量验证与测试造数 | `baiyue-firstleg/scripts/AGENTS.md`、`baiyue-firstleg/scripts/README.md` | 本机重型检查经 `scripts/local-check.ps1` 统一限流，规则见 `docs/AI工程执行与协作约束.md`；Backend `scripts/` 为仓库级入口，`scripts/admin-test-env-modules/` 为 Admin HTTP 内部模块；服务局部脚本留在 `<service>/scripts/`，不得散落到 `src/test/scripts/`；真实 HTTP、部署或环境写入仍须当前轮明确授权 |
| 平台/企业 RBAC | 订单与客户契约；公共语义见 `docs/平台客户层级与权限契约.md` | Admin `modules/iam/`、`core/access/`；Client `modules/tenant-management/`；Backend `iam/`、`auth/` |
| 消息中心与站内通知 | 触发业务的阶段/专题契约，收件箱以 IAM OpenAPI 为准 | Admin/Client `modules/notifications/`；Backend `iam/.../notification/`；生产者留在所属服务 |
| PDA 拣货与柜级装柜证据 | 国内 PDA README、拣货原型、国内货柜履约需求确认 | PDA `pages/picking/`、`stores/picking.js`、`api/pda-loading.js`；证据以 `taskId + warehouseId` 进入任务专用 API，业务所有权固定真实 `containerBookingId`，不得按入仓单或客户拆分；上传以幂等键绑定包含文件内容的请求哈希，完全重放直接返回已有结果且不得重复上传 File；Backend `firstleg/`、`warehouse/`、`file/` |
| 到仓测量、测量库位、箱规策略与头程计费 | `docs/入库测量与计费/README.md`；规则查 `baiyue-firstleg/firstleg/AGENTS.md` 对应入口 | Admin `modules/inbounds/measurement/InboundMeasurementDialog.vue`、`InboundMeasurementPanel.vue`，称重 `modules/inbounds/weight/components/WeightOcrPanel.vue`；Backend `firstleg/` 的 `InboundMeasurementService`、`MeasurementLocationOccupationService`、`FbaPricingService`。库位归 `warehouse/`，图片归 `file/`，OCR 归 `integration-service/`；只按实际调用增加服务指引 |
| 客户专属报价、柜级阶梯运费与费用调整 | 当前 Firstleg 计价契约、`docs/入库测量与计费/README.md` | Admin `modules/fba-pricing/carrier-rates/`、`modules/inbounds/fee/`、`modules/unified-orders/components/InboundFeeDetailManager.vue`；Backend `firstleg/` 的 `PlatformPriceBookService`、`ActivePriceBookEstimator`、`FbaPricingService`、`ContainerTierAmountAllocator`、`InboundFeeDetailService` 与 `fba-pricing-v1.yaml`。公共报价使用 `customerId=0`，客户专属报价按客户独立版本化并优先于公共 ACTIVE 版本；柜级区域重量阶梯只聚合同柜同客户中费用快照同为 `REGION_WEIGHT_TIER` 的成员并守恒分摊，混柜的固定仓价等其他模型不参与阶梯且保持原费用，装柜成员变化只重算未锁定的区域阶梯费用。人工调整计费量限系统基准上下 10% 且必须带版本、原因和二次确认；`PRIVATE_LAST_MILE_DELIVERY` 只允许私人目的仓；一件代发在预装确认前完成计价，`WAIT_PALLETIZE` 试算不得回退托盘化状态 |
| 箱唛、箱码与单箱测量 | `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`、`docs/墨家设备测量上传接口说明-V3.md` | Admin `modules/inbounds/measurement/`；Client `modules/first-leg/`；Backend 按 `firstleg/AGENTS.md` 的箱唛与测量入口 |
| 称重确认、整票库位块与部分拣货资源结算 | `baiyue-firstleg/firstleg/AGENTS.md` 的称重入口、`baiyue-firstleg/warehouse/AGENTS.md` 的 A0/资源结算规则 | Admin `modules/inbounds/weight/components/WeightOcrPanel.vue`；Backend Firstleg `MeasurementLocationOccupationService`、`InboundMeasurementService`、`MeasurementSubmissionService` → Warehouse `LocationBlockService`。国内整票资源结算按 `reservationId` 定位；称重、槽位容量和部分拣货的详细门禁留在所属服务指引 |
| 入库扣货、解除与凭证 | 入库测量与计费、国内货柜履约契约 | Admin `modules/unified-orders/pages/UnifiedOrdersView.vue`、`modules/inbounds/core/api.ts`；Backend `firstleg/` 的 `InboundHoldService`、`InboundHoldGuard`、`InboundHoldEvidenceService`，文件归 `file/` 的 `INBOUND_HOLD_EVIDENCE`。扣货状态必须阻断后续物理履约写入；已发生拣货、装柜或出仓时禁止手工扣货/解除，命令携带版本与幂等键，只有进入不可变历史的凭证可下载 |
| 财务管理与柜级公共费用分摊 | `docs/财务管理/` 产品确认、五页验收契约、Firstleg-Finance 跨服务契约 | Admin `modules/finance/`、`modules/loading-lists/components/ContainerFeesPanel.vue`；Client `modules/finance/views/FinanceBillsView.vue`，账单行按 `inboundCode` 复用头程入仓关系详情；Backend `finance/`、`firstleg/`，契约 `container-fees-v1.yaml`；导出与凭证归 `file/`。跨客户公共柜费按柜内真实客户与订单归属原子建组，金额合计等于柜费总额，审核、驳回、调整和作废整组处理，单行入口不得破坏组一致性 |
| 客户资金账户、充值、授信与业务扣费 | `docs/财务管理/README.md`、统一认证与服务通信契约 | Admin `modules/finance/pages/FinanceCustomerAccountsView.vue`；Client `modules/finance/views/FinanceAccountView.vue`；Backend `finance/` 的 `FinanceWalletService` 与三类 Wallet Controller。充值申请经 File 保存凭证，平台审核或手工充扣；余额、授信、冻结、结算和释放以 Finance 主账为准。海外业务经 `WALLET_COMMAND_REQUESTED/COMPLETED` Outbox 直接投递往返，不跨区同步调用钱包 |
| 订单编排、分柜、同柜不可拆组与柜次 | `docs/国内货柜履约/README.md`、`docs/国内货柜履约/国内货柜履约需求确认表.md`、`docs/统一订单主状态与操作契约.md` | Admin `modules/unified-orders/api/coLoadGroups.ts`、`modules/unified-orders/`、`container-loading/`；Client `modules/first-leg/`；Backend `firstleg/loading/coload/`、`firstleg/split/`、`firstleg/loading/`、`order/`；同柜组按订单创建，由服务端冻结每票全部可用入仓片段，仅要求同国内仓、同渠道，允许跨客户及不同目的仓港 |
| 全局智能排柜、预装与真实集装箱号后补 | 同上 | Admin `modules/container-loading/components/SmartLoadingDialog.vue` 内嵌 `pages/GlobalSmartLoadingView.vue`，柜次页 `SmartLoadingWorkbenchView.vue`，预装详情 `loading-lists/pages/PreloadPlanDetailView.vue`；PDA `pages/picking/`；Backend `firstleg/` 的 `PlatformSmartLoadingController`、`SmartLoadingService`、`PendingReviewOrderClient`、`loading/`，待审核事实来自 Order `PendingReviewOrderQueryService`。全局候选覆盖 `PENDING_REVIEW/WAIT_MEASURE/WAIT_SPLIT/LOADING`，状态只用于筛选展示，能否加入以服务端 `canAssign` 为准；待审核/待测量可提前占位，但确认预装或启动 PDA 前必须进入 `WAIT_SPLIT`。暂估明细的 `totalPackageCount/remainingPackageCount` 在测量前取 Order 原始申报箱数，测量完成后取最新已审核测量箱数，读取补充失败只回退当前已分配数，写入调整仍重新校验权威数量。同柜不可拆组仅在全员命中状态集合时作为一个分页与分配单元；人工加入允许跨渠道，智能推荐仍按柜次渠道。计划可一次性移除全部未拣明细，但任一成员已拣的同柜组必须整组保留。创建柜次时原子生成唯一预装计划，加入入仓码即建立关联；真实集装箱号不阻塞订舱关联，但确认预装和创建 PDA 任务前必须补齐。历史缺号任务允许在预装详情首次补录，保存后恢复 PDA 可进入状态 |
| 客户入库结果与头程费用确认 | 入库测量与计费主流程、当前 Firstleg 契约 | Client `modules/first-leg/components/InboundBillingPanel.vue`、`api/inboundBilling.ts`；Backend `firstleg/` 的 `MerchantInboundBillingController`、`MerchantInboundBillingService`、`FbaPricingService` 与 `firstleg-v1.yaml`。客户仅能确认本客户 `SENT` 的最新费用版本，提交 `expectedFeeVersion` 与幂等键；确认记录当前成员和时间并永久锁定该版本，平台不得再修改 |
| 订舱资料、放舱、出仓前船期与订舱级拖车 | 国内货柜履约 README、需求确认和实施边界 | Admin `modules/ocean-bookings/`、`port-schedules/`、`trucking/`；Backend `firstleg/oceanbooking/`、`firstleg/portschedule/`、`TruckAppointmentService`。拖车预约由 `RELEASED` 订舱拥有，不按客户、柜次、装柜计划或真实柜号归属；每个订舱最多一张非终态拖车单，创建候选由服务端排除缺提单/有效订舱文件或已有有效拖车单的订舱；PDA 装柜完成不推进拖车状态；全部要求货柜确认国内离仓后自动完成，人民币拖车费按实装体积分摊为柜次应付并经 Finance Outbox 入池 |
| 目的港码头拖车与还空预警 | `docs/海外仓业务/README.md` | 与订舱级拖车预约是不同生命周期。Admin 海外清关提柜列表/详情 `modules/container-loading/pages/OverseasContainersView.vue`、`modules/container-loading/pages/OverseasContainerDetailView.vue`；Firstleg 拖车 API `api/terminalDrayages.ts`，柜级到仓 API `api/containerArrivalTimes.ts`。原预约/实际提柜列改为预计/实际到仓：预计时间由平台在列表快捷选择并同步 Lastleg 整柜尾程订单，实际时间取海外 PDA 首次开始收货；车队、邮件、还柜与 `unloadingCompletedAt + 72h` 预警仍归 `firstleg/terminaldrayage/`。 |
| 整柜报关资料与完成文件 | 国内货柜履约契约 | 装柜完成后由 Admin `modules/container-loading/components/ContainerCustomsPanel.vue` 管理整柜报关，Client `modules/first-leg/components/CustomsDocumentsDialog.vue`、`api/customs.ts` 按订单处理本客户退税资料；Backend `firstleg/customs/container/`、`customs-v1.yaml`，文件归 `file/`。客户资料可覆盖同柜多个退税入仓码，开始报关后冻结；平台逐资料回传完成文件，全买单柜走平台确认与明细导出 |
| 国内出仓确认 | 国内货柜履约契约 | Admin `modules/outbound-dispatch/`；Backend `firstleg/outbound/dispatch/` |
| 客户统计与平台日志 | 当前统计/审计契约 | Admin `modules/customers/`、`modules/audit/`；Backend `firstleg/customerstatistics/`、`audit-service/` |
| 客户工作台账户与设置 | 订单与客户契约 | Client `modules/account/`、`system/`、`tenant-management/`；Backend `iam/`、`auth/` |
| 企业订单与跨境业务 | 订单与客户、国内货柜履约契约 | Client `modules/order-management/`、`cross-border/`；Backend `order/`、`firstleg/`、`integration-service/` |
| 海外接柜、入库与库内库存 | `docs/海外仓业务/README.md` | Admin 按 `apps/admin-web/AGENTS.md` 海外模块入口；海外入口 `gateway/`；尾程/入仓/换标/库存 `lastleg-service/`；仓库主档归国内 `warehouse/`，库位/托盘/锁归 `warehouse-overseas-service/` 并只引用国内 warehouseId；与排车、出库、派送共同组成海外仓全流程 |
| 尾程订单控制与柜级入仓计划转换 | `docs/海外仓业务/README.md` | Admin `modules/overseas-warehouse/pages/LastMileOrdersView.vue`、`LastMileOrderDetailView.vue`、`api/lastMileOrders.ts`；Backend `lastleg-service/` 的 `LastlegOrderController`、`LastlegOrderCommandService`、`InboundPlanService`、`ContainerInboundPlanConversionCoordinator`，资源归 `warehouse-overseas-service/` 的 `WarehousePalletBatchService`。`orders/container-summaries` 按 `sourceContainerBookingId` 跨客户聚合并分页返回全部稳定来源柜，已完成计划转换的柜仍保留用于接柜仓查询与修改；生成动作只消费 `allPlansReady/pendingPlanCount/resourcePendingPlanCount`，详情不受列表分页截断。确认前从 `/inbound-plans/container-preview` 读取服务端分组、托数、阻断项与 `snapshotVersion/snapshotHash`；`convert-container` 锁柜重算后先批量预留真实托盘，再本地原子生成剩余独立计划并确认资源，失败仅补偿未确认资源，同柜重放不得产生第二批资源。单票手工计划保存后，全柜计划齐全且预览就绪时自动生成并绑定托盘资源，一票柜立即触发；`resourcePendingPlanCount` 表示自动生成异常后的重试入口，资源未齐不得进入 PDA 接柜。自动入口见 Lastleg `ContainerInboundPlanConversionCoordinator.convertManualAndAutoMaterialize`。单票可维护完整入库计划、暂扣/解除及八行人工节点快照；命令提交订单版本与幂等键，新增暂扣只允许完成入库后执行并仅阻断该票后续排车/出库，不阻断入库计划或入库作业；人工节点首次保存后固定 `MANUAL` 来源且不得回退柜级节点 |
| 海外仓 PDA | `apps/pda-overseas-uniapp/AGENTS.md`；执行规则查 `baiyue-firstleg/lastleg-service/AGENTS.md`，跨模块流程才查海外仓 README | 入仓 `src/pages/operation/`、`src/api/inbound.js`；排车与出库 `src/pages/dispatch/`、`src/pages/outbound/`、`src/api/fulfillment.js`。Backend `lastleg-service/inboundplan/pda/`、`dispatch/pda/`、`delivery/`；统一经 `gateway/`。柜级收货与单票客户隔离按 Lastleg“PDA 入仓”规则核对 |
| 海外采购、本土卡车与散板 | `docs/海外仓业务/README.md` | Admin `modules/overseas-business/`；Client `modules/cross-border/`；Backend `lastleg-service/` 的 `procurement/`、`trucking/`、`looseboard/`；统一经 `gateway/` |
| 采购样品、货款、装箱清单、面单、预估快递费、国内收货寄客户 | `docs/海外仓业务/采购订单样品履约流程变更需求.md` | 采购流程变更入口；代码从上述采购模块进入 |
| 海外仓库与通用资料 | `docs/海外仓业务/README.md` | 全部仓库主档进入 Admin `modules/warehouses/` 与国内 `warehouse/`；海外库位/托盘/锁进入 `warehouse-overseas-service/` 并引用国内 warehouseId；报价、汇率、车辆按海外服务实际契约 |
| 车辆管理、司机证照、保养加油、车辆维修/故障/救援/异常、外接货与车次 | `apps/admin-web/src/modules/overseas-master-data/AGENTS.md`、`baiyue-firstleg/lastleg-service/AGENTS.md`；原型范围有疑问时查 `docs/海外仓业务/车辆管理原型梳理与任务规划.md` | Admin `modules/overseas-master-data/`；Backend `lastleg-service/fleet/`，接口 `lastleg-service/src/main/resources/openapi/fleet-drivers-v1.yaml`、`fleet-trips-v1.yaml`、`fleet-vehicle-records-v1.yaml`；证照与运维照片存储查 `file/AGENTS.md` |
| 拼车需求池、车次余位、销售拼车意向 | `docs/海外仓业务/内部拼车需求池首版开发契约.md`、`apps/admin-web/src/modules/overseas-master-data/AGENTS.md` | 复用 Lastleg Fleet 与本土业务；区分车次余位发布和客户订单，不从需求池生成第二套库存或费用 |
| 国内出仓后船节点 | `docs/海外仓业务/README.md` | Admin `modules/port-schedules/`、`ocean-bookings/`、货柜详情；Backend `firstleg/portschedule/`、`integration-service/`；从确认国内出仓查询至目的港到达、提柜和还柜。节点按 `containerBookingId` 柜级聚合，跨区事件使用 `tenantId=0` 平台技术范围，不携带或校验客户 |
| 海外出库、排车、派送、异常与回访 | 排车改造查[排车列表统一作业改造契约](海外仓业务/排车列表统一作业改造契约.md)；既有缺陷修复查[排车流程修复规划](海外仓业务/排车流程修复规划.md) | Admin `modules/overseas-warehouse/pages/DispatchesView.vue`、`DispatchDetailView.vue`、`OutboundsView.vue`、`DeliveryOrdersView.vue`、`ExceptionOrdersView.vue`、`CustomerVisitsView.vue`；Backend `lastleg-service/dispatch/`、`delivery/`、`dropship/`、`exceptionorder/`、`customervisit/`；统一经 `gateway/` |
| 海外业务费用来源与客户财务 | 当前实现查财务契约与统一认证与服务通信契约；阶段 0A—0E 开发再读 `docs/财务管理/海外仓费用统一接入阶段0技术契约.md` | 当前 V1 由 `lastleg-service/financefee/` 校验海外入仓、采购、美国卡车、本土散板和海外仓服务费，通过完整快照和 Outbox 直接投递 Finance 内部入口入池；阶段 0 目标改为收费身份/候选版本、Finance 接受或拒绝结果事件及版本化资金计划。必须沿代码确认落地范围，不把技术契约当成已实现状态；Client 仍只读取获准客户财务 |
散货托盘码生成、打印与跨区传递：Admin `modules/loading-lists/components/PalletLabelPrintDialog.vue`；Firstleg `LoadingPalletLabelService`、`LoadingCompletedOutboxService`；Lastleg `LastlegSourcePalletMapper`、`InboundPlanService`。从各项目最近指引继续定位；散货 FBA 标签与一件代发实装托盘分别取各自冻结事实。
| 登录认证 | [模块指引](../apps/admin-web/src/modules/auth/AGENTS.md) | [对应章节](业务实现边界.md#登录认证) |
| 客户与企业 | [模块指引](../apps/admin-web/src/modules/customers/AGENTS.md) | [对应章节](业务实现边界.md#客户与企业) |
| 供应商与国内整柜 | [模块指引](../apps/admin-web/src/modules/suppliers/AGENTS.md) | [对应章节](业务实现边界.md#供应商与国内整柜) |
| 平台收货仓 | [模块指引](../apps/admin-web/src/modules/warehouses/AGENTS.md) | [对应章节](业务实现边界.md#平台收货仓) |
| 头程订单、批量审核预览与入仓码关系 | [模块指引](../apps/admin-web/src/modules/unified-orders/AGENTS.md) | [对应章节](业务实现边界.md#头程订单批量审核预览与入仓码关系) |
| 客户头程订单批量导入 | [模块指引](../apps/client-web/src/modules/first-leg/AGENTS.md) | [对应章节](业务实现边界.md#客户头程订单批量导入) |
| 平台旧系统订单导入 | [模块指引](../apps/admin-web/src/modules/unified-orders/AGENTS.md) | [对应章节](业务实现边界.md#平台旧系统订单导入) |
| 平台修改客户原始申报与履约渠道 | [模块指引](../apps/admin-web/src/modules/unified-orders/AGENTS.md) | [对应章节](业务实现边界.md#平台修改客户原始申报与履约渠道) |
| 脚本管理、全量验证与测试造数 | [模块指引](../baiyue-firstleg/scripts/AGENTS.md) | [对应章节](业务实现边界.md#脚本管理全量验证与测试造数) |
| 平台/企业 RBAC | [模块指引](../apps/admin-web/src/modules/iam/AGENTS.md) | [对应章节](业务实现边界.md#平台企业-rbac) |
| 消息中心与站内通知 | [模块指引](../apps/admin-web/src/modules/notifications/AGENTS.md) | [对应章节](业务实现边界.md#消息中心与站内通知) |
| PDA 拣货与柜级装柜证据 | [模块指引](../apps/pda-uniapp/AGENTS.md) | [对应章节](业务实现边界.md#pda-拣货与柜级装柜证据) |
| 到仓测量、测量库位、箱规策略与头程计费 | [模块指引](../apps/admin-web/src/modules/inbounds/AGENTS.md) | [对应章节](业务实现边界.md#到仓测量测量库位箱规策略与头程计费) |
| 客户专属报价、柜级阶梯运费与费用调整 | [模块指引](../apps/admin-web/src/modules/fba-pricing/AGENTS.md) | [对应章节](业务实现边界.md#客户专属报价柜级阶梯运费与费用调整) |
| 箱唛、箱码与单箱测量 | [模块指引](../baiyue-firstleg/firstleg/AGENTS.md) | [对应章节](业务实现边界.md#箱唛箱码与单箱测量) |
| 称重确认、整票库位块与部分拣货资源结算 | [模块指引](../baiyue-firstleg/warehouse/AGENTS.md) | [对应章节](业务实现边界.md#称重确认整票库位块与部分拣货资源结算) |
| 入库扣货、解除与凭证 | [模块指引](../apps/admin-web/src/modules/unified-orders/AGENTS.md) | [对应章节](业务实现边界.md#入库扣货解除与凭证) |
| 财务管理与柜级公共费用分摊 | [模块指引](../apps/admin-web/src/modules/finance/AGENTS.md) | [对应章节](业务实现边界.md#财务管理与柜级公共费用分摊) |
| 客户资金账户、充值、授信与业务扣费 | [模块指引](../apps/client-web/AGENTS.md) | [对应章节](业务实现边界.md#客户资金账户充值授信与业务扣费) |
| 订单编排、分柜、同柜不可拆组与柜次 | [模块指引](../apps/admin-web/src/modules/container-loading/AGENTS.md) | [对应章节](业务实现边界.md#订单编排分柜同柜不可拆组与柜次) |
| 全局智能排柜、预装与真实集装箱号后补 | [模块指引](../apps/admin-web/src/modules/container-loading/AGENTS.md) | [对应章节](业务实现边界.md#全局智能排柜预装与真实集装箱号后补) |
| 客户入库结果与头程费用确认 | [模块指引](../apps/client-web/src/modules/first-leg/AGENTS.md) | [对应章节](业务实现边界.md#客户入库结果与头程费用确认) |
| 订舱资料、放舱、出仓前船期与订舱级拖车 | [模块指引](../apps/admin-web/src/modules/ocean-bookings/AGENTS.md) | [对应章节](业务实现边界.md#订舱资料放舱出仓前船期与订舱级拖车) |
| 目的港码头拖车与还空预警 | [模块指引](../baiyue-firstleg/firstleg/AGENTS.md) | [对应章节](业务实现边界.md#目的港码头拖车与还空预警) |
| 整柜报关资料与完成文件 | [模块指引](../apps/admin-web/src/modules/container-loading/AGENTS.md) | [对应章节](业务实现边界.md#整柜报关资料与完成文件) |
| 国内出仓确认 | [模块指引](../apps/admin-web/src/modules/outbound-dispatch/AGENTS.md) | [对应章节](业务实现边界.md#国内出仓确认) |
| 客户统计与平台日志 | [模块指引](../apps/admin-web/src/modules/customers/AGENTS.md) | [对应章节](业务实现边界.md#客户统计与平台日志) |
| 客户工作台账户与设置 | [模块指引](../apps/client-web/AGENTS.md) | [对应章节](业务实现边界.md#客户工作台账户与设置) |
| 企业订单与跨境业务 | [模块指引](../apps/client-web/AGENTS.md) | [对应章节](业务实现边界.md#企业订单与跨境业务) |
| 海外接柜、入库与库内库存 | [模块指引](../apps/admin-web/src/modules/overseas-warehouse/AGENTS.md) | [对应章节](业务实现边界.md#海外接柜入库与库内库存) |
| 尾程订单控制与柜级入仓计划转换 | [模块指引](../apps/admin-web/src/modules/overseas-warehouse/AGENTS.md) | [对应章节](业务实现边界.md#尾程订单控制与柜级入仓计划转换) |
| 海外仓 PDA | [模块指引](../apps/pda-overseas-uniapp/AGENTS.md) | [对应章节](业务实现边界.md#海外仓-pda) |
| 海外采购、本土卡车与散板 | [模块指引](../apps/admin-web/src/modules/overseas-business/AGENTS.md) | [对应章节](业务实现边界.md#海外采购本土卡车与散板) |
| 采购样品、货款、装箱清单、面单、预估快递费、国内收货寄客户 | [模块指引](../apps/admin-web/src/modules/overseas-business/AGENTS.md) | [对应章节](业务实现边界.md#采购样品货款装箱清单面单预估快递费国内收货寄客户) |
| 海外仓库与通用资料 | [模块指引](../baiyue-firstleg/warehouse-overseas-service/AGENTS.md) | [对应章节](业务实现边界.md#海外仓库与通用资料) |
| 车辆管理、司机证照、保养加油、车辆维修/故障/救援/异常、外接货与车次 | [模块指引](../apps/admin-web/src/modules/overseas-master-data/AGENTS.md) | [对应章节](业务实现边界.md#车辆管理司机证照保养加油车辆维修故障救援异常外接货与车次) |
| 拼车需求池、车次余位、销售拼车意向 | [模块指引](../apps/admin-web/src/modules/overseas-master-data/AGENTS.md) | [对应章节](业务实现边界.md#拼车需求池车次余位销售拼车意向) |
| 国内出仓后船节点 | [模块指引](../apps/admin-web/src/modules/port-schedules/AGENTS.md) | [对应章节](业务实现边界.md#国内出仓后船节点) |
| 海外出库、排车、派送、异常与回访 | [模块指引](../apps/admin-web/src/modules/overseas-warehouse/AGENTS.md) | [对应章节](业务实现边界.md#海外出库排车派送异常与回访) |
| 海外业务费用来源与客户财务 | [模块指引](../baiyue-firstleg/finance/AGENTS.md) | [对应章节](业务实现边界.md#海外业务费用来源与客户财务) |
| 自营销量与领星统计 | [模块指引](../apps/admin-web/src/modules/self-operated/AGENTS.md) | [对应章节](业务实现边界.md#自营销量与领星统计) |
| 预约管理与工作日历 | [模块指引](../apps/admin-web/src/modules/appointment-calendar/AGENTS.md) | [对应章节](业务实现边界.md#预约管理与工作日历) |
| 退货预报、签收、库存与合箱 | [模块指引](../baiyue-firstleg/lastleg-service/AGENTS.md) | [对应章节](业务实现边界.md#退货预报签收库存与合箱) |
| 散货托盘码生成、打印与跨区传递 | [模块指引](../apps/admin-web/src/modules/loading-lists/AGENTS.md) | [对应章节](业务实现边界.md#散货托盘码生成打印与跨区传递) |
## 原型入口索引
@@ -143,6 +99,6 @@ Admin、Client、海外 PDA 从各应用 AGENTS.md 短表定位，行为变更
| PDA 拣货 | `docs/悦/PDA拣货/pda-picking.html` |
| WMS 字段补充 | `docs/悦/货代SAAS平台后台/wms_full_data.json`、`docs/悦/货代SAAS平台后台/柏悦WMS系统文档.md` |
| 国内货柜履约原型盘点 | `docs/国内货柜履约/国内货柜履约页面与原型清单.md` |
| 海外仓全流程 | `docs/海外仓业务/README.md` 的页面 ID 索引 |
| 海外仓 PDA | `apps/pda-overseas-uniapp/AGENTS.md`、`apps/pda-overseas-uniapp/src/data/overseas-workbench.js`、`apps/pda-overseas-uniapp/src/pages/operation/operation.vue` 与 `docs/海外仓业务/README.md` |
| 海外仓全流程 | [海外仓页面 ID](海外仓业务/业务规则.md#原型页面定向索引) |
| 海外仓 PDA | `apps/pda-overseas-uniapp/AGENTS.md`、`apps/pda-overseas-uniapp/src/data/overseas-workbench.js`、`apps/pda-overseas-uniapp/src/pages/operation/operation.vue` 与[海外仓页面 ID](海外仓业务/业务规则.md#原型页面定向索引) |
| Admin/Client 验收 | `docs/Admin-Client前端原型还原验收规则.md` |
国内货柜履约/README.md
+2 -2
View File
@@ -1,6 +1,6 @@
# 国内货柜履约
本目录负责国内分柜、订舱、拖车、拣货、装柜、装柜后的报关协同、送港、进港和甩柜事实。整体货柜流程进入收尾，**报关协同代码尚未完成**；当前只在这里查找流程节点，报关开发请转到交接清单。
本目录负责国内分柜、订舱、拖车、拣货、装柜、装柜后的报关协同、送港、进港和甩柜事实。本入口只维护流程路由；代码、部署和验收状态以环境主契约及实际证据为准，不在此重复记录。
## 当前流程入口
@@ -9,7 +9,7 @@
- [阶段四：海运、目的港与尾程计划](../头程到尾程分阶段流程/阶段四-海运目的港与尾程计划.md)：实际开船后的海运、目的港和尾程计划衔接。
- [报关资料与船期价格接入梳理](报关资料与船期价格接入梳理.md)：报关资料、报关行回执、客户确认/打回、正式申报、海关结果和船期价格专题。
- [船期日历功能规划](船期日历功能规划.md)：渠道、周模板、单次船期、收货截止时间和按渠道货量统计的独立日历规划。
- [报关代码开发交接清单](../头程到尾程/报关代码开发交接清单.md)：报关代码当前未完成时，下一开发对话使用的范围和验收条件。
- [报关代码开发交接清单](../头程到尾程/报关代码开发交接清单.md)：报关专项的实现范围与验收线索，任务确实涉及时读取，不代表当前完成状态。
## 货柜关键节点
头程到尾程分阶段流程/README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 头程到尾程分阶段流程
本目录是端到端流程的分段查找入口。F01-F40 流程基线已确认，当前用于全流程收尾变更；阶段三报关协同代码已接入并通过真实 HTTP 验收。总览和节点关系看[《头程到尾程流程节点梳理》](../头程到尾程流程节点梳理.md)，字段、页面操作、权限和异常细节在对应阶段文件维护。
本目录是端到端流程的分段查找入口。F01-F40 流程基线已确认，当前用于全流程收尾变更；本入口不记录代码、部署或验收进度，相关事实只查环境主契约。总览和节点关系看[《头程到尾程流程节点梳理》](../头程到尾程流程节点梳理.md)，字段、页面操作、权限和异常细节在对应阶段文件维护。
## 三大业务块与六个分段
测试环境单机部署与配置契约.md
+21
View File
@@ -1,5 +1,14 @@
# 测试环境单机部署与配置契约
## 2026-10-21 清关提柜与预约日历到仓日期一致性修复
- 用户已授权修改后部署 TEST 并执行 HTTP 联调。Admin **#677 SUCCESS**，提交 `536308f3ec987a4bbe6e814a83f3b55f4a1bab71`，以测试环境 #676 / `e6c864a2a64e` 为基线，仅包含本轮 11 文件；Lastleg **#400 SUCCESS**，提交 `1ad357d259010bcf3c005a358c58e118a0cfd303`，以 #399 / `6fe632f28ead` 为基线，仅包含本轮 5 文件。未混入在途排车异常/照片修改，两个容器均 running/healthy；两项 Jenkins 临时 SCM 标签均已恢复原配置，同时保留流水线更新的参数属性。
- 预约日历与清关提柜列表、详情共用日期投影：实际到港优先，其次预计到港；未人工维护、未建计划时展示到港当地日期加两个自然日的默认值，不制造零点、不自动保存。柜级查询补充 `planCount` 并与日历对齐人工/冻结时间语义，已有计划时列表禁改；无数据库结构、SQL、Gateway 或 Nacos 变更。
- 本地定向前端 112 项、后端 33 项通过；模板行类型修正后，列表 49 项复测、生产和受影响测试类型检查、生产构建通过。Lastleg CI 复用本地定向测试结果，跳过测试执行但保留生产与测试源码编译。未声称全仓回归通过。
- 真实 HTTP 与线上资源 21 项断言通过。`MSCU7264022` 首次只读查询为 version 0、无计划，实际到港 `2026-10-21T14:49:15`，默认日期应为 `2026-10-23`；调查期间该柜变为已保存 `2026-10-24T00:00:00`、version 1、1 票入库计划，验收核对三处均优先采用该冻结时间。本轮业务核查只有读取/查询请求，没有修改该柜时间或创建计划。另以既有 `TSTU4808232` 验证未维护场景：实际到港 9 月 29 日，默认到仓 10 月 1 日，列表、详情与日历一致且无具体时刻；自有登录会话均已退出。
- 后续 review 发现未关闭边界：Firstleg 日历到港读取按 `observed_at/id` 取最新实际节点，清关提柜 `actualFacts.arrivedDestinationPortAt` 仍按历史 `actual_at` 最大值聚合。同一节点后续观测修正为更早时间时，未人工维护柜的默认到仓仍可能不一致；两条实际 SELECT 已用合成数据在内存中复现（23日后修正为21日，清关提柜默认25日、日历默认23日），没有访问共享数据库或写业务数据。运行中的 Firstleg `b4ff441a7030` 两份查询源码与复核代码一致。原柜已冻结的24日时间不受该边界影响；此前21项只证明已测场景，不代表该边界已通过。
- 证据：`baiyue-firstleg/reports/warehouse-arrival-677-20261021/summary.json`。发布、自动检查及原 HTTP 场景通过；上述日期来源一致性边界待修复。未执行浏览器视觉验收，不能据此声称已通过人工页面截图确认。
## 2026-10-21 FBA 正式确认缺项提示发布与 HTTP 验收
@@ -26,6 +35,11 @@
- 用户授权处理的 5 条旧时区预约中，3 条 ABE4 历史批次已被分批/合并替代，正式取消接口返回 A0409，未修改。另 2 条 `AP-20261016-955ABD8BD866`、`YY202610210002` 已正式取消并保留取消历史；ONT8 / ACY2 公共主档分别按初始化基线修正为 `America/Los_Angeles` / `America/New_York`。取消不释放原实物分配，因此通过原批次更新接口重新安排，两个批次均回查为 PENDING、版本 2 和正确 IANA 时区；未通过 SQL 改写历史。证据位于 `baiyue-firstleg/reports/full-acceptance-20261021-repair/appointment-*-journal.json`。
- 定向首轮 `targeted.json`：1960 项断言，1947 通过、13 失败，31 个模块、1156 个独立请求。失败集中于 OCR 空字段/修正确认版本的脚本误判、服务重启期间采购请求 HTTP 500、预约完整扫描未完成。OCR 已按服务端合同修复并通过 6 项直接合同测试；船期和海外业务直接合同 10 项通过。
- 预约同步在 15:27 完成整轮扫描后，`appointment-verify-r3-journal.json` 证明汇总、日历、事项列表均成功。期间 Lastleg 由其他工作发生重启，本轮未触发部署；不得把恢复单独归因于数据修复，也不把定向结果视为全量通过。修复后定向复测继续进行。
- 修复后 Admin 默认全量 `admin-full-r2.json`：16698 项断言、16670 通过、28 失败；170 次模块执行、138 个独立模块、9963 个独立请求、零跳过模块。详细失败保存于 `admin-full-r2-failures.json`。更深入的链路已执行，断言总量与 r1 不同，不能简单把两轮失败数当作同一覆盖范围比较。220 个根级及 Admin 合同文件的离线批次 `offline-full.tap` 为 2287 通过、零失败/跳过；批次后修改的清关文案、同步就绪条件、采购编号和手机号重试分别另有直接复测，不改写原批次结果。
- r2 剩余包括：未离仓清关的旧文案断言；开船来源改变后的同步就绪等待；换标/转运使用非权威箱号、部分废弃未选择具体箱；退货合箱缺箱内清点；逐票核实来源无实际船节点；BOL 缺来源/预约分配核实及实测缺 palletSpaces；F40 候选完整性；散板需求池至签收覆盖缺口；平台权限测试手机号冲突；采购编号仍按旧客户前缀判断。前两处及手机号、采购编号脚本已修正，HTTP 后继验证以独立报告为准，其余尚未闭合，不能宣称全量通过。
- `runtime.json` 核对 Lastleg 为 `6fe632f28ead`、Firstleg 为 `b4ff441a7030` 且 healthy，分别于 15:24、15:33 重启；由其他任务发生，本轮未部署。OCR 接口与人工确认链在 r2 通过，但识别状态为 FAILED，仍不构成识别效果或真机验收证据。
- 后继 HTTP `readiness-r3.json`：1646 项全部通过、24 个模块、969 个独立请求；清关文案和两种同步就绪条件已实际闭合。`master-data-r3.json`：164 项全部通过、98 个独立请求，包含权限用户创建及无权访问拒绝。两份均零跳过模块，只闭合各自受影响项，不宣称另一次全量全绿；采购编号修正尚无后继完整钱包链 HTTP 通过证据。
- 批次收尾 `offline-full-r2.tap`：220 个文件、2288 项全部通过，零失败/跳过，修改脚本语法检查通过。`repair-summary.json` 将原 r2 的 28 条失败按后继证据闭合 9 条，仍有 19 条未闭合断言（含连锁失败与覆盖缺口）；保留 Client 专项样本缺失、OCR 识别未成功和 UI/真机未验边界。
- 本批优化验收范围与报告口径，修复固定称重托盘缺失时借其他托盘兜底、重派脚本仍调用手工派送/发车、初始化基线及迁移/OpenAPI断言滞后、PowerShell子进程版本和文案误触静态断言等问题。当前默认Admin范围为71个模块，可选模块单列，不将本地合同、HTTP和页面验收混为一个结果。
- 根级85个、Admin模块137个测试文件共2290项：完整离线批次2289通过、1条静态断言失败；最后修改的船司合同及直接相关异常合同复测14项全部通过。按受影响文件替换复测结果后，2290项均有通过证据、零跳过；这是批次加定向复测的汇总，不改写原失败报告，也不宣称单次全量零失败。
@@ -2902,3 +2916,10 @@ Client #382（`a0736239e4ee4cd58b620dab912ffc0641360d9f`）正式页面在1920×
- 用户针对 backend-java #707 的空 IMAGE_REPOSITORY 失败授权固定配置。通过 Jenkins API 核实 #706 成功构建的实际地址，并将相同值写入 backend-java 与13个 baiyue-firstleg- 单服务Job的参数默认值；14项逐一回读通过。保存前核对无运行/排队任务、无构建触发器，保存后按XML语义核对仅此默认值变化；真实地址保留在Jenkins配置，不写入源码与本文。
- 两份流水线改为沿用当前Job已有 IMAGE_REPOSITORY 参数值，防止声明式参数刷新再次清空默认值；缺失、示例域名与格式拦截继续保留。专属提交 94595c810 已推送 test 分支，仅含两份Jenkinsfile与直接合同测试，不夹带工作区其他修改。
- 定向流水线合同20项通过，两份文件通过Jenkins declarative validate API语法检查；未触发构建、服务部署或SQL。配置原文备份及逐Job回读报告保存在本机私有环境目录 registry-default-20261021/；这次配置成功不代表排车业务代码已部署。
### 自有业务列表补列 TEST 发布（2026-10-21 16:36）
- 用户明确授权部署 TEST。以当时已部署 Admin `536308f3ec987a4bbe6e814a83f3b55f4a1bab71` 为基线，仅叠加已提交 `a4c7f8edd51f1e71ec4bcc1e75131c4a9c5fb726` 中自有业务列表、对应测试及模块核对矩阵三个文件，形成 `698531dc2694679738d5997d8acb9cce60399579`，标签 `test-owned-fields-20261021`。未切换工作分支或创建工作树，保留 TEST 其他已上线改动，未包含外配待确认的拆分统计字段。
- `admin-web-test #678` 精确检出目标，类型检查、生产构建及部署 SUCCESS，耗时59.379秒；容器 `admin-web-test:698531dc2694` healthy。临时 SCM pin 按配置哈希保护恢复，当前工作区其他未提交修改未参与发布。复用相关源码未变的8项定向测试结果，未因本次部署重跑全量测试。
- 实际容器首页引用 `OwnedBusinessView-RPRRkScS.js`；13项资源内容检查确认派送仓库、独立总价/单价、预约/实际到达、最晚装车完成时间的空值插槽及纯文字操作类均已发布，健康入口通过。业务字段语义沿自有业务主契约；静态资源核对不代替人工截图验收。
- 仅发布 Admin，无数据库、Nacos、Gateway 或后端变更。证据位于本机私有环境目录 `owned-fields-commit.json`、`owned-fields-release-state.json`、`owned-fields-admin.log`、`owned-fields-assets-report.json`。
海外仓业务/README.md
+20 -175
View File
@@ -1,184 +1,29 @@
# 海外仓业务范围与快速索引
## 已确认业务边界
# 海外仓业务文档入口
- 当前开发环境按端到端全流程交付，不再用开发批次切断上下游。订单与客户、入库测量与计费、国内货柜履约、海外仓业务和财务共同组成一条连续业务链。
- 海外仓业务从国内装柜完成及确认出仓后的船节点开始，覆盖海运在途、海外接柜、卸货入仓、库存与托盘、换标、转运、废弃、退货、排车、PDA 拣货与出库、发车、转派送、派送完成、异常退回、客户回访和一件代发。
- 海外采购、本土卡车、本土散板、海外仓报价、汇率和车辆主数据属于同一海外业务域，并统一经当前 `gateway/` 访问。
- 功能是否可用以正式路由、Controller/OpenAPI、权限、数据库结构和验收证据为准；历史规划只用于追溯，不再用于排除已经纳入全流程的能力。
本文件只帮助选择正文，不定义字段、状态或部署进度。已定位页面、API 或服务时跳过本文件；代码从目标应用/服务最近 `AGENTS.md` 进入，业务依据只读下表命中的主题或条款。
## 人工验收入口
## 当前业务正文
- 端到端人工验收统一使用[《虫虫出海全流程人工验收手册》](虫虫出海全流程人工验收手册.md)。手册覆盖客户与订单、国内履约、跨区事件、海外 PDA 入仓、库存与库内服务、排车出库、派送、异常退回、一件代发、海外主数据和海外业务，并区分页面、真机和自动化证据。
## 功能快速路由
- [排车列表统一作业改造契约](排车列表统一作业改造契约.md)：四阶段排车、一单一趟、跨客户同车、装车后自动派送及四块排车详情的当前改造入口。
- [排车流程修复规划](排车流程修复规划.md)：排车撤销、派送状态、换标全托、合托来源及草稿交互的修改范围、分工与回归要求。
- [采购订单样品履约流程变更需求](采购订单样品履约流程变更需求.md)：采购样品购买、装箱、面单、交寄、国内核费与寄客户的变更入口。
- [美国预约管理统一总览与优化方案](美国预约管理统一总览与优化方案.md)：提柜、用车、FBA及普通送货等统一展示的需求梳理与设计建议。
- [预约工作日历 V13 变更说明](预约工作日历V13变更说明.md)：已确认的多客户共车、分批后送、改期取消、重新预约、未定日期及下一步操作规则和验收场景。
- [预约工作日历开发协作契约](预约工作日历开发协作契约.md)：工作日历的接口、数据归属与唯一文件写者；不是已实现或环境验收说明。
### 预约送仓
本轮变更行为以[预约工作日历 V13 变更说明](预约工作日历V13变更说明.md)为主入口。下述接口用于定位既有业务归属；涉及整票占用、分批、取消及重约的实现须按 V13 收敛，不能由接口入口存在推定本轮规则已全部实现。
内部历史展示读取仓库元数据使用`POST /internal/warehouses/platform-metadata/batch`，由Warehouse权威提供，内部服务令牌鉴权且不经公网Gateway。每批1至2000个不重复正数ID，只读平台公共仓的编号、名称、类型、国家、原时区和状态，包含停用仓；不存在、非公共或已删除的ID统一列为缺失，不返回联系人及客户数据。调用方不得把原固定偏移或缺失时区猜成IANA地点时区；国家/时区不明时单列待定位，不放入美国当地日期格。接口合同见Warehouse `warehouse-v1.yaml`。
仓库主档时区使用IANA地点标识（如`America/New_York`），不以固定UTC偏移表示当地时间。国内默认`Asia/Shanghai`；明确单一时区的美国州可自动选择，多时区或存在地方例外的州须按实际地址确认。新增、编辑和导入在Warehouse共用校验。初始化地址资料无法确定地点时区时保留为空并阻止正式预约确认；不根据旧偏移批量猜测或迁移现有主档。参考[IANA时区数据说明](https://www.iana.org/time-zones)。
- 预约以同一美国起运仓和目的FBA仓组织，允许多个客户的真实货源统一安排。未建入仓计划也可保存；同仓不同日期/时段、不同货物可以分别建约。主单不归属单一客户，客户归属保留在每票货物明细，库存、订单、费用及派送的客户隔离不随合并改变。
- 预约管理日历和入仓单中的预约操作共用 Lastleg 的 FBA 预约记录。平台可读取完整预约；客户只能经自己的订单/入仓单读取本客户货物，不开放跨客户预约详情。
- FBA日历按地点当地时段与查询范围相交读取，跨日安排在覆盖的每一天展示同一业务记录；午夜结束不占次日，仅日期安排只占当天。确认时段与计划时段成对选用，不用旧计划结束时间补齐未知确认结束时间。卡片保留完整起止日期，切换已加载日期不追加查询。
- 系统生成全局唯一AP业务单号，外部确认号单独保存并按目的FBA仓唯一。创建和编辑携带持久化幂等键、操作者及请求摘要，同键同内容返回原命令快照，即使后来编辑也不改变原结果；异内容拒绝。主单、明细和命令记录同事务。本轮分批后的占用按 V13 逐来源数量及有效批次身份收敛，不能继续用整票唯一占用阻断合法部分分配；取消后恢复原单或重约仍须重新核对当前占用。
- 计划日期、可选计划时段、对方确认时段分别保存；仅有日期不补09点/零点，未定日期进入未定时列表。PENDING允许外部约号及箱数暂缺，不伪造值；SUCCESS必须有真实货量、FBA货件号或追踪号、外部确认号以及目的仓权威IANA时区，校验夏令时并保存对应UTC时间点。结束时间未知保持空。预计装车归运输安排，不再作为FBA预约写入字段；没有权威装车事实的关联查询明确返回未知。
- 入仓明细入口仅用lineIds选择业务货物，服务端批量转换成原ORDER/BOOKING整票来源；外接来货后仍保持BOOKING键，禁止同时以ORDER别名建约。主表和明细只有一套，不并行维护“提前预约”副本。仓储转运的目的地和货件资料读取实际转运主记录，不能把未填充的尾程展示投影误报为目的地变化。
- 取消/未约成须记录原因，解除失效预约的有效覆盖/绑定，并保留原计划、确认事实和历史；仍需送货的批次数量与后续需求按 V13 第六至七节保留，不回退库存或使同一货量再次可选。已有有效排车时先核对并处理运输安排。编辑使用版本校验，已确认预约不能直接退回待确认。
- 用车计划来源读取Fleet日期范围接口，一车一条，保留计划/实际出发及司机任务预计结束的UTC时间点，不表示收货预约已确认。前端最多显示42个起运仓当地日期，通过前后各14小时的UTC检索余量覆盖跨日，已发车按实际出发时间、未发车按计划出发时间检索并逐条按权威地点时区落格，原计划保留供核对，改期不移动已执行事实；缺仓库、国家或时区时独立展示待定位记录，不用浏览器时区猜测。服务端UTC保护窗口最多44天，超过2000条明确拒绝并要求缩小范围，不逐页扫描或静默截断。读取仍需车次列表权限，正常一个车次SQL和一次内部仓库元数据批量调用；目录失败不可当作空结果。
- 提柜日历读取Firstleg原码头拖车记录，入口为`GET /api/platform/v1/terminal-drayages/calendar`，同时要求预约列表与码头拖车列表权限。按启用目的仓国家筛选美国业务范围，不推断港口国家；已提柜按船节点权威实际日期、未提柜按预约日期检索和展示，原预约时间独立保留，改期不移动已执行事实；原业务日期无时区事实时显示待核实，不套用收货仓时区或转为UTC。日期范围最多42天，预约来源和船节点实际来源分别有界读取并按柜去重；任一来源超出1000条或目的仓无法分类时标记统计不完整，目录失败报错，不能假装无预约。详情回到原清关提柜业务，不由日历直接写原状态。
- Admin 入口为 `../../apps/admin-web/src/modules/appointment-calendar/`，既有入仓单入口为 `modules/overseas-warehouse/`。日历读取权限为 `platform:appointment:list`，既有预约写权限独立；API 合同见 `../../baiyue-firstleg/lastleg-service/src/main/resources/openapi/fba-appointment-calendar-v1.yaml`。合并预约不表示已经排车或发车，运输执行继续按既有排车与共享车次流程处理。
#### 在途货源与拼车外接货的预约跟进合同
本节规定来源解析、人工跟进和已有预约覆盖的共同边界。美国全类型预约的总体目标见[优化方案](美国预约管理统一总览与优化方案.md)；本节接口不代表总体目标、环境发布或整链验收已经完成。
| 事实 | 唯一来源与规则 |
| 任务 | 读取入口 |
|---|---|
| 头程已开船货 | `ORDER:<尾程订单ID>`；依据真实船节点和美国接仓点/FBA目录读取，不要求先建入仓计划。建计划后仍是同一来源，不重复计票。内部ID仅用于关联，不作为业务编号展示。 |
| 拼车外接货 | `BOOKING:<原登记号>`；Fleet提供客户、目的地、接仓点、承运阶段、版本及可空的实际订单关联。确认承运后尚未来货可记录联系；生成订单后保持BOOKING键，禁止同时以ORDER别名重复计货。未知箱数保持空值。 |
| 时间 | 在途列表的预计到港/到仓是订单保存的快照；船节点观察时间不代表实时ETA。预约已确认时间只读，不被预计时间更新覆盖。原预约缺少时区时明确待核实，不按操作者浏览器时区猜测。 |
| 人工跟进 | `ll_appointment_followup`保留追加历史，跟进人取登录主体；允许没有入仓计划、约号、车辆时保存。提柜联系与码头申请按稳定柜次共享，接仓联系按柜次及实际接仓点共享，FBA联系按ORDER/BOOKING货源及客户保存；各事项独立，不推进正式确认或作业状态。 |
| 预约覆盖 | `AppointmentCoverageService.query`按稳定来源及客户批量读取FBA预约，数量核对未覆盖、部分覆盖、待确认、已确认和待复核。外接货尚无订单但已保存安排时返回待确认及资料缺项，不返回假确认。正式确认号、地点时区和已核实来源版本分别读取；来源版本变化仅提示复核，不声称已完成精确船期影响分析。仓储转运的目的地与货件资料以转运主记录为准，缺少资料与实际目的地变化分开表达。 |
| 运输和容量 | 车次、正式排车关联、容量、余位及发布由Fleet维护。预约侧读取其真实结果，不以联系记录生成库存、托盘、车次或容量，也不在前端扣减余位。 |
| 尾程订单、入仓计划、接柜、库存与仓储资源 | [系统边界](业务规则.md#系统边界与索引维护)，按订单/计划/托盘等符号只读命中条款 |
| 海外排车、出库与派送改造 | [排车现行契约](排车列表统一作业改造契约.md)；已有缺陷追溯才读[修复规划](排车流程修复规划.md) |
| 外配车辆与承运 | [外配业务契约](外配业务首版开发契约.md) |
| 预约工作日历、多客户共车、分批、改期取消 | [V13 业务规则](预约工作日历V13变更说明.md)；接口/文件归属问题才读[开发协作契约](预约工作日历开发协作契约.md) |
| 船节点、查询频率、还柜与码头邮件 | [船节点契约](船节点标准化契约.md)；实现补充查[定时查询](业务规则.md#船节点定时查询边界)或[码头邮件](业务规则.md#码头车队邮件) |
| 本土卡车与散板表单 | [统一表单](业务规则.md#本土卡车与散板统一前端下单)、[散板](业务规则.md#本土散板简化下单)、[美国本土卡](业务规则.md#美国本土卡独立下单)，按任务选一项 |
| 采购样品、面单与寄送 | [采购样品流程](采购订单样品履约流程变更需求.md) |
| 司机、证照、车队与拼车需求池 | [车辆业务范围](车辆管理原型梳理与任务规划.md)、[拼车业务契约](内部拼车需求池首版开发契约.md)，按具体业务选读 |
| 自有业务 | [自有业务契约](自有业务首版开发契约.md)；接口细节查[接口设计](自有业务后端接口设计.md) |
HTTP入口为`/api/platform/v1/last-leg/appointment-planning`，包括`GET /cargo`、`GET /sources/resolve`及`GET/POST /sources/{sourceKey}/follow-ups`；请求和响应定义见[预约筹划OpenAPI](../../baiyue-firstleg/lastleg-service/src/main/resources/openapi/appointment-planning-v1.yaml)。深链进入预约页时须由后端重新核对客户、来源与目的仓，不能信任URL赋予资格。读取同时要求`platform:appointment:list`与`platform:overseas-warehouse:last-mile-order:list`，追加跟进另需`platform:appointment:followup`；仅平台主体可用，客户端不暴露跨客户货源。
专题契约描述确认目标，不表示代码、部署或真实验收已完成。只改唯一规则正文；入口或职责变化才同步本表。
整柜入口为`GET /containers`、`GET /containers/{containerId}`与`GET/POST /containers/{containerId}/follow-ups`，沿用上述权限。未传`warehouseId`记录整柜提柜或码头联系，传入时仅记录该柜实际接仓点的接仓联系。共享来源键由服务端生成`CONTAINER:<柜次>`或`CONTAINER:<柜次>:WAREHOUSE:<仓库>`，技术平台作用域不接收客户端客户参数，也不在界面展示内部键。原货源写入口仅接受FBA联系，不能逐客户重复登记整柜事项。
## 预约送仓
整柜列表读取实际已开船且仍有效的头程货物，覆盖美国接仓点的各种目的地类型；不要求先建入仓计划。关键词命中某票后仍统计同柜全部美国范围货物，接仓点一次批量分组加载。任一票箱数未知则汇总箱数显示待核实；同柜另有未知或非美国接仓点时明确标记范围不完整并禁止新联系记录。来源预计到港仍是订单快照，不能当作实时船期或预约确认。已有联系历史在来源离开活动列表后保留可读。
送仓预约的基础边界见[预约送仓正文](业务规则.md#预约送仓)；日历相关变更优先按上表定位 V13，不默认再读取总体优化方案和开发协作契约。
跟进写入携带事项版本和持久化幂等键。同键、同操作者、同内容重试返回原记录；异内容或不同版本冲突拒绝，未知结果重试保持原请求。跟进保存成功不代表预约申请或确认成功。仓库目录失败必须报错；日历某来源失败时保留其他来源结果并标注统计不完整。
## 原型与验收（按需）
跨客户合批核对入口为`POST /batches/preview`，读取权限与来源查询相同，单批最多100票。服务端批量核对ORDER/BOOKING来源、客户归属及真实订单，拒绝重复别名、不同起运仓/目的FBA仓、暂扣、多目的地及已有有效预约；未知箱数保留缺项。`POST /appointments`重新核对后保存同一FBA预约聚合，另需既有FBA预约写权限；`GET /appointments/unscheduled`按预约列表权限分页读取无日期安排。允许未建计划及已确认承运但尚未来货的真实来源，不能信任浏览器预览作为写入依据。两种创建入口均自动提交选择时的接仓点和目的FBA仓，服务端在锁定货源后与当前事实比对；任一变化返回冲突并要求重新核对，不静默改约至新仓，也不增加人工填写字段。备妥窗口无权威依据时明确待核实，不能用预计到港或到仓替代。部署与真实验收状态见环境主契约。
已确认承运的外接货从原登记深链或`GET /external-candidates`服务端分页列表进入，必须经服务端核对后才能加入既有预约合批工作区；使用同一预览/创建接口，与同起运仓、同目的FBA仓的头程货共同保存，保留原BOOKING键，不生成ORDER别名。来源已有有效预约时不再提供新增入口；未形成入仓码或箱数未知仍可保存待确认安排，正式确认继续核验资料。
外接候选由Fleet只读适配器按原登记分页发现，限已确认承运/已实收/已绑定、车次未取消或完成、权威启用美国接仓点和FBA目的仓范围；支持登记号、车次号、客户名称及来货号检索，每页最多100票。预约侧对当页来源和覆盖批量核实，保留客户归属、原登记、真实订单关联及未知箱数；目录失败显式报错。Admin仅打开外接货源列表时请求，切换头程/外接保留同一合批选择，保存后刷新覆盖。它不提供承运确认、车次容量或发布写入。
共同样例：两柜头程货送同一美国接仓点再送ONT8，提柜分别按两柜联系，FBA货源保留各票ORDER来源；同一车次接入外部登记B-1时保留BOOKING:B-1。B-1确认承运但尚未来货时可以跟进和保存安排，不伪造入仓码或对方确认；实际来货在原登记行锁和同一事务内，将已有有效预约明细关联到真实订单及入仓码，继续通过同一BOOKING键读取覆盖；关联失败则来货事务一起回滚。该关联不自动改写预约数量快照、确认时间或来源版本，也不扫描补填历史记录。预约保存按登记号和订单号的稳定顺序锁定货源，并在订单锁定后清除查询缓存、重新核对来源，防止使用锁定前的旧事实。客户不符、目的仓变化、重复别名或已取消承运均不能借用其他货物的预约结果。跨来源筹划、正式确认和变化处理遵循总体方案，读取或核对成功不能代替保存和正式确认成功。
| 业务域 | 能力范围 | 原型入口 |
|---|---|---|
| 海外仓 | 尾程订单、入库单、换标单、托盘管理、库存管理；箱号管理与产品库当前暂不进入海外仓业务正式入口；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/` |
| 海外仓排车与智能预排 | 平台查看排车列表/详情，按入仓计划或已收托盘创建预排，并完成编辑、取消、拣货、出库、发车和转派送 | 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/` |
| 海外仓 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/` |
| 海外仓 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` |
| 车辆管理、司机资质与保养加油 | 业务范围见[车辆管理原型梳理与任务规划](车辆管理原型梳理与任务规划.md)；后端 `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/fleet/`，OpenAPI `fleet-drivers-v1.yaml`、`fleet-trips-v1.yaml`、`fleet-vehicle-records-v1.yaml`；证照和运维照片复用 File | Admin 接入目录 `../../apps/admin-web/src/modules/overseas-master-data/`；原型来源和页面 ID 按规划第 1、2 节定位 |
| 自有业务运营视图 | [自有业务首版开发契约](自有业务首版开发契约.md)、[后端接口设计](自有业务后端接口设计.md) | Admin海外通用资料模块；Lastleg `fleet/ownedbusiness/`，原排车为主事实，File分类契约 `fleet-owned-business-photos-v1.yaml` |
| 外配业务运营视图 | [外配业务首版开发契约](外配业务首版开发契约.md) | Admin海外通用资料模块；Lastleg `fleet/outsourcedbusiness/`，复用原排车事实和附加运营记录 |
| 内部拼车需求池 | [内部拼车需求池首版开发契约](内部拼车需求池首版开发契约.md)：车次余位发布、销售意向、确认占位、本土订单关联及统一我仓上车 | 复用上述车辆管理及本土业务入口；不开放客户端运力市场 |
| 国内出仓后船节点 | 对已确认离开国内仓库的订舱/柜次定时查询船节点，保存最新节点、异常和查询历史，贯通目的港提柜至还柜事实 | 标准语义见[船节点标准化契约](船节点标准化契约.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`。
## 终端与模块边界
- 海外仓出库、派送、异常退回和一件代发已经纳入全流程，不再作为海外入仓之后的独立开发批次。
- 派送业务由 Admin/Client 承载，不进入海外 PDA；海外 PDA 负责现场入仓、托盘、排车拣货和出库等已注册作业。
- 箱号和产品信息作为入仓、库存、箱唛及 SKU 快照的一部分使用；是否提供独立维护页面由正式路由决定，不影响全流程状态推进。
- 高级 BI、开放平台和独立移动 APP 属于独立产品能力，不与现有业务全流程完成状态混为一谈。
## 船节点定时查询边界
- 所有供应商统一节点、时间语义、异常事实、停止规则和新增船司接入门禁以[船节点标准化契约](船节点标准化契约.md)为准；供应商缺失的节点保持缺失，不推测补齐。
- 现有 `CarrierScheduleQuery` 查询任务及其查询尝试、历史、来源、过期标识和频率约束整体重新归入海外仓业务；不再把它列作国内货柜履约港务/船期查询能力，也不得另建一套重复任务。
- 定时查询对象必须关联真实订舱、柜次以及可用的船司/船名航次或跟踪标识，不建立脱离业务单据的孤立轮询任务。
- Firstleg `portschedule/` 负责任务编排、业务关联、最新节点、节点历史、幂等和停止条件；`integration-service/` 只负责船司或轨迹供应商适配、限流、超时、重试和错误归一化，不保存业务主数据。
- 查询从确认柜子离开国内仓库后开始，贯通目的港到达、卸船、清关、提柜和还柜事实，默认在实际 `EMPTY_RETURNED` 后停止；这只扩展货柜轨迹事实，不纳入海外派送、海外仓出库或库存离仓业务。失败不能伪造成功节点，需保留来源、观测时间、最近成功时间和失败原因。
- 现有“每 3 天一次、窗口最多 3 次”、六家船公司来源、最近有效结果和过期标识是同一查询能力的既有约束，归海外仓业务继续核对；后续若调整自动轮询频率、供应商额度、退避或停止规则，应只修改海外仓业务契约和这套任务。
- 当前原型没有独立的“船节点定时查询”页面；涉及页面展示时从订舱、船期或货柜详情进入，不得为了匹配原型菜单把它归入海外派送。
## 本土卡车与散板统一前端下单
- 同一业务在 Admin 新增/编辑和 Client 下单使用一致的字段、顺序、控件、默认值、校验及提交转换；Admin 新增额外选择客户，编辑固定原订单客户；Client 的客户仅由登录会话确定，业务请求体不携带客户标识。
- 业务表单统一为运输信息、货物信息、费用与时效和备注。起运地/目的地、两端联系人、电话及详细地址左右对应；件数、预计托数、重量和体积默认零，预算默认为空、币种 USD，空预算和零预算分别保留。车辆只在卡车填写，商品与预计托数只在散板填写。
- 两端统一使用数字控件和 USD/CNY 选择；重量支持三位小数、体积六位小数、预算两位小数；取送时间按当地分钟输入并提交秒为零的值，不进行时区转换。四项联系信息及两个时间均必填，送货不能早于取货。
- 各应用内部由 `TransportDemandForm.vue` 和 `transportDemandForm.ts` 复用表单、校验与业务请求转换；两端对应源码按同一内容核对，不建立跨应用目录依赖。创建保留稳定幂等键；平台编辑保留客户、业务单号和版本，受状态及只读承运来源限制。
## 本土散板简化下单
- 平台代客创建必须显式选择客户；客户端客户范围只取认证会话。新增、编辑保持现有独立页面；平台普通编辑仍只允许待接单且非拼车来源订单，池来源继续只读展示真实承运安排。
- 下单移除运输方式及柜型字段，不再要求选择自送或我司提货。拼车或优先拼载属于内部安排，不再冒充交货方式或作为下单必填项；运输类型和是否打盘不在新增主表单要求填写，未知安排保持空，不自动补造。散板移除柜型字段。
- 需求保存取货地、目的地、可选详细地址补充、起运地联系人及联系电话、目的地联系人及联系电话、商品名称、预计托数、件数、总重量、总体积、预算总价、币种、取货与送达时间和备注。商品名称、预算和备注选填；四项联系人信息与取货、送货时间全部必填；预计托数、件数及重量体积可为零，不能为负。件数、地址补充和备注按统一前端下单表单展开填写。
- `estimatedPalletCount` 是下单预计托数；`packageCount` 是件数，二者独立。下单不生成实物托盘，不把预计托数写成实际收货或实占托位；拼车来源沿真实询价的货名与预计托数保存。
- `pickupAt` 与 `deliveryAt` 保存不带时区的当地日期时间，按分钟输入、原值显示，不进行 UTC 转换。取货与送货时间均必填；送货时间不能早于取货时间。预算明确显示 USD 或 CNY，金额空值与零值区分。
- 平台和客户接口共用 Lastleg `looseboard/dto/LocalLooseboardRequests.java`、`LocalLooseboardResponses.java` 及 `overseas-business-v1.yaml`，不保留旧运输枚举或要求日期别名。现有 API 路径与权限复用，空库结构同步模块基线及海外统一初始化，不回填测试存量，不自动执行 SQL 或部署。
## 美国本土卡独立下单
- 客户端和平台新增/编辑共用同一服务端需求合同：移除运输类型、柜型、下单预报托盘数及原要求时间；车辆类型为必选的“15拖”（`PALLET_15`）或“30拖”（`PALLET_30`）。车辆主档仍独立维护实际容量，车型不等于本票货量。
- 起运地联系人、起运地联系电话、目的地联系人、目的地联系电话、取货时间和送货时间全部必填。时间按日期及小时分钟填写，不进行时区转换；送货不能早于取货。列表、详情与平台编辑展示同一份保存值，客户端不提交客户标识。
- 独立下单不生成预报托盘，首次实际收货确定确认托数；已有拼车来源的真实预报及实际履约继续独立记录。拼车来源未提供的车型、目的地联系人/电话、送货时间保持未知，页面显示“—”，不捏造数据。美本土散板按本文“本土散板简化下单”使用独立需求合同。
- 接口及字段唯一实现合同为 Lastleg `trucking/dto/UsTruckOrderRequests.java`、`UsTruckOrderResponses.java` 与 `src/main/resources/openapi/overseas-business-v1.yaml`；数据结构同步模块基线及海外统一空库初始化。页面承载核对见 Client `cross-border/PROTOTYPE_MATRIX.md` 和 Admin `overseas-business/PROTOTYPE_MATRIX.md`。
## 系统边界与索引维护
- 托盘管理提供当前托盘单张标签 PDF：Admin `PalletsView.vue` → `warehouse-overseas-service` 的 `GET /api/platform/v1/warehouse-admin/{warehouseId}/pallets/{id}/label`。有 FBA 仓码的托盘与国内统一使用 Print `FBA_PALLET_A4_LANDSCAPE_V1`（297×210 mm）：顶部 SCK8 等仓码，中间 Code 128、底部完整托盘号，141 等内部编号保留在托盘号中；其他托盘使用 `INBOUND_MARK_V1`（100×100 mm）。只按真实托盘编码打印，不重新生成编号；模板约束、服务接入与权限见海外资源服务 `AGENTS.md`。
- 海外仓合作仓是现有头程仓库主数据的类型扩展，需同步核对 Admin `warehouses`、Warehouse Service 的 DTO/Controller/OpenAPI/SQL 及实际消费者；不得因此把海外库存业务写入国内 Warehouse Service。
- 海外库存、库内作业和海外本土业务已有明确服务入口：`gateway/` 是统一 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 冒充入仓码。
- 平台可按单票尾程订单入库计划（托数、托盘类型、分配/可合托/加急和备注）；入库仓、入仓码和预计到仓时间均展示冻结事实，不允许人工改写。预计到仓日期由服务端锁定来源柜全部订单的 `estimated_warehouse_at`，缺失或同柜不一致时阻断，人工与自动计划统一写入该柜日期。写入时校验订单版本、客户归属、仓库主档和幂等键；一票柜保存后立即自动生成并绑定托盘码、海外仓托盘和资源锁，多票柜在最后一票计划齐全时自动为全柜完成同一动作。`resourcePendingPlanCount` 只用于自动生成失败后的显式重试，不是正常人工步骤。分配、可合托、加急必须随入库单列表和海外 PDA 入仓码作业返回并展示，其中“可合托”只向现场提供选择：合托时扫描同目的仓已使用的托盘码，独立收货时扫描新托盘码，不作为实收或完成门禁。新增暂扣只允许货物完成入库后执行；暂扣只作用于该票并仅阻断排车和出库，不阻断入库计划或入库作业，同柜其他订单不受影响。
- 头程散货在预装确认且真实集装箱号就绪后，按 `集装箱号-FBA仓编码-三位序号` 冻结托盘码；序号在当前柜、当前 FBA 仓内从 001 独立递增。送柜报关、清关提柜和预装清单共用同一按 FBA 仓分组的打印清单，可整柜打印或选择单仓前 N 张补打。该编号随装柜完成事件进入海外，生成入库计划与海外实体托盘时原样沿用；一件代发继续使用国内装箱打托形成的托盘号，不参与散货重新编号。
- 头程与海外仓允许装托密度不同。尾程最终托数取不低于头程已有托盘码数的海外计划结果：头程已有编码全部保留，数量不足时在同柜、同 FBA 内按连续下标补码，不因数量差异阻断。柜级预览必须分别返回并展示头程已有、海外仓补充和最终托数；最终总数不得标成“本次新增”。
- 尾程订单人工节点固定为国内报关完成、预计/实际开船、预计到港、国外清关完成、实际到港等待卸船、预约提柜和卸柜八行完整快照。第一次保存后该订单永久使用 `MANUAL` 来源，读取和页面展示不得再回退柜级节点，也不得反向修改货柜船节点。
- 目的港码头拖车仍归 Firstleg 货柜聚合，但 Admin 清关提柜列表不再使用预约/实际提柜作为到仓业务时间：原两列改为“预计到仓/实际到仓”。未人工维护且未建入库计划时，预计到仓按[预约日历统一日期规则](预约工作日历V13变更说明.md#2026-10-19-当前预约列表收敛规则)展示到港日期加两个自然日的默认值，列表与详情一致且不自动写入。人工调整在列表内选择日期时间并由 Lastleg 按 `sourceContainerBookingId` 原子同步整柜尾程订单，已有入库计划后锁定；实际到仓只取海外 PDA 首次开始收货的 `ll_receiving_container_session.receiving_at`。车队、邮件、还柜及 `unloadingCompletedAt + 72h` 还空预警仍按原码头拖车链路处理。
- 手动还柜以真实海外卸柜完成且尚未还柜为准，仍校验独立还柜权限；无需事先存在车队、预约或提柜时间。首次命令使用版本 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 车队邮件说明](../../baiyue-firstleg/firstleg/docs/terminal-drayage-mail.md)。
- 页面还原按[页面 ID 索引](业务规则.md#原型页面定向索引)读取命中页面；不加载全部原型。
- 用户明确要求全流程人工验收时查[人工验收手册](虫虫出海全流程人工验收手册.md)；普通修改按根指引选择最小验证。
- [美国预约总体优化方案](美国预约管理统一总览与优化方案.md)、[PDA 改造评审](海外仓PDA拆柜收货改造方案评审稿.md)、后端缺口清单和原型核对属于专项设计/评审资料，不是普通开发的必读清单。
海外仓业务/业务规则.md
+173
View File
@@ -0,0 +1,173 @@
# 海外仓业务规则与实现边界
角色：业务规则正文，不是导航或部署进度。已知代码入口时直接沿模块指引工作；需要业务依据时，按索引链接或 `rg -n -F '符号或主题' docs/海外仓业务/业务规则.md` 读取命中标题/条款，不全文加载。
专题正式契约优先：排车查《排车列表统一作业改造契约》，预约查《预约工作日历V13变更说明》，船节点查《船节点标准化契约》，纸张与标签查打印标签维护入口；下列实现约束不得覆盖这些当前主题规则。部署与验收状态只查工作区根指引指定的环境主契约。
## 业务范围
- 当前开发环境按端到端全流程交付，不再用开发批次切断上下游。订单与客户、入库测量与计费、国内货柜履约、海外仓业务和财务共同组成一条连续业务链。
- 海外仓业务从国内装柜完成及确认出仓后的船节点开始，覆盖海运在途、海外接柜、卸货入仓、库存与托盘、换标、转运、废弃、退货、排车、PDA 拣货与出库、发车、转派送、派送完成、异常退回、客户回访和一件代发。
- 海外采购、本土卡车、本土散板、海外仓报价、汇率和车辆主数据属于同一海外业务域，并统一经当前 `gateway/` 访问。
- 功能是否可用以正式路由、Controller/OpenAPI、权限、数据库结构和验收证据为准；历史规划只用于追溯，不再用于排除已经纳入全流程的能力。
## 预约送仓
本轮变更行为以[预约工作日历 V13 变更说明](预约工作日历V13变更说明.md)为主入口。下述接口用于定位既有业务归属；涉及整票占用、分批、取消及重约的实现须按 V13 收敛，不能由接口入口存在推定本轮规则已全部实现。
内部历史展示读取仓库元数据使用`POST /internal/warehouses/platform-metadata/batch`，由Warehouse权威提供，内部服务令牌鉴权且不经公网Gateway。每批1至2000个不重复正数ID，只读平台公共仓的编号、名称、类型、国家、原时区和状态，包含停用仓；不存在、非公共或已删除的ID统一列为缺失，不返回联系人及客户数据。调用方不得把原固定偏移或缺失时区猜成IANA地点时区；国家/时区不明时单列待定位，不放入美国当地日期格。接口合同见Warehouse `warehouse-v1.yaml`。
仓库主档时区使用IANA地点标识（如`America/New_York`），不以固定UTC偏移表示当地时间。国内默认`Asia/Shanghai`；明确单一时区的美国州可自动选择，多时区或存在地方例外的州须按实际地址确认。新增、编辑和导入在Warehouse共用校验。初始化地址资料无法确定地点时区时保留为空并阻止正式预约确认；不根据旧偏移批量猜测或迁移现有主档。参考[IANA时区数据说明](https://www.iana.org/time-zones)。
- 预约以同一美国起运仓和目的FBA仓组织，允许多个客户的真实货源统一安排。未建入仓计划也可保存；同仓不同日期/时段、不同货物可以分别建约。主单不归属单一客户，客户归属保留在每票货物明细，库存、订单、费用及派送的客户隔离不随合并改变。
- 预约管理日历和入仓单中的预约操作共用 Lastleg 的 FBA 预约记录。平台可读取完整预约；客户只能经自己的订单/入仓单读取本客户货物，不开放跨客户预约详情。
- FBA日历按地点当地时段与查询范围相交读取，跨日安排在覆盖的每一天展示同一业务记录；午夜结束不占次日，仅日期安排只占当天。确认时段与计划时段成对选用，不用旧计划结束时间补齐未知确认结束时间。卡片保留完整起止日期，切换已加载日期不追加查询。
- 系统生成全局唯一AP业务单号，外部确认号单独保存并按目的FBA仓唯一。创建和编辑携带持久化幂等键、操作者及请求摘要，同键同内容返回原命令快照，即使后来编辑也不改变原结果；异内容拒绝。主单、明细和命令记录同事务。本轮分批后的占用按 V13 逐来源数量及有效批次身份收敛，不能继续用整票唯一占用阻断合法部分分配；取消后恢复原单或重约仍须重新核对当前占用。
- 计划日期、可选计划时段、对方确认时段分别保存；仅有日期不补09点/零点，未定日期进入未定时列表。PENDING允许外部约号及箱数暂缺，不伪造值；SUCCESS必须有真实货量、FBA货件号或追踪号、外部确认号以及目的仓权威IANA时区，校验夏令时并保存对应UTC时间点。结束时间未知保持空。预计装车归运输安排，不再作为FBA预约写入字段；没有权威装车事实的关联查询明确返回未知。
- 入仓明细入口仅用lineIds选择业务货物，服务端批量转换成原ORDER/BOOKING整票来源；外接来货后仍保持BOOKING键，禁止同时以ORDER别名建约。主表和明细只有一套，不并行维护“提前预约”副本。仓储转运的目的地和货件资料读取实际转运主记录，不能把未填充的尾程展示投影误报为目的地变化。
- 取消/未约成须记录原因，解除失效预约的有效覆盖/绑定，并保留原计划、确认事实和历史；仍需送货的批次数量与后续需求按 V13 第六至七节保留，不回退库存或使同一货量再次可选。已有有效排车时先核对并处理运输安排。编辑使用版本校验，已确认预约不能直接退回待确认。
- 用车计划来源读取Fleet日期范围接口，一车一条，保留计划/实际出发及司机任务预计结束的UTC时间点，不表示收货预约已确认。前端最多显示42个起运仓当地日期，通过前后各14小时的UTC检索余量覆盖跨日，已发车按实际出发时间、未发车按计划出发时间检索并逐条按权威地点时区落格，原计划保留供核对，改期不移动已执行事实；缺仓库、国家或时区时独立展示待定位记录，不用浏览器时区猜测。服务端UTC保护窗口最多44天，超过2000条明确拒绝并要求缩小范围，不逐页扫描或静默截断。读取仍需车次列表权限，正常一个车次SQL和一次内部仓库元数据批量调用；目录失败不可当作空结果。
- 提柜日历读取Firstleg原码头拖车记录，入口为`GET /api/platform/v1/terminal-drayages/calendar`，同时要求预约列表与码头拖车列表权限。按启用目的仓国家筛选美国业务范围，不推断港口国家；已提柜按船节点权威实际日期、未提柜按预约日期检索和展示，原预约时间独立保留，改期不移动已执行事实；原业务日期无时区事实时显示待核实，不套用收货仓时区或转为UTC。日期范围最多42天，预约来源和船节点实际来源分别有界读取并按柜去重；任一来源超出1000条或目的仓无法分类时标记统计不完整，目录失败报错，不能假装无预约。详情回到原清关提柜业务，不由日历直接写原状态。
- Admin 入口为 `../../apps/admin-web/src/modules/appointment-calendar/`，既有入仓单入口为 `modules/overseas-warehouse/`。日历读取权限为 `platform:appointment:list`，既有预约写权限独立；API 合同见 `../../baiyue-firstleg/lastleg-service/src/main/resources/openapi/fba-appointment-calendar-v1.yaml`。合并预约不表示已经排车或发车，运输执行继续按既有排车与共享车次流程处理。
#### 在途货源与拼车外接货的预约跟进合同
本节规定来源解析、人工跟进和已有预约覆盖的共同边界。美国全类型预约的总体目标见[优化方案](美国预约管理统一总览与优化方案.md)；本节接口不代表总体目标、环境发布或整链验收已经完成。
| 事实 | 唯一来源与规则 |
|---|---|
| 头程已开船货 | `ORDER:<尾程订单ID>`；依据真实船节点和美国接仓点/FBA目录读取，不要求先建入仓计划。建计划后仍是同一来源，不重复计票。内部ID仅用于关联，不作为业务编号展示。 |
| 拼车外接货 | `BOOKING:<原登记号>`；Fleet提供客户、目的地、接仓点、承运阶段、版本及可空的实际订单关联。确认承运后尚未来货可记录联系；生成订单后保持BOOKING键，禁止同时以ORDER别名重复计货。未知箱数保持空值。 |
| 时间 | 在途列表的预计到港/到仓是订单保存的快照；船节点观察时间不代表实时ETA。预约已确认时间只读，不被预计时间更新覆盖。原预约缺少时区时明确待核实，不按操作者浏览器时区猜测。 |
| 人工跟进 | `ll_appointment_followup`保留追加历史，跟进人取登录主体；允许没有入仓计划、约号、车辆时保存。提柜联系与码头申请按稳定柜次共享，接仓联系按柜次及实际接仓点共享，FBA联系按ORDER/BOOKING货源及客户保存；各事项独立，不推进正式确认或作业状态。 |
| 预约覆盖 | `AppointmentCoverageService.query`按稳定来源及客户批量读取FBA预约，数量核对未覆盖、部分覆盖、待确认、已确认和待复核。外接货尚无订单但已保存安排时返回待确认及资料缺项，不返回假确认。正式确认号、地点时区和已核实来源版本分别读取；来源版本变化仅提示复核，不声称已完成精确船期影响分析。仓储转运的目的地与货件资料以转运主记录为准，缺少资料与实际目的地变化分开表达。 |
| 运输和容量 | 车次、正式排车关联、容量、余位及发布由Fleet维护。预约侧读取其真实结果，不以联系记录生成库存、托盘、车次或容量，也不在前端扣减余位。 |
HTTP入口为`/api/platform/v1/last-leg/appointment-planning`，包括`GET /cargo`、`GET /sources/resolve`及`GET/POST /sources/{sourceKey}/follow-ups`；请求和响应定义见[预约筹划OpenAPI](../../baiyue-firstleg/lastleg-service/src/main/resources/openapi/appointment-planning-v1.yaml)。深链进入预约页时须由后端重新核对客户、来源与目的仓，不能信任URL赋予资格。读取同时要求`platform:appointment:list`与`platform:overseas-warehouse:last-mile-order:list`，追加跟进另需`platform:appointment:followup`；仅平台主体可用，客户端不暴露跨客户货源。
整柜入口为`GET /containers`、`GET /containers/{containerId}`与`GET/POST /containers/{containerId}/follow-ups`，沿用上述权限。未传`warehouseId`记录整柜提柜或码头联系，传入时仅记录该柜实际接仓点的接仓联系。共享来源键由服务端生成`CONTAINER:<柜次>`或`CONTAINER:<柜次>:WAREHOUSE:<仓库>`，技术平台作用域不接收客户端客户参数，也不在界面展示内部键。原货源写入口仅接受FBA联系，不能逐客户重复登记整柜事项。
整柜列表读取实际已开船且仍有效的头程货物，覆盖美国接仓点的各种目的地类型；不要求先建入仓计划。关键词命中某票后仍统计同柜全部美国范围货物，接仓点一次批量分组加载。任一票箱数未知则汇总箱数显示待核实；同柜另有未知或非美国接仓点时明确标记范围不完整并禁止新联系记录。来源预计到港仍是订单快照，不能当作实时船期或预约确认。已有联系历史在来源离开活动列表后保留可读。
跟进写入携带事项版本和持久化幂等键。同键、同操作者、同内容重试返回原记录；异内容或不同版本冲突拒绝，未知结果重试保持原请求。跟进保存成功不代表预约申请或确认成功。仓库目录失败必须报错；日历某来源失败时保留其他来源结果并标注统计不完整。
跨客户合批核对入口为`POST /batches/preview`，读取权限与来源查询相同，单批最多100票。服务端批量核对ORDER/BOOKING来源、客户归属及真实订单，拒绝重复别名、不同起运仓/目的FBA仓、暂扣、多目的地及已有有效预约；未知箱数保留缺项。`POST /appointments`重新核对后保存同一FBA预约聚合，另需既有FBA预约写权限；`GET /appointments/unscheduled`按预约列表权限分页读取无日期安排。允许未建计划及已确认承运但尚未来货的真实来源，不能信任浏览器预览作为写入依据。两种创建入口均自动提交选择时的接仓点和目的FBA仓，服务端在锁定货源后与当前事实比对；任一变化返回冲突并要求重新核对，不静默改约至新仓，也不增加人工填写字段。备妥窗口无权威依据时明确待核实，不能用预计到港或到仓替代。部署与真实验收状态见环境主契约。
已确认承运的外接货从原登记深链或`GET /external-candidates`服务端分页列表进入，必须经服务端核对后才能加入既有预约合批工作区；使用同一预览/创建接口，与同起运仓、同目的FBA仓的头程货共同保存，保留原BOOKING键，不生成ORDER别名。来源已有有效预约时不再提供新增入口；未形成入仓码或箱数未知仍可保存待确认安排，正式确认继续核验资料。
外接候选由Fleet只读适配器按原登记分页发现，限已确认承运/已实收/已绑定、车次未取消或完成、权威启用美国接仓点和FBA目的仓范围；支持登记号、车次号、客户名称及来货号检索，每页最多100票。预约侧对当页来源和覆盖批量核实，保留客户归属、原登记、真实订单关联及未知箱数；目录失败显式报错。Admin仅打开外接货源列表时请求，切换头程/外接保留同一合批选择，保存后刷新覆盖。它不提供承运确认、车次容量或发布写入。
共同样例：两柜头程货送同一美国接仓点再送ONT8，提柜分别按两柜联系，FBA货源保留各票ORDER来源；同一车次接入外部登记B-1时保留BOOKING:B-1。B-1确认承运但尚未来货时可以跟进和保存安排，不伪造入仓码或对方确认；实际来货在原登记行锁和同一事务内，将已有有效预约明细关联到真实订单及入仓码，继续通过同一BOOKING键读取覆盖；关联失败则来货事务一起回滚。该关联不自动改写预约数量快照、确认时间或来源版本，也不扫描补填历史记录。预约保存按登记号和订单号的稳定顺序锁定货源，并在订单锁定后清除查询缓存、重新核对来源，防止使用锁定前的旧事实。客户不符、目的仓变化、重复别名或已取消承运均不能借用其他货物的预约结果。跨来源筹划、正式确认和变化处理遵循总体方案，读取或核对成功不能代替保存和正式确认成功。
| 业务域 | 能力范围 | 原型入口 |
|---|---|---|
| 海外仓 | 尾程订单、入库单、换标单、托盘管理、库存管理；箱号管理与产品库当前暂不进入海外仓业务正式入口；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/` |
| 海外仓排车与智能预排 | 平台查看排车列表/详情，按入仓计划或已收托盘创建预排，并完成编辑、取消、拣货、出库、发车和转派送 | 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/` |
| 海外仓 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/` |
| 海外仓 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` |
| 车辆管理、司机资质与保养加油 | 业务范围见[车辆管理原型梳理与任务规划](车辆管理原型梳理与任务规划.md)；后端 `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/fleet/`，OpenAPI `fleet-drivers-v1.yaml`、`fleet-trips-v1.yaml`、`fleet-vehicle-records-v1.yaml`；证照和运维照片复用 File | Admin 接入目录 `../../apps/admin-web/src/modules/overseas-master-data/`；原型来源和页面 ID 按规划第 1、2 节定位 |
| 自有业务运营视图 | [自有业务首版开发契约](自有业务首版开发契约.md)、[后端接口设计](自有业务后端接口设计.md) | Admin海外通用资料模块；Lastleg `fleet/ownedbusiness/`，原排车为主事实，File分类契约 `fleet-owned-business-photos-v1.yaml` |
| 外配业务运营视图 | [外配业务首版开发契约](外配业务首版开发契约.md) | Admin海外通用资料模块；Lastleg `fleet/outsourcedbusiness/`，复用原排车事实和附加运营记录 |
| 内部拼车需求池 | [内部拼车需求池首版开发契约](内部拼车需求池首版开发契约.md)：车次余位发布、销售意向、确认占位、本土订单关联及统一我仓上车 | 复用上述车辆管理及本土业务入口；不开放客户端运力市场 |
| 国内出仓后船节点 | 对已确认离开国内仓库的订舱/柜次定时查询船节点，保存最新节点、异常和查询历史，贯通目的港提柜至还柜事实 | 标准语义见[船节点标准化契约](船节点标准化契约.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`。
## 终端与模块边界
- 海外仓出库、派送、异常退回和一件代发已经纳入全流程，不再作为海外入仓之后的独立开发批次。
- 派送业务由 Admin/Client 承载，不进入海外 PDA；海外 PDA 负责现场入仓、托盘、排车拣货和出库等已注册作业。
- 箱号和产品信息作为入仓、库存、箱唛及 SKU 快照的一部分使用；是否提供独立维护页面由正式路由决定，不影响全流程状态推进。
- 高级 BI、开放平台和独立移动 APP 属于独立产品能力，不与现有业务全流程完成状态混为一谈。
## 船节点定时查询边界
- 所有供应商统一节点、时间语义、异常事实、停止规则和新增船司接入门禁以[船节点标准化契约](船节点标准化契约.md)为准；供应商缺失的节点保持缺失，不推测补齐。
- 现有 `CarrierScheduleQuery` 查询任务及其查询尝试、历史、来源、过期标识和频率约束整体重新归入海外仓业务；不再把它列作国内货柜履约港务/船期查询能力，也不得另建一套重复任务。
- 定时查询对象必须关联真实订舱、柜次以及可用的船司/船名航次或跟踪标识，不建立脱离业务单据的孤立轮询任务。
- Firstleg `portschedule/` 负责任务编排、业务关联、最新节点、节点历史、幂等和停止条件；`integration-service/` 只负责船司或轨迹供应商适配、限流、超时、重试和错误归一化，不保存业务主数据。
- 查询从确认柜子离开国内仓库后开始，贯通目的港到达、卸船、清关、提柜和还柜事实，默认在实际 `EMPTY_RETURNED` 后停止；这只扩展货柜轨迹事实，不纳入海外派送、海外仓出库或库存离仓业务。失败不能伪造成功节点，需保留来源、观测时间、最近成功时间和失败原因。
- 现有“每 3 天一次、窗口最多 3 次”、六家船公司来源、最近有效结果和过期标识是同一查询能力的既有约束，归海外仓业务继续核对；后续若调整自动轮询频率、供应商额度、退避或停止规则，应只修改海外仓业务契约和这套任务。
- 当前原型没有独立的“船节点定时查询”页面；涉及页面展示时从订舱、船期或货柜详情进入，不得为了匹配原型菜单把它归入海外派送。
## 本土卡车与散板统一前端下单
- 同一业务在 Admin 新增/编辑和 Client 下单使用一致的字段、顺序、控件、默认值、校验及提交转换；Admin 新增额外选择客户，编辑固定原订单客户；Client 的客户仅由登录会话确定，业务请求体不携带客户标识。
- 业务表单统一为运输信息、货物信息、费用与时效和备注。起运地/目的地、两端联系人、电话及详细地址左右对应；件数、预计托数、重量和体积默认零，预算默认为空、币种 USD，空预算和零预算分别保留。车辆只在卡车填写，商品与预计托数只在散板填写。
- 两端统一使用数字控件和 USD/CNY 选择；重量支持三位小数、体积六位小数、预算两位小数；取送时间按当地分钟输入并提交秒为零的值，不进行时区转换。四项联系信息及两个时间均必填，送货不能早于取货。
- 各应用内部由 `TransportDemandForm.vue` 和 `transportDemandForm.ts` 复用表单、校验与业务请求转换；两端对应源码按同一内容核对，不建立跨应用目录依赖。创建保留稳定幂等键；平台编辑保留客户、业务单号和版本，受状态及只读承运来源限制。
## 本土散板简化下单
- 平台代客创建必须显式选择客户；客户端客户范围只取认证会话。新增、编辑保持现有独立页面；平台普通编辑仍只允许待接单且非拼车来源订单，池来源继续只读展示真实承运安排。
- 下单移除运输方式及柜型字段，不再要求选择自送或我司提货。拼车或优先拼载属于内部安排，不再冒充交货方式或作为下单必填项；运输类型和是否打盘不在新增主表单要求填写，未知安排保持空，不自动补造。散板移除柜型字段。
- 需求保存取货地、目的地、可选详细地址补充、起运地联系人及联系电话、目的地联系人及联系电话、商品名称、预计托数、件数、总重量、总体积、预算总价、币种、取货与送达时间和备注。商品名称、预算和备注选填；四项联系人信息与取货、送货时间全部必填；预计托数、件数及重量体积可为零，不能为负。件数、地址补充和备注按统一前端下单表单展开填写。
- `estimatedPalletCount` 是下单预计托数；`packageCount` 是件数，二者独立。下单不生成实物托盘，不把预计托数写成实际收货或实占托位；拼车来源沿真实询价的货名与预计托数保存。
- `pickupAt` 与 `deliveryAt` 保存不带时区的当地日期时间，按分钟输入、原值显示，不进行 UTC 转换。取货与送货时间均必填；送货时间不能早于取货时间。预算明确显示 USD 或 CNY，金额空值与零值区分。
- 平台和客户接口共用 Lastleg `looseboard/dto/LocalLooseboardRequests.java`、`LocalLooseboardResponses.java` 及 `overseas-business-v1.yaml`，不保留旧运输枚举或要求日期别名。现有 API 路径与权限复用，空库结构同步模块基线及海外统一初始化，不回填测试存量，不自动执行 SQL 或部署。
## 美国本土卡独立下单
- 客户端和平台新增/编辑共用同一服务端需求合同：移除运输类型、柜型、下单预报托盘数及原要求时间；车辆类型为必选的“15拖”（`PALLET_15`）或“30拖”（`PALLET_30`）。车辆主档仍独立维护实际容量，车型不等于本票货量。
- 起运地联系人、起运地联系电话、目的地联系人、目的地联系电话、取货时间和送货时间全部必填。时间按日期及小时分钟填写，不进行时区转换；送货不能早于取货。列表、详情与平台编辑展示同一份保存值，客户端不提交客户标识。
- 独立下单不生成预报托盘，首次实际收货确定确认托数；已有拼车来源的真实预报及实际履约继续独立记录。拼车来源未提供的车型、目的地联系人/电话、送货时间保持未知，页面显示“—”，不捏造数据。美本土散板按本文“本土散板简化下单”使用独立需求合同。
- 接口及字段唯一实现合同为 Lastleg `trucking/dto/UsTruckOrderRequests.java`、`UsTruckOrderResponses.java` 与 `src/main/resources/openapi/overseas-business-v1.yaml`；数据结构同步模块基线及海外统一空库初始化。页面承载核对见 Client `cross-border/PROTOTYPE_MATRIX.md` 和 Admin `overseas-business/PROTOTYPE_MATRIX.md`。
## 系统边界与索引维护
- 托盘管理的单张标签 PDF 从 Admin `PalletsView.vue` → `warehouse-overseas-service` 的 `GET /api/platform/v1/warehouse-admin/{warehouseId}/pallets/{id}/label` 进入，只按真实托盘编码打印，不重新生成编号。纸张、方向和模板字段只查[打印标签当前入口](../打印标签维护/README.md)的对应类型；服务接入与权限见海外资源服务 `AGENTS.md`，不在本文复制模板常量或尺寸。
- 海外仓合作仓是现有头程仓库主数据的类型扩展，需同步核对 Admin `warehouses`、Warehouse Service 的 DTO/Controller/OpenAPI/SQL 及实际消费者；不得因此把海外库存业务写入国内 Warehouse Service。
- 海外库存、库内作业和海外本土业务已有明确服务入口：`gateway/` 是统一 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 冒充入仓码。
- 平台可按单票尾程订单入库计划（托数、托盘类型、分配/可合托/加急和备注）；入库仓、入仓码和预计到仓时间均展示冻结事实，不允许人工改写。预计到仓日期由服务端锁定来源柜全部订单的 `estimated_warehouse_at`，缺失或同柜不一致时阻断，人工与自动计划统一写入该柜日期。写入时校验订单版本、客户归属、仓库主档和幂等键；一票柜保存后立即自动生成并绑定托盘码、海外仓托盘和资源锁，多票柜在最后一票计划齐全时自动为全柜完成同一动作。`resourcePendingPlanCount` 只用于自动生成失败后的显式重试，不是正常人工步骤。分配、可合托、加急必须随入库单列表和海外 PDA 入仓码作业返回并展示，其中“可合托”只向现场提供选择：合托时扫描同目的仓已使用的托盘码，独立收货时扫描新托盘码，不作为实收或完成门禁。新增暂扣只允许货物完成入库后执行；暂扣只作用于该票并仅阻断排车和出库，不阻断入库计划或入库作业，同柜其他订单不受影响。
- 头程散货在预装确认且真实集装箱号就绪后，按 `集装箱号-FBA仓编码-三位序号` 冻结托盘码；序号在当前柜、当前 FBA 仓内从 001 独立递增。送柜报关、清关提柜和预装清单共用同一按 FBA 仓分组的打印清单，可整柜打印或选择单仓前 N 张补打。该编号随装柜完成事件进入海外，生成入库计划与海外实体托盘时原样沿用；一件代发继续使用国内装箱打托形成的托盘号，不参与散货重新编号。
- 头程与海外仓允许装托密度不同。尾程最终托数取不低于头程已有托盘码数的海外计划结果：头程已有编码全部保留，数量不足时在同柜、同 FBA 内按连续下标补码，不因数量差异阻断。柜级预览必须分别返回并展示头程已有、海外仓补充和最终托数；最终总数不得标成“本次新增”。
- 尾程订单人工节点固定为国内报关完成、预计/实际开船、预计到港、国外清关完成、实际到港等待卸船、预约提柜和卸柜八行完整快照。第一次保存后该订单永久使用 `MANUAL` 来源，读取和页面展示不得再回退柜级节点，也不得反向修改货柜船节点。
- 目的港码头拖车仍归 Firstleg 货柜聚合，但 Admin 清关提柜列表不再使用预约/实际提柜作为到仓业务时间：原两列改为“预计到仓/实际到仓”。未人工维护且未建入库计划时，预计到仓按[预约日历统一日期规则](预约工作日历V13变更说明.md#2026-10-19-当前预约列表收敛规则)展示到港日期加两个自然日的默认值，列表与详情一致且不自动写入。人工调整在列表内选择日期时间并由 Lastleg 按 `sourceContainerBookingId` 原子同步整柜尾程订单，已有入库计划后锁定；实际到仓只取海外 PDA 首次开始收货的 `ll_receiving_container_session.receiving_at`。车队、邮件、还柜及 `unloadingCompletedAt + 72h` 还空预警仍按原码头拖车链路处理。
- 手动还柜以真实海外卸柜完成且尚未还柜为准，仍校验独立还柜权限；无需事先存在车队、预约或提柜时间。首次命令使用版本 0 创建拖车记录，车队字段可为空，不补造提柜事实。还柜时间不得早于卸柜完成时间或已有提柜时间，成功后同步标准还柜节点并解除报空预警。
- 船节点是头程海运在途事实与海外接柜之间的衔接能力，业务聚合继续由 Firstleg 按 `containerBookingId` 柜级持有，不绑定客户；跨区域事件使用 `tenantId=0` 平台技术范围，到港/可提柜结果通过明确契约提供给海外区域，不复制第二套轮询任务。
- Admin、Client 及海外 PDA 按当前统一 Gateway、Auth 会话与可靠直接投递契约接入；不沿用旧双区域 API 或独立海外 Token，业务页面不自行实现第二套登录。
- 海外仓 PDA 使用独立 `apps/pda-overseas-uniapp/` 工程和发布身份，但账号仍由国内 Auth 唯一签发；真实作业请求必须经统一 Gateway 的显式 PDA 路由。工作台只展示已注册并启用的现场作业，其他业务通过 Admin/Client 完成，不以某个终端是否承载全部操作判断端到端流程是否完成。
- 海外 PDA 的实际收货仓是国内 `warehouse-service` 中 `tenant_id=0`、类型为 `OVERSEAS`、状态 `ACTIVE` 且启用 `RECEIVING` 能力的平台共享物理仓，并由当前海外 PDA 作业账号的仓绑定固定，角色与会话字段以统一认证契约为准；海外数据库只保存相同 `warehouseId` 引用。PDA 不接收仓库 ID，也不能切换柜号。统一 Gateway 对每个 `/api/pda/**` 请求在本地验签后向 Auth 实时核对账号 `token_version` 与当前仓绑定，换仓或清空绑定后旧 Token 立即失效，Auth 不可用时拒绝请求。待收柜在首次准备时原子认领到该仓，入仓计划、尾程订单和收货会话冻结实际仓 ID/名称；国内装柜事件的仓库仅作为来源仓快照，目的仓/FBA 仓也不得冒充实际收货仓。
- 海外 PDA 接柜候选、认领会话、国内五类装柜照片对照、海外三类签收照片与整柜完成均按 `sourceContainerBookingId + containerNo` 聚合，不保存客户并允许同柜多个客户。国内照片在签收阶段展开、收货阶段折叠，只读加载失败不阻断拆柜。签收后为柜内每个计划按其自身客户生成任务；入仓码解析、SKU 实收、托盘占用和库存入账继续按该票真实客户隔离，整柜完成需全部计划核平且只发布一次柜级完成事件。
- 业务规则只改本主题正文或相应正式契约；仅代码入口、职责或路径变化时更新实际受影响的索引与最近指引，不批量同步所有层级。不把排期、完成比例或临时任务状态写入快速索引。
## 码头车队邮件
首次选择车队后从清关提柜列表发送请求，更换车队时原子保存原车队取消和新车队提柜两封邮件；同一车队重复选择不发信。邮箱读取供应商资料，缺失或无效时阻断发送或换队。邮件顺序投递，失败待人工核对后重试。接口、临时模板和启用方式见 [Firstleg 车队邮件说明](../../baiyue-firstleg/firstleg/docs/terminal-drayage-mail.md)。
海外仓业务/排车列表统一作业改造契约.md
+2
View File
@@ -17,6 +17,8 @@
2026-10-21 本轮登记契约：`POST /api/platform/v1/last-leg/dispatches/{dispatchNo}/exceptions`，动作`MARK_EXCEPTION`，`recordVersion/idempotencyKey/exceptionType`必填；`returnDirection/description/imageFileIds`选填。说明最多1000字、图片最多20张；异常图片类型`OVERSEAS_DISPATCH_EXCEPTION_EVIDENCE`，平台0、本车ID归属，非空JPG/PNG、单文件10MiB。主表新增可空`exceptions_json`，与原版本、历史、命令账本同事务保存；代码及基线已准备，未执行SQL或部署。
7. 本批聚焦排车列表、详情、直接关联操作及必要生产者和消费者。车辆列表、司机管理、自有业务、外配业务、出车记录的整页改造后续逐页处理。
8. 同时支持先选同一起运仓的可排货物/托盘再生成排车单，以及先创建空排车单再添加货物；空单不能伪造货物、拣货、装车或发车事实。2026-10-21 用户进一步明确先排车和货物，车辆、司机在建单后由调度或客服在后台补充，不涉及客户自助填写；新建排车不展示或要求填写车辆、司机及证照，先完成货物分组，允许选填每趟计划时间和备注。计划托位仅用于预排分组，不表示已绑定真实车辆。后续维护车辆信息及提交审核继续使用既有资源资格校验。用户随后明确：货物计划增减统一在智能排车办理，排车列表车辆信息及详情不再单独提供添加／移除货物。智能排车同时承载新建及已生成排车货物调整，已有单使用原排车号和正式货物命令，不转换为草稿或重建单据；保留真实PDA拣货，已扫码禁止调整，理货审核通过且零扫码时先显式退回重审后再调整。
2026-10-21 区域入口确认：智能排车新建选货删除查询区的海外仓选择，仅保留“全部／洛杉矶／纽约”。候选接口 `warehouseId` 可选，不传时按区域做数据库分页、计数；指定仓的已有排车和预约消费者保持单仓查询。首个选中来源决定草稿真实起运仓，草稿建立后按该仓读取并禁止切换至其他区域混仓；全部表示该草稿仓的全部候选。未确定起运仓且区域匹配多个仓时不能提前创建服务器车辆容器，先选货再确定仓。空单没有来源可推断仓，其起运仓放入排车设置内选择。创建、锁货和转换的同仓约束保持不变。
9. 车辆和司机既可从已有档案选择，也允许临时填写外配车辆和司机；临时填写不伪造车辆或司机档案关联，不自行创建主档。
10. 后台确认装车完成必须以PDA真实拣货核平为前提。后台不提供替代PDA的拣货数量补录来绕过此条件；PDA和后台均可确认装车完成，一次动作自动完成发车。
11. 用户随后澄清本次“新增预约”是预约日历的功能需求，先与本批排车改造分开整理。本批不新增日历预约创建或独立约车流程；排车保留已有FBA预约关联；用户随后对车辆预约权威来源问题答复“那就不要”，因此排车取消车辆预约字段、关联操作及公开协议，不再等待或新建该权威提供者。此前确认的先保存后关联意见保留为日历需求输入，不作为本批扩大实现范围的授权。
财务管理/README.md
+15 -384
View File
@@ -1,390 +1,21 @@
# 财务管理闭环盘点与范围建议
# 财务文档入口
当前费用入池 P0 的唯一收口说明见：[财务费用入池 P0 闭环](财务费用入池P0闭环.md)。费用入池后的对账、应收应付结算、收付款、冻结、隔离和导出闭环见：[财务对账结算 P1 闭环](财务对账结算P1闭环.md)。两份闭环文档覆盖当前已确认范围；与本文历史范围冲突时，以闭环文档和更新日期更晚的产品确认优先。
只负责路由。已知页面、接口或服务时跳过本文件；接口实现从 Finance Controller/DTO/OpenAPI 与最近指引进入，规则只读下表命中的正文段落。历史五页范围不覆盖后来确认的资金账户与当前闭环。
## 当前确认：一件代发客户资金账户（2026-09-05）
## 当前规则正文
当前对话已将资金账户作为一件代发的前置节点重新纳入范围，并覆盖本文后续历史章节中“钱包不做”的旧结论。首批固定为 CNY。平台设置授信时必须同时设置晚于今天的到期日，最远日期不设上限；到期日当天仍有效。有效期内消费先扣实际可用资金，不足部分累计为已用授信；次日授信失效时，已用授信自动并入实际余额并允许形成负数，负数实际余额会阻止客户提交新订单。充值先归还已用授信或负余额，剩余金额才形成正数资金。
客户选择固定或自定义金额，查看后台配置的平台统一静态收款码，付款后上传 JPG/PNG 截图形成待审核申请。平台在客户账户明细顶部审核或驳回，也可手工充值、扣款和设置客户限时授信；每次变动写不可变账户流水。新账户默认授信为 `0.00`，只有平台明确设置额度与有效期后才启用。Finance 还提供仅服务令牌可访问、按业务类型和业务单号幂等的冻结、结算和释放接口，供一件代发等模块接入。审核、账户更新、流水、冻结记录和幂等结果在 Finance 单事务内完成，文件内容仍归 File 服务。接口契约见 [客户资金账户 OpenAPI](openapi/finance-wallet-v1.yaml)。
> 盘点日期：2026-09-09
> 当前状态：费用入池 P0 与对账结算 P1 已完成测试环境部署及真实 HTTP 全链验收；最终报告为 `baiyue-firstleg/reports/admin-test-env-acceptance-20260909103401.json`，1518/1518 通过。领导页面人工截图仍按独立验收规则执行
> 盘点范围：入库计费现状、平台后台财务原型、Admin/Client/Firstleg 当前实现
> 结论口径：本文区分“代码已实现”“原型展示”和“建议范围”；原型功能不自动成为开发范围。
## 费用来源扩展确认（2026-09-02）
- Finance 继续保持独立服务和独立数据库；业务服务只生产费用事实，不能直接写财务单据或余额。
- Firstleg 入库费用继续按客户和入仓码进入 Finance；柜级公共费用必须先按柜内真实客户与业务订单原子分摊，再逐客户进入应收应付。入仓码是可选引用：存在时必须校验真实归属，不存在时保留订单/业务单号，禁止伪造入仓码。
- Lastleg 的海外入仓、海外采购、本土卡车、本土散板和海外仓服务费使用统一版本化来源。审核通过、调整和作废同事务写海外 Outbox，通过 Event Bridge 向国内 Finance 投递完整不可变快照；Finance 不跨海外数据库回查。
- Finance 以 `sourceSystem + sourceType + sourceFeeId + sourceVersion` 唯一入池；重复事件幂等，同版本不同哈希拒绝，已进入有效账单或结算单的来源禁止替换/作废。
- 海外仓服务费只强制客户、海外仓和业务编号；入仓记录/入仓码按真实业务选填，月租、仓租等无入仓码费用仍可入池。
当前实现包含柜级分摊 API/Admin 录入、海外费用来源 API、跨区事件、Finance 通用消费入口及数据库脚本，并已完成测试环境数据库和真实 HTTP 验收。页面人工截图仍按独立验收规则执行。
## 历史测试环境部署状态（2026-08-12，已解除）
当时的 Finance 全链路测试环境实跑报告为 `baiyue-firstleg/reports/finance-full-acceptance-20260812.json`：共 430 项，411 项通过，19 项失败，当时结论为 `DEPLOYMENT_BLOCKED`。这些阻断已在后续版本解除，当前结论以 P0/P1 闭环文档和 2026-09-09 最终报告为准。
当前主要部署阻断：
- Gateway 健康，但 `/finance-service/v3/api-docs` 返回 HTTP 503，测试环境 Finance 服务不可用。
- `baiyue_finance` 当前仅部署旧 F0 schema；`fin_bill`、`fin_fee_source` 等存量表无业务数据，G3/G4 新表未部署。因此对账、应收应付、凭证及结算写链无法完成真实 HTTP 验收。
- 本地脚本和模块契约测试通过只证明验收程序契约成立，不代表测试环境 Finance 服务或数据库迁移已经部署成功。
报告生成后，产品进一步确认现有 ACTIVE 往来单位均可作为应付结算候选，不要求 `SUPPLIER` 类型。曾为诊断临时新增的 `FIN-FULL-SUP-20260812` 及其类型映射已从测试库完整删除；全量脚本和 Admin 页面均已改为复用现有 ACTIVE 往来单位。原报告中的“未找到 ACTIVE SUPPLIER”仅反映当时脚本的旧过滤条件，不能倒推为测试环境已通过。当前仍需完成墨家测量实重同步修复、Finance 服务部署和 G3/G4 schema 迁移，再重跑同一三模块链路形成新报告。
产品/业务逐项确认请使用：[财务管理产品确认表](财务管理产品确认表.md)。
产品回传后的差异和剩余门禁见：[财务管理产品确认版差异与剩余待确认](财务管理产品确认版差异与剩余待确认.md)。
技术边界已确认：[财务服务边界设计](财务服务边界设计.md)。Finance 采用独立服务和独立数据库，Firstleg 仅提供业务费用来源。
开发前总控门禁与 F0/F1 任务清单：[财务开工门禁与F0-F1任务清单](财务开工门禁与F0-F1任务清单.md)。
订单与客户领导验收唯一范围入口：[财务核心五页产品与接口验收契约](财务核心五页产品与接口验收契约.md)。
订单与客户 11 个 P0 操作、状态机与验收用例：[财务核心 P0 操作契约与验收用例](财务核心P0操作契约与验收用例.md)。
订单与客户实现与 Admin 接入证据（不反向修改目标契约）：[财务核心 P0 实现证据矩阵](财务核心P0实现证据矩阵.md)。
文档优先级：五页验收契约和本轮产品确认 > 五页目标 OpenAPI > 既有人工 F1 契约/门禁 > 领域模型、历史全量规划和迁移文档。旧文档用于追溯，不得据此把钱包、充值、发票、费用分析或利润表重新纳入订单与客户。
旧文档降级规则：
| 文档/章节 | 当前用途 | 订单与客户实施约束 |
|---|---|---|
| 本文第六节起的“历史全量规划” | 保存早期盘点和演进背景 | 与五页契约冲突时全部失效，不作为菜单、路由、字段或接口依据 |
| `财务领域模型与跨服务契约.md` | 历史合并稿 | 已被数据字典和跨服务契约替代 |
| `财务服务边界设计.md`、`财务领域模型与数据字典.md` | 服务边界和长期模型参考 | 其中钱包、充值、发票、费用分析、利润模型不属于订单与客户 |
| `财务历史迁移与上线验收方案.md`、`财务F0实施任务拆分.md` | 历史迁移、底座任务追溯 | 不得覆盖五页范围和当前实现状态 |
详细设计材料：
- [海外仓费用统一接入财务评审方案](海外仓费用统一接入财务评审方案.md)
- [海外仓费用统一接入阶段0技术契约](海外仓费用统一接入阶段0技术契约.md)
- [财务业务操作流程图](财务全链路流程图.md)
- [财务业务全流程总览图（PNG）](财务业务全流程总览图.png)
- [财务来源接入现状](财务来源接入现状.md)
- [财务领域模型与数据字典](财务领域模型与数据字典.md)
- [Firstleg-Finance跨服务契约](Firstleg-Finance跨服务契约.md)
- [F1 人工账单、收款、成本接口契约](F1人工账单收款成本接口契约.md)
- [F1 人工财务契约审查与门禁](F1人工财务契约审查与门禁.md)
- [财务核心五页产品与接口验收契约](财务核心五页产品与接口验收契约.md)
- [财务核心五页 OpenAPI](openapi/finance-core-five-pages-v1.yaml)
- [财务核心 P0 操作契约与验收用例](财务核心P0操作契约与验收用例.md)
- [财务核心 P0 实现证据矩阵](财务核心P0实现证据矩阵.md)
- [财务历史迁移与上线验收方案](财务历史迁移与上线验收方案.md)
- [财务F0实施任务拆分](财务F0实施任务拆分.md)
历史合并稿：[财务领域模型与跨服务契约](财务领域模型与跨服务契约.md) 已由“领域模型与数据字典”和“Firstleg-Finance 跨服务契约”两份文档替代，不作为后续实施依据。
## 一、结论
当前首期采用人工简化方案：平台财务登记收付款并上传凭证；客户可查询并确认本人已出账对账单。首期不做银行自动对账、自动核销任务、复杂审批、客户钱包、发票、供应商在线结算、汇率、月结或总账。
当前已经实现业务计费闭环，并已落地 Finance 独立服务/数据库、人工账单/收款/成本基础接口、平台与客户权限种子、Admin 财务页面和 Client 只读账单页面。当前不是“整体未开发”，而是已进入专项修复和契约收敛阶段。
已具备的基础链路：
```text
测量/称重
-> 测量审核
-> 计费规则匹配
-> 费用试算与快照
-> 发布对客费用
-> 客户查看并确认已出账对账单
-> 完成入库
```
当前 F1 已具备的实现链路：
```text
平台财务创建草稿账单
-> 出账冻结
-> 人工登记收款
-> 一笔收款分配多张账单
-> 部分收款/收清状态更新
-> 客户只读查询
```
此前基础链路已完成 Firstleg 真实柜次体积快照、客户归属、成本凭证校验、revision、双权限上传、费用来源事件/Relay/快照、Finance `fin_fee_source` 消费写入和完整幂等。在此基础上，固定五页所需的 11 个目标 operation、Admin 页面动作与 IAM 权限目录现已闭环，G1-G4 本地门禁均为 `PASS`；最终直接证据包括 Finance 聚合 82/82、G3 16/16、G4 18/18、收款及 AR 同步 12/12、IAM 168/168、Admin 财务专项 60/60、Admin 全量 654/654 及 Admin 构建通过。真实 MySQL 执行、测试环境 HTTP 冒烟和领导页面验收仍需单独完成，未经当前对话明确授权不触发 Jenkins。
订单与客户范围已重新冻结为原型 5 页：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付。费用分析、利润表、发票和钱包不做，也不保留菜单、路由或假按钮。客户账户改为账单、收款和应收应付来源派生的财务往来总览，不做充值/预收。
## 二、事实来源与边界
本次按以下资料核对：
1. 入库测量与计费需求文档明确入库测量与计费只做头程计费，不自动形成应收、应付、对账单、收付款、核销、发票、利润或总账。
2. 平台后台原型提供财务管理全量参考，但其中数据和交互主要由单页 HTML 内的静态数据及前端脚本驱动。
3. 当前代码用于证明“已经实现什么”，不反向扩大产品范围。
主要依据：
- `docs/入库测量与计费/入库测量与计费计费财务需求确认表.md`
- `docs/入库测量与计费/入库测量与计费V2需求确认清单.md`
- `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`
- `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html`
- `apps/admin-web/src/modules/inbounds/`
- `apps/admin-web/src/modules/fee-items/`
- `apps/admin-web/src/prototype/modules/finance/`
- `apps/client-web/src/modules/first-leg/`
- `apps/client-web/src/modules/finance/`
- `baiyue-firstleg/firstleg/`
## 三、当前已经具备什么
### 3.1 可作为财务上游的业务数据
| 能力 | 当前状态 | 可复用价值 | 不能代表什么 |
|---|---|---|---|
| 实测重量、体积、计费量 | 已实现 | 作为费用计算依据和业务快照 | 不是财务凭证 |
| 客户计费规则、船司价格 | 已实现 | 产生确定的对客头程价格 | 船司价格不等于供应商应付 |
| 费用试算、确认、发布 | 已实现 | 形成版本化对客费用快照 | 不等于应收单或账单 |
| 费用调整 | 已实现 | 已发布费用调整生成新版本并留原因 | 尚未定义已出账或已核销后的调整方式 |
| 客户侧费用与账单查看 | 已实现 | 客户能看到入库及已发布费用结果，并在线确认本人已出账且待确认的对账单 | 客户不能修改金额、在线提出争议或登记收款/核销 |
| 费用项目主数据 | 已实现 | 支持费用编码、分类、国内/国际、提货/仓库应收应付属性 | 费用项目属性不自动生成财务记录 |
| 入库费用明细 | 后端已实现 | 支持人工新增、编辑、删除、审核、自动发布的入库运费明细 | 尚无跨入库单财务台账和结算生命周期 |
| 权限与审计基础 | 部分具备 | 费用明细查看、编辑、删除、审核已有权限和业务审计 | 财务制单、复核、收款、核销、反核销权限尚未定义 |
### 3.2 当前费用明细的真实边界
Firstleg 已有 `fl_inbound_fee_detail`，包含：
- 入库单、费用项目、方向、业务发生日、币种、单价、金额；
- 重量、体积、计费量等业务快照；
- 审核状态、审核人、驳回原因；
- 发布状态、发布时间；审核通过后自动发布并成为结算候选；
- 自动计费来源的费用单号和版本。
但当前仍存在以下断点：
- 自动发布链路只生成 `RECEIVABLE` 对客运费。
- 人工 `PAYABLE` 明细使用 Warehouse `supplierId/supplierName` 快照；费用项目 `supplierCategory` 可空，空表示任意启用供应商，非空严格匹配。
- 人工明细采用编辑、提交、审核、调整、作废闭环；审核通过后自动发布，不再存在“是否结算”开关。
- 已发布应收明细只能按单个入库单查询，未形成按客户、币种、账期聚合的财务台账。
- 没有冻结、出账、核销后的费用变更规则，无法保证历史账单金额稳定。
## 四、原型中有什么
平台后台原型的财务菜单包含以下能力：
| 原型模块 | 原型展示的主要能力 | 当前代码状态 | 是否能直接纳入首期 |
|---|---|---|---|
| 客户账户 | 原型为余额、冻结、可用余额和充值流水 | 未实现 | 订单与客户保留汇总/详情/流水结构，但改为未收、待出账、本期已收等派生指标；删除充值/钱包能力 |
| 客户应收应付 | 费用明细、编辑审核、按截止时间或勾选生成账单 | 已接入真实费用来源和编辑审核闭环 | 作为应收应付费用池 |
| 客户对账单 | 账期、汇率、应收、已收、结清、明细和支付历史 | 未实现 | 可作为应收闭环核心，但汇率和开票先暂缓 |
| 结算单应收 | 应收、已收、余额、到期日、审批、部分收款 | 未实现 | 可合并进账单/应收单，避免首期重复建模 |
| 结算单应付 | 供应商应付、已付、余额、审批、部分付款、利润 | 未实现；上游成本来源不完整 | 订单与客户纳入，但删除利润字段/按钮；必须先补真实供应商应付来源和付款凭证链路 |
| 费用分析 | 内外部费用对比、趋势和明细 | 未实现 | 订单与客户明确不做，不进菜单/路由 |
| 利润表 | 按客户、货柜、单票、月份统计收入、成本、利润率 | 未实现 | 订单与客户明确不做，不进菜单/路由 |
原型还出现了发票抬头、开票日期、汇率、支付方式、收付款凭证号等字段。它们只说明未来可能需要，不代表当前产品已经确认税务、外币折算、资金或发票边界。
当前 Admin 已有正式财务路由、账单详情/草稿修改/出账/调整/作废、人工收款和成本页面及真实凭证上传调用，Client 已有正式只读账单页面。后端已改为根据 `containerId` 调 Firstleg 体积快照并完成成本凭证校验，但 Admin 仍强制人工填写并提交柜内订单体积，且未接客户账期和 revision，因此前端创建闭环尚未与最终契约对齐。
## 五、当前修复中缺口
| 序号 | 断点 | 直接影响 |
|---|---|---|
| 1 | 五页读接口、平台/客户固定 DTO 和追踪响应已实现 | Finance 35/35 BUILD SUCCESS；本轮使用现有 Surefire 报告核对，不重新执行 Maven |
| 2 | 收款和成本均已校验凭证，但 `fileClient == null` 时仍 fail-open | File 客户端缺失时可能绕过凭证校验 |
| 3 | 后端已使用 Firstleg 真实体积快照，Admin 仍要求人工填写并提交体积 | 页面与最终请求契约不一致，产生无效输入和误导 |
| 4 | 幂等已有 SHA-256 与同参重放，但未覆盖完整规范化请求，缺 PROCESSING 恢复测试 | 仍可能误判同参或无法恢复中间态 |
| 5 | 客户账单已过滤可见状态，收款列表仍暴露平台字段且未按可见账单过滤 | 客户只读边界仍不完整 |
| 6 | Admin 已接账单动作，但未接客户账期、revision，整柜仍人工填体积 | 平台财务页面仍非完整闭环 |
| 7 | 业务错误码仍以通用错误和中文消息为主 | 前端无法稳定区分版本、幂等、凭证和归属错误 |
| 8 | revision 后端查询已落地，Admin 尚未接展示 | 调整历史仍不能在产品页面核对 |
## 六、全量财务规划与交付顺序
### 6.1 历史全量规划（不作为订单与客户范围）
以下内容只保留为历史分析。若与《财务核心五页产品与接口验收契约》冲突，以五页契约为准。
| 目标域 | 业务结果 | 主要来源 | 不能提前假定的口径 |
|---|---|---|---|
| 客户账户 | 客户财务往来派生汇总、详情和流水 | 账单、收款和应收应付来源 | 订单与客户不建设钱包、充值、预收或自动扣款 |
| 客户应收 | 客户欠款、到期、逾期、结清 | 已发布对客费用、补差/冲销 | 收入确认节点和账期规则 |
| 客户应付 | 客户代垫或返还类应付款（如确有业务） | 业务费用或人工单据 | 产品是否真的存在“平台向客户付款”的场景 |
| 客户对账单 | 期间内费用汇总、明细、平台出账和客户确认 | 应收/应付费用池 | 一张账单是否允许混合方向、混合币种 |
| 结算单应收 | 可审批、可收款、可核销的应收结算单 | 已确认客户账单 | 与客户对账单是一对一还是一对多 |
| 结算单应付 | 供应商成本、付款、余额和结清 | 供应商费用、运力/仓储/报关成本 | 成本确认、供应商账期、审批和付款方式 |
| 收付款与核销 | 到账/付款凭证，部分结算、反核销 | 银行流水或人工登记 | 是否首期接银行流水，是否允许一笔多单核销 |
| 发票 | 开票申请、开具、红冲、作废和关联 | 已确认应收/收款 | 税率、含税/未税、开票主体、外部平台 |
| 费用分析 | 历史规划，订单与客户不做 | 应收应付台账 | 不进入订单与客户菜单、路由和验收 |
| 利润 | 客户/单票/柜次/月度收入、成本、利润率 | 应收收入 + 应付成本 + 分摊 | 汇率、成本分摊、收入成本确认时间 |
### 6.2 分阶段交付顺序
全量目标建议拆成五个可验收阶段：
| 阶段 | 交付范围 | 关键闭环 | 前置依赖 |
|---|---|---|---|
| F0 财务底座 | 独立 Finance 服务/数据库、财务主体、客户/供应商往来单位、币种、费用科目、期间、权限、审计、幂等、金额精度 | 所有后续对象使用同一基础口径 | 服务边界已技术确认；产品确认主体、币种、权限和编码 |
| F1 应收与客户对账 | 应收费用池、平台出账、客户确认、结算单应收、收款登记、核销、反核销 | 费用 → 账单 → 客户确认 → 应收 → 收款 → 结清 | 当前已发布对客费用来源 |
| F2 应付与供应商结算 | 成本费用池、供应商账单、结算单应付、付款登记、付款核销、应付调整 | 成本 → 供应商账单 → 应付 → 付款 → 结清 | 供应商主数据和真实成本来源 |
| F3 客户账户与发票 | 订单与客户只做派生客户账户总览；发票暂缓 | 账户只读聚合，不维护资金余额 | 发票不属于订单与客户 |
| F4 分析与利润 | 订单与客户不做 | 不建设菜单、路由或假入口 | 后续重新立项 |
阶段之间可以并行做页面原型和契约设计，但生产数据链路必须按 F0 → F1/F2 → F3 → F4 验收。F4 不能用原型静态数字先行替代真实台账。
### 6.3 F1 最小财务闭环
F1 先处理当前已经有可靠来源的对客头程费用：
```text
已审核并发布的应收费用明细
-> 进入待对账费用池
-> 按客户 + 币种 + 账期生成对账单
-> 内部复核
-> 客户在线确认（异议仍线下反馈）
-> 平台财务出账后形成应收
-> 登记实际收款
-> 将收款核销到应收
-> 全额核销后结清
-> 错误时按权限反核销并留审计
```
F1 建议页面：
1. 应收费用池：查询、编辑、提交、审核、调整、作废；审核通过自动进入结算候选。
2. 客户对账单：生成、明细、内部复核、发送、关闭；平台财务可重开或调整。
3. 应收与收款：应收余额、到期日、收款登记、附件/凭证号、部分核销。
4. 核销记录：每笔收款对应哪些应收、核销金额、剩余余额、反核销历史。
5. 客户侧账单：查看明细、收款与未结余额，并在线确认本人已出账账单；不做在线争议。
以下历史排除清单已被 2026-08-11 的五页范围取代。结算单应付现在属于订单与客户；其余未确认能力继续排除：
- 供应商在线确认和自动付款（应付结算单与人工付款属于订单与客户）；
- 客户预充值、余额冻结和自动扣款；
- 发票申请、开票和税务接口；
- 多币种折算与汇兑损益；
- 利润表、利润率和总账；
- 银行流水自动认领；
- 复杂费用分摊和会计凭证。
### 6.4 全量阶段的范围门禁
| 范围 | 开工门禁 |
| 任务 | 唯一维护入口 |
|---|---|
| 客户账户 | 已确认只做派生财务往来总览；禁止充值、冻结/解冻、退款、自动扣款和可写余额 |
| 客户应收应付 | 明确客户作为付款方还是收款方；没有真实业务场景的方向不建菜单和数据 |
| 供应商应付 | 必须有供应商主数据、成本来源凭证、审批人、付款方式和付款责任主体 |
| 收付款核销 | 明确人工登记与银行流水的边界；收款、付款、核销、反核销分开授权 |
| 发票 | 明确开票主体、税率、含税/未税、红冲/作废和外部开票平台；未确认前只保留接口扩展位 |
| 费用分析/利润 | 先冻结汇率、收入成本确认日、成本分摊和跨币种折算；报表必须能钻取到原始费用和结算单 |
| 客户资金账户、充值、授信、冻结与业务扣费 | [资金账户规则](财务对账结算P1闭环.md#客户资金账户)；请求/响应查[资金账户 OpenAPI](openapi/finance-wallet-v1.yaml) |
| 业务费用来源、入池、直接已付与重复扣费隔离 | [费用入池规则](财务费用入池P0闭环.md)，按来源字段、覆盖矩阵或幂等条款读取 |
| 客户账单、AR/AP、收付款、作废与金额并发 | [对账结算规则](财务对账结算P1闭环.md)，只读相应出单、生命周期或不变量段落 |
| 客户/平台财务页面口径与导出 | [页面与数据口径](财务对账结算P1闭环.md#5-页面与数据口径) |
| Firstleg 与 Finance 的费用事件和服务边界 | [跨服务契约](Firstleg-Finance跨服务契约.md)；通信方式以[统一通信契约](../统一认证与服务通信契约.md)为准 |
| 海外费用接入阶段 0 专项 | [阶段 0 技术契约](海外仓费用统一接入阶段0技术契约.md)，仅该改造任务触发；不能据此推定当前实现已切换 |
## 七、已确认的产品结论（历史问题关闭结果）
## 专题与历史（按需）
下表原为产品问题清单，现按本轮确认结果保留。不得再把这些条目解释为待产品确认；实现仍受真实费用来源链路和专项技术门禁约束。
| 编号 | 待确认问题 | 建议默认值 |
|---|---|---|
| F1 | 订单与客户领导验收范围 | 固定为客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；费用分析和利润表不做 |
| F2 | 账单生成维度 | 客户 + 币种 + 账期；不同币种不合并 |
| F3 | 哪些费用可以进入账单 | `APPROVED + PUBLISHED + AVAILABLE + CNY + amount>0` 且未出账；无人工结算开关 |
| F4 | 当前已发布头程费用是否自动进入待对账池 | 是，但仍由财务选择并生成账单 |
| F5 | 账单生成后上游费用能否直接调整 | 不能；应走补差单/冲销单并保留原账单 |
| F6 | 客户是否需要在线确认和提出争议 | 客户在线确认本人已出账对账单；确认状态独立于主状态，在线争议暂不做 |
| F7 | 是否需要内部复核 | 建议制单与复核权限分离，首期允许同人需业务明确 |
| F8 | 收付款是人工登记还是接银行流水 | F1/F2 先人工登记，F3 再接银行流水；必须保存到账日/付款日、方式、凭证号和附件 |
| F9 | 一笔收款能否核销多张应收，一张应收能否被多次收款 | 两者都允许，禁止累计核销超过余额 |
| F10 | 反核销和作废权限 | 独立高风险权限，必须填写原因并完整审计 |
| F11 | 到期日如何计算 | 由客户结算条款或账单确认日 + 账期天数计算 |
| F12 | 历史已发布费用如何迁移 | 仅迁移满足入池条件且尚未形成线下已结算事实的费用 |
## 八、建议状态模型
状态应按对象拆分，避免把费用、账单和资金状态混为一个字段。
### 8.1 费用明细
```text
DRAFT -> PENDING -> APPROVED -> PUBLISHED -> BILLED
-> REJECTED
PUBLISHED/BILLED -> ADJUSTED（通过补差或冲销，不覆盖原记录）
```
### 8.2 对账单
```text
DRAFT -> REVIEWED -> SENT -> CONFIRMED -> CLOSED
-> DISPUTED -> DRAFT/VOIDED
```
### 8.3 应收与核销
```text
应收：OPEN -> PARTIALLY_SETTLED -> SETTLED
-> OVERDUE
收款：DRAFT -> CONFIRMED -> PARTIALLY_ALLOCATED -> FULLY_ALLOCATED
核销：ACTIVE -> REVERSED
```
“收款已登记”与“应收已核销”必须分开。只有核销完成后，对应应收余额才减少；反核销恢复余额，但不得删除原记录。
## 九、关键数据与约束建议
首期至少需要以下独立对象，不能只在现有费用明细表上继续追加字段：
| 对象 | 核心职责 |
|---|---|
| 财务费用来源 | 引用不可变的业务费用版本，保存来源服务、来源单据、来源版本和来源幂等键 |
| 对账单 | 客户、币种、账期、状态、版本、金额合计和确认信息 |
| 对账单明细 | 关联费用来源并保存出账时快照；一条有效费用只能进入一张有效账单 |
| 应收单 | 应收金额、已核销金额、余额、到期日和状态 |
| 收款单 | 到账金额、币种、日期、方式、凭证号、附件和登记/确认人 |
| 核销记录 | 收款单、应收单、核销金额、操作人、时间和幂等键 |
| 反核销记录 | 原核销记录、原因、审批/操作人和恢复金额 |
| 财务操作日志 | 对账、确认、争议、收款、核销、反核销和作废的完整历史 |
必须具备的约束：
- 金额统一使用定点小数，币种使用 ISO 三位码；不同币种首期禁止合并和直接核销。
- 长整型 ID 按字符串跨前端传输。
- 所有写操作带幂等键和乐观锁版本。
- 同一费用来源版本只能进入一个未作废的账单明细。
- 核销累计金额不得超过收款可用余额或应收未结余额。
- 出账、核销后禁止物理删除；调整、作废和反核销必须保留原记录。
- 客户隔离由服务端登录上下文保证；平台员工操作目标客户时必须显式选择客户并校验权限。
- 客户不可看到供应商成本、内部备注、审核意见和平台凭证附件。
## 十、原型需要修正或裁剪的地方
后续做正式页面时，不建议直接照搬原型：
1. “客户应收应付”把客户应收和供应商应付混在同一概念下，应按交易对手和职责拆分。
2. “客户对账单”和“结算单应收”字段大量重复，首期应定义清晰的一对一或一对多关系，避免两套金额状态并存。
3. 原型中的“支付历史”在应收场景应统一使用“收款/核销记录”，避免收付款术语混用。
4. 原型允许直接登记部分收付款，但没有展示确认、撤销、反核销、超额校验和并发冲突。
5. 客户账户充值与应收结算不是同一个闭环，不能用余额字段代替收款和核销台账。
6. 利润表直接展示结果，但没有收入确认、成本来源、外币折算和分摊规则，当前结果不可审计。
7. 所有正式业务表格的“操作”列应放在第一列；原型部分旧页面需要按仓库统一规则调整。
## 十一、完成标准
只有同时满足以下条件，才可以称为“客户应收财务闭环”：
- 每笔应收都能追溯到已审核、已发布且不可变的费用来源版本；
- 能生成、复核、发送并确认客户对账单；
- 能形成有到期日和余额的应收；
- 支持一次或多次收款及多对多核销；
- 支持部分核销、全额结清、反核销和作废；
- 所有金额变化均可审计，重复提交和并发操作不会多记账；
- Admin 与 Client 对同一账单、应收余额和状态的展示一致；
- 越权、跨客户、不同币种、超额核销、已出账费用调整等异常路径有服务端硬校验；
- 使用真实 API 完成至少一条“费用 -> 对账 -> 应收 -> 收款 -> 核销 -> 结清”回归，并验证反核销恢复余额。
## 十二、下一步文档工作
在写代码前建议依次完成：
1. 由产品/业务填写 F1-F12，冻结首期范围。
2. 形成《客户应收闭环需求确认表》，明确页面、角色、状态和异常处理。
3. 使用《财务管理产品确认表》完成 S1-S8、F0-F4 的产品确认。
4. 服务边界、领域模型、跨服务契约及 F0/F1 基础实现已经形成；当前按《F1人工财务契约审查与门禁》完成专项修复和测试放行，不再等待产品填写 XLSX 或重复讨论是否拆服务。
5. 形成《客户应收接口与权限契约》，包括错误码、幂等、数据范围和审计事件。
6. 形成《历史费用迁移与上线方案》，避免已有线下结算数据被重复出账。
- [领域模型与数据字典](财务领域模型与数据字典.md)、[服务边界设计](财务服务边界设计.md)用于字段或模型专题核对，不覆盖上表当前业务规则。
- [五页操作与验收用例](财务核心P0操作契约与验收用例.md)、[实现证据矩阵](财务核心P0实现证据矩阵.md)只在对应验收或历史追溯时读取。
- 原入口的旧范围、开发门禁、历史部署结果与规划已冻结到[历史盘点](归档/财务闭环盘点历史记录.md)，不继续同步改写。
- 当前部署状态与未关闭验收项只查[部署主契约](../测试环境单机部署与配置契约.md)及[认证通信主契约](../统一认证与服务通信契约.md)；旧报告不证明当前快照已验证。
财务管理/归档/财务闭环盘点历史记录.md
+392
View File
@@ -0,0 +1,392 @@
# 财务闭环盘点历史记录
> 角色：冻结历史。由原财务 README 迁入，用于追溯当时范围、方案和验收证据；下文“当前”“唯一”等称谓均属于记录当时，不是现行开发指令。当前规则从[财务入口](../README.md)进入，资金账户正文已归入[对账结算规则](../财务对账结算P1闭环.md#客户资金账户)。不为追随当前实现继续更新本记录。
当前费用入池 P0 的唯一收口说明见：[财务费用入池 P0 闭环](../财务费用入池P0闭环.md)。费用入池后的对账、应收应付结算、收付款、冻结、隔离和导出闭环见：[财务对账结算 P1 闭环](../财务对账结算P1闭环.md)。两份闭环文档覆盖当前已确认范围；与本文历史范围冲突时，以闭环文档和更新日期更晚的产品确认优先。
## 当前确认：一件代发客户资金账户（2026-09-05）
当前对话已将资金账户作为一件代发的前置节点重新纳入范围，并覆盖本文后续历史章节中“钱包不做”的旧结论。首批固定为 CNY。平台设置授信时必须同时设置晚于今天的到期日，最远日期不设上限；到期日当天仍有效。有效期内消费先扣实际可用资金，不足部分累计为已用授信；次日授信失效时，已用授信自动并入实际余额并允许形成负数，负数实际余额会阻止客户提交新订单。充值先归还已用授信或负余额，剩余金额才形成正数资金。
客户选择固定或自定义金额，查看后台配置的平台统一静态收款码，付款后上传 JPG/PNG 截图形成待审核申请。平台在客户账户明细顶部审核或驳回，也可手工充值、扣款和设置客户限时授信；每次变动写不可变账户流水。新账户默认授信为 `0.00`，只有平台明确设置额度与有效期后才启用。Finance 还提供仅服务令牌可访问、按业务类型和业务单号幂等的冻结、结算和释放接口，供一件代发等模块接入。审核、账户更新、流水、冻结记录和幂等结果在 Finance 单事务内完成，文件内容仍归 File 服务。接口契约见 [客户资金账户 OpenAPI](../openapi/finance-wallet-v1.yaml)。
> 盘点日期：2026-09-09
> 当前状态：费用入池 P0 与对账结算 P1 已完成测试环境部署及真实 HTTP 全链验收；最终报告为 `baiyue-firstleg/reports/admin-test-env-acceptance-20260909103401.json`，1518/1518 通过。领导页面人工截图仍按独立验收规则执行
> 盘点范围：入库计费现状、平台后台财务原型、Admin/Client/Firstleg 当前实现
> 结论口径：本文区分“代码已实现”“原型展示”和“建议范围”；原型功能不自动成为开发范围。
## 费用来源扩展确认（2026-09-02）
- Finance 继续保持独立服务和独立数据库；业务服务只生产费用事实，不能直接写财务单据或余额。
- Firstleg 入库费用继续按客户和入仓码进入 Finance；柜级公共费用必须先按柜内真实客户与业务订单原子分摊，再逐客户进入应收应付。入仓码是可选引用：存在时必须校验真实归属，不存在时保留订单/业务单号，禁止伪造入仓码。
- Lastleg 的海外入仓、海外采购、本土卡车、本土散板和海外仓服务费使用统一版本化来源。审核通过、调整和作废同事务写海外 Outbox，通过 Event Bridge 向国内 Finance 投递完整不可变快照；Finance 不跨海外数据库回查。
- Finance 以 `sourceSystem + sourceType + sourceFeeId + sourceVersion` 唯一入池；重复事件幂等，同版本不同哈希拒绝，已进入有效账单或结算单的来源禁止替换/作废。
- 海外仓服务费只强制客户、海外仓和业务编号；入仓记录/入仓码按真实业务选填，月租、仓租等无入仓码费用仍可入池。
当前实现包含柜级分摊 API/Admin 录入、海外费用来源 API、跨区事件、Finance 通用消费入口及数据库脚本，并已完成测试环境数据库和真实 HTTP 验收。页面人工截图仍按独立验收规则执行。
## 历史测试环境部署状态（2026-08-12，已解除）
当时的 Finance 全链路测试环境实跑报告为 `baiyue-firstleg/reports/finance-full-acceptance-20260812.json`：共 430 项，411 项通过，19 项失败，当时结论为 `DEPLOYMENT_BLOCKED`。这些阻断已在后续版本解除，当前结论以 P0/P1 闭环文档和 2026-09-09 最终报告为准。
当前主要部署阻断：
- Gateway 健康，但 `/finance-service/v3/api-docs` 返回 HTTP 503，测试环境 Finance 服务不可用。
- `baiyue_finance` 当前仅部署旧 F0 schema；`fin_bill`、`fin_fee_source` 等存量表无业务数据，G3/G4 新表未部署。因此对账、应收应付、凭证及结算写链无法完成真实 HTTP 验收。
- 本地脚本和模块契约测试通过只证明验收程序契约成立，不代表测试环境 Finance 服务或数据库迁移已经部署成功。
报告生成后，产品进一步确认现有 ACTIVE 往来单位均可作为应付结算候选，不要求 `SUPPLIER` 类型。曾为诊断临时新增的 `FIN-FULL-SUP-20260812` 及其类型映射已从测试库完整删除；全量脚本和 Admin 页面均已改为复用现有 ACTIVE 往来单位。原报告中的“未找到 ACTIVE SUPPLIER”仅反映当时脚本的旧过滤条件，不能倒推为测试环境已通过。当前仍需完成墨家测量实重同步修复、Finance 服务部署和 G3/G4 schema 迁移，再重跑同一三模块链路形成新报告。
产品/业务逐项确认请使用：[财务管理产品确认表](../财务管理产品确认表.md)。
产品回传后的差异和剩余门禁见：[财务管理产品确认版差异与剩余待确认](../财务管理产品确认版差异与剩余待确认.md)。
技术边界已确认：[财务服务边界设计](../财务服务边界设计.md)。Finance 采用独立服务和独立数据库，Firstleg 仅提供业务费用来源。
开发前总控门禁与 F0/F1 任务清单：[财务开工门禁与F0-F1任务清单](../财务开工门禁与F0-F1任务清单.md)。
订单与客户领导验收唯一范围入口：[财务核心五页产品与接口验收契约](../财务核心五页产品与接口验收契约.md)。
订单与客户 11 个 P0 操作、状态机与验收用例：[财务核心 P0 操作契约与验收用例](../财务核心P0操作契约与验收用例.md)。
订单与客户实现与 Admin 接入证据（不反向修改目标契约）：[财务核心 P0 实现证据矩阵](../财务核心P0实现证据矩阵.md)。
文档优先级：五页验收契约和本轮产品确认 > 五页目标 OpenAPI > 既有人工 F1 契约/门禁 > 领域模型、历史全量规划和迁移文档。旧文档用于追溯，不得据此把钱包、充值、发票、费用分析或利润表重新纳入订单与客户。
旧文档降级规则：
| 文档/章节 | 当前用途 | 订单与客户实施约束 |
|---|---|---|
| 本文第六节起的“历史全量规划” | 保存早期盘点和演进背景 | 与五页契约冲突时全部失效，不作为菜单、路由、字段或接口依据 |
| `财务领域模型与跨服务契约.md` | 历史合并稿 | 已被数据字典和跨服务契约替代 |
| `财务服务边界设计.md`、`财务领域模型与数据字典.md` | 服务边界和长期模型参考 | 其中钱包、充值、发票、费用分析、利润模型不属于订单与客户 |
| `财务历史迁移与上线验收方案.md`、`财务F0实施任务拆分.md` | 历史迁移、底座任务追溯 | 不得覆盖五页范围和当前实现状态 |
详细设计材料：
- [海外仓费用统一接入财务评审方案](../海外仓费用统一接入财务评审方案.md)
- [海外仓费用统一接入阶段0技术契约](../海外仓费用统一接入阶段0技术契约.md)
- [财务业务操作流程图](../财务全链路流程图.md)
- [财务业务全流程总览图（PNG）](../财务业务全流程总览图.png)
- [财务来源接入现状](../财务来源接入现状.md)
- [财务领域模型与数据字典](../财务领域模型与数据字典.md)
- [Firstleg-Finance跨服务契约](../Firstleg-Finance跨服务契约.md)
- [F1 人工账单、收款、成本接口契约](../F1人工账单收款成本接口契约.md)
- [F1 人工财务契约审查与门禁](../F1人工财务契约审查与门禁.md)
- [财务核心五页产品与接口验收契约](../财务核心五页产品与接口验收契约.md)
- [财务核心五页 OpenAPI](../openapi/finance-core-five-pages-v1.yaml)
- [财务核心 P0 操作契约与验收用例](../财务核心P0操作契约与验收用例.md)
- [财务核心 P0 实现证据矩阵](../财务核心P0实现证据矩阵.md)
- [财务历史迁移与上线验收方案](../财务历史迁移与上线验收方案.md)
- [财务F0实施任务拆分](../财务F0实施任务拆分.md)
历史合并稿：[财务领域模型与跨服务契约](../财务领域模型与跨服务契约.md) 已由“领域模型与数据字典”和“Firstleg-Finance 跨服务契约”两份文档替代，不作为后续实施依据。
## 一、结论
当前首期采用人工简化方案：平台财务登记收付款并上传凭证；客户可查询并确认本人已出账对账单。首期不做银行自动对账、自动核销任务、复杂审批、客户钱包、发票、供应商在线结算、汇率、月结或总账。
当前已经实现业务计费闭环，并已落地 Finance 独立服务/数据库、人工账单/收款/成本基础接口、平台与客户权限种子、Admin 财务页面和 Client 只读账单页面。当前不是“整体未开发”，而是已进入专项修复和契约收敛阶段。
已具备的基础链路：
```text
测量/称重
-> 测量审核
-> 计费规则匹配
-> 费用试算与快照
-> 发布对客费用
-> 客户查看并确认已出账对账单
-> 完成入库
```
当前 F1 已具备的实现链路：
```text
平台财务创建草稿账单
-> 出账冻结
-> 人工登记收款
-> 一笔收款分配多张账单
-> 部分收款/收清状态更新
-> 客户只读查询
```
此前基础链路已完成 Firstleg 真实柜次体积快照、客户归属、成本凭证校验、revision、双权限上传、费用来源事件/Relay/快照、Finance `fin_fee_source` 消费写入和完整幂等。在此基础上，固定五页所需的 11 个目标 operation、Admin 页面动作与 IAM 权限目录现已闭环，G1-G4 本地门禁均为 `PASS`；最终直接证据包括 Finance 聚合 82/82、G3 16/16、G4 18/18、收款及 AR 同步 12/12、IAM 168/168、Admin 财务专项 60/60、Admin 全量 654/654 及 Admin 构建通过。真实 MySQL 执行、测试环境 HTTP 冒烟和领导页面验收仍需单独完成，未经当前对话明确授权不触发 Jenkins。
订单与客户范围已重新冻结为原型 5 页：客户账户、客户应收应付、客户对账单、结算单应收、结算单应付。费用分析、利润表、发票和钱包不做，也不保留菜单、路由或假按钮。客户账户改为账单、收款和应收应付来源派生的财务往来总览，不做充值/预收。
## 二、事实来源与边界
本次按以下资料核对：
1. 入库测量与计费需求文档明确入库测量与计费只做头程计费，不自动形成应收、应付、对账单、收付款、核销、发票、利润或总账。
2. 平台后台原型提供财务管理全量参考，但其中数据和交互主要由单页 HTML 内的静态数据及前端脚本驱动。
3. 当前代码用于证明“已经实现什么”，不反向扩大产品范围。
主要依据：
- `docs/入库测量与计费/入库测量与计费计费财务需求确认表.md`
- `docs/入库测量与计费/入库测量与计费V2需求确认清单.md`
- `docs/入库测量与计费/入库测量与计费需求优化版-v2-测量计费入库主流程.md`
- `docs/悦/货代SAAS平台后台/货代SaaS平台原型.html`
- `apps/admin-web/src/modules/inbounds/`
- `apps/admin-web/src/modules/fee-items/`
- `apps/admin-web/src/prototype/modules/finance/`
- `apps/client-web/src/modules/first-leg/`
- `apps/client-web/src/modules/finance/`
- `baiyue-firstleg/firstleg/`
## 三、当前已经具备什么
### 3.1 可作为财务上游的业务数据
| 能力 | 当前状态 | 可复用价值 | 不能代表什么 |
|---|---|---|---|
| 实测重量、体积、计费量 | 已实现 | 作为费用计算依据和业务快照 | 不是财务凭证 |
| 客户计费规则、船司价格 | 已实现 | 产生确定的对客头程价格 | 船司价格不等于供应商应付 |
| 费用试算、确认、发布 | 已实现 | 形成版本化对客费用快照 | 不等于应收单或账单 |
| 费用调整 | 已实现 | 已发布费用调整生成新版本并留原因 | 尚未定义已出账或已核销后的调整方式 |
| 客户侧费用与账单查看 | 已实现 | 客户能看到入库及已发布费用结果，并在线确认本人已出账且待确认的对账单 | 客户不能修改金额、在线提出争议或登记收款/核销 |
| 费用项目主数据 | 已实现 | 支持费用编码、分类、国内/国际、提货/仓库应收应付属性 | 费用项目属性不自动生成财务记录 |
| 入库费用明细 | 后端已实现 | 支持人工新增、编辑、删除、审核、自动发布的入库运费明细 | 尚无跨入库单财务台账和结算生命周期 |
| 权限与审计基础 | 部分具备 | 费用明细查看、编辑、删除、审核已有权限和业务审计 | 财务制单、复核、收款、核销、反核销权限尚未定义 |
### 3.2 当前费用明细的真实边界
Firstleg 已有 `fl_inbound_fee_detail`，包含：
- 入库单、费用项目、方向、业务发生日、币种、单价、金额；
- 重量、体积、计费量等业务快照；
- 审核状态、审核人、驳回原因；
- 发布状态、发布时间；审核通过后自动发布并成为结算候选；
- 自动计费来源的费用单号和版本。
但当前仍存在以下断点：
- 自动发布链路只生成 `RECEIVABLE` 对客运费。
- 人工 `PAYABLE` 明细使用 Warehouse `supplierId/supplierName` 快照；费用项目 `supplierCategory` 可空，空表示任意启用供应商，非空严格匹配。
- 人工明细采用编辑、提交、审核、调整、作废闭环；审核通过后自动发布，不再存在“是否结算”开关。
- 已发布应收明细只能按单个入库单查询，未形成按客户、币种、账期聚合的财务台账。
- 没有冻结、出账、核销后的费用变更规则，无法保证历史账单金额稳定。
## 四、原型中有什么
平台后台原型的财务菜单包含以下能力：
| 原型模块 | 原型展示的主要能力 | 当前代码状态 | 是否能直接纳入首期 |
|---|---|---|---|
| 客户账户 | 原型为余额、冻结、可用余额和充值流水 | 未实现 | 订单与客户保留汇总/详情/流水结构，但改为未收、待出账、本期已收等派生指标；删除充值/钱包能力 |
| 客户应收应付 | 费用明细、编辑审核、按截止时间或勾选生成账单 | 已接入真实费用来源和编辑审核闭环 | 作为应收应付费用池 |
| 客户对账单 | 账期、汇率、应收、已收、结清、明细和支付历史 | 未实现 | 可作为应收闭环核心，但汇率和开票先暂缓 |
| 结算单应收 | 应收、已收、余额、到期日、审批、部分收款 | 未实现 | 可合并进账单/应收单，避免首期重复建模 |
| 结算单应付 | 供应商应付、已付、余额、审批、部分付款、利润 | 未实现；上游成本来源不完整 | 订单与客户纳入，但删除利润字段/按钮；必须先补真实供应商应付来源和付款凭证链路 |
| 费用分析 | 内外部费用对比、趋势和明细 | 未实现 | 订单与客户明确不做，不进菜单/路由 |
| 利润表 | 按客户、货柜、单票、月份统计收入、成本、利润率 | 未实现 | 订单与客户明确不做，不进菜单/路由 |
原型还出现了发票抬头、开票日期、汇率、支付方式、收付款凭证号等字段。它们只说明未来可能需要，不代表当前产品已经确认税务、外币折算、资金或发票边界。
当前 Admin 已有正式财务路由、账单详情/草稿修改/出账/调整/作废、人工收款和成本页面及真实凭证上传调用，Client 已有正式只读账单页面。后端已改为根据 `containerId` 调 Firstleg 体积快照并完成成本凭证校验，但 Admin 仍强制人工填写并提交柜内订单体积，且未接客户账期和 revision，因此前端创建闭环尚未与最终契约对齐。
## 五、当前修复中缺口
| 序号 | 断点 | 直接影响 |
|---|---|---|
| 1 | 五页读接口、平台/客户固定 DTO 和追踪响应已实现 | Finance 35/35 BUILD SUCCESS；本轮使用现有 Surefire 报告核对，不重新执行 Maven |
| 2 | 收款和成本均已校验凭证，但 `fileClient == null` 时仍 fail-open | File 客户端缺失时可能绕过凭证校验 |
| 3 | 后端已使用 Firstleg 真实体积快照，Admin 仍要求人工填写并提交体积 | 页面与最终请求契约不一致，产生无效输入和误导 |
| 4 | 幂等已有 SHA-256 与同参重放，但未覆盖完整规范化请求，缺 PROCESSING 恢复测试 | 仍可能误判同参或无法恢复中间态 |
| 5 | 客户账单已过滤可见状态，收款列表仍暴露平台字段且未按可见账单过滤 | 客户只读边界仍不完整 |
| 6 | Admin 已接账单动作，但未接客户账期、revision，整柜仍人工填体积 | 平台财务页面仍非完整闭环 |
| 7 | 业务错误码仍以通用错误和中文消息为主 | 前端无法稳定区分版本、幂等、凭证和归属错误 |
| 8 | revision 后端查询已落地，Admin 尚未接展示 | 调整历史仍不能在产品页面核对 |
## 六、全量财务规划与交付顺序
### 6.1 历史全量规划（不作为订单与客户范围）
以下内容只保留为历史分析。若与《财务核心五页产品与接口验收契约》冲突，以五页契约为准。
| 目标域 | 业务结果 | 主要来源 | 不能提前假定的口径 |
|---|---|---|---|
| 客户账户 | 客户财务往来派生汇总、详情和流水 | 账单、收款和应收应付来源 | 订单与客户不建设钱包、充值、预收或自动扣款 |
| 客户应收 | 客户欠款、到期、逾期、结清 | 已发布对客费用、补差/冲销 | 收入确认节点和账期规则 |
| 客户应付 | 客户代垫或返还类应付款（如确有业务） | 业务费用或人工单据 | 产品是否真的存在“平台向客户付款”的场景 |
| 客户对账单 | 期间内费用汇总、明细、平台出账和客户确认 | 应收/应付费用池 | 一张账单是否允许混合方向、混合币种 |
| 结算单应收 | 可审批、可收款、可核销的应收结算单 | 已确认客户账单 | 与客户对账单是一对一还是一对多 |
| 结算单应付 | 供应商成本、付款、余额和结清 | 供应商费用、运力/仓储/报关成本 | 成本确认、供应商账期、审批和付款方式 |
| 收付款与核销 | 到账/付款凭证，部分结算、反核销 | 银行流水或人工登记 | 是否首期接银行流水，是否允许一笔多单核销 |
| 发票 | 开票申请、开具、红冲、作废和关联 | 已确认应收/收款 | 税率、含税/未税、开票主体、外部平台 |
| 费用分析 | 历史规划，订单与客户不做 | 应收应付台账 | 不进入订单与客户菜单、路由和验收 |
| 利润 | 客户/单票/柜次/月度收入、成本、利润率 | 应收收入 + 应付成本 + 分摊 | 汇率、成本分摊、收入成本确认时间 |
### 6.2 分阶段交付顺序
全量目标建议拆成五个可验收阶段：
| 阶段 | 交付范围 | 关键闭环 | 前置依赖 |
|---|---|---|---|
| F0 财务底座 | 独立 Finance 服务/数据库、财务主体、客户/供应商往来单位、币种、费用科目、期间、权限、审计、幂等、金额精度 | 所有后续对象使用同一基础口径 | 服务边界已技术确认；产品确认主体、币种、权限和编码 |
| F1 应收与客户对账 | 应收费用池、平台出账、客户确认、结算单应收、收款登记、核销、反核销 | 费用 → 账单 → 客户确认 → 应收 → 收款 → 结清 | 当前已发布对客费用来源 |
| F2 应付与供应商结算 | 成本费用池、供应商账单、结算单应付、付款登记、付款核销、应付调整 | 成本 → 供应商账单 → 应付 → 付款 → 结清 | 供应商主数据和真实成本来源 |
| F3 客户账户与发票 | 订单与客户只做派生客户账户总览；发票暂缓 | 账户只读聚合，不维护资金余额 | 发票不属于订单与客户 |
| F4 分析与利润 | 订单与客户不做 | 不建设菜单、路由或假入口 | 后续重新立项 |
阶段之间可以并行做页面原型和契约设计，但生产数据链路必须按 F0 → F1/F2 → F3 → F4 验收。F4 不能用原型静态数字先行替代真实台账。
### 6.3 F1 最小财务闭环
F1 先处理当前已经有可靠来源的对客头程费用：
```text
已审核并发布的应收费用明细
-> 进入待对账费用池
-> 按客户 + 币种 + 账期生成对账单
-> 内部复核
-> 客户在线确认（异议仍线下反馈）
-> 平台财务出账后形成应收
-> 登记实际收款
-> 将收款核销到应收
-> 全额核销后结清
-> 错误时按权限反核销并留审计
```
F1 建议页面：
1. 应收费用池：查询、编辑、提交、审核、调整、作废；审核通过自动进入结算候选。
2. 客户对账单：生成、明细、内部复核、发送、关闭；平台财务可重开或调整。
3. 应收与收款：应收余额、到期日、收款登记、附件/凭证号、部分核销。
4. 核销记录：每笔收款对应哪些应收、核销金额、剩余余额、反核销历史。
5. 客户侧账单：查看明细、收款与未结余额，并在线确认本人已出账账单；不做在线争议。
以下历史排除清单已被 2026-08-11 的五页范围取代。结算单应付现在属于订单与客户；其余未确认能力继续排除：
- 供应商在线确认和自动付款（应付结算单与人工付款属于订单与客户）；
- 客户预充值、余额冻结和自动扣款；
- 发票申请、开票和税务接口；
- 多币种折算与汇兑损益；
- 利润表、利润率和总账；
- 银行流水自动认领；
- 复杂费用分摊和会计凭证。
### 6.4 全量阶段的范围门禁
| 范围 | 开工门禁 |
|---|---|
| 客户账户 | 已确认只做派生财务往来总览；禁止充值、冻结/解冻、退款、自动扣款和可写余额 |
| 客户应收应付 | 明确客户作为付款方还是收款方；没有真实业务场景的方向不建菜单和数据 |
| 供应商应付 | 必须有供应商主数据、成本来源凭证、审批人、付款方式和付款责任主体 |
| 收付款核销 | 明确人工登记与银行流水的边界；收款、付款、核销、反核销分开授权 |
| 发票 | 明确开票主体、税率、含税/未税、红冲/作废和外部开票平台；未确认前只保留接口扩展位 |
| 费用分析/利润 | 先冻结汇率、收入成本确认日、成本分摊和跨币种折算；报表必须能钻取到原始费用和结算单 |
## 七、已确认的产品结论（历史问题关闭结果）
下表原为产品问题清单，现按本轮确认结果保留。不得再把这些条目解释为待产品确认；实现仍受真实费用来源链路和专项技术门禁约束。
| 编号 | 待确认问题 | 建议默认值 |
|---|---|---|
| F1 | 订单与客户领导验收范围 | 固定为客户账户、客户应收应付、客户对账单、结算单应收、结算单应付；费用分析和利润表不做 |
| F2 | 账单生成维度 | 客户 + 币种 + 账期；不同币种不合并 |
| F3 | 哪些费用可以进入账单 | `APPROVED + PUBLISHED + AVAILABLE + CNY + amount>0` 且未出账；无人工结算开关 |
| F4 | 当前已发布头程费用是否自动进入待对账池 | 是，但仍由财务选择并生成账单 |
| F5 | 账单生成后上游费用能否直接调整 | 不能；应走补差单/冲销单并保留原账单 |
| F6 | 客户是否需要在线确认和提出争议 | 客户在线确认本人已出账对账单；确认状态独立于主状态，在线争议暂不做 |
| F7 | 是否需要内部复核 | 建议制单与复核权限分离，首期允许同人需业务明确 |
| F8 | 收付款是人工登记还是接银行流水 | F1/F2 先人工登记，F3 再接银行流水；必须保存到账日/付款日、方式、凭证号和附件 |
| F9 | 一笔收款能否核销多张应收，一张应收能否被多次收款 | 两者都允许，禁止累计核销超过余额 |
| F10 | 反核销和作废权限 | 独立高风险权限，必须填写原因并完整审计 |
| F11 | 到期日如何计算 | 由客户结算条款或账单确认日 + 账期天数计算 |
| F12 | 历史已发布费用如何迁移 | 仅迁移满足入池条件且尚未形成线下已结算事实的费用 |
## 八、建议状态模型
状态应按对象拆分，避免把费用、账单和资金状态混为一个字段。
### 8.1 费用明细
```text
DRAFT -> PENDING -> APPROVED -> PUBLISHED -> BILLED
-> REJECTED
PUBLISHED/BILLED -> ADJUSTED（通过补差或冲销，不覆盖原记录）
```
### 8.2 对账单
```text
DRAFT -> REVIEWED -> SENT -> CONFIRMED -> CLOSED
-> DISPUTED -> DRAFT/VOIDED
```
### 8.3 应收与核销
```text
应收：OPEN -> PARTIALLY_SETTLED -> SETTLED
-> OVERDUE
收款：DRAFT -> CONFIRMED -> PARTIALLY_ALLOCATED -> FULLY_ALLOCATED
核销：ACTIVE -> REVERSED
```
“收款已登记”与“应收已核销”必须分开。只有核销完成后，对应应收余额才减少；反核销恢复余额，但不得删除原记录。
## 九、关键数据与约束建议
首期至少需要以下独立对象，不能只在现有费用明细表上继续追加字段：
| 对象 | 核心职责 |
|---|---|
| 财务费用来源 | 引用不可变的业务费用版本，保存来源服务、来源单据、来源版本和来源幂等键 |
| 对账单 | 客户、币种、账期、状态、版本、金额合计和确认信息 |
| 对账单明细 | 关联费用来源并保存出账时快照；一条有效费用只能进入一张有效账单 |
| 应收单 | 应收金额、已核销金额、余额、到期日和状态 |
| 收款单 | 到账金额、币种、日期、方式、凭证号、附件和登记/确认人 |
| 核销记录 | 收款单、应收单、核销金额、操作人、时间和幂等键 |
| 反核销记录 | 原核销记录、原因、审批/操作人和恢复金额 |
| 财务操作日志 | 对账、确认、争议、收款、核销、反核销和作废的完整历史 |
必须具备的约束：
- 金额统一使用定点小数，币种使用 ISO 三位码；不同币种首期禁止合并和直接核销。
- 长整型 ID 按字符串跨前端传输。
- 所有写操作带幂等键和乐观锁版本。
- 同一费用来源版本只能进入一个未作废的账单明细。
- 核销累计金额不得超过收款可用余额或应收未结余额。
- 出账、核销后禁止物理删除；调整、作废和反核销必须保留原记录。
- 客户隔离由服务端登录上下文保证；平台员工操作目标客户时必须显式选择客户并校验权限。
- 客户不可看到供应商成本、内部备注、审核意见和平台凭证附件。
## 十、原型需要修正或裁剪的地方
后续做正式页面时，不建议直接照搬原型：
1. “客户应收应付”把客户应收和供应商应付混在同一概念下，应按交易对手和职责拆分。
2. “客户对账单”和“结算单应收”字段大量重复，首期应定义清晰的一对一或一对多关系，避免两套金额状态并存。
3. 原型中的“支付历史”在应收场景应统一使用“收款/核销记录”，避免收付款术语混用。
4. 原型允许直接登记部分收付款，但没有展示确认、撤销、反核销、超额校验和并发冲突。
5. 客户账户充值与应收结算不是同一个闭环，不能用余额字段代替收款和核销台账。
6. 利润表直接展示结果，但没有收入确认、成本来源、外币折算和分摊规则，当前结果不可审计。
7. 所有正式业务表格的“操作”列应放在第一列；原型部分旧页面需要按仓库统一规则调整。
## 十一、完成标准
只有同时满足以下条件，才可以称为“客户应收财务闭环”：
- 每笔应收都能追溯到已审核、已发布且不可变的费用来源版本；
- 能生成、复核、发送并确认客户对账单；
- 能形成有到期日和余额的应收；
- 支持一次或多次收款及多对多核销；
- 支持部分核销、全额结清、反核销和作废；
- 所有金额变化均可审计，重复提交和并发操作不会多记账；
- Admin 与 Client 对同一账单、应收余额和状态的展示一致；
- 越权、跨客户、不同币种、超额核销、已出账费用调整等异常路径有服务端硬校验；
- 使用真实 API 完成至少一条“费用 -> 对账 -> 应收 -> 收款 -> 核销 -> 结清”回归，并验证反核销恢复余额。
## 十二、下一步文档工作
在写代码前建议依次完成：
1. 由产品/业务填写 F1-F12，冻结首期范围。
2. 形成《客户应收闭环需求确认表》，明确页面、角色、状态和异常处理。
3. 使用《财务管理产品确认表》完成 S1-S8、F0-F4 的产品确认。
4. 服务边界、领域模型、跨服务契约及 F0/F1 基础实现已经形成；当前按《F1人工财务契约审查与门禁》完成专项修复和测试放行，不再等待产品填写 XLSX 或重复讨论是否拆服务。
5. 形成《客户应收接口与权限契约》，包括错误码、幂等、数据范围和审计事件。
6. 形成《历史费用迁移与上线方案》，避免已有线下结算数据被重复出账。
财务管理/财务对账结算P1闭环.md
+8
View File
@@ -84,3 +84,11 @@ P1 没有发现 Finance 单据状态机或金额处理缺陷。发现并修正
- 自动费用造数只选择已配置内部编号且被 ACTIVE 价格簿覆盖的 FBA 仓；测试环境 `ABE3` 已通过正式仓库接口补齐内部编号。
这些修正只增强验收数据和证据，不绕过生产权限、状态机、幂等、服务边界或数据库约束。
## 客户资金账户
本节承接原财务 README 的已确认资金账户规则，覆盖历史“五页范围”中排除钱包或充值的旧结论；与对账单派生的往来账户汇总分别维护。
首批固定为 CNY。平台设置授信时必须同时设置晚于今天的到期日，最远日期不设上限；到期日当天仍有效。有效期内消费先扣实际可用资金，不足部分累计为已用授信；次日授信失效时，已用授信自动并入实际余额并允许形成负数，负数实际余额会阻止客户提交新订单。充值先归还已用授信或负余额，剩余金额才形成正数资金。
客户选择固定或自定义金额，查看后台配置的平台统一静态收款码，付款后上传 JPG/PNG 截图形成待审核申请。平台在客户账户明细顶部审核或驳回，也可手工充值、扣款和设置客户限时授信；每次变动写不可变账户流水。新账户默认授信为 `0.00`，只有平台明确设置额度与有效期后才启用。Finance 还提供仅服务令牌可访问、按业务类型和业务单号幂等的冻结、结算和释放接口，供一件代发等模块接入。审核、账户更新、流水、冻结记录和幂等结果在 Finance 单事务内完成，文件内容仍归 File 服务。接口契约见 [客户资金账户 OpenAPI](openapi/finance-wallet-v1.yaml)。