Initial TrueGrowth source import

docs/COMIC_CREATOR_MULTI_IMAGE_HISTORY_LESSONS.md

@@ -0,0 +1,93 @@
+# 连环画多图生成与历史预览经验
+
+更新日期：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`，后续任务完成也不会进入历史。
+
+## 一句话
+
+多图生成不是“单图字段加数组”这么简单；核心是把任务集合、当前选择、历史候选、后台同步和存储清理当成一条完整链路处理。