graph LR
    A[编写规范<br/>Spec Definition] --> B[生成代码框架<br/>Code Generation]
    B --> C[实现业务逻辑<br/>Implementation]
    C --> D[验证一致性<br/>Validation]
    D --> E{规范变更?}
    E -->|是| A
    E -->|否| F[部署上线<br/>Deployment]

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#ffe1f5
    style D fill:#e1ffe1
    style F fill:#d4edda

mindmap
  root((驱动开发<br/>方法论))
    DDD
      领域模型
      业务理解
      战略设计
      战术设计
    FDD
      功能列表
      快速迭代
      特性交付
      项目管理
    SDD
      接口规范
      代码生成
      文档同步
      契约验证
    BDD
      行为场景
      自然语言
      协作沟通
      验收测试
    TDD
      测试先行
      重构
      红绿循环

FDD 视角：
- Feature: 用户登录
- 子功能：邮箱登录、手机号登录、第三方登录

SDD 视角：
- Spec: 登录接口规范
  - 输入：邮箱/手机号 + 密码
  - 输出：token + 用户信息
  - 错误处理：密码错误、账户锁定等

DDD 视角：
- 领域：电商系统
- 实体：订单（Order）、商品（Product）
- 值对象：金额（Money）、地址（Address）
- 领域服务：订单服务（OrderService）

SDD 视角：
- API 规范：创建订单接口
  - POST /api/orders
  - Request Body: { productId, quantity, address }
  - Response: { orderId, totalAmount, status }

DDD（业务理解） → FDD（功能规划） → SDD（技术实现）
    ↓                  ↓                  ↓
  领域模型           功能列表           接口规范

graph TD
    subgraph DDD[领域驱动设计 DDD]
        D1[业务理解<br/>Business Understanding]
        D2[领域模型<br/>Domain Model]
        D3[实体与值对象<br/>Entities & Value Objects]
    end

    subgraph FDD[功能驱动开发 FDD]
        F1[功能列表<br/>Feature List]
        F2[功能设计<br/>Feature Design]
        F3[功能实现<br/>Feature Build]
    end

    subgraph SDD[规范驱动开发 SDD]
        S1[接口规范<br/>API Specification]
        S2[代码生成<br/>Code Generation]
        S3[实现验证<br/>Implementation & Validation]
    end

    D1 --> D2 --> D3
    D3 --> F1
    F1 --> F2 --> F3
    F3 --> S1
    S1 --> S2 --> S3

    style DDD fill:#e8f4f8
    style FDD fill:#fff4e6
    style SDD fill:#f0e6ff

Feature: 用户登录

  Scenario: 用户使用正确的凭证登录
    Given 用户已经注册了账号 "user@example.com"
    When 用户输入正确的邮箱和密码
    Then 用户应该成功登录
    And 系统应该返回用户信息和访问令牌

  Scenario: 用户使用错误的密码登录
    Given 用户已经注册了账号 "user@example.com"
    When 用户输入错误的密码
    Then 登录应该失败
    And 系统应该返回 "密码错误" 的提示

paths:
  /api/v1/users/login:
    post:
      requestBody:
        schema:
          type: object
          properties:
            email: {type: string, format: email}
            password: {type: string, minLength: 8}
      responses:
        '200':
          schema:
            properties:
              token: {type: string}
              userId: {type: string}

Scenario: 成功登录
  Given 存在用户 "alice@example.com" 密码为 "SecurePass123"
  When POST /api/v1/users/login
    """
    {"email": "alice@example.com", "password": "SecurePass123"}
    """
  Then 响应状态码应该是 200
  And 响应包含 "token" 和 "userId" 字段

graph LR
    A[业务需求<br/>Business Requirement] --> B[BDD 场景<br/>Behavior Scenarios]
    B --> C[SDD 规范<br/>API Specification]
    C --> D[代码实现<br/>Implementation]
    D --> E[BDD 测试<br/>Acceptance Tests]
    E --> F{测试通过?}
    F -->|否| D
    F -->|是| G[交付<br/>Delivery]

    style B fill:#e8f4f8
    style C fill:#f0e6ff
    style E fill:#e1ffe1

