dzs/dzs-admin v1.0.105 增量质检报告

• 项目：dzs/dzs-admin（前端后台，Next.js/React + antd）
• 分支：v1.0.105
• 基线（base）：f5da644ba4724fabf776bda1a572758f4b946a22（对应 tag v1.0.104）
• 目标（head）：99e465cc94ed09e0df64d3fb93cfdee0e9e61cc8
• 变更规模：7 个文件（源码 2 / 脚本 1 / 测试 2 / 文档规则 3，其中 1 个文件跨类）；核心逻辑改动仅 2 个源文件，其余为文档、测试与断言同步。

---

一、变更主题

本版本是 v1.0.104 发布后的一次「发布后修正」，全部围绕一条用户裁定：

2026-10-15 用户裁定：后台「插入数据」面板中品类恒单选——不允许同时勾选多个品类。 连锁效果：① 品类下拉不再进入多选态；②「对比表」table_compare 随「多品类对比」一并不可达 → 展示形式选项里不再出现；③ 历史多品类长码（targetId=1,2）回填时收敛为「保留第一个」。

实现方式是一枚全局闸门常量，引擎与组件共读，保证单一出处、不出现口径漂移：

// src/lib/placeholder-panel.ts
export const ALLOW_MULTI_COMMODITY = false;   // 恢复条件：C 端 resolve_price 支持多品类 且 需求改回多选

---

二、变更文件清单

---

三、修复的问题（base → head）

工具实测：修复 0 条。

本增量未修复任何既有质检问题（git diff 中亦无针对历史缺陷的修补）。

---

四、新增的问题（base → head）

工具实测：新增 1 条。

研判（本报告结论）：大概率为误报 / 可接受。该处（第 31–38 行 TC-EDT-003）是解释性注释，逐行说明「抽屉 mask={false} 的关闭语义由哪条用例守护」，并非被注释掉的死代码；本文件是团队刻意重注释的回归用例集。建议不改，若质检平台支持白名单可将其归入误报。

无 Critical / High 级别新增问题。改动未触碰鉴权、SQL、外部接口边界。

---

五、关键改动正确性核查

逐项核对了闸门在多品类相关路径上的覆盖情况（src/lib/placeholder-panel.ts、src/components/articles/MarkdownEditor.tsx）：

1. 引擎侧收敛 ✅ derivePanelState 中

   const allowMulti = ALLOW_MULTI_COMMODITY && dataKind === 'price' && field === 'representative';
   ...
   if (targetIds.length > 1 && !allowMulti) targetIds = [targetIds[0]];
   

   闸门为 false 时 allowMulti 恒为 false → 任何多品类输入都会被收敛为第一个，行为符合裁定。

2. 组件侧展示 ✅ 品类 Select 的绑定与之同源：

   mode={allowMultiTarget ? 'multiple' : undefined}
   value={allowMultiTarget ? panelSelection.targetIds : panelSelection.targetIds[0]}
   

   与引擎用同一个常量判定，不存在「引擎已收敛、组件仍多选」的错配。

3. 下游「对比表」不可达 ✅ const multi = targetIds.length > 1; 因 targetIds 已被收敛，multi 恒为 false → formatOptionsFor 的 if (multi) return build(['table_compare']) 分支不可达，展示形式选项不再出现「对比表」。逻辑正确。

4. 契约未被破坏（关键） ✅ defaultFormatFor 仍然保留「多品类 → table_compare」的返回；formatOptionsFor 的 分支也保留。二者只是，占位符第 8 段 7 个取值（含 ）依旧合法，存量卡解析/短码/快照固化均不受影响。这与 「契约三条」及 `dzs-api 零改动」的结论一致。

---

六、风险与回归影响

---

七、验证建议

1. 存量卡回归：构造一张含 commodity:1,2 ... :table_compare 的已发布文章，走「卡片 ✎ 编辑 → 保存」，确认：① 不报错；② 长码被改写为单品；③ 是否需要对运营弹确认（见风险①）。
2. 面板单选语义：在「代表价」口径下连续选择两个品类，确认下拉为非多选态、第二次选择替换第一次、展示形式无「对比表」。
3. 契约不变：对存入的 table_compare 长码确认短码生成、快照固化、C 端解析路径不受影响（本仓零改动即可由既有用例守住）。
4. 闸门恢复演练（未来）：置 ALLOW_MULTI_COMMODITY = true 后，scripts/verify-placeholder-panel.ts 与 TC-EDT-105 的多选断言应能一次性恢复，验证闸门设计未破坏原逻辑。

---

八、结论

• 本增量为一次范围极小、意图明确的发布后修正：以单枚常量闸门将后台品类收敛为恒单选，引擎与组件共读、口径一致，下游「对比表」正确不可达，占位符契约与 C 端不受影响，改动方向正确。
• 无 Crit/High 级问题，无修复项；新增 1 条 Low（注释过多），经研判为解释性注释导致的误报/可接受。
• 唯一需要产品/运营侧确认的是风险①：编辑并保存存量多品类卡会将其静默改写为单品卡——属既定裁决语义，建议补一条保存前提示或在发布说明中告知。