3.7 KiB
3.7 KiB
连环画多图生成与历史预览经验
更新日期：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 - 当前页当前图作为初始索引
- 标题里标注页码，必要时标注同页第几张图
推荐实现模式
- 类型层新增
ComicPageImageVariant，不要复用导出 source 类型。 - 工具层提供
getComicPageImageVariants、appendComicPageImageVariants、selectComicPageImageVariant。 - 生成层把
count和taskIds作为一组处理，统一等待、统一取消、统一写回。 - UI 层主图展示当前选中图，缩略图区展示本页全部历史图。
- 存储层统一过滤大图数据，避免持久化压力。
- 测试覆盖工具函数和 task-sync，确保旧单图记录、多图任务、data URL 清理都能工作。
复现路径
- 在连环画生成页选择多页。
- 把“每页生成数量”设为 2 张或更多。
- 点击生成。
- 如果只读取单个
taskId，页面只会展示第一张图；如果同步逻辑只认page.taskId，后续任务完成也不会进入历史。
一句话
多图生成不是“单图字段加数组”这么简单；核心是把任务集合、当前选择、历史候选、后台同步和存储清理当成一条完整链路处理。