ai-robot-core/docs/spec-product-zh.md

---
name: spec-product-zh
version: 1.3.0
description: "基于 Kiro Spec-Driven Development 与 API-First 思想的‘规范驱动+接口先行’协同开发方法论。通过结构化文档（Requirements/OpenAPI/Design/Tasks）实现 AI 开发的全链路可控与高效协作。"
license: MIT
compatibility: opencode
metadata:
  audience: "开发者, 架构师, AI 智能体"
  workflow: specification
  language: zh-CN
  methodology:
    - "Kiro Spec-Driven Development"
    - "API-First (接口先行)"
  artifacts:
    - requirements.md
    - openapi.provider.yaml
    - openapi.deps.yaml
    - design.md
    - tasks.md
---

# 规范驱动 + 接口先行（Spec-Driven + API-First）开发方法论

本方法论旨在通过结构化规范文档作为人类与 AI 的“共同语言”，并以接口契约作为协作锚点，实现多角色 AI 的并行、有序、高质量开发。

> 职责边界：
> - 本文档专注于**生成规范文档**（requirements/design/tasks/openapi）。
> - AI 在编码阶段的行为准则、门禁、引用规则等执行规范：遵循项目根目录 `agents.md`。
> - 契约成熟度与门禁的硬规则（给 AI）：见 `spec/contracting.md`。
> - hooks/构建检查等落地细则（给人）：见 `docs/contracting-guide.md`。

---

## 0. 前置步骤：模块拆分与依赖接口盘点（Module & Dependency Scoping）

在进入“某个模块的 Spec 生成”之前，必须先做一次轻量的边界澄清，否则后续文档会不可控、也无法高效并行。

### 0.1 产出物

建议在本模块的 Spec 目录下新增一个轻量清单（可写在 `requirements.md` 中的 Scope/Dependencies 小节，或单独写在 `scope.md`）：

- **模块边界说明（Module Scope）**：本次 Spec 只覆盖哪个模块/子域？不覆盖什么？
- **依赖清单（Dependencies）**：本模块会调用哪些外部模块/第三方？
- **依赖接口清单（Dependency Contracts）**：对每个依赖，列出“需要的接口能力”（先不管实现在哪）。

### 0.2 判定标准（进入第 1 阶段的准入条件）

- 能明确回答：
  - “这是哪个模块的需求？”
  - “本模块对外提供什么能力？”
  - “本模块依赖谁？依赖哪些接口？”
- 若依赖不明确：先补齐依赖接口清单（哪怕先是草案），再进入需求与接口建模。

---

## 1. 核心流程：三阶段协同（每次只做一个模块/一个领域边界）

### 第一阶段：需求定义与接口建模（Requirements & API Design）

- **目标**：明确“做什么”以及“如何交互”，建立单一可信源（SSOT）。
- **模块化原则**：对于庞大系统，一个 Spec 上下文应**仅聚焦于一个功能模块或领域边界**（如 `ruoyi-forum`），避免跨模块需求混杂导致 AI 上下文过载。
- **依赖先行（Dependency-First）**：
  - 如果本模块依赖其他模块（或第三方服务），必须在此阶段先完成**外部依赖接口契约**（哪怕只有最小集合）。
  - **调用方**：基于依赖契约生成 Mock 并直接进入开发逻辑，无需等待被调用方实现。
  - **实现方**：后续根据该依赖契约补全真实实现，并通过契约一致性验证。
- **产出**（默认建议放在 `spec/<module>/` 目录下，例如 `spec/ruoyi-forum/requirements.md`）：
  - `requirements.md`（本模块需求）
  - `openapi.provider.yaml`（本模块对外提供的 API）
  - `openapi.deps.yaml`（本模块依赖的外部 API 契约，供 Mock/SDK 生成）

### 第二阶段：技术设计与方案评审（Technical Design）

- **目标**：细化“怎么实现”，解决技术实现路径与数据模型问题。
- **产出**：`design.md`（技术蓝图）。
- **规范**：
  - 设计方案必须引用需求 ID。
  - 若涉及跨模块调用，应明确定义：依赖 API 的 Mock 策略、超时/重试/熔断/降级、错误映射。

### 第三阶段：任务分解与并行开发（Task Decomposition & Implementation）

- **目标**：将设计转化为可执行的原子任务。
- **并行编程协作（多窗口并行）**：
  - **前端/调用方 AI**：基于 `openapi.provider.yaml` + `openapi.deps.yaml` 生成 SDK + Mock，优先完成页面与业务流程。
  - **后端/提供方 AI**：实现 `openapi.provider.yaml` 对应接口，并持续导出 OpenAPI 工件供校验。
  - **依赖实现方 AI**：对照 `openapi.deps.yaml`（或其子集）补齐真实实现。
