feat: add frontend development guidelines and structure documentation

- Introduced API guidelines for interface contracts and request handling. - Added design tokens usage guidelines for consistent styling across the project. - Established DTO guidelines for defining request parameters and response data types. - Created frontend structure guidelines to clarify directory organization and code placement rules. - Compiled a comprehensive frontend development guideline document covering various aspects of the development process. - Implemented quality guidelines to ensure code maintainability and adherence to best practices.
2026-07-25 22:20:25 +08:00
commit 91861565bb
78 changed files with 5001 additions and 0 deletions
@@ -0,0 +1,92 @@
+---
+id: LIFECYCLE-AI-RD-WORKFLOW
+type: standard
+status: draft
+created: 2026-06-29
+---
+
+# 生命周期
+
+## 1. 用户需求
+
+负责人：PM
+
+输入：原始用户需求、业务背景、访谈记录、问题描述。
+
+输出：
+
+- UR：用户需求。
+- RA：需求分析。
+- SA：场景分析。
+
+关键动作：
+
+- 评审原始需求是否清晰、完整、有价值。
+- 细化用户目标、业务价值、成功标准。
+- 补齐主场景、异常场景、边界场景。
+
+## 2. 研发需求
+
+负责人：SE
+
+输入：UR、RA、SA。
+
+输出：
+
+- OR：研发目标需求。
+- DR：研发需求。
+
+关键动作：
+
+- 将业务目标转译为工程目标。
+- 明确功能范围、非功能要求、接口、数据、依赖和约束。
+- 识别技术风险、拆分边界和交付策略。
+
+## 3. 详细设计
+
+负责人：RD
+
+输入：OR、DR。
+
+输出：
+
+- DS：详细设计。
+- TASK：可开发任务。
+
+关键动作：
+
+- 拆分模块、接口、数据结构、状态流和异常处理。
+- 将设计落到可由 AI 或研发执行的任务粒度。
+- 标注测试点、兼容性和回归影响。
+
+## 4. 编码
+
+负责人：RD / AI agent
+
+输入：DS、TASK。
+
+输出：代码变更、实现说明、风险说明。
+
+关键动作：
+
+- 按任务边界实现。
+- 维护变更与 DS、DR 的映射。
+- 运行必要验证。
+
+## 5. 测试
+
+负责人：QA / RD / AI agent
+
+输入：UR、OR、DR、DS、代码变更。
+
+输出：
+
+- TP：测试计划。
+- TC：测试用例。
+- 测试结果。
+
+关键动作：
+
+- 从需求和设计生成测试覆盖。
+- 标记正向、异常、边界、回归用例。
+- 记录未覆盖风险。
@@ -0,0 +1,54 @@
+---
+id: REVIEW-GATES-AI-RD-WORKFLOW
+type: standard
+status: draft
+created: 2026-06-29
+---
+
+# 评审门禁
+
+## Gate 1：用户需求评审
+
+通过条件：
+
+- 目标用户和核心问题明确。
+- 业务价值和优先级明确。
+- 需求范围与非目标明确。
+- 关键场景、异常场景、边界场景已覆盖。
+- 验收方向可被验证。
+
+## Gate 2：研发需求评审
+
+通过条件：
+
+- OR 能追溯到 UR、RA、SA。
+- DR 覆盖功能、非功能、接口、数据、依赖、约束。
+- 关键风险和未知项已标记 owner。
+- 拆分策略适合后续详细设计。
+
+## Gate 3：详细设计评审
+
+通过条件：
+
+- DS 能追溯到 OR、DR。
+- 模块、接口、数据、状态、异常处理清晰。
+- 每个开发任务边界清晰且可独立验证。
+- 测试点和回归影响已标注。
+
+## Gate 4：编码准出
+
+通过条件：
+
+- 代码变更能追溯到 DS/TASK。
+- 本地验证通过或说明未验证原因。
+- 变更影响范围明确。
+- 未完成项和技术债已记录。
+
+## Gate 5：测试准出
+
+通过条件：
+
+- 测试用例覆盖 UR、OR、DR、DS 的关键点。
+- 失败用例有明确处理结论。
+- 未覆盖风险已记录。
+- 需求链路状态可更新为 `verified` 或 `rework`。
@@ -0,0 +1,52 @@
+---
+id: ROLES-AI-RD-WORKFLOW
+type: standard
+status: draft
+created: 2026-06-29
+---
+
+# 角色边界
+
+## PM
+
+负责用户需求侧产物：
+
+- 收集原始输入。
+- 评审和澄清用户需求。
+- 产出 UR、RA、SA。
+- 维护业务价值、优先级和验收方向。
+
+## SE
+
+负责研发需求侧产物：
+
+- 评审 PM 产物的工程可转译性。
+- 产出 OR、DR。
+- 识别技术依赖、集成边界、非功能要求和风险。
+- 推动需求进入详细设计。
+
+## RD
+
+负责详细设计和实现：
+
+- 基于 OR、DR 产出 DS。
+- 将 DS 拆为 TASK。
+- 使用 AI agent 或人工完成编码。
+- 维护实现与设计之间的追踪关系。
+
+## QA
+
+负责测试设计和验证：
+
+- 基于 UR、OR、DR、DS 设计 TP、TC。
+- 维护覆盖关系和测试结果。
+- 标记质量风险和回归范围。
+
+## AI Agent
+
+作为执行与分析助手：
+
+- 执行 skill 中定义的流程。
+- 生成或补全阶段产物。
+- 检查追踪关系。
+- 根据 DS/TASK 编码并验证。
@@ -0,0 +1,58 @@
+---
+id: TRACEABILITY-AI-RD-WORKFLOW
+type: standard
+status: draft
+created: 2026-06-29
+---
+
+# 追踪规则
+
+## 基本规则
+
+1. 每个 artifact 必须有唯一 `id`。
+2. 每个真实需求必须有统一 `case_id`。
+3. 下游产物必须在 `source_ids` 中声明直接上游。
+4. 上游产物应在 `derived_ids` 中声明直接下游。
+5. 如果需求变更影响已通过评审的产物，必须新增变更记录或更新状态为 `rework`。
+
+## 推荐链路
+
+```text
+INTAKE
+  -> UR
+  -> RA
+  -> SA
+  -> OR
+  -> DR
+  -> DS
+  -> TASK
+  -> TP
+  -> TC
+```
+
+实际项目允许分支，例如一个 DR 产生多个 DS，一个 DS 产生多个 TASK。
+
+## 追踪矩阵字段
+
+在每个 case 的 `traceability.md` 中维护：
+
+| 上游 ID | 下游 ID | 关系 | 覆盖状态 | 备注 |
+| --- | --- | --- | --- | --- |
+| UR-xxx | OR-xxx | derives | covered | - |
+
+覆盖状态：
+
+- `covered`：已覆盖。
+- `partial`：部分覆盖。
+- `missing`：缺失。
+- `changed`：上游变更后待更新。
+- `not-applicable`：明确不适用。
+
+## AI 检查点
+
+每次进入下一阶段前，让 AI agent 检查：
+
+- 是否存在没有下游的关键上游产物。
+- 是否存在没有上游的下游产物。
+- 是否存在 status 不一致的产物。
+- 是否存在已变更但未重新评审的产物。