# 数据库设计重构方案 —— 问题分析、解决方案与变更影响

---

## 问题总览

| 编号 | 问题 | 解决类型 | 风险等级 |
|------|------|----------|----------|
| 1 | 数据冗余（冗余归档表 + user_works 状态不同步） | 代码重构 + Flyway 迁移 | 中 |
| 2 | 模式文件不同步（schema.sql / init_database.sql / Flyway 冲突） | 文件清理 + 重命名 | 低 |
| 3 | 枚举类型重复定义（4个实体各自定义 TaskType/WorkType） | 代码重构 | 低 |
| 4 | Payment 字段命名混淆（orderId 实为业务订单号，非外键） | **已撤回，不做改动** | 无 |
| 5 | 用户名冗余存储（8张表都存 username，改名时无法同步） | 新增级联更新方法 | 低 |
| 6 | Base64 图片直接存数据库（storyboardImages 字段） | 保存时上传 COS | 低 |
| 7 | task_queue 与 task_status 职责边界模糊 | 仅文档注释 | 无 |

---

## 问题一：数据冗余

### 问题描述

1. `completed_tasks_archive` 表：将完成的任务复制到归档表，但原表数据并未删除，形成冗余副本
2. `failed_tasks_cleanup_log` 表：记录清理日志，但 `user_error_log` 表已有完整的错误记录，功能重复
3. `user_works` 状态与 `task_queue` / 业务任务表不同步：多条更新路径导致状态可能不一致

### 解决方案

**1A — 删除冗余归档表**

- 删除 JPA 实体：`CompletedTaskArchive.java`、`FailedTaskCleanupLog.java`
- 删除 Repository：`CompletedTaskArchiveRepository.java`、`FailedTaskCleanupLogRepository.java`
- 新增 Flyway 迁移：`V16__Drop_Redundant_Archive_Tables.sql`

```sql
DROP TABLE IF EXISTS completed_tasks_archive;
DROP TABLE IF EXISTS failed_tasks_cleanup_log;
```

**1B — 重构 TaskCleanupService**

- 移除所有归档/清理日志的写入逻辑
- 失败任务清理时改用 `userErrorLogService.logErrorAsync()` 记录，不再写单独的表

**1C — 增强 user_works 状态修复**

- 在 `TaskQueueService.repairUserWorkStatus()` 中增加对长时间停留在 `PROCESSING` 状态的任务的检测和修复
- 在 `TaskQueueScheduler` 中添加 5 分钟执行一次的定时任务，自动发现并修复不一致状态

### 变更影响

| 影响范围 | 说明 |
|----------|------|
| 数据库 | 删除 2 张表。已有数据丢失（归档记录），但原始数据仍在 task_queue / user_error_log 中 |
| TaskCleanupService | 大幅精简，从 ~150 行减到 ~60 行 |
| TaskQueueScheduler | 新增 `repairUserWorkStatus()` 定时任务 |
| 前端 | **无影响**，前端未直接查询这两张表 |

### 涉及文件

```
[已删除] model/CompletedTaskArchive.java
[已删除] model/FailedTaskCleanupLog.java
[已删除] repository/CompletedTaskArchiveRepository.java
[已删除] repository/FailedTaskCleanupLogRepository.java
[已修改] service/TaskCleanupService.java          — 移除归档逻辑
[已修改] service/TaskQueueService.java             — 增强 repairUserWorkStatus()
[已修改] scheduler/TaskQueueScheduler.java         — 新增状态修复定时任务
[已新增] db/migration/V16__Drop_Redundant_Archive_Tables.sql
```

---

## 问题二：模式文件不同步

### 问题描述

1. `schema.sql` 与 `init_database.sql` 内容不一致，且与 Flyway 迁移脚本重复
2. Flyway 迁移脚本存在版本号冲突：V2、V3、V7 各有两个同版本号的文件

### 解决方案

**2A — 删除过时的 schema.sql**

该文件仅在最初开发时使用，Flyway 已接管所有数据库变更。

**2B — 标注 init_database.sql**

在文件头部添加醒目注释，说明仅用于全新手动部署，不由 Flyway 管理。同时移除其中 `completed_tasks_archive` 和 `failed_tasks_cleanup_log` 的建表语句（与问题一保持一致）。

