---
id: T-242
title: 增加受约束的本地货运单删除
phase: 2
deps:
  - T-241
status: DONE
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. 文件删除在数据库提交后以独立短超时执行。失败文件不再有数据库记录或鉴权读取路径，
   不把文件系统失败伪装成数据库回滚，也不记录 storage key 或真实订单内容；Web 成功事件
   只记录内部订单 UUID 和操作人 UUID。
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`；冲突时仍在详情页显示
   “该货运单已进入采购流程，不能删除”。不在密集列表中增加直接删除按钮。

## 验收要点

- [x] 未创建采购需求的货运单可删除，订单、商品和图片数据库记录均不存在。
- [x] 所有缓存图片文件在提交后删除；文件已不存在时仍视为成功。
- [x] 任一商品有关联采购需求时整单返回冲突，订单、全部商品、图片和采购记录均不变化。
- [x] 删除不改变同步运行历史、同步水位或顺运宝 ERP 数据。
- [x] 重复 API 删除为幂等 `204`；无权访问的 ID 不泄漏存在性。
- [x] Web 删除必须通过 ADMIN session、CSRF 和确认交互，成功/冲突反馈明确。
- [x] 删除后使用相同完整订单号重新导入可创建新的本地货运快照。
- [x] 既有货运导入、图片读取、采购需求和采购任务流程不回归。
- [x] 1440×900、390×844 和 375×667 下详情操作区无重叠、溢出或误触风险。
- [x] 标准 Go 测试、race、vet 和三个入口构建通过。

## 边界

- 不删除或修改顺运宝 ERP 数据。
- 不删除同步运行记录，不回退日期增量水位；恢复必须使用完整订单号重新导入。
- 不级联删除采购需求、参考图、采购任务、执行结果或订单提交记录。
- 不提供批量删除、回收站、撤销、归档或自动过期清理。
- 不在页面、日志、fixture 或提交中加入真实货运单、店铺、商品或图片。

## 执行记录

- 2026-07-29：创建任务。第一版采用详情页单单删除和服务端强约束，以最小界面面积提供
  可恢复的本地清理能力；采购审计优先于删除便利性。
- 2026-07-29：仓储使用现有 `_txlock=immediate` 事务按 ADMIN 作用域检查整单采购引用；
  成功时收集 READY 图片键、删除全部商品和订单并保留同步运行/水位。跨作用域与重复删除
  均为空操作，采购关联映射为 `FREIGHT_ORDER_IN_USE`；同单号新同步可建立全新 revision 1
  快照。本任务不需要 schema migration。
- 2026-07-29：图片服务在数据库提交后用 5 秒总预算调用受路径约束且幂等的本地删除；
  Admin API `DELETE` 返回 204/409，SSR POST 强制 CSRF 与 `confirm_delete=1`，详情页使用
  二次确认 dialog 和 noscript 复选框回退，成功事件只记录内部 UUID。
- 2026-07-29：`go test ./...`、`go test -race ./...`、`go vet ./...` 和 API、authctl、
  migrate 三个入口构建通过。Playwright 连接隔离 Gin/SQLite，在 1440×900、390×844、
  375×667 验证弹窗无越界，首次焦点位于保留动作，三个操作按钮均高 44px；实际删除后
  跳转空列表、原图片接口返回 404、本地 JPEG 消失，控制台无警告或错误。