规范、设计与实现映射

状态：完整工作稿，拟议、可调整。本页定义追溯方法及示例记录，不代表已建立组件库、包依赖、设计文件或测试证据；D06 已决定以合成中性任务作为设计承载，真实实现项目、仓库和技术栈仍未确定，实际项目盘点、包映射、设计关联和任务测试仍待实施。 更新：2026-10-18（UTC+8） 所属章节：治理、交付与质量

1. 映射的目的与边界

映射使一个能力从“为什么需要”一直追到“实际怎样实现和验证”：

需求或任务 → 规范规则及版本 → 设计资产／Token → 平台实现 → 可运行样例 → 测试证据 → 使用产品与已知差异。

这条链不是要求所有资源同仓、同版本或使用同一工具。它要求每一跳有明确的稳定标识与主档，缺失之处如实显示。可运行样例称为 story、示例页面或测试夹具都可以，本页不指定 Storybook 或其他工具。

规范主档记录共同语义与行为；正式 API、安装和平台实现细节一旦随代码维护，应以相应仓库为主档，知识库保留背景、取舍和稳定入口，不维护第二份自称最新的 API。产品特有模型、公式与流程仍以产品主档或其正式规格为准。

当前阶段以通用组件和行业无关组合为对象，追溯链可以先建立到实际测试宿主与证据。尚未关联采用产品时如实记录，不以 AMKit 接入或真实业务审批作为组件契约完善的前置；产品集成另列阶段外未评估。文档夹具、可运行样例、真实平台运行与产品采用分别记状态，任何一层都不能代替下一层的证据。

2. 已知产品定位与未决承载关系

• YUDS：共同设计语言、组件契约、任务模式与质量要求。
• Teakit：TypeScript 库与框架的产品背景定位。
• Teasim：UI 体系的产品背景定位。
• 具体实现项目：负责把规范变成可使用的组件、平台适配和证据。
• 具体产品：负责领域模型、计算、流程配置、数据服务和任务应用。

Teakit／Teasim 的定位不自动回答“谁承载 YUDS”“是否直接依赖”“是否适用于所有平台”。本页不规定 YUDS = Teasim，不规定必须使用 TypeScript，也不由已有库名反推所有原生实现都要绑定该库。选型须比较真实现状、许可证、任务适配和维护能力，再单独记录决定。

背景入口：Teakit 产品定位与边界 ↗、Teasim 产品定位与边界 ↗。历史上已被替代的定位不再作为当前依赖判断依据。

3. 最小映射记录

为可独立变化的规则建立文档追踪 ID，当前分配与维护方法见第 12 节；文件编号继续承担阅读组织，两者不要混为版本号。早期示例“YUDS.DIALOG.FOCUS.RETURN”未分配，现以第 12 节登记为准。产品公共 API 命名仍待实现项目决定。

设计、代码、Token 已由上表分别记录版本；平台适配也须保留独立版本，不能用一个“组件版本”替代全部资产。对组件／组合记录再补以下最小字段，它们是追溯记录字段，不是已批准的组件 API：

弃用与迁移沿用上表 migration、第 12 节及贡献、决定、版本与迁移的迁移／弃用契约，不另建重复状态体系：记录旧／新版本、受影响组合与使用方、替代方案、弃用或移除条件及验证入口。没有实际迁移证据时只记录计划。发布稳定性、弃用状态、资产存在与测试结果各自独立，名称相同不自动继承另一端的版本或结论。

规范可以一对多映射到不同平台实现，一个实现也可能承担多条规则。映射必须保持语义对应，不能为了方便强行建立“一篇文档对应一个组件”的关系。

4. 示例：弹层焦点返回

以下为结构示例，没有实际包、设计资源或通过证据：

这样一条记录清楚表达规范已有提案、实现与验证尚无证据，不能被压缩成“弹层完成”。上表为既有结构示例，产品采用栏的“待选择参考任务”不构成当前前置；本阶段可先选独立的弹层组合夹具，产品采用另记尚未关联。

5. 设计交付如何进入实现

设计交付应包含用途、数据结构、状态、内容规则、交互、焦点、输入替代、主题密度和关键尺寸语义。静态高保真画面只是其中一项，不能迫使开发自行猜测空状态、服务失败或读屏行为。

设计与实现交接至少核对：

