docs/头程到尾程分阶段流程/阶段一-客户准入与头程下单.md

# 阶段一：客户准入与头程下单

> 对应全景流程：F01～F07。  
> 阶段起点：企业已注册并可以登录。  
> 阶段终点：平台审核通过，Order 为 `APPROVED`，Firstleg 已创建正式国内入库单并沿用固定入仓码，统一主状态进入 `WAIT_MEASURE`。  
> 本文只记录现状流程；易用性问题先登记，不在本文直接改状态、接口或页面。

## 1. 阶段目标和边界

本阶段解决六件事：

1. 确认“谁可以代表哪个客户下单”；
2. 确认客户是否具备提交资格；
3. 冻结订单的国内收货仓、目的仓、渠道、地址和货物申报；
4. 生成客户可见的订单号和全局唯一入仓码；
5. 由平台审核订单并建立正式国内入库单；
6. 把权威订单和申报快照交给下一阶段的国内收货、测量和计费。

本阶段不负责：货物是否已经到仓、实际尺寸重量、费用最终确认、分柜、装柜、出仓和海外履约。

## 2. 角色、终端与权限

| 角色 | 终端 | 可做操作 | 不可做操作 |
|---|---|---|---|
| 企业成员 | Client | 按权限查看本企业订单 | 查看其他客户、平台内部备注和成本 |
| 企业订单操作员 | Client | 新建、编辑草稿、批量导入、提交、按规则取消 | 指定客户 ID、修改审核状态、维护公共仓库/渠道 |
| 企业管理员 | Client | 管理本企业成员角色，并拥有获授权的订单操作 | 配置平台后台权限、跨企业授权 |
| 平台订单运营 | Admin | 查询授权数据、审核、维护允许的申报字段 | 修改客户归属、订单号、入仓码或实测事实 |
| 平台超级管理员 | Admin | 在平台权限范围内处理全部订单 | 绕过服务端状态机、直接指定任意目标状态 |
| Order 服务 | 后端 | 保存订单、货物、快照、状态、入仓码、审计和 Outbox | 拥有测量、仓位、柜次或海外库存 |
| Firstleg 服务 | 后端 | 审核后创建国内入库单，接收版本化申报更新 | 成为订单交易状态权威 |

客户数据范围必须来自已认证身份。页面传入的 `tenantId/customerId` 不能单独形成授权。

## 3. F02 基础资料准备

### 3.1 企业和账号

- 企业注册完成，可以用中文邮箱/手机号和密码登录；
- 企业基本资料、联系信息和资质文件已填写；
- 平台已经人工审核企业资料；
- 当前成员拥有 `order:first-leg:create`、`order:first-leg:submit` 等对应权限；
- 当前客户 Finance 资金账户存在且提交时可用。

注册成功不等于具备提交资格。资料未审核通过时仍可登录、补资料和保存草稿，但提交订单必须失败关闭。

### 3.2 下单主数据

| 主数据 | 权威来源 | 下单使用方式 |
|---|---|---|
| 国内收货仓 | Warehouse | 只能选 `ACTIVE` 且具备对应收货能力的公共仓 |
| FBA/海外目的仓 | Warehouse | 按目的类型返回匹配且启用的公共仓 |
| 私人目的地址 | Order 客户地址簿 | 只能选择本客户 `PRIVATE_DESTINATION`，或保存本单临时快照 |
| 平台提货地址 | Order 客户地址簿 | `PICKUP` 时选择本客户 `PICKUP` 地址 |
| 运输渠道与价格 | Firstleg 价格/渠道目录 | 先选国内收货仓，再加载当前有效渠道 |
| 企业资格 | IAM | 提交时实时校验 |
| 资金账户 | Finance | 提交时校验实际余额不小于 0 |

下拉列表只负责选择，提交时服务端必须重新查询权威主数据。Warehouse、IAM 或 Finance 无法返回可信结果时提交失败，不回退前端旧缓存。

## 4. F01 企业资料与下单资格流程

### 4.1 客户维护企业资料

入口：Client → 公司信息。

现状操作：

1. 填写企业名称、统一社会信用代码、企业类型和注册地址等基本信息；
2. 填写联系人、手机、邮箱、微信和联系地址；
3. 上传营业执照；法人身份证为可选资料；
4. 保存后等待平台审核。

数据归属：企业和成员属于 IAM。公司联系电话/邮箱是企业资料，不等于成员登录标识；成员手机号修改走账号链路。

### 4.2 平台审核企业资料

入口：Admin → 客户管理/企业资料审核。

