docs/头程到尾程AI流程优化上下文包.md

# 头程到尾程 AI 流程优化上下文包

> **规则基线声明（2026-09-24）**：本文中的旧状态表和阶段合同可能保留历史口径，不能覆盖当前流程。当前分析必须先采用 [头程到尾程流程节点梳理（重构版）](头程到尾程流程节点梳理.md) 和 [报关资料与船期价格接入梳理](国内货柜履约/报关资料与船期价格接入梳理.md)：`LOADED` 后报关线、送港线并行，客户逐轮确认后整柜正式申报，送港可甩柜，实际开船后才进入海运节点。

> 用途：给 AI、产品、业务和技术提供同一份优化输入规范。本文不替代六阶段现状文档，也不直接改变状态机；它定义分析顺序、术语、证据、指标、输出格式和实施门禁，防止 AI 只根据局部页面提出脱离业务事实的建议。

## 1. 第二轮完整性审计结论

现有材料已经覆盖 F01～F40 的操作、状态、异常和交接，但若要让 AI 持续辅助优化，还需要补齐以下横向信息：

| 缺口 | 为什么重要 | 本文补充方式 |
|---|---|---|
| 文档读取优先级 | AI 容易拿历史规划覆盖当前实现 | 固定事实优先级和最小上下文 |
| 统一术语和对象关系 | “柜次、订舱、拖车、托盘”等容易混淆 | 建立术语与禁止混用表 |
| 流程变体矩阵 | 单一主链会漏掉一件代发、私人地址、异常退回 | 明确变体和分叉点 |
| 跨端 RACI | 仅写角色仍不清楚谁负责、谁批准、谁被通知 | 建立阶段级责任矩阵 |
| 输入输出合同 | AI 容易建议重复录入或跨服务改权威数据 | 固定六阶段交接合同 |
| 阻断原因分类 | “不能继续”若无分类，无法做任务卡和统计 | 定义 blocker 分类和恢复动作 |
| 指标口径与基线 | 没有分母、起止点就无法验证“更好用” | 建立指标字典和基线采集表 |
| 问题证据格式 | 主观反馈无法排序，也无法复现 | 统一问题观察记录 |
| 优化卡模板 | 建议容易停留在“做个工作台” | 强制写现状、方案、数据、验收和回滚 |
| AI 输出约束 | AI 可能新建平行状态机、引入兼容层或越权自动化 | 明确禁止项和完成定义 |

## 2. AI 读取顺序

每次只读取与目标阶段相关的最小材料，按以下顺序判断事实：

1. 当前对话中的业务确认；
2. 对应阶段文档；
3. [现状流程全景清单](头程下单到尾程出库现状流程全景清单.md)；
4. 目标应用、服务最近的 `AGENTS.md`；
5. 当前 Controller、DTO、Service、页面和 OpenAPI；
6. 当前阶段设计/审核记录；
7. 原型；
8. 历史规划和旧验收记录。

优化分析的默认入口：

- 总览：[分阶段流程目录](头程到尾程分阶段流程/README.md)
- 操作：[全流程操作手册](头程下单到尾程出库全流程操作手册.md)
- 现状：[现状流程全景清单](头程下单到尾程出库现状流程全景清单.md)
- 方案：[易用性与数据流转优化方案](头程下单到尾程出库流程易用性与数据流转优化方案.md)
- 约束：本文

出现冲突时必须明确写出“来源 A、来源 B、采用哪一项及原因”，不能静默拼接两套口径。

## 3. 统一术语与禁止混用

