first commit

2026-07-25 23:45:09 +08:00
commit c7bd957e6f
47 changed files with 3870 additions and 0 deletions
@@ -0,0 +1,94 @@
+# 影响分级与确认门禁
+
+## 按最高影响分级
+
+评估业务行为、工程数量、接口契约、数据、架构、权限与安全、回归范围、发布协同和可回滚性。最高风险维度决定最终等级。
+
+| 维度 | L0 | L1 | L2 |
+|---|---|---|---|
+| 业务行为 | 不改变运行行为 | 小范围行为变化 | 核心流程或多模块变化 |
+| 工程 | 单个极小位置 | 单工程或少量模块 | 多工程或跨服务 |
+| 接口 | 不涉及 | 少量兼容性变化 | 大量或破坏性变化 |
+| 数据 | 不涉及 | 小范围兼容调整 | 迁移、重构或跨存储变化 |
+| 架构 | 不涉及 | 核心架构不变 | 架构或依赖方向变化 |
+| 安全 | 不涉及 | 低风险局部逻辑 | 核心权限、隔离或敏感数据 |
+| 回归 | 极小 | 清晰且可控 | 广泛、复杂或不确定 |
+| 发布 | 简单 | 可控且容易回滚 | 多方协同、高风险或难回滚 |
+
+注释、拼写、静态文案和非行为性文档只有在不改变配置、契约、合规含义或运行行为时才属于 L0。
+
+典型 L1 包括范围明确的 CRUD、兼容性接口调整或影响已知的小型缺陷修复。
+
+典型 L2 包括跨服务改造、核心流程重构、破坏性接口、复杂迁移、大范围权限调整、广泛回归、多工程协同发布或影响明显不确定。
+
+## 提出分级建议
+
+修改代码前输出：
+
+```markdown
+## 变更影响等级评估
+- 建议等级：
+- 判断依据：
+- 涉及业务：
+- 涉及工程：
+- 接口影响：
+- 数据影响：
+- 架构影响：
+- 回归范围：
+- 主要风险：
+- 建议执行流程：
+```
+
+最终等级由用户确认。确认前允许只读调查。
+
+## 门禁
+
+### L0
+
+一次性确认具体改动、位置、影响和最小验证方式，然后实施并验证。
+
+### L1
+
+完成 `01.精简变更日志.md` 的计划部分，包括需求、范围、方案、影响与回归、冒烟用例。编码前确认一次，然后实施、Review、验证并补全同一份日志。
+
+### L2
+
+执行三次门禁：
+
+1. **G1 需求门禁：**确认大需求 `技术侧需求分析.md`、业务子任务拆分、全部 `01.需求分析.md`、范围、矛盾和待决事项。
+2. **G2 方案门禁：**确认 `02.技术实现方案.md` 和 `03.冒烟与逻辑验证.md` 第 1–4 节，包括接口与数据设计、影响、回归和验证计划。
+3. **G3 开发交付门禁：**提交完成执行结果的 `03.冒烟与逻辑验证.md`、`04.技术实现记录.md` 和 `05.代码Review报告.md`，确认可以交给测试人员。
+
+代码 Review 和验证是实现后的强制质量动作，不得在其执行前人为增加确认门禁。
+
+在 `STATUS.md` 记录门禁状态：
+
+```text
+G1 需求门禁：待确认 / 已通过
+G2 方案门禁：待确认 / 已通过
+G3 开发交付门禁：待确认 / 已通过
+```
+
+每次门禁必须绑定：
+
+- 当前原始需求版本；
+- 本门禁确认的文档及文档版本；
+- 相关代码分支、Commit 或等价版本标识；
+- 确认时间、确认来源和确认范围。
+
+门禁通过后，确认对象发生实质修改时，将门禁改为“需要重新确认”，记录失效原因并停止进入下一阶段。仅修正错别字、链接等不改变语义的编辑可以保留门禁，但要写入状态历史。
+
+## 重开与升级
+
+出现以下情况时，暂停受影响工作并退回失效阶段：
+
+- 出现需求矛盾；
+- 必须改变已确认的业务规则；
+- 影响扩大到其他工程或核心功能；
+- 接口兼容、数据设计或架构发生实质变化；
+- 原方案不可行；
+- 需要破坏性或不可逆操作。
+
+新证据触发更高等级时必须升级，并在继续前补齐产物。只有用户明确确认后才能降级。
+
+不改变已确认行为、契约、数据、架构和影响范围的私有实现调整无需重开门禁，但要写入实现记录。
@@ -0,0 +1,113 @@
+# L0 与 L1 轻量流程
+
+## L0
+
+仅对影响极小且不改变运行行为的变更使用 L0。
+
+```text
+理解并定位
+→ 说明具体改动和影响
+→ 用户确认
+→ 修改
+→ 检查差异
+→ 执行最小必要验证
+→ 报告结果
+```
+
+确认内容可以很精简：
+
+```markdown
+变更等级：L0
+
+计划修改：
+- ...
+
+影响范围：
+- ...
+
+验证方式：
+- ...
+```
+
+L0 不创建完整的 L2 PM 文档集，但仍必须保留用户已有改动、遵循项目规则、检查最终差异，并说明实际执行了哪些验证。
+
+如果看似简单的修改会改变配置、运行行为、对外含义、契约或业务规则，必须升级。
+
+## L1
+
+维护一份持续更新的文档：
+
+```text
+01.精简变更日志.md
+```
+
+落地位置分两种情况：
+
+- 独立需求：放在该需求的 `management/PM-<编号>-<名称>/` 大需求根目录下。
+- 大需求下的子任务：放在对应 `tasks/ST-<编号>-<名称>/` 子任务目录内。
+
+PM 编号尚未确定时使用 `PM-待确认-<需求名称>`，在本次 L1 编码前确认中由用户决定后再改为正式目录。Agent 不得自行生成永久编号。
+
+编码前完成第 1–6 节并取得一次确认；编码后补充第 7–12 节。
+
+```markdown
+# 精简变更日志
+
+## 1. 基本信息
+- 需求编号：
+- 需求名称：
+- 影响等级：L1
+- 当前状态：
+
+## 2. 需求说明
+
+## 3. 变更范围
+- 涉及工程：
+- 涉及功能：
+- 涉及接口：
+- 非本次范围：
+
+## 4. 影响及回归范围
+
+## 5. 技术实现计划
+- 现有逻辑：
+- 复用内容：
+- 计划改动：
+- 数据变化：
+- 风险与待确认项：
+
+## 6. 冒烟自测用例
+| 功能点 | 验证场景 | 预期结果 |
+|---|---|---|
+
+## 7. 用户确认记录
+
+## 8. 实际代码改动
+
+## 9. Code Review
+
+## 10. 逻辑验证和冒烟结果
+
+## 11. 遗留问题
+
+## 12. 完成结论
+```
+
+执行流程：
+
+```text
+只读调查
+→ 编写计划部分
+→ 用户确认一次
+→ 实现
+→ Review
+→ 逻辑验证和冒烟
+→ 补全日志
+→ 标记开发完成
+```
+
+编码前可以写 Review 检查范围，但不能伪造 Review 结论。实际 Review 和测试结果只能在执行后填写。
+
+如果发现广泛依赖、核心架构变化、破坏性兼容问题、复杂迁移或无法界定的回归范围，升级为 L2。
+
+Agent 在 L1 中不得执行 `git add`、`git commit`、`git push`；暂存、提交和推送由用户完成。变更日志中的请求响应、日志和测试证据必须脱敏。
@@ -0,0 +1,144 @@
+# L2 需求管理
+
+## PM 目录
+
+收到新的 L2 需求后创建：
+
+```text
+management/
+└─ PM-<大需求编号>-<需求名称>/
+   ├─ README.md
+   ├─ STATUS.md
+   ├─ 技术侧需求分析.md
+   ├─ source/
+   │  ├─ README.md
+   │  ├─ v1/
+   │  └─ v2/
+   ├─ code/
+   │  └─ MANIFEST.md
+   └─ tasks/
+      └─ ST-001-<业务模块>/
+         ├─ 01.需求分析.md
+         ├─ 02.技术实现方案.md
+         ├─ 03.冒烟与逻辑验证.md
+         ├─ 04.技术实现记录.md
+         ├─ 05.代码Review报告.md
+         └─ 06.验收与交付报告.md
+```
+
+测试、上线和上线验证完成后，在大需求根目录新增一份 `归档记录.md`；不移动整个目录。
+
+PM 编号由用户决定。尚未提供编号时，可以使用：
+
+```text
+PM-待确认-<需求名称>
+```
+
+作为需求分析期间的临时目录，并将 PM 编号列为 G1 需求评审的必确认项。用户确定编号后，在进入技术方案阶段前重命名为正式目录，并检查外部链接。Agent 不得自行生成永久 PM 编号。
+
+大需求 `README.md` 负责总览和子任务索引。使用相对链接，并维护大需求与每个子任务之间的双向关联。
+
+## 原始需求版本
+
+将每次收到的需求保存为完整、不可变的版本快照：
+
+```text
+source/v1/
+source/v2/
+source/v3/
+```
+
+不得覆盖或修改原始文件。在 `source/README.md` 中记录版本、接收时间、来源、主要变化和当前/废止状态。对话中的临时补充在进入正式版本前，应作为补充需求单独记录。
+
+收到新版本后：
+
+1. 比较新旧版本；
+2. 识别受影响的模块、需求、方案、用例和实现；
+3. 重开失效阶段；
+4. 更新状态历史；
+5. 已通过门禁失效时重新确认。
+
+除非变更说明明确，不得假设新版本自动解决了旧版本中的矛盾。
+
+## 代码分析副本
+
+用户在 `code/` 下维护分析用代码副本，默认基准分支为 `master`，项目另有配置时以项目为准。Agent 可以执行只读 Git 检查和安全的基准分支同步，但不得执行 `git add`、`git commit`、`git push`。
+
+更新流程：
+
+```text
+检查仓库状态
+→ 确认基准分支和本地无业务修改
+→ 使用只允许安全快进的方式获取更新
+→ 记录工程、分支、最新 Commit 和更新时间
+→ 更新 MANIFEST
+→ 重新判断既有分析是否过期
+```
+
+Agent 不得在副本中实现需求。允许使用 `git status`、`git diff`、`git log` 和安全同步命令调查；发现脏工作区、错误分支、历史分叉或无法安全快进时停止并报告，不得强制重置或擅自解决分叉。
+
+维护 `code/MANIFEST.md`：
+
+| 工程 | 本地目录 | 远端仓库 | 基准分支 | 当前 Commit | 更新时间 |
+|---|---|---|---|---|---|
+
+真正的需求开发在独立的项目开发工作区中完成。
+
+## 需求矛盾与歧义
+
+需求前后冲突、版本描述不一致、语义歧义或关键条件缺失时，禁止猜测。
+
+在相关 `01.需求分析.md` 中记录：
+
+| 编号 | 描述位置 A | 描述 A | 描述位置 B | 描述 B | 影响范围 | 状态 | 确认结论 |
+|---|---|---|---|---|---|---|---|
+
+使用 `RC-001` 等稳定编号。展示两处描述，说明受影响模块和功能，列出可能理解但不代替用户选择，并请求确认。
+
+确认前：
+
+- 标记为 `待确认`；
+- 不设计或实现受影响的业务决策；
+- 安全时可以继续不受影响的工作；
+- 无法继续时将子任务标记为待确认或阻塞。
+
+确认后记录结论、确认人、时间、来源和受影响文档，并同步更新。
+
+## 状态历史
+
+以 `STATUS.md` 作为当前状态和历史记录的唯一事实来源。阶段和状态分开维护。
+
+阶段：
+
+```text
+需求接入 → 需求分析 → 技术方案设计 → 冒烟用例设计
+→ 技术实现 → Code Review → 逻辑验证 → 测试 → 发布 → 归档
+```
+
+状态：
+
+```text
+未开始 / 进行中 / 待确认 / 已阻塞 / 待评审 / 已完成 / 已跳过 / 已取消
+```
+
+记录：
+
+- 大需求状态摘要；
+- 每个子任务的当前阶段和状态；
+- G1/G2/G3 状态；
+- 阻塞事项；
+- 只追加的变更历史，包括时间、对象、原/新状态、原因、操作者和证据链接。
+
+不得删除或改写历史来掩盖返工。旧记录有误时追加更正。验证或测试失败时，重新打开实现阶段并记录回退。
+
+门禁记录必须包含确认的原始需求版本、文档及文档版本、用户提供的代码版本标识、确认时间、来源和范围。文档中的“当前状态”字段只作为展示，发生冲突时以 `STATUS.md` 为准。
+
+当前状态表：
+
+| 子任务 | 业务模块 | 当前阶段 | 当前状态 | 阻塞项 | 最后更新 |
+|---|---|---|---|---|---|
+
+历史表：
+
+| 时间 | 对象 | 原阶段/状态 | 新阶段/状态 | 原因 | 操作者 | 证据 |
+|---|---|---|---|---|---|---|
@@ -0,0 +1,125 @@
+# L2 需求分析
+
+## 目标和边界
+
+将业务需求转换为研发可理解的功能范围和业务子任务，说明需要改变哪些能力、可能涉及哪些工程。本阶段描述“需要开发什么”，不展开完整实现设计。
+
+## 执行流程
+
+```text
+归档原始需求版本
+→ 通读全部材料
+→ 识别矛盾和问题
+→ 按业务能力拆分
+→ 更新并阅读代码副本
+→ 调查架构、文档、接口和代码
+→ 识别涉及工程及复用
+→ 编写技术侧需求解读
+→ 编写各子任务 01 文档
+→ 更新关联和 STATUS
+→ 提交 G1
+```
+
+拆分前必须完整阅读需求及相关附件。
+
+## 按业务模块拆分
+
+使用可独立识别的业务能力，例如：
+
+```text
+品牌重构
+├─ 品牌管理
+├─ 品牌审核
+└─ 品牌授权
+```
+
+子任务应具备可识别的业务目标、参与者/流程/状态边界、验收结果或独立交付能力。不得将前端、后端、数据库直接作为一级业务子任务；技术工作放入适用的业务子任务内部。
+
+记录前后置依赖、共享能力、接口、数据、联调顺序和联合测试要求。只有跨模块公共能力可以独立设计、交付和验证时，才建立公共技术子任务。
+
+## 技术侧需求解读
+
+需求分析应说明：
+
+- 业务背景和目标；
+- 对业务需求的技术侧解读；
+- 范围和非目标；
+- 业务模块与子任务；
+- 需要新增、修改、复用、废弃或迁移的功能；
+- 涉及工程及原因；
+- 现有能力和复用判断；
+- 接口、数据及上下游影响；
+- 非功能要求；
+- 发布、迁移、灰度、兼容、回滚和上线后验证要求；
+- 依赖、风险和待确认项。
+
+本阶段不提供完整类与方法设计、完整字段级接口定义、详细表结构或逐文件实现步骤。
+
+使用 `已确认`、`待确认`、`待代码核实`、`技术建议` 标注结论来源。不得将推导结果写成原始需求事实。
+
+## 识别涉及工程
+
+根据架构文档和已记录 Commit 的代码证据调查：
+
+- 入口和调用链；
+- 模块依赖；
+- 现有接口及调用方；
+- 领域与数据模型；
+- 认证和授权；
+- 消息、事件和定时任务；
+- 下游与外部系统。
+
+记录：
+
+| 工程 | 当前职责 | 涉及模块 | 影响原因 | 预计变更类型 | 证据 |
+|---|---|---|---|---|---|
+
+不得只根据仓库名称推断。
+
+## 复用分析
+
+每个功能按以下类型分类：
+
+```text
+直接复用 / 扩展复用 / 适配复用 / 需要修改 / 需要新增 / 需要废弃或迁移 / 待确认
+```
+
+指出具体接口、模块或代码符号及其复用边界。用户指定原接口时，记录当前调用方、当前行为、问题、目标行为、兼容性、保留/废弃策略、影响和回归需求。
+
+## `01.需求分析.md`
+
+每个子任务至少包含：
+
+```markdown
+# ST-XXX 子任务需求分析
+
+## 1. 文档信息与需求来源
+## 2. 目标、范围与非范围
+## 3. 业务规则、角色和权限
+## 4. 正常流程、异常流程和状态流转
+## 5. 功能点清单
+## 6. 涉及工程及现有实现
+## 7. 复用、新增、修改和迁移分析
+## 8. 接口、数据及上下游影响
+## 9. 非功能与上线要求
+## 10. 子任务依赖
+## 11. 验收标准
+## 12. 需求矛盾、风险和待确认项
+```
+
+功能使用 `F-001` 等稳定编号，验收标准使用 `AC-001`。链接到大需求和原始需求版本。
+
+## 提交 G1
+
+提交以下完整确认包：
+
+- 大需求级 `技术侧需求分析.md`；
+- 业务子任务拆分；
+- 全部子任务的 `01.需求分析.md`；
+- 范围与非范围；
+- 需求矛盾、待确认项和风险；
+- 当前原始需求版本；
+- PM 编号；尚未确定时由用户在本次评审中决定；
+- 相关文档链接和版本。
+
+用户确认 G1 后才能开始技术方案设计。确认结论必须写入 `STATUS.md` 并绑定上述版本。
@@ -0,0 +1,133 @@
+# L2 技术方案设计
+
+## 每个子任务一份文档
+
+每个子任务只创建一份：
+
+```text
+02.技术实现方案.md
+```
+
+该子任务的全部功能、接口、CRUD、消息、回调、定时任务、批处理和数据模型设计都写在同一文档内。除非用户明确要求，不得拆成多个功能方案文件。使用目录、编号标题、功能编号和接口总览表管理长文档。
+
+## 设计流程
+
+```text
+读取已确认的 01
+→ 确认需求版本和代码基线
+→ 调查现有实现和测试
+→ 识别复用和约束
+→ 设计总体流程
+→ 设计每个功能和接口
+→ 设计数据模型和一致性
+→ 分析影响与回归
+→ 设计实施顺序和验证
+→ 更新 STATUS
+```
+
+设计中发现业务规则缺失或矛盾时，将受影响内容退回需求分析。
+
+## 文档结构
+
+```markdown
+# ST-XXX 技术实现方案
+
+## 目录
+## 1. 文档信息、依据和版本
+## 2. 目标、范围和验收依据
+## 3. 现有实现与复用分析
+## 4. 总体实现方案
+## 5. 功能点和接口总览
+## 6. 各功能点实现方案
+## 7. 数据模型设计
+## 8. 跨工程改造与依赖顺序
+## 9. 变更影响与回归范围
+## 10. 权限、安全、事务、并发和幂等
+## 11. 非功能、日志、监控和审计
+## 12. 兼容、迁移、发布和回滚
+## 13. 测试与验证设计
+## 14. 实施步骤
+## 15. 方案取舍、风险和待确认项
+## 16. 需求追溯
+```
+
+确实不适用的章节写明原因，不得机械填充。
+
+## 每个功能必须有方案
+
+每个 `F-XXX` 都要说明：
+
+- 目标及需求/验收依据；
+- 涉及工程和模块；
+- 现有实现、可复用符号及 Commit 证据；
+- 新增、修改、复用和非范围；
+- 正常、异常和适用的边界流程；
+- 接口、请求、响应、错误码和权限；
+- 业务校验；
+- 数据读写；
+- 事务、一致性、并发和幂等；
+- 缓存、搜索和消息行为；
+- 兼容性；
+- 测试和验证；
+- 风险与待确认项。
+
+简单 CRUD 也必须提供精简方案，至少覆盖校验、唯一性、分页/筛选、删除语义、权限、数据影响、适用的幂等和冒烟验证。
+
+## 数据模型设计
+
+发生任何数据模型变化时，在同一文档第 7 节设计。
+
+### 数据库
+
+说明实体含义、表、字段类型/可空/默认值、主键、约束、索引及查询依据、关系、枚举、审计/逻辑删除、容量、DDL、历史迁移、兼容、发布和回滚。
+
+### Redis
+
+说明 Key 规则、数据类型和值结构、事实数据源、TTL、读写时机、更新/失效、未命中/空值、原子性、并发、热 Key/大 Key 风险和旧 Key 清理。
+
+### Elasticsearch
+
+说明索引/Alias、文档 ID 和示例、Mapping/分词、适用的分片/副本/Routing、查询场景、数据库到 ES 的同步、延迟目标、重试修复、Reindex、历史初始化、Alias 切换和回滚。
+
+### 跨存储一致性
+
+明确事实数据源、写入顺序、事件或 CDC 链路、缓存失效、ES 同步、幂等、重试/补偿、对账和失败行为。
+
+没有数据模型变化时，也要写明并指出复用依据。
+
+## 影响与回归
+
+每个被修改的接口或功能都要调查：
+
+- 上游调用方和下游依赖；
+- 复用同一核心方法的其他接口；
+- 共享数据库表、Redis Key 和 ES 文档；
+- 消息、消费者、任务、报表、导入导出；
+- 前端、客户端和外部集成；
+- 权限、状态流转、监控和发布顺序。
+
+影响分类：直接、间接、兼容、数据、行为、性能、发布、潜在或已验证无影响。
+
+维护：
+
+| 影响编号 | 变更项 | 受影响接口/功能 | 工程 | 类型 | 说明 | 是否改造 | 回归级别 |
+|---|---|---|---|---|---|---|---|
+
+以及：
+
+| 回归编号 | 工程 | 接口/功能 | 回归场景 | 原因 | 优先级 |
+|---|---|---|---|---|---|
+
+禁止写“回归相关功能”等模糊描述。必须列出具体场景。“无影响”也要写明检查过的调用链和数据链证据。
+
+影响超出已确认范围时，记录后果和选项并请用户确认，不得静默扩大范围。
+
+## 追溯与 G2
+
+建立：
+
+```text
+需求 → F-XXX → 方案章节 → 涉及工程 → AC-XXX → TC-XXX 验证用例
+```
+
+`02.技术实现方案.md` 和 `03.冒烟与逻辑验证.md` 的验证计划部分完成后，一起提交 G2；确认前不得开始实现。
@@ -0,0 +1,119 @@
+# L2 冒烟与逻辑验证
+
+## 文档定位
+
+每个子任务只维护一份：
+
+```text
+03.冒烟与逻辑验证.md
+```
+
+该文档分两个生命周期使用：
+
+1. **G2 前：**设计核心主流程、范围内功能点和关键回归的验证计划。
+2. **代码 Review 后：**填写实际执行结果、证据、失败修复和提测结论。
+
+冒烟用于证明提测版本主流程可用、需求范围内功能点已验证；逻辑验证补充静态检查、构建、自动化测试、接口、数据及关键回归。二者使用同一组 `TC-XXX` 编号，禁止再维护第二份重复结果。
+
+## G2 前必须设计
+
+- 核心业务主流程；
+- `01.需求分析.md` 中全部范围内功能点；
+- `02.技术实现方案.md` 中新增或修改的接口；
+- 明确要求的关键业务规则；
+- 关键权限和状态流转；
+- 主要数据新增、修改、查询和删除结果；
+- 接口变更直接影响的关键旧功能；
+- 会阻断提测的主要异常场景；
+- 计划执行的构建、自动化测试和静态检查。
+
+通常不要求穷举性能压测、所有并发组合、故障注入、全量兼容和无关系统级回归。某类风险属于本次需求核心内容时必须纳入。
+
+## 文档结构
+
+```markdown
+# ST-XXX 冒烟与逻辑验证
+
+## 1. 文档信息与验证基线
+## 2. 验证目标、范围和非范围
+## 3. 环境、前置条件和测试数据
+## 4. 验证计划
+### 4.1 静态检查、构建和自动化测试计划
+### 4.2 冒烟及功能用例
+### 4.3 关键影响回归计划
+## 5. 实际执行基线
+## 6. 静态检查、构建和自动化测试结果
+## 7. 冒烟及功能用例结果
+## 8. 关键回归结果
+## 9. 接口和数据验证
+## 10. 失败、修复和重验
+## 11. 未执行项、遗留问题和风险
+## 12. 验证结论
+```
+
+G2 时只确认第 1–4 节。第 5–12 节必须在代码实现和 Review 后按实际结果填写。
+
+## 用例设计
+
+计划表只描述如何验证：
+
+| 编号 | 功能点 | 验证场景 | 前置条件 | 操作步骤 | 预期结果 | 验证类型 |
+|---|---|---|---|---|---|---|
+
+每个功能点至少一条有效用例。简单 CRUD 的最低验证：
+
+| 功能点 | 最低验证 |
+|---|---|
+| 新增 | 创建成功且数据结果正确 |
+| 修改 | 修改成功且查询结果正确 |
+| 查询 | 能查询到正确目标数据 |
+| 列表 | 核心筛选和分页可用 |
+| 删除 | 删除成功且后续结果符合规则 |
+
+只为明确关键的边界增加用例，例如无权限、非法状态、重复提交、审核中禁止删除或接口变更后的关键调用方回归。
+
+## Review 后执行
+
+Review 阻断问题处理完成后，执行：
+
+- 最终代码检查；
+- 项目适用的格式化、Lint、静态分析和类型检查；
+- 编译或构建；
+- 单元测试和集成测试；
+- 核心调用链、权限、事务、幂等和状态流转检查；
+- `TC-XXX` 冒烟及功能用例；
+- 技术方案中的关键影响回归；
+- 本地接口与数据库、Redis、ES、消息和日志验证。
+
+结果表只记录实际执行事实：
+
+| 用例编号 | 实际结果 | 状态 | 证据 | 执行时间 |
+|---|---|---|---|---|
+
+环境、权限或依赖不足时标记“未验证”并说明原因，禁止默认通过。
+
+## 失败处理
+
+```text
+记录失败
+→ 分析原因
+→ 返回实现阶段修复
+→ 重新 Code Review
+→ 重跑失败项和受影响回归
+→ 更新结果
+```
+
+不得删除失败测试、弱化断言、跳过必要用例、吞掉异常或只重跑成功项。
+
+## 提测结论
+
+只有以下条件同时满足，才能写“具备提测条件”：
+
+- 核心主流程通过；
+- 范围内功能点均有执行记录；
+- 没有未处理的 Critical/High 或其他阻断缺陷；
+- 接口变更影响的关键旧功能完成必要回归；
+- 未验证内容已明确且不阻断提测；
+- 已记录实际验证基线，包括工程、分支和 Commit 或等价版本标识。
+
+完成第 5–12 节后，该文档与 04、05 一起提交 G3。
@@ -0,0 +1,104 @@
+# L2 冒烟自测
+
+## 定位
+
+`03.冒烟自测用例.md` 是提测前的精简自测清单，目标是：
+
+1. 保证提测版本核心业务主流程可用；
+2. 保证需求范围内每个功能点都经过有效验证。
+
+它不是完整测试方案，不要求穷举所有异常、并发和基础设施故障。只有某类风险属于本次需求核心内容时，才必须纳入冒烟。
+
+## 编写时机
+
+技术方案完成后、编码前编写初稿：
+
+```text
+01 需求分析
+→ 02 技术方案
+→ 03 冒烟用例
+→ G2
+→ 代码实现
+```
+
+实现中发现新的关键功能或影响范围时，先更新 02 和 03。
+
+## 必须覆盖
+
+- 本次需求核心主流程；
+- `01.需求分析.md` 中全部范围内功能点；
+- `02.技术实现方案.md` 中新增或修改的接口；
+- 明确要求的关键业务规则；
+- 关键权限和状态流转；
+- 主要数据新增、修改、查询和删除结果；
+- 接口变更直接影响的关键旧功能；
+- 会阻断提测的主要异常场景。
+
+通常不在冒烟阶段全面覆盖性能压测、全部并发组合、故障注入、全量兼容和无关系统级回归。
+
+## 文档结构
+
+```markdown
+# ST-XXX 冒烟自测用例
+
+## 1. 文档信息
+- 大需求编号：
+- 子任务编号：
+- 需求版本：
+- 技术方案版本：
+- 提测版本或 Commit：
+- 测试环境：
+
+## 2. 自测范围
+- 核心主流程：
+- 本次功能点：
+- 关键回归：
+- 非本次自测范围：
+
+## 3. 前置条件和测试数据
+
+## 4. 冒烟自测用例
+| 编号 | 功能点 | 验证场景 | 前置条件 | 操作步骤 | 预期结果 | 实际结果 | 状态 | 证据 |
+|---|---|---|---|---|---|---|---|---|
+
+## 5. 功能覆盖检查
+| 功能编号 | 功能名称 | 对应用例 | 是否已验证 |
+|---|---|---|---|
+
+## 6. 自测结论
+- 核心主流程是否通过：
+- 需求功能点是否全部验证：
+- 是否存在阻断问题：
+- 未通过或未验证项：
+- 是否具备提测条件：
+```
+
+编码前填写场景和预期结果；执行后再填写实际结果、状态和证据。
+
+## 最小用例原则
+
+每个功能点至少一条有效用例。简单 CRUD 可采用：
+
+| 功能点 | 最低验证 |
+|---|---|
+| 新增 | 创建成功且数据结果正确 |
+| 修改 | 修改成功且查询结果正确 |
+| 查询 | 能查询到正确目标数据 |
+| 列表 | 核心筛选和分页可用 |
+| 删除 | 删除成功且后续结果符合规则 |
+
+只有明确关键的边界才增加用例，例如无权限、非法状态、重复提交、审核中禁止删除，或接口变更后的关键调用方回归。
+
+技术方案中的完整回归范围可以大于冒烟范围；冒烟只选择影响主流程、需求功能和提测质量的关键场景。
+
+## 通过结论
+
+只有以下条件同时满足，才能写“具备提测条件”：
+
+- 核心主流程通过；
+- 范围内功能点都有验证记录；
+- 没有阻断缺陷；
+- 接口变更影响的关键旧功能完成必要回归；
+- 未验证内容已明确且不阻断提测。
+
+环境、权限或依赖不足时标记“未验证”，禁止默认通过。
@@ -0,0 +1,145 @@
+# 代码实现
+
+## 实现输入
+
+L2 编码以三份已确认文档为直接依据：
+
+```text
+01.需求分析.md
+02.技术实现方案.md
+03.冒烟与逻辑验证.md
+```
+
+确认需求版本、代码基线、开发工程和真实开发工作区。不得误在 `management/.../code/` 分析副本中开发。
+
+Agent 可以使用 `git status`、`git diff`、`git log` 等只读命令调查和 Review，但禁止执行 `git add`、`git commit`、`git push`。暂存、提交和推送均由用户完成；其他可能改变分支或历史的操作必须符合用户指示和安全规则。
+
+## 项目规范优先
+
+编码前调查：
+
+- `AGENTS.md`、`CLAUDE.md` 等 Agent 指令；
+- `README.md`、`CONTRIBUTING.md` 和架构文档；
+- `.editorconfig`、格式化、Lint、静态分析和构建配置；
+- 测试规范；
+- 当前模块和相邻同类代码。
+
+作用域更近的项目规则优先。没有书面规范时，从同一模块的同类近期实现中提炼惯例，不得凭单个偶然文件确定全局风格。
+
+保持目录、分层、命名、DTO/VO/Entity 划分、校验、异常、错误码、日志、权限、事务、数据访问、Redis、ES、消息、配置、依赖注入、注释和测试风格一致。
+
+保持风格不代表复制明显错误、过时代码或安全缺陷；发现问题时说明并采用最小安全处理。
+
+## 控制范围
+
+禁止借需求开发进行无关的：
+
+- 全工程格式化；
+- 大范围重命名；
+- 目录或框架替换；
+- 旧代码全面重构；
+- 注释清洗；
+- 个人偏好的设计模式改造；
+- 不必要的第三方依赖引入。
+
+新增依赖前检查项目已有能力、统一实现、兼容性、构建/部署/安全风险和必要性，并写入方案与实现记录。
+
+## 敏感信息保护
+
+- 不在代码、配置、需求文档、日志、测试记录或验证证据中写入密码、Token、Cookie、私钥、访问密钥和完整连接串。
+- 手机号、身份证、地址、客户数据和其他生产敏感信息必须脱敏。
+- 接口请求响应、数据库结果、日志和截图只保留验证所需字段。
+- 凭据通过项目认可的安全环境注入；缺少凭据时请求用户处理，不得创建或保存临时明文凭据。
+- 发现疑似密钥或生产敏感数据进入改动时，立即停止受影响工作并报告。
+
+## 实施顺序
+
+```text
+检查工作区、分支、Commit 和用户已有改动
+→ 读取项目规范
+→ 确认开发基线
+→ 按功能点和工程依赖实施
+→ 编写/更新自动化测试
+→ 构建和测试
+→ 对照冒烟用例自测
+→ 更新实现记录和 STATUS
+```
+
+多工程通常按照：
+
+```text
+数据脚本与公共模型
+→ 服务提供方
+→ 服务调用方
+→ 消息消费者
+→ 前端或外部接入方
+→ 联调
+```
+
+实际顺序以已确认方案为准。
+
+## TDD
+
+适合自动化的功能执行：
+
+```text
+建立失败测试
+→ 确认因目标能力缺失而失败
+→ 最小实现
+→ 测试通过
+→ 重构
+→ 相关回归
+```
+
+缺陷修复优先建立可复现问题的测试。外部环境导致无法标准测试先行时，记录原因并使用可执行替代验证。
+
+不得通过删除测试、弱化断言、跳过必要用例、吞异常或修改测试迎合错误实现来制造通过。
+
+## 方案偏差
+
+编码中发现方案不可行时：
+
+```text
+记录问题
+→ 判断需求和影响
+→ 更新 02
+→ 更新 03
+→ 必要时重开门禁
+→ 继续实现
+```
+
+接口契约、数据模型、涉及工程、业务流程、状态、权限、兼容性或需求范围变化时，必须先更新方案。仅私有结构调整且不改变这些内容时，写入实现记录即可。
+
+## `04.技术实现记录.md`
+
+记录实现事实，不复制整份方案：
+
+```markdown
+# ST-XXX 技术实现记录
+
+## 1. 实现信息
+- 需求版本：
+- 技术方案版本：
+- 开发工程：
+- 开发分支：
+- 实现前 Commit：
+- 实现后 Commit：
+- 当前状态：
+
+## 2. 功能实现状态
+| 功能编号 | 功能名称 | 涉及工程 | 实现状态 | 方案章节 | 备注 |
+|---|---|---|---|---|---|
+
+## 3. 工程及代码改动
+## 4. 数据模型改动
+## 5. 接口改动
+## 6. 自动化测试改动
+## 7. 与技术方案的差异
+## 8. 编译和测试结果
+## 9. 项目规范遵循情况
+## 10. 遗留问题及风险
+```
+
+项目规范遵循情况应列出已读取规范、参考实现、执行的格式/静态检查、差异和原因。
+
+实现完成仅表示代码准备进入 Review，不等于子任务最终完成。
@@ -0,0 +1,127 @@
+# 代码 Review 与逻辑验证
+
+## 固定顺序
+
+```text
+代码实现完成
+→ Code Review
+→ 修复 Review 问题
+→ 再次 Review
+→ 执行 03 中的逻辑验证和本地接口冒烟
+→ 输出结论
+```
+
+## Code Review
+
+检查完整变更及必要的相邻上下文，不只看修改行。可以使用 `git status`、`git diff`、`git log` 等只读命令确定 Review 范围，但不得执行 `git add`、`git commit`、`git push`。
+
+### 需求符合性
+
+- 是否覆盖全部确认功能；
+- 是否符合 01、02、03；
+- 是否遗漏接口影响和回归；
+- 是否擅自增加范围。
+
+### 项目规范与质量
+
+- 架构、分层、命名和代码风格；
+- 复用、重复实现、异常、日志和错误码；
+- 无关修改和大范围格式化；
+- 依赖和测试风格。
+
+### 核心架构变化
+
+检查模块职责、分层边界、依赖方向、核心接口、数据事实源、Redis/ES/消息链路、权限、事务和状态流转。
+
+分类为：
+
+```text
+方案内预期变化
+实现细节调整且不影响架构
+方案外架构变化，需要确认
+疑似架构破坏，必须修复
+```
+
+### 严重缺陷
+
+重点检查：
+
+- 代码中不得有在循环中查询数据库的情况
+- 越权、注入和敏感信息泄漏；
+- 数据错误、丢失或覆盖；
+- 空指针和未处理异常；
+- 事务、并发、幂等和状态错误；
+- 缓存/数据库/ES 不一致；
+- 消息重复、丢失或无限重试；
+- 死循环、资源泄漏和明显性能问题；
+- 接口兼容破坏；
+- 不可恢复的删除或迁移；
+- 异常路径错误返回成功；
+- 测试被弱化或跳过。
+
+只能写“在本次检查范围内未发现严重问题”，不得承诺绝对无 Bug。
+
+问题分级：
+
+| 等级 | 含义 | 要求 |
+|---|---|---|
+| Critical | 安全、数据丢失、系统不可用 | 修复后才能继续 |
+| High | 核心错误、架构破坏、明显兼容问题 | 修复后才能继续 |
+| Medium | 局部逻辑、维护性或规范问题 | 原则上修复并记录 |
+| Low | 优化或轻微风格问题 | 按范围处理 |
+
+## `05.代码Review报告.md`
+
+```markdown
+# ST-XXX 代码 Review 报告
+
+## 1. Review 信息和范围
+## 2. 需求符合性
+## 3. 项目规范符合性
+## 4. 核心架构变化
+## 5. Review 问题
+| 编号 | 等级 | 工程及位置 | 问题 | 影响 | 处理状态 |
+|---|---|---|---|---|---|
+## 6. 修复及复查
+## 7. 未确认风险
+## 8. Review 结论
+```
+
+发现问题后返回实现阶段，修复并重新 Review。
+
+## 逻辑验证
+
+Review 的阻断问题处理后，执行：
+
+- 最终差异检查；
+- 格式化、Lint、静态分析和类型检查；
+- 编译或构建；
+- 单元与集成测试；
+- 关键调用链、数据读写、权限、事务、幂等和状态流转检查；
+- 技术方案中的关键影响回归；
+- `03.冒烟与逻辑验证.md` 中确认的验证计划。
+
+失败时记录、分析、修复、重跑失败项和受影响回归。不得只重跑成功用例。
+
+## 本地接口测试
+
+本地环境可启动时：
+
+```text
+确认依赖和数据安全
+→ 启动相关工程
+→ 准备专用测试数据
+→ 执行核心主流程接口
+→ 验证范围内全部功能
+→ 回归关键受影响接口
+→ 检查数据库、Redis、ES、消息和日志
+→ 保存证据
+```
+
+检查状态码、响应结构、业务字段、落库、缓存/索引、状态流转、权限、关键异常和直接受影响旧接口。
+
+开始写数据前确认不是生产或不可随意修改的共享环境。需要人工登录、凭据或外部依赖时，明确请求用户协助。测试数据、请求响应、日志和截图必须脱敏，不得将凭据或生产敏感数据写入验证文档。
+
+实际结果统一写入 `03.冒烟与逻辑验证.md` 第 5–12 节，不再创建单独逻辑验证报告。只有实际执行并有证据的内容可以标记通过；环境受限的内容写“未验证”及原因。
+
+完成后提交 03、04、05 及关键证据，进入 G3。
@@ -0,0 +1,128 @@
+# 交付、上线与归档
+
+## 开发完成与需求完成
+
+Review、逻辑验证和冒烟通过后，子任务可标记：
+
+```text
+逻辑验证：已完成
+子任务：开发完成 / 待提测
+```
+
+这不等于需求已测试、上线或归档。
+
+后续状态：
+
+```text
+开发完成 → 待提测 → 测试中 → 测试通过
+→ 待发布 → 已上线 → 上线验证通过 → 已归档
+```
+
+测试失败时返回实现阶段，完成修复、Review、验证和重新提测，并追加状态历史。
+
+## G3
+
+向用户提交：
+
+- `04.技术实现记录.md`；
+- `05.代码Review报告.md`；
+- 已填写执行结果的 `03.冒烟与逻辑验证.md`；
+- 功能完成与未完成项；
+- 验证证据；
+- 遗留问题和风险；
+- 是否具备提测条件。
+
+用户确认后将 G3 标记为通过，进入测试人员提测流程。
+
+## `06.验收与交付报告.md`
+
+```markdown
+# ST-XXX 验收与交付报告
+
+## 1. 交付信息
+- 需求版本：
+- 涉及工程：
+- 开发分支：
+- 发布分支或 Tag：
+- 发布 Commit：
+
+## 2. 开发交付内容
+## 3. 测试结果
+- 测试环境：
+- 测试时间：
+- 测试人员：
+- 测试结论：
+- 缺陷及处理：
+- 测试报告：
+
+## 4. 发布记录
+- 发布时间：
+- 发布环境：
+- 发布版本：
+- 发布工程：
+- 数据脚本：
+- 配置变化：
+- 实际顺序：
+
+## 5. 上线验证
+- 核心主流程：
+- 关键接口：
+- 数据库：
+- Redis：
+- Elasticsearch：
+- 消息和任务：
+- 日志和监控：
+
+## 6. 遗留问题
+## 7. 最终结论
+```
+
+外部测试报告可以保存链接、编号或副本，不必重复全文。
+
+`git add`、`git commit`、`git push` 均由用户执行。Agent 可以读取并记录用户完成后的发布分支、Tag 和 Commit。
+
+## 逻辑归档
+
+归档不移动大需求目录。测试通过、上线并完成上线验证后，在大需求根目录维护一份：
+
+```text
+归档记录.md
+```
+
+归档文档汇总：
+
+- 基本信息、最终需求版本和时间；
+- 最终范围、延期或取消内容、需求变化；
+- 子任务完成情况；
+- 各工程发布分支、Tag、Commit 和时间；
+- 数据库、Redis、ES、配置和迁移；
+- Review、冒烟与逻辑验证、测试和上线结论；
+- 关键文档相对链接；
+- 遗留问题、风险和后续维护建议；
+- 最终归档结论。
+
+同时在 `STATUS.md` 追加：
+
+```text
+已上线 → 上线验证通过 → 已归档
+```
+
+目录、原始需求版本和历史状态不得删除。`code/` 副本即使以后继续更新，归档文档也必须保留本次实际发布的 Tag 和 Commit。
+
+## 后续维护
+
+归档事实记录原则上不直接改写。后续优化或修复建立新需求或维护任务，关联原 PM、最终需求版本和上线 Commit。
+
+## OpenSpec 适配
+
+默认归档载体为 `归档记录.md`。项目启用 OpenSpec 时，将其作为可替换归档后端：
+
+```text
+management 过程文档
+→ 字段映射或转换
+→ OpenSpec 归档
+```
+
+初期保持 management 文档为过程事实来源，避免人工双写。项目级适配规则应规定字段映射、归档命令、幂等、失败回退、状态同步和后续维护。
+
+OpenSpec 的引入不得改变前置开发流程、文档编号、需求追溯和状态历史。
@@ -0,0 +1,32 @@
+# 参考文件目录索引
+
+根据当前影响等级和阶段，只加载所需规则。
+
+| 文件 | 适用场景 |
+|---|---|
+| [01-分级与门禁.md](01-分级与门禁.md) | 新需求分级、选择门禁、范围升级或更新门禁状态 |
+| [02-L0与L1轻量流程.md](02-L0与L1轻量流程.md) | 执行 L0 或 L1 变更 |
+| [03-需求管理.md](03-需求管理.md) | 建立或维护 L2 PM 目录、原始需求版本、代码副本、状态历史或需求矛盾 |
+| [04-需求分析.md](04-需求分析.md) | 阅读需求、拆分业务子任务、识别工程或编写 `01.需求分析.md` |
+| [05-技术方案设计.md](05-技术方案设计.md) | 编写或修改 `02.技术实现方案.md`，包括接口、数据模型、影响和回归范围 |
+| [06-冒烟与逻辑验证.md](06-冒烟与逻辑验证.md) | 编写验证计划，执行冒烟、自动化检查和本地接口验证，并维护 `03.冒烟与逻辑验证.md` |
+| [07-代码实现.md](07-代码实现.md) | 实现代码、遵循项目风格、执行 TDD 或维护 `04.技术实现记录.md` |
+| [08-代码审查与验证.md](08-代码审查与验证.md) | Review 完成代码、检查严重缺陷、验证逻辑、启动本地服务或测试接口 |
+| [09-交付与归档.md](09-交付与归档.md) | 标记开发完成、提测、记录发布、维护 `06.验收与交付报告.md` 或逻辑归档 |
+
+## 阶段路由
+
+```text
+分级
+├─ L0 → 01 + 02
+├─ L1 → 01 + 02 + 07 + 08
+└─ L2
+   ├─ 接入与状态 → 01 + 03
+   ├─ G1 需求 → 03 + 04
+   ├─ G2 方案与验证计划 → 05 + 06
+   ├─ 实现 → 07
+   ├─ Review 与验证 → 08
+   └─ G3、交付与归档 → 09
+```
+
+需求变化时，重新读取所有被影响阶段的参考文件，不得只更新最新一份文档。