@miniidealab/openlogos 0.2.0 → 0.3.1

package/skills/code-reviewer/SKILL.md

@@ -0,0 +1,204 @@
+# Skill: Code Reviewer
+
+> 审查 AI 生成的代码，基于 OpenLogos 全链路规格（API YAML、时序图 EX 用例、DB DDL）进行系统性校验，确保代码与设计文档完全一致，覆盖所有异常路径，满足安全要求。
+
+## 触发条件
+
+- 用户要求审查代码或 Code Review
+- 用户提到 "Phase 3 Step 4"、"代码审核"、"代码审查"
+- AI 刚生成了一段代码，需要验证其质量
+- 部署前的最终检查
+- 编排测试失败后需要定位代码问题
+
+## 前置依赖
+
+- `logos/resources/api/` 中包含 API YAML 规格
+- `logos/resources/prd/3-technical-plan/2-scenario-implementation/` 中包含场景时序图（含 EX 用例）
+- `logos/resources/database/` 中包含 DB DDL
+- 待审查的代码已可读取
+
+无 API 的项目（纯 CLI / 库）可省略 API 一致性检查，聚焦时序图覆盖和异常处理。
+
+## 核心能力
+
+1. 校验代码实现与 API YAML 规格的一致性
+2. 检查异常处理是否覆盖所有 EX 用例
+3. 检查 DB 操作是否符合 DDL 设计
+4. 检查安全策略（认证、RLS、输入校验）
+5. 检查代码风格和最佳实践
+6. 输出结构化的审查报告
+
+## 执行步骤
+
+### Step 1: 加载规格上下文
+
+读取以下文件，建立代码审查的"参照基准"：
+
+- **API YAML**（`logos/resources/api/*.yaml`）：提取端点清单，记录每个端点的路径、方法、请求体 schema、响应 schema、状态码
+- **场景时序图**（`logos/resources/prd/3-technical-plan/2-scenario-implementation/`）：提取所有 EX 异常用例编号和预期行为
+- **DB DDL**（`logos/resources/database/`）：提取表结构、字段类型、约束、索引
+- **`logos-project.yaml`**：读取 `tech_stack` 确认技术栈，`external_dependencies` 确认外部依赖
+
+汇总为审查检查清单：
+
+```markdown
+审查范围：S01 相关代码
+- API 端点：4 个（auth.yaml）
+- EX 异常用例：7 个（EX-2.1 ~ EX-5.2）
+- DB 表：2 张（users, profiles）
+- 安全策略：RLS 2 条
+```
+
+### Step 2: API 一致性审查
+
+逐个端点对比代码实现与 API YAML 规格：
+
+**检查项**：
+
+| 检查项 | 说明 | 严重程度 |
+|--------|------|---------|
+| 路径匹配 | 代码中的路由路径是否与 YAML 中的 `paths` 完全一致 | Critical |
+| HTTP 方法 | GET/POST/PUT/DELETE 是否匹配 | Critical |
+| 请求体字段 | 代码是否读取了 YAML 中 `requestBody.schema` 定义的所有 required 字段 | Critical |
+| 请求体校验 | 字段类型、format（email/uuid）、minLength 等约束是否在代码中有校验 | Warning |
+| 响应字段 | 代码返回的 JSON 字段名和类型是否与 YAML 中 `responses.schema` 一致 | Critical |
+| 状态码 | 正常和异常情况下返回的 HTTP 状态码是否与 YAML 定义一致 | Critical |
+| 错误响应格式 | 错误响应是否遵循 `{ code, message, details? }` 统一格式 | Warning |
+
+**输出格式**：
+
+```markdown
+### API 一致性
+
+| 端点 | 检查项 | 状态 | 说明 |
+|------|--------|------|------|
+| POST /api/auth/register | 请求体字段 | ✅ | email, password 均已读取 |
+| POST /api/auth/register | 响应状态码 | ❌ Critical | 注册成功返回 200，YAML 定义为 201 |
+| POST /api/auth/register | 错误码 | ❌ Warning | 邮箱重复返回通用 400，YAML 定义为 409 |
+```
+
+### Step 3: 异常处理覆盖审查
+
+将时序图中的所有 EX 异常用例与代码中的错误处理逐一对应：
+
+1. 列出该场景所有 EX 编号及其预期行为
+2. 在代码中查找对应的 try/catch、if/else、error handler
+3. 标注未覆盖的 EX 用例
+
+**检查重点**：
+
+- 每个 EX 用例是否有对应的代码分支
+- 异常情况下是否返回了正确的 HTTP 状态码和错误码
+- 是否有"静默吞掉异常"的情况（catch 块为空或只打日志不返回错误）
+- 外部服务调用（DB、第三方 API）是否都有超时和错误处理
+- 是否存在时序图中没有但代码中多出的异常处理（可能意味着时序图遗漏）
+
+**输出格式**：
+
+```markdown
+### 异常处理覆盖
+
+| EX 编号 | 异常描述 | 代码覆盖 | 说明 |
+|---------|---------|---------|------|
+| EX-2.1 | 邮箱已注册 | ✅ | 返回 409，格式正确 |
+| EX-2.2 | Auth 服务不可用 | ❌ Critical | 无 try/catch 包裹 supabase.auth.signUp 调用 |
+| EX-4.1 | profiles 写入失败 | ❌ Critical | INSERT 失败后未回滚 auth.users 记录 |
+```
+
+### Step 4: DB 操作审查
+
+检查代码中的数据库操作是否符合 DDL 设计：
+
+**检查项**：
+
+- **表名和列名**：代码中引用的表名/列名是否与 DDL 一致（无拼写错误、大小写差异）
+- **字段类型**：代码中传入的值类型是否与 DDL 定义匹配（如 DDL 中 `INTEGER` 的金额字段，代码是否传入分值而非元）
+- **约束遵守**：NOT NULL 字段是否确保有值、UNIQUE 字段是否做了冲突处理、CHECK 约束中的枚举值是否在代码中有对应常量
+- **事务使用**：涉及多表写入的操作是否包裹在事务中
+- **迁移一致**：DDL 中的最新字段是否在代码中已使用（避免 DDL 更新了但代码忘记跟进）
+
+### Step 5: 安全审查
+
+检查代码的安全实现：
+
+| 检查项 | 说明 | 严重程度 |
+|--------|------|---------|
+| 认证检查 | 需认证的端点是否在处理逻辑前验证了 token/session | Critical |
+| 授权检查 | 用户是否只能访问自己的数据（owner check） | Critical |
+| 输入校验 | 用户输入是否做了类型校验和长度限制（防注入、防 XSS） | Critical |
+| 敏感数据 | 响应中是否泄露了密码哈希、内部 ID、堆栈信息 | Critical |
+| RLS 依赖 | 如果依赖 PostgreSQL RLS，代码是否正确设置了 `auth.uid()` 上下文 | Warning |
+| SQL 注入 | 是否使用参数化查询（禁止字符串拼接 SQL） | Critical |
+| 速率限制 | 关键端点（登录、注册）是否有防暴力破解的速率限制 | Warning |
+
+### Step 6: 输出审查报告
+
+按严重程度汇总所有发现，生成结构化报告：
+
+```markdown
+# 代码审查报告：S01 用户注册
+
+## 审查范围
+- 场景：S01
+- 端点：4 个
+- EX 用例：7 个
+- 代码文件：src/api/auth/register.ts, src/api/auth/login.ts
+
+## 审查摘要
+
+| 严重程度 | 数量 |
+|---------|------|
+| 🔴 Critical | 2 |
+| 🟡 Warning | 3 |
+| 🔵 Info | 1 |
+
+## Critical 发现
+
+### [C1] POST /api/auth/register 状态码不匹配
+- **规格来源**：auth.yaml → register → responses.201
+- **问题**：代码返回 200，规格定义为 201
+- **修复建议**：将 `res.status(200)` 改为 `res.status(201)`
+
+### [C2] EX-2.2 未处理：Auth 服务不可用
+- **规格来源**：S01 时序图 → EX-2.2
+- **问题**：`supabase.auth.signUp()` 调用未包裹 try/catch
+- **修复建议**：添加 try/catch，超时或 5xx 时返回 503
+
+## Warning 发现
+...
+
+## Info 发现
+...
+```
+
+**报告原则**：
+- Critical 必须修复后才能进入编排验收
+- Warning 建议修复，但不阻塞交付
+- Info 为改进建议，可后续处理
+- 每条发现都必须引用规格来源（API YAML、EX 编号、DDL）
+
+## 输出规范
+
+- 审查报告直接输出到对话中（不写文件）
+- 按严重程度分类：Critical / Warning / Info
+- 每条发现格式：编号 + 规格来源 + 问题描述 + 修复建议
+- 末尾给出总结和下一步建议（如"修复 2 个 Critical 后可运行编排验收"）
+
+## 实践经验
+
+- **一致性优先**：代码必须与 API YAML 完全一致——字段名、类型、状态码都不能偏差。大部分线上 Bug 来自代码和规格的微妙不一致
+- **异常处理是重点**：大部分 Bug 都出在异常路径上，仔细检查每个 EX 用例是否有对应的 catch/error handler
+- **安全不打折**：认证检查、RLS 策略、输入校验，任何一项缺失都是 Critical
+- **不要过度审查**：代码风格问题标记为 Info，不阻塞交付。审查的核心目标是"代码与规格一致"，不是"代码完美"
+- **审查前先跑一遍**：如果代码能跑起来，先运行一次编排测试，用失败的 case 反向定位问题，比逐行看代码高效
+- **关注补偿逻辑**：多步写入（如先创建 auth user 再写 profile）如果中途失败，是否有回滚或补偿机制——这是最容易遗漏的 Critical 问题
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我做代码审查`
+- `帮我检查这段代码是否符合 API YAML 规格`
+- `Review 一下 S01 相关的代码实现`
+- `帮我检查异常处理是否完整`
+- `帮我检查安全策略是否到位`

package/skills/db-designer/SKILL.en.md

@@ -0,0 +1,212 @@
+# Skill: DB Designer
+
+> Derive database table structures from API specifications and generate SQL DDL in the appropriate dialect. The database type is determined during Phase 3 Step 0 technology selection, ensuring that field types, constraints, indexes, and security policies are fully aligned with API endpoints.
+
+## Trigger Conditions
+
+- User requests database design or SQL writing
+- User mentions "Phase 3 Step 2", "DB design", "table structure"
+- API YAML specifications already exist and database design needs to be derived
+- User provides a data model that needs to be converted to DDL
+
+## Core Capabilities
+
+1. Derive table structures from API request/response structures
+2. Read `tech_stack.database` from `logos-project.yaml` to determine the database type
+3. Generate SQL DDL in the corresponding database dialect
+4. Design indexes with rationale for each
+5. Design security policies (RLS / application-level permissions)
+6. Add comments to every table and every field
+
+## Prerequisites
+
+- `logos/resources/api/` contains API YAML specifications (output from api-designer)
+- `tech_stack.database` in `logos-project.yaml` is filled in
+
+If the API directory is empty, prompt the user to complete the API design (api-designer) in Phase 3 Step 2 first. If `tech_stack.database` is not filled in, prompt the user to complete Phase 3 Step 0 (architecture-designer) first.
+
+## Execution Steps
+
+### Step 1: Determine Database Type
+
+Read the `tech_stack` field from `logos/logos-project.yaml` to determine the database type and dialect:
+
+- PostgreSQL → Use features like UUID, TIMESTAMPTZ, RLS, JSONB, etc.
+- MySQL → Use features like InnoDB, utf8mb4, TIMESTAMP, etc.
+- SQLite → Use simplified types like INTEGER PRIMARY KEY, TEXT, etc.
+- Other → Confirm with the user and select the closest dialect
+
+### Step 2: Extract Data Entities
+
+Extract all data entities that need to be persisted from the API YAML:
+
+1. Scan `requestBody` and `responses` across all endpoints to identify core data objects
+2. Distinguish between "needs persistence" and "transfer-only" data:
+   - Objects with CRUD operations → need a table (e.g., `users`, `projects`)
+   - Objects that only appear in requests/responses but are not stored directly → no table needed (e.g., `loginRequest`)
+3. Annotate each object with its source API endpoint
+
+Output an entity checklist for user confirmation:
+
+```markdown
+Identified N data entities requiring persistence from API specifications:
+
+| # | Entity | Source Endpoint | Core Fields |
+|---|--------|----------------|-------------|
+| 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: Design Table Structures
+
+Design complete table structures for each entity, following the current database dialect:
+
+**Every table must include**:
+- Primary key (UUID or auto-increment ID, depending on dialect)
+- Business fields (mapped from API schema, with types converted to database types)
+- Audit fields: `created_at`, `updated_at`
+- Soft delete field: `deleted_at` (as needed)
+- Field constraints: `NOT NULL`, `UNIQUE`, `CHECK`, `DEFAULT`
+
+**Type mapping principles**:
+- API `string + format: email` → `TEXT NOT NULL` (with CHECK constraint or application-level validation)
+- 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` constraint (listing enum values)
+- Monetary fields → `INTEGER` (store in cents), **DECIMAL/FLOAT is prohibited**
+
+**Example (PostgreSQL)**:
+
+```sql
+-- Users table (source: auth.yaml → register, login)
+CREATE TABLE users (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email       TEXT NOT NULL UNIQUE,
+  password    TEXT NOT NULL,
+  status      TEXT NOT NULL DEFAULT 'pending'
+                CHECK (status IN ('pending', 'active', 'disabled')),
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+### Step 4: Design Table Relationships
+
+Design foreign keys based on entity relationships in the API:
+
+1. Derive relationships from nested paths and reference fields in API endpoints (e.g., `/api/projects/:projectId/members` → `project_members` table linking `projects` and `users`)
+2. Determine relationship types (one-to-many, many-to-many)
+3. Design foreign key constraints and cascade strategies:
+   - `ON DELETE CASCADE`: child records are deleted when the parent record is deleted (e.g., user deleted → projects deleted)
+   - `ON DELETE SET NULL`: child records are retained but the foreign key is set to null when the parent is deleted
+   - `ON DELETE RESTRICT`: prevent deletion of the parent record if child records exist
+
+### Step 5: Design Security Policies
+
+Design corresponding security mechanisms based on the database type:
+
+**PostgreSQL — Row-Level Security (RLS)**:
+
+```sql
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY projects_owner_policy ON projects
+  USING (owner_id = auth.uid());
+```
+
+- Enable RLS on all tables containing user data
+- Design at least one Policy per table (owner / admin / public)
+- Document the correspondence between RLS policies and the API authentication scheme
+
+**MySQL — Application-Level Permissions**:
+
+- Annotate data access permissions in table comments (owner-only / admin / public)
+- Do not implement permission control in DDL; delegate to the application layer
+
+### Step 6: Design Indexes
+
+Design indexes for common query patterns, with a rationale for each index:
+
+```sql
+-- User lookup by email (login scenario, source: S02)
+CREATE UNIQUE INDEX idx_users_email ON users(email);
+
+-- Project lookup by owner (project list, source: S04 Step 1)
+CREATE INDEX idx_projects_owner ON projects(owner_id);
+```
+
+Index design principles:
+- Foreign key columns: indexes are mandatory (to avoid full table scans on JOINs)
+- Unique constraint columns: unique indexes are created automatically
+- High-frequency query columns: determine based on API query parameters
+- Composite indexes: consider for multi-condition queries (leftmost prefix rule)
+- Avoid over-indexing: limit index count on write-heavy tables
+
+### Step 7: Output Complete DDL
+
+Organize the DDL file in the following order:
+
+1. File header comment (source, database type, generation timestamp)
+2. Base tables (tables without foreign key dependencies first)
+3. Association tables (tables with foreign key dependencies after)
+4. Indexes
+5. Security policies (RLS / Policy)
+6. Table and field comments (PostgreSQL uses `COMMENT ON`)
+
+Add a comment above each DDL block noting the source API endpoint.
+
+## Output Specification
+
+- File format: SQL (dialect determined by `tech_stack.database`)
+- Storage location: `logos/resources/database/`
+- Single file output: `schema.sql` (simple projects); or split by domain: `auth.sql`, `billing.sql` (complex projects)
+- Every table must have a comment (PostgreSQL: `COMMENT ON TABLE`; MySQL: `COMMENT = '...'`)
+- Every field must have a comment (PostgreSQL: `COMMENT ON COLUMN`; MySQL: `COMMENT '...'` after field definition)
+- Add a SQL comment above each DDL block noting the source API endpoint
+
+## Database Dialect Quick Reference
+
+| Feature | PostgreSQL | MySQL |
+|---------|-----------|-------|
+| UUID Primary Key | `UUID DEFAULT gen_random_uuid()` | `CHAR(36) DEFAULT (UUID())` or use `BINARY(16)` |
+| Timestamp Type | `TIMESTAMPTZ` | `DATETIME` / `TIMESTAMP` (mind timezone handling) |
+| JSON Support | `JSONB` (indexable) | `JSON` (limited functionality) |
+| Row-Level Security | RLS (`ENABLE ROW LEVEL SECURITY`) | Not supported; must be implemented at the application layer |
+| Table Comment | `COMMENT ON TABLE t IS '...'` | `CREATE TABLE t (...) COMMENT = '...'` |
+| Column Comment | `COMMENT ON COLUMN t.c IS '...'` | `col_name TYPE COMMENT '...'` |
+
+## Best Practices
+
+### General (All Databases)
+
+- **Store monetary values as INTEGER in cents**: DECIMAL/FLOAT is prohibited to avoid floating-point precision issues
+- **Soft delete**: prefer a `deleted_at` timestamp field over physical deletion
+- **Audit fields**: every table should include `created_at` and `updated_at`
+- **Timestamp fields with timezone**: avoid timezone pitfalls
+- **Field names aligned with API**: DB column names should match API YAML field names as closely as possible (e.g., API uses `userId` → DB uses `user_id`; as long as the mapping rule is clear), reducing unnecessary transformations in the code layer
+- **Core tables first, auxiliary tables later**: don't try to design all tables at once — output core business tables for user review first, then add auxiliary tables
+
+### PostgreSQL-Specific
+
+- **Primary key**: `id UUID DEFAULT gen_random_uuid() PRIMARY KEY`
+- **Timestamp type**: use `TIMESTAMPTZ`
+- **RLS**: enable on all tables with `ALTER TABLE ... ENABLE ROW LEVEL SECURITY;`
+- **JSONB**: prefer JSONB for unstructured storage and create GIN indexes
+
+### MySQL-Specific
+
+- **Primary key**: `id CHAR(36) DEFAULT (UUID()) PRIMARY KEY` or auto-increment BIGINT
+- **Timestamp type**: use `TIMESTAMP` (automatic timezone conversion) or `DATETIME` (stored as-is)
+- **Character set**: specify `CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci` when creating tables
+- **Engine**: always use `ENGINE=InnoDB`
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with AI:
+
+- `Help me design the database`
+- `Derive database DDL from the API specifications`
+- `Help me design the database tables involved in S01`
+- `Help me add indexes and RLS policies to the existing table structures`

package/skills/db-designer/SKILL.md

@@ -0,0 +1,212 @@
+# 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 端点
+
+输出实体清单供用户确认：
+
+```markdown
+从 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**
+
+**示例（PostgreSQL）**：
+
+```sql
+-- 用户表（来源：auth.yaml → register, login）
+CREATE TABLE users (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email       TEXT NOT NULL UNIQUE,
+  password    TEXT NOT NULL,
+  status      TEXT NOT NULL DEFAULT 'pending'
+                CHECK (status IN ('pending', 'active', 'disabled')),
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+### Step 4: 设计表间关联
+
+根据 API 中的实体关系设计外键：
+
+1. 从 API 端点的嵌套路径和引用字段推导关联（如 `/api/projects/:projectId/members` → `project_members` 表关联 `projects` 和 `users`）
+2. 确定关联类型（一对多、多对多）
+3. 设计外键约束和级联策略：
+   - `ON DELETE CASCADE`：父记录删除时子记录跟随删除（如用户删除 → 项目删除）
+   - `ON DELETE SET NULL`：父记录删除时子记录保留但外键置空
+   - `ON DELETE RESTRICT`：父记录有子记录时禁止删除
+
+### Step 5: 设计安全策略
+
+根据数据库类型设计对应的安全机制：
+
+**PostgreSQL — 行级安全（RLS）**：
+
+```sql
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY projects_owner_policy ON projects
+  USING (owner_id = auth.uid());
+```
+
+- 所有包含用户数据的表启用 RLS
+- 为每张表设计至少一条 Policy（owner / admin / public）
+- 注明 RLS 策略与 API 认证方案的对应关系
+
+**MySQL — 应用层权限**：
+
+- 在表注释中标注数据访问权限（owner-only / admin / public）
+- 不在 DDL 中实现权限控制，交由应用层处理
+
+### Step 6: 设计索引
+
+为常见查询模式设计索引，每个索引附设计理由：
+
+```sql
+-- 用户按邮箱查找（登录场景，来源 S02）
+CREATE UNIQUE INDEX idx_users_email ON users(email);
+
+-- 项目按 owner 查找（项目列表，来源 S04 Step 1）
+CREATE INDEX idx_projects_owner ON projects(owner_id);
+```
+
+索引设计原则：
+- 外键列：必须建索引（避免 JOIN 全表扫描）
+- 唯一约束列：自动创建唯一索引
+- 高频查询列：根据 API 的查询参数判断
+- 复合索引：多条件查询时考虑（最左前缀原则）
+- 不过度索引：写多读少的表控制索引数量
+
+### Step 7: 输出完整 DDL
+
+按以下顺序组织 DDL 文件：
+
+1. 文件头注释（来源、数据库类型、生成时间）
+2. 基础表（无外键依赖的表先建）
+3. 关联表（有外键依赖的表后建）
+4. 索引
+5. 安全策略（RLS / Policy）
+6. 表和字段注释（PostgreSQL 使用 `COMMENT ON`）
+
+每段 DDL 上方用注释标注来源 API 端点。
+
+## 输出规范
+
+- 文件格式：SQL（方言由 `tech_stack.database` 决定）
+- 存放位置：`logos/resources/database/`
+- 单文件输出：`schema.sql`（简单项目）；或按领域分文件：`auth.sql`、`billing.sql`（复杂项目）
+- 每张表必须有注释（PostgreSQL: `COMMENT ON TABLE`；MySQL: `COMMENT = '...'`）
+- 每个字段必须有注释（PostgreSQL: `COMMENT ON COLUMN`；MySQL: 字段定义后 `COMMENT '...'`）
+- 每段 DDL 上方用 SQL 注释标注来源 API 端点
+
+## 数据库方言差异速查
+
+| 特性 | PostgreSQL | MySQL |
+|------|-----------|-------|
+| UUID 主键 | `UUID DEFAULT gen_random_uuid()` | `CHAR(36) DEFAULT (UUID())` 或使用 `BINARY(16)` |
+| 时间类型 | `TIMESTAMPTZ` | `DATETIME` / `TIMESTAMP`（注意时区处理） |
+| JSON 支持 | `JSONB`（可索引） | `JSON`（功能受限） |
+| 行级安全 | RLS (`ENABLE ROW LEVEL SECURITY`) | 不支持，需在应用层实现 |
+| 表注释 | `COMMENT ON TABLE t IS '...'` | `CREATE TABLE t (...) COMMENT = '...'` |
+| 字段注释 | `COMMENT ON COLUMN t.c IS '...'` | `col_name TYPE COMMENT '...'` |
+
+## 实践经验
+
+### 通用（所有数据库）
+
+- **金额一律 INTEGER 存分值**：禁止 DECIMAL/FLOAT，避免浮点精度问题
+- **软删除**：优先使用 `deleted_at` 时间字段而非物理删除
+- **审计字段**：每张表包含 `created_at` 和 `updated_at`
+- **时间字段带时区**：避免时区陷阱
+- **字段名与 API 一致**：DB 列名尽量与 API YAML 中的字段名对齐（如 API 用 `userId` → DB 用 `user_id`，映射规则明确即可），减少代码层的无谓转换
+- **先出核心表再补辅助表**：不要试图一次设计所有表——先输出核心业务表让用户 review，再补充辅助表
+
+### PostgreSQL 特有
+
+- **主键**：`id UUID DEFAULT gen_random_uuid() PRIMARY KEY`
+- **时间类型**：使用 `TIMESTAMPTZ`
+- **RLS**：所有表启用 `ALTER TABLE ... ENABLE ROW LEVEL SECURITY;`
+- **JSONB**：需要非结构化存储时优先使用 JSONB 并建 GIN 索引
+
+### MySQL 特有
+
+- **主键**：`id CHAR(36) DEFAULT (UUID()) PRIMARY KEY` 或自增 BIGINT
+- **时间类型**：使用 `TIMESTAMP`（自动时区转换）或 `DATETIME`（原样存储）
+- **字符集**：建表时指定 `CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`
+- **引擎**：一律使用 `ENGINE=InnoDB`
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我设计数据库`
+- `基于 API 规格帮我推导数据库 DDL`
+- `帮我设计 S01 涉及的数据库表`
+- `帮我给现有表结构补充索引和 RLS 策略`