<<用户认证函数>>=
/**
 * 用户登录验证
 * 
 * 这个函数负责验证用户的登录凭证。
 * 如果验证成功，返回用户信息；否则返回错误。
 */
int authenticate_user(const char* username, const char* password) {
    <<验证用户名和密码>>
    <<查询数据库>>
    <<生成 token>>
    return result;
}

<<计算订单总价>>=
def calculate_total(order):
    """
    计算订单的总价

    这个函数会遍历订单中的所有商品，
    累加每个商品的价格乘以数量。
    """
    total = 0
    for item in order.items:
        total += item.price * item.quantity
    return total

# order-service.spec.yaml
endpoints:
  - name: calculateTotal
    method: POST
    path: /api/orders/calculate
    request:
      schema:
        type: object
        properties:
          items:
            type: array
            items:
              price: number
              quantity: number
    response:
      schema:
        total: number
    description: |
      计算订单的总价。
      遍历订单中的所有商品，累加每个商品的价格乘以数量。

graph TB
    subgraph Client[客户端层]
        Web[Web 应用]
        Mobile[移动应用]
    end

    subgraph Spec[规范层]
        OpenAPI[OpenAPI Spec<br/>user-service.yaml]
    end

    subgraph Generated[生成层]
        Models[数据模型<br/>Models]
        Handlers[处理器<br/>Handlers]
        Validators[验证器<br/>Validators]
        Tests[测试用例<br/>Tests]
    end

    subgraph Implementation[实现层]
        Business[业务逻辑<br/>Business Logic]
        DB[(数据库<br/>Database)]
    end

    Web --> OpenAPI
    Mobile --> OpenAPI
    OpenAPI -.生成.-> Models
    OpenAPI -.生成.-> Handlers
    OpenAPI -.生成.-> Validators
    OpenAPI -.生成.-> Tests

    Handlers --> Business
    Business --> DB

    style OpenAPI fill:#f9d5e5
    style Generated fill:#eeeeee
    style Implementation fill:#d5f4e6

# user-service.spec.yaml
openapi: 3.0.0
info:
  title: 用户服务 API
  version: 1.0.0
  description: 提供用户注册、登录、信息查询等功能

paths:
  /api/v1/users/register:
    post:
      summary: 用户注册
      description: |
        新用户注册接口。
        需要提供邮箱、密码、昵称等信息。
        系统会验证邮箱格式和密码强度。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
                - nickname
              properties:
                email:
                  type: string
                  format: email
                  description: 用户邮箱
                  example: "user@example.com"
                password:
                  type: string
                  format: password
                  minLength: 8
                  description: 密码，至少8位
                  example: "SecurePass123!"
                nickname:
                  type: string
                  minLength: 2
                  maxLength: 20
                  description: 用户昵称
                  example: "张三"
      responses:
        '201':
          description: 注册成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                    description: 用户ID
                  email:
                    type: string
                  nickname:
                    type: string
                  createdAt:
                    type: string
                    format: date-time
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "邮箱格式不正确"
        '409':
          description: 邮箱已存在

# 安装
npm install @openapitools/openapi-generator-cli -g

# 生成 Go 代码
openapi-generator-cli generate -i user-service.spec.yaml -g go -o ./generated

# 生成 TypeScript 代码
openapi-generator-cli generate -i user-service.spec.yaml -g typescript-axios -o ./generated

# 生成 Python 代码
openapi-generator-cli generate -i user-service.spec.yaml -g python -o ./generated

# 使用 Docker
docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate \
  -i /local/user-service.spec.yaml \
  -l go \
  -o /local/generated

# 安装
go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest

# 生成 Go 代码
oapi-codegen -package models user-service.spec.yaml > models/user.go

// generated/models/user.go
package models

type RegisterRequest struct {
    Email    string `json:"email" validate:"required,email"`
    Password string `json:"password" validate:"required,min=8"`
    Nickname string `json:"nickname" validate:"required,min=2,max=20"`
}

