Merge branch 'test' of http://8.163.30.128:10082/admin/docs into test

2026-08-05 09:46:54 +08:00
parent 84598f98eb a6fb5ea886
commit df63049fd1
4 changed files with 171 additions and 2 deletions
@@ -21,4 +21,49 @@

 ## 当前状态

-二期已经启动，采用“需求确认与开发并行”的推进方式。2026-07-31 已合并产品确认结果：到仓作业结论已补齐，二期财务范围收缩为“仅头程计费”。当前 V2 的 C1-C8 业务结论以及 T1-T3 技术、仓库和供应商参数仍待确认；原 P2-Q14 至 P2-Q16 已并入 V2，不再单独维护。应收应付、对账、收付款、核销、发票、汇率结算和利润不纳入二期。具体任务状态和实际进度由开发负责人回填，当前文档不代表已承诺完成日期。
+截至 2026-08-04，任务 `019fc6f9-8dcf-74e1-bc68-d42f15d7802a` 已完成，二期核心主链路已在本地测试数据库和隔离服务端口上完成真实 API 回归，最终结果为 `INBOUNDED + APPROVED + SENT`。
+
+- 订单：`2084549604719718402`
+- 入库单：`2084549769916538881`
+- 入仓码：`RK-2084549604719718402`
+- 测量批次：`2084556854154715137`
+- 费用单：`FBAF-2084549769916538881-1`
+- 计费结果：实重 `20kg`，体积 `0.24m³`，计费量 `40.08kg`，费用 `440.68 CNY`
+- 自动化测试：Firstleg 77 项、Warehouse 68 项、共享资源租户专项 3 项全部通过
+- 在线验证：7 个隔离服务健康状态均为 `UP`
+
+本地 OCR 未配置真实供应商凭证，因此本轮验证的是“图片上传成功、OCR 返回失败、人工修正并确认、继续完成计费入库”的可用降级链路。真实 OCR 识别准确率仍需在测试环境使用现场秤图验证。
+
+产品确认与技术验收是两类状态。V2 的 C1-C8 产品结论仍由产品/业务负责人填写；已经实现和测试通过的技术能力记录在验收报告及确认清单的技术状态章节中。
+
+## 核心文档
+
+- [二期全链路验收结果（2026-08-04）](二期全链路验收结果-2026-08-04.md)
+- [二期前端联调报告（2026-08-04）](二期前端联调报告-2026-08-04.md)
+- [第三方入仓测量接口联调说明](第三方入仓测量接口联调说明-2026-08-04.md)
+- [二期需求优化版 V2：测量、计费、托盘入库主流程](二期需求优化版-v2-测量计费入库主流程.md)
+- [二期 V2 需求确认清单](二期V2需求确认清单.md)
+
+## 规划与历史文档
+
+- [二期需求优化版：原型对照](二期需求优化版-原型对照.md)
+- [二期开发规划：头程到仓](二期开发规划.md)
+- [二期开发进度表](二期开发进度表.md)
+- [二期头程计费模块规划](二期计费财务模块规划.md)
+- [二期头程计费需求确认表](二期计费财务需求确认表.md)
+- [二期产品待确认事项](二期产品待确认事项.md)
+- [二期需求确认清单：产品与业务确认](二期需求确认清单.md)
+
+## 数据库增量
+
+可重复执行的测试库增量脚本位于：
+
+```text
+D:\baiyue-firstleg\deploy\sql\2026-08-04-二期回归字段增量-测试库可重复执行.sql
+```
+
+脚本已在本地测试库重复执行验证，包含：
+
+- `fl_inbound_weight_result.created_by`
+- `fl_inbound_weight_result.updated_by`
+- `fl_inbound_pallet_allocation.warehouse_resource_tenant_id`
@@ -5,6 +5,8 @@
 > 确认对象：[二期需求优化版 V2：测量、计费、托盘入库闭环](二期需求优化版-v2-测量计费入库主流程.md)  
 > 适用范围：头程订单审核通过后的测量、计费、托盘分配、库位占用和入库闭环

+> 技术状态（2026-08-04）：任务 `019fc6f9-8dcf-74e1-bc68-d42f15d7802a` 已完成核心正常主链路开发和真实 API 回归。以下“产品确认状态”仍由产品/业务负责人填写，技术完成不自动等同于产品确认。
+
 ## 一、使用说明

 - 本清单是二期 V2 的唯一会议确认入口。