- **产出**：`tasks.md`（执行清单）。

---

## 2. 关键文档规范

### 2.1 requirements.md（需求规范）

requirements 的目标是把“自然语言需求”固化为**可追踪、可校验、可版本化**的规范。

必须包含以下结构：
- **Frontmatter**：包含 `feature_id`, `title`, `status`, `version`（可按团队需要扩展）。
- **用户故事**：使用统一句式“作为…我希望…以便…”。
- **验收标准（EARS 语法）**：每条验收标准必须带稳定 ID（推荐 `AC-<FEATURE>-NN`）。
- **追踪映射（Traceability）**：验收标准到接口端点（以及可选 operationId）的映射。

#### 2.1.1 requirements.md 标准模板（可直接复制）

```markdown
---
feature_id: "REG"               # 功能短 ID（用于拼接 US/AC/NFR 编号）
title: "用户注册"
status: "draft"                # draft | review | approved | implemented
version: "0.1.0"
owners:
  - "product"
  - "backend"
  - "frontend"
last_updated: "2026-02-23"
source:
  type: "conversation"          # conversation | issue | doc | meeting
  ref: ""
---

# 用户注册（REG）

## 1. 背景与目标
- 背景：
- 目标：
- 非目标（Out of Scope）：

## 2. 模块边界（Scope）
- 覆盖：
- 不覆盖：

## 3. 依赖盘点（Dependencies）
- 依赖模块/第三方：
  - 依赖 A：用途说明
  - 依赖 B：用途说明

## 4. 用户故事（User Stories）
- [US-REG-01] 作为访客，我希望使用邮箱注册账号，以便获得会员权益。

## 5. 验收标准（Acceptance Criteria, EARS）
- [AC-REG-01] WHEN 访客提交有效的邮箱与密码 THEN 系统 SHALL 创建用户并返回 201。
- [AC-REG-02] WHEN 访客提交的邮箱不合法 THEN 系统 SHALL 返回 400，并给出字段级错误信息。
- [AC-REG-03] WHEN 邮箱已被注册 THEN 系统 SHALL 返回 400，并提示“邮箱已注册”。

## 6. 追踪映射（Traceability）

| AC ID | Endpoint | 方法 | operationId（可选） | 备注 |
|------|----------|------|---------------------|------|
| AC-REG-01 | /users/register | POST | registerUser | 创建用户 |
| AC-REG-02 | /users/register | POST | registerUser | 参数校验 |
| AC-REG-03 | /users/register | POST | registerUser | 唯一性约束 |
```

### 2.2 OpenAPI 契约（openapi.provider.yaml / openapi.deps.yaml）

为支持“大系统多模块 + 多窗口并行”，推荐将 OpenAPI **拆成两份**：

- `openapi.provider.yaml`：**本模块对外提供**的 API（本模块是 Provider）。
- `openapi.deps.yaml`：**本模块依赖**的外部 API 契约（本模块是 Consumer，便于 Mock/SDK 生成）。

约定：
- 两份文件都必须可被 Mock/SDK/测试工具消费。
- Provider 文件建议带 `x-requirements: [AC-xxx]` 追踪需求。
- Deps 文件应定义你“需要对方提供什么能力”，不以对方当前实现为准（可以先草案，后续对齐）。

---

#### 2.2.1 契约成熟度（Contract Refinement Levels）

为减少“边实现边改契约”导致的需求偏移，本方法论引入契约成熟度等级，并要求在 OpenAPI 的 `info` 下进行**全局标记**：

- `info.x-contract-level: L0 | L1 | L2 | L3`

> 约定：
> - `openapi.deps.yaml` 与 `openapi.provider.yaml` 都必须标记该字段。
> - L0/L1 用于并行启动；Provider 在进入可合并的实现阶段前应提升到 L2。

**L0（占位/可 Mock）**
- 目标：调用方可快速生成 Mock，跑通主流程（happy path）。
- 必须：最小 path/method/2xx 响应骨架；统一错误响应骨架（可粗）。
- 允许：schema 粗粒度、校验缺失、错误码不细。

**L1（可调用/可生成 SDK）**
- 目标：调用方可基于契约生成 SDK，并开发主要业务流程。
- 必须：关键请求/响应字段（必填/可选）、基本状态码集合、operationId、描述。

