12: 设计稿差异与现有业务结构保护规格

Type: spec Status: resolved Label: ready-for-agent Blocked by: 07 Category: spec

本规格固化设计稿差异与现有业务结构保护的讨论结论，作为同一张蓝湖正式素材替换地图的子规格单。100% 仅表示规格交付，不表示任何素材替换实施批次已经执行过判断表自查。

Problem Statement

蓝湖设计稿与现有驾驶舱实现之间必然存在差异。如果没有一条可执行的边界，实现者在替换素材时可能出现两种错误：把本应升级为结构决策的差异（面板结构、状态语义、数据契约、交互行为）当成纯视觉直接实现，破坏既有契约；或者把纯视觉差异（颜色、间距、图标）无谓地升级为结构决策，拖慢交付。

当前只有「现有代码和业务契约优先」这一原则，没有落地成实现者可逐项对照的判断表。同时，设计稿逐画板盘点（票 02 待办）尚未完成，冲突可能在任何实施批次中途才暴露，需要一个明确的处置闭环，既不让结构差异被悄悄改掉，也不让视觉差异卡住批次。

Solution

提供一张七类差异 × 五列的判断表，作为素材替换实施批次的验收前置：

七类差异（视觉资产、布局尺寸、信息层级、组件状态、地图/设备语义、数据契约、交互行为）各给出可判定的触发条件、归入（素材替换/结构升级）、处置路径与依据出处。
默认取向是「归视觉」，仅触及状态语义、信息层级、交互契约或数据契约才升级为结构决策。
信息层级与数据一律以现有实现与实际后端为准，设计稿数据仅作参考展示。
结构升级必须另立新决策票并由维护者裁定，不口头裁决、不由实现票直接按设计稿做。
每个素材替换实施批次开始时由实现者用判断表自查，「未越界」列为该批次验收前置；终稿验收是最后一道闸。
归视觉的偏差记录到既有缺口清单；结构保护中能自动化的部分由既有断言面承担，判断表不重复造断言。

User Stories

作为实现者，我想在替换素材前有可对照的判断表，以便不靠直觉判断差异归属。
作为实现者，我想让视觉差异默认归入素材替换，以便不无谓地把颜色/间距升级为结构决策。
作为实现者，我想在差异触及面板结构、状态语义、数据契约或交互行为时升级，以便不悄悄破坏既有契约。
作为实现者，我想让判断表每行给出可判定的触发条件，以便不会对「这一行到底归哪边」产生困惑。
作为实现者，我想让判断表每行给出依据出处，以便裁决可追溯到 ADR 或既有票。
作为维护者，我想让结构升级必须另立新决策票，以便不出现口头裁决、无据可查。
作为维护者，我想让升级的新决策票挂到同一张地图上，以便与本次素材替换决策在同一处可查。
作为维护者，我想让实施批次开始时自查判断表，以便结构越界在批次早期被发现而不是终稿才发现。
作为维护者，我想让终稿验收作为最后一道闸，以便即使批次自查遗漏也有兜底。
作为维护者，我想让归视觉的偏差记录到既有缺口清单，以便不出现第二套偏差清单互相打架。
作为维护者，我想让偏差记录包含语义键、缺口类型、回退结果与责任人，以便逐项追踪关闭。
作为值班人员，我想让信息层级以现有实现为准，以便设计稿层级变更不会突然改变我已习惯的界面。
作为值班人员，我想让数据展示以实际后端为准，以便界面不会显示与后端契约不一致的数据。
作为值班人员，我想让状态集合与触发时机不被素材替换改变，以便既有状态语义保持稳定。
作为值班人员，我想让地图的图层显隐、拾取、聚合与状态语义不被素材替换改变，以便一张图行为稳定。
作为值班人员，我想让交互行为不被素材替换改变，以便既有相机、选择态与联动契约保持稳定。
作为实现者，我想让符号外观与颜色可以替换，以便视觉升级不必走结构决策。
作为实现者，我想让状态画法可以替换，以便 hover/选中/禁用等视觉反馈可以升级而状态机不变。
作为实现者，我想让数据展示格式（时间格式、千分位、小数位）可调整，以便展示符合设计稿而不改数据内容。
作为实现者，我想让设计稿标注中的行为说明不被自行解读，以便交互变更必须升级而非我自行实现。
作为维护者，我想让「设计稿未覆盖的现有 UI」维持现状并标记为无设计稿依据，以便不因蓝湖没画就删除或臆造。
作为维护者，我想让删除现有 UI 属结构变更必须升级，以便不默认执行删除。
作为实现者，我想在实施中途发现冲突时按判断表分类，以便处置路径唯一。
作为实现者，我想让归视觉的中途冲突自行处理并记录偏差，以便不阻塞当前批次。
作为实现者，我想让归结构的中途冲突暂停该部分实现并升新票，以便不擅自改契约。
作为维护者，我想让已就地修订的视觉项列入「已有裁决（不得重新打开）」区，以便实现者不会把它们当新冲突重新裁决。
作为维护者，我想让已有裁决区指向原票出处，以便裁决可追溯且不重复讨论。
作为维护者，我想让判断表不转成自动化断言，以便不重复既有断言面（模式/面板数/状态词表冻结）。
作为维护者，我想让既有断言面继续承担结构保护，以便自动化保护不因判断表而削弱。
作为验收人员，我想让实施批次的验收包含判断表自查证据，以便可以确认该批次确实对照过边界。
作为验收人员，我想让结构升级项必须关联一张新决策票，以便升级不是口头记录。
作为验收人员，我想让偏差记录只在既有缺口清单出现，以便不存在第二套偏差记录。
作为验收人员，我想让盘点（票 02）完成后新识别冲突逐项分类，以便确凿结构冲突触发新票。
作为验收人员，我想让判断表的越界判定保持为人工语义判断，以便不产出「代码自动判定越界」的虚假保证。
作为维护者，我想让本规格成为后续所有素材替换实施票引用的边界契约，以便不各按各的标准。

