# 连环画多图生成与历史预览经验

更新日期：2026-04-30

## 背景

连环画生成页从“每页只生成 1 张图”升级为“每页可并发生成多张图，并在页面预览区保留历史结果”。
这类能力看起来只是加一个数量下拉框，实际会牵动任务队列、页面状态、任务同步、导出来源和存储清理。

## 这次暴露的问题

### 1. `count > 1` 不等于一个任务返回多张图

图片工具的 queue 模式在直接调用时会按 `count` 拆成多个任务，并通过 `data.taskIds` 返回。
如果调用方只读取 `taskId` 或第一个任务，剩余图片会生成完成但不会被页面消费。

经验规则：

- 创建任务后优先读取 `data.taskIds`
- 兼容 `data.taskId`、顶层 `taskId`、`task.id`
- 等待所有 task 完成后，把成功结果逐张写回页面历史
- 停止生成时要取消全部 active task，而不是只取消第一个

### 2. 当前图和历史图是两种状态

页面需要同时表达：

- 当前用于导出、预览主图的图片
- 本页历史生成过的所有候选图片

只保留 `imageUrl` 会丢失历史；只保留历史数组又会影响旧记录和导出兼容。

更稳的结构是：

- 保留 `imageUrl/imageMimeType/imageGeneratedAt` 作为当前选中图
- 新增 `imageVariants` 保存历史候选图
- 新生成的多张图 append 到历史
- 默认把最新成功图设为当前图
- 点击缩略图只切换当前图，不删除历史

### 3. 任务同步路径也要兼容多任务

页面内主动等待任务完成是一条路径，后台任务同步又是另一条路径。
如果 `task-sync` 仍只判断 `page.taskId === task.id`，多图中的第二张及之后无法同步回记录。

经验规则：

- 页面记录同时保存 `taskId` 和 `taskIds`
- 同步时把 `taskId + taskIds` 合并成集合判断
- 同步成功也走同一套 append variant helper
- 避免页面主动等待和后台同步写出两套不一致的数据结构

### 4. 历史图不能保存大体积 `data:` URL

连环画记录会进本地持久化，历史图如果保存 base64，会快速放大存储体积，也可能造成内存和序列化压力。

经验规则：

- `imageVariants` 只保存可重放 URL、mime、生成时间和 taskId
- 存储前过滤 `data:` 图片
- 旧的 `imageUrl` 如果是 `data:` 也要移除
- 清理逻辑必须同时覆盖当前图和历史图

### 5. 预览队列应覆盖所有已生成图片

用户点击当前图时，预期是在整个生成结果里浏览，而不是只能看当前页当前图。

经验规则：

- 预览队列按页码排序
- 每页展开所有 `imageVariants`
- 当前页当前图作为初始索引
- 标题里标注页码，必要时标注同页第几张图

## 推荐实现模式

1. 类型层新增 `ComicPageImageVariant`，不要复用导出 source 类型。
2. 工具层提供 `getComicPageImageVariants`、`appendComicPageImageVariants`、`selectComicPageImageVariant`。
3. 生成层把 `count` 和 `taskIds` 作为一组处理，统一等待、统一取消、统一写回。
4. UI 层主图展示当前选中图，缩略图区展示本页全部历史图。
5. 存储层统一过滤大图数据，避免持久化压力。
6. 测试覆盖工具函数和 task-sync，确保旧单图记录、多图任务、data URL 清理都能工作。

## 复现路径

1. 在连环画生成页选择多页。
2. 把“每页生成数量”设为 2 张或更多。
3. 点击生成。
4. 如果只读取单个 `taskId`，页面只会展示第一张图；如果同步逻辑只认 `page.taskId`，后续任务完成也不会进入历史。

## 一句话

多图生成不是“单图字段加数组”这么简单；核心是把任务集合、当前选择、历史候选、后台同步和存储清理当成一条完整链路处理。