vue-page-store 0.2.3 → 0.3.0

package/README.md

@@ -1,28 +1,33 @@
 # vue-page-store
 
-> Vue 2.6 页面级 Store —— 状态、通信、生命周期，一个作用域全收。
+> Vue 2.6 页面级作用域运行时容器 —— 状态、生命周期、副作用、通信，一个作用域全收。
 
-## 为什么需要它？
+## 它是什么
 
-在微前端架构（single-spa / qiankun）下，复杂页面（仪表盘、漏斗分析、数据详情）的状态管理面临一个尴尬处境：
+`vue-page-store` 是面向 **复杂 Vue 2 业务页面** 的页面级运行时容器。
 
-| 方案 | 问题 |
-|------|------|
-| **Vuex** | 全局 store，页面销毁后状态残留，命名冲突，不适合页面级生命周期 |
-| **全局 EventBus** | 命名冲突、手动 $off 容易遗漏、事件扩散到全局 |
-| **provide / inject** | 只传数据，不管通信和副作用 |
-| **组件 data** | 跨组件共享困难，深层传递 props 地狱 |
+一个 `definePageStore` 定义一个 **Page Scope** —— 它统一管理这个页面作用域内的：
 
-`vue-page-store` 解决的就是这个中间地带：**页面内部需要共享状态 + 通信 + 生命周期管理，但不应该污染全局。**
+- **state** — 响应式页面状态
+- **getters** — 派生计算
+- **actions** — 业务逻辑
+- **watch** — 声明式副作用
+- **lifecycle** — 页面生命周期（mount / unmount / activate / deactivate）
+- **event bus** — 页面内作用域通信
 
-## 核心特性
+页面销毁时 `$destroy` 一键回收，不污染全局。
 
-- **页面级作用域隔离** — 每个 store 独立一份 state 和事件，互不干扰
-- **`useStore(this)` 一行绑定** — 自动挂载生命周期，自动销毁，零手动清理
-- **页面生命周期** — `mount` / `unmount` / `activate` / `deactivate`，keep-alive 原生支持
-- **API 对齐 Pinia** — `state` / `getters` / `actions` / `$patch` / `$reset`，零学习成本
-- **内置作用域事件** — `$emit` / `$on` / `$off` 限定在当前 store 内，替代全局 EventBus
-- **声明式 watch** — 页面级副作用自动绑定生命周期
+## 它不是什么
+
+- **不是 Vuex / Pinia 替代品** — 全局状态（用户信息、权限、路由）请继续用 Vuex
+- **不是全局状态管理方案** — 它的作用域是"页面"，不是"应用"
+
+| | Vuex | vue-page-store |
+|---|---|---|
+| 作用域 | 全局 | 页面 |
+| 生命周期 | 跟随应用 | 跟随页面组件 |
+| 适合 | 用户信息、权限、路由状态 | 仪表盘、漏斗详情、大型配置页 |
+| 销毁 | 通常不销毁 | 页面离开即回收 |
 
 ## 安装
 
@@ -30,263 +35,264 @@
 npm install vue-page-store
 ```
 
-> **前置条件**：项目中已安装 `vue@^2.6.0`
+要求 `vue@^2.6.0` 作为 peer dependency。
 
 ## 快速上手
 
-### 1. 定义 Store
+### 1. 定义 store
 
-```javascript
-import { definePageStore } from 'vue-page-store';
+```js
+// stores/funnel.js
+import { definePageStore } from 'vue-page-store'
 
 export const useFunnelStore = definePageStore('funnelDetail', {
   state: () => ({
-    filters: { dateRange: [], platform: '' },
-    loading: false,
-    funnelSteps: [],
+    filters: {},
+    list: [],
+    loading: false
   }),
 
   getters: {
-    isReady() {
-      return !this.loading && this.funnelSteps.length > 0;
-    },
+    isEmpty() { return this.list.length === 0 },
+    isReady() { return !this.loading }
   },
 
   actions: {
     async fetchData() {
-      this.loading = true;
+      this.loading = true
       try {
-        this.funnelSteps = await api.getFunnelSteps(this.filters);
+        this.list = await api.getFunnelData(this.filters)
       } finally {
-        this.loading = false;
+        this.loading = false
       }
-    },
+    }
   },
 
   watch: {
-    'filters.platform'(newVal) {
-      this.fetchData();
+    // 函数简写 — 默认浅监听
+    'filters.dateRange'(val) {
+      this.fetchData()
     },
+    // 对象写法 — 显式 deep
+    'filters': {
+      handler(val) { this.fetchData() },
+      deep: true
+    }
   },
 
-  // 0.2.0 新增：页面生命周期
   lifecycle: {
-    mount() {
-      // 页面挂载时自动拉数据
-      this.fetchData();
-    },
-    unmount() {
-      console.log('页面销毁');
-    },
-  },
-});
+    mount()    { this.fetchData() },
+    unmount()  { console.log('funnel page destroyed') },
+    activate() { this.fetchData() },
+  }
+})
 ```
 