| 术语 | 正确定义 | 不得混用为 |
|---|---|---|
| 订单号 `orderNo` | 客户交易订单业务号 | 入仓码、入库单号 |
| 入仓码 `inboundCode` | 从头程提交到海外尾程持续使用的稳定关联码 | 内部 `inboundId`、计划号 |
| 柜次号 `cabinetNo` | 平台模拟柜/柜次业务编号 | 真实集装箱号 |
| 真实柜号 `containerNo` | 船司/码头识别的物理集装箱号 | 模拟柜 ID |
| 海运订舱 | 船司运输、提单和柜型需求聚合 | 柜次、国内拖车 |
| 国内订舱级拖车 | 一个已放舱订舱的国内提柜/送柜任务 | 目的港码头拖车、海外配送排车 |
| 目的港码头拖车 | 海外清关后提柜、到仓和还空链路 | 海外配送排车 |
| 海外配送排车 | 海外库存出库后送往 FBA/私人地址的车辆任务 | 目的港提柜 |
| 头程普通托盘码 | 预装/装柜阶段按真实柜号与 FBA 仓生成 | 一件代发 `DP` 托盘 |
| 一件代发 `DP` 托盘 | 国内测量后逐箱 SKU 清点并封托的来源托盘 | 海外仓随意重打托盘 |
| 海外实物托盘 | Warehouse Overseas 管理的公共物理资源 | 库存客户归属 |
| `LOADED` | 国内实际装柜完成 | 国内实际离仓、海外入仓 |
| `DEPARTED_WAREHOUSE` | 柜子实际离开国内仓 | 船已开航 |
| `PICKUP_READY` | 目的港清关完成、可提柜 | 已提柜、已到海外仓 |
| `INBOUND_COMPLETED` | 海外实收和库存入账完成 | 已出库、已派送 |
| `OUTBOUNDED` | 对应出库单已完成出库 | 客户/目的仓已签收 |
| `DELIVERED` | 目的派送签收完成 | 仅发车或仅上传 BOL |

用户页面只展示业务号；内部 ID 只能出现在接口关联或可折叠诊断信息。

## 4. 必须覆盖的流程变体

AI 分析任何阶段时，至少检查下列适用变体，不能只优化最顺畅的一条 FBA 散货主链：

| 维度 | 变体 | 关键差异 |
|---|---|---|
| 下单方式 | 单票、批量导入 | 批量需预览、逐行错误和重试 |
| 国内交货 | 自送、快递、平台提货 | 平台提货是否有独立派车/回执仍需业务确认 |
| 目的类型 | FBA、OVERSEAS、PRIVATE | 目的仓、逐箱事实、私人地址和派送拆分不同 |
| 履约类型 | 普通、一件代发 | 一件代发国内先清点封托，海外必须沿用来源托盘 |
| 装柜 | 整票、部分装载、一票多柜、多票拼柜 | 分片、数量守恒和 Order 最终完成条件不同 |
| 海外收货 | FBA bulk、OVERSEAS carton、dropship pallet | 批量箱数、逐箱、整托三种操作不可混用 |
| 海外托盘 | 独立托盘、同目的仓合托 | 合托不改变客户和入仓单归属 |
| 后续服务 | 正常排车、换标、转运、废弃、退货出库 | 库存锁、资格和子状态不同 |
| 派送结果 | 正常签收、拒收/取消、异常退回 | 退回必须恢复原出库来源库存 |
| 系统结果 | 同步成功、异步处理中、可重试失败、永久失败 | 页面回执和人工动作不同 |

## 5. 六阶段 RACI

缩写：R=实际执行，A=最终负责/批准，C=协作或复核，I=需要知会。

| 阶段 | 企业客户 | 平台订单/运营 | 国内仓/PDA | 海外运营 | 海外仓/PDA | 财务/客服 | 系统 |
|---|---|---|---|---|---|---|---|
| 1 下单审核 | R | A/R | I | I | I | C | C |
| 2 测量计费组托 | C | A/C | R | I | I | C | R |
| 3 国内装柜出仓 | C | A/R | R | I | I | C | R |
| 4 海运与尾程计划 | I | R/C | I | A/R | I | I | R |
| 5 海外入仓与库内 | C | I | I | A/C | R | C | R |
| 6 排车出库派送 | I/C | I | I | A/R | R | R/C | R |

RACI 是评审起点，不是权限契约。具体按钮仍由服务端权限码、身份范围和当前状态决定。优化建议若改变 A/R，必须列为业务决策，不能由页面设计默认改变职责。

## 6. 阶段输入输出合同