@@ -108,3 +110,21 @@ C1 至 C8 确认后，原 P2-Q14 至 P2-Q16 不再单独维护，避免形成两
 - 托盘数量、库位占用和并发冲突规则可以转为数据库约束和接口验收。
 - 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 创建 | 公共仓资源租户为 `10001`，分配状态 `CONFIRMED` |
+
+完整证据见 [二期全链路验收结果（2026-08-04）](二期全链路验收结果-2026-08-04.md)。
@@ -563,4 +563,63 @@ D:\apache-maven-3.8.8\bin\mvn.cmd clean test -pl order,firstleg,warehouse,file,i
 5. 浏览器端完整登录、刷新 Token、权限按钮、403、跨租户、空态、加载态和重复提交体验。
 6. 当前托盘管理没有独立启停和状态筛选接口；本期页面只做查询、新增、编辑、删除。

-因此当前结论是：**代码编译及 312 项单元/契约测试全部通过，可以进入前后端测试环境联调；真实数据库迁移和在线 HTTP 业务验收尚未执行。**
+上述内容是本报告初版时的阶段结论。2026-08-04 已继续完成真实数据库迁移和隔离端口在线 HTTP 回归，最终结论以第十七章为准。
+
+## 十七、最终在线回归结果（任务 019fc6f9）
+
+### 17.1 验收结论
+
+2026-08-04 已连接本地测试 MySQL，并使用独立 Nacos 分组和隔离端口完成真实 API 全链路回归。下单、订单审核生成入库单、测量草稿、图片绑定、称重图片、OCR 失败人工修正、重量确认、托盘库位占用、测量审核、FBA 自动计费、费用发送和入库完成全部通过。
+
+最终状态：
+
+| 项目 | 结果 |
+|---|---|
+| 订单 ID | `2084549604719718402` |
+| 入库单 ID | `2084549769916538881` |
+| 入仓码 | `RK-2084549604719718402` |
+| 测量批次 | `2084556854154715137` |
+| 入库状态 | `INBOUNDED` |
+| 测量审核状态 | `APPROVED` |
+| 费用状态 | `SENT` |
+| 费用单号 | `FBAF-2084549769916538881-1` |
+| 实重 / 体积 | `20kg` / `0.24m³` |
+| 体积重 / 计费量 | `40.08kg` / `40.08kg` |
+| 最终费用 | `440.68 CNY` |
+| 托盘 | `2084561214309851137` |
+| 库位 | `2084561214452457473` |
+| 库位预占单 | `LR2084562525306675202` |
+| 分配状态 | `CONFIRMED` |
+
+### 17.2 环境与自动化结果
+
+- Nacos 隔离组：`BAIYUE_PHASE2_E2E_20260804`。
+- 隔离端口：`19100`、`19201`、`19202`、`19204`、`19205`、`19206`、`19207`，未占用默认 `9000/9100/920x` 端口。
+- 7 个隔离服务健康检查均为 `UP`。
+- Firstleg 自动化测试 77 项通过。
+- Warehouse 自动化测试 68 项通过。
+- 共享资源租户专项测试 3 项通过。
+
+### 17.3 前端需要采用的最终契约
+
+- 入库详情已经返回 `version`，测量审核、驳回等乐观锁请求必须使用服务端最新版本。
+- Long 类型 ID 继续按字符串处理。
+- 客服审核通过后由后端自动完成计费、费用发送和入库，前端成功后刷新详情与最新费用，不串行调用补偿接口。
+- 平台操作公共收货仓时，业务租户与仓储资源租户由后端分别校验，前端不自行改写资源租户。
+- OCR 未配置时会返回明确失败状态，页面必须允许人工修正识别重量并确认，不能把 OCR 失败等同于整条业务失败。
+
+### 17.4 本轮修复
+
+1. 补齐 `fl_inbound_weight_result.created_by`、`updated_by`，修复称重结果登记 SQL 失败。
+2. 增加 `firstleg.inbound.warehouse-resource-tenant-id`，支持商户订单使用公共资源租户下的仓库、托盘和库位；本轮测试值为 `10001`。
+3. 仓储确认结果回传并保留 `reservationNo`，避免分配快照写入空预占单号。
+4. 入库详情 `InboundOrderSummary` 增加 `version`。
+5. `fl_inbound_pallet_allocation` 增加 `warehouse_resource_tenant_id`，保留历史资源归属快照。
+
+### 17.5 当前边界
+
+- 本轮已验证 OCR 不可用时的人工修正降级闭环；未验证真实 OCR 供应商对现场秤图的准确率、时延和失败重试。
+- 浏览器端视觉、移动端适配和真实用户操作体验仍由前端按本报告接口完成联调验收。
+- 可重复执行的测试库 SQL：`D:\baiyue-firstleg\deploy\sql\2026-08-04-二期回归字段增量-测试库可重复执行.sql`。
+
+最终结论：**二期核心正常主链路已经完成真实 MySQL、真实 HTTP 和自动化回归，后端达到前端联调条件；真实 OCR 供应商识别和浏览器端体验属于后续环境验收项。**
@@ -5,6 +5,8 @@
 > 依据：二期原型、现有二期需求优化稿及 2026-08-01 新增流程说明  
 > 本文只定义二期范围和业务契约，不代表功能已经开发完成。