-### 2. 组件中使用
+### 2. 页面组件中使用
+
+```js
+// FunnelPage.vue
+import { useFunnelStore } from './stores/funnel'
 
-```javascript
 export default {
   created() {
-    // 传 this → 自动绑定生命周期 + 自动销毁，不需要 beforeDestroy
-    this.store = useFunnelStore(this);
-  },
+    // 传入 this → 自动绑定生命周期 + 自动 provide + 页面销毁时自动回收
+    this.pageStore = useFunnelStore(this)
+  }
+}
+```
 
-  computed: {
-    isReady() {
-      return this.store.isReady;
-    },
-  },
+### 3. 子组件中使用
 
-  methods: {
-    handleSearch() {
-      this.store.$patch({ filters: this.localFilters });
-      this.store.fetchData();
-    },
-  },
-};
+```js
+// FilterPanel.vue — 不需要 import 任何 store 文件
+export default {
+  inject: ['pageStore'],
+  mounted() {
+    this.pageStore.fetchData()  // 直接用
+  }
+}
 ```
 
-> **不传 `this`** 也完全可以，行为和 0.1.0 一样，需要自己在 `beforeDestroy` 里调 `$destroy()`。
-
-### 3. 页面内通信
+所有页面统一用 `this.pageStore`，所有子组件统一 `inject: ['pageStore']`。不需要知道父页面用的哪个 store 定义，零耦合。
 
-```javascript
-// 组件 A —— 发射事件
-this.store.$emit('filter:change', newFilters);
+## API
 
-// 组件 B —— 监听事件
-const off = this.store.$on('filter:change', (filters) => {
-  this.applyFilters(filters);
-});
+### `definePageStore(id, options)`
 
-// 无需手动清理 —— $destroy 时自动回收
+定义一个页面级 store，返回 `useStore(componentVm?)` 函数。
+
+**options：**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `state` | `() => Object` | **必填**，状态工厂函数 |
+| `getters` | `{ [key]: function }` | 派生计算，`this` 指向 store |
+| `actions` | `{ [key]: function }` | 业务方法，`this` 指向 store |
+| `watch` | `{ [path]: handler \| options }` | 声明式 watcher，支持 dot-path |
+| `lifecycle` | `{ mount, unmount, activate, deactivate }` | 页面生命周期钩子 |
+
+### Store 实例属性与方法
+
+| 属性/方法 | 说明 |
+|---|---|
+| `store.xxx` | 直接访问 state 字段 |
+| `store.$state` | 原始响应式 state 对象 |
+| `store.$status` | `{ mounted, active }` 响应式状态 |
+| `store.$disposed` | store 是否已销毁 |
+| `store.$id` | store 唯一标识 |
+| `store.$patch(partial \| fn)` | 批量更新 state（浅合并） |
+| `store.$reset()` | 重置到 `state()` 初始值，清除动态字段 |
+| `store.$emit(event, payload)` | 发射事件（当前 store 作用域） |
+| `store.$on(event, handler)` | 订阅事件，返回取消函数 |
+| `store.$off(event, handler?)` | 取消订阅 |
+| `store.bindTo(componentVm)` | 绑定组件生命周期 + 自动 provide，子组件 `inject: ['pageStore']` |
+| `store.$destroy()` | 手动销毁 |
+
+### watch 配置
+
+```js
+watch: {
+  // 函数写法 — 默认 shallow watch
+  'fieldName'(newVal, oldVal) { ... },
+
+  // 对象写法 — 可配置 deep / immediate
+  'filters': {
+    handler(newVal, oldVal) { ... },
+    deep: true,        // 默认 false
+    immediate: true    // 默认 false
+  }
+}
 ```
 
-## 页面生命周期（0.2.0）
+## State Shape 规则
 
-通过 `useStore(this)` 传入组件实例，store 会自动绑定到组件的生命周期：
+`state()` 返回值定义了推荐的状态边界：
 
-| 组件钩子 | store 行为 | `$status` 变化 |
-|----------|-----------|---------------|
-| `mounted` | 调用 `lifecycle.mount` | `mounted: true, active: true` |
-| `activated` | 调用 `lifecycle.activate` | `active: true` |
-| `deactivated` | 调用 `lifecycle.deactivate` | `active: false` |
-| `beforeDestroy` | 自动调 `$destroy()`，触发 `lifecycle.unmount` | `mounted: false, active: false` |
+- **推荐**：在 `state()` 中声明完整字段，即使初始值为 `null` 或空数组
+- **允许**：通过 `$patch` 动态新增字段（会写入 `$state`，但不会自动成为 `store.xxx` 顶层代理）
+- **注意**：`$reset()` 会清除所有不在 `state()` 中的动态字段
 
