# 多图生成工具箱排序与埋点经验

## 背景

这次调整同时涉及工具箱展示顺序和多图生成工具的行为观测：

- 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 失败，先区分是否为既有问题，并在提交说明中保留验证结论。