[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6MFYNJWC75525V5WM4P2T6P":3,"skill-same:01M6MFYNJWC75525V5WM4P2T6P":68},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":33,"publishedAt":39,"linkOnly":40,"markdownContent":41,"markdownBody":42,"frontMatter":43,"refName":44,"commitSha":45,"skillDirectory":46,"forksCount":47,"repositoryHtmlUrl":48,"repositoryHomepageUrl":49,"ownerHtmlUrl":50,"ownerBlogUrl":51,"ownerDescription":52,"updatedAt":53,"install":54,"resources":67},"01M6MFYNJWC75525V5WM4P2T6P","data-api-design",null,"hashgraph-online\u002Fawesome-codex-plugins","hashgraph-online","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F160371962?v=4","01M6CNB6NRJVNNGN14TR01Q6D3","HOL (Hashgraph Online)","01M6JT1HSKKG9V68KQAQGBA7XP",1575,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FechoVic\u002Fboss-skill\u002Fskill\u002Fskills\u002Farchitect\u002Fdata-api-design\u002FSKILL.md",[17,22,25,30],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":26,"categoryName":27,"taxonomyType":28,"taxonomyTypeDesc":29},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",{"categoryNo":31,"categoryName":32,"taxonomyType":28,"taxonomyTypeDesc":29},"01JBSEEDCAT000000000000033","数据分析师",[34,35,36,37,38],"design","api design","data","api","data api design","2026-11-10 10:12:30",false,"---\n\nname: architect\u002Fdata-api-design\ndescription: 数据模型和API设计方法论，包含ERD设计、数据字典、RESTful API规范\nversion: 1.0.0\nagent: architect\ntype: methodology\nuser-invocable: false\nagent-invocable: true\ndependencies: []\ntriggers:\n- 架构设计完成后\n- 需要设计数据模型时\n- 需要定义API接口时\n  metadata:\n  internal: true\n\n---\n\n# 数据模型与API设计方法论\n\n## 适用场景\n\n在系统架构确定后，需要设计：\n- 数据库表结构和关系\n- 数据字典和约束\n- API接口规范\n- 请求\u002F响应格式\n\n## 数据模型设计\n\n### 1. 实体识别\n\n从PRD中识别核心实体（名词）：\n\n**示例**：\n- 用户系统：User（用户）、Role（角色）、Permission（权限）\n- 博客系统：User（用户）、Post（文章）、Comment（评论）、Tag（标签）\n- 电商系统：User（用户）、Product（商品）、Order（订单）、OrderItem（订单项）\n\n### 2. 关系识别\n\n确定实体之间的关系：\n\n| 关系类型         | 说明           | 示例           |\n| ---------------- | -------------- | -------------- |\n| **一对一 (1:1)** | 一个A对应一个B | User - Profile |\n| **一对多 (1:N)** | 一个A对应多个B | User - Post    |\n| **多对多 (M:N)** | 多个A对应多个B | Post - Tag     |\n\n**关系表示**：\n- `||--o{`: 一对多\n- `||--||`: 一对一\n- `}o--o{`: 多对多\n\n### 3. 实体关系图 (ERD)\n\n使用 Mermaid 绘制 ERD：\n\n```mermaid\nerDiagram\n    User ||--o{ Post : creates\n    User ||--o{ Comment : writes\n    Post ||--o{ Comment : has\n    Post }o--o{ Tag : has\n\n    User {\n        uuid id PK\n        string email UK\n        string name\n        string passwordHash\n        enum role\n        datetime createdAt\n        datetime updatedAt\n    }\n\n    Post {\n        uuid id PK\n        uuid authorId FK\n        string title\n        text content\n        enum status\n        datetime publishedAt\n        datetime createdAt\n        datetime updatedAt\n    }\n\n    Comment {\n        uuid id PK\n        uuid postId FK\n        uuid userId FK\n        text content\n        datetime createdAt\n    }\n\n    Tag {\n        uuid id PK\n        string name UK\n    }\n```\n\n### 4. 数据字典\n\n为每个表定义详细的字段信息：\n\n#### User 表\n\n| 字段         | 类型                  | 约束             | 默认值             | 说明               |\n| ------------ | --------------------- | ---------------- | ------------------ | ------------------ |\n| id           | UUID                  | PK               | uuid_generate_v4() | 主键               |\n| email        | VARCHAR(255)          | UNIQUE, NOT NULL | -                  | 邮箱，用于登录     |\n| name         | VARCHAR(100)          | NOT NULL         | -                  | 用户名             |\n| passwordHash | VARCHAR(255)          | NOT NULL         | -                  | 密码哈希（bcrypt） |\n| role         | ENUM('user', 'admin') | NOT NULL         | 'user'             | 用户角色           |\n| createdAt    | TIMESTAMP             | NOT NULL         | NOW()              | 创建时间           |\n| updatedAt    | TIMESTAMP             | NOT NULL         | NOW()              | 更新时间           |\n\n**索引**：\n- `idx_user_email`: email（唯一索引，用于登录查询）\n- `idx_user_role`: role（用于角色筛选）\n\n#### Post 表\n\n| 字段        | 类型                                   | 约束         | 默认值             | 说明                    |\n| ----------- | -------------------------------------- | ------------ | ------------------ | ----------------------- |\n| id          | UUID                                   | PK           | uuid_generate_v4() | 主键                    |\n| authorId    | UUID                                   | FK, NOT NULL | -                  | 作者ID，外键关联User.id |\n| title       | VARCHAR(200)                           | NOT NULL     | -                  | 文章标题                |\n| content     | TEXT                                   | NOT NULL     | -                  | 文章内容                |\n| status      | ENUM('draft', 'published', 'archived') | NOT NULL     | 'draft'            | 文章状态                |\n| publishedAt | TIMESTAMP                              | NULL         | -                  | 发布时间                |\n| createdAt   | TIMESTAMP                              | NOT NULL     | NOW()              | 创建时间                |\n| updatedAt   | TIMESTAMP                              | NOT NULL     | NOW()              | 更新时间                |\n\n**索引**：\n- `idx_post_author`: authorId（用于查询用户的文章）\n- `idx_post_status`: status（用于筛选状态）\n- `idx_post_published`: publishedAt（用于按发布时间排序）\n\n### 5. 数据类型选择\n\n| 数据类型     | 使用场景   | PostgreSQL      | MySQL                    | MongoDB  |\n| ------------ | ---------- | --------------- | ------------------------ | -------- |\n| **主键**     | 唯一标识   | UUID, SERIAL    | INT AUTO_INCREMENT, UUID | ObjectId |\n| **字符串**   | 短文本     | VARCHAR(n)      | VARCHAR(n)               | String   |\n| **长文本**   | 文章内容   | TEXT            | TEXT                     | String   |\n| **整数**     | 数量、年龄 | INTEGER, BIGINT | INT, BIGINT              | Number   |\n| **小数**     | 价格、评分 | DECIMAL(p,s)    | DECIMAL(p,s)             | Number   |\n| **布尔**     | 是否标志   | BOOLEAN         | TINYINT(1)               | Boolean  |\n| **日期时间** | 时间戳     | TIMESTAMP       | DATETIME                 | Date     |\n| **枚举**     | 固定选项   | ENUM            | ENUM                     | String   |\n| **JSON**     | 灵活数据   | JSONB           | JSON                     | Object   |\n\n**推荐**：\n- **主键**：使用 UUID 而非自增ID（避免暴露数据量、分布式友好）\n- **时间戳**：使用 TIMESTAMP WITH TIME ZONE（时区友好）\n- **枚举**：使用 ENUM 而非字符串（类型安全、节省空间）\n- **JSON**：PostgreSQL 使用 JSONB（支持索引和查询）\n\n## API设计\n\n### 1. API规范选择\n\n| 规范        | 适用场景           | 优点               | 缺点               |\n| ----------- | ------------------ | ------------------ | ------------------ |\n| **RESTful** | 通用场景、CRUD操作 | 简单、标准、易理解 | 过度获取、多次请求 |\n| **GraphQL** | 复杂查询、多端适配 | 按需获取、类型安全 | 学习曲线、缓存复杂 |\n| **gRPC**    | 微服务、高性能     | 性能高、类型安全   | 浏览器支持差       |\n\n**本项目推荐**：RESTful（除非有特殊需求）\n\n### 2. RESTful API设计原则\n\n#### 资源命名\n\n- **使用名词**：`\u002Fusers`, `\u002Fposts`, `\u002Fcomments`（不是 `\u002FgetUsers`, `\u002FcreatePost`）\n- **使用复数**：`\u002Fusers`（不是 `\u002Fuser`）\n- **使用小写**：`\u002Fusers`（不是 `\u002FUsers`）\n- **使用连字符**：`\u002Forder-items`（不是 `\u002ForderItems` 或 `\u002Forder_items`）\n\n#### HTTP方法\n\n| 方法   | 用途     | 示例                | 幂等性 |\n| ------ | -------- | ------------------- | ------ |\n| GET    | 获取资源 | `GET \u002Fusers`        | 是     |\n| POST   | 创建资源 | `POST \u002Fusers`       | 否     |\n| PUT    | 完整更新 | `PUT \u002Fusers\u002F123`    | 是     |\n| PATCH  | 部分更新 | `PATCH \u002Fusers\u002F123`  | 否     |\n| DELETE | 删除资源 | `DELETE \u002Fusers\u002F123` | 是     |\n\n#### URL设计\n\n| 操作     | 方法   | URL                 | 说明                 |\n| -------- | ------ | ------------------- | -------------------- |\n| 获取列表 | GET    | `\u002Fapi\u002Fv1\u002Fusers`     | 支持分页、筛选、排序 |\n| 获取详情 | GET    | `\u002Fapi\u002Fv1\u002Fusers\u002F:id` | 返回单个资源         |\n| 创建     | POST   | `\u002Fapi\u002Fv1\u002Fusers`     | 请求体包含资源数据   |\n| 完整更新 | PUT    | `\u002Fapi\u002Fv1\u002Fusers\u002F:id` | 替换整个资源         |\n| 部分更新 | PATCH  | `\u002Fapi\u002Fv1\u002Fusers\u002F:id` | 只更新指定字段       |\n| 删除     | DELETE | `\u002Fapi\u002Fv1\u002Fusers\u002F:id` | 删除资源             |\n\n**嵌套资源**：\n- `GET \u002Fapi\u002Fv1\u002Fusers\u002F:userId\u002Fposts` - 获取用户的文章\n- `POST \u002Fapi\u002Fv1\u002Fposts\u002F:postId\u002Fcomments` - 为文章创建评论\n\n**查询参数**：\n- 分页：`?page=1&limit=20`\n- 筛选：`?status=published&author=123`\n- 排序：`?sort=-createdAt`（-表示降序）\n- 搜索：`?q=keyword`\n\n### 3. 请求\u002F响应格式\n\n#### 成功响应\n\n**单个资源**：\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"123\",\n    \"name\": \"John Doe\",\n    \"email\": \"john@example.com\"\n  }\n}\n```\n\n**资源列表**：\n```json\n{\n  \"success\": true,\n  \"data\": [{ \"id\": \"1\", \"name\": \"Item 1\" }, { \"id\": \"2\", \"name\": \"Item 2\" }],\n  \"meta\": {\n    \"page\": 1,\n    \"limit\": 20,\n    \"total\": 100,\n    \"totalPages\": 5\n  }\n}\n```\n\n#### 错误响应\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"邮箱格式不正确\",\n    \"details\": [\n      {\n        \"field\": \"email\",\n        \"message\": \"必须是有效的邮箱地址\"\n      }\n    ]\n  }\n}\n```\n\n**错误码**：\n- `VALIDATION_ERROR`: 验证错误（400）\n- `UNAUTHORIZED`: 未认证（401）\n- `FORBIDDEN`: 无权限（403）\n- `NOT_FOUND`: 资源不存在（404）\n- `CONFLICT`: 资源冲突（409，如邮箱已存在）\n- `INTERNAL_ERROR`: 服务器错误（500）\n\n### 4. 认证和授权\n\n#### 认证方案\n\n**JWT (推荐)**：\n```\nAuthorization: Bearer \u003Ctoken>\n```\n\n**请求头**：\n```\nPOST \u002Fapi\u002Fv1\u002Fauth\u002Flogin\nContent-Type: application\u002Fjson\n\n{\n  \"email\": \"user@example.com\",\n  \"password\": \"password123\"\n}\n```\n\n**响应**：\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n    \"user\": {\n      \"id\": \"123\",\n      \"name\": \"John Doe\",\n      \"email\": \"john@example.com\"\n    }\n  }\n}\n```\n\n#### 授权模型\n\n**RBAC (基于角色)**：\n```typescript\nenum Role {\n  USER = 'user',\n  ADMIN = 'admin',\n}\n\n\u002F\u002F 中间件检查\nif (user.role !== Role.ADMIN) {\n  throw new ForbiddenError();\n}\n```\n\n### 5. API接口列表\n\n| 模块     | 方法   | 路径                  | 描述         | 认证 | 权限         |\n| -------- | ------ | --------------------- | ------------ | ---- | ------------ |\n| **认证** |        |                       |              |      |              |\n|          | POST   | \u002Fapi\u002Fv1\u002Fauth\u002Fregister | 用户注册     | 否   | -            |\n|          | POST   | \u002Fapi\u002Fv1\u002Fauth\u002Flogin    | 用户登录     | 否   | -            |\n|          | POST   | \u002Fapi\u002Fv1\u002Fauth\u002Flogout   | 用户登出     | 是   | -            |\n|          | GET    | \u002Fapi\u002Fv1\u002Fauth\u002Fme       | 获取当前用户 | 是   | -            |\n| **用户** |        |                       |              |      |              |\n|          | GET    | \u002Fapi\u002Fv1\u002Fusers         | 获取用户列表 | 是   | admin        |\n|          | GET    | \u002Fapi\u002Fv1\u002Fusers\u002F:id     | 获取用户详情 | 是   | -            |\n|          | PATCH  | \u002Fapi\u002Fv1\u002Fusers\u002F:id     | 更新用户信息 | 是   | self\u002Fadmin   |\n|          | DELETE | \u002Fapi\u002Fv1\u002Fusers\u002F:id     | 删除用户     | 是   | admin        |\n| **文章** |        |                       |              |      |              |\n|          | GET    | \u002Fapi\u002Fv1\u002Fposts         | 获取文章列表 | 否   | -            |\n|          | GET    | \u002Fapi\u002Fv1\u002Fposts\u002F:id     | 获取文章详情 | 否   | -            |\n|          | POST   | \u002Fapi\u002Fv1\u002Fposts         | 创建文章     | 是   | -            |\n|          | PATCH  | \u002Fapi\u002Fv1\u002Fposts\u002F:id     | 更新文章     | 是   | author\u002Fadmin |\n|          | DELETE | \u002Fapi\u002Fv1\u002Fposts\u002F:id     | 删除文章     | 是   | author\u002Fadmin |\n\n## 输出要求\n\n完成数据模型和API设计后，应输出以下内容（通常作为架构文档的第4-5章）：\n\n```markdown\n## 4. 数据模型\n\n### 4.1 实体关系图 (ERD)\n\n[Mermaid ERD]\n\n### 4.2 数据字典\n\n#### User 表\n\n[字段表格]\n\n#### Post 表\n\n[字段表格]\n\n---\n\n## 5. API 设计\n\n### 5.1 API 规范\n\n- **风格**：RESTful\n- **版本**：URL 前缀 `\u002Fapi\u002Fv1`\n- **认证**：Bearer Token (JWT)\n- **格式**：JSON\n\n### 5.2 接口列表\n\n[接口表格]\n\n### 5.3 响应格式\n\n[成功响应示例]\n[错误响应示例]\n```\n\n## 关键原则\n\n1. **规范化**：遵循数据库范式，避免冗余\n2. **类型安全**：使用强类型（UUID、ENUM）\n3. **RESTful**：遵循REST原则，资源导向\n4. **一致性**：命名、格式、错误码保持一致\n5. **文档化**：每个字段、每个接口都有清晰说明\n\n## 常见误区\n\n❌ **使用动词**：`\u002FgetUsers`, `\u002FcreatePost`（应该用HTTP方法表示动作）\n❌ **过度嵌套**：`\u002Fusers\u002F:id\u002Fposts\u002F:id\u002Fcomments\u002F:id`（最多2层）\n❌ **暴露实现**：`\u002Fapi\u002FgetUserFromDatabase`（暴露内部实现）\n❌ **不一致**：有的用复数有的用单数，有的驼峰有的下划线\n","# 数据模型与API设计方法论\n\n## 适用场景\n\n在系统架构确定后，需要设计：\n- 数据库表结构和关系\n- 数据字典和约束\n- API接口规范\n- 请求\u002F响应格式\n\n## 数据模型设计\n\n### 1. 实体识别\n\n从PRD中识别核心实体（名词）：\n\n**示例**：\n- 用户系统：User（用户）、Role（角色）、Permission（权限）\n- 博客系统：User（用户）、Post（文章）、Comment（评论）、Tag（标签）\n- 电商系统：User（用户）、Product（商品）、Order（订单）、OrderItem（订单项）\n\n### 2. 关系识别\n\n确定实体之间的关系：\n\n| 关系类型         | 说明           | 示例           |\n| ---------------- | -------------- | -------------- |\n| **一对一 (1:1)** | 一个A对应一个B | User - Profile |\n| **一对多 (1:N)** | 一个A对应多个B | User - Post    |\n| **多对多 (M:N)** | 多个A对应多个B | Post - Tag     |\n\n**关系表示**：\n- `||--o{`: 一对多\n- `||--||`: 一对一\n- `}o--o{`: 多对多\n\n### 3. 实体关系图 (ERD)\n\n使用 Mermaid 绘制 ERD：\n\n```mermaid\nerDiagram\n    User ||--o{ Post : creates\n    User ||--o{ Comment : writes\n    Post ||--o{ Comment : has\n    Post }o--o{ Tag : has\n\n    User {\n        uuid id PK\n        string email UK\n        string name\n        string passwordHash\n        enum role\n        datetime createdAt\n        datetime updatedAt\n    }\n\n    Post {\n        uuid id PK\n        uuid authorId FK\n        string title\n        text content\n        enum status\n        datetime publishedAt\n        datetime createdAt\n        datetime updatedAt\n    }\n\n    Comment {\n        uuid id PK\n        uuid postId FK\n        uuid userId FK\n        text content\n        datetime createdAt\n    }\n\n    Tag {\n        uuid id PK\n        string name UK\n    }\n```\n\n### 4. 数据字典\n\n为每个表定义详细的字段信息：\n\n#### User 表\n\n| 字段         | 类型                  | 约束             | 默认值             | 说明               |\n| ------------ | --------------------- | ---------------- | ------------------ | ------------------ |\n| id           | UUID                  | PK               | uuid_generate_v4() | 主键               |\n| email        | VARCHAR(255)          | UNIQUE, NOT NULL | -                  | 邮箱，用于登录     |\n| name         | VARCHAR(100)          | NOT NULL         | -                  | 用户名             |\n| passwordHash | VARCHAR(255)          | NOT NULL         | -                  | 密码哈希（bcrypt） |\n| role         | ENUM('user', 'admin') | NOT NULL         | 'user'             | 用户角色           |\n| createdAt    | TIMESTAMP             | NOT NULL         | NOW()              | 创建时间           |\n| updatedAt    | TIMESTAMP             | NOT NULL         | NOW()              | 更新时间           |\n\n**索引**：\n- `idx_user_email`: email（唯一索引，用于登录查询）\n- `idx_user_role`: role（用于角色筛选）\n\n#### Post 表\n\n| 字段        | 类型                                   | 约束         | 默认值             | 说明                    |\n| ----------- | -------------------------------------- | ------------ | ------------------ | ----------------------- |\n| id          | UUID                                   | PK           | uuid_generate_v4() | 主键                    |\n| authorId    | UUID                                   | FK, NOT NULL | -                  | 作者ID，外键关联User.id |\n| title       | VARCHAR(200)                           | NOT NULL     | -                  | 文章标题                |\n| content     | TEXT                                   | NOT NULL     | -                  | 文章内容                |\n| status      | ENUM('draft', 'published', 'archived') | NOT NULL     | 'draft'            | 文章状态                |\n| publishedAt | TIMESTAMP                              | NULL         | -                  | 发布时间                |\n| createdAt   | TIMESTAMP                              | NOT NULL     | NOW()              | 创建时间                |\n| updatedAt   | TIMESTAMP                              | NOT NULL     | NOW()              | 更新时间                |\n\n**索引**：\n- `idx_post_author`: authorId（用于查询用户的文章）\n- `idx_post_status`: status（用于筛选状态）\n- `idx_post_published`: publishedAt（用于按发布时间排序）\n\n### 5. 数据类型选择\n\n| 数据类型     | 使用场景   | PostgreSQL      | MySQL                    | MongoDB  |\n| ------------ | ---------- | --------------- | ------------------------ | -------- |\n| **主键**     | 唯一标识   | UUID, SERIAL    | INT AUTO_INCREMENT, UUID | ObjectId |\n| **字符串**   | 短文本     | VARCHAR(n)      | VARCHAR(n)               | String   |\n| **长文本**   | 文章内容   | TEXT            | TEXT                     | String   |\n| **整数**     | 数量、年龄 | INTEGER, BIGINT | INT, BIGINT              | Number   |\n| **小数**     | 价格、评分 | DECIMAL(p,s)    | DECIMAL(p,s)             | Number   |\n| **布尔**     | 是否标志   | BOOLEAN         | TINYINT(1)               | Boolean  |\n| **日期时间** | 时间戳     | TIMESTAMP       | DATETIME                 | Date     |\n| **枚举**     | 固定选项   | ENUM            | ENUM                     | String   |\n| **JSON**     | 灵活数据   | JSONB           | JSON                     | Object   |\n\n**推荐**：\n- **主键**：使用 UUID 而非自增ID（避免暴露数据量、分布式友好）\n- **时间戳**：使用 TIMESTAMP WITH TIME ZONE（时区友好）\n- **枚举**：使用 ENUM 而非字符串（类型安全、节省空间）\n- **JSON**：PostgreSQL 使用 JSONB（支持索引和查询）\n\n## API设计\n\n### 1. API规范选择\n\n| 规范        | 适用场景           | 优点               | 缺点               |\n| ----------- | ------------------ | ------------------ | ------------------ |\n| **RESTful** | 通用场景、CRUD操作 | 简单、标准、易理解 | 过度获取、多次请求 |\n| **GraphQL** | 复杂查询、多端适配 | 按需获取、类型安全 | 学习曲线、缓存复杂 |\n| **gRPC**    | 微服务、高性能     | 性能高、类型安全   | 浏览器支持差       |\n\n**本项目推荐**：RESTful（除非有特殊需求）\n\n### 2. RESTful API设计原则\n\n#### 资源命名\n\n- **使用名词**：`\u002Fusers`, `\u002Fposts`, `\u002Fcomments`（不是 `\u002FgetUsers`, `\u002FcreatePost`）\n- **使用复数**：`\u002Fusers`（不是 `\u002Fuser`）\n- **使用小写**：`\u002Fusers`（不是 `\u002FUsers`）\n- **使用连字符**：`\u002Forder-items`（不是 `\u002ForderItems` 或 `\u002Forder_items`）\n\n#### HTTP方法\n\n| 方法   | 用途     | 示例                | 幂等性 |\n| ------ | -------- | ------------------- | ------ |\n| GET    | 获取资源 | `GET \u002Fusers`        | 是     |\n| POST   | 创建资源 | `POST \u002Fusers`       | 否     |\n| PUT    | 完整更新 | `PUT \u002Fusers\u002F123`    | 是     |\n| PATCH  | 部分更新 | `PATCH \u002Fusers\u002F123`  | 否     |\n| DELETE | 删除资源 | `DELETE \u002Fusers\u002F123` | 是     |\n\n#### URL设计\n\n| 操作     | 方法   | URL                 | 说明                 |\n| -------- | ------ | ------------------- | -------------------- |\n| 获取列表 | GET    | `\u002Fapi\u002Fv1\u002Fusers`     | 支持分页、筛选、排序 |\n| 获取详情 | GET    | `\u002Fapi\u002Fv1\u002Fusers\u002F:id` | 返回单个资源         |\n| 创建     | POST   | `\u002Fapi\u002Fv1\u002Fusers`     | 请求体包含资源数据   |\n| 完整更新 | PUT    | `\u002Fapi\u002Fv1\u002Fusers\u002F:id` | 替换整个资源         |\n| 部分更新 | PATCH  | `\u002Fapi\u002Fv1\u002Fusers\u002F:id` | 只更新指定字段       |\n| 删除     | DELETE | `\u002Fapi\u002Fv1\u002Fusers\u002F:id` | 删除资源             |\n\n**嵌套资源**：\n- `GET \u002Fapi\u002Fv1\u002Fusers\u002F:userId\u002Fposts` - 获取用户的文章\n- `POST \u002Fapi\u002Fv1\u002Fposts\u002F:postId\u002Fcomments` - 为文章创建评论\n\n**查询参数**：\n- 分页：`?page=1&limit=20`\n- 筛选：`?status=published&author=123`\n- 排序：`?sort=-createdAt`（-表示降序）\n- 搜索：`?q=keyword`\n\n### 3. 请求\u002F响应格式\n\n#### 成功响应\n\n**单个资源**：\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": \"123\",\n    \"name\": \"John Doe\",\n    \"email\": \"john@example.com\"\n  }\n}\n```\n\n**资源列表**：\n```json\n{\n  \"success\": true,\n  \"data\": [{ \"id\": \"1\", \"name\": \"Item 1\" }, { \"id\": \"2\", \"name\": \"Item 2\" }],\n  \"meta\": {\n    \"page\": 1,\n    \"limit\": 20,\n    \"total\": 100,\n    \"totalPages\": 5\n  }\n}\n```\n\n#### 错误响应\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"邮箱格式不正确\",\n    \"details\": [\n      {\n        \"field\": \"email\",\n        \"message\": \"必须是有效的邮箱地址\"\n      }\n    ]\n  }\n}\n```\n\n**错误码**：\n- `VALIDATION_ERROR`: 验证错误（400）\n- `UNAUTHORIZED`: 未认证（401）\n- `FORBIDDEN`: 无权限（403）\n- `NOT_FOUND`: 资源不存在（404）\n- `CONFLICT`: 资源冲突（409，如邮箱已存在）\n- `INTERNAL_ERROR`: 服务器错误（500）\n\n### 4. 认证和授权\n\n#### 认证方案\n\n**JWT (推荐)**：\n```\nAuthorization: Bearer \u003Ctoken>\n```\n\n**请求头**：\n```\nPOST \u002Fapi\u002Fv1\u002Fauth\u002Flogin\nContent-Type: application\u002Fjson\n\n{\n  \"email\": \"user@example.com\",\n  \"password\": \"password123\"\n}\n```\n\n**响应**：\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n    \"user\": {\n      \"id\": \"123\",\n      \"name\": \"John Doe\",\n      \"email\": \"john@example.com\"\n    }\n  }\n}\n```\n\n#### 授权模型\n\n**RBAC (基于角色)**：\n```typescript\nenum Role {\n  USER = 'user',\n  ADMIN = 'admin',\n}\n\n\u002F\u002F 中间件检查\nif (user.role !== Role.ADMIN) {\n  throw new ForbiddenError();\n}\n```\n\n### 5. API接口列表\n\n| 模块     | 方法   | 路径                  | 描述         | 认证 | 权限         |\n| -------- | ------ | --------------------- | ------------ | ---- | ------------ |\n| **认证** |        |                       |              |      |              |\n|          | POST   | \u002Fapi\u002Fv1\u002Fauth\u002Fregister | 用户注册     | 否   | -            |\n|          | POST   | \u002Fapi\u002Fv1\u002Fauth\u002Flogin    | 用户登录     | 否   | -            |\n|          | POST   | \u002Fapi\u002Fv1\u002Fauth\u002Flogout   | 用户登出     | 是   | -            |\n|          | GET    | \u002Fapi\u002Fv1\u002Fauth\u002Fme       | 获取当前用户 | 是   | -            |\n| **用户** |        |                       |              |      |              |\n|          | GET    | \u002Fapi\u002Fv1\u002Fusers         | 获取用户列表 | 是   | admin        |\n|          | GET    | \u002Fapi\u002Fv1\u002Fusers\u002F:id     | 获取用户详情 | 是   | -            |\n|          | PATCH  | \u002Fapi\u002Fv1\u002Fusers\u002F:id     | 更新用户信息 | 是   | self\u002Fadmin   |\n|          | DELETE | \u002Fapi\u002Fv1\u002Fusers\u002F:id     | 删除用户     | 是   | admin        |\n| **文章** |        |                       |              |      |              |\n|          | GET    | \u002Fapi\u002Fv1\u002Fposts         | 获取文章列表 | 否   | -            |\n|          | GET    | \u002Fapi\u002Fv1\u002Fposts\u002F:id     | 获取文章详情 | 否   | -            |\n|          | POST   | \u002Fapi\u002Fv1\u002Fposts         | 创建文章     | 是   | -            |\n|          | PATCH  | \u002Fapi\u002Fv1\u002Fposts\u002F:id     | 更新文章     | 是   | author\u002Fadmin |\n|          | DELETE | \u002Fapi\u002Fv1\u002Fposts\u002F:id     | 删除文章     | 是   | author\u002Fadmin |\n\n## 输出要求\n\n完成数据模型和API设计后，应输出以下内容（通常作为架构文档的第4-5章）：\n\n```markdown\n## 4. 数据模型\n\n### 4.1 实体关系图 (ERD)\n\n[Mermaid ERD]\n\n### 4.2 数据字典\n\n#### User 表\n\n[字段表格]\n\n#### Post 表\n\n[字段表格]\n\n---\n\n## 5. API 设计\n\n### 5.1 API 规范\n\n- **风格**：RESTful\n- **版本**：URL 前缀 `\u002Fapi\u002Fv1`\n- **认证**：Bearer Token (JWT)\n- **格式**：JSON\n\n### 5.2 接口列表\n\n[接口表格]\n\n### 5.3 响应格式\n\n[成功响应示例]\n[错误响应示例]\n```\n\n## 关键原则\n\n1. **规范化**：遵循数据库范式，避免冗余\n2. **类型安全**：使用强类型（UUID、ENUM）\n3. **RESTful**：遵循REST原则，资源导向\n4. **一致性**：命名、格式、错误码保持一致\n5. **文档化**：每个字段、每个接口都有清晰说明\n\n## 常见误区\n\n❌ **使用动词**：`\u002FgetUsers`, `\u002FcreatePost`（应该用HTTP方法表示动作）\n❌ **过度嵌套**：`\u002Fusers\u002F:id\u002Fposts\u002F:id\u002Fcomments\u002F:id`（最多2层）\n❌ **暴露实现**：`\u002Fapi\u002FgetUserFromDatabase`（暴露内部实现）\n❌ **不一致**：有的用复数有的用单数，有的驼峰有的下划线\n",{},"main","2b63f856ce19c2a797929cacabd9e0fc936812fa","plugins\u002FechoVic\u002Fboss-skill\u002Fskill\u002Fskills\u002Farchitect\u002Fdata-api-design",491,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins","https:\u002F\u002Fhol.org\u002Fplugins\u002Fbest-codex-plugins","https:\u002F\u002Fgithub.com\u002Fhashgraph-online","https:\u002F\u002Fhol.org","Open-source standards and developer tools for interoperable AI agents: discovery, identity, communication, payments, privacy and security.","2026-11-14 14:06:13",{"source":7,"skillName":5,"commands":55,"prompt":65,"zipAvailable":66},[56,59,62],{"tool":57,"command":58},"npx","npx skills add hashgraph-online\u002Fawesome-codex-plugins --skill data-api-design",{"tool":60,"command":61},"bunx","bunx skills add hashgraph-online\u002Fawesome-codex-plugins --skill data-api-design",{"tool":63,"command":64},"pnpm","pnpm dlx skills add hashgraph-online\u002Fawesome-codex-plugins --skill data-api-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FechoVic\u002Fboss-skill\u002Fskill\u002Fskills\u002Farchitect\u002Fdata-api-design\u002FSKILL.md",true,[],[69,79,87,95,103,111],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":73,"licenseFileUrl":74,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":78},"01M7DV332YQMGD8WTRJ9DZQXTB","worktable-review-with-annotations","Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.","MIT","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":73,"licenseFileUrl":83,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":78},"01M7DV2YGHCZVBEB1AHYB6CGHE","worktable-find-and-synthesize-context","Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":73,"licenseFileUrl":91,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":78},"01M7DV2TQN1H11ME2SAF9MXN7V","worktable-create-or-update-docs","Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":73,"licenseFileUrl":99,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":78},"01M7DV2NE452NEA8TXATKSNAJH","worktable-create-or-manage-records","Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":73,"licenseFileUrl":107,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":78},"01M7DV2HENRBR2KSCVM064WH0Y","worktable-create-or-manage-interactive-html","Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FSKILL.md",[],[],{"skillNo":112,"name":113,"nameZh":6,"description":114,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":73,"licenseFileUrl":115,"sourceHtmlUrl":116,"categories":117,"keywords":118,"publishedAt":78},"01M7DV2CADR5R7RQFFYPNAGR9Y","worktable-collaborate-threads","Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FSKILL.md",[],[]]