zkxw/docs/superpowers/specs/2026-10-26-protocol-sample-code-lock-design.md

协议编辑锁定已落库样本编码 — 设计

日期：2026-10-26
状态：已确认（方案 1，实现默认）
关联：样本编码全链路纠错（2026-10-22-sample-code-correction-design.md）

---

1. 背景

客户服务 / 样本信息管理已提供「更正编码」，会级联更新下游快照。协议单（采集协议、科研捐赠）编辑里换码不会回写下游，易造成不一致。因此编辑已落库样本时禁止改编码。

2. 范围决策

项	决定
业务	采集协议 + 科研捐赠
端	Web 管理端 + 小程序市场端（mobile-oa-h5）
新增样本	仍可选 / 可自动生成编码
已落库判定	样本行有持久化 id
本会话未保存新行	仍可改码
后端	更新时若 payload 带已存在 id 且编码变更 → 拒绝
真要改码	仅走「更正编码」

3. 非目标

• 不禁止删除已有样本后再新增另一条（删 + 增）
• 不在协议编辑内提供纠错入口
• 不改「更正编码」级联逻辑

4. UI

• Web：SampleTransportFormSection 编辑弹窗中，若 sampleDraft.id 非空，样本编码只读展示；新增仍用选择器 / 自动生成。
• 小程序：ProtocolSampleTransportPanel 同等规则（科研捐赠本就自动生成只读，编辑已落库时保持只读并提示来源）。
• 可选提示：已落库编码请到客户服务使用「更正编码」。

5. 后端

在采集协议 save_samples、科研捐赠样本更新路径中，于写库前：

1. 加载本单现有未删样本，按 id 建索引。
2. 遍历 payload：若 id 命中现有行，则 sample_code、sample_code_id（trim 后）必须与库中一致。
3. 否则 ValueError，文案明确引导使用「更正编码」。

无 id 或 id 不在本单现有行中的条目视为新增，不套本校验。

6. 测试

• 已落库样本改 sampleCode / sampleCodeId → 拒绝。
• 已落库样本保持原码 → 通过。
• 无 id 新增样本 → 不受本规则影响。