状态管理矩阵

为什么要有这份文档

这个项目刻意保留了多种状态管理方式用于展示和演进。 这对学习有价值，但也意味着协作者和 agent 很容易“按自己的偏好”误改边界。 这份文档的目的是停止猜测。

当前分布

Redux

• 主要承担应用级共享状态，例如登录态和用户信息
• 根 store 在 lib/app.dart 中创建
• reducer 和 middleware 位于 lib/redux/

Riverpod

• 用于部分全局共享状态，例如灰度模式、语言、主题
• 也用于部分功能模块，例如趋势页相关数据流
• 根容器同样在 lib/app.dart 中接入

Provider

• 仍存在于部分功能模块，尤其是较早的页面链路
• 典型例子是仓库详情页的跨 tab 状态共享

Signals

• 用于局部页面状态
• 当前通知页和部分文件列表相关页面会使用

工作策略

• 不要再引入第五种状态管理模式
• 无关任务里不要顺手把模块从一种方案迁到另一种方案
• 新状态优先跟随“最近的既有模式”，而不是个人习惯
• 如果一个需求同时涉及全局状态和页面局部状态，要明确边界，避免双份真相

评审时必问的问题

1. 这份状态是页面局部、功能局部，还是应用全局？
2. 目标模块原来已经在用哪种状态方案？
3. 这次改动是否真的需要碰 lib/app.dart？
4. 会不会让 Redux、Riverpod、Provider 或 Signals 之间出现重复状态源？

后续方向

如果将来要收敛状态管理种类，应先在 docs/06-decisions/ 记录决策，再开始迁移。 不要让“慢慢改着改着就变了”成为默认路径。