Initial TrueGrowth source import

docs/MULTI_IMAGE_TOOLBOX_ANALYTICS_LESSONS.md

@@ -0,0 +1,72 @@
+# 多图生成工具箱排序与埋点经验
+
+## 背景
+
+这次调整同时涉及工具箱展示顺序和多图生成工具的行为观测：
+
+- AI 工具需要展示在内容工具前面。
+- 多图生成需要排在 AI 工具第一位。
+- 多图生成需要补齐 PV、UV、内部功能点击、生成与导出结果等埋点。
+
+## 经验
+
+### 工具箱排序要显式化
+
+工具箱原先依赖内置工具数组顺序和对象插入顺序展示分类。短期挪动数组能解决当前问题，但后续新增内容工具或自定义工具时，分类顺序容易再次漂移。
+
+更稳的做法是定义分类顺序常量：
+
+- AI 工具
+- 内容工具
+- 实用工具
+- 自定义工具
+
+分类按钮和分类列表都复用同一个排序函数，避免抽屉筛选区和工具列表出现顺序不一致。
+
+### 工具排序和分类排序分开处理
+
+“AI 工具在内容工具前面”是分类排序问题，“多图生成排在 AI 工具第一位”是同分类内工具顺序问题。两者不要混成一个魔法排序函数：
+
+- 分类顺序由 `TOOL_CATEGORY_ORDER` 控制。
+- 同分类内工具顺序仍由内置 manifest 数组控制。
+
+这样后续产品同学要调整 AI 工具内部顺序时，只需要移动 manifest 中的工具定义。
+
+### 多图生成埋点分层
+
+多图生成的埋点建议分成三层：
+
+- `multi_image_generation_page_view`：工具打开 PV。
+- `multi_image_generation_unique_view`：工具按日去重 UV，PostHog 仍可按 distinct user 做更精确聚合。
+- `multi_image_generation_action`：内部动作、点击、状态结果统一事件。
+
+点击类事件同时走 `trackUIInteraction()`，便于和现有 UI 行为看板放在一起分析。
+
+### 埋点字段只传低敏摘要
+
+多图生成包含 prompt、PDF、图片 URL、历史记录等敏感信息。埋点只应上传：
+
+- 数量：页数、已生成数、失败数、选中数、参考图数量。
+- 状态：start、success、failed、cancelled、skipped。
+- 配置：模型 ID、图片尺寸、生成模式、导出类型。
+- 摘要：prompt 长度、长度分桶、行数。
+
+不要上传原始 prompt、PDF 文件名、图片 URL、导出文件名或完整错误文本。
+
+### UV 本地去重要避免污染
+
+本地按日去重 UV 写入 localStorage 时，应先确认 analytics 可用。否则本地开发或 PostHog 未初始化时会提前写入去重标记，导致正式初始化后当天 UV 被误跳过。
+
+### 提交边界要检查未跟踪文件
+
+本次工具依赖 `comic-creator` 相关未跟踪文件。提交前要确认：
+
+- 不只提交 manifest 中的入口引用，否则提交后的树会缺少工具 ID、registry loader 或组件实现。
+- 不把无关的大量工作区改动混入提交。
+- 对未跟踪的新功能目录，按功能完整性选择最小必要文件集合。
+
+## 验证建议
+
+- 低成本必跑：`pnpm nx typecheck drawnix --skip-nx-cache`。
+- 定向检查：对本次改动文件跑 `pnpm exec eslint ...`。
+- 如果整包 lint 失败，先区分是否为既有问题，并在提交说明中保留验证结论。