type RegisterResponse struct {
    UserID    string `json:"userId"`
    Email     string `json:"email"`
    Nickname  string `json:"nickname"`
    CreatedAt string `json:"createdAt"`
}

// generated/handlers/user_handler.go
package handlers

func RegisterUser(w http.ResponseWriter, r *http.Request) {
    // TODO: 实现注册逻辑
    // 1. 解析请求体
    // 2. 验证邮箱格式和密码强度
    // 3. 检查邮箱是否已存在
    // 4. 创建用户
    // 5. 返回响应
}

func RegisterUser(w http.ResponseWriter, r *http.Request) {
    // 1. 解析请求体
    var req models.RegisterRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        respondError(w, http.StatusBadRequest, "请求参数错误")
        return
    }

    // 2. 验证邮箱格式和密码强度
    if !isValidEmail(req.Email) {
        respondError(w, http.StatusBadRequest, "邮箱格式不正确")
        return
    }

    // 3. 检查邮箱是否已存在
    if userRepo.Exists(req.Email) {
        respondError(w, http.StatusConflict, "邮箱已存在")
        return
    }

    // 4. 创建用户
    user := &models.User{
        Email:    req.Email,
        Password: hashPassword(req.Password),
        Nickname: req.Nickname,
    }
    if err := userRepo.Create(user); err != nil {
        respondError(w, http.StatusInternalServerError, "创建用户失败")
        return
    }

    // 5. 返回响应
    respondJSON(w, http.StatusCreated, models.RegisterResponse{
        UserID:    user.ID,
        Email:     user.Email,
        Nickname:  user.Nickname,
        CreatedAt: user.CreatedAt.Format(time.RFC3339),
    })
}

# 验证 OpenAPI 规范文件格式
swagger-cli validate user-service.spec.yaml

# 使用 Spectral 进行更严格的校验
spectral lint user-service.spec.yaml

# 生成文档（验证规范可用性）
redoc-cli bundle user-service.spec.yaml -o docs/api.html

graph LR
    A[0. 初始化项目<br/>specify init] --> B[1. 建立宪章<br/>/speckit.constitution]
    B --> C[2. 定义规范<br/>/speckit.specify]
    C --> D[AI：生成规范文档<br/>spec.md]
    D --> E[3. 技术方案<br/>/speckit.plan]
    E --> F[AI：创建方案<br/>plan.md]
    F --> G[4. 任务列表<br/>/speckit.tasks]
    G --> H[AI：生成任务<br/>tasks.md]
    H --> I[5. 执行实现<br/>/speckit.implement]
    I --> J[AI：实现代码]

    style A fill:#e1f5ff
    style B fill:#ffe1e1
    style C fill:#fff4e6
    style E fill:#f0e6ff
    style G fill:#e6ffe6
    style I fill:#ffe6e6

# 在当前目录初始化项目
specify init --here --force --ai cursor-agent

# 或者创建新项目目录
specify init my-project --ai cursor-agent

/speckit.constitution Create principles focused on code quality, testing standards, 
user experience consistency, and performance requirements

# 项目宪章 (Project Constitution)

## 代码质量原则
- 所有代码必须遵循 SOLID 原则
- 函数单一职责，最大长度不超过 50 行
- 必须有清晰的命名和注释
- 代码覆盖率不低于 80%

## 测试标准
- 所有公共 API 必须有单元测试
- 关键业务逻辑必须有集成测试
- 遵循 TDD 开发模式：先写测试，再写实现
- 测试命名格式：Should_ExpectedBehavior_When_Condition

## 用户体验一致性
- 所有界面必须支持响应式设计
- 加载时间不超过 3 秒
- 错误信息必须清晰且可操作
- 支持键盘快捷键操作

## 性能要求
- API 响应时间 < 200ms (P95)
- 数据库查询必须有索引优化
- 静态资源必须启用缓存
- 支持水平扩展

## 安全要求
- 所有输入必须验证和消毒
- 敏感数据必须加密存储
- 使用 HTTPS 传输
- 定期进行安全审计

