# 前端引入 Pinia 方案（已完成） ## 当前状态 当前方案涉及的核心改造已经完成，现状如下： - `Pinia` 已正式接入项目 - `auth / appearance / menu / notification` 四个 store 已完成落地 - “建议进入 Pinia”的状态范围已全部进入对应 store - 认证、外观、菜单、通知、租户切换上下文均已由 store 统一收口 - 页面侧对认证与外观状态的消费已改为直接读取 store - 原 `utils/auth.ts` 与 `utils/appearance.ts` 兼容层已完成清理 - 前端构建验证已通过 ## 1. 背景 当前前端技术栈为 `Vue 3 + Vue Router + Element Plus + Axios`，尚未引入 `Pinia`。从现有代码看，跨页面共享状态主要通过以下方式维护： - `frontend/src/utils/auth.ts` - 使用 `localStorage` 持久化 token、用户信息、租户信息、权限、界面偏好。 - `frontend/src/utils/appearance.ts` - 使用 `reactive` 单例维护主题和密度状态。 - `frontend/src/views/layout/AppLayout.vue` - 集中维护菜单、租户切换、未读站内信、WebSocket 连接、跨标签页同步等全局状态。 - `window.dispatchEvent` / `window.addEventListener` - 通过 `auth:token-updated`、`in-app-unread-changed`、`storage` 事件做组件间和多 Tab 同步。 该方案在当前阶段可以工作，但随着前端功能继续增加，已经出现以下趋势： - 全局状态来源分散，排查问题时需要同时阅读 `utils`、布局组件和页面组件。 - 业务状态与持久化逻辑、事件广播逻辑耦合较深。 - 租户切换、登录态变更、菜单刷新、通知未读数刷新等链路缺少统一的 store 边界。 - 后续若继续增加全局缓存，会放大“旧租户状态残留”和“页面使用过期缓存”的风险。 结论：建议引入 `Pinia`，但采用渐进式迁移，不进行一次性重构。 ## 2. 目标 本方案目标如下： - 建立统一的前端全局状态管理入口。 - 将认证、租户、菜单、外观、通知等跨页面共享状态从工具函数和布局组件中抽离。 - 降低租户切换、重新登录、刷新 token、多标签页同步等复杂链路的维护成本。 - 为后续增加全局缓存、数据预取、业务上下文复用提供稳定边界。 ## 3. 非目标 本次方案不包含以下内容： - 不将所有页面内 `ref/reactive` 状态迁入 Pinia。 - 不将表单输入、弹窗开关、分页条件等纯页面局部状态全局化。 - 不在首轮引入额外状态管理插件或复杂中间件。 - 不在首轮重构全部页面的接口调用方式。 ## 4. 是否建议引入 建议引入，原因如下： - 项目已经存在明确的全局共享状态。 - 当前共享状态分散在 `localStorage`、响应式单例、布局组件和浏览器事件之间。 - 多租户切换已经是核心链路，继续扩展时需要稳定的 store 清理机制。 - 后续若继续做全局搜索、通知中心、更多个性化设置、页面缓存，Pinia 会显著降低复杂度。 不建议一次性全面迁移，原因如下： - 大部分业务页面仍以单页局部状态为主，强行迁移收益不高。 - 一次性改动风险大，容易引入登录态、权限态和租户态回归问题。 ## 5. 适合进入 Pinia 的状态范围（已完成） 已完成进入 Pinia： - 认证态 - token - 当前用户 - 当前租户 - scope - roles - permissions - 外观态 - themeMode - density - 初始化状态 - 菜单与布局态 - 当前菜单列表 - 当前租户 logo - 是否正在切换租户 - 通知态 - 未读数 - 通知列表 - 轮询和 WebSocket 生命周期状态 - 租户切换上下文 - 当前租户 ID - 切换后是否需要清理的业务缓存版本号 不建议进入 Pinia： - 单页面查询条件 - 表单内容 - 弹窗显隐 - 临时上传进度 - 仅在单个页面使用的表格数据 ## 6. 推荐目录结构 建议在 `frontend/src` 下新增如下目录： ```text stores/ index.ts auth.ts appearance.ts menu.ts notification.ts ``` 职责建议如下： - `stores/index.ts` - 统一创建 `pinia` 实例。 - `stores/auth.ts` - 管理登录态、用户信息、权限、租户信息、登录态广播、登出清理。 - `stores/appearance.ts` - 管理主题、密度、文档样式同步。 - `stores/menu.ts` - 管理租户端和平台端菜单加载、菜单刷新。 - `stores/notification.ts` - 管理未读数、通知列表、轮询、WebSocket 连接和重连。 ## 7. 设计原则 ### 7.1 store 负责状态和动作，工具函数只保留纯函数能力 例如： - `utils/auth.ts` - 逐步收缩为解析、序列化、兼容读取等纯工具。 - 登录保存、登出清理、权限变更广播 - 迁移到 `authStore`。 ### 7.2 持久化与内存态分层 - `Pinia` 中维护运行时状态。 - `localStorage` 仅作为持久化载体，不再作为主要读取入口。 - 页面和组件默认从 store 读取，不直接散落读取 `localStorage`。 ### 7.3 租户切换必须具备显式清理机制 租户切换后，至少要做到： - 刷新 `authStore` - 刷新 `menuStore` - 刷新 `notificationStore` - 清空或失效租户相关业务缓存 - 触发页面重新拉数或重建 建议在 `authStore` 中增加： - `authVersion` - `tenantContextVersion` 通过版本号驱动需要重新加载的数据，而不是只依赖浏览器事件和页面手工处理。 ### 7.4 不引入“超大 store” 避免把全部全局状态堆进一个 `appStore`。按领域拆分，降低耦合。 ## 8. 分阶段实施方案 ### 阶段 1：基础接入（已完成） 目标： - 引入 `pinia` - 完成基础目录和初始化接入 - 不改变现有业务行为 实施内容： - 安装 `pinia` - 新增 `frontend/src/stores/index.ts` - 在 `frontend/src/main.ts` 中接入 `app.use(pinia)` - 新增空的 `authStore`、`appearanceStore`、`menuStore`、`notificationStore` 产出： - 项目具备 store 基础设施 - 不触发业务逻辑迁移 ### 阶段 2：迁移认证与外观（已完成） 目标： - 优先迁移最稳定、最全局的状态 实施内容： - 将 `utils/auth.ts` 中的状态读写入口迁移到 `authStore` - 将 `utils/appearance.ts` 中的响应式单例迁移到 `appearanceStore` - 保留 `localStorage` 持久化，但统一由 store 写入 - 页面不再直接读取 `localStorage` 获取认证信息 涉及文件重点： - `frontend/src/utils/auth.ts` - `frontend/src/utils/appearance.ts` - `frontend/src/main.ts` - `frontend/src/App.vue` - `frontend/src/router/index.ts` - `frontend/src/views/modules/ProfilePage.vue` 验收标准： - 登录、刷新、退出登录功能不回归 - 主题和密度切换行为不回归 - 多 Tab 基本同步仍然可用 ### 阶段 3：迁移菜单与租户切换链路（已完成） 目标： - 将当前集中在 `AppLayout.vue` 的布局级共享状态抽出 实施内容： - 将菜单加载迁移到 `menuStore` - 将租户切换迁移到 `authStore` 或专门的 `tenant context` action - 将租户 Logo、租户切换状态从布局组件迁移到 store - 明确切租户后的 store 级缓存清理动作 涉及文件重点： - `frontend/src/views/layout/AppLayout.vue` - `frontend/src/api/modules.ts` - `frontend/src/router/index.ts` 验收标准： - 租户切换后菜单正确刷新 - 原路由保留逻辑仍然成立 - 不出现旧租户菜单、旧租户 logo、旧租户权限残留 ### 阶段 4：迁移通知中心与 WebSocket 生命周期（已完成） 目标： - 将布局中的通知状态与连接管理从视图层抽离 实施内容： - 将未读数、通知列表迁移到 `notificationStore` - 将轮询、WebSocket 建连、重连、关闭逻辑迁移到 store action - 保留 `AppLayout.vue` 作为纯展示和交互入口 验收标准： - 未读数更新正常 - 标记已读/全部已读正常 - 页面切换不导致重复连接 - 登出或切租户后连接被正确关闭 ## 9. 与现有代码的映射关系（已完成） 建议按如下方式收口： - 当前 `frontend/src/utils/auth.ts` - 收口到 `authStore` - 当前 `frontend/src/utils/appearance.ts` - 收口到 `appearanceStore` - 当前 `frontend/src/views/layout/AppLayout.vue` - 收口到 `menuStore + notificationStore + authStore` - 当前直接调用 `hasPermission()` 的页面 - 后续逐步改为从 `authStore` 暴露的 getter 或 helper 读取 ## 10. 持久化策略建议 首轮建议不引入额外持久化插件，采用手工持久化，原因如下： - 当前状态字段较少，手工维护可控。 - 可以保留现有 `localStorage` 键，降低兼容成本。 - 可以在迁移期同时兼容旧逻辑，便于灰度替换。 后续如 store 数量和持久化字段继续增多，再评估是否引入持久化插件。 ## 11. 风险与应对 ### 风险 1：登录态回归 表现： - 登录后页面未刷新权限 - token 刷新后页面仍使用旧状态 应对： - 认证迁移阶段保留兼容读取逻辑 - 为登录、登出、refreshAuth、tenant switch 增加回归测试清单 ### 风险 2：租户切换后残留旧缓存 表现： - 菜单、通知、页面数据、权限按钮残留旧租户信息 应对： - 引入 `tenantContextVersion` - 在切换租户 action 中显式调用各 store 的 `reset` 或 `reload` ### 风险 3：组件和 store 职责混乱 表现： - 视图层继续直接读写 `localStorage` - store 同时处理过多页面局部逻辑 应对： - 代码评审时明确约束 - 新增共享状态优先进入 store - 页面局部状态继续留在页面组件 ## 12. 预估改造顺序 推荐顺序： 1. `pinia` 基础接入 2. `appearanceStore` 3. `authStore` 4. `menuStore` 5. `notificationStore` 6. 页面侧逐步替换直接读取 `localStorage` 的逻辑 这样做的原因： - `appearance` 和 `auth` 边界最清晰，迁移成本最低。 - `menu` 和 `notification` 与租户切换耦合更深，适合第二阶段处理。 - 页面层替换可以跟随 store 稳定后分批推进。 ## 13. 验收结果（已完成） 完成首轮引入后，应满足以下标准： - 项目已正式接入 `Pinia` - 认证态、外观态不再以分散的 `localStorage` 读取为主入口 - 租户切换存在明确的 store 级清理机制 - 菜单和通知逻辑从 `AppLayout.vue` 中部分或全部抽离 - 现有登录、登出、刷新 token、切换租户、多 Tab 同步能力不回退 ## 14. 最终状态（已完成） 建议采用“引入基础设施 + 迁移最核心全局状态 + 保留页面局部状态”的方式推进。 具体建议如下： - 建议引入 `Pinia` - 不建议一次性重构所有页面 - 第一批只迁移 `auth / appearance / menu / notification` - 明确把“租户切换后的 store 清理机制”作为本次方案的硬性要求 该方案执行后，前端状态管理会从“工具函数 + 布局组件 + 浏览器事件”的分散模式，过渡到“store 统一收口、页面按需消费”的结构，更适合当前项目继续演进。