cmroubao/docs/tasks/T-243.md

id, title, phase, deps, status, created, context_ref, work_branch, write_paths

id	title	phase	deps	status	created	context_ref	work_branch	write_paths
T-243	允许货运删除清理未完成采购需求草稿	2	T-242	DONE	2026-07-29	e5f403f	null	docs/tasks/T-243.md docs/current-state.md backend-api/internal/usecase/** backend-api/internal/repository/sqlite/freight_* backend-api/internal/transport/httpapi/** backend-api/internal/transport/webui/**

Bug / 背景

T-242 把任意 procurement_requests 记录都视为“已进入采购流程”。采购人员点击“创建采购 需求”后，系统会先生成 NEEDS_IMAGE 需求，但只有上传参考图并显式生成后才会出现 purchase_tasks。因此无参考图、无任务的需求既不会显示在采购任务列表，又会阻止货运删除， 用户无法从界面完成清理。

这不是采购任务列表漏查：任务列表应继续只展示真实 purchase_tasks。Bug 是删除保护边界把 采购准备草稿和不可丢失的参考图/采购任务混为一谈，且冲突提示没有说明实际阻止原因。

修订契约

• reference_asset_id IS NULL 且 purchase_task_id IS NULL 的采购需求属于可清理草稿。
• 可清理草稿只允许处于 BLOCKED、NEEDS_IMAGE 或 SOURCE_CHANGED；删除货运单时在同一 事务内一并删除。
• 任一需求已绑定参考图但尚未生成任务时，整单禁止删除并返回 FREIGHT_ORDER_HAS_REFERENCE。
• 任一需求已生成采购任务时，整单禁止删除并优先返回 FREIGHT_ORDER_HAS_PURCHASE_TASK。
• 货运详情把 NEEDS_IMAGE 显示为“需要参考图，尚未生成任务”，避免与采购任务列表混淆。

方案

1. 用两个来源中立仓储错误替换过宽的 ErrFreightOrderInUse，由 usecase 映射为两个稳定 409 错误码；若同单同时存在参考图和任务，优先报告采购任务。
2. SQLite immediate transaction 先检查全部历史商品关联：任何非空 purchase_task_id 立即回滚；其次任何非空 reference_asset_id 立即回滚。
3. 无保护性关联时，删除该订单商品下状态为 BLOCKED、NEEDS_IMAGE、SOURCE_CHANGED 且两个关联 ID 均为空的采购需求，再沿用 T-242 的图片键收集、商品和订单删除。
4. 不依赖状态字符串来放宽保护：无法归类、数据不一致或未来新增状态的需求保持 fail-closed， 由剩余外键阻止删除并映射内部错误。
5. SSR 对两类冲突使用独立提示；确认弹窗明确未绑定参考图的草稿需求会一并删除，已有参考图 或任务时系统拒绝。API 保持相同 DELETE 路由和幂等 204。
6. 仓储、usecase、API 与 Web 测试覆盖草稿删除、参考图保护、任务保护、优先级、事务不变性 和现有无需求删除；真实响应式 smoke 使用脱敏隔离数据，不操作线上 ERP。

验收要点

• 仅含 NEEDS_IMAGE 且无参考图/任务的货运单可删除，草稿需求、商品和订单同事务消失。
• BLOCKED 及无参考图的 SOURCE_CHANGED 草稿遵守相同删除规则。
• 已绑定参考图但未生成任务返回 409 FREIGHT_ORDER_HAS_REFERENCE，全部记录不变化。
• 已生成采购任务返回 409 FREIGHT_ORDER_HAS_PURCHASE_TASK，全部采购链路不变化。
• 同单同时存在两类保护关联时优先报告已生成采购任务。
• 未知或不一致需求不能被静默删除。
• 采购任务列表仍只展示 purchase_tasks；货运详情准确说明需求尚未生成任务。
• Web 成功、参考图冲突和任务冲突反馈明确，CSRF、确认和响应式交互不回归。
• 删除不影响 ERP、同步历史、水位和 T-242 图片文件清理。
• 标准 Go 测试、race、vet 和三个入口构建通过。

边界

• 不把采购需求加入采购任务列表，不新增第二套采购列表。
• 不删除已绑定参考图、采购任务、执行、候选、授权、下单或支付记录。
• 不增加采购需求单独撤销、批量删除、回收站或归档。
• 不修改顺运宝 ERP，不回退同步水位。
• 不在文档、测试、日志或提交中写入真实订单、商品、店铺或图片。

执行记录

• 2026-07-29：根据真实本地状态审计确认，删除冲突来自 NEEDS_IMAGE 采购需求，且其 reference_asset_id、purchase_task_id 均为空；采购任务列表只查 purchase_tasks 的行为正确。本任务修复保护边界和反馈，不改变任务列表定义。
• 2026-07-29：SQLite immediate 事务先检查 purchase_task_id，再检查 reference_asset_id；两者均不存在时只删除 BLOCKED、NEEDS_IMAGE、 SOURCE_CHANGED 草稿，并在删除商品前确认没有其他需求残留。任务冲突优先于参考图 冲突，未来或不一致状态保持 fail-closed；无需 schema migration。
• 2026-07-29：Admin API 保持原 DELETE 路由和幂等 204，保护分支分别返回 FREIGHT_ORDER_HAS_REFERENCE、FREIGHT_ORDER_HAS_PURCHASE_TASK。SSR 使用独立提示， 详情把 NEEDS_IMAGE 显示为“需要参考图，尚未生成任务”，确认文案明确草稿会被清理。
• 2026-07-29：仓储测试覆盖三种草稿状态、参考图保护、任务保护和任务优先级；usecase、 API、SSR 测试覆盖稳定错误映射及实际 NEEDS_IMAGE 删除。go test ./...、 go test -race ./...、go vet ./... 和 API、authctl、migrate 三个入口构建通过。 Playwright 连接脱敏隔离 Gin/SQLite，以桌面和 390×844 验证状态说明、确认弹窗、真实 登录及删除后空列表，控制台无警告或错误；未访问顺运宝 ERP。