mm_state_store 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,332 @@
-# Temporary Holding Version
+# 状态（mm_state_store）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## 说明
+mm_state_store 是状态存储模块，用于缓存程序运行期间的状态，可随时修改和删除。
+State 继承自 mm_cache 的 Cache，键为对象标识（如用户 ID、设备 ID），值为该对象的状态对象
+（如账户信息、权限等），并具备过期时间、作用域隔离与 JSON 文件持久化能力。
+状态按引用存取，不做深拷贝，外部持有的对象与缓存中是同一个对象。
+
+## 主要状态管理
+- 客户端设备状态：键为设备 ID，值为设备状态对象
+- 用户登录状态：键为用户 ID，值为用户状态对象（账户信息、权限等）
+- 应用状态：键为应用标识，值为应用状态对象
+
+## 功能特点
+
+- 以对象标识为键缓存状态，值必须为对象（账户信息、权限等）
+- 键名为非空字符串，值必须是对象
+- 支持过期时间（TTL）与剩余时间查询
+- 写入与读取均为引用，不做深拷贝，可直接存放连接句柄等不可克隆对象
+- 支持保存到 JSON 文件，按作用域分文件存储
+- 基于 mm_corejs 的 Admin 管理器，按作用域缓存实例、彼此隔离
+
+## 安装
+
+```bash
+npm install mm_state_store
+```
+
+## 快速开始
+
+以下示例中的 `await` 需运行在 async 函数内，或使用 ESM 的顶层 await。
+
+```javascript
+const { State, stateAdmin } = require('mm_state_store');
+
+// 直接使用状态类：键为用户 ID，值为该用户的状态
+const state = new State();
+await state.set('1001', {
+  account: { uid: '1001', nickname: '张三' },
+  power: ['user:read']
+});
+const user = await state.get('1001');
+console.log(user.account.nickname); // "张三"
+
+// 通过管理器按作用域获取实例（相同作用域返回同一实例）
+const userState = stateAdmin('user');
+await userState.set('1002', {
+  account: { uid: '1002', nickname: '李四' },
+  power: ['user:read']
+});
+console.log((await stateAdmin('user').get('1002')).account.nickname); // "李四"
+
+await state.dispose();
+await userState.dispose();
+```
+
+## API
+
+所有方法均返回 Promise，需使用 `await` 调用。
+
+### 类方法
+
+| 方法 | 说明 | 参数 | 返回值 |
+|---|---|---|---|
+| set | 设置指定对象的状态 | key（对象标识）, value（状态对象）, seconds（过期秒数，0 为永不过期） | boolean |
+| get | 获取指定对象的状态 | key | object \| null |
+| del | 删除指定对象的状态 | key | number（删除数量） |
+| has | 判断指定对象的状态是否存在 | key | boolean |
+| ttl | 获取剩余过期时间 | key | number（-1 永不过期，-2 不存在） |
+| keys | 获取对象标识列表 | pattern（支持 * 通配符） | string[] |
+| list | 获取全部状态的副本 | - | object |
+| clear | 清空当前作用域的全部状态 | - | boolean |
+| save | 写入持久化文件（需开启 persist） | - | boolean |
+| dispose | 释放实例（含底层定时器） | - | Promise |
+
+### 工厂函数
+
+| 函数 | 说明 | 参数 | 返回值 |
+|---|---|---|---|
+| stateAdmin | 获取指定作用域的状态实例，不存在时创建 | scope, config | State |
+
+`scope` 缺省时使用 `os`。`config` 为配置对象，常用：
+
+```javascript
+{
+  cachebase: {
+    persist: true,          // 开启文件持久化，默认 false
+    dir: './data',          // 持久化目录，文件名为 <scope>.json
+    auto_save: false,       // 关闭自动保存，改为手动调用 save()
+    save_interval: 30000    // 自动保存间隔（毫秒）
+  }
+}
+```
+
+## 使用示例
+
+### 1. 用户状态（账户信息、权限）
+
+```javascript
+const { stateAdmin } = require('mm_state_store');
+
+const userState = stateAdmin('user');
+
+// 缓存用户状态：键为用户 ID，值为该用户的状态对象
+await userState.set('1001', {
+  account: { uid: '1001', nickname: '张三', mobile: '13800000001' },
+  power: ['user:read', 'user:write']
+});
+
+const user = await userState.get('1001');
+console.log(user.account.nickname); // "张三"
+console.log(user.power);            // [ 'user:read', 'user:write' ]
+
+// 更新状态：取旧状态合并后整体写回
+await userState.set('1001', { ...user, power: ['user:read'] });
+console.log((await userState.get('1001')).power); // [ 'user:read' ]
+
+// 用户退出或缓存失效：删除该用户状态
+await userState.del('1001');
+console.log(await userState.has('1001')); // false
+
+await userState.dispose();
+```
+
+### 2. 客户端设备状态（含过期时间）
+
+```javascript
+const { stateAdmin } = require('mm_state_store');
+
+const deviceState = stateAdmin('device');
+
+// 键为设备 ID，值为设备状态对象，30 分钟过期
+await deviceState.set('d01', { platform: 'ios', online: true, last_time: Date.now() }, 1800);
+
+// 设备离线：合并旧状态后写回
+await deviceState.set('d01', { ...(await deviceState.get('d01')), online: false });
+console.log((await deviceState.get('d01')).online); // false
+
+// 查看剩余过期时间与全部设备状态
+console.log(await deviceState.ttl('d01')); // 剩余秒数
+console.log(await deviceState.list());
+
+await deviceState.dispose();
+```
+
+### 3. 文件持久化
+
+```javascript
+const { State } = require('mm_state_store');
+
+const config = { scope: 'app', cachebase: { persist: true, dir: './data', auto_save: false } };
+const state = new State(config);
+await state.set('1001', { account: { uid: '1001', nickname: '张三' }, power: ['user:read'] });
+console.log(await state.save()); // true，写入 ./data/app.json
+await state.dispose();
+
+// 重新创建实例后自动从 ./data/app.json 加载
+const loaded = new State(config);
+console.log((await loaded.get('1001')).account.nickname); // "张三"
+await loaded.dispose();
+```
+
+### 4. 作用域隔离与工厂配置
+
+```javascript
+const { stateAdmin } = require('mm_state_store');
+
+// 首次创建时传入配置：app 作用域持久化到 ./data/app.json
+const appState = stateAdmin('app', {
+  cachebase: { persist: true, dir: './data', auto_save: false }
+});
+const userState = stateAdmin('user');
+
+await appState.set('cfg', { version: '1.0.0', debug: false });
+
+// 不同作用域互不影响
+console.log(await userState.has('cfg'));                   // false
+console.log((await stateAdmin('app').get('cfg')).version);  // "1.0.0"
+
+// 同作用域再次调用仍复用首次创建的实例（配置不覆盖）
+console.log(stateAdmin('app') === appState);                // true
+console.log(await appState.save());                         // true
+
+await appState.dispose();
+await userState.dispose();
+```
+
+### 5. 遍历与清空
+
+```javascript
+const { State } = require('mm_state_store');
+
+const state = new State({ scope: 'temp' });
+await state.set('1001', { account: { uid: '1001', nickname: '张三' } });
+await state.set('1002', { account: { uid: '1002', nickname: '李四' } });
+
+console.log(await state.keys());      // [ '1001', '1002' ]
+console.log(await state.keys('100*')); // [ '1001', '1002' ]
+console.log(Object.keys(await state.list())); // [ '1001', '1002' ]
+
+await state.clear();
+console.log(await state.list()); // {}
+
+await state.dispose();
+```
+
+### 6. 登录态维护与权限校验
+
+```javascript
+const { stateAdmin } = require('mm_state_store');
+
+const loginState = stateAdmin('login');
+
+/**
+ * 用户登录，写入登录态并设置 2 小时过期
+ * @param {string} user_id 用户 ID
+ * @param {object} user 用户信息
+ * @returns {Promise<void>}
+ */
+async function login(user_id, user) {
+  const session = {
+    account: { uid: user_id, nickname: user.nickname },
+    power: user.power,
+    login_time: Date.now()
+  };
+  await loginState.set(user_id, session, 7200);
+}
+
+/**
+ * 校验用户是否拥有指定权限
+ * @param {string} user_id 用户 ID
+ * @param {string} power 权限标识
+ * @returns {Promise<boolean>} 是否拥有权限
+ */
+async function checkPower(user_id, power) {
+  const session = await loginState.get(user_id);
+  if (!session) {
+    return false;
+  }
+  return session.power.includes(power);
+}
+
+/**
+ * 用户退出，删除登录态
+ * @param {string} user_id 用户 ID
+ * @returns {Promise<void>}
+ */
+async function logout(user_id) {
+  await loginState.del(user_id);
+}
+
+await login('1001', { nickname: '张三', power: ['user:read'] });
+console.log(await checkPower('1001', 'user:read'));  // true
+console.log(await checkPower('1001', 'user:write')); // false
+console.log(await loginState.ttl('1001'));           // 约 7200
+
+await logout('1001');
+console.log(await loginState.has('1001')); // false
+
+await loginState.dispose();
+```
+
+### 7. 参数校验与错误处理
+
+```javascript
+const { State } = require('mm_state_store');
+
+const state = new State({ scope: 'demo' });
+
+try {
+  await state.set('', {});          // 键名为空字符串
+} catch (err) {
+  console.log(err.message);         // "键名必须是非空字符串"
+}
+
+try {
+  await state.set('1001', ['a']);   // 状态值为数组
+} catch (err) {
+  console.log(err.message);         // "状态值必须是对象"
+}
+
+// 读取不存在的键不抛错，返回 null
+console.log(await state.get('404')); // null
+
+await state.dispose();
+```
+
+## 注意事项
+
+1. 键应为对象标识（如用户 ID、设备 ID），值必须是对象（不能为 `null`、数组或基础类型），否则抛出 `TypeError`。
+2. 键名必须是非空字符串，否则抛出 `TypeError`。
+3. 不存在或已过期的键，`get` 返回 `null`，`has` 返回 `false`。
+4. `set` 与 `get` 均按引用传递，不做深拷贝：外部修改对象会直接影响缓存，修改 `get`/`list` 返回的对象同样会改写缓存内容，需要隔离时请自行拷贝。
+5. `save` 仅在 `cachebase.persist` 为 `true` 时生效，否则返回 `false`；持久化文件为 `<dir>/<scope>.json`，内容为 JSON5 格式。
+6. 默认 `auto_save` 为 `true`、`save_interval` 为 30 秒；如需精确控制落盘时机可关闭自动保存并手动 `save()`。
+7. 底层写入使用同步 JSON 写文件，不是原子写；进程在写入瞬间被强制终止可能导致文件损坏，重要数据需自行备份。
+8. 通过 `stateAdmin(scope, config)` 传入的配置仅首次创建时生效，同作用域后续调用复用已有实例。
+9. 底层 CacheBase 会启动过期检查与自动保存定时器，不再使用时请调用 `dispose()` 释放，避免进程无法退出。
+10. 持久化文件损坏或无法解析时，加载会降级为空状态并输出错误日志，不会中断实例创建，可通过重新 `set` + `save` 覆盖损坏文件。
+
+## 依赖
+
+- mm_corejs：提供 Admin 管理器
+- mm_cache：提供 Cache 缓存基类（内存、文件持久化、过期时间）
+
+## 测试
+
+```bash
+# 运行用例（jest，并要求 100% 行/分支/函数/语句覆盖）
+npm test
+```
+
+用例位于 `test/state.test.js`，覆盖：导出结构、基本读写与覆盖、键名与状态值校验、引用语义、作用域缺省规则、键列表与通配查询、清空隔离、过期时间、空作用域、工厂复用与配置、持久化保存与重载、损坏文件降级。
+
+## 示例
+
+```bash
+# 运行动态示例
+npm run demo
+```
+
+示例位于 `example/index.js`，依次演示作用域工厂与用户状态、过期时间、遍历清空、文件持久化。
+
+文档中的示例（快速开始与使用示例章节）如下：
+
+1. 用户状态（账户信息、权限）
+2. 客户端设备状态（含过期时间）
+3. 文件持久化
+4. 作用域隔离与工厂配置
+5. 遍历与清空
+6. 登录态维护与权限校验
+7. 参数校验与错误处理