1. 平台查看企业资料和资质；
2. 资料正确时点击审核通过；
3. 资料不正确时联系客户修改，不在头程订单流程伪造通过；
4. 审核通过后，客户获得订单提交资格。

### 4.3 提交资格实时检查

客户打开订单页时可以看到企业资料审核提示，但页面提示不是最终门禁。点击提交时服务端重新检查：

- 当前客户身份和成员权限；
- 企业资料审核状态；
- Finance 资金账户有效响应；
- 实际余额是否小于 0；
- 仓库、渠道、目的仓和地址是否仍有效。

草稿保存不触发资金门禁，因此“能保存”不能解释成“能提交”。

## 5. F03 客户单票下单详细操作

入口：Client → 头程订单 → 创建订单。

### 5.1 选择履约类型

当前主要履约形态：

| 履约形态 | 业务含义 | 关键限制 |
|---|---|---|
| 普通头程 | 普通 FBA、海外仓或私人仓货物 | 按箱码进入后续测量和装柜 |
| `ONE_CLICK_DROPSHIP` 一件代发 | 国内清点 SKU、组托后跨境，海外按 SKU/箱唛出库 | 每个货物明细必须有 SKU；目的类型固定走海外仓能力，不允许靠货名推导 SKU |

### 5.2 选择交货方式

| 交货方式 | 页面值 | 必填数据 | 后续含义 |
|---|---|---|---|
| 快递自送 | `SELF_EXPRESS` | 国内收货仓；快递信息按页面当前要求维护 | 客户自行寄到国内仓 |
| 平台上门提货 | `PICKUP` | 本企业提货地址、联系人、电话、城市、详细地址、预约提货时间 | 订单冻结客户要求的提货事实；不等于订舱级拖车 |
| 卡车自送 | `SELF_TRUCK` | 国内收货仓和本单自送信息 | 客户自行送到国内仓 |

`PICKUP` 地址可从地址簿选择，也可保存当前地址。停用地址不能用于新订单，但历史订单继续显示已冻结快照。

### 5.3 选择国内收货仓和渠道

1. 从平台有效国内收货仓单选；
2. 选择仓库后加载该仓可用运输渠道；
3. 选择渠道，保存稳定 `channelCode` 和服务端名称快照；
4. 选择报价包税方式；
5. 选择买单或退税；
6. 选择整柜 `FCL` 或散货 `LCL`；
7. 木制品货物要求商检时，页面和服务端必须校验。

渠道编码是业务校验依据，不能从渠道中文名称反推。

### 5.4 选择目的类型和目的地

| 目的类型 | 页面操作 | 服务端规则 |
|---|---|---|
| `FBA` | 选择平台维护的有效 FBA 仓 | 仓库类型必须匹配；货物行要求货件编号和跟踪编号 |
| `OVERSEAS` | 选择平台维护的有效海外目的仓 | 不允许用私人地址或国内仓冒充 |
| `PRIVATE` | 选择/保存本企业私人地址，填写名称、联系人、电话、国家、城市、地址和邮编 | 地址属于本客户；不创建伪公共仓 |

一件代发页面不开放 FBA/私人仓选择，使用海外仓路径承接后续海外库存。

### 5.5 录入货物明细

每张订单至少一条货物明细。当前页面覆盖：

| 分类 | 字段 |
|---|---|
| 识别 | SKU、中文品名、英文品名、产品图片、混箱组合 |
| 包装 | 包装类型（纸箱/托盘/木箱）、材质、箱数、每箱数量、总数量 |
| 申报尺寸重量 | 长宽高、总毛重、总净重、总体积 |
| 海关申报 | 报关 HS CODE、清关 HS CODE、申报单价、申报金额 |
| FBA | 货件编号、跟踪编号、UPC |
| 产品属性 | 用途、型号、品牌、产品规格、危险品、木制品 |
| 辅助 | 备注 |

关键计算和校验：

- 总数量、总重量和总体积由明细汇总，不能另传一套冲突合计；
- 箱数、件数、重量和体积必须满足正数/非负规则；
- FBA 货物必须填写货件编号和跟踪编号；
- 木制品必须满足商检选择；
- 一件代发 SKU 强制存在，同一箱可通过混箱组合保存多个 SKU；
- 图片只保存经 File 校验的文件引用，Order 不长期保存图片二进制。

### 5.6 订单级其他信息