我想创建一个任务管理应用 Taskify，具有以下功能：
- 用户可以创建、编辑、删除任务
- 任务可以分配给团队成员
- 支持任务的优先级和截止日期
- 实时通知和更新

我们将使用 .NET Aspire 和 Postgres 数据库。
前端使用 Blazor Server，支持拖拽式任务面板和实时更新。
创建 REST API，包括项目 API、任务 API 和通知 API。

/speckit.tasks

/speckit.implement

.
├── CLAUDE.md                    # AI 助手配置（由 specify init 创建）
├── memory/
│   └── constitution.md          # 项目宪章（原则和约束）⭐️
├── specs/
│   └── 001-create-taskify/
│       ├── spec.md              # 功能规范
│       ├── plan.md              # 实现计划
│       ├── tasks.md             # 任务列表
│       ├── data-model.md        # 数据模型
│       ├── research.md          # 技术研究
│       ├── quickstart.md        # 快速开始指南
│       └── contracts/
│           ├── api-spec.json    # API 规范（可转为 OpenAPI）
│           └── signalr-spec.md  # SignalR 规范
├── scripts/
│   ├── check-prerequisites.sh   # 检查前置条件
│   ├── setup-plan.sh            # 规划脚本
│   ├── create-new-feature.sh    # 功能创建脚本
│   ├── update-claude-md.sh      # 更新 AI 配置
│   └── common.sh                # 通用工具函数
└── templates/
    ├── CLAUDE-template.md       # AI 配置模板
    ├── spec-template.md         # 规范模板
    ├── plan-template.md         # 计划模板
    └── tasks-template.md        # 任务模板

# 0. 初始化 Spec-Kit 项目
specify init --here --force --ai cursor-agent

# 1. 建立项目原则（定义代码质量、测试、性能等标准）
/speckit.constitution Create principles focused on code quality, testing standards, 
user experience consistency, and performance requirements

# 2. 使用 Spec-Kit 定义项目规范
/speckit.specify

# 3. 使用 Spec-Kit 创建技术方案（包括 API 规范）
/speckit.plan

# 4. 从 Spec-Kit 生成的 API 规范创建 OpenAPI 文档
cp specs/001-feature/contracts/api-spec.json openapi.yaml

# 5. 用 OpenAPI 工具生成客户端 SDK
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client

# 6. 生成任务列表
/speckit.tasks

# 7. 用 Spec-Kit 实现服务端代码（AI 会遵循 constitution 中的原则）
/speckit.implement

# 8. 用 OpenAPI 工具生成 API 文档
redoc-cli bundle openapi.yaml -o docs/api.html

# 9. 启动 Mock 服务（前端开发可以并行进行）
prism mock openapi.yaml

# OpenAPI Generator（支持 50+ 语言）
openapi-generator-cli generate -i api.yaml -g go -o ./client

# Swagger Codegen（老牌工具）
swagger-codegen generate -i api.yaml -l java -o ./client

# oapi-codegen（Go 专用，轻量高效）
oapi-codegen -package api api.yaml > api/generated.go

# Swagger UI（最流行）
docker run -p 8080:8080 -e SWAGGER_JSON=/api.yaml -v ${PWD}:/api swaggerapi/swagger-ui

# Redoc（更现代的风格）
redoc-cli bundle api.yaml -o docs/index.html

# Stoplight Elements（交互式文档）
npx @stoplight/elements-dev-portal api.yaml

# Prism（推荐，功能强大）
prism mock api.yaml

# Mockoon（GUI 工具）
mockoon-cli start --data api.yaml

# json-server + OpenAPI
openapi-backend mock api.yaml --port 3000

# Swagger CLI（基础验证）
swagger-cli validate api.yaml

# Spectral（规则引擎，可自定义校验规则）
spectral lint api.yaml

# OpenAPI Enforcer（严格校验）
openapi-enforcer validate api.yaml

# 1. 编写/更新规范
vim api.spec.yaml

