@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/fullstack-consistency.md

@@ -0,0 +1,418 @@
+# 全栈一致性检查清单 (Fullstack Consistency Checklist)
+
+> **核心原则**: 前端、后端、数据库三层必须保持数据结构、状态码、字段命名的完全一致。
+
+---
+
+## 🔴 为什么需要全栈一致性检查
+
+### 真实案例
+
+```
+项目: 电商订单系统
+问题: 订单状态显示错误
+
+根因分析:
+- 后端定义: status = "PENDING" | "PAID" | "SHIPPED" | "DELIVERED"
+- 前端期望: status = "pending" | "paid" | "shipped" | "delivered"
+- 数据库存储: status = 0 | 1 | 2 | 3 (数字枚举)
+
+结果: 前端显示 "未知状态"，用户投诉
+```
+
+---
+
+## 📋 Phase 1: API 契约一致性检查
+
+### 1.1 请求字段一致性
+
+```markdown
+## 请求字段检查表
+
+### 端点: POST /api/v1/orders
+
+| 字段 | 前端发送 | 后端期望 | 数据库字段 | 一致? |
+|------|----------|----------|------------|-------|
+| userId | user_id | userId | user_id | ❌ 命名不一致 |
+| productId | productId | productId | product_id | ⚠️ DB 不一致 |
+| quantity | quantity | quantity | quantity | ✅ |
+| price | price | amount | price | ❌ 后端字段名不同 |
+```
+
+**检查命令**:
+```bash
+# 提取后端请求模型
+grep -rn "class.*Request" --include="*.py" -A 20 | grep -E "^\s+\w+:"
+
+# 提取前端请求体
+grep -rn "body.*JSON.stringify" --include="*.ts" --include="*.tsx" -A 5
+
+# 提取数据库模型
+grep -rn "class.*Model" --include="*.py" -A 30 | grep -E "^\s+\w+\s*="
+```
+
+### 1.2 响应字段一致性
+
+```markdown
+## 响应字段检查表
+
+### 端点: GET /api/v1/users/{id}
+
+| 字段 | 后端返回 | 前端期望 | 类型匹配 | 一致? |
+|------|----------|----------|----------|-------|
+| id | id | id | number | ✅ |
+| name | name | userName | - | ❌ 字段名不同 |
+| email | email | email | string | ✅ |
+| createdAt | created_at | createdAt | - | ❌ 命名风格不同 |
+| avatar | avatar_url | avatar | - | ❌ 字段名不同 |
+| role | role | role | string | ✅ |
+| permissions | - | permissions | - | ❌ 后端未返回 |
+```
+
+**常见问题**:
+| 问题类型 | 示例 | 严重级别 |
+|----------|------|----------|
+| 字段名不一致 | `user_id` vs `userId` | P1 |
+| 字段缺失 | 后端返回但前端未使用 | P2 |
+| 字段多余 | 前端期望但后端未返回 | P0 |
+| 类型不匹配 | 后端返回 string，前端期望 number | P0 |
+| 嵌套结构不一致 | `user.profile.name` vs `user.name` | P1 |
+
+### 1.3 状态码一致性
+
+```markdown
+## HTTP 状态码检查表
+
+| 场景 | 后端返回 | 前端处理 | 一致? |
+|------|----------|----------|-------|
+| 成功 | 200 | 200 | ✅ |
+| 创建成功 | 201 | 200 (当作成功) | ⚠️ 可接受 |
+| 无内容 | 204 | 期望 200 + body | ❌ 前端报错 |
+| 参数错误 | 400 | 400 | ✅ |
+| 未认证 | 401 | 401 → 跳转登录 | ✅ |
+| 无权限 | 403 | 401 (混淆) | ❌ 处理错误 |
+| 未找到 | 404 | 404 | ✅ |
+| 验证失败 | 422 | 400 (混淆) | ❌ 处理错误 |
+| 服务器错误 | 500 | 500 | ✅ |
+```
+
+### 1.4 错误响应格式一致性
+
+```markdown
+## 错误响应格式检查
+
+### 后端错误响应格式
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid email format",
+    "details": [
+      { "field": "email", "message": "Must be a valid email" }
+    ]
+  }
+}
+```
+
+### 前端期望格式
+```typescript
+interface ErrorResponse {
+  message: string;  // ❌ 期望顶层 message
+  errors?: Record<string, string[]>;  // ❌ 期望不同的 details 格式
+}
+```
+
+### 一致性问题
+| 检查项 | 后端 | 前端 | 一致? |
+|--------|------|------|-------|
+| 错误消息位置 | error.message | message | ❌ |
+| 字段错误格式 | error.details[].field | errors[field] | ❌ |
+| 错误码 | error.code | 无 | ⚠️ 前端未使用 |
+```
+
+---
+
+## 📋 Phase 2: 枚举/状态值一致性检查
+
+### 2.1 状态枚举一致性
+
+```markdown
+## 状态枚举检查表
+
+### 订单状态 (Order Status)
+
+| 状态 | 后端定义 | 前端定义 | 数据库存储 | 一致? |
+|------|----------|----------|------------|-------|
+| 待支付 | "PENDING" | "pending" | 0 | ❌ 大小写+类型 |
+| 已支付 | "PAID" | "paid" | 1 | ❌ 大小写+类型 |
+| 已发货 | "SHIPPED" | "shipping" | 2 | ❌ 命名不同 |
+| 已完成 | "COMPLETED" | "done" | 3 | ❌ 命名不同 |
+| 已取消 | "CANCELLED" | "canceled" | 4 | ❌ 拼写不同 |
+```
+
+**检查命令**:
+```bash
+# 后端枚举定义
+grep -rn "class.*Status.*Enum\|class.*Type.*Enum" --include="*.py" -A 10
+
+# 前端枚举/常量定义
+grep -rn "enum\|const.*Status\|const.*Type" --include="*.ts" --include="*.tsx" -A 10
+
+# 数据库枚举定义
+grep -rn "ENUM\|CHECK.*IN" --include="*.sql"
+```
+
+### 2.2 布尔值一致性
+
+```markdown
+## 布尔值表示检查
+
+| 字段 | 后端返回 | 前端期望 | 数据库存储 | 一致? |
+|------|----------|----------|------------|-------|
+| isActive | true/false | true/false | 1/0 | ✅ (ORM 转换) |
+| enabled | "true"/"false" | true/false | "Y"/"N" | ❌ 类型不匹配 |
+| deleted | 1/0 | true/false | 1/0 | ❌ 类型不匹配 |
+```
+
+### 2.3 日期时间格式一致性
+
+```markdown
+## 日期时间格式检查
+
+| 字段 | 后端返回 | 前端期望 | 数据库存储 | 一致? |
+|------|----------|----------|------------|-------|
+| createdAt | "2024-01-15T10:30:00Z" | ISO 8601 | TIMESTAMP | ✅ |
+| updatedAt | "2024-01-15 10:30:00" | ISO 8601 | DATETIME | ❌ 格式不同 |
+| birthday | "15/01/2024" | "YYYY-MM-DD" | DATE | ❌ 格式不同 |
+| timestamp | 1705312200 | Date object | BIGINT | ⚠️ 需转换 |
+```
+
+---
+
+## 📋 Phase 3: 数据库一致性检查
+
+### 3.1 字段命名一致性
+
+```markdown
+## 数据库字段命名检查
+
+### 命名风格对比
+| 层级 | 命名风格 | 示例 |
+|------|----------|------|
+| 数据库 | snake_case | user_id, created_at |
+| 后端模型 | camelCase 或 snake_case | userId 或 user_id |
+| API 响应 | camelCase | userId, createdAt |
+| 前端 | camelCase | userId, createdAt |
+
+### 检查清单
+- [ ] 数据库字段名与后端模型映射正确
+- [ ] 后端序列化时字段名转换正确
+- [ ] 前端接收的字段名与类型定义一致
+```
+
+### 3.2 数据类型一致性
+
+```markdown
+## 数据类型映射检查
+
+| 数据库类型 | 后端类型 | API 类型 | 前端类型 | 一致? |
+|------------|----------|----------|----------|-------|
+| INT | int | number | number | ✅ |
+| BIGINT | int | number | number | ⚠️ JS 精度问题 |
+| VARCHAR(255) | str | string | string | ✅ |
+| TEXT | str | string | string | ✅ |
+| DECIMAL(10,2) | Decimal | string | string | ⚠️ 需注意精度 |
+| BOOLEAN | bool | boolean | boolean | ✅ |
+| JSON | dict | object | object | ✅ |
+| TIMESTAMP | datetime | string (ISO) | Date | ⚠️ 需转换 |
+| UUID | UUID | string | string | ✅ |
+```
+
+**特别注意**:
+```typescript
+// ❌ BIGINT 精度问题
+// 数据库: 9007199254740993 (超过 JS 安全整数)
+// 前端收到: 9007199254740992 (精度丢失!)
+
+// ✅ 解决方案: 后端返回字符串
+{
+  "id": "9007199254740993"  // string 类型
+}
+```
+
+### 3.3 约束一致性
+
+```markdown
+## 约束一致性检查
+
+| 约束类型 | 数据库 | 后端验证 | 前端验证 | 一致? |
+|----------|--------|----------|----------|-------|
+| NOT NULL | ✅ | ✅ required | ✅ required | ✅ |
+| UNIQUE | ✅ email | ❌ 未检查 | ❌ 未检查 | ❌ |
+| 长度限制 | VARCHAR(100) | max_length=100 | maxLength={100} | ✅ |
+| 范围限制 | CHECK(age>=0) | ge=0 | min={0} | ✅ |
+| 外键 | FOREIGN KEY | ❌ 未验证存在 | ❌ 未验证 | ❌ |
+| 默认值 | DEFAULT 0 | default=0 | 无 | ⚠️ |
+```
+
+---
+
+## 📋 Phase 4: SSE/WebSocket 一致性检查
+
+### 4.1 事件名称一致性
+
+```markdown
+## SSE/WebSocket 事件检查
+
+| 事件 | 后端发送 | 前端监听 | 一致? |
+|------|----------|----------|-------|
+| 消息开始 | "message_start" | "messageStart" | ❌ |
+| 内容块 | "content_block" | "content" | ❌ |
+| 工具调用 | "tool_use" | "tool_call" | ❌ |
+| 完成 | "done" | "complete" | ❌ |
+| 错误 | "error" | "error" | ✅ |
+```
+
+### 4.2 事件数据结构一致性
+
+```markdown
+## 事件数据结构检查
+
+### 事件: tool_use
+
+**后端发送**:
+```json
+{
+  "type": "tool_use",
+  "tool_name": "search",
+  "tool_input": { "query": "test" },
+  "tool_use_id": "tu_123"
+}
+```
+
+**前端期望**:
+```typescript
+interface ToolCallEvent {
+  type: "tool_call";  // ❌ 事件类型不同
+  name: string;       // ❌ 字段名不同 (tool_name vs name)
+  args: object;       // ❌ 字段名不同 (tool_input vs args)
+  id: string;         // ❌ 字段名不同 (tool_use_id vs id)
+}
+```
+```
+
+---
+
+## 📋 Phase 5: 分页/排序一致性检查
+
+### 5.1 分页参数一致性
+
+```markdown
+## 分页参数检查
+
+| 参数 | 前端发送 | 后端期望 | 一致? |
+|------|----------|----------|-------|
+| 页码 | page | page | ✅ |
+| 每页数量 | pageSize | limit | ❌ |
+| 偏移量 | - | offset | ⚠️ 后端额外支持 |
+| 起始页 | 1 | 0 | ❌ 起始值不同 |
+```
+
+### 5.2 分页响应一致性
+
+```markdown
+## 分页响应检查
+
+**后端返回**:
+```json
+{
+  "items": [...],
+  "total": 100,
+  "page": 1,
+  "page_size": 10,
+  "total_pages": 10
+}
+```
+
+**前端期望**:
+```typescript
+interface PaginatedResponse<T> {
+  data: T[];           // ❌ items vs data
+  total: number;       // ✅
+  currentPage: number; // ❌ page vs currentPage
+  pageSize: number;    // ❌ page_size vs pageSize
+  totalPages: number;  // ❌ total_pages vs totalPages
+}
+```
+```
+
+---
+
+## 📊 全栈一致性检查汇总模板
+
+```markdown
+## 全栈一致性审查报告
+
+### API 契约检查
+| 端点 | 请求字段 | 响应字段 | 状态码 | 错误格式 |
+|------|----------|----------|--------|----------|
+| POST /users | ✅ | ⚠️ 2处不一致 | ✅ | ❌ |
+| GET /users/{id} | N/A | ❌ 3处不一致 | ✅ | ❌ |
+| PUT /users/{id} | ⚠️ 1处不一致 | ✅ | ✅ | ❌ |
+
+### 枚举/状态值检查
+| 枚举类型 | 后端-前端 | 后端-数据库 | 前端-数据库 |
+|----------|-----------|-------------|-------------|
+| OrderStatus | ❌ | ⚠️ | ❌ |
+| UserRole | ✅ | ✅ | ✅ |
+| PaymentType | ❌ | ✅ | ❌ |
+
+### 数据库一致性检查
+| 表 | 字段命名 | 数据类型 | 约束 |
+|----|----------|----------|------|
+| users | ✅ | ⚠️ BIGINT | ❌ UNIQUE 未验证 |
+| orders | ❌ snake_case | ✅ | ✅ |
+
+### 问题汇总
+| # | 层级 | 问题 | 严重级别 | 修复建议 |
+|---|------|------|----------|----------|
+| 1 | API | 响应字段 name vs userName | P1 | 统一为 name |
+| 2 | 枚举 | 状态值大小写不一致 | P1 | 统一为大写 |
+| 3 | DB | BIGINT 精度问题 | P0 | 返回字符串 |
+```
+
+---
+
+## 🔧 自动化检查脚本
+
+```bash
+#!/bin/bash
+# fullstack-consistency-check.sh
+
+echo "=== 全栈一致性检查 ==="
+
+echo ""
+echo "--- 1. API 字段对比 ---"
+echo "后端请求模型:"
+grep -rn "class.*Request.*BaseModel" --include="*.py" -A 15 | head -50
+
+echo ""
+echo "前端请求类型:"
+grep -rn "interface.*Request\|type.*Request" --include="*.ts" -A 10 | head -50
+
+echo ""
+echo "--- 2. 枚举值对比 ---"
+echo "后端枚举:"
+grep -rn "class.*Enum\|Literal\[" --include="*.py" | head -20
+
+echo ""
+echo "前端枚举:"
+grep -rn "enum \|type.*=.*\|" --include="*.ts" | grep -v node_modules | head -20
+
+echo ""
+echo "--- 3. 数据库字段 ---"
+grep -rn "Column\|Field" --include="*.py" | grep -E "String|Integer|Boolean|DateTime" | head -30
+
+echo ""
+echo "=== 检查完成 ==="
+```