| 阶段 | 最小输入 | 成功输出 | 下一阶段硬前置 |
|---|---|---|---|
| 1 | 客户身份、仓库/渠道/目的地、申报 | `APPROVED`、固定入仓码、正式国内入库单 | `WAIT_MEASURE` |
| 2 | 正式入库单、稳定箱码、实到货物 | 审核实测；普通/组托完成后 `WAIT_SPLIT` | 无 HOLD、数量证据完整 |
| 3 | `WAIT_SPLIT` 箱/整托、柜型与运输资料 | `LOADED`、报关放行、实际国内离仓 | `DEPARTED_WAREHOUSE` 和最终实装快照 |
| 4 | 真实柜、订舱、离仓、装柜完成事件 | 尾程订单、`FIRST_LEG` 在途、入仓计划和资源 | `INBOUND_PLANNED`、`PICKUP_READY` |
| 5 | 可收柜、每票计划、真实资源 | `INBOUND_COMPLETED`、库存余额/位置/流水 | 可用库存且无对应阻断 |
| 6 | 可用库存、目的地、车辆/服务资料 | 签收、国内 `DELIVERED`、Order `COMPLETED` | 所有有效入库单均完成 |

任何优化都必须说明是否改变合同。只改页面布局时不得暗中改变状态推进、数据所有者或阶段完成判定。

## 7. 阻断原因分类

建议服务端统一返回：`blockerCode/category/message/ownerRole/recoveryAction/deepLink/retryable/detectedAt`。

| 分类 | 示例 | 默认责任 | 恢复方式 |
|---|---|---|---|
| `DATA_MISSING` | 缺箱码、重量图片、真实柜号、车辆资料 | 当前录入岗位 | 补齐字段/附件 |
| `STATE_NOT_READY` | 未审核、未 `WAIT_SPLIT`、未完成拣货 | 上一步岗位 | 完成上一步，不强制跳过 |
| `PERMISSION_DENIED` | 无审核、放行、调整权限 | 管理员/负责人 | 授权或由有权人处理 |
| `VERSION_CONFLICT` | 页面版本过期 | 当前操作员 | 刷新并重新核对 |
| `RESOURCE_CONFLICT` | 托盘/库位/库存已占用 | 仓库/调度 | 换资源或释放合法锁 |
| `BUSINESS_HOLD` | 国内 HOLD、海外暂扣、换标冻结 | 发起阻断的岗位 | 按证据解除 |
| `EXTERNAL_WAIT` | 船司、清关、车队、客户确认 | 对应外部协作岗位 | 等待并记录 SLA |
| `ASYNC_PROCESSING` | Outbox 已发、Inbox 处理中 | 系统 | 自动重试，业务只读 |
| `ASYNC_RETRYABLE` | 跨区/资源确认暂时失败 | 技术/运营 | 原幂等键受控重试 |
| `ASYNC_PERMANENT` | 契约字段错误、哈希冲突 | 技术负责人 | 修正源事实后重放 |
| `IRREVERSIBLE` | 已拣货、已离仓、已签收 | 业务负责人 | 专用异常/冲正流程 |

## 8. 问题证据记录模板

任何“难用、慢、容易错”都先按下表记录，AI 才能比较优先级：

| 字段 | 填写要求 |
|---|---|
| 问题编号 | `UX-S阶段-序号`，例如 `UX-S3-004` |
| 发生阶段/F 编号 | 必填，例如阶段三/F18 |
| 角色与终端 | 谁在 Admin、Client 或 PDA 操作 |
| 触发条件 | 什么状态、什么类型、什么前置数据 |
| 当前操作路径 | 菜单、页面、按钮、扫码顺序 |
| 期望结果 | 操作员真正想完成的业务结果 |
| 实际结果 | 页面/接口/状态发生了什么 |
| 证据 | 截图、录屏、业务号、时间、错误码；不放密钥和敏感数据 |
| 频率 | 每票/每天次数或样本比例 |
| 影响 | 多花时间、返工、错账、漏单、需技术介入等 |
| 临时处理 | 当前怎么绕过去 |
| 权威事实 | 哪个服务/接口/文档决定正确行为 |

问题优先级建议使用 `影响人数 × 发生频率 × 单次损失 × 风险系数`，同时单独标记合规、资金、库存和数据隔离风险；高风险项不因发生频率低而降级。

