Initial TrueGrowth source import

docs/MULTI_IMAGE_HISTORY_STARRED_CONCURRENCY_LESSONS.md

@@ -0,0 +1,113 @@
+# 多图生成历史收藏入口与 AI 并发经验
+
+更新日期：2026-04-30
+
+## 背景
+
+用户反馈“工具中，所有历史和收藏的 icon，视觉可以加强一点，现在用户没留意到”，并要求把大模型调用最大并发统一放宽到 20。
+
+这次问题横跨两个容易混淆的区域：
+
+- AI 输入栏里的提示词历史三点入口。
+- 多图生成、视频/音乐/MV 工具窗口顶部共享的历史/收藏入口。
+
+真正要改的是第二类，也就是 `WorkflowNavBar` 渲染出的右上角历史和收藏按钮。
+
+## 这次暴露的问题
+
+### 1. 看到“历史/收藏”要先定位界面上下文
+
+同样叫“历史”，项目里至少有提示词历史、生成历史、工作流历史、工具窗口历史。
+
+经验规则：
+
+- 用户给了截图时，以截图所在组件为准，不要只按关键词搜索结果猜入口。
+- 先确认组件层级和复用范围，再动视觉。
+- 如果入口来自共享组件，优先改共享组件和对应共享样式，而不是只改某个业务页。
+
+这次正确链路是：
+
+```text
+ComicCreator -> WorkflowNavBar -> .va-nav-actions/.va-nav-btn
+```
+
+而不是：
+
+```text
+AIInputBar -> PromptHistoryPopover -> MoreHorizontal
+```
+
+### 2. 共享导航按钮要用明确图标和常态可见反馈
+
+原来的 `📋 2`、`⭐` 图标偏轻，且按钮几乎无常态容器，用户在窗口工具区里不容易注意到。
+
+更稳的 UI 规则：
+
+- 用 lucide 图标替代 emoji，保证尺寸、线宽和主题色一致。
+- 常态保留轻边框、弱背景和计数胶囊，不要只在 hover 时可见。
+- 有历史或收藏数量时加 `has-count` 高亮，让“这里有内容”成为第一眼信号。
+- 收藏状态要让图标本身填充色变化，不能只靠数字变化。
+
+### 3. 历史列表里的收藏按钮也要同步加强
+
+入口变醒目后，进入历史页的收藏操作也应该保持同一套视觉语言。
+
+经验规则：
+
+- 历史入口、收藏入口、历史列表收藏按钮要使用一致的星形图标和品牌色。
+- 删除按钮保留低调常态，只在 hover 时转错误色，避免和收藏抢注意力。
+- 历史列表按钮需要 `aria-label/title`，图标按钮不能只靠视觉表达含义。
+
+### 4. AI 并发和高内存并发要分开治理
+
+“大模型调用最大并发到 20”不等于所有 `concurrency` 都改成 20。
+
+应统一到 20 的是 AI/大模型生成调用：
+
+- 主任务执行器 pending/resume 执行上限。
+- 多图生成并行页生成上限。
+- PPT 批量页图生成上限。
+- 模型测试工具的可输入最大并发。
+
+不应跟随调整的是高内存或非 AI 路径：
+
+- ZIP/Blob 批量下载。
+- 漫画导出抓图写 ZIP。
+- Service Worker 静态资源预缓存。
+- GitHub/Gist 分片同步。
+
+这些路径会放大内存、网络或第三方限流风险，应该保留独立低并发。
+
+### 5. 并发上限要抽成语义常量
+
+多个业务点都写 `5` 或 `3` 时，后续很容易漏改。
+
+经验规则：
+
+- 抽出 `AI_GENERATION_CONCURRENCY_LIMIT = 20`。
+- 只有“AI/model generation calls”引用该常量。
+- 常量注释要明确非 AI Blob/ZIP/cache/GitHub 路径不复用它。
+- 测试不要断言旧魔法数，断言行为：串行为 1，并行不超过选中数量和 AI 上限。
+
+### 6. 跑测试要用包内 Vitest 配置
+
+根目录直接跑 `vitest` 时，React/jsdom 和 alias 可能与包内配置不一致，容易出现误报。
+
+经验规则：
+
+- 对 drawnix 组件测试优先在 `packages/drawnix` 下使用 `--config ./vitest.config.ts`。
+- UI 小改优先跑目标测试和 `nx run drawnix:typecheck`，无必要不全量构建。
+- 如果旧测试失败，要区分是否命中本次改动路径，避免被无关 mock 问题牵走。
+
+## 回归检查清单
+
+- 多图生成窗口右上角历史/收藏入口常态是否明显？
+- 有历史数量时，历史按钮是否高亮并显示计数？
+- 有收藏数量时，收藏星标是否填充并高亮？
+- 进入历史页后，收藏/取消收藏按钮是否同样清晰？
+- 主任务执行器、漫画并行、PPT 并行是否都引用统一 AI 并发常量？
+- 下载、ZIP、SW 预缓存、GitHub 同步是否仍保留独立低并发？
+
+## 一句话
+
+同名 UI 入口先按截图定位真实组件；同名并发先按资源类型分层治理。视觉强化改用户看见的共享入口，并发放宽只给 AI 调用链路。