5.0 KiB

Raw Blame History

RFC 129: Mock 数据规范化方案

状态: 实施中
创建日期: 2026-01-24
作者: AI Assistant

背景

前端 mock 数据与后端 API 规范存在多处不一致，包括 ID 格式、字段命名、枚举值等，需要进行全面规范化。

问题分析

1. ID 格式不一致

现状: 使用简单数字字符串 ('1', '2', '3')
目标: 使用 UUID v7 格式 ('018e1234-5678-7abc-8def-100000000001')
影响: 所有实体的 ID 和外键引用

2. 字段命名不一致

现状: 混用 snake_case 和 camelCase
目标: API 响应层统一使用 camelCase
影响: 类型定义和 mock 数据

3. 枚举值格式

现状: 直接使用字符串或数字
目标: 使用后端 API 层的字符串格式
示例:
- 项目类型: 'mine' | 'collab'
- 文件夹分类: 1 (MY_PROJECTS) | 2 (COLLABORATIVE_PROJECTS)

4. 缺失字段

用户: country_code, phone_verified, username_changed
项目: tagline, synopsis, owner_type
文件夹: breadcrumbs 数组结构
资源: screenplay_character_id 等剧本关联字段

解决方案

阶段 1: ID 规范化 ✅

已完成:

✅ users.ts - 所有用户 ID 更新为 UUID v7
✅ projects.ts - 所有项目 ID 更新为 UUID v7
✅ folders.ts - 所有文件夹 ID 和 ownerId 更新为 UUID v7
✅ storyboards.ts - 分镜 ID 和 projectId 更新为 UUID v7 (部分)
✅ resources.ts - 资源 ID 和关联 ID 更新为 UUID v7 (部分)

待完成:

⏳ resources.ts - 完成所有资源的 ID 更新
⏳ storyboards.ts - 完成所有分镜的 ID 更新
⏳ timeline.ts - 时间轴数据 ID 更新
⏳ variants.ts - 变体数据 ID 更新
⏳ voices.ts - 配音数据 ID 更新

阶段 2: 字段补充

用户表 (users.ts):

{
  user_id: string;        // UUID v7
  username: string;
  email?: string;
  phone: string;
  country_code: string;   // 新增
  phone_verified: boolean; // 新增
  username_changed: boolean; // 新增
  nickname?: string;
  avatar_url?: string;
  ai_credits_balance: number;
  created_at: string;
}

项目表 (projects.ts):

{
  id: string;             // UUID v7
  name: string;
  description?: string;
  type: 'mine' | 'collab';
  ownerId: string;        // UUID v7
  folderId?: string;      // UUID v7
  tagline?: string;       // 新增
  synopsis?: string;      // 新增
  contentType?: ProjectContentType;
  aspectRatio?: AspectRatioType;
  plannedDuration?: number;
  actualDuration?: number;
  styleAndCharacters?: string;
  // ...
}

文件夹表 (folders.ts):

{
  id: string;             // UUID v7
  name: string;
  parentFolderId?: string; // UUID v7
  ownerId: string;        // UUID v7
  folderCategory: 1 | 2;  // 1=我的项目, 2=协作项目
  breadcrumbs: Array<{    // 新增
    id: string;
    name: string;
  }>;
  // ...
}

资源表 (resources.ts):

{
  id: string;             // UUID v7
  projectId: string;      // UUID v7
  name: string;
  type: 'character' | 'scene' | 'prop' | 'real'; // 新增 'real'
  screenplay_character_id?: string; // 新增
  screenplay_scene_id?: string;     // 新增
  screenplay_prop_id?: string;      // 新增
  element_tag_id?: string;          // 新增
  // ...
}

阶段 3: 数据关联性验证

验证清单:

所有 projectId 引用的项目存在
所有 folderId 引用的文件夹存在
所有 ownerId/createdBy 引用的用户存在
分镜的 resources 关联正确
时间轴的 storyboardId 关联正确

阶段 4: 辅助函数更新

更新所有查询辅助函数，确保支持 UUID v7 格式的 ID 查询。

实施计划

Week 1 (当前)

完成 ID 规范化 (users, projects, folders 主要部分)
创建规范化文档和 RFC
完成 resources.ts 的完整更新
完成 storyboards.ts 的完整更新

Week 2

补充所有缺失字段
验证数据关联性
更新辅助函数
编写单元测试

Week 3

更新相关组件和 hooks
集成测试
文档更新

风险和注意事项

向后兼容性: 现有代码可能依赖旧的 ID 格式
- 缓解: 逐步迁移，保留辅助函数
数据量大: resources.ts 有大量数据需要更新
- 缓解: 使用脚本批量处理
测试覆盖: 需要确保所有依赖 mock 数据的测试通过
- 缓解: 先更新 mock 数据，再运行测试套件

参考文档

变更记录

2026-01-24: 创建 RFC，完成阶段 1 的主要部分

5.0 KiB Raw Blame History