• 相同变体名称表达相同含义，避免设计中的“primary”与代码中的“primary”分别表示重要性和颜色。
• 同一 Token 的用途、取值与主题映射一致；不能仅因视觉相近就替换语义。
• 组件状态是数据驱动还是仅视觉变体；禁用、只读、加载和无权限分别定义。
• 表单事件、提交时机、验证和错误恢复的契约明确；业务计算不从示意数值推导。
• 布局约束表达为最小／最大、可换行、可滚动及内容增长行为，而不是仅固定截图坐标。
• 可访问名称、角色、状态、焦点与读屏反馈有说明，平台细节在实现主档补充。

实现受平台限制时，先说明无法满足哪项语义或验收要求，再提出适配方案及证据；不能默默删掉规则，也不能要求所有平台完全复刻一端的 DOM、单位或 API。

6. Token 与主题映射

每个已发布 Token 应能追到其语义、允许用途、主题映射、平台表示和弃用信息。既有 Token 的取值相同，不代表可以合并；是否独立由已确认的角色、职责或资源契约决定，不能据业务用途差异自行增加公共颜色别名。

颜色统一使用 Token 契约、主题与状态的七角色＋固定职责色阶，平台调用语法不同也保持同一 Token ID；本节不授权增加用途／组件颜色别名。排版使用 label／prose／heading 各九档及业务用途映射。

映射检查包括：未定义引用、非颜色资源的循环引用、公共颜色别名违规、孤立值、重复语义、主题缺项和平台单位转换。具体 Token 格式、生成工具与包结构尚未选择，本页不声称符合某个未采用的格式标准。

主题改变要沿映射追踪组件、图表、页面及视觉证据；密度和用户字号不应被硬编码在仅颜色主题的映射里。运行时切换涉及缓存、样式加载和状态保持，由实现项目定义并验证。

7. 样例和测试的职责

样例用于帮助理解与复现，测试用于检查明确契约。一个正常状态样例不能替代完整测试，也不能用截图文案描述不存在的后端能力。

每个高复用能力应按风险准备适用夹具：默认、内容增长、错误、加载、空、权限限制、部分结果、主题、密度、缩放、不同语言与输入。复杂模式还需真实或受控模拟的状态转换，不只展示若干互不连接的静态页面。

测试证据应固定到构建版本、环境和数据。测试报告不能永远指向会被后续运行覆盖的“最近一次”；可保留稳定运行标识或不可变报告。截图注意脱敏和访问权限，不能为可复现而公开真实客户数据。

当前夹具可使用固定合成对象与受控事件服务，须记录稳定 ID 和版本、输入数据、授权／披露条件、初态、事件顺序、操作与可观察输出。查询、取消、幂等和持久保存能力分别写明有／无分支；例如内存模拟不能证明生产服务防重或跨会话保存。正常链应覆盖入口、操作、结果与返回，并提供失败注入；只换掉行业字段名不算可复现夹具。

在实际宿主建立前，story_or_fixture 只记录文档夹具及未实现状态；建立后固定宿主构建、代码／Token／平台配置版本和依赖，再按质量基线、门禁与验收证据第 10 节保留完整环境、方法和证据。文档走查、模拟服务运行、真实平台输入与辅助技术测试分别记录；Q14.5 仍未满足，不能把产品采用阶段外解释为环境矩阵不适用。D01/D02/D05 初始设计配置已采用，真实产品审批制度缺失不一概阻止通用行为测试；测试结果须绑定实际配置，不替代设计决定或生产能力证据。

8. 现有资产的复用、适配与替换

对 Teakit、Teasim、其他内部项目或外部系统的资产，先盘点证据再决定：

据此可选择直接复用、加适配层、保留为产品特例、替换或暂不采用。每种选择附理由、验证和维护责任。不能因为“现有”就默认符合，也不能因为来自参考系统就整体移植其平台、品牌或实现承诺。

9. 例外登记与到期处理

例外应从使用处反向可查到规则。建议记录：

• 例外标识、规则及规范版本。
• 产品、实现包、页面、任务与环境范围。
• 偏离内容、产生原因、用户影响及风险。
• 补偿措施与可观察验证结果。
• 有权批准的人、一个明确责任人和批准依据。
• 开始日期、到期日期或明确退出条件，以及下一次复查安排。
• 整改计划、受影响使用方、关闭日期与验证证据。

到期检查应得出关闭、重新批准限定延期或限制支持的明确结果。缺少负责人、期限或依据的例外保持未批准，不能生成“默认长期允许”。统一规范不能通过各产品永久例外被悄悄掏空；重复例外应反过来触发规范是否适用的评估。