**2C — 修复 Flyway 版本号冲突**

| 原文件名 | 新文件名 |
|----------|----------|
| V2__add_indexes.sql | V2.1__add_indexes.sql |
| V2__add_task_status_cascade_triggers.sql | V2.2__add_task_status_cascade_triggers.sql |
| V3__Create_Task_Queue_Table.sql | V3.1__Create_Task_Queue_Table.sql |
| V3__fix_foreign_key_cascade.sql | V3.2__fix_foreign_key_cascade.sql |
| V7__Add_indexes_task_status.sql | V7.1__Add_indexes_task_status.sql |
| V7__Create_Task_Cleanup_Tables.sql | V7.2__Create_Task_Cleanup_Tables.sql |

`V7.2__Create_Task_Cleanup_Tables.sql` 内容改为空操作（注释说明已被 V16 取代）。

### 变更影响

| 影响范围 | 说明 |
|----------|------|
| 数据库 | **无影响**——仅重命名迁移文件，内容不变 |
| 应用启动 | Flyway 不再因版本冲突报错 |
| 开发者 | 只需关注 `db/migration/` 下的 Flyway 脚本 |

### 涉及文件

```
[已删除] src/main/resources/schema.sql
[已修改] init_database.sql                    — 添加注释头 + 移除冗余建表
[已重命名] V2/V3/V7 重复的迁移脚本（共 6 个文件）
[已修改] V7.2__Create_Task_Cleanup_Tables.sql — 改为 no-op
```

---

## 问题三：枚举类型重复定义

### 问题描述

4 个实体类各自在内部定义了功能相同的枚举：

- `TaskQueue.TaskType` — TEXT_TO_VIDEO / IMAGE_TO_VIDEO / STORYBOARD_VIDEO / STORYBOARD_IMAGE
- `TaskStatus.TaskType` — 同上
- `PointsFreezeRecord.TaskType` — 同上
- `UserWork.WorkType` — 同上（仅名称不同）

新增任务类型时需要改 4 个地方，容易遗漏。

### 解决方案

新建统一枚举 `com.example.demo.model.enums.CommonTaskType`：

```java
public enum CommonTaskType {
    TEXT_TO_VIDEO("文生视频"),
    IMAGE_TO_VIDEO("图生视频"),
    STORYBOARD_VIDEO("分镜视频"),
    STORYBOARD_IMAGE("分镜图");
}
```

删除 4 个实体类中的内部枚举，所有字段类型、构造方法参数、getter/setter 统一改为 `CommonTaskType`。

### 全项目扫描结果

| 扫描范围 | 旧枚举引用数 | 状态 |
|----------|-------------|------|
| `src/main/`（主代码，所有 service / model / controller） | 0 | 已全部替换 |
| `src/test/PointsRefundIntegrationTest.java` | 16 处 `PointsFreezeRecord.TaskType` | 已修复 → `CommonTaskType` |
| `frontend/src/`（前端 Vue 组件） | 使用字符串值 `'TEXT_TO_VIDEO'` 等 | 无需修改（枚举名不变，API 返回值不变） |

### 变更影响

| 影响范围 | 说明 |
|----------|------|
| 数据库 | **无影响**——JPA 使用 `@Enumerated(EnumType.STRING)`，数据库中存储的字符串值不变 |
| 编译 | 所有引用 `TaskQueue.TaskType`、`TaskStatus.TaskType`、`UserWork.WorkType`、`PointsFreezeRecord.TaskType` 的地方都需要改为 `CommonTaskType` |
| 测试代码 | `PointsRefundIntegrationTest.java` 中 16 处旧引用已同步更新 |
| 前端 | **无影响**——前端使用字符串值匹配，枚举名称未改变 |

### 涉及文件

```
[已新增] model/enums/CommonTaskType.java
[已修改] model/TaskQueue.java              — 删除内部枚举，字段改为 CommonTaskType
[已修改] model/TaskStatus.java             — 同上
[已修改] model/PointsFreezeRecord.java     — 同上
[已修改] model/UserWork.java               — 删除 WorkType，字段改为 CommonTaskType
[已修改] service/TaskQueueService.java     — 更新所有枚举引用
[已修改] service/TaskStatusPollingService.java — 更新 createTaskStatus / convertToTaskStatusType
[已修改] service/UserWorkService.java      — 更新 WorkType 引用
[已修改] test/service/PointsRefundIntegrationTest.java — 16 处旧枚举引用更新
```

