api-designer

Skill: API Designer

基于时序图设计 OpenAPI 3.0+ YAML 规格，让 API 从场景中自然浮现而非凭空定义。每个端点可追溯到时序图的 Step 编号，确保"无场景不设计 API"。

触发条件

• 用户要求设计 API 或编写 API 文档
• 用户提到 "Phase 3 Step 2"、"API 设计"
• 已有场景时序图，需要细化 API 规格
• 用户提供了一个 API 端点需要详细设计

前置依赖

• logos/resources/prd/3-technical-plan/2-scenario-implementation/ 中包含场景时序图
• logos/resources/prd/3-technical-plan/1-architecture/ 中包含架构概要（确认前后端分离方式、认证方案等）
• logos-project.yaml 的 tech_stack 已填写

如果时序图目录为空，提示用户先完成 Phase 3 Step 1（scenario-architect）。

核心能力

1. 从时序图中提取所有跨系统边界的 API 调用
2. 去重、合并、按领域分组，形成端点清单
3. 设计 OpenAPI 3.0+ YAML 规格（路径、参数、请求体、响应结构）
4. 定义统一的错误响应格式和错误码体系
5. 设计认证方案（Bearer Token / API Key / Cookie）
6. 设计分页、排序、过滤的标准化参数

执行步骤

Step 1: 读取场景上下文

读取以下文件建立完整上下文：

• 场景时序图（logos/resources/prd/3-technical-plan/2-scenario-implementation/）：提取所有跨系统边界的箭头
• 架构概要（logos/resources/prd/3-technical-plan/1-architecture/）：确认认证方案、前后端分离方式、API 网关等
• logos-project.yaml：读取 tech_stack 确认后端框架和部署方式

Step 2: 提取端点清单

遍历所有场景时序图，收集每个跨系统边界的调用箭头：

1. 识别"跨系统边界"的箭头——客户端到服务端、服务端到外部服务、服务间调用
2. 为每个箭头提取：HTTP 方法、路径、所属场景编号和 Step 编号
3. 去重合并——同一个端点可能在多个场景中出现（如 POST /api/auth/login 可能在 S02 和 S03 都有）
4. 输出端点清单摘要供用户确认：

从时序图中识别到 N 个 API 端点：

| # | 方法 | 路径 | 来源场景 | 领域 |
|---|------|------|---------|------|
| 1 | POST | /api/auth/register | S01 Step 2 | auth |
| 2 | POST | /api/auth/login | S02 Step 1 | auth |
| 3 | GET  | /api/projects | S04 Step 1 | projects |

Step 3: 按领域分组

将端点按业务领域分组，每组对应一个 YAML 文件：

• auth.yaml — 认证相关（注册、登录、登出、重置密码）
• projects.yaml — 核心业务对象的 CRUD
• billing.yaml — 支付和订阅

分组原则：

• 同一数据实体的操作放在一起
• 认证/授权独立分组
• 第三方服务回调（如支付回调）放在对应业务领域

Step 4: 设计统一约定

在生成具体端点前，先确定全局约定：

认证方案（从架构概要中读取）：

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

统一错误响应：

components:
  schemas:
    ErrorResponse:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: 机器可读的错误码（如 EMAIL_EXISTS）
        message:
          type: string
          description: 人类可读的错误描述
        details:
          type: object
          description: 附加错误信息（如字段级校验错误）