# 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)**:
```typescript
{
  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)**:
```typescript
{
  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)**:
```typescript
{
  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)**:
```typescript
{
  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 (当前)
- [x] 完成 ID 规范化 (users, projects, folders 主要部分)
- [x] 创建规范化文档和 RFC
- [ ] 完成 resources.ts 的完整更新
- [ ] 完成 storyboards.ts 的完整更新

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

### Week 3
- [ ] 更新相关组件和 hooks
- [ ] 集成测试
- [ ] 文档更新

## 风险和注意事项

1. **向后兼容性**: 现有代码可能依赖旧的 ID 格式
   - **缓解**: 逐步迁移，保留辅助函数

2. **数据量大**: resources.ts 有大量数据需要更新
   - **缓解**: 使用脚本批量处理

3. **测试覆盖**: 需要确保所有依赖 mock 数据的测试通过
   - **缓解**: 先更新 mock 数据，再运行测试套件

## 参考文档

- [项目管理服务](../../../docs/requirements/backend/04-services/project/project-service.md)
- [文件夹管理服务](../../../docs/requirements/backend/04-services/project/folder-service.md)
- [用户管理服务](../../../docs/requirements/backend/04-services/user/user-service.md)
- [项目资源服务](../../../docs/requirements/backend/04-services/resource/project-resource-service.md)
- [分镜管理服务](../../../docs/requirements/backend/04-services/project/storyboard-service.md)

## 变更记录

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