-### 无 keep-alive
-
-```
-mounted → lifecycle.mount → ... → beforeDestroy → lifecycle.unmount
+```js
+state: () => ({
+  filters: {},
+  list: [],
+  detail: null  // 推荐：先声明为 null，而不是运行时再 $patch 进去
+})
 ```
 
-### 有 keep-alive
+## 实例模型：Singleton
 
-```
-mounted → lifecycle.mount
-  → deactivated → lifecycle.deactivate
-  → activated → lifecycle.activate
-  → deactivated → lifecycle.deactivate
-  → activated → lifecycle.activate
-  → ... 反复切换 ...
-  → beforeDestroy → lifecycle.unmount
-```
+当前版本采用 **id → singleton** 模型：
 
-### keep-alive 示例
+- 同一个 `id` 在整个应用中对应唯一一个 store 实例
+- `useStore()` 多次调用返回同一实例
+- `$destroy()` 后从 registry 移除，下次 `useStore()` 会创建新实例
 
-```javascript
-export const useListStore = definePageStore('listPage', {
-  state: () => ({
-    list: [],
-    needRefresh: false,
-  }),
+**适用场景：**
 
-  actions: {
-    async fetchList() {
-      this.list = await api.getList();
-      this.needRefresh = false;
-    },
-  },
+- 单页面单作用域（最常见）
+- keep-alive 下的页面缓存
 
-  lifecycle: {
-    mount() {
-      this.fetchList();
-    },
-    activate() {
-      // 从缓存恢复时，按需刷新
-      if (this.needRefresh) this.fetchList();
-    },
-  },
-});
-```
+**不适用场景：**
 
-### `$status` 响应式状态
+- 同一路由多开独立副本
+- 需要按参数区分的多实例页面
 
-`$status` 是响应式对象，可以直接在模板中使用：
+> 多实例支持（keyed instance / scopeKey）将在未来版本演进。
 
-```html
-<template>
-  <div v-if="store.$status.active">
-    <!-- 页面激活时才渲染 -->
-  </div>
-</template>
-```
+## 适用场景
 
-## API
+- 仪表盘页面 — 多模块共享筛选条件、加载状态
+- 漏斗/留存等分析详情页 — 复杂交互 + 异步数据 + 生命周期管理
+- 大型配置页 — 多 tab/多步骤表单的状态统一管理
+- keep-alive 业务页 — 需要 activate/deactivate 感知的页面
+- 微前端子应用 — 页面作用域隔离，不污染宿主全局状态
 
-### `definePageStore(id, options)`
+## 不适用场景
+
+- 全局用户信息、权限、路由等 → 用 Vuex
+- 简单页面的小 data 管理 → 用组件 data 就够了
+- 需要同 id 多实例并存 → 当前版本不支持
+
+## 异步安全
+
+页面销毁后，异步请求可能仍在 pending。**不需要手动检查** —— store 在销毁后会自动忽略所有写操作：
 
-定义一个页面级 Store，返回 `useStore` 函数。
+```js
+actions: {
+  async fetchData() {
+    this.loading = true
+    const data = await api.getData()
+    // 即使页面已销毁，下面的赋值也会被自动静默，不会报错
+    this.list = data
+    this.loading = false
+  }
+}
+```
 
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `id` | `string` | 唯一标识 |
-| `options.state` | `() => Object` | 返回初始 state 的工厂函数 |
-| `options.getters` | `Object` | 计算属性，`this` 指向 store |
-| `options.actions` | `Object` | 方法，`this` 指向 store |
-| `options.watch` | `Object` | 声明式侦听，支持点路径 `'a.b.c'` |
-| `options.lifecycle` | `Object` | 页面生命周期钩子 |
+底层原理：`$destroy()` 后，state 的 setter 和 `$patch` 都会检查 `$disposed`，写入直接跳过。开发环境下会打印 warning 帮助调试。
 
-### `useStore(vm?)`
+## 调试
 
-调用 `definePageStore` 返回的函数。
+`storeRegistry` 是导出的 Map，可以在控制台直接查看：
 
-| 用法 | 行为 |
-|------|------|
-| `useStore()` | 获取/创建 store，手动管理生命周期（兼容 0.1.0） |
-| `useStore(this)` | 获取/创建 store，自动绑定生命周期 + 自动销毁 |
+```js
+import { storeRegistry } from 'vue-page-store'
 
