From 62eee74a70c5fcdcffba4717a9fb1a792c6596d9 Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Wed, 29 Jul 2026 16:21:09 +0800
Subject: [PATCH] docs(t243): define freight draft deletion fix

---
 docs/tasks/T-243.md | 81 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 docs/tasks/T-243.md

diff --git a/docs/tasks/T-243.md b/docs/tasks/T-243.md
new file mode 100644
index 0000000..82a8799
--- /dev/null
+++ b/docs/tasks/T-243.md
@@ -0,0 +1,81 @@
+---
+id: T-243
+title: 允许货运删除清理未完成采购需求草稿
+phase: 2
+deps:
+  - T-242
+status: TODO
+created: 2026-07-29
+context_ref: e5f403f
+work_branch: null
+write_paths:
+  - 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`
+  的行为正确。本任务修复保护边界和反馈，不改变任务列表定义。