## 9. 指标字典与基线

上线任何优化前至少采集两周基线，并固定分子、分母、起止事件：

| 指标 | 起点 | 终点 | 口径 |
|---|---|---|---|
| 订单提交耗时 | 打开新建页 | 服务端返回提交成功 | 中位数/P90，排除纯草稿停留 |
| 审核等待时长 | `SUBMITTED` | `APPROVED` | 区分人工等待和系统建单失败 |
| 测量作业时长 | 首条测量采集 | 提交审核 | 按箱数分层 |
| 测量返工率 | 已提交批次 | 被驳回批次 | 驳回批次/提交批次 |
| 待分柜等待 | 进入 `WAIT_SPLIT` | 首次有效分配 | 区分 HOLD 和无柜资源 |
| 国内装柜时长 | PDA 任务开始 | `LOADED` | 按普通箱/整托分层 |
| 离仓阻断时长 | `LOADED` | `DEPARTED_WAREHOUSE` | 按 blocker 分类拆分 |
| 跨区建单耗时 | Outbox 创建 | Lastleg 消费成功 | P50/P90/P99 和失败率 |
| 海外计划耗时 | `PENDING_ASSIGNMENT` | `INBOUND_PLANNED` | 区分人工录入与资源失败 |
| 海外收货时长 | `receiving_at` | `INBOUND_COMPLETED` | 按三种收货模式分层 |
| 排车等待时长 | 库存具备资格 | 正式排车创建 | 排除暂扣和换标冻结 |
| 拣货准确率 | PDA 扫码尝试 | 成功核平 | 错托/错箱/重复扫码分别统计 |
| 派送完成时长 | 排车发车 | 有签收资料的 `DELIVERED` | 按目的地/服务方式分层 |
| 人工介入率 | 系统异常/阻断 | 需后台或技术处理 | 分 blockerCode |
| 重复单据数 | 所有幂等重放 | 重复业务单 | 必须为 0 |

埋点只记录阶段、稳定动作码、阻断码、结果、耗时和匿名业务类型；不记录 Token、证件、客户敏感明细或文件内容。

## 10. AI 优化卡标准格式

AI 每提出一项优化，必须完整输出：

```text
优化编号：OPT-Sx-xxx
阶段/F 编号：
问题证据：
当前角色与操作路径：
根因类型：交互 / 数据重复 / 状态不可见 / 跨系统等待 / 权限 / 业务规则
建议方案：
保持不变的业务规则：
影响终端：Admin / Client / 国内 PDA / 海外 PDA
影响服务与权威数据：
新增或复用的动作码、阻断码：
同步/异步数据流：
异常和重试：
权限与客户隔离：
埋点和基线指标：
验收场景：正常 / 分支 / 异常 / 并发 / 幂等 / 越权
风险与回退：
优先级及依据：
待业务确认：
```

没有证据的建议标记为“假设待验证”，不得直接进入实施清单。

## 11. AI 分析约束

AI 不得：

1. 新建第二套可写全流程状态机；
2. 用子单状态覆盖 Order、Firstleg 或 Lastleg 主状态；
3. 让前端根据状态字符串自行推导写资格；
4. 以内部数据库 ID 作为业务人员定位方式；
5. 为即时显示做国内/海外数据库同步双写；
6. 用当前分页数据判断整柜或整票完成；
7. 把预计时间、创建时间或人工猜测写成实际发生时间；
8. 为旧字段/旧状态新增兼容分支；
9. 把按钮隐藏当作服务端权限和状态门禁；
10. 把自动重试包装成业务成功；
11. 把一件代发整托拆成普通散货流程；
12. 在没有现场证据和指标基线时承诺具体效率提升比例。

AI 应优先：复用服务端权威动作与门禁、减少重复输入、显示数据来源、提供修复深链、标准化操作回执、提高异步可观测性，并保证幂等、版本、权限和客户隔离。

## 12. 分阶段优化工作法

每个阶段按同一节奏推进：

