ADR-0002 新增功能默认状态方案

状态

已采纳

日期

2026-03-10

背景

即使接受“当前存在多种状态管理方案”，团队和 agent 仍然需要一个面向新增功能的默认选择标准。 否则每个新页面都可能重新争论一次，或者由 AI 直接按训练偏好做决定。

决策

新增功能的状态管理默认按以下优先级选择：

1. 先看目标模块已有状态方案
2. 再看状态作用域是页面局部、功能局部还是应用全局
3. 只有在目标模块没有明确先例时，才使用下面的默认规则

默认规则

页面局部状态

优先选择：

• StatefulWidget 本地 state
• 若该模块已使用 Signals，则可继续使用 Signals

适用：

• 页码
• 筛选项
• 展开/收起
• 加载中标记
• 只影响当前页面的临时状态

功能局部共享状态

优先选择：

• 沿用目标功能目录已存在方案
• 如果目标功能是新建且预计会存在多 tab、多子视图共享，可优先考虑 Riverpod

适用：

• 复杂详情页
• 多 tab 共享数据
• 多个子 widget 共用一份异步加载状态

应用全局状态

优先选择：

• 复用现有 Redux 或 Riverpod 全局入口

适用：

• 登录态
• 当前用户核心身份信息
• 全局主题/语言/灰度模式

禁止事项

• 不要因为某个库“更先进”就替换当前功能模块状态方案
• 不要在一个新功能里同时引入两套新的状态来源
• 不要把页面局部交互状态直接抬升到全局

评审清单

新增功能提交前至少回答：

1. 这个状态为什么不放在页面本地？
2. 为什么不沿用目标模块既有模式？
3. 这个状态会影响几个页面或几个 tab？
4. 是否会和现有 Redux/Riverpod/Provider/Signals 形成重复状态源？

结果

这个 ADR 的目标不是追求形式统一，而是降低新增功能的状态决策成本，并减少 AI 改动的随机性。