zkxw/docs/superpowers/specs/2026-10-14-freight-batch-delete-design.md

运费单删除（级联软删）设计

日期：2026-10-14
范围：Web 管理端「运费信息」、市场移动端（专员/经理）「运费信息」

背景

此前两端仅有「取消关联（unlink）」；当有效关联清零时部分路径会顺带软删主表，但没有显式「删除运费单」能力。产品需要列表上一键删除整单。

决策

1. 语义：同事务软删 biz_sample_freight + 该批次全部 del_flag=0 的 biz_sample_freight_item（级联解除关联并删除批次）。
2. 市场端权限门禁：存在当前账号不可见的关联样本时 禁止删除（与 edit 一致）；错误文案提示需全部样本在范围内。
3. Web 权限：沿用现有运费页入口（require_admin_or_super_admin），不新增独立按钮权限码。
4. 批次号：软删后 freight_no 仍占用唯一索引（与现网一致，本轮不回收）。
5. 非目标：不改协议单内配置/取消运费交互；不做 Web 批量删除。

与 unlink 的差异

| | unlink | delete（本能力） | |--|--------|------------------| | 目标 | 解除选中（或可见范围内）样本关联 | 废弃整个运费单 | | Items | 仅软删匹配项 | 软删该批次全部 active items | | 主表 | 剩余 0 才软删（市场：仅当无任何剩余 active） | 始终软删主表 | | 市场范围外样本 | 可见解完可不删主表 | 禁止整单删除 |

API

• Web：DELETE /web/admin/sample-freights/{id}
• Market：DELETE /mini/market/{specialist|manager}/freights/{id}
• Market 成功返回：{ id, visibleItemCount: 0, disappeared: true }
• Web 成功返回：{ id, deleted: true, linkedSampleCount: 0 }

前端

• Web：运费列表行内「删除」+ 确认框（说明将解除全部关联）。
• Mobile：列表卡片 / 详情底栏在后端 allowedActions 含 delete 时展示；确认后 DELETE；消失后回列表。

实现要点

• 禁止只软删主表而留下 active items（否则 uk_bsfi_active_sample 会阻止样本再关联）。
• Market allowedActions：全可见时 ['edit','delete','link','unlink']；有范围外样本时 ['link','unlink']。
• decorate_allowed_actions freight 白名单含 delete。