# 派送节点交付与六按钮现状核查

范围：测试项目当前 `test` 分支；后端16派送业务。仅源码和离线测试，不代表真实环境已部署或人工验收通过。

## 状态错误结论

用户请求仅提交 `status=DELIVERING, remark=123`，缺少必传 `expectedVersion`，因此返回参数错误。后端 `CustomerVisitRequests.DeliveryStatus` 保留版本必填；列表/详情 `DeliveryRow` 已返回 `version/allowedActions`。当前 Admin 的编辑状态选项将 `DELIVERING` 标为“派送中”，`DELIVERED` 标为“派送完成”，提交代码遗漏版本；不能据用户口述把 DELIVERING 改成完成。

状态命令保持 `{status,expectedVersion,remark}`，不新增幂等头。`START_DELIVERY→DELIVERING` 记录首次派送时间；`COMPLETE_DELIVERY→DELIVERED` 记录签收时间、更新尾程子单状态并生成待回访。相同状态重放成功，不重复状态写入；非法回退及版本冲突拒绝。未新增资料齐全、签名识别或电子签署门禁。

## 三类资料最终契约

完整机器契约：`src/main/resources/openapi/delivery-documents-v1.yaml`。七类方案已撤销，旧类别不接受。

| 顺序与业务类别 | 显示名称 | File类型 |
|---|---|---|
| LOADING_PHOTO | 装车照片 | DELIVERY_LOADING_PHOTO |
| BOL | BOL文件（含签名） | DELIVERY_BOL |
| RECEIPT | 签收文件（POD签收/快递签收） | DELIVERY_RECEIPT |

每类0至20个文件，沿用 File 任意格式且单文件非空、不超过50MiB规则，按有已保存文件的类别计数0/3至3/3。POD与快递签收合为同一类别，文件数量不改变类别计数。

- 读取/下载权限：`platform:overseas-warehouse:delivery:list`；上传/保存权限：`platform:overseas-warehouse:delivery:documents`。
- GET/PUT `/delivery-orders/{deliveryNo}/documents?customerId=...`；PUT全量保存 `{expectedVersion,idempotencyKey,bolNo,documents:[{category,fileIds}]}`，遗漏类别清空。
- 同一派送锁内先检查版本与全部文件归属，再原子写当前快照、增加派送版本、写不可变历史及操作日志。文件保存使用 File 的真实文件名、格式、大小、创建时间，不信任前端元数据。
- 上传不绑定、不修改版本或摘要。未保存/取消弹框不落绑定。替换和删除仅改当前引用，已保存历史和物理对象保留。
- 当前下载仅允许当前绑定文件；指定 `revisionVersion` 仅可下载该派送单对应历史版本已绑定文件。两者均复核客户、派送内部ID、类别和fileId。
- BOL号独立保存，未建立与其他单据的权威关联，不按相同BOL文本或运单号复用其他文件。
- 列表和详情行新增 `bolNo/documentSummary`，摘要从本地保存快照读取，不逐文件调用File。

## 六按钮现状

| 按钮 | 当前实现与权限 | 判定与边界 |
|---|---|---|
| 编辑节点 | `CustomerVisitController` 的 PUT `/delivery-orders/{deliveryNo}/status`、POST `/complete`；`delivery:status`；版本与状态机 | 已实现状态命令，前端漏版本交Admin修复。当前策略只校验派送状态，未联查出库实物门禁；若“编辑节点”意为补录节点时间或修改完成前置规则，需进一步确认，不自动实现 |
| 打印BOL | 派送Controller未发现生成打印接口；Print现有海运提单确认件不能直接证明派送BOL实现 | 未实现派送专属生成链。上传已签名BOL及下载不等于生成打印；模板、字段、签名来源需确认 |
| 详情 | GET `/delivery-orders/{deliveryNo}?customerId=...`，`delivery:list`，返回派送行/货物/费用/操作历史 | 已实现，真实环境待验收 |
| 取消 | 通用状态仅允许WAIT_DELIVERY→CANCELLED，更新派送状态/版本/日志。另出库 `/outbound-orders/{outboundNo}/cancel` 属出库专项，校验未执行并取消关联派送、PDA任务和明细 | 部分实现。单改派送状态不等于撤销履约关联；出库取消还会将尾程主状态写RECEIVED，已报测试总控。需确认派送取消与出库/排车的业务关系，不能擅自互相替代 |
| 编辑车队 | 派送创建保存carrier/driver/vehicle快照，未发现派送单独立维护接口 | 未实现；可改状态、是否联动排车和来源主档规则需确认 |
| 标记退货 | `ExceptionOrderController` `/return-inbound-options`、`/mark-return`；`delivery:return`。从原出库明细选择，冻结可退上限，幂等生成异常；异常处理使用version/幂等与证据 | 已实现后端。退回海外仓必须先按来源恢复实收库存，再同事务完成异常并置派送RETURNED；不能直接改派送状态代替库存。Admin旧自由SKU入参交其收敛 |

## 验证与部署前提

- 本次定向69项通过：包含资料版本/重放/异请求冲突、客户/单据/类别/fileId错配、文件计数与保存后重读、未保存下载拒绝、历史解绑下载、旧枚举拒绝、嵌套校验、权限分离、状态开始/完成/重放、现有出库/退货和SQL合同；只读用户的详情/重放/历史不返回管理动作，按当前授权而非历史权限裁剪。
- Mapper扫描通过。AGENTS索引检查有两项既存柜费契约缺口：金额守恒、单行拒绝处理分摊组，未修改该域。
- 模块基线和获准的海外统一入口同步 `ll_delivery_order.bol_no/documents_json`、`ll_delivery_document_revision`。只维护当前初始化定义，没有旧类别迁移或清理脚本；既有运行库应用方式交测试总控按环境授权处理。
- 单元测试验证保存前全部校验无部分写入和快照重读；真实MySQL事务故障注入、跨服务真实上传下载、页面刷新与人工截图尚未验收。
- 配套最终三类File提交 `81b72992` 和IAM权限 `cde8acf1` 已进入 `test`；不能使用早期七类File提交作为最终类别合同。