From c80a5c26ed77cd51260745f0d20f361b232742da Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Wed, 29 Jul 2026 15:48:42 +0800
Subject: [PATCH] docs(t242): define freight order deletion

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

diff --git a/docs/tasks/T-242.md b/docs/tasks/T-242.md
new file mode 100644
index 0000000..f73008a
--- /dev/null
+++ b/docs/tasks/T-242.md
@@ -0,0 +1,77 @@
+---
+id: T-242
+title: 增加受约束的本地货运单删除
+phase: 2
+deps:
+  - T-241
+status: TODO
+created: 2026-07-29
+context_ref: 7e3aaac
+work_branch: null
+write_paths:
+  - docs/tasks/T-242.md
+  - docs/current-state.md
+  - backend-api/internal/usecase/freight_*
+  - backend-api/internal/repository/sqlite/freight_*
+  - backend-api/internal/transport/httpapi/**
+  - backend-api/internal/transport/webui/**
+---
+
+## 问题 / 背景
+
+Admin 可以导入、查看和生成采购需求，但误导入或不再需要的本地货运信息无法清理。货运商品
+可能已经关联采购需求、采购任务和本地缓存图片，直接删除 `freight_orders` 会被外键阻止，
+强制级联又会破坏采购来源审计或留下不可访问的 JPEG。
+
+本功能只管理当前系统保存的 ERP 投影，不调用顺运宝删除接口，也不声称删除 ERP 源数据。
+
+## 关联需求与交互
+
+- ADMIN 在货运详情页明确确认后删除本系统中的货运单。
+- 尚未创建任何采购需求的货运单可以删除；只要任一商品已进入采购流程，整单禁止删除。
+- 删除成功后返回货运列表；操作不影响 ERP，可通过完整订单号重新导入。
+- JSON 管理 API 提供同一删除能力和稳定的成功、冲突、未找到响应。
+
+## 方案
+
+1. 在 `FreightService` 增加删除命令；校验 ADMIN 作用域和 UUID 后调用仓储事务，并在提交后
+   通过图片服务清理已收集的本地缓存文件。
+2. SQLite 使用 immediate 写事务锁定删除过程：按 `creator_subject` 读取订单，检查其全部
+   当前/历史商品是否被 `procurement_requests` 引用；有关联则不改数据并返回稳定冲突。
+3. 无采购关联时先收集 READY 图片 `storage_key`，再删除全部商品明细和货运单；图片数据库
+   记录依赖现有 `ON DELETE CASCADE`。保留 `erp_sync_runs` 和增量水位作为同步审计。
+4. 文件删除在数据库提交后以独立短超时执行。失败文件不再有数据库记录或鉴权读取路径，
+   不把文件系统失败伪装成数据库回滚；记录不含真实订单内容的受控诊断事件。
+5. Admin API 增加 `DELETE /api/v1/freight-orders/:id`：首次或重复删除均返回 `204`，
+   其他 ADMIN 作用域中的 ID 也按不存在处理；已有采购关联返回 `409` 和稳定错误码
+   `FREIGHT_ORDER_IN_USE`。
+6. SSR 增加 `POST /freight/:id/delete`，复用 ADMIN session、CSRF 和安全响应头。删除入口
+   位于详情页标题操作区，危险样式与“返回列表”分开；提交前确认本地删除边界。
+7. 成功后 `303` 到 `/freight?notice=deleted`；冲突时仍在详情页显示
+   “该货运单已进入采购流程，不能删除”。不在密集列表中增加直接删除按钮。
+
+## 验收要点
+
+- [ ] 未创建采购需求的货运单可删除，订单、商品和图片数据库记录均不存在。
+- [ ] 所有缓存图片文件在提交后删除；文件已不存在时仍视为成功。
+- [ ] 任一商品有关联采购需求时整单返回冲突，订单、全部商品、图片和采购记录均不变化。
+- [ ] 删除不改变同步运行历史、同步水位或顺运宝 ERP 数据。
+- [ ] 重复 API 删除为幂等 `204`；无权访问的 ID 不泄漏存在性。
+- [ ] Web 删除必须通过 ADMIN session、CSRF 和确认交互，成功/冲突反馈明确。
+- [ ] 删除后使用相同完整订单号重新导入可创建新的本地货运快照。
+- [ ] 既有货运导入、图片读取、采购需求和采购任务流程不回归。
+- [ ] 1440×900、390×844 和 375×667 下详情操作区无重叠、溢出或误触风险。
+- [ ] 标准 Go 测试、race、vet 和三个入口构建通过。
+
+## 边界
+
+- 不删除或修改顺运宝 ERP 数据。
+- 不删除同步运行记录，不回退日期增量水位；恢复必须使用完整订单号重新导入。
+- 不级联删除采购需求、参考图、采购任务、执行结果或订单提交记录。
+- 不提供批量删除、回收站、撤销、归档或自动过期清理。
+- 不在页面、日志、fixture 或提交中加入真实货运单、店铺、商品或图片。
+
+## 执行记录
+
+- 2026-07-29：创建任务。第一版采用详情页单单删除和服务端强约束，以最小界面面积提供
+  可恢复的本地清理能力；采购审计优先于删除便利性。