db-designer

Skill: DB Designer

从 API 规格推导数据库表结构，生成对应方言的 SQL DDL。数据库类型由 Phase 3 Step 0 技术选型确定，确保字段类型、约束、索引和安全策略与 API 端点完全对齐。

触发条件

• 用户要求设计数据库或编写 SQL
• 用户提到 "Phase 3 Step 2"、"DB 设计"、"表结构"
• 已有 API YAML 规格，需要推导数据库设计
• 用户提供了数据模型需要转化为 DDL

核心能力

1. 从 API 请求/响应结构推导表结构
2. 读取 logos-project.yaml 的 tech_stack.database 确定数据库类型
3. 生成对应数据库方言的 SQL DDL
4. 设计索引并说明设计理由
5. 设计安全策略（RLS / 应用层权限）
6. 为每张表、每个字段添加注释

前置依赖

• logos/resources/api/ 中包含 API YAML 规格（api-designer 产出）
• logos-project.yaml 的 tech_stack.database 已填写

如果 API 目录为空，提示用户先完成 Phase 3 Step 2 的 API 设计（api-designer）。如果 tech_stack.database 未填写，提示用户先完成 Phase 3 Step 0（architecture-designer）。

执行步骤

Step 1: 确认数据库类型

读取 logos/logos-project.yaml 的 tech_stack 字段，确定数据库类型和方言：

• PostgreSQL → 使用 UUID、TIMESTAMPTZ、RLS、JSONB 等特性
• MySQL → 使用 InnoDB、utf8mb4、TIMESTAMP 等特性
• SQLite → 使用 INTEGER PRIMARY KEY、TEXT 等简化类型
• 其他 → 与用户确认后选择最接近的方言

Step 2: 提取数据实体

从 API YAML 中提取所有需要持久化的数据实体：

1. 扫描所有端点的 requestBody 和 responses，识别核心数据对象
2. 区分"需要持久化"与"仅传输用"的数据：
   • 有 CRUD 操作的对象 → 需要建表（如 users、projects）
   • 只出现在请求/响应中但不直接存储的 → 不建表（如 loginRequest）
3. 为每个对象标注来源 API 端点

输出实体清单供用户确认：

从 API 规格中识别到 N 个需要持久化的数据实体：

| # | 实体 | 来源端点 | 核心字段 |
|---|------|---------|---------|
| 1 | users | auth.yaml → register, login | email, password, status |
| 2 | projects | projects.yaml → create, list, get | name, description, owner_id |
| 3 | subscriptions | billing.yaml → subscribe | plan, status, expires_at |

Step 3: 设计表结构

为每个实体设计完整的表结构，遵循当前数据库方言：

每张表必须包含：

• 主键（UUID 或自增 ID，视方言决定）
• 业务字段（从 API schema 映射，类型转换为数据库类型）
• 审计字段：created_at、updated_at
• 软删除字段：deleted_at（按需）
• 字段约束：NOT NULL、UNIQUE、CHECK、DEFAULT

类型映射原则：

• API string + format: email → TEXT NOT NULL（配合 CHECK 约束或应用层校验）
• API string + format: uuid → UUID（PostgreSQL）/ CHAR(36)（MySQL）
• API integer → INTEGER / BIGINT
• API boolean → BOOLEAN（PostgreSQL）/ TINYINT(1)（MySQL）
• API string + enum → TEXT + CHECK 约束（列出枚举值）
• 金额字段 → INTEGER（存分值），禁止 DECIMAL/FLOAT