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 交易状态

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

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

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

10.2 统一订单主状态交接

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

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

11. 数据流转和权威归属

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