**L2（可验收/可契约测试）**
- 目标：提供者可运行 Provider-driven 契约校验（schema/错误语义/边界）。
- 必须：关键校验规则（format/minLength/enum/range 等）、结构化错误模型、核心异常分支。

**L3（可演进/可兼容治理）**
- 目标：长期维护与兼容演进，减少 breaking change。
- 必须：deprecated/兼容策略、示例（examples）、变更记录（changelog 或版本策略）。

#### 2.2.2 从轻量切分到可验收契约：细化路径

- 在第 0 节（Scoping）阶段：输出依赖能力清单（自然语言即可），并将其转写为 `openapi.deps.yaml` 的 **L0** 草案。
- 在第 1 阶段（需求与接口建模）阶段：
  - 新增/完善 AC（EARS）会驱动契约从 L0 → L1（补齐核心字段、状态码与映射）。
  - 每个新增字段/错误语义/校验规则，应能追溯到某条 `AC-*`（否则属于“潜在需求漂移”）。
- 在进入“提供者实现可合并”之前：必须将 `openapi.provider.yaml` 提升到 **L2**（达到可契约测试的程度）。
- 在产品稳定期：逐步推动关键接口达到 **L3**（兼容治理与示例完善）。

> 门禁落点（实现细节）：成熟度等级与合并策略、校验规则应由 `agents.md` 中的执行规则 + Git hooks/构建检查共同约束。

### 2.3 design.md（技术设计）

- **内容**：系统架构、数据模型（ER 图）、核心流程、异常与重试、鉴权与审计。
- **跨模块调用要求**：必须描述依赖 API 的失败策略（超时/重试/熔断/降级）以及错误映射。

### 2.4 tasks.md（任务清单）

- **结构**：带状态的 Markdown 任务列表。
- **要求**：任务按“本模块提供能力”与“本模块消费依赖”拆分；每个任务需标注关联 `AC-ID`。

---

## 3. 自动化协同增强（Hooks/门禁）

本方法论要求在流程中引入自动化门禁，以确保文档与交付一致。

- 当 `requirements.md` / OpenAPI 文件变更时，应触发：OpenAPI Lint、Diff（兼容性检查）、契约一致性测试。
- 当 `tasks.md` 任务完成时，应同步更新进度与相关说明。

> 说明：关于“AI 编码行为准则、阶段闸门、引用规则、变更策略”等执行层规范，见项目根目录 `agents.md`；关于 hooks/构建检查等落地细则，见 `docs/contracting-guide.md`。

---

## 4. 版本化迭代规则（Version Iteration Protocol）

### 4.1 问题背景

在多次迭代后，规范文档（尤其是 `requirements.md`）会因 AC 不断累积导致文档膨胀，进而引发：
- AI 上下文快速占满（单个文档可能 500+ 行）
- 历史需求干扰当前迭代的理解
- 难以快速定位当前活跃的 AC 范围

### 4.2 解决方案：单文档内版本分区

采用 **单文档内版本分区 + 历史折叠** 策略：
- 保留最近 1-2 个版本为”活跃版本”（展开）
- 将更早的版本折叠为 `<details>` 标签（AI 默认跳过）
- 在 frontmatter 中标记 `active_version` 和 `version_history`

### 4.3 requirements.md 版本化模板

```markdown
---
feature_id: “MOD”                   # 模块短 ID
title: “模块需求规范”
status: “in-progress”
version: “0.3.0”                    # 当前最新版本
active_version: “0.2.0-0.3.0”      # 活跃版本范围（展开显示）
version_history:                    # 版本历史索引
  - version: “0.3.0”
    ac_range: “AC-MOD-21~30”
    description: “功能增强 C”
  - version: “0.2.0”
    ac_range: “AC-MOD-11~20”
    description: “功能扩展 B”
  - version: “0.1.0”
    ac_range: “AC-MOD-01~10”
    description: “基础功能 A（已折叠）”
last_updated: “2026-02-27”
---

# 模块需求规范（MOD）

## 1. 背景与目标
[保持不变，描述整体背景]

## 2. 模块边界（Scope）
[保持不变]

## 3. 依赖盘点（Dependencies）
[保持不变]

## 4. 用户故事（User Stories）
[仅保留活跃版本的 US，历史 US 折叠]

## 5. 验收标准（Acceptance Criteria, EARS）

### 📌 当前活跃版本（v0.2.0 - v0.3.0）

#### 5.2 功能扩展 B（v0.2.0）
- [AC-MOD-11] WHEN 用户执行操作 X THEN 系统 SHALL 返回结果 Y
- [AC-MOD-12] WHEN 参数无效 THEN 系统 SHALL 返回 400 错误
[展开显示 v0.2.0 的所有 AC]

#### 5.3 功能增强 C（v0.3.0）
- [AC-MOD-21] WHEN 用户触发事件 Z THEN 系统 SHALL 执行流程 W
- [AC-MOD-22] WHEN 条件满足 THEN 系统 SHALL 更新状态
[展开显示 v0.3.0 的所有 AC]

---

### 📦 历史版本（已归档）

<details>
<summary>v0.1.0：基础功能 A（AC-MOD-01~10）</summary>

#### 5.1 基础功能 A（v0.1.0）
- [AC-MOD-01] WHEN 用户提交请求 THEN 系统 SHALL 处理并返回
- [AC-MOD-02] WHEN 请求格式错误 THEN 系统 SHALL 返回错误信息
[折叠的历史 AC]

</details>

## 6. 追踪映射（Traceability）
[仅保留活跃版本的映射表]

| AC ID | Endpoint | 方法 | operationId | 备注 |
|------|----------|------|-------------|------|
| AC-MOD-11 | /api/resource | GET | getResource | v0.2.0 |
| AC-MOD-21 | /api/resource | POST | createResource | v0.3.0 |
```

