baiyue-firstleg/lastleg-service/docs/delivery-node-handoff-20260909.md

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

范围：测试项目当前 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提交作为最终类别合同。