package/example/index.js

@@ -0,0 +1,148 @@
+/**
+ * mm_state_store 状态存储示例
+ * 演示 State 类与 stateAdmin 作用域工厂，状态读写、过期时间、
+ * 遍历清空与 JSON 文件持久化。
+ * 运行：node example/index.js
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { State, stateAdmin } = require('../index.js');
+
+/** 示例临时目录 */
+const TMP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'mm-state-example-'));
+
+/** 待释放的实例 */
+const states = [];
+
+/**
+ * 创建状态实例并登记
+ * @param {string} scope 作用域
+ * @param {object} [config] 配置对象
+ * @returns {State} 状态实例
+ */
+function createState(scope, config) {
+  const state = new State({ scope, ...(config || {}) });
+  states.push(state);
+  return state;
+}
+
+/**
+ * 演示作用域工厂与状态读写
+ * @returns {Promise<void>}
+ */
+async function demoScope() {
+  console.log('\n=== 1. 作用域工厂与用户状态 ===');
+
+  const user_state = stateAdmin('user');
+  states.push(user_state);
+
+  // 键为用户 ID，值为该用户的状态对象
+  await user_state.set('1001', {
+    account: { uid: '1001', nickname: '张三', mobile: '13800000001' },
+    power: ['user:read', 'user:write']
+  });
+
+  const user = await user_state.get('1001');
+  console.log('用户昵称:', user.account.nickname);
+  console.log('用户权限:', user.power);
+  console.log('是否已缓存:', await user_state.has('1001'));
+
+  // 更新状态：取旧状态合并后整体写回
+  await user_state.set('1001', { ...user, power: ['user:read'] });
+  console.log('更新后权限:', (await user_state.get('1001')).power);
+
+  console.log('同作用域复用实例:', stateAdmin('user') === user_state);
+
+  const session_state = stateAdmin('session');
+  states.push(session_state);
+  console.log('不同作用域隔离:', (await session_state.has('1001')) === false);
+}
+
+/**
+ * 演示过期时间
+ * @returns {Promise<void>}
+ */
+async function demoExpire() {
+  console.log('\n=== 2. 过期时间 ===');
+
+  const device_state = stateAdmin('device');
+  states.push(device_state);
+
+  // 键为设备 ID，值为设备状态对象，30 秒过期
+  await device_state.set('d01', { platform: 'ios', online: true }, 30);
+  console.log('剩余时间(秒):', await device_state.ttl('d01'));
+
+  await device_state.set('d02', { platform: 'android', online: true }, 0.01);
+  console.log('短 TTL 剩余(秒):', await device_state.ttl('d02'));
+
+  await new Promise((resolve) => setTimeout(resolve, 30));
+  console.log('过期后读取 d02:', await device_state.get('d02'));
+  console.log('过期后 ttl(d02):', await device_state.ttl('d02'));
+}
+
+/**
+ * 演示遍历与清空
+ * @returns {Promise<void>}
+ */
+async function demoList() {
+  console.log('\n=== 3. 遍历与清空 ===');
+
+  const cache_state = createState('cache');
+
+  await cache_state.set('1001', { account: { uid: '1001', nickname: '张三' } });
+  await cache_state.set('1002', { account: { uid: '1002', nickname: '李四' } });
+
+  console.log('全部标识:', await cache_state.keys());
+  console.log('通配 100*:', await cache_state.keys('100*'));
+  console.log('状态表:', JSON.stringify(await cache_state.list()));
+
+  await cache_state.clear();
+  console.log('清空后列表:', await cache_state.list());
+}
+
+/**
+ * 演示文件持久化
+ * @returns {Promise<void>}
+ */
+async function demoPersist() {
+  console.log('\n=== 4. 文件持久化 ===');
+
+  const scope = 'app';
+  const config = { cachebase: { persist: true, dir: TMP_DIR, auto_save: false } };
+
+  const app_state = createState(scope, config);
+  await app_state.set('1001', {
+    account: { uid: '1001', nickname: '张三' },
+    power: ['user:read']
+  });
+  console.log('保存结果:', await app_state.save());
+
+  // 落盘内容即下次启动时自动加载的数据（JSON5 格式）
+  const file = path.join(TMP_DIR, `${scope}.json`);
+  console.log('持久化文件:', file);
+  console.log('文件内容:', fs.readFileSync(file, 'utf8'));
+  console.log('创建同名作用域实例时会自动加载该文件');
+}
+
+/**
+ * 主流程
+ * @returns {Promise<void>}
+ */
+async function main() {
+  await demoScope();
+  await demoExpire();
+  await demoList();
+  await demoPersist();
+
+  for (const state of states) {
+    await state.dispose();
+  }
+  fs.rmSync(TMP_DIR, { recursive: true, force: true });
+  console.log('\n示例执行完成');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});