-### `lifecycle` 钩子
+// 查看所有活跃 store
+storeRegistry.forEach((store, id) => {
+  console.log(id, store.$status, store.$disposed)
+})
+```
 
-| 钩子 | 触发时机 | `this` 指向 |
-|------|---------|------------|
-| `mount` | 组件 `mounted` | store |
-| `unmount` | 组件 `beforeDestroy`（`$destroy` 时触发） | store |
-| `activate` | 组件 `activated`（keep-alive 恢复） | store |
-| `deactivate` | 组件 `deactivated`（keep-alive 缓存） | store |
+## 从 v0.2.x 升级
 
-### Store 实例方法
+### Breaking Changes
 
-| 方法 | 说明 |
-|------|------|
-| `$patch(partial)` | 浅合并更新 state，接受对象或 `(state) => Object` 函数 |
-| `$reset()` | 重置 state 到初始值 |
-| `$emit(event, payload?)` | 发射事件（仅当前 store 作用域） |
-| `$on(event, handler)` | 订阅事件，返回取消函数 |
-| `$off(event, handler?)` | 取消事件订阅（不传 handler 则取消该事件全部监听） |
-| `$destroy()` | 销毁 store，回收所有资源 |
-| `bindTo(vm)` | 手动绑定到组件实例（通常不需要，`useStore(this)` 内部调用） |
+**1. `$reset()` 语义变严格**
 
-### Store 实例属性
+v0.2.x：只恢复已有字段的值，动态新增字段会残留。
 
-| 属性 | 说明 |
-|------|------|
-| `$id` | store 唯一标识 |
-| `$state` | 原始响应式 state 对象 |
-| `$status` | 响应式对象 `{ mounted: boolean, active: boolean }` |
+v0.3.0：完全恢复到 `state()` 的 shape，动态字段会被移除。
 
-## 从 0.1.0 升级
+**2. `watch` 默认不再 deep**
 
-**零破坏性变更**。0.1.0 的代码不改一行也能跑。
+v0.2.x：所有 watcher 默认 `deep: true`。
 
-区别只在于你现在可以把：
+v0.3.0：默认 `deep: false`。如果你的 watcher 依赖深层变化检测，需要显式加 `deep: true`。
 
-```javascript
-created() {
-  this.store = useSomeStore();
-},
-beforeDestroy() {
-  this.store.$destroy();
+```js
+// v0.2.x — 这个能监听到 filters 内部变化
+watch: {
+  'filters'(val) { this.fetchData() }
 }
-```
-
-简化成：
 
-```javascript
-created() {
-  this.store = useSomeStore(this);
+// v0.3.0 — 需要显式声明 deep
+watch: {
+  'filters': {
+    handler(val) { this.fetchData() },
+    deep: true
+  }
 }
 ```
 
-> `storeToRefs` 和 `$subscribe` 在 0.2.0 中移除——实际项目中无使用场景，精简 API。
-
-## 与 Pinia / Vuex 的关系
+**3. `_disposed` → `$disposed`**
 
-这不是 Pinia 或 Vuex 的替代品，而是补充：
+`_disposed` 改为公开属性 `$disposed`，语义不变。如果你之前用了 `store._disposed`，替换为 `store.$disposed`。
 
-| | Vuex | Pinia | vue-page-store |
-|---|---|---|---|
-| 作用域 | 全局 | 全局 | 页面级 |
-| 生命周期 | 应用级 | 应用级 | 页面级（自动绑定） |
-| 事件通信 | 无 | 无 | 内置 $emit/$on |
-| Vue 2.6 支持 | ✅ | ⚠️ 需 @vue/composition-api | ✅ 原生支持 |
-| 适用场景 | 用户信息、权限、全局配置 | 同 Vuex | 复杂页面内部状态 |
+### New Features
 
-**推荐组合**：Vuex 管全局，vue-page-store 管页面。
+- `bindTo()` 自动 provide — 子组件 `inject: ['pageStore']` 即可获取，不需要 import store 文件
+- `bindTo()` 重复绑定防护 — 同一个组件实例多次调用不会重复注册生命周期
+- 开发环境 warning — watch 缺少 handler、definePageStore 参数错误等场景会有提示
 
-## Vue 3
+## Roadmap
 
-本库专为 Vue 2.6 设计。Vue 3 项目推荐使用 [Pinia](https://pinia.vuejs.org/)。
+- **Plugin system** — 可扩展能力（logger、persist、loading tracker）
+- **Keyed instance** — `useStore(vm, scopeKey)` 支持同定义多实例
+- **Page cache strategy** — TTL、revalidate、stale-while-activate
 
 ## License
 
-[MIT](./LICENSE)
+MIT © weijianjun