page-flow-cleanup-audit

页面流程清理审计

原则

从第一性原则开始：确认页面目的、它依赖的事实，以及必须保持为真的业务不变量。不要从机械去重或删除 optional check 开始。

好的清理会移除多余 source of truth 和无意义分支，同时保留真实的 loading、empty、error、permission 和 lifecycle 状态。

当清理可能改变用户可见行为时使用本技能。它用于区分无意义防御代码和真实的生命周期、权限、错误、空态。

不要把注释当作清理目标。只有注释错误、因代码变更过期，或描述了已删除行为时才更新。

不要在清理一个组件或 helper 后停止。对于用户请求的页面或流程，必须追踪完整流程边界和影响面后再报告完成。

本技能属于三个清理技能之一：

• 用 page-flow-cleanup-audit 处理用户可见流程、状态所有权和业务不变量。
• 用 necessary-code-audit 判断 wrapper、兼容、fallback、默认值和防御代码是否必要。
• 用 unused-code-audit 证明删除的 helper、export 和文件是否仍有消费者。

工作流

1. 定义流程边界

• 命名页面/文件/功能及其用户可见目的。
• 识别入口：用户入口、主组件或 handler、hook、query helper、mutation helper、store、dialog 和外部消费者。
• 区分主流程和相邻可复用业务面。不要因为 UI 看起来相似就合并。
• 如果请求包含“无需向后兼容”或“删除防御代码”，只应用到兼容层或不可能状态 guard，不应用到真实可空业务状态。
• 建立影响面图：route、共享包、store、query key、API client、analytics event、native/web 消费者、测试/脚本，以及被流程触达的下游 app/package。

深度要求：编辑前检查边界内每个文件；每个被修改的共享 helper/type/store/query，都要检查代表性下游消费者。不要依赖单个 grep 结果或一个明显调用点。

2. 找到 Source Of Truth

按以下顺序追踪状态：

1. Server/API contract。
2. Query key 和 query function。
3. Mutation 后的 query cache invalidation。
4. Local store 或 component state。
5. 派生计算。
6. UI adapter 和 presentation。

危险信号：

• 多个 query 获取同一个业务事实。
• store 和 React Query 同时宣称拥有同一个远程状态。
• mutation 在多个组件里直接 invalidate 原始 key。
• “轻量 query” 复制同一个 API 来源，制造第二份 cache。
• component-local count/status 来自过期或独立 source。

推荐形态：

• 一个 query helper 拥有一个远程事实。
• mutation 调用一个共享 invalidation helper。
• 除非后端有真实 count endpoint，否则 count 和 label 从 canonical query 派生。
• response type 表达边界后的保证，而不是在 UI 增加 guard。

3. 分类重复逻辑

只有确定性且业务等价的逻辑才抽取。

适合抽取：

• 产品/分类分组。
• 过滤和排序。
• 时间序列或组合收益派生。
• 资格判断。
• Query-key projection helper。
• 类型层面的请求/响应边界 helper。

不要抽取：

• 布局、密度、折叠行为、移动端/桌面端交互、toolbar 组合或 route-specific loading 决策。
• 看起来相似但上下文或用户流程不同的 UI 代码。
• 只隐藏两个调用点、却不减少业务复杂度的组件 wrapper。

4. 分类防御代码

满足以下情况时可删除为无意义：

• prop 或边界类型已经保证值存在。
• 布尔参数总是作为常量传入。
• helper 只包装空对象或显然的字面量。
• fallback 只服务旧数据格式，且用户明确不再兼容。
• as any 隐藏了可通过收紧边界解决的类型问题。
• 可选链违背 required prop，只会弱化错误。

满足以下情况时必须保留：

• 领域类型确实可选，例如可选 expiration、可选 strategy item、缺失 profile data、未选中 row。
• 分支代表真实 loading、empty、error、permission 或 access 状态。
• fallback 是有意的用户体验降级，例如截图分享失败后退回链接分享。
• 值来自外部输入，缺失仍是合法业务行为。