- 期望出货日期：客户期望，不等于平台确认 ETD；
- 客户备注：客户和平台可见；
- 客户参考号/跟踪编号：用于客户内部定位，不替代平台订单号；
- 费用预估：下单阶段只作当前规则下的估算，不能当成最终费用或客户确认版本。

### 5.7 保存草稿

客户点击“保存草稿”：

- Order 保存主表、Party 快照和货物明细；
- 状态保持 `DRAFT`；
- 不生成入仓码；
- 不创建 Firstleg 正式入库单；
- 不触发资金账户校验；
- 后续可继续编辑或取消。

## 6. F04 客户批量导入详细流程

入口：Client → 头程订单 → 批量导入订单。

### 6.1 下载模板

模板按当前登录客户动态生成：

- 本客户有效提货地址和私人地址；
- 全部有效国内收货仓；
- 匹配目的类型的有效目的仓；
- 当前有效渠道和中文下拉项；
- 日期、数字和枚举校验。

模板目录必须读取全部分页候选，不能只生成第一页选项。

### 6.2 填写和上传

- 文件只接受 `.xlsx`；
- 最大 5MB；
- 最多 50 行有效数据；
- 直接选择中文下拉值，不填写内部 ID；
- 平台上门提货必须填写预约时间和提货地址；
- 木制品必须选择商检；
- 一件代发必须填写 SKU。

### 6.3 两种导入模式

| 模式 | 行失败时行为 |
|---|---|
| `PARTIAL` | 成功行创建草稿，失败行返回行号、字段和原因 |
| `ATOMIC` | 任一行失败时整批不创建订单 |

导入时服务端重新加载仓库、渠道、地址和客户归属，不信任模板隐藏页。成功结果只创建 `DRAFT`，客户仍需检查并提交。

## 7. F05 订单提交和入仓码

### 7.1 提交前检查

客户端进行表单校验后，服务端再次校验：

1. 当前订单属于登录客户且版本一致；
2. 状态允许提交；
3. 当前成员有提交权限；
4. 企业资料已审核通过；
5. Finance 账户响应有效且实际余额不小于 0；
6. 国内收货仓、目的仓和渠道仍启用并类型匹配；
7. 地址属于本客户且类型正确；
8. 货物字段、FBA 条件、木制品商检和一件代发 SKU 完整。

### 7.2 提交事务结果

成功后：

- Order 状态 `DRAFT → SUBMITTED`；
- 统一主状态展示为 `PENDING_REVIEW`；
- 生成并固定全局唯一入仓码；
- 写提交历史、操作者和服务端时间；
- 发布后续协作所需的可靠消息/内部事实；
- 同一幂等请求重放返回原结果，不产生第二个入仓码。

入仓码是订单、国内入库、箱码、装柜和海外尾程之间的稳定业务关联码。页面不得用内部订单 ID 替代。

### 7.3 F06 草稿编辑与取消

- 草稿允许有权限的企业操作员继续修改并保存；
- 已提交订单不得再通过草稿入口覆盖审核中的权威版本；
- 只有服务端当前状态允许时才能取消，页面按钮不是最终授权；
- 取消携带当前版本和幂等键，并记录操作人、时间和原因；
- 已进入不可逆履约的订单不能取消，需进入后续阶段异常流程；
- 请求超时后先查询当前状态，不换新幂等键盲目重试。

## 8. F07 平台审核和申报修订

入口：Admin → 统一订单 → 待审核。

### 8.1 单票审核

1. 按订单号、入仓码、客户、仓库、渠道或状态定位订单；
2. 核对客户、交货方式、预约时间、国内收货仓、目的类型、目的仓、货物和申报；
3. 查看平台可见内部信息和服务端返回的下一动作；
4. 必要时修改允许的客户申报字段；
5. 点击审核通过。

### 8.2 批量审核

1. 选择同一操作范围内的待审核订单；
2. 一次调用批量审核预览，不逐票循环拉详情；
3. 预览按请求顺序返回中文货物摘要、渠道、目的仓、入仓码、`canApprove` 和 `blockReason`；
4. 操作员只提交可审核项；
5. 服务端再次校验状态和版本后逐票处理。

### 8.3 平台申报修订边界

平台可在 `DRAFT/REJECTED/SUBMITTED/APPROVED` 范围内按版本修改客户原始申报，但：

- 不得修改客户归属、国内收货仓、订单号、入仓码和状态；
- 不得增删或重排货物行，使用稳定 `itemNo` 定位；
- 不得覆盖设备/仓库实测、测量审核和计费事实；
- 国内收货仓或中转仓要变化时必须重新下单；
- 只有渠道变化时才检查 Firstleg 履约可逆性和重新计价门禁；
- 内部校验不可用时失败关闭，不能只改 Order 留下跨服务不一致；
- 成功后通过 `ORDER_DECLARATION_UPDATED_V1` 向 Firstleg 同步完整申报快照和字段变化。

