Initial TrueGrowth source import

docs/PPT_IMAGE_HISTORY_LESSONS.md

@@ -0,0 +1,89 @@
+# PPT 生图历史交互经验总结
+
+更新日期：2026-04-26
+
+## 背景
+
+PPT 页面现在主要由整页图片构成，Frame 负责承载、预览、重生成和切换历史图片。
+这类交互的关键不是“能记录历史”，而是让用户明确知道：
+
+- 哪张图是当前正在展示的 PPT 页面
+- 每张历史图是什么时间生成的
+- hover 时能快速判断大图效果
+
+## 这次暴露的问题
+
+### 1. 历史时间不应使用菜单展示时间
+
+历史列表里的时间如果使用“写入历史记录的时间”或“切换历史图的时间”，会误导用户。
+
+正确语义应该是：
+
+- 图片什么时候由 AI 生成，就展示什么时候
+- 用户之后切换历史图，不应该刷新这张图的生成时间
+
+一句话：
+**生图历史的时间属于图片产物，不属于当前选择动作。**
+
+### 2. 当前图必须在历史列表里显式激活
+
+只靠缩略图和顺序无法让用户判断当前 PPT 页正在用哪张图，尤其是一次生成多张相似图片时。
+
+更稳的做法是：
+
+- 用 `elementId` 优先判断当前图
+- `elementId` 不存在或已失效时，用 `imageUrl` 兜底
+- 当前项使用激活样式和“当前”标记
+
+一句话：
+**历史列表需要表达“当前状态”，不能只表达“候选集合”。**
+
+### 3. hover 大图应优先规避底部遮挡
+
+历史菜单通常靠近页面下方，预览图如果向右下展开，很容易被视口底部截断。
+
+当前更稳的默认定位是：
+
+- 在历史 item 右侧展示
+- 以 item 底部为基准向上展开
+- 后续如果需要再做完整视口碰撞检测
+
+一句话：
+**没有碰撞检测前，右上展开比右下展开更稳。**
+
+## 代码层面固化的规则
+
+### 1. 历史记录写入时带上生成时间
+
+从任务队列写入 PPT 生图历史时，应优先使用：
+
+1. `task.completedAt`
+2. `task.updatedAt`
+3. `task.createdAt`
+4. `Date.now()` 兜底
+
+这样能让历史记录尽量接近图片真实生成完成时间。
+
+### 2. 切换历史图时保留原历史时间
+
+用户从历史菜单切回某张图时，需要把该历史项的 `createdAt` 继续传回 PPT 元数据更新流程，避免被 `Date.now()` 覆盖。
+
+切换历史图只是改变当前展示图，不应该改变历史列表顺序。历史项如果已存在，应原位更新 `elementId` / `prompt` 等轻量信息，而不是重新插到第一位。
+
+### 3. 批量生成时每张图都进入历史
+
+一次生成多张图时：
+
+- 最后一张作为当前展示图
+- 所有结果都进入该 Frame 的 `slideImageHistory`
+- 历史项保留各自所属任务的生成完成时间
+- 新生成结果按生成顺序排在历史列表后面，不反向插入到最前
+
+### 4. UI 激活态要跟数据判断一致
+
+历史 item 的激活态判断应复用当前 PPT 图的真实关联关系：
+
+- 优先比较 `slideImageElementId`
+- 再比较 `slideImageUrl`
+
+避免 UI 激活态和实际画布内容不一致。