---

## 问题四：Payment 字段命名混淆 —— 已撤回，不做改动

### 问题描述

`Payment.orderId` 存储的是业务订单号（如 `"ORD123456789"`），是一个 String 标识符，不是外键。命名为 `orderId` 可能被误读为外键。

### 评估结论：不需要改动

经过完整的支付链路分析，改名会导致以下问题：

**JSON 序列化会破坏前端**
- `Payment` 实体没有 `@JsonProperty` 注解，Jackson 序列化直接使用 Java 字段名
- 改名后 JSON key 从 `"orderId"` 变为 `"orderNumber"`
- 前端 `Payments.vue` 等多个组件通过 `payment.orderId` 访问该字段，改名后全部变成 `undefined`
- 修复需要同步改动前端 6+ 个 Vue 文件，涉及面过大

**原始问题不影响功能**
- `orderId` 命名虽然容易被误读为外键，但代码逻辑完全正确
- 支付回调（Alipay / LuluPay）通过 `out_trade_no` 查找，链路正常
- 这只是一个代码可读性问题，不值得冒支付功能出错的风险

### 涉及文件

```
无改动
```

---

## 问题五：用户名冗余存储

### 问题描述

8 张业务表都存储了 `username` 字段（冗余存储，非外键关联），用户改名时这些表无法同步更新，导致数据不一致。

涉及的表：`task_queue`、`task_status`、`text_to_video_tasks`、`image_to_video_tasks`、`storyboard_video_tasks`、`points_freeze_records`、`user_error_log`、`user_works`

### 解决方案

在 `UserService` 中新增 `cascadeUpdateUsername(oldUsername, newUsername)` 方法，在用户改名时通过 `JdbcTemplate` 批量更新所有相关表：

```java
private void cascadeUpdateUsername(String oldUsername, String newUsername) {
    String[] tables = {
        "task_queue", "task_status", "text_to_video_tasks",
        "image_to_video_tasks", "storyboard_video_tasks",
        "points_freeze_records", "user_error_log", "user_works"
    };
    for (String table : tables) {
        jdbcTemplate.update(
            "UPDATE " + table + " SET username = ? WHERE username = ?",
            newUsername, oldUsername);
    }
}
```

该方法在 `updateUsername()` 中被调用，确保改名操作是原子性的。

### 变更影响

| 影响范围 | 说明 |
|----------|------|
| 数据库 | **无结构变更**——仅在改名时批量 UPDATE 数据 |
| 性能 | 改名操作会执行 8 条 UPDATE 语句，但用户改名是低频操作，影响可忽略 |
| 索引 | 各表的 `username` 字段已有索引，UPDATE 不会全表扫描 |
| 前端 | **无影响** |

### 涉及文件

```
[已修改] service/UserService.java — 注入 JdbcTemplate，新增 cascadeUpdateUsername()
```

---

## 问题六：Base64 图片直接存数据库

### 问题描述

分镜图功能中，外部 AI API 返回 Base64 图片后：
- `resultUrl`（网格合并图）**已经在保存时上传 COS** ✓
- `storyboardImages`（单独分镜图片 JSON 数组）**直接将 Base64 存入数据库** ✗

一张 Base64 图片约 200KB-1MB，6 张分镜图意味着每条任务记录可能有 3-6MB 的文本存在 `LONGTEXT` 字段中，严重影响数据库性能和备份效率。

### 解决方案

**在保存时就将每张图上传 COS，存 COS 返回的链接，Base64 不进库。**

新增私有方法 `uploadStoryboardImagesToCos(taskId, storyboardImagesJson)`：

```java
private String uploadStoryboardImagesToCos(String taskId, String storyboardImagesJson) {
    // 1. 解析 JSON 数组
    // 2. 遍历每张图，如果是 data:image 开头的 Base64 就上传 COS
    // 3. 替换为 COS URL
    // 4. 上传失败时保留原值（不丢数据）
    // 5. 返回替换后的 JSON
}
```