1. 业务走查：按阶段文档真实操作一票普通流和适用分支；
2. 证据采集：记录点击、等待、重复输入、错误和人工交接；
3. 问题归类：使用 blocker 与根因分类；
4. 数据核对：标出每个字段的权威来源、快照时点和消费者；
5. 方案设计：生成优化卡，不先改状态机；
6. 业务评审：确认 RACI、不可逆点、异常和指标；
7. 技术影响分析：页面、API、DTO、权限、事件、SQL、测试和部署；
8. 小步实施：优先 P0 可见性、导航和回执，再做流程合并/自动化；
9. 验收对比：使用相同业务样本比较基线与上线后指标；
10. 文档收口：把确认结论回写阶段文档和优化方案，历史假设移出当前基线。

## 13. 优化完成定义

单项优化只有同时满足以下条件才算完成：

- 问题证据和目标指标明确；
- 正常、分支和异常流程都不丢失；
- 服务端动作、权限、状态、版本和幂等门禁有效；
- 权威数据和快照来源没有改变或已明确评审；
- Admin/Client/PDA 受影响入口同步；
- 异步结果和失败可见；
- 业务号可贯通查询且不泄露内部 ID；
- 自动化检查和人工操作验收均有证据；
- 上线后指标可与基线比较；
- 文档、索引和操作说明已更新。

## 14. 仍需业务现场补充的资料

代码和文档无法替代以下现场事实，建议按阶段收集：

- 各岗位实际人员数量、班次、交接方式和峰值单量；
- 每个页面真实录屏及操作员口述痛点；
- 常见失败/返工前十名及每月次数；
- 各阶段目标 SLA、超时升级对象和通知渠道；
- 纸质标签、称重秤、PDA、打印机和现场网络型号/限制；
- 平台提货是否存在系统外派车和签收环节；
- 报关、清关、车队邮件、客户确认等系统外协作耗时；
- 费用、库存、出库和签收发生争议时的最终责任人；
- 当前运营最常用的 Excel、群消息和线下登记表；
- 客户最常咨询的进度问题及客服当前查询路径。

这些资料未收集前，AI 可以提出候选方案，但应明确标注假设，不应直接决定自动化规则或 SLA。

## 15. 待确认问题索引

六份阶段文档共登记 66 个业务/体验评审问题。问题原文保留在各阶段“评审问题”章节，评审时不应只看优化草案：

| 阶段 | 数量 | 重点决策 |
|---|---:|---|
| 阶段一 | 6 | 平台提货是否有独立履约、平台代下单、审核驳回口径、旧入仓码、预估费用命名、混箱 SKU 责任 |
| 阶段二 | 12 | 到仓时间、提前测量、差异原因、OCR、库位警告、费用发布、HOLD、共托和 SKU 纠错 |
| 阶段三 | 12 | 占位与作业资格、推荐解释、柜号体系、柜级总控、PDA 原子提交、证据、报关和不可逆更正 |
| 阶段四 | 12 | 柜级时间线、预计/实际节点、船司异常责任、邮件送达语义、跨区诊断、资源失败和还空口径 |
| 阶段五 | 12 | 柜级资源诊断、照片对照、三种实收、合托、盘点入口、库存不可用来源和换标进度 |
| 阶段六 | 12 | 草稿锁、装载风险、转派送、三单时间线、扫码扣库存、异常退回、跨区延迟和最终完成解释 |

第一轮评审建议优先决定以下跨阶段问题：

1. 平台提货是否属于系统内完整履约链路；
2. 到仓时间是否需要独立、权威的实收登记；
3. HOLD/暂扣的责任人、审批、证据和 SLA；
4. 国内 PDA 批量提交的原子性和弱网恢复目标；
5. 排柜占位、预装确认和真实作业资格的统一文案；
6. 柜级总控台是否作为订舱、PDA、报关、离仓和跨区进度的统一入口；
7. 跨区事件失败的业务责任人、人工介入边界和重放权限；
8. 盘点正式入口和账实差异处置流程；
9. 海外扫码即扣库存的复核、撤销和异常边界；
10. 国内离仓、海外入仓、海外出库和最终签收的客户可见进度语义。

每项决定应记录：结论、负责人、确认日期、影响阶段、是否改变接口/状态/权限，以及需要更新的文档。未决定项保持“待确认”，不能由 AI 默认选择。