@pubinfo/core 2.1.0 → 2.1.2

package/src/built-in/pinia-plugin/plugins/persistedstate/README.md

@@ -0,0 +1,551 @@
+# Pinia 持久化状态插件
+
+这是一个功能强大的 Pinia 插件，提供状态持久化、跨标签页同步以及自定义 Hook 扩展能力。
+
+## 特性
+
+- ✅ **自动持久化**：自动将 Pinia store 的状态保存到浏览器存储
+- 🔄 **跨标签页同步**：多个标签页之间实时同步状态变化
+- ↔️ **双向联动**：即使直接操作 `localStorage` 也能反向刷新 Pinia
+- 🎯 **选择性持久化**：支持白名单（pick）和黑名单（omit）过滤
+- 🔧 **灵活配置**：支持自定义序列化器、存储实例和键名
+- 🪝 **生命周期钩子**：提供 beforeHydrate 和 afterHydrate 钩子
+- 🧩 **Hook 扩展**：`pinia:persist:*` 钩子可统一处理加解密等自定义逻辑
+- 🔒 **类型安全**：完整的 TypeScript 类型支持
+- 🌐 **SSR 友好**：在服务端渲染环境中安全运行
+
+## 安装
+
+该插件已集成在 pubinfo 框架中，无需单独安装。
+
+## 快速开始
+
+### 1. 全局配置
+
+在 `persist.ts` 中配置默认选项：
+
+```typescript
+import { createPersistedStateOptions } from './persistedstate';
+
+export function createPersistedStateOptions(): SyncedPersistedStateOptions {
+  return {
+    storage: window.localStorage, // 存储实例
+    key: id => `_${id}`, // 键名生成函数
+    serializer: customSerializer(), // 自定义序列化器
+    storageArea: 'local', // 存储区域
+  };
+}
+```
+
+### 2. 在 Store 中启用持久化
+
+#### 2.1 Options API 风格
+
+```typescript
+import { defineStore } from 'pinia';
+
+export const useUserStore = defineStore('user', {
+  state: () => ({
+    name: '',
+    age: 0,
+    token: '',
+  }),
+  // 启用持久化
+  persist: true,
+});
+```
+
+#### 2.2 Setup 函数风格
+
+```typescript
+import { defineStore } from 'pinia';
+import { ref } from 'vue';
+
+export const useUserStore = defineStore('user', () => {
+  const name = ref('');
+  const age = ref(0);
+  const token = ref('');
+
+  return {
+    name,
+    age,
+    token,
+  };
+}, {
+  // 启用持久化（作为第三个参数）
+  persist: true,
+});
+```
+
+#### 2.3 自定义配置（Options API）
+
+```typescript
+export const useUserStore = defineStore('user', {
+  state: () => ({
+    name: '',
+    age: 0,
+    token: '',
+    tempData: null,
+  }),
+  persist: {
+    // 自定义存储键名
+    key: 'my-user-store',
+
+    // 只持久化指定字段（白名单）
+    pick: ['name', 'token'],
+
+    // 排除指定字段（黑名单）
+    // omit: ['tempData'],
+
+    // 自定义存储实例
+    storage: window.sessionStorage,
+
+    // 开启调试模式
+    debug: true,
+
+    // 生命周期钩子
+    beforeHydrate: (context) => {
+      console.log('恢复前', context.store.$id);
+    },
+    afterHydrate: (context) => {
+      console.log('恢复后', context.store.$state);
+    },
+  },
+});
+```
+
+#### 2.4 自定义配置（Setup 函数）
+
+```typescript
+export const useUserStore = defineStore('user', () => {
+  const name = ref('');
+  const age = ref(0);
+  const token = ref('');
+  const tempData = ref(null);
+
+  return {
+    name,
+    age,
+    token,
+    tempData,
+  };
+}, {
+  persist: {
+    // 自定义存储键名
+    key: 'my-user-store',
+
+    // 只持久化指定字段（白名单）
+    pick: ['name', 'token'],
+
+    // 自定义存储实例
+    storage: window.sessionStorage,
+
+    // 开启调试模式
+    debug: true,
+
+    // 生命周期钩子
+    beforeHydrate: (context) => {
+      console.log('恢复前', context.store.$id);
+    },
+    afterHydrate: (context) => {
+      console.log('恢复后', context.store.$state);
+    },
+  },
+});
+```
+
+#### 2.5 多个持久化配置
+
+支持为同一个 store 配置多个持久化策略：
+
+```typescript
+// Options API 风格
+export const useUserStore = defineStore('user', {
+  state: () => ({
+    name: '',
+    token: '',
+    preferences: {},
+  }),
+  persist: [
+    {
+      // 配置1：token 保存到 localStorage
+      key: 'user-auth',
+      pick: ['token'],
+      storage: window.localStorage,
+    },
+    {
+      // 配置2：用户偏好保存到 sessionStorage
+      key: 'user-prefs',
+      pick: ['preferences'],
+      storage: window.sessionStorage,
+    },
+  ],
+});
+
+// Setup 函数风格
+export const useUserStore = defineStore('user', () => {
+  const name = ref('');
+  const token = ref('');
+  const preferences = ref({});
+
+  return { name, token, preferences };
+}, {
+  persist: [
+    {
+      key: 'user-auth',
+      pick: ['token'],
+      storage: window.localStorage,
+    },
+    {
+      key: 'user-prefs',
+      pick: ['preferences'],
+      storage: window.sessionStorage,
+    },
+  ],
+});
+```
+
+## 高级功能
+
+### 跨标签页同步
+
+插件会自动监听 `storage` 事件，实现跨标签页的状态同步：
+
+- 当一个标签页修改了持久化的状态时，其他标签页会自动更新
+- 支持 localStorage 和 sessionStorage
+- 仅对 `storageArea: 'local'` 的配置启用跨标签页同步
+
+### 外部存储监听
+
+插件支持监听外部对 localStorage 的修改，并自动同步到 Pinia store：
+
+```typescript
+const userStore = useUserStore();
+
+// 在浏览器控制台或其他代码中直接修改 localStorage
+localStorage.setItem('_user', JSON.stringify({
+  name: 'New Name',
+  token: 'new-token'
+}));
+
+// Pinia store 会自动更新，userStore.user 会同步最新值
+console.log(userStore.user.name); // 'New Name'
+```
+
+**工作原理：**
+1. 插件拦截了 `Storage.prototype` 的 `setItem`、`removeItem`、`clear` 方法
+2. 当检测到存储变化时，自动从 localStorage 读取最新值
+3. 反序列化并更新到对应的 Pinia store
+4. 通过事件抑制机制避免循环更新
+
+**使用场景：**
+- 浏览器 DevTools 中手动修改存储
+- 第三方脚本或扩展修改存储
+- 需要通过原生 API 直接操作存储的场景
+
+### Hook 扩展（加解密）
+
+当需要对所有持久化数据统一加密、脱敏或落库前做额外处理时，可以注册 `pinia:persist:write` 与 `pinia:persist:read` 两个同步钩子：
+
+```typescript
+import type { Module } from '@/core';
+import { decrypt, encrypt } from '@/features/crypto';
+
+export const cryptoModule: Module = {
+  name: 'persist-crypto',
+  hooks: {
+    'pinia:persist:write': (payload) => {
+      payload.value = encrypt(payload.value);
+      return payload;
+    },
+    'pinia:persist:read': (payload) => {
+      payload.value = decrypt(payload.value);
+      return payload;
+    },
+  },
+};
+```
+
+- `write` 钩子在状态序列化完成后执行，可修改 `payload.value` 再写入存储。
+- `read` 钩子在反序列化前触发，可对 `payload.value` 做解密或数据修正。
+- 入参包括 `storeId`、实际存储键、`storageArea`、`fullKey` 以及读取时的 `sourceKey`。
+- 钩子必须同步返回（不可返回 Promise），以保证恢复流程无延迟。
+
+### 调试与验证
+
+1. **确认键名**：在 DevTools 的 Application 面板中找到 `key(store.$id)` 对应的条目，例如 `_user`。
+2. **修改值**：直接 `JSON.parse`/`JSON.stringify` 编辑该值，或在 Console 中执行
+   ```js
+   localStorage.setItem('_user', JSON.stringify({ name: 'Alice' }));
+   ```
+3. **观察响应**：Pinia store 会立刻触发 `$patch`，对应的组件状态、调试面板等都会同步更新。
+4. **验证抑制机制**：调用 `userStore.$persist()` 再查看 `storage` 事件日志，可确认不会出现循环写入。
+
+### 手动控制
+
+Store 会被扩展两个方法：
+
+```typescript
+const userStore = useUserStore();
+
+// 手动持久化当前状态
+userStore.$persist();
+
+// 手动从存储恢复状态
+userStore.$hydrate();
+
+// 带选项恢复
+userStore.$hydrate({ runHooks: false }); // 不执行钩子
+```
+
+### 自定义序列化器
+
+```typescript
+import type { Serializer } from './persistedstate';
+
+function customSerializer(): Serializer {
+  return {
+    serialize: (data) => {
+      // 自定义序列化逻辑
+      return JSON.stringify(data);
+    },
+    deserialize: (value) => {
+      // 自定义反序列化逻辑
+      return JSON.parse(value);
+    },
+  };
+}
+```
+
+## API 文档
+
+### `SyncedPersistedStateOptions`
+
+全局配置选项：
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `storage` | `StorageLike` | - | 存储实例（localStorage/sessionStorage） |
+| `serializer` | `Serializer` | JSON | 序列化器 |
+| `key` | `(storeKey: string) => string` | `id => id` | 键名生成函数 |
+| `auto` | `boolean` | `false` | 是否自动为所有 store 启用持久化 |
+| `debug` | `boolean` | `false` | 是否开启调试模式 |
+| `storageArea` | `'local' \| 'session'` | `'local'` | 存储区域类型 |
+
+### `PersistenceOptions`
+
+Store 级别的配置选项：
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `key` | `string` | store.$id | 自定义存储键名 |
+| `storage` | `StorageLike` | - | 存储实例 |
+| `serializer` | `Serializer` | - | 序列化器 |
+| `pick` | `string[]` | - | 要持久化的字段（白名单） |
+| `omit` | `string[]` | - | 不持久化的字段（黑名单） |
+| `debug` | `boolean` | - | 是否开启调试 |
+| `storageArea` | `'local' \| 'session'` | - | 存储区域 |
+| `beforeHydrate` | `(context) => void` | - | 恢复前钩子 |
+| `afterHydrate` | `(context) => void` | - | 恢复后钩子 |
+
+### `StorageLike`
+
+自定义存储接口：
+
+```typescript
+interface StorageLike {
+  getItem: (key: string) => string | null
+  setItem: (key: string, value: string) => void
+}
+```
+
+### `Serializer`
+
+序列化器接口：
+
+```typescript
+interface Serializer {
+  serialize: (data: StateTree) => string
+  deserialize: (data: string) => StateTree
+}
+```
+
+### `pinia:persist:*` 钩子
+
+| 名称 | 入参 | 必须同步返回 | 描述 |
+|------|------|--------------|------|
+| `pinia:persist:write` | `PiniaPersistWriteHookPayload` | ✅ | 写入前修改序列化字符串，例如加密 |
+| `pinia:persist:read` | `PiniaPersistReadHookPayload` | ✅ | 读取后、反序列化前修改字符串，例如解密 |
+
+#### `PiniaPersistWriteHookPayload`
+
+| 字段 | 描述 |
+|------|------|
+| `storeId` | 当前 store 的 `$id` |
+| `key` | 实际写入存储的键 |
+| `fullKey` | localStorage 同步时用于监听的键 |
+| `storageArea` | `'local'` 或 `'session'` |
+| `state` | 经过 pick/omit 处理后的状态对象 |
+| `value` | 默认序列化得到的字符串，可在钩子中替换 |
+
+#### `PiniaPersistReadHookPayload`
+
+| 字段 | 描述 |
+|------|------|
+| `storeId` | 当前 store 的 `$id` |
+| `key` | 逻辑上对应的键 |
+| `sourceKey` | 实际读取数据的键 |
+| `fullKey` | localStorage 同步时用于监听的键 |
+| `storageArea` | `'local'` 或 `'session'` |
+| `value` | 从存储获取的原始字符串，钩子中可替换 |
+
+## 工作原理
+
+### 1. 初始化流程
+
+```
+创建插件 -> 标准化配置 -> 设置事件监听 -> 为每个 store 创建绑定
+```
+
+### 2. 状态持久化流程
+
+```
+状态变化 -> 应用 pick/omit 过滤 -> 序列化 -> 保存到存储 -> 触发本地事件
+```
+
+### 3. 状态恢复流程
+
+```
+从存储读取 -> 反序列化 -> 应用 pick/omit 过滤 -> 更新 store 状态
+```
+
+### 4. 跨标签页同步流程
+
+```
+标签页A修改存储 -> 触发 storage 事件 -> 标签页B监听到事件 -> 恢复状态
+```
+
+## 实现细节
+
+### Storage API 拦截
+
+插件会拦截 `Storage.prototype` 的以下方法：
+- `setItem` - 拦截设置操作
+- `removeItem` - 拦截删除操作
+- `clear` - 拦截清空操作
+
+拦截后会触发自定义事件，实现同一标签页内的状态同步。
+
+### 事件抑制机制
+
+为了避免循环触发，插件实现了事件抑制机制：
+
+```typescript
+// 持久化前抑制下一个本地事件
+suppressNextLocalEvent(fullKey);
+entry.storage.setItem(entry.key, value);
+```
+
+### 键名管理
+
+完整的存储键名由 `key(store.$id)` 决定，可通过全局 `key` 选项或 store 级的 `persist.key` 来自定义，例如 `_user`、`auth`, `user-prefs` 等。插件会使用该键名进行所有读写与事件监听操作，因此手动修改存储或与第三方脚本联动时也要保持一致。
+
+## 注意事项
+
+### 1. 循环引用
+
+确保状态对象不包含循环引用，否则序列化会失败。
+
+### 2. 存储限制
+
+- localStorage 通常限制为 5-10MB
+- 大型对象可能导致性能问题
+- 建议只持久化必要的数据
+
+### 3. 安全性
+
+- 不要存储敏感信息（如密码）到 localStorage
+- 考虑加密敏感数据
+- Token 等认证信息建议使用短期存储
+
+### 4. SSR 兼容性
+
+插件在非浏览器环境会自动返回空操作插件：
+
+```typescript
+if (typeof window === 'undefined') {
+  return function noopPlugin() {};
+}
+```
+
+### 5. 性能考虑
+
+- 大型状态对象的序列化/反序列化可能影响性能
+- 高频更新的状态不建议持久化
+- 使用 `pick` 选项只持久化必要字段
+
+## 调试
+
+启用调试模式查看详细日志：
+
+```
+persist: {
+  debug: true,
+}
+```
+
+日志示例：
+```
+[persistedstate] storage is not available for store user
+[persistedstate] failed to persist store Error: ...
+[persistedstate] failed to hydrate store Error: ...
+```
+
+## 常见问题
+
+### Q: 如何清除持久化的数据？
+
+```typescript
+// 方法1：手动清除
+localStorage.removeItem('wsy_rbac_user');
+
+// 方法2：重置 store
+const userStore = useUserStore();
+userStore.$reset();
+```
+
+### Q: 如何禁用某个 store 的持久化？
+
+```typescript
+// 不添加 persist 选项即可
+export const useTempStore = defineStore('temp', {
+  state: () => ({}),
+  // 没有 persist 选项
+});
+```
+
+### Q: 如何在开发环境禁用持久化？
+
+```
+persist: import.meta.env.DEV ? false : true,
+```
+
+### Q: 如何持久化嵌套对象的部分字段？
+
+使用点号表示法：
+
+```
+persist: {
+  pick: ['user.name', 'user.email'], // 只持久化 user 对象的 name 和 email
+}
+```
+
+## 相关资源
+
+- [Pinia 官方文档](https://pinia.vuejs.org/)
+- [Web Storage API](https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Storage_API)
+- [Storage 事件](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/storage_event)
+
+## License
+
+MIT

package/src/built-in/pinia-plugin/plugins/persistedstate/index.ts

@@ -0,0 +1,3 @@
+export * from './persistedstate';
+export * from './types';
+export * from './utils';