docs: organize contracts by business domain

入库测量与计费/入库测量与计费V2需求确认清单.md

@@ -0,0 +1,143 @@
+# 虫虫出海入库测量与计费 V2 需求确认清单
+
+> 创建日期：2026-08-03
+> 当前状态：待产品与业务确认
+> 确认对象：[入库测量与计费需求优化版 V2：测量、计费、托盘入库闭环](入库测量与计费需求优化版-v2-测量计费入库主流程.md)
+> 适用范围：头程订单审核通过后的测量、计费、托盘分配、库位占用和入库闭环
+
+> 技术状态（2026-08-04）：任务 `019fc6f9-8dcf-74e1-bc68-d42f15d7802a` 已完成核心正常主链路开发和真实 API 回归。以下“产品确认状态”仍由产品/业务负责人填写，技术完成不自动等同于产品确认。
+
+> 订单衔接规则更新（2026-08-07，已确认）：客户草稿不生成入仓码；客户提交进入待审核时立即生成并固定唯一入仓码。平台审核不以选择承运商为前置条件；审核通过后才创建可进入测量流程的正式入库单，并沿用提交时生成的入仓码。承运商可在后续履约或计费前补充。
+
+> 主体模型：入库测量与计费只实现“平台—客户”两级；业务数据的 `tenant_id>0` 是客户隔离兼容字段，平台公共仓储资源归属 `tenant_id=0`。下表历史“资源租户”均指公共主数据技术归属，不代表真实租户。
+
+## 一、使用说明
+
+- 本清单是入库测量与计费 V2 的唯一会议确认入口。
+- 产品只有一人，不填写确认人和确认时间，只填写“最终结论”和“状态”。
+- 状态统一使用：`待确认`、`已确认`、`暂缓`。
+- 认可当前建议时，可将当前建议直接复制为最终结论，并把状态改为“已确认”。
+- 修改当前建议时，必须写清可直接转成页面、接口、状态、计算或验收规则的最终结论。
+- 暂时无法确定时，状态改为“暂缓”，同时填写入库测量与计费临时处理方式。
+- C1 至 C8 全部形成可开发结论后，V2 才能替换现有 24 项开发计划。
+
+## 二、产品与业务必须确认的 8 项
+
+| 编号 | 需要确认的事项 | 当前建议 | 最终结论 | 状态 |
+|---|---|---|---|---|
+| C1 | 是否正式采用 V2 作为入库测量与计费唯一开发基线 | 采用“测量数据采集 → 测量审核 → 自动试算 → 人工确认 → 发送费用 → 托盘与库位占用 → 入库成功”主流程；确认后旧 24 项计划和第一份优化稿停止作为开发依据 | 待填写 | 待确认 |
+| C2 | 长宽高和重量分别从哪里取得 | 长宽高由第三方测量设备按入仓码回传；重量由称重图片 OCR 识别，允许人工校正并保留 OCR 原值、修正值和修正原因 | 待填写 | 待确认 |
+| C3 | 测量审核失败是否允许继续计费和入库 | 默认禁止；仅在 Nacos 异常放行开关开启、操作人有专属权限且填写放行原因时允许继续；作废单、缺少费用快照或无可用库位始终禁止放行 | 待填写 | 待确认 |
+| C4 | 入库测量与计费计费结果的业务边界 | 入库测量与计费只生成发送给客户的头程费用；船司价格只作为计价基础，不生成船司应付、成本、对账、收付款、核销、发票或利润数据 | 待填写 | 待确认 |
+| C5 | KG/CBM 计费公式、换算系数和价格匹配维度 | 包税按 `体积 × 167` 转换为 KG 后与实重取大；不包税按 `重量 ÷ 363` 转换为 CBM 后与实测体积取大；`167`、`363` 按客户规则版本配置，不硬编码；价格按起运仓、渠道/计费类型、船司、FBA 目的仓和有效期唯一匹配 | 待填写 | 待确认 |
+| C6 | 入库测量与计费首批头程费用项目白名单 | 只纳入实际使用的基础运费和明确附加费；每项费用必须确认编码、名称、计费单位、币种、自动/人工、触发条件及是否允许人工调整 | 待填写 | 待确认 |
+| C7 | 发送费用、入库成功及复核节点 | “发送费用给客户”作为入库测量与计费完成节点：锁定费用快照、生成托盘分配、占用库位并将入库单改为已入库；默认不再增加独立接收审核或第二人复核 | 待填写 | 待确认 |
+| C8 | 托盘拆分和库位占用规则 | 按实际总体积除以单托盘可用容积向上取整；入库测量与计费默认一托一库位；托盘只分配体积和箱数汇总，不拆到 SKU；入库后换位作为 P1 独立功能 | 待填写 | 待确认 |
+
+## 三、C6 首批费用项目填写表
+
+没有实际业务的费用不要为了匹配原型而纳入入库测量与计费。白名单之外的费用默认不能自动生成。
+
+| 费用编码 | 费用名称 | 计费单位 | 默认币种 | 自动/人工 | 单价来源 | 触发条件 | 是否允许调整 | 备注 |
+|---|---|---|---|---|---|---|---|---|
+| 待填写 | 待填写 | KG/CBM/票/固定金额 | CNY/USD/待确认 | 待填写 | 客户规则/船司价格/人工 | 待填写 | 待填写 | 待填写 |
+| 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 |
+| 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 |
+| 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 |
+| 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 | 待填写 |
+
+## 四、技术、仓库与供应商确认的 3 项
+
+以下事项不要求产品单独决定，但必须在对应任务开工前形成书面技术结论。
+
+| 编号 | 需要确认的事项 | 当前建议 | 最终结论 | 状态 |
+|---|---|---|---|---|
+| T1 | 第三方长宽高设备接入参数 | 确认供应商、测试环境、入仓码格式、设备编码、事件号、HMAC 签名、时间戳容差、幂等期限、超时和重试规则；第三方不得直接传内部数据库主键 | 待填写 | 待确认 |
+| T2 | OCR 接入参数 | 确认 OCR 服务商、图片格式、单图技术上限、单批数量、识别时限、置信度阈值、公斤/磅识别、失败重试和人工校正规则；业务服务通过 `fileId` 调用，不传服务器目录 | 待填写 | 待确认 |
+| T3 | 托盘和库位基础资料 | 确认托盘编码规则、标准可用容积、仓库现有托盘数量、库位编码、可用状态及初始化数据；并发占位由数据库唯一约束或乐观锁保证 | 待填写 | 待确认 |
+
+## 五、确认后形成的入库测量与计费主流程
+
+```text
+订单与客户头程订单提交待审核
+  → 生成并固定唯一入仓码
+  → 平台审核通过（承运商不是审核前置条件）
+  → 创建正式入库单并沿用该入仓码
+  → 第三方回传长宽高
+  → 上传称重图片并进行 OCR
+  → 人工校正和确认重量
+  → 测量审核
+  → 客户规则与船司 FBA 价格自动试算
+  → 人工确认费用
+  → 发送费用给客户
+  → 拆分托盘并分配库位
+  → 占用库位并完成入库
+  → 客户只读查看费用和入库结果
+  → 异步发送客户通知
+```
+
+## 六、明确不纳入入库测量与计费
+
+- 船司应付、供应商应付和应付审核。
+- 客户或供应商对账单、结算周期和账单争议。
+- 收款、付款、退款、核销、反核销和银行流水。
+- 发票、开票接口、会计凭证和总账。
+- 单票利润、利润率和完整财务报表。
+- 头程/FBA 阶梯计费、组合优惠和通用计费表达式平台。
+- 完整 SKU 库存、盘点、拣货、复核和出库。
+- 入库后的常规移库、拆托、并托和库存成本。
+- PDA 作业端。
+
+### 6.1 海外仓阶梯费用的范围例外
+
+- 已纳入“海外仓客户级天数阶梯仓储费”的基础资料 CRUD，归属 Warehouse 服务，不新增独立服务或数据库。
+- 一名客户只允许一份有效配置，维护币种及连续的天数区间、仓储费单价。
+- 该配置当前只供平台端维护和查询，暂不接入本期头程/FBA 自动计费、费用发送、账单或结算流程。
+- 后续接入海外仓实际计费时，需要另行确认计费单位、入库/出库日边界、免租期、尾段处理、币种换算和规则生效版本。
+
+## 七、与原确认问题的对应关系
+
+| 原编号 | 原问题 | V2 对应项 | 处理方式 |
+|---|---|---|---|
+| P2-Q14 | 首批费用项目 | C6 | 由 C6 费用白名单替代 |
+| P2-Q15 | 计费规则复杂度 | C4、C5 | 由计费边界、公式和匹配维度替代 |
+| P2-Q16 | 费用生成节点 | C7 | 由费用确认、发送和入库成功节点替代 |
+
+C1 至 C8 确认后，原 P2-Q14 至 P2-Q16 不再单独维护，避免形成两套需求编号。
+
+## 八、确认完成后的文档处理
+
+1. 将本文件状态改为“已确认”。
+2. 将 [入库测量与计费需求优化版 V2](入库测量与计费需求优化版-v2-测量计费入库主流程.md) 标记为正式开发基线。
+3. 将 [入库测量与计费需求优化版：原型对照](入库测量与计费需求优化版-原型对照.md) 标记为历史版本，不再用于开发。
+4. 用 V2 的 13 项任务替换现有 24 项开发计划，并同步 Markdown 和 Excel 进度表。
+5. 将 C1 至 C8 的结论转换为状态、接口、数据表、权限、异常和验收规则。
+6. 将 T1 至 T3 分配给技术、仓库和供应商负责人，在对应开发任务开始前补齐。
+7. 后续新增应收应付、对账、收付款、发票或利润时，必须另行立项，不得直接扩入入库测量与计费。
+
+## 九、进入开发排期的完成标准
+
+- C1 至 C8 均为“已确认”，或“暂缓”但已写明入库测量与计费可执行的临时处理方式。
+- C6 至少形成一版可初始化的费用项目白名单。
+- 计费公式、换算系数、唯一匹配维度和费用发送节点可以转为自动化测试。
+- 托盘数量、库位占用和并发冲突规则可以转为数据库约束和接口验收。
+- T1 至 T3 已明确责任方和最晚完成节点。
+- V2 的 13 项任务已经同步到正式开发进度表，旧任务不再继续认领。
+
+## 十、技术实现状态（2026-08-04）
+
+| 对应项 | 技术状态 | 验证说明 |
+|---|---|---|
+| C1 主链路 | 已完成正常链路 | 下单、审核、测量、称重、计费、费用发送、托盘库位、入库已通过真实 API |
+| C2 测量与重量来源 | 已实现 | 第三方/平台箱规明细、图片证据、OCR 失败人工修正与确认已验证 |
+| C3 审核失败放行 | 已实现配置和权限边界 | Nacos 开关默认关闭；正常审核通过链路已验证 |
+| C4 计费边界 | 已按入库测量与计费范围实现 | 仅生成客户头程费用，不扩展应付、对账、核销、发票和利润 |
+| C5 KG/CBM 规则 | 已实现并验证样本 | 实重 `20kg`、体积重 `40.08kg`，取 `40.08kg` 计费 |
+| C6 费用项目白名单 | 技术能力已具备，业务内容待确认 | 本轮使用测试价格 `11 CNY/kg`，不能代替正式费用白名单 |
+| C7 费用发送与入库节点 | 已实现 | 审核通过后自动生成费用 `440.68 CNY`，最终 `SENT + INBOUNDED` |
+| C8 托盘与库位 | 已实现 | 托盘、库位、预占、确认占用及公共主数据技术归属快照已验证 |
+| T1 第三方测量参数 | 接口能力已实现，供应商参数待定 | 正式签名密钥、设备编码和供应商联调环境仍需确认 |
+| T2 OCR 参数 | 降级链路已验证，真实供应商待接入 | 本地 OCR 未配置，已验证失败后人工修正继续入库 |
+| T3 托盘库位基础资料 | 已实现并通过 API 创建 | 当前公共主数据技术归属规则为 `tenant_id=0`，分配状态 `CONFIRMED`；`10001` 不再作为公共资源归属 |
+
+完整接口与回归证据见 [入库测量与计费前端联调报告（2026-08-04）](入库测量与计费前端联调报告-2026-08-04.md)。