### 4.4 AI 执行规则（新增迭代需求时）

当用户提出新迭代需求时，AI 必须：

1. **读取 frontmatter**：识别 `version` 和 `active_version`
2. **确定新版本号**：按语义化版本递增（如 `0.6.0` → `0.7.0`）
3. **判断是否需要折叠**：
   - 若活跃版本已有 2 个（如 `0.5.0-0.6.0`），则将最旧的版本（`0.5.0`）折叠
   - 若活跃版本仅 1 个，则保留并追加新版本
4. **追加新需求**：
   - 在”当前活跃版本”区域末尾追加新章节（如 `#### 5.7 新功能（v0.7.0）`）
   - 新 AC 编号延续上一版本（如上一版本最大为 `AC-AISVC-90`，则新版本从 `AC-AISVC-91` 开始）
5. **更新 frontmatter**：
   - `version: “0.7.0”`
   - `active_version: “0.6.0-0.7.0”`
   - 在 `version_history` 中追加新版本记录
6. **更新追踪映射表**：仅保留活跃版本的映射

### 4.5 折叠策略

- **保留活跃版本数**：最多 2 个版本展开（当前版本 + 上一版本）
- **折叠粒度**：按大版本折叠（如 `v0.1.0-0.4.0` 合并为一个折叠块）
- **折叠标记**：使用 `<details><summary>` 标签，AI 读取时会自动跳过折叠内容
- **AC 编号连续性**：折叠不影响 AC 编号的全局唯一性，新 AC 始终递增

### 4.6 示例：从 v0.2.0 迭代到 v0.3.0

**用户需求**：新增”功能增强 C”

**AI 执行步骤**：
1. 读取 `requirements.md`，识别当前 `version: “0.2.0”`，`active_version: “0.1.0-0.2.0”`
2. 确定新版本号为 `0.3.0`
3. 将 `v0.1.0` 的内容移入 `<details>` 折叠块
4. 在”当前活跃版本”区域追加 `#### 5.3 功能增强 C（v0.3.0）`
5. 新 AC 从 `AC-MOD-21` 开始编号（上一版本最大为 `AC-MOD-20`）
6. 更新 frontmatter：
   ```yaml
   version: “0.3.0”
   active_version: “0.2.0-0.3.0”
   version_history:
     - version: “0.3.0”
       ac_range: “AC-MOD-21~30”
       description: “功能增强 C”
     - version: “0.2.0”
       ac_range: “AC-MOD-11~20”
       description: “功能扩展 B”
     - version: “0.1.0”
       ac_range: “AC-MOD-01~10”
       description: “基础功能 A（已折叠）”
   ```

---

## 5. 如何执行

1. **前置步骤**：完成模块拆分与依赖接口盘点（第 0 节）。
2. **发起需求**：仅针对”一个模块”，生成初始 `requirements.md`（v0.1.0）。
3. **定义契约**：输出 `openapi.provider.yaml` 与 `openapi.deps.yaml`，并进行接口走查。
4. **架构设计**：生成 `design.md`，明确模块内边界、数据流与依赖策略。
5. **任务执行**：生成并执行 `tasks.md`；调用方优先基于 deps 契约 Mock 并行推进。
6. **迭代需求**：按”版本化迭代规则”（第 4 节）追加新版本需求，保持文档精简。