# 2. 验证规范
spectral lint api.spec.yaml

# 3. 生成代码框架
openapi-generator-cli generate -i api.spec.yaml -g go -o ./generated

# 4. 生成文档
redoc-cli bundle api.spec.yaml -o docs/api.html

# 5. 启动 Mock 服务（供前端开发）
prism mock api.spec.yaml &

# 6. 实现业务逻辑
vim src/handlers/user.go

# 7. 运行测试
go test ./...

# 使用 Makefile 简化流程
cat > Makefile << 'EOF'
.PHONY: validate generate docs mock

validate:
    spectral lint api.yaml

generate:
    openapi-generator-cli generate -i api.yaml -g go -o ./generated

docs:
    redoc-cli bundle api.yaml -o docs/api.html

mock:
    prism mock api.yaml

all: validate generate docs
EOF

# 然后只需要
make all

# .github/workflows/openapi.yml
name: OpenAPI Workflow

on: [push, pull_request]

jobs:
  validate-and-generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Validate OpenAPI Spec
        run: |
          npm install -g @stoplight/spectral-cli
          spectral lint api.yaml

      - name: Generate Code
        run: |
          docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate \
            -i /local/api.yaml \
            -g go \
            -o /local/generated

      - name: Generate Docs
        run: |
          npm install -g redoc-cli
          redoc-cli bundle api.yaml -o docs/api.html

      - name: Commit Generated Files
        run: |
          git add generated/ docs/
          git commit -m "Auto-generated from OpenAPI spec" || true

sequenceDiagram
    participant PM as 产品经理
    participant BE as 后端开发
    participant FE as 前端开发
    participant Spec as 规范文件
    participant Tool as spec-kit
    participant CI as CI/CD

    PM->>BE: 提出需求
    BE->>Spec: 编写 API 规范
    BE->>Tool: 生成代码框架
    Tool-->>BE: 返回代码骨架

    par 并行开发
        BE->>BE: 实现业务逻辑
    and
        Tool->>FE: 生成 Mock 服务
        FE->>FE: 前端开发与联调
    end

    BE->>Tool: 生成 API 文档
    Tool-->>FE: 提供最新文档

    BE->>BE: 完成实现
    BE->>Tool: 验证规范一致性
    Tool-->>BE: 验证通过

    BE->>CI: 提交代码
    CI->>Tool: 自动验证规范
    Tool-->>CI: 验证通过
    CI->>CI: 部署到测试环境

    FE->>BE: 联调真实 API
    FE-->>BE: 反馈问题
    BE->>Spec: 更新规范
    Note over BE,Spec: 规范变更，<br/>重新生成代码

    style Spec fill:#f9d5e5
    style Tool fill:#d5f4e6
    style CI fill:#eeeeee

graph TB
    Start{项目规模?}
    Start -->|大型/企业级| A[完整 SDD 工具链<br/>spec-kit + OpenAPI]
    Start -->|中型/团队项目| B[轻量级方案<br/>Markdown + 结构化注释]
    Start -->|小型/个人项目| C[极简方案<br/>测试即规范]

    A --> A1[自动代码生成<br/>多语言支持<br/>Mock 服务器<br/>完整文档]
    B --> B1[手动代码框架<br/>文档模板<br/>脚本辅助]
    C --> C1[测试驱动<br/>代码注释<br/>最小化文档]

    style A fill:#ff6b6b
    style B fill:#ffd93d
    style C fill:#6bcf7f
    style A1 fill:#ffe5e5
    style B1 fill:#fff8e1
    style C1 fill:#e8f5e9

# user-service-api.md

## 用户注册接口

**路径：** POST /api/v1/users/register

**请求：**
```json
{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "nickname": "张三"
}

{
  "userId": "123",
  "email": "user@example.com",
  "nickname": "张三",
  "createdAt": "2025-11-09T20:20:00Z"
}

然后在代码中引用：

```go
// 实现规范：user-service-api.md#用户注册接口
func RegisterUser(w http.ResponseWriter, r *http.Request) {
    // 按照规范实现...
}