package/index.js

@@ -0,0 +1,22 @@
+const Admin = require('mm_corejs').Admin;
+const State = require('./lib/state.js');
+
+const admin = new Admin();
+admin.setClass(State);
+
+module.exports = {
+  State,
+  admin,
+  /**
+   * 获取指定作用域的状态存储实例，不存在时创建
+   * @param {string} [scope] 作用域名称，缺省时使用 os
+   * @param {object} [config] 配置对象，如 { cachebase: { persist: true, dir: './cache' } }
+   * @returns {State} 状态存储实例
+   */
+  stateAdmin(scope, config) {
+    if (!scope) {
+      scope = 'os';
+    }
+    return admin.get(scope, { ...(config || {}), scope });
+  }
+};

package/lib/state.js

@@ -0,0 +1,162 @@
+const { Cache } = require('mm_cache');
+
+const DEFAULT_SCOPE = 'os';
+
+/**
+ * 状态存储类，以对象标识为键缓存状态，支持过期时间与持久化。
+ * 存取均为引用，不做深拷贝，可直接存放连接句柄等不可克隆对象。
+ * @class
+ * @augments {Cache}
+ */
+class State extends Cache {
+  /**
+   * 构造函数
+   * @param {object} [config] 配置对象
+   * @param {string} [config.scope] 作用域名称，缺省时使用 os
+   * @param {string} [config.way] 缓存方式，默认 cachebase（纯内存，可开启持久化）
+   * @param {object} [config.cachebase] 持久化配置，如 { persist: true, dir: './cache', save_interval: 30000 }
+   */
+  constructor(config = {}) {
+    const scope = config.scope || config.name || DEFAULT_SCOPE;
+    const cachebase_config = { ...(config.cachebase || {}), scope };
+    super({
+      way: 'cachebase',
+      ...config,
+      scope,
+      cachebase: cachebase_config
+    });
+  }
+
+  /**
+   * 校验键名，必须是非空字符串
+   * @param {*} key 对象标识
+   * @returns {void}
+   * @throws {TypeError} 键名不是非空字符串时抛出
+   */
+  _checkKey(key) {
+    if (!key || typeof key !== 'string') {
+      throw new TypeError('键名必须是非空字符串');
+    }
+  }
+
+  /**
+   * 校验状态值，必须是对象
+   * @param {*} value 状态值
+   * @returns {void}
+   * @throws {TypeError} 状态值不是对象时抛出
+   */
+  _checkValue(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      throw new TypeError('状态值必须是对象');
+    }
+  }
+
+  /**
+   * 设置指定对象的状态，按引用保存，不做深拷贝
+   * @param {string} key 对象标识
+   * @param {object} value 状态对象
+   * @param {number} [seconds] 过期时间（秒），0 表示永不过期
+   * @returns {Promise<boolean>} 是否设置成功
+   */
+  async set(key, value, seconds = 0) {
+    this._checkKey(key);
+    this._checkValue(value);
+    return await super.set(key, value, seconds);
+  }
+
+  /**
+   * 获取指定对象的状态，返回缓存中的同一引用
+   * @param {string} key 对象标识
+   * @returns {Promise<object|null>} 状态对象，不存在或已过期时返回 null
+   */
+  async get(key) {
+    this._checkKey(key);
+    return await super.get(key);
+  }
+
+  /**
+   * 删除指定对象的状态
+   * @param {string} key 对象标识
+   * @returns {Promise<number>} 删除数量
+   */
+  async del(key) {
+    this._checkKey(key);
+    return await super.del(key);
+  }
+
+  /**
+   * 判断指定对象的状态是否存在
+   * @param {string} key 对象标识
+   * @returns {Promise<boolean>} 是否存在
+   */
+  async has(key) {
+    this._checkKey(key);
+    return Boolean(await super.has(key));
+  }
+
+  /**
+   * 获取指定对象状态的剩余过期时间
+   * @param {string} key 对象标识
+   * @returns {Promise<number>} 剩余秒数，-1 表示永不过期，-2 表示不存在
+   */
+  async ttl(key) {
+    this._checkKey(key);
+    return await super.ttl(key);
+  }
+
+  /**
+   * 获取当前作用域下的全部对象标识
+   * @param {string} [pattern] 匹配模式，支持 * 通配符
+   * @returns {Promise<string[]>} 对象标识数组
+   */
+  async keys(pattern = '*') {
+    const prefix = `${this.scope}:`;
+    const keys = await super.keys(pattern);
+    return keys.map((key) => (key.startsWith(prefix) ? key.slice(prefix.length) : key));
+  }
+
+  /**
+   * 获取当前作用域下的全部状态（值为缓存中的引用）
+   * @returns {Promise<object>} 以对象标识为键的状态表
+   */
+  async list() {
+    const keys = await this.keys();
+    const result = {};
+    for (const key of keys) {
+      result[key] = await this.get(key);
+    }
+    return result;
+  }
+
+  /**
+   * 清空当前作用域下的全部状态
+   * @returns {Promise<boolean>} 是否清空成功
+   */
+  async clear() {
+    const keys = await this.keys();
+    for (const key of keys) {
+      await super.del(key);
+    }
+    return true;
+  }
+
+  /**
+   * 将当前作用域的数据写入持久化文件，仅在启用 persist 时生效
+   * @returns {Promise<boolean>} 是否执行了保存
+   */
+  async save() {
+    if (!this._client) {
+      await this.connect();
+    }
+    if (!this._client || typeof this._client.save !== 'function') {
+      return false;
+    }
+    if (!this._client.config || !this._client.config.persist) {
+      return false;
+    }
+    this._client.save();
+    return true;
+  }
+}
+
+module.exports = State;

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "mm_state_store",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "状态存储模块：以对象标识为键缓存状态对象，支持过期时间与持久化",
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/qiuwenwu91/mm_state_store.git"
+  },
+  "keywords": [
+    "mm_mod",
+    "mm_infra",
+    "mm_data",
+    "state",
+    "状态",
+    "缓存"
+  ],
+  "layer": "infra",
+  "group": "data",
+  "author": "邱文武",
+  "license": "ISC",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "jest --coverage",
+    "demo": "node example/index.js"
+  },
+  "jest": {
+    "collectCoverageFrom": [
+      "index.js",
+      "lib/**/*.js"
+    ],
+    "coverageThreshold": {
+      "global": {
+        "lines": 100,
+        "branches": 100,
+        "functions": 100,
+        "statements": 100
+      }
+    }
+  },
+  "dependencies": {
+    "mm_corejs": "^1.1.4",
+    "mm_cache": "^1.5.5"
+  },
+  "devDependencies": {
+    "jest": "^30.5.2"
+  }
+}

