zkxw/openspec/changes/storage-cert-qc-field-acl/design.md

Context

储存证质检信息由 biz_sample_storage_cert_qc.payload JSON 保存，Web 共用 storage-cert-qc-dialog，API 以菜单码控制读写且保存为整单覆盖。业务现要求按「质检 / 生产」拆分字段编辑权，并可由管理员配置人员。

已确认：方案 A（租户级配置 + 按人授权）；配置入口独立菜单码；未配置前兼容旧写权限；同人字段并集；修改端为 web-admin + backend。

Goals / Non-Goals

Goals:

• 租户可配置质检、生产两套「字段 + 人员」ACL
• 前端按字段只读/可写；后端 merge 强制执行
• 三处入口行为一致；配置 UI 符合 Fresh Mint 弹窗规范

Non-Goals:

• 不按样本、不按工单单独配置 ACL
• 不引入角色绑定作为本期主路径（人员勾选）
• 不改造 mobile-h5 / mobile-oa-h5
• 不改变 payload 字段语义与预填逻辑（仅限制谁能改）

Decisions

1. 存储：主表 biz_storage_cert_qc_acl（tenant_no+scope 唯一，field_keys JSON，configured_flag）+ 子表 biz_storage_cert_qc_acl_user（acl_id+user_id，软删同步）。相对单 JSON 大包，子表便于人员校验与审计扩展。
2. 权限解析：用户可编辑字段 = 其所属各已配置 scope 的 field_keys 并集；严格模式在「任一 scope 的 configured_flag=1」时启用；否则有原 WRITE_MENUS 即可编辑全部合法字段。
3. 写路径：BREAKING 行为：PUT 从整单覆盖改为服务端 merge——仅更新 editableFieldKeys 内键；无任何可写字段拒绝保存；提交中含无权键且值相对库内有变化则 403。
4. 配置权限：独立菜单码（建议 cell-storage:sample-info:storage-cert-qc-acl）；与业务填写菜单分离。按钮仅在 canConfigureAcl=true 时展示。
5. 字段候选：前后端共用类型字段清单（与 STORAGE_CERT_QC_GROUPS / 后端 type keys 对齐）；配置 UI 展示两样本类型字段并集，非法 key 拒绝保存。
6. UI：主弹窗 footer 左侧配置按钮、右侧取消/确定；配置子弹两个 Tab（字段勾选 / 人员多选）。先 Figma 确认再编码。

Risks / Trade-offs

• [未配置→已配置切换瞬间全员变严] → 上线说明；兼容期默认未配置仍可写；配置保存前可预览影响（可选，本期不做强制）。
• [人员名单维护成本] → 接受方案 A；后续可加角色扩展，不阻塞本期。
• [整单覆盖客户端旧代码] → 后端 merge 兼容旧客户端：无权字段被忽略或在变更时 403；推荐 403 以便发现错误集成。
• [超级管理员] → 不默认绕过 ACL；仅配置菜单控制谁能改 ACL。若需超管旁路，另开需求。

Migration Plan

1. 执行 SQL 建表；部署后端（读接口先返回兼容态 editableFieldKeys=全部或空+aclStrict=false）。
2. 部署前端（无配置权限时 UI 与现网接近）。
3. 管理员配置质检/生产后该租户进入严格模式。
4. 回滚：保留表数据；回退代码后配置表闲置；严格模式逻辑随代码回退消失。

Open Questions

• 无（关键项已在对话确认：租户级、独立配置菜单、兼容期、字段并集、先 Figma）。