+> 技术实现状态更新（2026-08-04）：任务 `019fc6f9-8dcf-74e1-bc68-d42f15d7802a` 已完成核心正常主链路开发，并通过本地测试 MySQL 和隔离端口真实 API 回归。产品/业务待确认项仍以第九章和《二期 V2 需求确认清单》为准。
+
 ## 一、结论

 二期主流程应从原来的“人工测量—测量审核—接收审核—人工计费—填写一个库位”调整为：
@@ -393,3 +395,46 @@ POST /internal/location-reservations/{reservationNo}/release
 - 原“接收审核通过即入库”改为“发送费用给客户即入库成功”。
 - 原“只填一个库位”改为按托盘容积向上拆分，并一托一位占用库位。
 - 托盘管理从“不纳入”改为二期必要基础能力，但不扩展为完整 WMS。
+
+## 十一、实现与验收状态（2026-08-04）
+
+### 11.1 已实现并通过真实 API 验证
+
+- 订单审核后生成入库单和唯一入仓码。
+- 平台测量草稿、箱规明细、尺寸证据图片绑定。
+- 称重图片上传、OCR 失败状态、人工修正、重量确认和多重量汇总。
+- 测量提交、托盘拆分、库位预占及确认占用。
+- 客服测量审核通过后自动计费、发送费用并完成入库。
+- FBA 目的仓计费按实重和体积重取大，本轮 `20kg` 与 `40.08kg` 取 `40.08kg`。
+- 入库详情、费用快照、托盘和库位分配结果查询。
+- 公共收货仓资源租户与商户业务租户分离。
+
+### 11.2 最终验证数据
+
+| 项目 | 结果 |
+|---|---|
+| 入库单 | `2084549769916538881` |
+| 入仓码 | `RK-2084549604719718402` |
+| 测量批次 | `2084556854154715137` |
+| 最终状态 | `INBOUNDED / APPROVED / SENT` |
+| 计费 | `40.08kg × 11 CNY/kg = 440.68 CNY` |
+| 托盘 / 库位 | `2084561214309851137` / `2084561214452457473` |
+| 预占单 | `LR2084562525306675202`，状态 `CONFIRMED` |
+
+### 11.3 已落地配置与数据快照
+
+公共仓资源租户配置：
+
+```yaml
+firstleg:
+  inbound:
+    warehouse-resource-tenant-id: ${WAREHOUSE_RESOURCE_TENANT_ID:0}
+```
+
+默认值 `0` 保持租户独立仓逻辑；本地联调使用 `10001`。托盘分配快照已保存 `warehouse_resource_tenant_id` 和 `reservation_no`，避免配置变化后无法追溯历史资源归属。
+
+### 11.4 尚未关闭的环境验收项
+
+- 接入真实 OCR 供应商凭证后，以现场秤图验证识别准确率、超时和重试。
+- 前端浏览器完成登录、权限按钮、403、跨租户、重复提交、空态和移动端体验验收。
+- C1-C8 产品结论仍需产品/业务负责人正式填写，技术实现通过不等于代替产品确认。