package/test/state.test.js

@@ -0,0 +1,392 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { Cache } = require('mm_cache');
+const { admin: cachebase_admin } = require('mm_cachebase');
+const mod = require('../index');
+const State = require('../lib/state');
+
+/** 用例数据：用户状态 */
+const user_1001 = {
+  account: { uid: '1001', nickname: '张三', mobile: '13800000001' },
+  power: ['user:read', 'user:write']
+};
+
+/** 用例数据：用户状态（覆盖后） */
+const user_1001_new = {
+  account: { uid: '1001', nickname: '张三丰', mobile: '13800000001' },
+  power: ['user:read']
+};
+
+/** 用例数据：设备状态 */
+const device_d01 = { platform: 'ios', online: true };
+
+/** 临时目录，用于持久化用例 */
+let tmp_dir;
+
+/** 待释放的实例，避免定时器阻止进程退出 */
+const states = [];
+
+/**
+ * 创建状态实例并登记，便于统一释放
+ * @param {string} scope 作用域
+ * @param {object} [config] 配置对象
+ * @returns {State} 状态实例
+ */
+function createState(scope, config) {
+  const state = new State({ scope, ...(config || {}) });
+  states.push(state);
+  return state;
+}
+
+/**
+ * 延时指定毫秒
+ * @param {number} ms 毫秒数
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+beforeAll(() => {
+  tmp_dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mm-state-'));
+});
+
+afterAll(async () => {
+  for (const state of states) {
+    await state.dispose();
+  }
+  cachebase_admin.clear();
+  fs.rmSync(tmp_dir, { recursive: true, force: true });
+});
+
+describe('mm_state_store 模块入口', () => {
+  it('导出 State 类、admin 与 stateAdmin 函数', () => {
+    expect(mod.State).toBe(State);
+    expect(mod.admin).toBeDefined();
+    expect(typeof mod.stateAdmin).toBe('function');
+  });
+
+  it('State 继承 Cache，默认缓存方式为 cachebase', () => {
+    const state = createState('export_state');
+    expect(state).toBeInstanceOf(Cache);
+    expect(state.getCacheWay()).toBe('cachebase');
+  });
+
+  it('未提供 scope 时使用 os', () => {
+    const state = new State();
+    states.push(state);
+    expect(state.scope).toBe('os');
+  });
+
+  it('未提供 scope 时回退到 name', () => {
+    const state = new State({ name: 'named_state' });
+    states.push(state);
+    expect(state.scope).toBe('named_state');
+  });
+
+  it('stateAdmin 缺省作用域为 os 并复用实例', () => {
+    const state = mod.stateAdmin();
+    states.push(state);
+    expect(state.scope).toBe('os');
+    expect(mod.stateAdmin()).toBe(state);
+  });
+
+  it('stateAdmin 按作用域复用实例，不同作用域彼此隔离', () => {
+    const state = mod.stateAdmin('factory_state');
+    const other = mod.stateAdmin('factory_other');
+    states.push(state, other);
+
+    expect(state).toBeInstanceOf(State);
+    expect(mod.stateAdmin('factory_state')).toBe(state);
+    expect(other).not.toBe(state);
+  });
+});
+
+describe('基本读写', () => {
+  it('set 后可 get，has 为 true', async () => {
+    const state = createState('basic_state');
+
+    expect(await state.set('1001', user_1001)).toBe(true);
+    expect(await state.get('1001')).toEqual(user_1001);
+    expect(await state.has('1001')).toBe(true);
+  });
+
+  it('不存在的键 get 返回 null，has 返回 false', async () => {
+    const state = createState('basic_missing');
+
+    expect(await state.get('1002')).toBeNull();
+    expect(await state.has('1002')).toBe(false);
+  });
+
+  it('允许覆盖已有状态', async () => {
+    const state = createState('basic_overwrite');
+    await state.set('1001', user_1001);
+
+    expect(await state.set('1001', user_1001_new)).toBe(true);
+    expect(await state.get('1001')).toEqual(user_1001_new);
+  });
+
+  it('del 返回删除数量', async () => {
+    const state = createState('basic_del');
+    await state.set('1001', user_1001);
+
+    expect(await state.del('1001')).toBe(1);
+    expect(await state.del('1001')).toBe(0);
+    expect(await state.has('1001')).toBe(false);
+  });
+});
+
+describe('参数校验', () => {
+  it('键名必须是非空字符串', async () => {
+    const state = createState('validate_key');
+
+    await expect(state.set('', {})).rejects.toThrow('键名必须是非空字符串');
+    await expect(state.set(123, {})).rejects.toThrow('键名必须是非空字符串');
+    await expect(state.get(null)).rejects.toThrow('键名必须是非空字符串');
+    await expect(state.del(undefined)).rejects.toThrow('键名必须是非空字符串');
+    await expect(state.has(0)).rejects.toThrow('键名必须是非空字符串');
+    await expect(state.ttl(undefined)).rejects.toThrow('键名必须是非空字符串');
+  });
+
+  it('状态值必须是对象', async () => {
+    const state = createState('validate_value');
+
+    await expect(state.set('1001', null)).rejects.toThrow('状态值必须是对象');
+    await expect(state.set('1001', undefined)).rejects.toThrow('状态值必须是对象');
+    await expect(state.set('1001', 1)).rejects.toThrow('状态值必须是对象');
+    await expect(state.set('1001', 'ios')).rejects.toThrow('状态值必须是对象');
+    await expect(state.set('1001', true)).rejects.toThrow('状态值必须是对象');
+    await expect(state.set('1001', [1, 2])).rejects.toThrow('状态值必须是对象');
+    expect(await state.has('1001')).toBe(false);
+  });
+
+  it('允许设置空对象', async () => {
+    const state = createState('validate_empty');
+    expect(await state.set('1001', {})).toBe(true);
+  });
+});
+
+describe('引用语义', () => {
+  it('写入后修改外部对象会同步反映到缓存', async () => {
+    const state = createState('ref_set');
+    const source = { account: { uid: '3001', nickname: '王五' }, power: ['user:read'] };
+
+    await state.set('3001', source);
+    source.account.nickname = '改动后';
+    source.power.push('user:admin');
+
+    const fetched = await state.get('3001');
+    expect(fetched).toBe(source);
+    expect(fetched.account.nickname).toBe('改动后');
+    expect(fetched.power).toEqual(['user:read', 'user:admin']);
+  });
+
+  it('get 返回缓存中的同一引用', async () => {
+    const state = createState('ref_get');
+    const source = { account: { uid: '3001', nickname: '王五' } };
+
+    await state.set('3001', source);
+
+    expect(await state.get('3001')).toBe(source);
+  });
+
+  it('可存放含不可克隆句柄的对象', async () => {
+    const state = createState('ref_handle');
+    const handle = { ws: { readyState: 1 }, queue: Promise.resolve() };
+
+    expect(await state.set('c1', handle)).toBe(true);
+
+    const fetched = await state.get('c1');
+    expect(fetched.ws).toBe(handle.ws);
+    expect(fetched.queue).toBe(handle.queue);
+  });
+
+  it('list 返回的状态值为缓存中的引用', async () => {
+    const state = createState('ref_list');
+    const source = { account: { uid: '3001', nickname: '王五' } };
+    await state.set('3001', source);
+
+    const all_states = await state.list();
+    expect(all_states['3001']).toBe(source);
+  });
+
+  it('底层返回 undefined 时原样返回', async () => {
+    const state = createState('clone_abnormal');
+    await state.set('1001', user_1001);
+
+    const client_get = state._client.get;
+    state._client.get = async () => undefined;
+    expect(await state.get('1001')).toBeUndefined();
+    state._client.get = client_get;
+  });
+});
+
+describe('键列表与作用域', () => {
+  it('keys 返回不含作用域前缀的键名，支持通配符', async () => {
+    const state = createState('list_state');
+    await state.set('1001', user_1001);
+    await state.set('d01', device_d01);
+
+    expect((await state.keys()).sort()).toEqual(['1001', 'd01']);
+    expect(await state.keys('100*')).toEqual(['1001']);
+  });
+
+  it('list 返回键值状态表', async () => {
+    const state = createState('list_all');
+    await state.set('1001', user_1001);
+    await state.set('d01', device_d01);
+
+    expect(await state.list()).toEqual({ 1001: user_1001, d01: device_d01 });
+  });
+
+  it('底层返回无前缀的键时原样保留', async () => {
+    const state = createState('raw_key_state');
+    await state.set('1001', user_1001);
+
+    const client_keys = state._client.keys;
+    state._client.keys = async () => ['raw_key_state:1001', 'raw_key'];
+    expect(await state.keys()).toEqual(['1001', 'raw_key']);
+    state._client.keys = client_keys;
+  });
+
+  it('空作用域的 keys 为数组、list 为空对象、ttl 为 -2', async () => {
+    const state = createState('empty_state');
+
+    expect(await state.keys()).toEqual([]);
+    expect(await state.list()).toEqual({});
+    expect(await state.ttl('1001')).toBe(-2);
+  });
+
+  it('clear 仅清空当前作用域', async () => {
+    const state_a = createState('clear_a');
+    const state_b = createState('clear_b');
+    await state_a.set('1001', user_1001);
+    await state_b.set('1001', user_1001);
+
+    expect(await state_a.clear()).toBe(true);
+    expect(await state_a.list()).toEqual({});
+    expect(await state_b.keys()).toEqual(['1001']);
+  });
+
+  it('不同作用域的状态互不影响', async () => {
+    const app_state = createState('app_scope');
+    const user_state = createState('user_scope');
+    await app_state.set('cfg', { version: '1.0.0' });
+
+    expect(await user_state.has('cfg')).toBe(false);
+    expect(await app_state.get('cfg')).toEqual({ version: '1.0.0' });
+  });
+});
+
+describe('过期时间', () => {
+  it('永不过期返回 -1，过期后不可读且不在 keys 中', async () => {
+    const state = createState('ttl_state');
+
+    await state.set('1001', user_1001);
+    expect(await state.ttl('1001')).toBe(-1);
+
+    await state.set('1002', user_1001, 0.05);
+    expect(await state.ttl('1002')).toBe(1);
+
+    await sleep(80);
+    expect(await state.get('1002')).toBeNull();
+    expect(await state.has('1002')).toBe(false);
+    expect(await state.ttl('1002')).toBe(-2);
+    expect(await state.keys()).toEqual(['1001']);
+  });
+});
+
+describe('持久化', () => {
+  it('未启用 persist 时 save 返回 false', async () => {
+    const state = createState('memory_state');
+    await state.set('1001', user_1001);
+
+    expect(await state.save()).toBe(false);
+  });
+
+  it('未连接即调用 save 时先连接，未启用 persist 返回 false', async () => {
+    const state = createState('fresh_save');
+    expect(await state.save()).toBe(false);
+  });
+
+  it('save 的底层分支行为', async () => {
+    const state = createState('stub_save');
+    await state.set('1001', user_1001);
+    const client = state._client;
+
+    state._client = { config: { persist: true } };
+    expect(await state.save()).toBe(false);
+
+    state._client = { save: () => true, config: null };
+    expect(await state.save()).toBe(false);
+
+    let saved_count = 0;
+    state._client = {
+      save: () => {
+        saved_count += 1;
+      },
+      config: { persist: true }
+    };
+    expect(await state.save()).toBe(true);
+    expect(saved_count).toBe(1);
+
+    state._client = client;
+  });
+
+  it('保存落盘后可重新加载', async () => {
+    const scope = 'persist_state';
+    const config = { cachebase: { persist: true, dir: tmp_dir, auto_save: false } };
+
+    const state = createState(scope, config);
+    await state.set('1001', user_1001);
+    expect(await state.save()).toBe(true);
+    expect(fs.existsSync(path.join(tmp_dir, `${scope}.json`))).toBe(true);
+
+    await state.dispose();
+    cachebase_admin.clear();
+
+    const loaded = createState(scope, config);
+    expect(await loaded.get('1001')).toEqual(user_1001);
+    expect(await loaded.save()).toBe(true);
+  });
+
+  it('同作用域再次调用 stateAdmin 时沿用首次配置', async () => {
+    const scope = 'factory_config';
+    const config = { cachebase: { persist: true, dir: tmp_dir, auto_save: false } };
+    const state = mod.stateAdmin(scope, config);
+    states.push(state);
+    await state.set('1001', user_1001);
+
+    const again = mod.stateAdmin(scope, { cachebase: { persist: false } });
+    expect(again).toBe(state);
+    expect(await again.get('1001')).toEqual(user_1001);
+    expect(await again.save()).toBe(true);
+  });
+
+  it('持久化文件损坏时降级为空状态并可通过保存覆盖', async () => {
+    const scope = 'corrupt_state';
+    const config = { cachebase: { persist: true, dir: tmp_dir, auto_save: false } };
+    const file = path.join(tmp_dir, `${scope}.json`);
+    fs.writeFileSync(file, '{ 这不是合法的 JSON', 'utf8');
+
+    // 损坏文件的加载错误属于预期行为，屏蔽底层错误日志
+    const error_spy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      const state = createState(scope, config);
+      expect(await state.list()).toEqual({});
+      expect(await state.set('1001', user_1001)).toBe(true);
+      expect(await state.save()).toBe(true);
+
+      await state.dispose();
+      cachebase_admin.clear();
+
+      const reloaded = createState(scope, config);
+      expect(await reloaded.get('1001')).toEqual(user_1001);
+    } finally {
+      error_spy.mockRestore();
+    }
+  });
+});