### 8.4 审核通过结果

- Order 状态 `SUBMITTED → APPROVED`；
- Firstleg 幂等创建正式国内入库单；
- 正式入库单沿用提交时生成的入仓码；
- 生成/补齐后续测量和 PDA 使用的稳定箱码映射；
- 统一主状态进入 `WAIT_MEASURE`；
- 审核动作和建单结果写入时间线。

审核通过不代表货物到仓，也不代表测量、计费或入库完成。

## 9. 客户订单列表和详情

### 9.1 列表筛选

当前客户可按订单号、国内收货仓、渠道、入仓码/SKU、创建时间、当前状态、目的仓类型和快递单号查询本企业订单。

### 9.2 列表核心展示

列表包含订单号、入仓码、状态、渠道、运输方式、交货方式、预约提货时间、国内收货仓、目的仓、目的类型、箱数、SKU、重量、体积、费用摘要、货件编号、跟踪编号、柜次和船期摘要等。

数据可能来自 Order 申报和 Firstleg 履约聚合；Order 为 `SUBMITTED` 时必须优先展示待审核，不能因 Firstleg 预投影显示成待测量。

### 9.3 详情和可用操作

详情展示：

- 订单主信息和客户/地址快照；
- 货物明细和图片；
- 入仓码业务关系；
- 服务端时间线；
- 当前履约摘要；
- 当前允许的编辑、提交、费用确认、报关资料等动作。

平台内部备注、成本、其他客户数据和内部事件字段不能进入客户响应。

## 10. 状态机和动作

### 10.1 Order 交易状态

```text
DRAFT --提交--> SUBMITTED --平台审核通过--> APPROVED
  └--取消--> CANCELLED

APPROVED --后续全部履约可信回写--> COMPLETED
```

当前产品不以“审核驳回”作为正常业务路径；历史 `REJECTED` 数据在客户侧仍按待补充/待审核兼容展示，不能据此新增一套驳回流程。

### 10.2 统一订单主状态交接

| Order/Firstleg 事实 | 统一显示 | 下一责任人 |
|---|---|---|
| Order `DRAFT` | 草稿 | 客户 |
| Order `SUBMITTED` | `PENDING_REVIEW` | 平台订单运营 |
| Order `APPROVED` + 正式入库单 | `WAIT_MEASURE` | 国内仓/测量人员 |

交易状态和履约主状态是两个维度。平台审核后不应把 Order 交易状态继续当成仓库作业状态。

## 11. 数据流转和权威归属

```text
Auth/IAM
  ├─ 当前客户、成员、角色、企业审核资格
  ↓
Client 下单
  ├─ Warehouse：实时校验国内仓、目的仓和仓库快照
  ├─ Firstleg：读取有效渠道/价格目录
  ├─ Finance：提交时校验资金账户
  ↓
Order 本地事务
  ├─ 订单主表、Party快照、货物明细
  ├─ 状态、版本、入仓码、时间线、幂等结果
  └─ Outbox/内部调用事实
  ↓ 审核通过
Firstleg
  ├─ 正式国内入库单
  ├─ 稳定箱码/箱唛来源
  └─ 下一阶段 WAIT_MEASURE
```

### 11.1 Order 权威数据

- 客户归属、订单号、入仓码；
- 客户原始申报和货物明细；
- 下单时 Party/地址和仓库必要快照；
- 订单交易状态、版本、幂等和时间线。

### 11.2 Order 不拥有的数据

- 实际尺寸、重量和测量审核；
- 国内仓位、托盘和装柜事实；
- 柜次、船节点、海外库存和出库；
- Finance 钱包和结算主账。

### 11.3 关键编号

| 编号 | 生成时点 | 是否可改 | 用途 |
|---|---|---|---|
| `orderNo` | 创建/提交规则生成 | 否 | 客户订单定位 |
| `inboundCode` | 首次成功提交 | 否 | 国内入库至海外尾程稳定关联 |
| 客户参考号 | 客户填写 | 按状态 | 客户内部检索，不替代平台编号 |
| 货物 `itemNo` | 订单明细创建 | 不重排 | 申报更新和箱码来源定位 |

## 12. 正常流、分支和异常恢复