// @spec: User Registration API
// @method: POST
// @path: /api/v1/users/register
// @request:
//   email: string (required, email format)
//   password: string (required, min 8 chars)
//   nickname: string (required, 2-20 chars)
// @response:
//   201: { userId, email, nickname, createdAt }
//   400: { error: "请求参数错误" }
//   409: { error: "邮箱已存在" }
func RegisterUser(w http.ResponseWriter, r *http.Request) {
    // 实现...
}

func TestUserRegistration(t *testing.T) {
    // 规范：用户注册成功
    t.Run("注册成功", func(t *testing.T) {
        req := RegisterRequest{
            Email:    "user@example.com",
            Password: "SecurePass123!",
            Nickname: "张三",
        }
        resp := RegisterUser(req)
        assert.Equal(t, 201, resp.StatusCode)
        assert.NotEmpty(t, resp.UserID)
    })

    // 规范：邮箱格式错误
    t.Run("邮箱格式错误", func(t *testing.T) {
        req := RegisterRequest{
            Email:    "invalid-email",
            Password: "SecurePass123!",
            Nickname: "张三",
        }
        resp := RegisterUser(req)
        assert.Equal(t, 400, resp.StatusCode)
        assert.Contains(t, resp.Error, "邮箱格式")
    })

    // 规范：邮箱已存在
    t.Run("邮箱已存在", func(t *testing.T) {
        // 先创建一个用户
        RegisterUser(RegisterRequest{Email: "existing@example.com", ...})

        // 再次注册相同邮箱
        req := RegisterRequest{
            Email:    "existing@example.com",
            Password: "SecurePass123!",
            Nickname: "李四",
        }
        resp := RegisterUser(req)
        assert.Equal(t, 409, resp.StatusCode)
    })
}

## API 规范

### 接口名称
[描述]

### 请求格式
[格式]

### 响应格式
[格式]

### 实现
- [ ] 代码实现
- [ ] 测试用例
- [ ] 文档更新

# 使用工具从代码提取 API 信息
swagger-codegen generate -i existing-code -o spec.yaml

# 或手动整理
# 1. 列出所有接口
# 2. 提取请求/响应结构
# 3. 整理成规范格式

# api.v1.spec.yaml
openapi: 3.0.0
info:
  version: 1.0.0

# api.v2.spec.yaml  
openapi: 3.0.0
info:
  version: 2.0.0

## 规范审查清单

- [ ] 接口命名是否清晰？
- [ ] 请求/响应格式是否完整？
- [ ] 错误处理是否全面？
- [ ] 是否有安全考虑？
- [ ] 是否有性能要求？

graph LR
    subgraph 需求阶段
        BDD[BDD<br/>定义行为]
    end

    subgraph 设计阶段
        DDD[DDD<br/>领域建模]
        FDD[FDD<br/>功能拆分]
    end

    subgraph 实现阶段
        SDD[SDD<br/>接口规范]
        TDD[TDD<br/>测试驱动]
    end

    subgraph 交付阶段
        CI[持续集成<br/>CI/CD]
    end

    BDD --> DDD
    DDD --> FDD
    FDD --> SDD
    SDD --> TDD
    TDD --> CI

    style BDD fill:#e8f4f8
    style DDD fill:#e8f4f8
    style FDD fill:#fff4e6
    style SDD fill:#f0e6ff
    style TDD fill:#e1ffe1
    style CI fill:#d4edda

# SDD 快速参考

## 基本流程
1. 编写规范 → 2. 生成代码 → 3. 实现逻辑 → 4. 验证一致性

## 工具选择
- 大型项目：OpenAPI + spec-kit
- 中型项目：Markdown + 脚本
- 小型项目：测试 + 注释

## 最佳实践
✅ 规范先于代码
✅ 规范即文档
✅ 自动化验证
✅ 版本控制
✅ 团队协作

## 常见陷阱
❌ 先写代码后补规范
❌ 规范和代码不同步
❌ 过度设计
❌ 忽视工具学习成本