← Schema-As-Code / 语义字典

Schema-As-Code 组织级语义注册表 · ① 语义字典

语义字典 Semantic Dictionary

先注册、后引用。字典是组织级唯一信源，所有 YAML 契约必须引用字典中的已定义项。
契约只是字典的只读消费面。

字典是唯一定义源

全组织同一术语坐标系，任何团队不得维护平行的"私有字典"；非法引用在编译前置校验时阻断

字典可被机器查询

覆盖层目录、语义绑定、场景映射三层结构可被编译管线查询，并编译为三种消费格式

字典变更可同步

字典单点变更 → 契约重编译 → 四种消费格式同步更新，Git Diff 可追溯

第一层：覆盖层目录

Overlay Catalog · 每个界面点必须且只能被一个 L1 覆盖层覆盖（互斥）

L1 transactional

交易与操作：用户动作会改变系统状态或数据

适用：支付、删除、提交、确认、撤销

禁止：纯信息展示、状态更新、新手引导

L1 observational

观察与信息：用户仅接收信息，无需立即行动

适用：通知、状态更新、提示、反馈

禁止：需要用户决策、需要二次确认、不可逆操作

L1 navigational

导航与引导：用户需要方向指引，无数据变更

适用：面包屑、步骤指示、返回、跳转

禁止：表单提交、数据操作、支付流程

L1 conversational

对话与交互：用户与系统双向交流，上下文持续

适用：聊天、问答、建议、澄清

禁止：一次性操作、无上下文的状态提示

L2 financial transactional 子层

涉及资金流动：支付、转账、退款

L2 data-destructive transactional 子层

涉及数据删除：删除账户、清空数据

第二层：语义重绑定

Semantic Rebinding · 同一个词，不同覆盖层下绑定为不同语义

通用术语：Alert 在不同覆盖层下的语义绑定

transactional

阻断器

用户必须立即处理，否则系统状态恶化

视觉：红色脉冲 + 八边形

行为：必须二次确认

文案：必须说明后果

observational

信息条

用户可选择性关注，不影响系统状态

视觉：蓝色静态 + 信息图标

行为：可自动消失

文案：禁止附加操作说明

navigational

路径提示

用户需要方向确认，无状态风险

视觉：绿色静态 + 箭头图标

行为：点击后跳转

文案：显示下一步预览

字典 v1.0.0 注册的 6 个语义绑定

术语 ID

所属覆盖层

语义绑定

约束注入

跨层禁止

status.critical

transactional

阻断器：用户必须立即处理

红色脉冲、八边形；必须二次确认；必须说明后果

observational / navigational / conversational

status.warning

transactional

限制器：用户可自助恢复

黄色静态、三角图标；必须显示恢复时间；必须提供操作步骤

—

status.info

observational

信息条：用户可选择性关注

蓝色静态、信息图标；可自动消失；禁止附加操作说明

transactional

status.success

observational

成功条：操作已完成

绿色静态、对勾图标；可自动消失；禁止附加操作说明

transactional

action.destructive

transactional

危险动作：数据永久丢失

红色空心描边、危险图标；必须二次确认；必须说明不可恢复

observational / navigational / conversational

action.primary

navigational

引导动作：帮助用户进入下一步

品牌色实心、箭头图标；点击后跳转；显示下一步预览

transactional / observational

第三层：场景映射

Scenario Mapping · 业务场景的完整语义方案，设计师查询即得

SCN-001

删除账户

覆盖层：transactional

语义绑定：status.critical + action.destructive

组件：Alert + Button + Modal

文案：必须包含"此操作不可恢复"

约束：必须输入账户名二次确认

SCN-002

网络中断

覆盖层：transactional

语义绑定：status.warning

组件：Alert + Button

文案：必须显示"网络不稳定"

约束：必须显示自动重试倒计时

SCN-003

保存成功

覆盖层：observational

语义绑定：status.success

组件：Toast

文案：仅显示"保存成功"

约束：3 秒后自动消失

SCN-004

新功能上线

覆盖层：observational

语义绑定：status.info

组件：Banner

文案：显示功能名称 + 一句话说明

约束：不可阻断当前操作

SCN-005

支付确认

覆盖层：transactional (financial)

语义绑定：status.critical

组件：Alert + Form + Button

文案：必须显示金额、收款方、支付方式

约束：必须输入支付密码或指纹

SCN-006

步骤引导

覆盖层：navigational

语义绑定：action.primary

组件：Stepper + Button

文案：显示当前步骤和总步骤

约束：第一步禁用"上一步"

场景查询演示：设计师查询 SCN-001（删除账户）

字典返回：完整语义方案

scenario_id: "SCN-001"
name: "删除账户"
overlay: "transactional"
semantic_bindings:
  - "status.critical"
  - "action.destructive"
components:
  - "Alert"
  - "Button"
  - "Modal"
copy_constraints:
  - "必须包含'此操作不可恢复'"
  - "必须说明数据删除范围"
interaction_constraints:
  - "必须输入账户名二次确认"
  - "必须提供取消按钮"
  - "操作后跳转至登录页"

设计师获得：可直接执行的方案

✓ 语义方案既定，视觉探索在边界内展开

• 覆盖层：transactional → 阻断性语义

• 状态：status.critical → 红色脉冲 + 八边形

• 操作：action.destructive → 红色空心 + 二次确认

• 文案：必须包含"此操作不可恢复"

• 交互：必须输入账户名确认

✓ 无需重新争论，跨产品线语义天然一致

注册纪律：先注册、后引用

Registration Discipline · 非法引用在编译前置校验时直接阻断

✓ 合法引用

intent_id: "ERR-001"
semantic_domain: "transactional"  # ← 字典已注册

semantic_tokens:
  error_severity:
    fatal:
      visual_mapping:
        color_token: "status.critical"  # ← 字典已注册

编译通过 ✓

✕ 非法引用 — 被阻断

intent_id: "ERR-001"
semantic_domain: "transactional"

semantic_tokens:
  error_severity:
    fatal:
      visual_mapping:
        color_token: "status.danger"  # ← 字典未注册

[CI 阻断] dictionary-reference-not-found

Token "status.danger" 未在语义字典注册。

请先走字典变更流程：快照证据 → 诊断归档 → 候选模式 → 评审入典

字典是元规则，契约是只读消费面

语义字典（上游·元规则）→ YAML 契约（中游·实例）→ 编译管线（下游·执行）

返回 Schema-As-Code →