用途
recollect-post-migration-cleanup 是 Recollect 项目在前端从旧版 Pages Router 迁移到 v2 App Router 路由后使用的清理技能。它处理前端调用方的迁移收尾工作，属于 Phase 13+ 的工作，要求所有 v2 API 路由已经存在后才能运行。
该技能的清理范围仅包括：前端调用方、mutation hooks、遗留辅助函数和遗留类型。它不负责创建 API 路由（该部分由 recollect-api-migrator 代理处理）。
主要能力
技能按路由逐个执行清理流程，每一步都旨在防止特定类型的死代码或断链引用：
-
更新 Mutation Hook：从 v2 路由文件导入类型（而非 apiTypes.ts），并将 postApi 指向 v2 URL。如果 v2 路由的 payload/response 结构不同，还需同步更新 hook 的乐观更新器和缓存结构。
-
更新所有前端使用点：通过 ast-grep 搜索所有导入旧 hook 的文件，然后逐一更新：导入新 hook、调整解构返回值、按需更新 payload 构造。
-
从 supabaseCrudHelpers 移除遗留辅助函数：打开 src/async/supabaseCrudHelpers/index.ts 删除遗留函数，并移除因此不再使用的导入。
-
从 apiTypes.ts 移除遗留类型：删除遗留 payload/response 类型，类型现在统一存放在 v2 路由的 schema.ts 中，以保证类型的单一来源。
-
删除旧文件：使用 trash（绝不使用 rm）删除旧的 Pages Router 路由文件和旧的 mutation hook 文件。
-
验证：运行
pnpm lint:types（捕获断链导入、类型不匹配）和pnpm lint:knip（捕获孤立导出、未使用代码），修复问题后再标记该路由完成。
使用方式
技能提供了路由表，根据用户表述加载对应内容：
- “update hook for [route]” 或 “wire up v2 [route]” → 执行上述工作流
- “mutation hook template” 或 “how to structure hook” → 参考 references/mutation-hook-template.ts
- “where is [helper/type/constant]” → 参考 references/codebase-patterns.md
- “cache structure” 或 “query keys” → 参考 references/codebase-patterns.md
需要保留的错误处理模式
更新 hooks 时需保留 v2 路由中的错误处理模式：
- 重复检测（23505）：v2 路由返回
{ data: null, error: "Duplicate name" }，状态码 409。Hook 应在 onError 中处理或显示 toast。 - 授权（403）：v2 路由返回
{ data: null, error: "User is not the owner" }，状态码 403。Hook 应回滚乐观更新。 - 服务器错误（500）：由 v2 路由中的 Sentry 自动捕获。Hook 应显示通用错误 toast。
常见问题
- 未使用导入警告：删除遗留代码后 ESLint 会标记孤立导入，可运行
pnpm fix:prettier src/async/supabaseCrudHelpers/index.ts和pnpm fix:prettier src/types/apiTypes.ts。 - Knip 未使用导出警告：新类型尚未被消费时，需确保所有使用点从 v2 路由文件导入。
- 类型不匹配：如果 v2 响应结构与遗留不同（如新增可空字段、移除幻影字段），需相应更新 hook 的泛型参数和乐观更新器。
- 缓存键变更：如果 v2 路由提供的数据结构不同，React Query 缓存键可能需要更新，检查 src/utils/constants.ts 中的正确键常量。
成功标准
路由清理在满足以下所有条件时视为完成：mutation hook 从 v2 路由文件导入类型；mutation hook 的 postApi 指向 v2 URL；所有前端使用点已更新为新 hook；遗留辅助函数已从 supabaseCrudHelpers/index.ts 移除；遗留类型已从 apiTypes.ts 移除；旧 Pages Router 文件已用 trash 删除；旧 mutation hook 已用 trash 删除（如适用）；pnpm lint:types 通过；pnpm lint:knip 通过（无未使用导出）。
限制
该技能仅处理前端清理，不创建 API 路由。它要求所有 v2 API 路由已存在，未提供相关信息的收费、平台或价格等细节暂未提供。