10. 防止文档与实现漂移

建议在变更入口加入映射检查：改规范时列出受影响设计、Token、实现和产品；改实现时确认是否符合原规范；改产品流程时检查是否仍使用相同任务模式。自动化可检查标识、链接、版本字段和声明状态，语义变化仍由人审阅。

定期或在相关发布时检查：

• 规范已变化而实现仍指旧版本。
• 实现行为已变但规范和变更记录未更新。
• 设计新增了未实现变体，示例却把它写成可用。
• 原有测试环境已失效，支持声明仍沿用旧结论。
• 例外过期、负责人离任、弃用入口仍被推荐。
• 正式 API 在知识库与代码仓库出现相互冲突的两份主档。

发现差异时先标清真实现状和影响，再选择修实现、修规范或批准限定差异。不能以“文档落后”一律要求规范迁就当前代码，也不能凭规范存在就声称当前代码已实现。

11. 映射验收清单

• 规则有稳定标识、版本、主档与决策状态。
• 设计、Token、包和产品职责没有互相替代。
• 实现包、组件入口、提交与环境均为真实可定位资源。
• story／样例和测试证据固定到相应版本，空缺如实标注。
• 通过、失败、未执行与不适用有区分。
• 已知差异、例外、期限和唯一责任人可查。
• 变更影响、迁移与弃用能反向找到使用方。
• 不存在未批准的 Teakit／Teasim 绑定或平台承诺。

目前完成的是映射方法与示例；实际项目盘点、包映射、设计关联和任务测试仍待实施。

12. 当前规范规则登记与逐端缺口

早期已分配的标识包括 FND、CMP、NAV、TASK、SCOPE、YUDS-六位编号-局部编号及 YUDS.六位编号.局部编号；后续组件与组合族保留各自已经登记的稳定 ID，不把它们改成同一种点分格式，也不批量改名。这些标识只用于文档追溯，不是组件属性、包名、产品 API 或版本发布批准。规则移动时保留 ID 并更新主档定位；删除时保留被替代关系，不把原 ID 分配给新含义。版本以知识库提交 SHA 固定；“P1 工作稿”仅是阅读阶段名，不能代替 SHA。

12.1 实际注册族与定位规则

同一个完整 ID 只能有一个规范定义主档；其他文件出现同一 ID 是引用。下表保留早期注册族及其定位方式，不是当前所有组件与扩展族的完整目录。p1-rule-register.json 及各批登记保持当时快照；当前组件、组合与扩展族的逐条定位和正文哈希以统一主档登记 ↗为准，不把历史登记回写为新位置。记录应保存完整 ID、主档六位编号、定义标题或规则表行、正文 SHA-256 及知识库提交。提交尚未产生时记录工作稿文件哈希，不能伪造提交 SHA。附件是可重建索引，权威正文仍是唯一主档。

斜线与短范围只用于压缩登记，不是新的字面 ID；例如 YUDS-090100-01 不能替换成未登记的 YUDS.090100.01。新增局部编号须先登记精确条目，不因匹配前缀就自动有效。A–E／W／G 与 Q- 等用例编号、CMP-LAYER-F2 等反例编号是夹具身份，应以“主档编号＋夹具 ID”定位，不混入规范定义主键。重名定义、无主档、悬空引用或把夹具当规范 ID 均阻止追溯检查通过；修正文案不能通过重新分配旧 ID 掩盖语义变化。

每条实现记录需展开到单条规则和单个平台，范围登记行不能代替单条追溯。设计资产、Token 配置、实现仓库／包／提交、平台适配版本、样例构建、实际测试和采用产品均分别填写。当前这些资源尚未关联核查，记录“未关联／未检查”，不据此断言项目不存在；组件／组合宿主可先独立建立，产品端到端集成单列“阶段外／未评估”。

发布前把每条记录的“待指定”换成实际责任人、批准依据和固定证据；缺项不默认继承另一端的通过。例外采用第 9 节同一台账，正文只保留例外 ID 和入口。证据以运行 ID／提交 SHA＋原始文件哈希固定；更正采用追加记录关联旧证据，禁止覆写失败报告为通过。

迁移先比较同一规则旧／新版本的用户可观察行为，列影响平台与使用方，再执行验证。回退代码不表示撤回已完成业务写入；退回旧文档也不删除新版本曾存在的事实。未关联真实调用方时，只能交付迁移计划，不宣称迁移完成。