Implementation Decisions

判断表为人工审查契约：不转成自动化断言。七类差异 × 五列（差异类型 / 触发条件 / 归入 / 处置路径 / 依据）供实现者在素材替换实施批次开始时逐项对照。
默认取向：差异默认归入素材替换，仅触及状态语义、信息层级、交互契约或数据契约才升级为结构决策。
现状优先：信息层级以现有实现为准；数据内容一律以实际后端为准，设计稿数据仅作参考展示；数据展示格式（时间格式、千分位、小数位）属视觉可调。
结构升级必须立票：结构差异记录到判断表 → 另立新决策票（挂同一张地图）→ 维护者裁定；不口头裁决、不由实现票直接按设计稿做。
实施批次自查：每个素材替换实施批次开始时由实现者用判断表自查，「未越界」列为该批次验收前置；终稿验收是最后一道闸。
偏差单一来源：归视觉的偏差记录到既有缺口清单（语义键、缺口类型、回退结果、责任人），不另设第二套偏差清单。
中途冲突处置：归视觉 → 实施者自行处理并记录偏差；归结构 → 暂停该部分实现、升新票、不得由实施者改契约。
设计稿未覆盖项：现有 UI 维持现状、标记「无设计稿依据」；删除现有 UI 属结构变更必须升级。
已有裁决区：判断表单列「已有裁决（不得重新打开）」——EMPTY 点位、未关联设备、锚点/尺寸、核心资源组成员，均指向原票出处。
不重复造断言：结构保护中能自动化的（禁止新增 panelId、状态词表冻结、四模式/16 面板断言）由既有断言面承担，判断表不重复。
盘点联动：票 02 逐画板盘点完成后，新识别冲突按判断表分类；确凿结构冲突触发新票。判断表不替代盘点，也不在盘点完成前臆断冲突存在与否。

Testing Decisions

好测试只断言外部可观察事实，不假装自动判定越界。
过程验收测试：素材替换实施批次的验收证据必须包含判断表自查表与未越界声明；缺失即验收失败。
升级可追溯测试：凡判定为结构升级的差异，验收证据中必须关联一张新决策票 key；仅有文字描述无票 key 即失败。
单一来源测试：偏差记录只出现在既有缺口清单；检测到任何第二套偏差清单即失败。
结构回归测试：既有断言面（四模式、16 个 panelId、状态词表冻结等）继续全绿；这是「判断表不重复造断言」的配套——自动化结构保护仍由它们承担。
盘点联动测试：票 02 完成后，新识别冲突逐项分类；确凿结构冲突必须触发新票，纯视觉冲突记录偏差后放行。
越界判定边界：测试不包含「代码自动判定某差异是否越界」——越界是人工语义判断；规格只保证三件外围事实可断言（自查证据存在、升级关联新票、偏差只在缺口清单）。
复用既有先例：既有断言面的结构回归走查、票 06 缺口清单的验收口径、以及各素材替换规格的批次验收清单。规格阶段只写验收契约，不运行构建、开发服务器或浏览器调试。

Out of Scope

蓝湖画板逐项盘点本身；由票 02 负责。
具体素材替换批次的拆分与终稿验收方案；由票 08 负责。
缺口清单的字段与可见性定义；由票 06 负责。
token、位置符号、字体的具体视觉口径；分别由票 03/05/06 对应规格负责。
判断表的自动化断言实现；明确不转代码。
未完成盘点前臆断具体冲突是否存在。

Further Notes

本规格的唯一决策来源是讨论票 07 的 ## Answer。
判断表是人工审查契约，核心价值是把「现有代码和业务契约优先」落地成实现者可逐项对照的边界，并让升级路径可追溯。
判断表不替代票 02 盘点；确凿冲突只有在盘点完成后才能逐项触发升级。
「设计稿未覆盖的现有 UI 维持现状」是本规格对票 02 蓝湖未覆盖清单的处置约定，不把「没画」解读为「该删」。
当前项目规则要求修改代码后不得自动运行构建或调试命令；实现阶段需由用户明确要求后再执行验证。

12-design-diff-structure-boundary-spec.md 11 KB История Директен файл