html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

w百分比

Browse Source
This commit is contained in:
ouyangxq
2026-08-10 12:24:02 +08:00
parent c5ff4d4247
commit 848153e348
5 changed files with 48 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
三期/三期开发规划.md
+10 -9
View File
@@ -54,11 +54,11 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
- 装柜、柜号、铅封号及货柜/铅封照片证据。 - 装柜、柜号、铅封号及货柜/铅封照片证据。
- 客户上传报关资料、平台审核补件、整理并提交报关代理。 - 客户上传报关资料、平台审核补件、整理并提交报关代理。
- 报关回执上传、版本、客户可见范围和授权下载。 - 报关回执上传、版本、客户可见范围和授权下载。
- 装柜完成门禁、确认、冲正、时间线和站内通知。 - 装柜完成门禁、确认、时间线和站内通知；`LOADED` 后纠错走线下人工流程。
### 明确不纳入三期 ### 明确不纳入三期
- 入库、上架、实时库存、移库、盘点、冻结、补货和完整 WMS。 - 入库、上架、移库、盘点、冻结、补货和完整 WMS；拣货仅复用二期实时库存、当前位置和可用量接口。
- 港区闸口、车队、船公司、海关单一窗口的正式自动化接口。 - 港区闸口、车队、船公司、海关单一窗口的正式自动化接口。
- GPS 实时跟车、电子铅封、称重设备、摄像头 OCR 和 IoT 自动采集。 - GPS 实时跟车、电子铅封、称重设备、摄像头 OCR 和 IoT 自动采集。
- 自动报关、关税计算、退税、完整清关业务和自动单证识别。 - 自动报关、关税计算、退税、完整清关业务和自动单证识别。
@@ -189,6 +189,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
| 数据对象 | 关键内容 | | 数据对象 | 关键内容 |
|---|---| |---|---|
| 现有订单三期投影 | 订单、客户、仓库、三期主状态、关联柜次、子流程摘要和版本 | | 现有订单三期投影 | 订单、客户、仓库、三期主状态、关联柜次、子流程摘要和版本 |
| 父/子订单关系 | 父订单、子订单、来源柜次、已装载数量、未装载数量和自动生成原因 |
| 排柜方案 | 经确认的规则版本、输入快照、柜次、货物分配、规则计算结果和确认记录 | | 排柜方案 | 经确认的规则版本、输入快照、柜次、货物分配、规则计算结果和确认记录 |
| 柜次 | 柜型、柜号、铅封号、装载顺序、重量、体积和关联订单 | | 柜次 | 柜型、柜号、铅封号、装载顺序、重量、体积和关联订单 |
| 订舱记录 | 船公司/代理、订舱号、船名航次、港口、舱位和异常 | | 订舱记录 | 船公司/代理、订舱号、船名航次、港口、舱位和异常 |
@@ -209,7 +210,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
- 按已确认的排柜规则提供建议、冲突展示、人工调整、版本对比和确认。 - 按已确认的排柜规则提供建议、冲突展示、人工调整、版本对比和确认。
- 订舱、船期、拖车预约、装柜、柜号、铅封和照片。 - 订舱、船期、拖车预约、装柜、柜号、铅封和照片。
- 报关资料审核、补件、提交批次、回执上传和客户可见控制。 - 报关资料审核、补件、提交批次、回执上传和客户可见控制。
- 权限至少拆分为查看、排柜、订舱、拖车、仓内复核、报关、确认装柜完成和冲正；国内端不提供确认派送完成权限。 - 权限至少拆分为查看、排柜、订舱、拖车、仓内复核、报关、确认装柜完成；仓库初始化操作员、拣货员、理货员角色，国内端不提供在线冲正或确认派送完成权限。
### 企业客户端 `apps/client-web` ### 企业客户端 `apps/client-web`
@@ -224,7 +225,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
- 进入任务即标记“拣货中”；允许部分拣货、跳拣和异常上报，未完成项原因必填并阻断完成。 - 进入任务即标记“拣货中”；允许部分拣货、跳拣和异常上报，未完成项原因必填并阻断完成。
- 扫描保存在设备持久化草稿，点击提交时批量写后端；草稿绑定作业员、任务和柜次。 - 扫描保存在设备持久化草稿，点击提交时批量写后端；草稿绑定作业员、任务和柜次。
- PDA 仅现场拍摄五类装柜照片，同类型可多张追加；确认关联信息后上传，并处理进度、失败重试和作废。 - PDA 仅现场拍摄五类装柜照片，同类型可多张追加；确认关联信息后上传，并处理进度、失败重试和作废。
- 在线作业、前后台切换、重复提交、版本冲突和换班清理；断网不允许正式作业或提交。 - 在线作业、前后台切换、重复提交、版本冲突和异常退出清理；不支持换班接管，断网不允许正式作业或提交。
- Android 广播扫描已按 Action=`android.intent.action.SCANRESULT`、Extra=`value` 接入；真实设备型号、Android 版本、打包发布方式和真机验收仍待确认。 - Android 广播扫描已按 Action=`android.intent.action.SCANRESULT`、Extra=`value` 接入；真实设备型号、Android 版本、打包发布方式和真机验收仍待确认。
### 服务端 `baiyue-firstleg` ### 服务端 `baiyue-firstleg`
@@ -232,7 +233,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
- 最终保证身份、客户归属、仓库数据范围、权限、状态、门禁、幂等、并发和审计。 - 最终保证身份、客户归属、仓库数据范围、权限、状态、门禁、幂等、并发和审计。
- 管理出仓、排柜、订舱、拖车、拣货、装柜、报关和时间线的事务边界。 - 管理出仓、排柜、订舱、拖车、拣货、装柜、报关和时间线的事务边界。
- 文件上传校验类型、大小、内容和权限；使用不可预测标识和授权下载。 - 文件上传校验类型、大小、内容和权限；使用不可预测标识和授权下载。
- 为船期、车队、海关等外部接口预留适配层，但三期不承诺正式对接。 - 船期首版按六家船公司官网查询并记录来源、更新时间和过期标识；车队、海关仍只预留适配层，报关首版全部人工处理，不承诺正式系统对接。
## 八、建议里程碑 ## 八、建议里程碑
@@ -244,7 +245,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
| P3-M3 PDA 拣货 | 在线任务、持久化草稿、批量提交、差异、复核和幂等可用 | 目标设备和真机验收口径确认 | | P3-M3 PDA 拣货 | 在线任务、持久化草稿、批量提交、差异、复核和幂等可用 | 目标设备和真机验收口径确认 |
| P3-M4 装柜封柜 | 柜号、铅封和照片证据完整，门禁生效 | 文件能力与必传清单确认 | | P3-M4 装柜封柜 | 柜号、铅封和照片证据完整，门禁生效 | 文件能力与必传清单确认 |
| P3-M5 报关协同 | 客户上传、平台审核、补件、提交和回执下载闭环 | 报关资料清单确认 | | P3-M5 报关协同 | 客户上传、平台审核、补件、提交和回执下载闭环 | 报关资料清单确认 |
| P3-M6 装柜完成 | PDA 拣货、五类证据各至少 1 张有效照片和锁码文本满足门禁后进入 `LOADED`/装柜完成 | 装柜完成门禁和冲正规则确认 | | P3-M6 装柜完成 | 订舱、拖车、放行回执、PDA 拣货、五类证据和锁码文本满足门禁后进入 `LOADED`/装柜完成 | 装柜完成硬门禁已确认 |
| P3-M7 联调验收 | 跨端、设备、安全、弱网、性能、迁移和发布完成 | P3-M1 至 P3-M6 验收通过 | | P3-M7 联调验收 | 跨端、设备、安全、弱网、性能、迁移和发布完成 | P3-M1 至 P3-M6 验收通过 |
## 九、建议开发任务 ## 九、建议开发任务
@@ -299,8 +300,8 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
| P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 已确认：父订单→子订单→柜次；已装载/未装载数量自动形成子订单 | | P3-Q2 | 是否存在拼柜、一单多柜和拆批出仓？ | 已确认：父订单→子订单→柜次；已装载/未装载数量自动形成子订单 |
| P3-Q3 | “预约托车”是否统一为“预约拖车”？ | 已确认统一使用“预约拖车” | | P3-Q3 | “预约托车”是否统一为“预约拖车”？ | 已确认统一使用“预约拖车” |
| P3-Q4 | 目标 PDA 型号、系统和扫描头接入方式是什么？ | 广播接入已确认并完成；设备型号、Android 版本、打包发布和真机验收仍待确认 | | P3-Q4 | 目标 PDA 型号、系统和扫描头接入方式是什么？ | 广播接入已确认并完成；设备型号、Android 版本、打包发布和真机验收仍待确认 |
| P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 已确认依赖二期库存/库位可用量接口；不扩展完整 WMS | | P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 已确认依赖二期实时库存、当前位置和可用量接口；不扩展完整 WMS |
| P3-Q6 | 柜封照片有哪些必传角度和留存期限？ | 已确认：五类各至少 1 张、同类型可多张追加、后台操作员/理货员可上传、错图作废、无限期保留、客户不可见 | | P3-Q6 | 柜封照片有哪些必传角度和留存期限？ | 已确认：五类各至少 1 张、同类型可多张追加、后台操作员/理货员可上传、拣货员仅 PDA 现场采集、错图作废、无限期保留、客户不可见 |
| P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 已确认首版人工维护清单和版本，不接自动报关 | | P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 已确认首版人工维护清单和版本，不接自动报关 |
| P3-Q8 | 报关代理如何接收资料和返回回执？ | 已确认线下提交，授权人员人工上传回执 | | P3-Q8 | 报关代理如何接收资料和返回回执？ | 已确认线下提交，授权人员人工上传回执 |
| P3-Q9 | 原型中的“港务信息”具体指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 已确认首版查询六家船公司官网，每 3 天一次最多 3 次，记录来源/更新时间/过期标识 | | P3-Q9 | 原型中的“港务信息”具体指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 已确认首版查询六家船公司官网，每 3 天一次最多 3 次，记录来源/更新时间/过期标识 |
@@ -311,7 +312,7 @@ PDA 拣货 → 装柜并上传货柜/铅封照片
## 十二、建议实施顺序 ## 十二、建议实施顺序
1. 固化已确认业务规则，仅对目标设备和实时库存/库位数据源做技术澄清。 1. 固化已确认业务规则，仅对目标设备型号、Android 版本、打包发布和真机验收做技术澄清。
2. 统一订单、柜次、订舱、拖车、拣货、报关和港务/船期信息的稳定编码与关联契约。 2. 统一订单、柜次、订舱、拖车、拣货、报关和港务/船期信息的稳定编码与关联契约。
3. 先实现服务端权限、状态、门禁、幂等、并发和审计，再接各端页面。 3. 先实现服务端权限、状态、门禁、幂等、并发和审计，再接各端页面。
4. 完成管理后台的出仓编排，再接 PDA 现场执行和客户资料协同。 4. 完成管理后台的出仓编排，再接 PDA 现场执行和客户资料协同。
三期/三期开发进度表.md
+11 -11
View File
@@ -16,17 +16,17 @@
| 大任务 ID | 大任务 | 范围 | 状态 | 进度 | 计划开始 | 计划完成 | 负责人 | 关键依赖/备注 | | 大任务 ID | 大任务 | 范围 | 状态 | 进度 | 计划开始 | 计划完成 | 负责人 | 关键依赖/备注 |
|---|---|---|---|---:|---|---|---|---| |---|---|---|---|---:|---|---|---|---|
| T01 | 需求确认与原型 | 锁定阶段边界、流程依赖、排柜规则、设备、文件、报关和港务信息；完成页面原型 | 已完成 | 100% | 2026-07-28 | 2026-08-10 | 总控 | 产品确认版已同步；仅保留设备与实时库存的技术澄清 | | T01 | 需求确认与原型 | 锁定阶段边界、流程依赖、排柜规则、设备、文件、报关和港务信息；完成页面原型 | 已完成 | 100% | 2026-07-28 | 2026-08-10 | 总控 | 产品确认版已同步；仅保留设备与真机技术澄清 |
| T02 | 公共契约与数据模型 | 主/子状态、权限、事件、错误码、订单三期投影、柜次、任务、证据、报关和审计模型 | 进行中 | 10% | 2026-08-10 | 待排期 | 待分配 | 已确认父子订单、硬门禁和仓库角色；依赖二期输出契约 | | T02 | 公共契约与数据模型 | 主/子状态、权限、事件、错误码、订单三期投影、柜次、任务、证据、报关和审计模型 | 进行中 | 10% | 2026-08-10 | 待排期 | 待分配 | 已确认父子订单、硬门禁和仓库角色；依赖二期输出契约 |
| T03 | 订单三期编排与柜次 | 增强现有订单列表/详情，建立父子订单-柜次关系、拆分/拼柜和时间线 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 不新建出仓单；一单多柜、拼柜和未装数量自动生成子订单 | | T03 | 订单三期编排与柜次 | 增强现有订单列表/详情，建立父子订单-柜次关系、拆分/拼柜和时间线 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 不新建出仓单；一单多柜、拼柜和未装数量自动生成子订单 |
| T04 | 智能排柜 | 排柜规则、系统建议、冲突、人工确认和追溯 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 装载率上限 110%；税率排序可配置 | | T04 | 智能排柜 | 排柜规则、系统建议、冲突、人工确认和追溯 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 装载率上限 110%；税率排序可配置 |
| T05 | 订舱与港务信息 | 订舱、变更异常、船公司官网查询、更新时间和过期标识 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 订舱完成属于 `LOADED` 门禁；船期每 3 天最多查询 3 次 | | T05 | 订舱与港务信息 | 订舱、变更异常、船公司官网查询、更新时间和过期标识 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 订舱完成属于 `LOADED` 门禁；船期每 3 天最多查询 3 次 |
| T06 | 拖车预约 | 服务商、车辆司机、预约时间窗、到离仓节点和异常 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 拖车完成属于 `LOADED` 门禁 | | T06 | 拖车预约 | 服务商、车辆司机、预约时间窗、到离仓节点和异常 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 拖车完成属于 `LOADED` 门禁 |
| T07 | PDA 拣货与复核 | 在线进入任务、持久化扫描草稿、批量提交、部分拣货、异常、幂等和单人作业 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 单柜次单作业员；设备型号/实时库存仍需技术澄清 | | T07 | PDA 拣货与复核 | 在线进入任务、持久化扫描草稿、批量提交、部分拣货、异常、幂等和单人作业 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 单柜次单作业员；复用二期实时库存/库位接口，设备真机口径待澄清 |
| T08 | 装柜及柜封证据 | 装柜节点、柜号、铅封号、PDA 现场拍照、后台角色上传、多图追加、作废和复核 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 操作员/拣货员/理货员可上传；无限期保留、客户不可见 | | T08 | 装柜及柜封证据 | 装柜节点、柜号、铅封号、PDA 现场拍照、后台角色上传、多图追加、作废和复核 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 操作员/理货员可后台上传，拣货员仅 PDA 现场采集；无限期保留、客户不可见 |
| T09 | 报关资料与回执 | 人工资料清单、后台审核补件、线下提交代理、人工上传放行回执 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 放行回执属于 `LOADED` 门禁，不做自动接口 | | T09 | 报关资料与回执 | 人工资料清单、后台审核补件、线下提交代理、人工上传放行回执 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 放行回执属于 `LOADED` 门禁，不做自动接口 |
| T10 | 装柜完成门禁 | 校验订舱、拖车、报关放行、PDA 拣货、五类证据和锁码文本，推进 `LOADED` | 待开始 | 0% | 待排期 | 待排期 | 待分配 | `LOADED` 后错误线下处理，不提供在线冲正 | | T10 | 装柜完成门禁 | 校验订舱、拖车、报关放行、PDA 拣货、五类证据和锁码文本，推进 `LOADED` | 待开始 | 0% | 待排期 | 待排期 | 待分配 | `LOADED` 后错误线下处理，不提供在线冲正 |
| T11 | 客户端三期协同 | 装柜进度、柜次、回执、预计开船/到港和变更时间线 | 待确认 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T05、T09、T10；客户可见范围 | | T11 | 客户端三期协同 | 装柜进度、柜次、回执、预计开船/到港和变更时间线 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 客户不查看装柜照片和锁码；依赖 T05、T09、T10 |
| T12 | 联调测试与发布 | 跨端联调、自动化测试、PDA 真机、安全、弱网、迁移、验收和发布 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T02～T11 完成 | | T12 | 联调测试与发布 | 跨端联调、自动化测试、PDA 真机、安全、弱网、迁移、验收和发布 | 待开始 | 0% | 待排期 | 待排期 | 待分配 | 依赖 T02～T11 完成 |
## 三、详细任务表 ## 三、详细任务表
@@ -35,17 +35,17 @@
| ID | 大任务 | 端 | 模块 | 功能/交付内容 | 优先级 | 状态 | 进度 | 依赖 | 负责人 | 备注 | | ID | 大任务 | 端 | 模块 | 功能/交付内容 | 优先级 | 状态 | 进度 | 依赖 | 负责人 | 备注 |
|---|---|---|---|---|---|---|---:|---|---|---| |---|---|---|---|---|---|---|---:|---|---|---|
| P3-T01-00 | T01 | 公共 | 需求确认与原型 | 完成需求确认表、页面清单和原型评审，锁定开工阻断项 | P0 | 已完成 | 100% | - | 总控 | 已同步产品确认版；只剩设备和实时库存技术澄清 | | P3-T01-00 | T01 | 公共 | 需求确认与原型 | 完成需求确认表、页面清单和原型评审，锁定开工阻断项 | P0 | 已完成 | 100% | - | 总控 | 已同步产品确认版；只剩设备和真机技术澄清 |
| P3-T02-00 | T02 | 公共 | 公共契约与数据模型 | 拆状态、权限、数据模型、接口和审计；初始化操作员/拣货员/理货员角色 | P0 | 进行中 | 10% | P3-T01-00 | 待分配 | 统一固化父子订单、柜次、硬门禁和人工报关 | | P3-T02-00 | T02 | 公共 | 公共契约与数据模型 | 拆状态、权限、数据模型、接口和审计；初始化操作员/拣货员/理货员角色 | P0 | 进行中 | 10% | P3-T01-00 | 待分配 | 统一固化父子订单、柜次、硬门禁和人工报关 |
| P3-T03-00 | T03 | 后台/服务端 | 订单三期编排与柜次 | 实现父订单→子订单→柜次、一单多柜、拼柜、未装数量自动子订单和时间线 | P0 | 待开始 | 0% | P3-T02-00 | 待分配 | 复用现有订单，不创建独立出仓单 | | P3-T03-00 | T03 | 后台/服务端 | 订单三期编排与柜次 | 实现父订单→子订单→柜次、一单多柜、拼柜、未装数量自动子订单和时间线 | P0 | 待开始 | 0% | P3-T02-00 | 待分配 | 复用现有订单，不创建独立出仓单 |
| P3-T04-00 | T04 | 后台/服务端 | 智能排柜 | 实现 110% 装载率上限、可配置税率排序、人工确认和版本追溯 | P0 | 待开始 | 0% | P3-T03-00 | 待分配 | - | | P3-T04-00 | T04 | 后台/服务端 | 智能排柜 | 实现 110% 装载率上限、可配置税率排序、人工确认和版本追溯 | P0 | 待开始 | 0% | P3-T03-00 | 待分配 | - |
| P3-T05-00 | T05 | 后台/服务端 | 订舱与港务信息 | 订舱状态及六家船公司查询、三日周期、三次上限、过期标识 | P0 | 待开始 | 0% | P3-T03-00 | 待分配 | - | | P3-T05-00 | T05 | 后台/服务端 | 订舱与港务信息 | 订舱状态及六家船公司查询、三日周期、三次上限、过期标识 | P0 | 待开始 | 0% | P3-T03-00 | 待分配 | - |
| P3-T06-00 | T06 | 后台/服务端 | 拖车预约 | 服务商、车辆司机、时间窗、到离仓和异常；完成状态供门禁校验 | P0 | 待开始 | 0% | P3-T03-00 | 待分配 | - | | P3-T06-00 | T06 | 后台/服务端 | 拖车预约 | 服务商、车辆司机、时间窗、到离仓和异常；完成状态供门禁校验 | P0 | 待开始 | 0% | P3-T03-00 | 待分配 | - |
| P3-T07-00 | T07 | PDA/后台/服务端 | PDA 拣货与复核 | 按单柜次单作业员实现在线草稿、批量提交、异常和幂等 | P0 | 待开始 | 0% | P3-T04-00 | 待分配 | 设备型号和实时库存数据源单独澄清 | | P3-T07-00 | T07 | PDA/后台/服务端 | PDA 拣货与复核 | 按单柜次单作业员实现在线草稿、批量提交、异常、幂等和实时库存校验 | P0 | 待开始 | 0% | P3-T04-00 | 待分配 | 设备型号和真机发布口径单独澄清 |
| P3-T08-00 | T08 | PDA/后台/服务端 | 装柜及柜封证据 | 实现五类多图追加、角色上传、作废和无限期留存，客户不可见 | P0 | 待开始 | 0% | P3-T07-00 | 待分配 | - | | P3-T08-00 | T08 | PDA/后台/服务端 | 装柜及柜封证据 | 实现五类多图追加、角色上传、作废和无限期留存，客户不可见 | P0 | 待开始 | 0% | P3-T07-00 | 待分配 | - |
| P3-T09-00 | T09 | 客户端/后台/服务端 | 报关资料与回执 | 实现人工清单、补件、线下提交记录、人工放行回执上传 | P0 | 待开始 | 0% | P3-T02-00 | 待分配 | - | | P3-T09-00 | T09 | 客户端/后台/服务端 | 报关资料与回执 | 实现人工清单、补件、线下提交记录、人工放行回执上传 | P0 | 待开始 | 0% | P3-T02-00 | 待分配 | - |
| P3-T10-00 | T10 | 后台/服务端 | 装柜完成门禁 | 实现订舱/拖车/放行/PDA/证据硬门禁并推进 `LOADED` | P0 | 待开始 | 0% | P3-T07-00、P3-T08-00、P3-T09-00 | 待分配 | `LOADED` 后只线下人工处理 | | P3-T10-00 | T10 | 后台/服务端 | 装柜完成门禁 | 实现订舱/拖车/放行/PDA/证据硬门禁并推进 `LOADED` | P0 | 待开始 | 0% | P3-T07-00、P3-T08-00、P3-T09-00 | 待分配 | `LOADED` 后只线下人工处理 |
| P3-T11-00 | T11 | 客户端/服务端 | 客户端三期协同 | 待客户可见字段确认后拆分 | P0 | 待确认 | 0% | P3-T05-00、P3-T09-00、P3-T10-00 | 待分配 | - | | P3-T11-00 | T11 | 客户端/服务端 | 客户端三期协同 | 展示柜次、装柜进度、客户可见回执和船期；不返回照片与锁码 | P0 | 待开始 | 0% | P3-T05-00、P3-T09-00、P3-T10-00 | 待分配 | - |
| P3-T12-00 | T12 | 公共 | 联调测试与发布 | 待各模块拆分完成后细化测试与发布任务 | P0 | 待开始 | 0% | P3-T02-00～P3-T11-00 | 待分配 | - | | P3-T12-00 | T12 | 公共 | 联调测试与发布 | 待各模块拆分完成后细化测试与发布任务 | P0 | 待开始 | 0% | P3-T02-00～P3-T11-00 | 待分配 | - |
| P3-T01-PROTO-01 | T01 | 公共 | 原型盘点 | 盘点流程图、后台、企业客户端和 PDA 中与三期相关的页面及交互 | P0 | 已完成 | 100% | - | 待分配 | 2026-07-28 已完成首次盘点，来源为 `docs/悦` | | P3-T01-PROTO-01 | T01 | 公共 | 原型盘点 | 盘点流程图、后台、企业客户端和 PDA 中与三期相关的页面及交互 | P0 | 已完成 | 100% | - | 待分配 | 2026-07-28 已完成首次盘点，来源为 `docs/悦` |
| P3-T03-PROTO-01 | T03 | 后台 | 订单三期编排原型 | 在现有订单列表/详情中设计柜次、子流程摘要、阻塞原因、时间线和操作入口 | P0 | 进行中 | 50% | P3-T01-PROTO-01、P3-Q11 | 待分配 | 不新建出仓单页面 | | P3-T03-PROTO-01 | T03 | 后台 | 订单三期编排原型 | 在现有订单列表/详情中设计柜次、子流程摘要、阻塞原因、时间线和操作入口 | P0 | 进行中 | 50% | P3-T01-PROTO-01、P3-Q11 | 待分配 | 不新建出仓单页面 |
@@ -70,7 +70,7 @@
| T07 PDA 拣货与复核 | 通用 WMS 出库、PDA 集装箱拣货 | 已有参考 | 保留扫描交互，按在线作业、持久化草稿、批量提交、异常阻断和轻量冲突提示重做真实契约 | | T07 PDA 拣货与复核 | 通用 WMS 出库、PDA 集装箱拣货 | 已有参考 | 保留扫描交互，按在线作业、持久化草稿、批量提交、异常阻断和轻量冲突提示重做真实契约 |
| T08 装柜及柜封证据 | 货柜列表、预装清单、装柜清单 | 部分参考 | 后台页面裁剪复用；PDA 只拍照，Admin 可上传，同类型多张追加，错图作废 | | T08 装柜及柜封证据 | 货柜列表、预装清单、装柜清单 | 部分参考 | 后台页面裁剪复用；PDA 只拍照，Admin 可上传，同类型多张追加，错图作废 |
| T09 报关资料与回执 | 报关单列表、单证管理、装柜清单附件 | 部分参考 | 后台裁剪复用；客户上传、补件和回执下载页面新建 | | T09 报关资料与回执 | 报关单列表、单证管理、装柜清单附件 | 部分参考 | 后台裁剪复用；客户上传、补件和回执下载页面新建 |
| T10 装柜完成门禁 | 现有订单状态操作和分散证据字段 | 部分参考 | 在订单详情补门禁检查、确认装柜完成和冲正交互；不提供国内确认派送 | | T10 装柜完成门禁 | 现有订单状态操作和分散证据字段 | 部分参考 | 在订单详情补门禁检查和确认装柜完成；不提供在线冲正或国内确认派送 |
| T11 客户端三期协同 | 头程下单客户端只有船期字段和少量装柜摘要 | 覆盖不足 | 新建三期客户端装柜进度、报关和港务信息页面 | | T11 客户端三期协同 | 头程下单客户端只有船期字段和少量装柜摘要 | 覆盖不足 | 新建三期客户端装柜进度、报关和港务信息页面 |
> `货代SaaS平台原型.html` 是全量平台参考原型，其中海外仓、完整 WMS、费用和清关能力不自动纳入三期；所有复用项仍需经过三期范围裁剪。 > `货代SaaS平台原型.html` 是全量平台参考原型，其中海外仓、完整 WMS、费用和清关能力不自动纳入三期；所有复用项仍需经过三期范围裁剪。
@@ -102,7 +102,7 @@
## 七、未确认事项（需求确认进度） ## 七、未确认事项（需求确认进度）
当前 13 项主确认事项中，P3-Q1～P3-Q3、P3-Q6～P3-Q13 已有产品最终结论；P3-Q4 仅剩设备/真机技术澄清，P3-Q5 仅剩实时库存与库位数据源技术澄清。完整结论统一维护在 [三期需求确认表](三期需求确认表.md)。 当前 13 项主确认事项中，P3-Q1～P3-Q3、P3-Q5～P3-Q13 已有产品最终结论；P3-Q4 仅剩设备型号、Android 版本、打包发布和真机验收技术澄清。完整结论统一维护在 [三期需求确认表](三期需求确认表.md)。
验收拆分已建立：PDA 进入任务、拣货幂等/版本冲突、五类证据真实上传、多图追加和锁码门禁进入自动化；真机在线、设备草稿批量提交、证据作废、设备与权限留存等仍保留 coverageGap，详见[三期验收任务拆分与待确认清单](三期验收任务拆分与待确认清单.md)。 验收拆分已建立：PDA 进入任务、拣货幂等/版本冲突、五类证据真实上传、多图追加和锁码门禁进入自动化；真机在线、设备草稿批量提交、证据作废、设备与权限留存等仍保留 coverageGap，详见[三期验收任务拆分与待确认清单](三期验收任务拆分与待确认清单.md)。
@@ -112,7 +112,7 @@
| P3-Q2 | 开工阻断 | 是否支持拼柜、一单多柜和拆批装柜 | 已确认 | T03 订单三期编排与柜次、T04 智能排柜 | | P3-Q2 | 开工阻断 | 是否支持拼柜、一单多柜和拆批装柜 | 已确认 | T03 订单三期编排与柜次、T04 智能排柜 |
| P3-Q3 | 非阻断 | “预约托车”是否统一为“预约拖车” | 已确认 | T06 拖车预约、页面与接口文案 | | P3-Q3 | 非阻断 | “预约托车”是否统一为“预约拖车” | 已确认 | T06 拖车预约、页面与接口文案 |
| P3-Q4 | 模块阻断 | PDA 型号、系统和扫描头接入方式 | 确认中 | 广播模式已接入；设备型号、Android 版本、发布和真机验收待确认 | | P3-Q4 | 模块阻断 | PDA 型号、系统和扫描头接入方式 | 确认中 | 广播模式已接入；设备型号、Android 版本、发布和真机验收待确认 |
| P3-Q5 | 开工阻断 | 拣货是否依赖实时库存和库位可用量 | 待确认 | T02 二三期契约、T07 PDA 拣货 | | P3-Q5 | 开工阻断 | 拣货是否依赖实时库存和库位可用量 | 已确认 | 复用二期实时库存、当前位置和可用量接口；不扩展完整 WMS |
| P3-Q6 | 模块阻断 | 装柜照片和锁码规则 | 已确认 | 五类多图、角色上传、无限期保留、客户不可见 | | P3-Q6 | 模块阻断 | 装柜照片和锁码规则 | 已确认 | 五类多图、角色上传、无限期保留、客户不可见 |
| P3-Q7 | 模块阻断 | 报关资料清单是否按国家、渠道和货物类型变化 | 已确认 | T09 报关资料、文件版本 | | P3-Q7 | 模块阻断 | 报关资料清单是否按国家、渠道和货物类型变化 | 已确认 | T09 报关资料、文件版本 |
| P3-Q8 | 模块阻断 | 报关代理接收资料和返回回执的方式 | 已确认 | 线下提交、人工上传回执 | | P3-Q8 | 模块阻断 | 报关代理接收资料和返回回执的方式 | 已确认 | 线下提交、人工上传回执 |
@@ -128,7 +128,7 @@
| 准入编号 | 准入条件 | 当前状态 | 责任方 | 完成证据 | | 准入编号 | 准入条件 | 当前状态 | 责任方 | 完成证据 |
|---|---|---|---|---| |---|---|---|---|---|
| P3-GO-01 | P3-Q1～P3-Q3、P3-Q6～P3-Q13 均形成产品结论；P3-Q4/P3-Q5 仅剩技术澄清 | 已完成 | 产品、业务 | `三期需求确认表.md` 已同步最终结论 | | P3-GO-01 | P3-Q1～P3-Q3、P3-Q5～P3-Q13 均形成产品结论；P3-Q4 仅剩设备技术澄清 | 已完成 | 产品、业务 | `三期需求确认表.md` 已同步最终结论 |
| P3-GO-02 | 确认结论已同步开发规划、进度表、页面清单和验收范围 | 进行中 | 产品、项目负责人 | 本轮已同步四份文档，后续随契约实现更新 | | P3-GO-02 | 确认结论已同步开发规划、进度表、页面清单和验收范围 | 进行中 | 产品、项目负责人 | 本轮已同步四份文档，后续随契约实现更新 |
| P3-GO-03 | 关键缺失原型已补齐并评审，包括订单装柜完成门禁、客户端三期页面和 PDA 五类多图拍照 | 进行中 | 产品、设计、业务 | 页面清单中的关键页面达到已确认状态 | | P3-GO-03 | 关键缺失原型已补齐并评审，包括订单装柜完成门禁、客户端三期页面和 PDA 五类多图拍照 | 进行中 | 产品、设计、业务 | 页面清单中的关键页面达到已确认状态 |
| P3-GO-04 | T02 公共契约完成，二期输入、状态机、权限、数据模型、接口、错误码和审计口径稳定 | 待开始 | 前后端、架构/技术负责人 | 契约评审记录及稳定的数据/API 定义 | | P3-GO-04 | T02 公共契约完成，二期输入、状态机、权限、数据模型、接口、错误码和审计口径稳定 | 待开始 | 前后端、架构/技术负责人 | 契约评审记录及稳定的数据/API 定义 |
三期/三期需求确认表.md
+7 -7
View File
@@ -20,13 +20,13 @@
| P3-Q3 | 原型“预约托车”是否统一为“预约拖车”？ | 建议使用行业常用的“拖车”，同时确认业务实际含义 | 非阻断 | 已确认 | 产品/业务 | 2026-08-10 | 页面、接口和文档统一使用“预约拖车” | 页面文案、接口字段说明 | | P3-Q3 | 原型“预约托车”是否统一为“预约拖车”？ | 建议使用行业常用的“拖车”，同时确认业务实际含义 | 非阻断 | 已确认 | 产品/业务 | 2026-08-10 | 页面、接口和文档统一使用“预约拖车” | 页面文案、接口字段说明 |
| P3-Q4 | 目标 PDA 型号、系统和扫描头接入方式是什么？ | 保持设备适配层，不绑定厂商 SDK | 模块阻断 | 确认中 | 用户当前对话确认 | 2026-08-10 | 采用 uni-app 开发并支持在线更新；Android 广播方式已确认并已接入：Action=`android.intent.action.SCANRESULT`、字符串 Extra=`value`。具体 PDA 型号、Android 版本、打包发布流程和目标设备真机验收仍待技术确认 | PDA 拣货、真机验收 | | P3-Q4 | 目标 PDA 型号、系统和扫描头接入方式是什么？ | 保持设备适配层，不绑定厂商 SDK | 模块阻断 | 确认中 | 用户当前对话确认 | 2026-08-10 | 采用 uni-app 开发并支持在线更新；Android 广播方式已确认并已接入：Action=`android.intent.action.SCANRESULT`、字符串 Extra=`value`。具体 PDA 型号、Android 版本、打包发布流程和目标设备真机验收仍待技术确认 | PDA 拣货、真机验收 |
| P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 默认使用二期处理单元和当前位置；如需完整库存，单独评估 WMS 范围 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | PDA 拣货必须依赖实时库存和库位可用量；首版复用二期处理单元、当前位置和可用量接口，超量、库存不足和库位不可用由服务端拒绝；不扩展完整 WMS | 二三期契约、拣货、库存边界 | | P3-Q5 | 拣货是否依赖实时库存和库位可用量？ | 默认使用二期处理单元和当前位置；如需完整库存，单独评估 WMS 范围 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | PDA 拣货必须依赖实时库存和库位可用量；首版复用二期处理单元、当前位置和可用量接口，超量、库存不足和库位不可用由服务端拒绝；不扩展完整 WMS | 二三期契约、拣货、库存边界 |
| P3-Q6 | 柜封照片有哪些必传类型、数量、采集方式、处理规则和留存期限？ | 已确认规则直接进入契约；权限和留存继续确认 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 空仓、半仓、满仓、锁仓、带锁码照五类各至少 1 张有效照片，同类型可无限追加；PDA 只能现场拍照；后台操作员和理货员可人工上传；拣货员只负责 PDA 现场采集，不开放后台人工上传；错图不硬删除，按原因、操作人、时间作废；带锁码照必须填写锁码文本；照片无限期保留，客户不可见照片和锁码 | 装柜、PDA 拍照、Admin 上传、文件存储、订单后程门禁 | | P3-Q6 | 柜封照片有哪些必传类型、数量、采集方式、处理规则和留存期限？ | 五类证据、角色和留存按确认版直接进入契约 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 空仓、半仓、满仓、锁仓、带锁码照五类各至少 1 张有效照片，同类型可无限追加；PDA 只能现场拍照；后台操作员和理货员可人工上传；拣货员只负责 PDA 现场采集，不开放后台人工上传；错图不硬删除，按原因、操作人、时间作废；带锁码照必须填写锁码文本；照片无限期保留，客户不可见照片和锁码 | 装柜、PDA 拍照、Admin 上传、文件存储、订单后程门禁 |
| P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 清单配置化，并保存业务使用的清单版本 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 首版不对接海关或代理系统；按人工维护资料清单、收集/补件并保存版本，具体清单可配置 | 客户资料、报关审核、文件版本 | | P3-Q7 | 报关资料清单是否按国家、渠道和货物类型变化？ | 清单配置化，并保存业务使用的清单版本 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 首版不对接海关或代理系统；按人工维护资料清单、收集/补件并保存版本，具体清单可配置 | 客户资料、报关审核、文件版本 |
| P3-Q8 | 报关代理如何接收资料并返回回执？ | 首版系统内整理、线下提交，正式接口后续评估 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 全部人工处理：平台整理资料后线下交代理，授权人员人工上传代理回执；系统记录提交批次、回执版本和时间，不建设自动对接 | 报关协同、回执上传 | | P3-Q8 | 报关代理如何接收资料并返回回执？ | 首版系统内整理、线下提交，正式接口后续评估 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | 全部人工处理：平台整理资料后线下交代理，授权人员人工上传代理回执；系统记录提交批次、回执版本和时间，不建设自动对接 | 报关协同、回执上传 |
| P3-Q9 | “港务信息”指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 先确认词义和字段；首版平台人工维护并审计 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 首版聚焦船公司船期/货物跟踪查询；每 3 天查询一次，最多 3 次，记录查询时间、来源、更新时间和过期标识。首批来源：美森、SML、ZIM、COSCO、EMC、合德官网；失败后标记信息过期并保留最近结果 | 订舱、港务查询、客户展示 | | P3-Q9 | “港务信息”指船期、港口作业状态还是两者，包含哪些字段，由谁维护？ | 先确认词义和字段；首版平台人工维护并审计 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 首版聚焦船公司船期/货物跟踪查询；每 3 天查询一次，最多 3 次，记录查询时间、来源、更新时间和过期标识。首批来源：美森、SML、ZIM、COSCO、EMC、合德官网；失败后标记信息过期并保留最近结果 | 订舱、港务查询、客户展示 |
| P3-Q10 | 订单进入“装柜完成”后发现错误如何处理？ | 不直接回退状态，使用授权冲正动作和反向审计事件 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | `LOADED` 后不提供在线冲正/回退入口，统一线下人工处理；系统保留原状态和审计记录，不由国内 Admin/PDA 推进 `DELIVERED` | 装柜完成门禁、权限、审计 | | P3-Q10 | 订单进入“装柜完成”后发现错误如何处理？ | 仅保留线下人工处理和审计，不建设在线冲正 | 模块阻断 | 已确认 | 产品/业务 | 2026-08-10 | `LOADED` 后不提供在线冲正/回退入口，统一线下人工处理；系统保留原状态和审计记录，不由国内 Admin/PDA 推进 `DELIVERED` | 装柜完成门禁、权限、审计 |
| P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 已确认 PDA 子流程直接进入契约，其余跨模块依赖继续确认 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 订舱完成、拖车完成、报关资料完成且有放行回执、PDA 拣货完成及五类证据完整均为进入 `LOADED` 的强制门禁；PDA 单柜次单人作业，不做多人并行；进入任务即拣货中，提交时批量写入 | 全流程、状态机、PDA、页面进度 | | P3-Q11 | 九个动作中哪些是强制前置，哪些允许并行？ | 统一门禁按已确认前置执行；PDA 单柜次单人作业 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 订舱完成、拖车完成、报关资料完成且有放行回执、PDA 拣货完成及五类证据完整均为进入 `LOADED` 的强制门禁；PDA 单柜次单人作业，不做多人并行；进入任务即拣货中，提交时批量写入 | 全流程、状态机、PDA、页面进度 |
| P3-Q12 | 报关回执包含哪些类型，海关放行是否为装柜完成硬门禁？ | 当前不默认以放行为门禁，业务明确各类回执含义 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 首版回执由人工上传；必须存在有效放行回执才能通过 `LOADED` 门禁。回执类型和版本可追溯，具体字段按人工业务单据映射 | 报关状态、装柜完成门禁、客户回执 | | P3-Q12 | 报关回执包含哪些类型，海关放行是否为装柜完成硬门禁？ | 有效放行回执作为硬门禁，首版人工上传 | 开工阻断 | 已确认 | 产品/业务 | 2026-08-10 | 首版回执由人工上传；必须存在有效放行回执才能通过 `LOADED` 门禁。回执类型和版本可追溯，具体字段按人工业务单据映射 | 报关状态、装柜完成门禁、客户回执 |
| P3-Q13 | 三期终点以什么状态为准？ | 国内系统以能掌控的最后环节为终点 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-08-08 | 三期终点为 `LOADED`/装柜完成；`DELIVERED`/派送完成只能在到达海外仓后由海外仓可信回传推进，不属于国内三期操作和验收范围 | 阶段边界、状态、里程碑、验收、海外仓回传 | | P3-Q13 | 三期终点以什么状态为准？ | 国内系统以能掌控的最后环节为终点 | 开工阻断 | 已确认 | 用户当前对话确认 | 2026-08-08 | 三期终点为 `LOADED`/装柜完成；`DELIVERED`/派送完成只能在到达海外仓后由海外仓可信回传推进，不属于国内三期操作和验收范围 | 阶段边界、状态、里程碑、验收、海外仓回传 |
### 2.1 PDA 已确认子决策 ### 2.1 PDA 已确认子决策
@@ -57,9 +57,9 @@
## 四、建议确认顺序 ## 四、建议确认顺序
1. 已完成 P3-Q1、P3-Q2、P3-Q3、P3-Q6～P3-Q13 的产品确认，可直接进入契约和实现拆分。 1. 已完成 P3-Q1～P3-Q3、P3-Q5～P3-Q13 的产品确认，可直接进入契约和实现拆分。
2. P3-Q4 仅保留设备型号、Android 版本、打包发布和真机验收的技术确认。 2. P3-Q4 仅保留设备型号、Android 版本、打包发布和真机验收的技术确认。
3. P3-Q5 仍需技术确认实时库存/库位接口是否作为拣货数据源，不影响已确认的 PDA 交互规则。 3. P3-Q5 已确认复用二期实时库存、当前位置和可用量接口，完整 WMS 不纳入三期。
## 五、产品与业务确认会议 ## 五、产品与业务确认会议
@@ -87,7 +87,7 @@
### 5.4 会议输出（确认版） ### 5.4 会议输出（确认版）
- 13 项确认事项的状态和最终结论已同步；其中 P3-Q4、P3-Q5 仅保留技术/设备澄清，不再阻断已确认模块的契约设计。 - 13 项确认事项的状态和最终结论已同步；仅 P3-Q4 保留设备/真机技术澄清，不再阻断已确认模块的契约设计。
- 需要新增或调整的原型清单。 - 需要新增或调整的原型清单。
- 三期范围内/范围外清单及跨期依赖。 - 三期范围内/范围外清单及跨期依赖。
- 仍有风险的事项、责任人和完成日期。 - 仍有风险的事项、责任人和完成日期。
三期/三期验收任务拆分与待确认清单.md
+1 -2
View File
@@ -25,13 +25,12 @@
| P3-PDA-D01 | PDA 断网、恢复网络和真机在线限制 | HTTP 验收器无法模拟设备网络与现场相机 | 目标 PDA 型号、Android 版本、网络策略和真机环境确定后执行真机脚本 | | P3-PDA-D01 | PDA 断网、恢复网络和真机在线限制 | HTTP 验收器无法模拟设备网络与现场相机 | 目标 PDA 型号、Android 版本、网络策略和真机环境确定后执行真机脚本 |
| P3-PDA-D03/D04 | 设备持久化草稿、批量提交、跨账号隔离 | 当前公开服务未提供稳定的设备草稿/批量提交 HTTP 契约 | 固定草稿 DTO、提交端点、幂等键、版本字段和清理语义 | | P3-PDA-D03/D04 | 设备持久化草稿、批量提交、跨账号隔离 | 当前公开服务未提供稳定的设备草稿/批量提交 HTTP 契约 | 固定草稿 DTO、提交端点、幂等键、版本字段和清理语义 |
| P3-Q4 | 真机型号、系统、扫描头、打包发布 | 广播协议已接入，但具体设备和真机发布口径未提供 | 产品/技术补齐设备清单并完成真机验收 | | P3-Q4 | 真机型号、系统、扫描头、打包发布 | 广播协议已接入，但具体设备和真机发布口径未提供 | 产品/技术补齐设备清单并完成真机验收 |
| P3-Q5 | 拣货实时库存与库位数据源 | 已确认 PDA 交互，不代表实时库存接口已稳定 | 技术确认二期库存/位置契约并纳入真实 HTTP 验收 |
## 并行任务拆分 ## 并行任务拆分
1. `P3-ACCEPT-PDA-ONLINE`：PDA 真机在线/断网/前后台验收。 1. `P3-ACCEPT-PDA-ONLINE`：PDA 真机在线/断网/前后台验收。
2. `P3-ACCEPT-PDA-DRAFT`：草稿持久化、批量提交、幂等、版本冲突和跨账号隔离验收。 2. `P3-ACCEPT-PDA-DRAFT`：草稿持久化、批量提交、幂等、版本冲突和跨账号隔离验收。
3. `P3-ACCEPT-EVIDENCE-VOID`：五类证据多图追加、作废、锁码文本和 `LOADED` 门禁验收。 3. `P3-ACCEPT-EVIDENCE-VOID`：五类证据多图追加、作废、锁码文本和 `LOADED` 门禁验收。
4. `P3-CONFIRM-Q4-Q5`：技术补齐设备/真机和实时库存/库位契约确认。 4. `P3-CONFIRM-Q4`：技术补齐设备型号、Android 版本、打包发布和真机验收口径。
每个任务完成后，必须把真实请求、响应状态、业务码、`requestId/traceId` 写入报告，并删除对应 coverageGap；不得以 mock 或数据库直写替代接口验收。 每个任务完成后，必须把真实请求、响应状态、业务码、`requestId/traceId` 写入报告，并删除对应 coverageGap；不得以 mock 或数据库直写替代接口验收。
墨家设备测量上传接口说明-V3.md
+19 -8
View File
@@ -5,7 +5,12 @@
## 1. 接口用途 ## 1. 接口用途
墨家设备扫描柏悦唛头并上传当前箱子的测量结果。每次请求对应一次设备测量，不需要传订单内部字段，也不需要关心柏悦后续如何保存、审核或计费。 墨家设备扫描当前箱上的两张标签并上传测量结果：
- 柏悦唛头二维码，扫描结果作为 `boxCode`；
- 客户从 Amazon FBA 下载并贴在箱上的 FBA 标签，扫描其中的 Shipment ID，作为 `shipment_id`。
每次请求对应一次设备测量，不需要传订单内部字段，也不需要关心柏悦后续如何处理数据。
唛头二维码内容由柏悦生成，设备应原样读取并作为 `boxCode` 上传。例如： 唛头二维码内容由柏悦生成，设备应原样读取并作为 `boxCode` 上传。例如：
@@ -15,6 +20,8 @@ PCHK2608040174#19-1
设备不需要解析或修改 `boxCode`。 设备不需要解析或修改 `boxCode`。
`shipment_id` 不是柏悦生成的内容，也不能从 `boxCode` 推导。设备必须从当前箱的 Amazon FBA 标签实际扫描并原样上传。
## 2. 接口地址 ## 2. 接口地址
```text ```text
@@ -41,6 +48,7 @@ POST <GATEWAY_HOST>/openapi/v1/inbound-measurements
```json ```json
{ {
"boxCode": "PCHK2608040174#19-1", "boxCode": "PCHK2608040174#19-1",
"shipment_id": "FBA19L5KMY2CU000002",
"length": 100.1, "length": 100.1,
"width": 100.2, "width": 100.2,
"height": 100.3, "height": 100.3,
@@ -55,6 +63,7 @@ POST <GATEWAY_HOST>/openapi/v1/inbound-measurements
| 字段 | 必填 | 说明 | | 字段 | 必填 | 说明 |
|---|---|---| |---|---|---|
| `boxCode` | 是 | 扫描得到的唛头二维码文本，必须原样传输 | | `boxCode` | 是 | 扫描得到的唛头二维码文本，必须原样传输 |
| `shipment_id` | 是 | 从当前箱 Amazon FBA 标签实际扫描得到的 Shipment ID，必须原样传输；兼容字段名 `shipmentId` |
| `length` | 是 | 当前箱长度，单位 cm | | `length` | 是 | 当前箱长度，单位 cm |
| `width` | 是 | 当前箱宽度，单位 cm | | `width` | 是 | 当前箱宽度，单位 cm |
| `height` | 是 | 当前箱高度，单位 cm | | `height` | 是 | 当前箱高度，单位 cm |
@@ -76,20 +85,22 @@ data:image/jpeg;base64,<Base64内容>
成功时返回 HTTP 200 和 JSON 成功结果。墨家只需判断 HTTP 状态和响应中的成功标识，不需要处理柏悦内部业务字段。联调期间，即使模拟箱码暂未匹配柏悦入库单，只要测量字段和图片已被柏悦完整接收并保存，也会返回成功；柏悦自行记录并排查匹配结果。 成功时返回 HTTP 200 和 JSON 成功结果。墨家只需判断 HTTP 状态和响应中的成功标识，不需要处理柏悦内部业务字段。联调期间，即使模拟箱码暂未匹配柏悦入库单，只要测量字段和图片已被柏悦完整接收并保存，也会返回成功；柏悦自行记录并排查匹配结果。
失败时，柏悦会返回 HTTP 错误或 JSON 错误信息。设备应记录请求时间、`boxCode`、`machineNo` 和响应信息，便于重试和排查。 失败时，柏悦会返回 HTTP 错误或 JSON 错误信息。设备应记录请求时间、`boxCode`、`shipment_id`、`machineNo` 和响应信息，便于重试和排查。
## 6. 重试约定 ## 6. 重试约定
网络超时或未收到响应时，设备可以重试同一次上传。当前按 `boxCode` 保存最新结果，同一个箱号重试不会新增多条当前记录。 网络超时或未收到响应时，设备可以重试同一次上传。当前按 `boxCode` 保存最新结果，同一个箱号重试不会新增多条当前记录。
同一个 `boxCode` 后续再次上传时，以最新一次设备测量结果为准，设备无需额外传版本号。 同一个 `boxCode` 后续再次上传时，以最新一次设备上传的测量结果和实扫 `shipment_id` 为准，设备无需额外传版本号。
## 7. 待墨家确认 ## 7. 待墨家确认
1. `boxCode` 是否可以原样上传完整二维码文本，例如 `PCHK2608040174#19-1`。 1. 是否可以同时扫描柏悦唛头和 Amazon FBA 标签，并分别上传 `boxCode`、`shipment_id`。
2. `picture` 是否可以按 `data:image/jpeg;base64,...` 格式上传。 2. `boxCode` 是否可以原样上传完整二维码文本，例如 `PCHK2608040174#19-1`。
3. `weight` 的单位、精度和是否必传。 3. `shipment_id` 是否可以原样上传，例如 `FBA19L5KMY2CU000002`。
4. `machineNo` 是否每台机器固定且唯一。 4. `picture` 是否可以按 `data:image/jpeg;base64,...` 格式上传。
5. 首轮联调完成后，再共同确认动态 HMAC-SHA256 签名的启用时间。 5. `weight` 的单位、精度和是否必传。
6. `machineNo` 是否每台机器固定且唯一。
7. 首轮联调完成后，再共同确认动态 HMAC-SHA256 签名的启用时间。
柏悦侧会另行提供正式接口地址、固定 AppKey 和测试箱码。首轮联调只校验固定 AppKey，不需要 Secret；本文不包含任何真实密钥或柏悦内部业务处理规则。 柏悦侧会另行提供正式接口地址、固定 AppKey 和测试箱码。首轮联调只校验固定 AppKey，不需要 Secret；本文不包含任何真实密钥或柏悦内部业务处理规则。