| name | doc-layer-system |
| description | AI 驱动开发七层文档体系的可执行 skill（用户级通用）。在任何涉及代码开发、文档同步、代码审查、测试编写的任务中，Agent 必须遵循此体系的分层规则、人工裁决规则、同步流程和变更钩子机制。项目特定规则（目录路径、域列表、死亡线区域清单、金标准领域清单等）通过项目级 skill 补丁扩展，本 skill 不硬编码任何项目特定内容。触发场景：编写/修改代码或文档后需要同步、新增接口/数据库/页面功能、执行 /review、编写测试用例、处理文档与代码之间的矛盾、询问「这个东西该放哪里」或「这几个文档矛盾了听谁的」。 |
七层文档体系
本 skill 是七层文档体系的可执行版本，用户级通用，可跨项目使用。
项目特定约定（目录路径、域列表、死亡线区域清单、金标准领域清单等）通过项目级 skill 补丁扩展，不写进本文件。
0. 适用范围与形态映射
本 skill 的七层划分是功能性抽象，可跨技术形态使用。
| 抽象层 | 通用含义 | 常见实现形态 |
|---|
| L1 需求层 | 产品意图与业务规则的完整载体 | 功能文档、业务需求书、线框/原型图 |
| L2 交互规格层 | 用户可见的交互规格（可选层：无 UI 项目可省略） | Web/移动端页面视觉规格；CLI 的命令行交互规格；低保真交互流程图；状态页（loading/empty/error/disabled） |
| L3 契约层 | 系统对外暴露的接口契约 | HTTP REST API；RPC/gRPC；CLI 命令签名；事件 Schema；消息队列消息格式 |
| L4 持久化规格层 | 数据存储结构规格 | 关系型数据库表结构；KV Store Schema；文件格式规范；消息存储结构 |
| L5 客户端实现规约（可选层：无客户端项目可省略） | 客户端/前端的架构规范与主要链路 | Web/移动端前端；桌面端；CLI 客户端逻辑层 |
| L6 服务端实现规约 | 服务端/后端的架构规范与主要链路 | REST 后端；微服务；数据管道；定时任务系统；事件消费者 |
| L7 测试用例层 | 对 L1~L6 各层设计意图的验证规格 | 自动化测试用例规格；手工验证场景规格 |
L2 与 L5 是可选层：纯后端服务、CLI 工具、数据管道、事件驱动系统等项目，可在项目级补丁中声明省略 L2 和/或 L5，直接从 L1 接入 L3/L4/L6/L7。
0.1 审核能力矩阵
每层文档的每次正式变更，需要由具备对应审核能力的人确认。能力要求是通用约束，具体绑定到哪个角色/岗位/人，由项目级补丁声明；若项目缺失某项能力，也应在补丁中显式声明降级方案（例如「L4 副审由主审兼任」）。
| 层 | 主审所需能力 | 副审所需能力 |
|---|
| L1 需求 | 业务判断能力（能确认功能边界与业务规则） | 技术可行性判断能力 |
| L2 交互规格层 | 视觉与交互判断能力 | 客户端实现判断能力 |
| L3 契约层 | 契约设计能力（客户端 + 服务端双侧） | 测试设计能力 |
| L4 持久化规格层 | 存储设计能力 | 架构判断能力 |
| L5 客户端实现规约（架构治理类） | 架构判断能力 | 全体技术可参与 |
| L5 客户端实现规约（实现方案类） | 客户端实现判断能力 | 业务判断能力（涉及业务时） |
| L6 服务端实现规约（架构治理类） | 架构判断能力 | 全体技术可参与 |
| L6 服务端实现规约（实现方案类） | 服务端实现判断能力 | 业务判断能力（涉及业务时） |
| L7 测试用例 | 测试设计能力 | 业务判断能力（金标准） |
0.2 项目形态与层裁剪
不同项目形态适用不同的层组合。项目级补丁应在文件开篇声明当前形态（如 > 项目形态：纯后端）。
| 项目形态 | 适用层 | 省略层 |
|---|
| 全栈（前端 + 后端） | L1 / L2 / L3 / L4 / L5 / L6 / L7 | 无 |
| 纯后端（无独立客户端） | L1 / L3 / L4 / L6 / L7 | L2（无 UI）/ L5（无客户端） |
| 纯前端（对接外部 API） | L1 / L2 / L3 / L5 / L7 | L4（无自有持久化）/ L6（无自有服务端） |
| 纯前端（离线 / 无后端） | L1 / L2 / L5 / L7 | L3 / L4 / L6 |
说明：
- 「纯前端对接外部 API」场景中 L3 仍然适用，用于记录前端所依赖的外部 API 契约（只读，非自有）
- 裁剪后不适用的层在本项目中跳过，对应文档路径和扫描矩阵条目无效
- 项目补丁声明形态后，
code-to-7layer 反推 skill 会据此自动裁剪子任务列表
0.3 业务域与功能模块
本 skill 使用**「域/模块」**作为贯穿各层的组织轴：
- 有明确领域边界的项目（DDD 实践、微服务等）：以业务域（如「用户」「订单」「支付」）为轴
- 无明确领域边界的项目（按技术模块或功能分组）：以功能模块（如「认证」「消息推送」「管理后台」）为轴
两者组织方式完全等价，后文「域」均指「业务域或功能模块」，以项目实际情况为准。项目级补丁应在文件开篇声明域/模块列表。
1. 七层定义速查
| 层级 | 名称 | 核心问题 | 审核强度 |
|---|
| L1 | 需求层 | 产品是什么形态、有哪些功能、业务链路如何、交互原型是什么样的 | 🔴 diff 逐字审 |
| L2 | 交互规格层 | 用户/调用方看到的交互流程、界面状态、视觉规格具体是什么样的 | 🟡 方向性确认 |
| L3 | 契约层（接口层） | 系统与外部之间约定什么接口契约 | 🔴 diff 逐字审 |
| L4 | 数据库层 | 数据如何存储 | 🔴 diff 逐字审 |
| L5 | 客户端实现规约层（前端技术层） | 客户端/前端用什么技术、走什么主要业务链路、遵守什么架构规范 | 🔴 diff 逐字审（治理类） / 🟠 关键面抽查（实现方案类） |
| L6 | 服务端实现规约层（后端技术层） | 服务端/后端用什么技术、走什么主要业务链路、遵守什么架构规范 | 🔴 diff 逐字审（治理类） / 🟠 关键面抽查（实现方案类） |
| L7 | 测试用例层 | 怎样验证 L1~L6 各层的设计意图是否被正确实现 | 🟠 关键面抽查（金标准）/ 🟡 方向性确认（其余） |
审核强度说明：
- 🔴 diff 逐字审：对本次 diff（新增/修改行）逐字确认；存量内容不重审但评审人须确认 diff 与上下文一致。死亡线区域任何 diff 自动升级为 diff 逐字审 + 死亡线双轨审查。
- 🟠 关键面抽查：重点审架构规范的禁止模式清单、主要链路覆盖度、技术选型记录；其他细节抽查。
- 🟡 方向性确认：整体浏览方向一致、重要字段/状态无缺漏即可。
1.1 层间关系
裁决链（排序参考，非自动执行依据）：
L1 需求
↓
L2 交互层（可选：无 UI/交互界面时跳过）
↓
L3 契约层 ‖ L4 持久化规格层 （无一一映射，但有显式耦合面，见下方说明）
↓
L5 客户端实现规约（可选：无客户端时跳过） ‖ L6 服务端实现规约
↓
L7 测试用例
关于 L5/L6 与代码的关系：L5/L6 是设计型层，不是代码镜像层。它们是重大业务/技术裁决的锁定层——人在此审核拍板、锁定决策，AI 后续施工只能在框架内执行，不得自行重裁、不得违反已锁定的链路思维。L5/L6 文档对以下内容有效力：① 架构骨架与分层方向（脚手架结构、禁止越层方向）；② 跨模块红线/禁忌清单；③ 关键技术选型；④ 本层级/域/模块的全部核心业务链路——"核心业务链路"按决策风险轴判定（定义见 §5.5/§5.6 与 references/L5L6写作指南.md），不设数量上限：有多少条需人拍板的决策点/复杂编排，就逐条说明多少。只有真正的实现细节（私有方法、SQL、DTO/VO 转换、标准 CRUD、纯透传/字段映射）以代码为准、不视为冲突；核心决策不许落到"以代码为准"这一档。表达形式与禁列见 §5.5/§5.6。
关于同级层关系：L3 与 L4 没有一一映射关系，但存在显式耦合面——以下情形改动一层时需扫描另一层：① 接口字段直接透传表字段（字段名/类型相同）；② 表字段被接口响应引用；③ 枚举值在接口与表中共用。其他改动（如索引调整、内部注释变化）不触发跨层扫描。L5 ↔ L6 互不强制驱动，两者通过 L3 接口层对话。
1.2 版本归属与生命周期状态
禁止进度状态词（这些归任务总控/任务级设计文档，不进正式文档）：
已完成、开发中、已上线、测试中、待发布
版本归属字段（必填，记录能力属于哪个版本）：
| 场景 | 写法 |
|---|
| 文档对应单一版本 | > 版本归属：V2 |
| 文档跨多版本共用 | > 适用版本：V1、V2 |
| 跨版本长期成立 | > 版本归属：通用 |
生命周期状态字段（必填，记录文档自身的当前状态）：
| 状态值 | 含义 |
|---|
草稿 | 尚未经过正式审核 |
已审核 | 已经过主审角色确认，当前为真值 |
已废弃 | 对应功能已下线/移除，文档保留供参考 |
过时待修订 | 功能仍在，但文档与现状已有已知偏差，待修订 |
生命周期状态与版本归属组合使用：> 版本归属：V2 | 生命周期状态：已审核
1.3 文档元数据要求
每份 L1~L6 正式文档顶部必须包含以下必填字段：
| 字段 | 说明 |
|---|
版本归属 | 见 §1.2 规则 |
生命周期状态 | 见 §1.2 规则 |
推断元数据（不强制人工维护，由 Git/PR 系统推断）：
| 字段 | 推断来源 |
|---|
| 最后审核日期 | 对应 PR 合并时间 / 最后一次 commit 时间 |
| 最后审核人 | 对应 PR Reviewer / commit author |
项目补丁可声明推断脚本，将 Git 元数据注入文档头部的可选字段。
AI 在冲突分级（§2）时，若能推断出「文档上次合并时间早于代码相关变更时间」，应在报告中附注「文档可能过时（最后合并 X，相关代码已于 Y 变更）」作为裁决参考，不直接据此修改任何层。
2. 冲突处理规则
[!CAUTION]
这是本 skill 相对旧五层体系的最大改动：推翻了"AI 按裁决链自动修正低优先级层"的旧规则，改为三级分级处理。
适用范围：所有跨层冲突、任何层与代码的冲突。
2.1 三级冲突分级
| 级别 | 定义 | AI 动作 |
|---|
| L0 表面冲突 | 措辞/排版/字段注释/同义词差异，不影响语义 | AI 直接按裁决链上游对齐；在 PR 描述中列出已对齐项，无需停机 |
| L1a 局部语义冲突 | 业务规则/状态流/字段含义不一致，且影响面仅限单一未发布功能、非死亡线区域 | 标注 [SEMANTIC-DEFER]，允许继续当轮编码；但交付前必须完成裁决，未裁决不可合并 |
| L1b 跨域语义冲突 | 同 L1a 定义，但影响面跨已发布功能、跨域，或命中死亡线区域 | AI 立刻停止，明确报告冲突，请求人工裁决后继续 |
| L2 契约破坏冲突 | 接口签名/字段类型/数据库字段名/枚举值/鉴权方式不一致 | AI 立即停机 + 标红 + 默认拒绝继续编码，必须人工裁决后解锁 |
判断分级的辅助输入：变更面（是否涉及契约面）+ 死亡线标记（死亡线区域的任何语义冲突自动升级到 L2；非死亡线但跨已发布功能的语义冲突升级到 L1b）。
2.2 人工裁决流程（适用 L1 / L2 级）
- 立刻停止当前操作
- 明确报告冲突：「发现 [来源 A] 与 [来源 B] 不一致：[具体不一致内容]」
- 询问而非判断（四选一）：「请裁决：(a) 以 [来源 A] 为准，修订 [来源 B]；(b) 以 [来源 B] 为准，修订 [来源 A]；(c) 两边都不完整，需要在 [层] 补写新规则；(d) 无法当下判断，挂起任务。」
- 等待人的决定，不允许 AI 用裁决链"猜"哪个对
- 人做出决定后，AI 按人的指示统一更新所有相关层
禁止行为（L1 / L2 冲突）：
- ❌ AI 看到 L3 和代码不一致，自己按 L3 改代码
- ❌ AI 看到 L6 文档和代码主要链路不一致，自己按代码反写 L6
- ❌ AI 看到 L1 决策和 L2 页面不一致，自己按 L1 改 L2
- ❌ 任何"我觉得显然是 X 对"的自动行为
裁决链的唯一用途：告诉人"理论上谁优先"，供人做决定时参考；也作为 L0 表面冲突自动对齐的依据。不允许 AI 用它自动解决 L1/L2 冲突。
3. 变更钩子机制
「变更钩子」是当文档/代码改动时，主动扫描有依赖关系的下游层是否需要跟着改的机制。
3.1 改动扫描矩阵
| 改动来源 | 必须扫描的下游 |
|---|
| L1 需求变更 | L2 页面、L3 接口、L4 数据库、L7 金标准测试；L5/L6 核心业务链路（仅当 L1 调整命中已登记的决策点/编排时） |
| L2 页面变更 | L3（页面新增字段/操作时）、L5 前端技术、L7 测试 |
| L3 接口变更 | L5 前端技术、L6 后端技术、L7 接口测试 |
| L4 数据库变更 | L6 后端技术、L7 实现验证测试；L3（命中显式耦合面：字段透传/接口引用/共用枚举时） |
| L5 前端技术变更 | 前端代码、L7 前端测试 |
| L6 后端技术变更 | 后端代码、L7 实现验证/金标准测试 |
| 代码变更（按位置细化） | 见下方展开表 |
代码变更扫描展开表：
| 代码改动位置 | 必须扫描 |
|---|
| Controller / DTO / VO / 接口签名 | L3 接口层、L7 接口验证测试 |
| Entity / Migration / Repository 映射 | L4 数据库层、L7 实现验证测试 |
| Service / Repository 业务规则、状态机、判定逻辑 | L1 业务规则、L6 状态机描述、L7 金标准测试 |
| 架构骨架（包结构/分层/命名规范）变更 | L5/L6 架构治理类 |
| 前端页面/组件/状态管理/服务层封装 | L2 视觉规格（如有）、L5 业务链路 |
| 算法核心（死亡线区域） | L1 业务规则、L7 金标准、要求用户审查 |
| 私有方法、严格不改变结果集语义的 SQL 优化（同结果集/同顺序/同分页语义）、样式微调 | 不触发扫描 |
| SQL 优化涉及 join 方式/去重策略/排序/分页语义/隔离级别变化 | L4 数据库层、L6 后端技术、L7 实现验证测试 |
3.2 钩子实现三层联动
- AI 主动扫描层：AI 在执行任务时，按 §3.1 矩阵主动扫描；发现不一致 → 人工裁决
- 脚本检查层：项目可选地实现
post-change-check 脚本，文件改动后自动跑（示例（MyApp）：.claude/hooks/post-change-check.sh）
- 评审拦截层：评审工作流中作为强制检查项（项目可自定义触发器与命名，如 /review）
4. 开发流程同步规则
4.0 工作模式选择
在开始具体开发流程前，先选定当前工作模式：
| 模式 | 适用场景 | 文档要求 |
|---|
| 施工模式（默认） | 正常功能开发、计划内修改 | 按 §4.1~§4.4 线性流程，先更新文档再编码 |
| 设计探索窗口 | 技术预研、产品原型、PoC 验证，或需求边界未定时的并行实现 | 允许先编码（提交标注 [EXPLORATORY]），步骤 1~3 文档与代码可并行推进；必须选择以下两个出口之一：① 探索结束 → 冻结 L3/L4 契约（进入「已审核」状态）→ 切换到施工模式；② 探索作废 → 弃稿，不留 [EXPLORATORY] 残骸在主干 |
| 止血模式 | 线上故障紧急修复、安全漏洞 | 允许直接改代码（提交标注 [HOTFIX]）；要求 24 小时内补齐 L3/L4/L6 变更记录与 L7 回归测试 |
| RCA 模式 | Bug 归因不明，需要先做证据收集 | 先复现 + 收集证据，再判定属哪一层的偏差；不强制开局判定层，进入 §4.3 时再走对应流程 |
§4.3 Bug 修复：若可立刻判定 bug 属哪层偏差，直接按原有步骤；若不可判定，先进入 RCA 模式做证据收集和归因，再决定走哪条路径。
契约冻结定义：L3/L4 文档的生命周期状态进入「已审核」即视为契约冻结。契约冻结后，任何 L3/L4 修改按 §4.2「改接口/数据库」分支处理，不得退回设计探索窗口。
4.1 新增功能开发
步骤 1：确认 L1（需求是否已覆盖此功能）
↓ 如果 L1 未覆盖 → 先与用户确认，更新 L1
步骤 2：更新 L2（页面视觉规格，如适用）（无 UI 的项目跳过此步骤）
步骤 3：更新 L3（接口契约）+ L4（数据库设计）
↓ 用户确认 → "L3/L4 已审核"
步骤 4：编写代码（按 L5/L6 架构规范执行）
步骤 5：检查 L5/L6 主要链路描述是否与新代码对齐（如有偏差 → 人工裁决）
步骤 6：编写/更新 L7（测试用例）
步骤 7：执行评审动作（项目可自定义触发器与命名，如 /review）
4.2 修改现有功能
步骤 1：判断修改范围
├─ 仅实现优化（不改接口/行为）
│ → 改代码 → 检查 L5/L6 主要链路是否需要更新 → 更新 L7
├─ 改接口/数据库
│ → 先更新 L3/L4 → 用户确认 → 改代码 → 检查 L5/L6 → 更新 L7
└─ 改功能设计
→ 先更新 L1/L2 → 用户确认 → 改代码 → 检查 L3/L4/L5/L6 → 更新 L7
遇到冲突：任何步骤中发现两层不一致 → 人工裁决，不继续执行。
4.3 Bug 修复
步骤 1：定位 bug 属于哪一层的偏差
├─ 代码不符合 L3/L2 → 报告冲突，等用户确认是改代码还是改文档
└─ 某层设计本身有问题 → 请示用户修改对应层
步骤 2：按用户决定修改代码
步骤 3：检查相关层是否需要更新
步骤 4：补充/更新 L7 测试（确保此 bug 不再回归）
4.4 版本调整
步骤 1：在 L1（项目总览）更新当前发布版本或版本边界
步骤 2：更新对应模块 L1 的版本归属
步骤 3：更新 L2/L3/L4/L5/L6 的版本归属（如受影响）
步骤 4：更新 L7 的版本归属，只让当前发布版本资产进入当前准入
5. 各层文档编写规则
每层规则的完整字段结构：层定位 / 核心问题 / 职责边界 / 应包含 / 不应包含 / 文档路径模板 / 审核强度 / 裁决位置 / 变更触发 / 下游联动 / 与代码的关系
5.1 L1 需求层
层定位：七层体系最高层，是产品形态的完整载体。使用产品/业务语言（文字描述）或交互原型（Figma 线框/原型图）表达。所有下游层的设计必须能回溯到某条 L1 的功能或业务规则。
核心问题：产品是什么形态、有哪些功能、业务链路如何、交互原型是什么样的。
职责边界：
L1 管：产品目标与用户价值；功能列表（用户能做哪些操作）；业务链路（含关键判定点与分支）；业务规则（约束条件/触发逻辑/计算规则的业务语言表述）；异常边界；交互原型（线框图/Figma 链接/文字描述布局与交互）；版本边界。
L1 不管：UI 视觉规格（颜色/字体/样式，归 L2）；接口字段契约（归 L3）；表名/字段/SQL（归 L4）；框架/库/中间件选型（归 L5/L6）；测试验证规格（归 L7）；进度状态词。
应包含：产品目标、用户价值、功能列表、业务链路（含分支）、业务规则、异常边界、交互原型（满足以下之一：Figma 线框/原型图截图、Figma 链接、文字描述布局与交互）、版本归属。
禁止用实现语言替代需求表达（口诀：这里写的是「业务是什么」还是「代码怎么做」？）：
- ❌ 用调用链替代需求（「调用
UserService.checkPermission」）、用循环替代规则（「for 遍历订单」）
- ✅ 允许引用精确字段名/错误码/枚举值/公式名作为需求规则的精确锚点：「VIP 等级满足
level >= 3」「错误码 USER_BANNED」「积分按消费金额百分比计算」
- 区别：引用精确标识 ≠ 用实现替代需求表达；精确锚点是让需求可以无歧义地被验证
L1 与 L2 分工：L1 保留业务目标、用户流程主干、核心场景与业务规则；交互细节（含低保真流程图、状态页、交互说明）归 L2 交互规格层。L2 是高保真视觉设计稿或交互规格文档（"交互流程/界面状态具体是什么样"）。
文档路径模板：
通用模板：{docs_root}/01-需求/01-{NN}-{domain_name}/
示例（MyApp）：docs/01-需求/01-{NN}-{domain}/
审核强度：🔴 diff 逐字审。每条业务规则、每张原型图都必须人类逐字确认。
裁决位置：顶端。与其他层冲突时理论上 L1 优先——但发现冲突时不允许 AI 自动覆盖下游，必须人工裁决。
变更触发：产品方向调整、功能增减、业务链路变化、业务规则/异常边界变更、交互原型实质性改动、版本边界调整。不触发：UI 视觉规格调整（归 L2）；接口/数据库/前后端技术变化（归对应层）。
下游联动：L2（功能/交互形态变化）、L3（接口相关业务规则变化）、L4（持久化业务概念变化）、L7 金标准（核心业务规则变化）。发现不一致 → 人工裁决。
与代码的关系：描述型。代码行为必须与 L1 功能描述一致；代码实现细节变化不要求 L1 更新；发现不一致 → 人工裁决。
5.2 L2 交互规格层
层定位：可选层，位于 L1 之下、L3 之上。回答交互规格问题：用户/调用方看到的交互流程、界面状态（正常/加载/空/错误/禁用）、视觉呈现如何规格化。读者是设计师、界面开发者、交互评审者。L2 支持精简形态（文字描述交互流程 + 状态页说明，无专职设计师时合法）和完整形态（高保真设计稿 + 交互规格）。
核心问题：这个功能区的交互流程、界面状态、视觉规格具体是什么样的。
职责边界：
L2 管：配色方案（颜色规格）；字体规格（字号/字重/行高）；组件视觉样式；间距与布局；视觉状态（正常/禁用/加载中/空/错误的视觉形态）；图标与图片的视觉规格；高保真设计稿。
L2 不管：业务目标/用户流程主干/业务规则（归 L1）；接口字段契约（归 L3）；数据库结构（归 L4）；前端组件实现方案/CSS 代码/动画细节（归 L5）；进度状态词。
应包含（精简/完整形态二选一）：
- 精简形态（对视觉要求不高时）：每个功能区的交互流程描述（步骤级）；所有界面状态的文字说明（正常/loading/empty/error/disabled/permission）；全局视觉约定（如有则注明来源）。允许低保真 wireflow、状态页流程图。
- 完整形态（有专职设计师时）：高保真设计稿截图或 Figma 高保真页面链接；颜色/字体/间距规格；所有重要视觉状态的设计稿；交互流程图
两种形态均需标明：所属功能域、版本归属。
Figma 归属规则：同一 Figma 文件中，线框/原型页面 → L1；高保真视觉设计页面 → L2。
文档路径模板：
通用模板：{docs_root}/02-交互规格/{platform_or_domain}/
示例（MyApp）：docs/02-交互规格/{platform}/
项目级补丁挂载点（项目特例，不进通用规则）：多平台项目可按平台或业务域组织子目录，每份文档元数据头声明所属业务域（所属业务域）。
审核强度：🟡 方向性确认。整体浏览确认视觉方向一致、重要状态覆盖完整。
裁决位置：第二层。L2 向 L1 负责；L2 对 L5 有约束（前端视觉还原须与 L2 一致）。冲突时人工裁决。
变更触发：L1 功能/交互变化（检查页面视觉设计是否需要跟进）；品牌/视觉规范调整；设计评审反馈；视觉还原后设计稿不可实现（前端反馈）。不触发：接口字段/数据库/前端实现方案变化；业务规则文字变化但页面视觉不变（归 L1）。
下游联动：L5（页面视觉规格变化）、L7（重要视觉状态新增/修改）。发现不一致 → 人工裁决。
与代码的关系：描述型。前端实现的颜色、字体、间距须与 L2 一致（在 L2 管辖范围内）；代码实现手段（用什么 CSS/库）自由；发现不一致 → 人工裁决。
5.3 L3 契约层（接口层）
层定位：系统对外暴露契约的规格层。调用方读 L3 知道"能发什么请求/调用、期望收到什么响应"；实现方读 L3 知道"必须遵守什么契约"。L3 以字段级契约（字段名/类型/必填性/语义）表达，不限定传输协议形态。L3 与 L4 同级独立，互不强制驱动对方变更。
核心问题：前后端之间约定什么字段、什么契约。
职责边界：
L3 管：HTTP 方法 + 请求 URL；请求参数（含 query 参数和 body 字段）；响应体结构（含列表分页结构）；接口专属错误码；前置条件；状态流（接口触发或依赖的状态变更）；版本归属。
L3 不管：数据库表结构/字段/索引（归 L4）；后端实现细节（算法/缓存/中间件，归 L6）；前端调用实现（状态管理/错误重试，归 L5）；业务功能背景/用户价值（归 L1）；UI 视觉（归 L2）；测试脚本（归 L7）；进度状态词。
应包含：HTTP 方法 + URL；请求参数表（字段/类型/必填/说明，含列表接口的游标分页字段）；响应体结构（外壳 + data 字段）；接口专属错误码表（code/含义/触发条件）；前置条件；状态流（如适用）；版本归属。
字段边界判定（口诀：调用方看到这个字段，能知道"发什么、收什么"吗？）：
- ✅
cursor: string，选填，上次响应返回的 cursor 值
- ❌
cursor 存储在 Redis Hash，key 格式为 user:{uid}:cursor（实现细节，归 L6）
- ✅
错误码 10001：资源已过期；❌ 当 resource_token 在 DB 中不存在时返回 10001（触发实现细节，归 L6）
L3 与 L6 状态/错误责任划分：
| 类别 | L3（外部可观察，由 L3 负责） | L6（内部实现，引用 L3 不重述） |
|---|
| 状态枚举值 | 定义并列出 | 引用 L3，不重述 |
| 接口调用导致的外部可观察状态转换 | 是 | 引用 L3 |
| 内部状态机（重试/补偿/定时回收等不经接口暴露） | 否 | 是 |
| 错误码（code + 含义 + 业务语言触发条件） | 是 | 引用 L3 |
| 失败处理策略（重试/降级/回滚/补偿） | 否 | 是 |
L3 不单独维护状态流图：L3 只声明对外可观察状态枚举与转移规则（哪些外部接口调用触发哪个状态转换），不维护完整的状态机图。完整领域状态机（含内部子态、超时、补偿）由 L6 持有，L6 同时维护「对外可观察状态投影表」映射到 L3 枚举值。
L3 文档组织：全局规则文件（一份：HTTP 方法约束、鉴权方案、响应外壳格式、分页规则、全局错误码、模块索引）+ 域级接口文件（每业务域一份：字段级契约）。
文档路径模板：
全局规则：{docs_root}/{L3_root}/00-全局接口规则.md
域级接口：{docs_root}/{L3_root}/{NN}-{domain_name}接口.md
示例（MyApp）：docs/03-技术设计/接口/00-全局规则.md（全局）
docs/03-技术设计/接口/{NN}-{domain}接口.md（域级）
项目级补丁挂载点（项目特例，不进通用规则）：项目可在此声明 HTTP 方法约束（如仅 GET/POST）、参数规范（POST 参数放 body）、翻页规则（游标/页码）、响应包装格式（如统一包装体）、鉴权方案（如 JWT）等。
审核强度：🔴 diff 逐字审。接口字段是前后端技术合同，每个细节都可能导致联调失败。
裁决位置：第三层，与 L4 同级。向 L1/L2 负责；下游 L5/L6/L7 依赖 L3。L4 不在 L3 联动范围内（同级独立）。冲突时人工裁决。
变更触发：L1 新增/删除接口相关功能；L2 变更导致新增/修改字段；联调发现字段不匹配；鉴权方案变更；错误码新增/修改。不触发：数据库新增索引（归 L4）；后端实现优化（接口行为不变，归 L6）；前端调用方式调整（接口契约不变，归 L5）。
下游联动：L5（请求参数/响应/错误码变化）；L6（接口新增/字段变化/状态流变化）；L7 接口验证测试（任何接口变更）。L4：仅当触发「L3/L4 耦合面」（§1.1）时需主动扫描；其他情形不在联动范围内。发现不一致 → 冲突分级处理（§2）。
与代码的关系：契约型。L3 是对外承诺，代码实际行为必须与 L3 一致；代码内部的算法/数据结构/调用链路变化（接口行为不变）不要求 L3 更新；发现不一致 → 人工裁决。
5.4 L4 数据库层
层定位：存储结构的真值层。后端开发者/DBA 读 L4 知道"有哪些表、哪些字段、类型和约束是什么、表间如何关联"，无需读代码或逆向数据库。L4 与 L3 同级独立，互不强制驱动对方变更。
核心问题：数据如何存储。
职责边界：
L4 管：表名与用途说明（业务语言）；字段列表（字段名/数据类型/是否可空/默认值/说明）；索引（索引名/字段组合/类型/用途说明）；约束（唯一/非空/外键）；表关系（业务语言描述引用关系）；版本归属。
L4 不管：接口字段格式/请求响应体（归 L3）；ORM 实体代码（归 L6）；业务状态机/状态流转逻辑（归 L6）；SQL 查询语句（归 L6）；数据迁移脚本 Migration（归代码库）；进度状态词。
应包含：表名与用途说明；字段列表（覆盖全部字段）；索引表（含用途说明）；约束；表关系（业务语言）；版本归属。
字段边界判定（口诀：开发者看到这个字段描述，能知道"存什么、类型是什么、有什么约束"吗？）：
- ✅
status tinyint NOT NULL DEFAULT 0，枚举：0=进行中 1=已完成
- ❌
当 status=1 时触发积分结算，调用 PointService.settle()（业务逻辑，归 L6）
与执行资产的关系：DDL 建表语句和 Migration 脚本是 L4 的执行绑定资产，L4 文档是其设计视图。每条 L4 表结构条目必须与至少一个 migration 文件建立稳定引用（仓库相对路径 + 版本/序号），使 L4 可追溯验证。Migration 脚本的内容以代码库为准；L4 文档是「表结构是什么」的规格描述。若 migration 与 L4 描述不一致，按 §2.1 L2 契约破坏冲突处理。
不包含：ORM 实体类代码；接口 DTO/VO；SQL 查询语句。
L4 文档组织：全局规则文件（一份：全局约束、Owner 矩阵、域列表与文件导航）+ 域级数据库文件（每业务域一份）。
文档路径模板：
全局规则：{docs_root}/{L4_root}/00-README.md
域级文件：{docs_root}/{L4_root}/{NN}-{domain_name}.md
示例（MyApp）：docs/03-技术设计/数据库/00-README.md（全局）
docs/03-技术设计/数据库/{NN}-{domain}.md（域级）
项目级补丁挂载点（项目特例，不进通用规则）：项目可在此声明 ID 生成策略（如 Snowflake/UUID）、必填公共字段（如 create_time/update_time）、ORM 映射规范、跨域引用约束等。
审核强度：🔴 diff 逐字审。字段名/类型/约束直接影响 ORM 映射和数据完整性。
裁决位置：第三层，与 L3 同级。向 L1/L2 负责；下游 L6/L7 依赖 L4。L3 与 L4 之间按「显式耦合面」规则（§1.1）决定是否互扫：耦合面被触发才扫，其他情形不触发。冲突时按 §2 冲突分级处理。
变更触发：L1 新增/变更业务实体；DDL Migration 执行后（需同步 L4 保持规格与现实一致）；索引新增/删除；约束变更；表新增/废弃。不触发：接口字段格式变化（归 L3）；后端业务逻辑变化（不影响表结构，归 L6）；ORM 代码重构（不改字段名/类型）。
下游联动：L6（字段名/类型/约束/表变化）；L7 实现验证测试（字段/约束变化）。发现不一致 → 人工裁决。
与代码的关系：契约型。L4 是存储规格说明，DDL 和 ORM 代码必须实现规格；Migration 脚本是实现手段，属代码库，不归 L4 跟踪；发现不一致 → 人工裁决。
5.5 L5 客户端实现规约层（前端技术层）
层定位：可选层，与 L6 同级，适用于有独立客户端的项目（Web/移动端前端、桌面端、CLI 客户端等）。同时承担两个等重职责，缺一不可：
- 防腐约束：记录前端架构宪法——脚手架结构、目录规范、框架分层、编码哲学、禁止模式。跨会话长期有效，防止开发者（人或 AI）跨时间做出漂移的架构决策（跨会话失忆导致的一致性缺失）。
- 技术实现方案的唯一用户审核层：记录主要业务链路的前端实现方案、状态管理策略、服务层调用模式、关键技术选型。用户无需读代码，在 L5 层面与开发方形成共识并作为验收基准。
L5 是设计型层，不是代码镜像层。在 L5 管辖范围内，文档 > 代码；代码细节（函数内部逻辑、样式写法）自由实现；L5 不腐烂，因为不追代码细节。
L5 是重大决策的锁定层：所有需人拍板的前端业务/技术裁决在此审核、锁定；AI 后续施工只能在框架内执行，不得自行重裁、不得违反已锁定的链路思维。人据此验收，AI 据此施工——人和 AI 都看得懂是硬要求。
核心问题：前端用什么技术、走什么主要业务链路、遵守什么架构规范。
职责边界：
L5 管：脚手架与目录结构（精确到模块级）；框架分层设计（层级名称/各层职责/禁止越层方向）；模块划分；文件命名约定；编码规范与禁止模式（含明令禁止的反模式及理由）；主要业务链路（步骤级端到端流程，不精确到代码行）；状态管理策略；服务层调用模式；关键技术选型。
L5 不管：函数/方法内部实现；CSS/样式代码（可说"使用 SCSS"，不写具体规则）；第三方库内部 API 说明；与 L3 重复的接口字段定义；后端业务链路（归 L6）；UI 视觉规格（归 L2）；进度状态词。
应包含（拆为两类，可合并为单文件）：
- 架构治理类（防腐约束）：脚手架结构图（到模块级，每目录标注职责）；框架分层设计（分层名称/各层职责/层间通信/禁止越层方向需明确标注）；模块划分；文件命名约定；编码规范清单（命名约定/代码风格/明令禁止的反模式）
- 核心业务链路清单（用户审核层）：本层级/域/模块的全部核心业务链路——按决策风险轴判定（见下方「核心业务链路定义」），不设数量上限，有多少需人拍板的决策点/复杂编排就逐条写多少；状态管理策略（机制选型/主要 store 划分/跨组件数据流向）；服务层调用模式（API 封装方式/统一错误处理）；关键技术选型决策记录。只有纯实现细节（函数内部逻辑、CSS 写法、第三方库具体用法）以代码为准、不要求在 L5 记录。
- 表达形式（强制）：核心链路用精炼语言 / 表格 / 图说明，每条至多附一个轻量代码锚点（组件/模块名）供定位。禁止：代码、伪代码、逐方法实录（"A 组件调 B 服务"式的代码复述）、逐句证据尾注、状态/置信度标注、漂移登记。详见
references/L5L6写作指南.md。
核心业务链路定义（决策风险轴）：判定试金石——「不写下来的话，一个有能力的 AI 在施工时，会不会做出一个看起来合理、但和团队已拍板结果不同的选择？」会 → 进 L5；只有一种合理写法（纯 CRUD/透传/字段映射/标准操作）→ 不进，代码自由。两种形态：① 决策点（前端如：状态管理粒度、缓存一致性策略、并发更新处理、错误重试/降级策略、乐观更新与否）；② 复杂业务编排（多步交互流程：步骤顺序 + 每步为什么 + 关键取舍）。
L5 管辖范围（文档 > 代码）vs 代码自由范围：
- 管辖：架构骨架与分层方向（脚手架/目录/分层/禁止模式）；跨模块红线/禁忌清单；全部核心业务链路（决策点 + 复杂编排，无数量上限）；技术选型
- 代码自由：纯实现细节——函数/方法内部逻辑；CSS/样式细节；第三方库具体用法；性能微调；只有一种合理写法的标准操作
文档路径模板：
通用模板：{docs_root}/{NN}-前端技术/
多端项目：{docs_root}/{NN}-前端技术/{platform}/
示例（MyApp）：docs/03-技术设计/前端/{platform}/
L5a/L6a 全局一份文件（改动少）；L5b/L6b 按域/功能域分文件（随功能演进）。
建议文件拆分方式（规模较大时）：
{platform}/
L5-架构规范.md ← 脚手架 + 框架分层 + 编码规范（全局，改动少）
L5-业务链路.md ← 各功能域主要业务链路（按功能域分节）
L5-技术选型.md ← 技术选型决策记录（变化少）
审核强度：
- L5a 架构治理类（脚手架/目录/分层/命名/禁止模式）：🔴 diff 逐字审。变更频率低但影响全局，每次改动必须仔细审。
- L5b 实现方案类（主要业务链路/状态管理/外部依赖/技术选型）：🟠 关键面抽查。随功能演进，审关键路径和选型决策是否记录完整。
裁决位置：第五层，与 L6 同级独立（通过 L3 接口层对话）。向 L1/L2/L3 负责。任何冲突 → 人工裁决。
变更触发：L1 业务链路变化；L2 交互变化影响前端状态管理；L3 接口变化影响前端调用链路；技术选型决策变更；架构规范调整。不触发：代码内部实现细节调整（主要链路走向未变）；CSS 细节调整；L3 接口字段新增但 L5 描述链路步骤未变。
下游联动：前端代码（架构规范或主要链路变更）；L7（主要业务链路新增/修改）。发现不一致 → 人工裁决。
与代码的关系：设计型。在架构规范、主要业务链路、技术选型范围内文档 > 代码；其余代码自由实现；发现不一致 → 人工裁决。
5.6 L6 服务端实现规约层（后端技术层）
层定位：与 L5 客户端实现规约层完全对称，面向服务端/后端代码库。同时承担两个等重职责，缺一不可：
- 防腐约束：记录后端架构宪法——包结构规范、框架分层（Controller → Service → Repository）、类命名规范、禁止模式。跨会话长期有效，防止越层调用、业务逻辑下沉等架构漂移。
- 技术实现方案的唯一用户审核层：记录主要业务链路的后端实现方案、关键状态机、定时任务、外部依赖、关键技术选型。用户无需读代码，在 L6 层面与开发方形成共识并作为验收基准。
L6 是设计型层，不是代码镜像层。在 L6 管辖范围内，文档 > 代码；私有方法、DTO 转换、SQL 细节自由实现；L6 不腐烂，因为不追代码细节。
L6 是重大决策的锁定层：所有需人拍板的后端业务/技术裁决在此审核、锁定；AI 后续施工只能在框架内执行，不得自行重裁、不得违反已锁定的链路思维。人据此验收，AI 据此施工——人和 AI 都看得懂是硬要求。
核心问题：后端用什么技术、走什么主要业务链路、遵守什么架构规范。
职责边界：
L6 管：包结构与目录规范（到模块/域级）；框架分层设计（Controller→Service→Repository，各层职责/层间单向依赖约束/禁止反向调用禁止越层）；模块/域划分；类命名规范（Controller/Service/Repository/DTO/VO/Entity 等）；编码规范与禁止模式；主要业务链路（Controller→Service→Repository 关键路径，步骤级）；关键状态机（状态枚举/合法转换路径/触发条件）；定时任务（名称/调度频率/业务意图）；外部依赖（依赖服务/交互模式/集成点/失败处理策略）；事务边界；关键技术选型。
L6 不管：私有 helper 方法实现；DTO/VO/Entity 字段转换细节；标准 CRUD Repository 操作；配置类/常量类的具体代码；与 L3 重复的接口字段定义；与 L4 重复的表结构详情；前端链路细节（归 L5）；进度状态词。
应包含（拆为两类，可合并为单文件）：
- 架构治理类（防腐约束）：包结构说明（精确到模块/域级，每包标注职责与允许包含的类型）；框架分层设计（分层名称/各层职责/禁止越层方向需明确标注）；模块/域划分；类命名规范；编码规范清单（命名约定/代码风格/明令禁止的反模式）
- 核心业务链路清单（用户审核层）：本层级/域/模块的全部核心业务链路——按决策风险轴判定（见下方「核心业务链路定义」），不设数量上限，有多少需人拍板的决策点/复杂编排就逐条写多少（步骤级，非代码级）；完整领域状态机（含内部子态/超时态/补偿态 + 对外投影映射表）；定时任务清单；外部依赖说明；事务边界说明；关键技术选型决策记录。只有纯实现细节（私有方法、SQL、DTO/VO 转换、标准 CRUD）以代码为准、不要求在 L6 记录。
- 表达形式（强制）：核心链路/决策点用精炼语言 / 表格 / 图说明，每条至多附一个轻量代码锚点（类名/模块名）供定位。禁止：代码、伪代码、逐方法实录（"A 类调 B 类"式的代码复述）、逐句证据尾注、状态/置信度标注、漂移登记。反推中发现的漂移/缺口/技术债不进 L6 正文，去独立技术债登记文档。详见
references/L5L6写作指南.md。
核心业务链路定义（决策风险轴）：判定试金石——「不写下来的话，一个有能力的 AI 在施工时，会不会做出一个看起来合理、但和团队已拍板结果不同的选择？」会 → 进 L6；只有一种合理写法（纯 CRUD/透传/字段转换/标准操作）→ 不进，代码自由。两种形态：① 决策点（后端如：批量查 vs 循环查库、要不要做缓存及缓存边界、事务边界放哪、同步 vs 异步执行、幂等如何保证、并发如何处理）；② 复杂业务编排（多步业务流程：步骤顺序 + 每步为什么 + 关键取舍）。
L6 状态机与 L3 的关系：L6 持有完整领域状态机定义，包括内部子态、超时态、补偿态、重试机制。其中「对外可观察的状态投影」必须与 L3 声明的对外状态枚举存在明确映射表（格式：领域内部状态 → L3 对外枚举值），且不得与 L3 枚举值相矛盾。L6 不负责定义 L3 枚举，只负责说明内部状态如何映射到 L3 枚举。（见 §5.3 L3 不单独维护状态流图）
L6 管辖范围（文档 > 代码）vs 代码自由范围：
- 管辖：架构骨架与分层方向（包结构/分层设计/模块划分/类命名/禁止模式）；跨模块红线/禁忌清单；全部核心业务链路（决策点 + 复杂编排，无数量上限）；完整领域状态机；定时任务；外部依赖；技术选型
- 代码自由：纯实现细节——方法内部逻辑；DTO/VO 转换细节；SQL 实现；配置代码；性能微调；只有一种合理写法的标准 CRUD 操作
文档路径模板：
业务域文档：{docs_root}/{NN}-后端技术/{domain_name}/L6-{domain_name}.md
架构规范： {docs_root}/{NN}-后端技术/L6-架构规范.md
示例（MyApp）：docs/03-技术设计/后端/{domain}/（业务域）
docs/03-技术设计/L6-架构规范.md（全局架构规范）
L5a/L6a 全局一份文件（改动少）；L5b/L6b 按域/功能域分文件（随功能演进）。
审核强度：
- L6a 架构治理类（包结构/分层/命名/禁止模式）：🔴 diff 逐字审。变更频率低但影响全局，每次改动必须仔细审。
- L6b 实现方案类（主要业务链路/关键状态机/定时任务/外部依赖/技术选型）：🟠 关键面抽查。随功能演进，审关键路径和选型决策是否记录完整。
裁决位置：第六层，与 L5 同级独立。向 L1/L3/L4 负责。任何冲突 → 人工裁决。
变更触发：L1 业务链路变化；L3 接口变化影响后端处理链路；L4 数据库变化影响 Service/Dao 操作模式；技术选型变更；架构规范调整；新增定时任务或外部依赖。不触发：私有方法重构（业务逻辑不变）；DTO/VO 转换方式调整；SQL 优化（主要链路走向未变）；新增标准 CRUD 操作。
下游联动：后端代码（架构规范或主要链路变更）；L7（主要业务链路新增/修改、关键状态机变更）。发现不一致 → 人工裁决。
与代码的关系：设计型。在架构规范、主要业务链路、关键状态机、定时任务、外部依赖、技术选型范围内文档 > 代码；其余代码自由实现；发现不一致 → 人工裁决。
5.7 L7 测试用例层
层定位：最底层，被 L1~L6 共同驱动。L7 是规格层，不是执行层：描述"测什么、用什么场景、期望什么结果"；测试脚本是执行产物，不属于 L7 文档范畴。L7 通过了 = 代码正确实现了上游各层设计；L7 未通过 = 触发向上溯源诊断链。
核心问题：怎样验证 L1~L6 各层的设计意图是否被正确实现。
四类测试用例资产：
| 类型 | 验证对象 | 典型形态 | 可否删除 |
|---|
| 契约测试用例 | L3 契约层（接口签名/字段/错误码/状态流） | API 集成测试、mock 测试 | 契约废弃后可删 |
| 持久化不变量测试用例 | L4 持久化规格层（表/字段/索引语义/唯一约束） | DAO/Repository 测试 | 表/字段废弃后可删 |
| 端到端业务测试用例（含金标准） | L1 业务不变量与跨层流程 | E2E 测试、Service 集成测试 | 金标准不可删除；其余随功能废弃可删 |
| 手工验证场景用例 | L1/L3 中无法全自动化的场景（真机/三方回调/人工环境） | 手工执行 runbook | 场景废弃时可删 |
用例通用格式（每条用例须包含）：前置条件、操作步骤、期望结果、来源层引用（来源于哪一层的哪条规格）。
执行绑定要求（强制）：
- 每条 L7 用例必须填写
execution_ref 字段，指向至少一个可执行测试资产（文件路径 + 测试名 / Case ID）
- 手工验证场景类例外，但仍需
manual_runbook_ref 字段指向对应手工验证手册
- 每个执行资产（测试文件）须在文件头部声明
covers: [L7-case-id, ...] 列出覆盖的 L7 用例
- 金标准用例若无
execution_ref，视为「未生效」，必须在 PR 描述中明确标注并在合并前补全
- 项目可选实现 lint 脚本，校验 L7 规格 ↔ 执行资产双向引用完整性
execution_ref 最小协议：
合法类型仅三类（不在此三类内的引用不视为有效绑定）：
- 测试文件路径：仓库相对路径 + 用例锚点，格式如
src/test/java/example/ActivityTest.java#testCreateActivity
- 测试用例 ID：CI/测试管理系统中可解析的唯一标识，格式由项目补丁声明
- runbook 路径：仅限手工验证用例，格式如
docs/04-测试/手工验证/{NN}-{domain}/runbook.md
校验规则：
post-change-check 脚本须能解析上述三类引用并验证目标存在- 引用目标不存在或已移动超过 24 小时未修复，标记
[STALE-REF]
[STALE-REF] 用例不阻断 CI，但进入 PR review 必须先解除
命名规范由项目补丁声明。
金标准不可删除规则：
| 情形 | 判定 |
|---|
| 代码重构，业务逻辑未变 | ❌ 不可无等价替代地删除 |
| 测试跑起来麻烦 | ❌ 不可删除（执行问题改工具，不改用例） |
| 存在等价替代测试集（覆盖相同不变量，且更高质量/粒度重组/平台迁移） | ✅ 可删除（须满足等价替代三条件，见下方） |
| L1 明确废弃对应功能 | ✅ 可删除（须有 L1 变更记录 + 死亡线审查人签字） |
| L1 业务规则被明确修订 | ✅ 可修改（须有 L1 变更记录，修改后更新 L1 引用） |
等价替代三条件（全部满足才允许替换删除金标准用例）：
- 显式声明被保护的业务不变量（需与原金标准的「来源层引用」字段一致）
- 新测试集合在不变量维度上提供等价或更强的覆盖证明（用例数 × 场景深度，不得缩水）
- 替换操作在 PR 描述中由金标准副审（测试/业务 owner）签字确认
金标准测试用例须在"来源层引用"字段中标注守护的 L1 业务不变量。执行层的注释格式由项目自定义（示例（MyApp）：.as("L1不变量：[描述]")）。
项目级补丁挂载点：具体金标准领域清单（核心算法/积分/等级等）由各项目自定义，不进通用规则。
不应包含：可执行测试脚本（归执行层）；测试环境配置/测试账号（归项目级配置）；执行结果/Bug 记录（归测试报告）；业务规则决策（归 L1）；接口字段定义（归 L3）；项目具体金标准领域清单（归项目补丁）；任务批次临时文件（归任务总控）。
文档路径模板：
实现验证：{docs_root}/{NN}-测试/{NN}-实现验证测试/{NN}-{domain_name}/
金标准： {docs_root}/{NN}-测试/{NN}-金标准测试/{domain_name}/
接口验证：{docs_root}/{NN}-测试/{NN}-接口验证测试/{domain_name}/
手工验证：{docs_root}/{NN}-测试/{NN}-手工验证场景/{NN}-{domain_name}/
示例（MyApp）：
docs/04-测试/实现验证/{NN}-{domain_name}/
docs/04-测试/手工验证/{NN}-{domain_name}/
审核强度：金标准用例 🟠 关键面抽查；其余三类 🟡 方向性确认。
裁决位置：最底层，没有下游文档层。L7 失败时触发向上溯源诊断链：
L7 用例失败
Step 1：L7 用例本身是否已过期（上游层已变更但 L7 未同步）？
→ 过期 → 人工裁决：更新 L7，还是回滚上游层变更？
Step 2：L7 用例有效 → L3/L4 设计是否与 L1 一致？→ 不一致 → 人工裁决
Step 3：L3/L4 有效 → L5/L6 方案是否与 L3/L4 对齐？→ 不对齐 → 人工裁决
Step 4：以上均一致 → 代码实现有缺陷 → 修复代码，重跑 L7
变更触发：L1 业务不变量废弃/调整（金标准）；L1 新增功能或业务规则（金标准）；L2 页面规格变更（手工验证）；L3 接口新增/修改/废弃（接口验证/实现验证）；L4 数据库变更（实现验证）；L5/L6 主要链路变更（对应类型）。不触发：后端私有方法重构（输出结果不变）；SQL 优化（查询结果不变）；前端样式微调；测试脚本重写（执行层变化，用例规格未变）。
与代码的关系：验收型（特殊类型）。金标准用例 > 代码；接口验证用例来源于 L3（L3 > L7 > 代码）；实现验证/手工验证用例失败需人工判定是代码缺陷还是 L7 过期。
禁止行为：❌ 因测试用例跑起来麻烦就修改/删除用例；❌ 代码重构后金标准用例要调整就直接改；❌ 把测试脚本写入 L7 文档；❌ 用"测试通过"掩盖 L7 覆盖不足。
5.8 运行与发布资产（跨层附属，非独立编号层）
定位：发布策略、回滚策略、灰度规则、观测指标、告警阈值、运行手册等内容不归属于任何单一层，统一作为跨层附属的运行资产管理。不增加 L8 编号，不破坏「七层」命名稳定性。
归属路径：由项目补丁声明（示例（MyApp）：docs/06-运行资产/ 或 docs/04-测试/04-04-运行手册/）。
应包含：发布策略（触发条件/部署顺序/预检清单）；回滚策略（条件/步骤/影响范围说明）；灰度规则（分流比例/Feature Flag/上线流程）；关键观测指标（SLI/SLO/核心业务指标及告警阈值）；运行手册（runbook：告警处理流程/故障定位步骤/应急操作）。
变更触发扫描：发布/回滚/灰度/告警阈值变更 → 检查 §5.8 运行资产 + L7 实现验证测试。
文档粒度总则
以下原则适用于 L1~L7 所有层：
-
按业务域拆分：同层中同一业务域的内容集中在同一文件（或目录）内；跨域内容须有索引文档承担入口职责。域的定义由项目补丁声明。
-
单文档软上限：单份文档的行数软上限由项目补丁声明（建议默认 ≤ 800 行）；超出时触发 long-doc-governance 分拆流程。
-
索引文档要求：同层若有多份文档，必须有一份索引文档（通常命名 00-README.md）列出所有子文件及其职责。
-
可定位性要求：跨域聚合文档允许存在，但必须能在 30 秒内定位到具体域条目（通过目录标题/锚点实现）。
-
与治理 skill 联动：post-change-check 报 [CRITICAL] 长文档警告时，强制触发 long-doc-governance skill 治理；不得忽略。
6. 死亡线审查机制
6.0 通用最小兜底清单（无论项目补丁是否存在，本条即时生效）
以下区域 AI 触碰时无需项目补丁即触发死亡线流程：
- 支付 / 计费 / 退款 / 优惠权益相关代码
- 鉴权 / Token / 密码 / 密钥相关代码
- 用户数据删除 / 批量更新 / 数据迁移脚本
- 第三方平台回调（支付/认证/OAuth 等）
- 涉及金额、用户身份、隐私字段的 SQL / 批处理脚本
项目补丁可叠加本项目的核心算法（如核心算法/积分/等级等），但不能删减上述兜底清单。
6.1 定义
死亡线 = 用户必须亲自审查的代码区域。AI 不能独自决定这些区域的逻辑。
项目级补丁挂载点：项目特有的死亡线区域（如核心算法区域名称、代码位置、审查要点）由各项目在项目级 skill 补丁中维护，叠加到 §6.0 通用清单之上。
6.2 AI 在死亡线区域的行为
当 AI 触碰死亡线区域的代码时：
- 在提交说明中明确标记：「⚠️ 死亡线区域变更：[区域名]」
- 要求项目补丁声明的死亡线审查人亲自审查：不能自行判断逻辑是否正确
- 确认/补充 L7 对应的金标准测试用例
- 禁止静默修改，即使是"看起来无害"的重构
[!WARNING]
死亡线区域的任何变更都不能自行决定。即使 AI 有 99% 的信心逻辑是对的，仍然必须要求项目补丁声明的死亡线审查人审查。
6.3 死亡线最小准入清单（通过 = 全部满足）
死亡线变更通过的定义：以下四项全部满足，AI 才可继续后续步骤；否则保持停机状态。
- 命名审查人：项目补丁中声明的真实审查人已被@或通知（不允许「AI 自审」或「留待以后再审」）。
- 列出审查对象：具体文件 + 行号范围 + 改动 diff 已提供给审查人（不允许只说「改了死亡线区域」）。
- 关联验证证据：至少关联以下一项：① 相关金标准测试 ID（execution_ref）；② 本次变更新增的回归测试；③ 手工验证 runbook 执行记录。
- 留下可追溯记录：审查确认留存在 PR 评论、独立 review-record 文件、或项目约定的其他可追溯位置（不允许口头确认无记录）。
7. 文档同步检查清单
每次开发任务完成时，AI 必须对照此清单自检：
7.1 代码变更后
7.2 文档变更后的级联检查
8. 速判决策树
发现文档和代码（或两层之间）矛盾了，怎么办？
唯一答案：立刻停止，向人报告具体不一致内容，等人决定。
（裁决链告诉人"理论上谁优先"，但人才是最终决策者，AI 不自动执行裁决。）
刚完成一次代码修改，接下来做什么？
Q: 修改涉及接口或数据库吗？
├─ 是 → 检查 L3/L4 是否已更新；发现不一致 → 人工裁决
└─ 否 → 继续
Q: 修改涉及后端主要业务链路或架构规范吗？
├─ 是 → 检查 L6 主要链路/架构规范描述是否与代码一致；发现不一致 → 人工裁决
└─ 否 → 继续
Q: 修改涉及前端主要业务链路或架构规范吗？
├─ 是 → 检查 L5 主要链路/架构规范描述是否与代码一致；发现不一致 → 人工裁决
└─ 否 → 继续
Q: 修改涉及死亡线区域吗？
├─ 是 → 标记死亡线变更，要求用户审查
└─ 否 → 继续
Q: 有相关测试用例需要更新吗？
├─ 是 → 更新 L7 对应资产；如涉及 L1 不变量，检查金标准用例
└─ 否 → 继续
└─ 完成。执行评审动作（项目可自定义触发器与命名，如 /review）
该把这个东西放哪一层？
这是「做什么、为什么、交互形态/线框」吗？→ L1 需求层
这是「UI 颜色/字体/视觉排版/高保真设计」吗？→ L2 交互层（页面层）
这是「系统对外暴露的接口字段契约」吗？→ L3 契约层（接口层）
这是「数据如何存储（表/字段/索引/约束）」吗？→ L4 数据库层
这是「客户端/前端架构规范/主要业务链路/技术选型」吗？→ L5 客户端实现规约层（前端技术层）
这是「服务端/后端架构规范/主要业务链路/技术选型」吗？→ L6 服务端实现规约层（后端技术层）
这是「如何验证以上各层的正确性」吗？→ L7 测试用例层
9. 与其他 skill 的协作关系
| 场景 | 本 skill 的职责 | 协作 skill 类型 |
|---|
| 需要判断文档属于哪一层、确认放置位置 | 分层裁决与规则参考 | 项目级文档编写指南 skill |
| 新增接口 | 提供 L3 编写规范；按流程先更新 L3 | 项目级接口/后端基础构件 skill |
| 新增数据库表或字段 | 提供 L4 编写规范；按流程先更新 L4 | 项目级数据库基础构件 skill |
| 探查现有数据库结构 | 提供 L4 真值验证依据 | 项目级数据库探查 skill |
| 大型跨会话任务 | 在任务总控中标注各子任务涉及哪些层 | 任务总控 skill |
| 代码审查 | 补充七层一致性检查 | /review 工作流 |
| 中等任务管理 | 任务级设计文档标注本轮变更涉及哪些层 | 轻量设计方案 / 施工蓝图 skill |
| 编写测试用例 | 提供 L7 四类用例规格与金标准规则 | 项目级测试与金标准 skill |
以上协作 skill 均为类型描述，具体 skill 名称由项目在项目级 skill 补丁中维护。本 skill 不引用任何具体项目的 skill 名称。