两个保存路径都在写库之前调用此方法：
- `saveStoryboardImageResultWithTransactionTemplate()` — 异步事务保存
- `saveStoryboardImageResult()` — 同步事务保存

**不需要批量迁移**——修复源头后，新数据直接存 COS URL，不会再有 Base64 进库。

### 变更影响

| 影响范围 | 说明 |
|----------|------|
| 数据库 | 新数据 `storyboardImages` 字段从 ~3-6MB Base64 变为 ~500 字节的 URL JSON，**大幅减小存储** |
| COS | 每次生成分镜图会多上传 6 张图片到 COS（本就应该上传） |
| 前端 | **无影响**——前端通过 URL 加载图片，COS URL 和 Base64 Data URI 都能被 `<img>` 标签识别 |
| 视频生成 | 后续用分镜图生成视频时，需要从 COS URL 下载图片（代码中已有 `downloadImageAsBase64` 方法处理） |

### 涉及文件

```
[已修改] service/StoryboardVideoService.java — 新增 uploadStoryboardImagesToCos()，
                                               两个保存方法在存库前调用
[已删除] migrateBase64ToCos() 批量迁移方法（不再需要）
[已修改] scheduler/TaskQueueScheduler.java   — 删除 migrateBase64ToCos 定时任务
```

---

## 问题七：task_queue 与 task_status 职责边界模糊

### 问题描述

`task_queue` 和 `task_status` 两张表字段高度相似（都有 taskId、username、taskType、status），开发者容易误认为是重复表可以合并。但实际上它们职责完全不同：

- `task_queue` — **任务调度引擎**：管理内存 BlockingQueue 的持久化，控制并发执行
- `task_status` — **外部 API 轮询**：存储 externalTaskId，跟踪外部 AI API 的返回状态

合并会破坏现有的调度和轮询逻辑。

### 解决方案

**不做代码结构变更**，仅在关键位置添加 Javadoc 注释明确职责边界：

- `TaskQueue.java` — 类级注释说明"任务调度与执行引擎的持久化层"
- `TaskStatus.java` — 类级注释说明"跟踪已提交到外部 AI API 的任务轮询状态"
- `TaskQueueService.java` — 类级注释说明调度逻辑和调用关系
- `TaskStatusPollingService.java` — 类级注释说明轮询逻辑和级联更新路径

### 变更影响

| 影响范围 | 说明 |
|----------|------|
| 数据库 | **无影响** |
| 运行时 | **无影响**——仅添加注释 |
| 开发者 | 阅读代码时能快速理解两张表的区别，避免误合并 |

### 涉及文件

```
[已修改] model/TaskQueue.java                      — 添加 Javadoc
[已修改] model/TaskStatus.java                     — 添加 Javadoc
[已修改] service/TaskQueueService.java             — 添加 Javadoc
[已修改] service/TaskStatusPollingService.java     — 添加 Javadoc
```

---

## 部署注意事项

### Flyway 迁移

- 如果数据库是**全新部署**：Flyway 会自动按版本号顺序执行所有迁移脚本，包括 V16（删除冗余表）
- 如果数据库**已有数据**：
  - `V16__Drop_Redundant_Archive_Tables.sql` 会删除 `completed_tasks_archive` 和 `failed_tasks_cleanup_log`，其中数据会丢失
  - 原始任务数据仍保留在 `task_queue` 和 `user_error_log` 中，不受影响
  - 如果 Flyway 的 `flyway_schema_history` 中已有旧版本号的记录（V2、V3、V7），需要手动清理或设置 `flyway.baseline-on-migrate=true`

### COS 配置

- 问题六的修复依赖 COS 服务开启（`cosService.isEnabled() == true`）
- 如果 COS 未配置或不可用，代码会**回退保留 Base64**，不会导致数据丢失或报错

### 历史 Base64 数据

- 修复后新生成的分镜图会直接存 COS URL
- 已存在的历史 Base64 数据不会自动清理
- 如需清理历史数据，可手动执行一次性 SQL 脚本或编写临时迁移任务