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。