| 场景 | 系统行为 | 操作员处理 |
|---|---|---|
| 企业资料未审核 | 可保存草稿，提交拒绝 | 补资料并等待平台审核 |
| 资金余额小于 0 | 提交拒绝 | 充值或联系财务处理 |
| Finance/IAM/Warehouse 不可用 | 提交失败关闭 | 保留草稿，服务恢复后原单重试 |
| 仓库/渠道在草稿后停用 | 提交时拒绝 | 重新选择有效项 |
| 私人地址归属不符 | 拒绝且不泄露其他客户数据 | 选择本企业地址或新建 |
| 木制品未选商检 | 表单/服务端拒绝 | 补充商检选项 |
| FBA 缺货件号/跟踪号 | 提交拒绝 | 补齐对应货物行 |
| 一件代发缺 SKU | 保存/提交按当前门禁拒绝 | 为每个物理箱内货物补 SKU |
| 版本冲突 | 当前写入失败且不覆盖新版本 | 刷新订单后重新编辑 |
| 请求超时 | 不能换新幂等键盲重试 | 先查询订单/幂等结果，再用原操作处理 |
| 批量导入部分失败 | `PARTIAL` 只建成功行；`ATOMIC` 整批不建 | 按行号和字段修正后重新导入 |
| 审核时 Firstleg 建单失败 | 不能宣称阶段完成 | 查看服务端结果，受控重试或修复依赖 |
| 渠道变更不允许 | Order 和 Firstleg 都不写 | 根据阻断原因新建订单或处理下游占用 |

## 13. 阶段完成判定

每张进入阶段二的订单必须同时满足：

- [ ] Order 属于正确客户且状态为 `APPROVED`
- [ ] 客户可见订单号存在
- [ ] 全局唯一入仓码存在且未变化
- [ ] 国内收货仓、渠道、目的类型和目的地快照完整
- [ ] 货物明细行集合、箱数、SKU/申报字段符合订单类型
- [ ] Firstleg 正式国内入库单已创建并沿用同一入仓码
- [ ] 一件代发稳定箱码与 SKU 来源可用
- [ ] 统一主状态为 `WAIT_MEASURE`
- [ ] 审核和建单时间线可查
- [ ] 重放提交/审核不会生成重复入仓码或重复入库单

任何一项缺失都不能把订单交给国内仓作为正式测量任务。

## 14. 本阶段评审问题

这些问题不阻断现状记录，但需要业务评审确认后才能进入优化：

1. 平台上门提货当前在订单中冻结地址和预约时间，但是否存在独立派车、接单、到仓回执流程？若没有，阶段二只能从“货物实际到仓”开始，不能假设提货已被系统履约。
2. 客户是否仍需要平台代创建订单；若保留，代创建时客户授权、数据来源和通知方式需单列。
3. 当前产品不设订单审核驳回，但代码兼容 `REJECTED` 历史状态；业务是否确认继续采用“平台修改或联系客户修改、保持待审核”。
4. 旧系统入仓码模式是否仍会在任何环境启用；若不会，应从正式流程和页面移除。
5. 下单页的费用预估对客户应如何命名，避免被理解成最终账单。
6. 一件代发混箱 SKU 的实际填报责任人和现场纠错责任是否已明确。

## 15. 阶段二交接包

交给阶段二“国内到仓、测量、计费与组托”的输入应只有以下权威数据：

- 客户和订单业务身份；
- 订单号、入仓码、货物 `itemNo`；
- 交货方式和预约提货事实；
- 国内收货仓快照；
- 渠道与目的仓/私人地址快照；
- 客户申报箱数、SKU、尺寸、重量、体积和报关资料；
- 一件代发箱内 SKU 关系；
- 审核通过时间、版本和幂等历史。

阶段二新增实测和计费事实，不反向覆盖本阶段客户原始申报。

## 16. 事实来源

- `docs/订单与客户/README.md`
- `docs/订单与客户/订单与客户头程订单闭环设计.md`
- `docs/统一订单主状态与操作契约.md`
- `docs/业务快速索引.md`
- `apps/client-web/AGENTS.md`
- `apps/client-web/src/modules/first-leg/views/FirstLegOrdersView.vue`
- `apps/client-web/src/modules/first-leg/api/firstLeg.ts`
- `apps/admin-web/AGENTS.md`
- `apps/admin-web/src/modules/unified-orders/pages/UnifiedOrdersView.vue`
- `baiyue-firstleg/order/AGENTS.md`
- `baiyue-firstleg/order/src/main/resources/openapi/order-v1.yaml`