bff-store 0.1.0 → 0.1.2

package/docs/BUG_FIX_MONGODB_CHILD_PROCESS.md

@@ -0,0 +1,129 @@
+# BUG: child_process / mongodb 错误
+
+**日期**: 2026-06-03
+
+## 问题现象
+
+Next.js 构建时报错：
+```
+Module not found: Can't resolve 'child_process'
+./tests/next_test/node_modules/mongodb/lib/client-side-encryption/mongocryptd_manager.js:38
+const { spawn } = require('child_process');
+```
+
+## 根因分析
+
+**不是本次改动引起的，是之前就存在的依赖架构问题。**
+
+### 1. bff-store 的 `package.json` 把 mongodb 放在 `dependencies`
+
+```json
+// bff-store/package.json
+{
+  "dependencies": {
+    "mongodb": "^6.21.0"
+  }
+}
+```
+
+### 2. next_test 通过 `file:` 路径安装 bff-store
+
+```json
+// next_test/package.json
+{
+  "bff-store": "file:../../dist"
+}
+```
+
+### 3. npm install 时把 mongodb 也装进了 next_test/node_modules
+
+```
+next_test/node_modules/mongodb/   ← 被安装了
+```
+
+### 4. Next.js/Webpack 在静态分析时解析到了 mongodb
+
+即使 `dist/index.mjs` 实际不引用 mongodb（`tsup external: ['mongodb']`），但 Next.js 的 bundler 在分析依赖时看到了 `node_modules/mongodb`，尝试解析它，然后触发了 `child_process` 的引用。
+
+## 验证
+
+- `dist/index.mjs` 实际 bundle：干净（0 个 mongodb 引用）
+- tsup 的 external 配置：正确（mongodb 被 external）
+- 清理 next_test 的 `node_modules` 和 `package-lock.json` 后重装，mongodb 没再被安装，构建成功
+
+## 结论
+
+| 环节 | 状态 |
+|------|------|
+| 本次新增代码（environment.ts、nodeStore.ts）| 无问题 |
+| `dist/index.mjs` 实际 bundle | 干净（0 个 mongodb 引用）|
+| tsup 的 external 配置 | 正确（mongodb 被 external）|
+| **根本原因** | `package.json` 的 `dependencies` 里有 mongodb |
+
+这是之前就存在的问题，只是以前 next_test 可能没走到触发这个解析的代码路径。
+
+## 修复（2026-06-03）
+
+已将 `mongodb` 从 `package.json` 的 `dependencies` 移到 `devDependencies`。
+
+**原因**：
+- `tsup` 构建 `mongodb-entry.ts` 时会将 mongodb 打包进 `dist/storage/mongodb-entry.js`
+- 根 `package.json` 的 `dependencies` 不需要 mongodb
+- npm install 时不会为消费者安装 devDependencies，所以 next_test 不再被强制安装 mongodb
+
+**修复后验证**：
+- next_test 重新 `npm install` 后，`node_modules/mongodb` 不存在
+- Next.js 构建成功，无 `child_process` 错误
+
+---
+
+## 问题二：Can't resolve 'bff-store'
+
+**日期**: 2026-06-03
+
+### 问题现象
+
+Next.js dev 时报错：
+```
+Module not found: Can't resolve 'bff-store'
+import { createStore, useStore, remoteStorage } from 'bff-store';
+```
+
+### 根因分析
+
+`package.json` exports 的 `require` 字段指向不存在的文件：
+
+```json
+"exports": {
+  ".": {
+    "types": "./dist/index.d.ts",
+    "import": "./dist/index.mjs",
+    "require": "./dist/index.js"  // ← 这个文件不存在！
+  }
+}
+```
+
+tsup 只生成 ESM（`.mjs`），没有生成 CJS（`.js`）。但 exports 里写了 `require` 字段指向 `index.js`，Node.js CJS resolver 尝试解析时找不到文件就报错了。
+
+### 修复
+
+移除 exports 中的 `require` 字段（ESM-only 库）：
+
+```json
+"exports": {
+  ".": {
+    "types": "./dist/index.d.ts",
+    "import": "./dist/index.mjs"
+  }
+}
+```
+
+### ESM-only 的影响
+
+| 方式 | 支持 |
+|------|------|
+| `import from 'bff-store'` | ✅ 正常 |
+| `node --input-type=module` + import | ✅ 正常 |
+| `const x = require('bff-store')` | ❌ 报错 |
+
+bff-store 主打 React + 新项目，用 ESM 语法不受影响。老项目用 `require` 的场景暂不支持。

package/docs/FRONTEND_BACKEND_ISOLATION.md

@@ -0,0 +1,150 @@
+# 前端/后端隔离机制
+
+## 概述
+
+bff-store 通过构建配置和 package.json exports 条件导出实现前端/后端隔离，确保 Node.js 特有模块（fs、mongodb）不会进入前端 bundle。
+
+---
+
+## 1. 构建层面隔离（tsup）
+
+tsup.config.ts 定义了 5 个独立的构建入口：
+
+| 入口 | 输出 | external |
+|------|------|----------|
+| `src/index.ts` | `dist/index.mjs` | `react, jotai, mongodb` |
+| `src/storage/jsonl-entry.ts` | `dist/storage/jsonl-entry.mjs` | `react, jotai` |
+| `src/storage/mongodb-entry.ts` | `dist/storage/mongodb-entry.mjs` | `react, jotai` |
+| `src/server/entry.ts` | `dist/server/entry.mjs` | `react, jotai` |
+| `src/server/cli.ts` | `dist/cli.js` | `react, jotai` + noExternal: mongodb |
+
+**关键**：主入口的 tsup external 里标了 `mongodb`，所以 `dist/index.mjs` 不会打包 mongodb。fs 同理。
+
+---
+
+## 2. package.json 条件导出
+
+```json
+"exports": {
+  ".": {
+    "types": "./dist/index.d.ts",
+    "import": "./dist/index.mjs",
+    "require": "./dist/index.js"
+  },
+  "./jsonl": {
+    "types": "./dist/storage/jsonl-entry.d.ts",
+    "import": "./dist/storage/jsonl-entry.mjs",
+    "require": "./dist/storage/jsonl-entry.js"
+  },
+  "./mongodb": {
+    "types": "./dist/storage/mongodb-entry.d.ts",
+    "import": "./dist/storage/mongodb-entry.mjs",
+    "require": "./dist/storage/mongodb-entry.js"
+  },
+  "./server": {
+    "types": "./dist/server/entry.d.ts",
+    "import": "./dist/server/entry.mjs",
+    "require": "./dist/server/entry.js"
+  }
+}
+```
+
+用户不主动 `import from 'bff-store/jsonl'` 或 `bff-store/mongodb'`，就拿不到包含 fs/mongodb 的模块。
+
+---
+
+## 3. 主入口 index.ts 干净
+
+`src/index.ts` 只导出前端安全的模块：
+
+- `createStore`, `useStore`, `createPersistedAtom`
+- `memoryStorage`, `remoteStorage`
+- `isNode`, `isBrowser`, `createNodeStore`
+
+**没有**引用 `jsonl.ts` 或 `mongodb.ts`。
+
+---
+
+## 4. 引用 fs/mongodb 的文件
+
+| 文件 | 引用 |
+|------|------|
+| `src/storage/jsonl.ts` | `import * as fs from 'fs'` |
+| `src/storage/mongodb.ts` | `import { MongoClient } from 'mongodb'` |
+| `src/server/index.ts` | `import { mongodbStorage } from '../storage/mongodb'` |
+
+这些文件**只会被** `jsonl-entry.ts`、`mongodb-entry.ts`、`server/entry.ts` 引用，不会被主入口 `index.ts` 引用。
+
+### 为什么 index.ts 不引用 fs/mongodb 很重要？
+
+**不是"空间换时间"，是避免运行时错误。**
+
+tsup 的 `external` 配置是保险，但 `import` 语句本身就会触发模块解析：
+
+```typescript
+// index.ts 如果这样写
+import * as fs from 'fs';  // ← 加了这行
+export { createStore } from './createStore';
+```
+
+1. tsup external 会让 fs 代码不打包进 bundle
+2. 但 bundler（webpack/rollup）看到 `import` 语句仍会尝试解析
+3. Next.js 环境有 node_modules/fs → 解析成功，但运行时会出问题
+4. 纯浏览器环境没有 fs → 运行时直接报错
+
+**不让源头存在，比靠 external 兜底更安全。**
+
+---
+
+## 5. createNodeStore 的安全性
+
+`createNodeStore` 在 `src/nodeStore.ts` 中实现，它的 import：
+
+```typescript
+import { getDefaultStore } from 'jotai';
+import { createStore } from './createStore';
+import type { AtomConfigs, StoreAtoms, StoreLoadingAtoms } from './types';
+import type { StorageAdapter } from './storage/base';
+```
+
+**没有**引用 fs 或 mongodb，所以即使在 index.ts 中导出，前端也不会被打包进去。
+
+---
+
+## 6. 之前 mongodb 进 next_test 的原因
+
+不是代码问题，是 **package.json dependencies** 的问题。
+
+```json
+// 原先的 package.json
+{
+  "dependencies": {
+    "mongodb": "^6.21.0"  // ← 问题在这里
+  }
+}
+```
+
+next_test 通过 `file:../../dist` 安装 bff-store 时，npm install 会安装 `dependencies` 中的包，导致 mongodb 被装进 next_test/node_modules，即使用不到也会被 Next.js bundler 解析到。
+
+**修复**：将 mongodb 移到 `devDependencies`，因为 tsup 构建时会把它打包进 `dist/storage/mongodb-entry.js`，不需要作为独立依赖安装。
+
+---
+
+## 验证方法
+
+### 检查主入口是否干净
+```bash
+grep -c "mongodb" dist/index.mjs  # 应为 0
+grep -c "fs" dist/index.mjs        # 应为 0
+```
+
+### 检查子入口是否包含目标模块
+```bash
+grep -c "mongodb" dist/storage/mongodb-entry.mjs  # 应 > 0
+grep -c "fs" dist/storage/jsonl-entry.mjs          # 应 > 0
+```
+
+### 检查 next_test 是否被安装 mongodb
+```bash
+ls node_modules/mongodb  # 应不存在
+```

package/docs/IMPLEMENTATION_OVERVIEW.md

@@ -0,0 +1,231 @@
+# 实现大纲 / Implementation Overview
+
+> 本文档反映 2026-07-05 post-mortem 修复后的实现状态。
+
+---
+
+## 架构概览
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Frontend / React                                       │
+│  createStore() → useStore() → atoms (jotai)            │
+└────────────────────────┬────────────────────────────────┘
+                         │ storage API (HTTP or direct)
+┌────────────────────────▼────────────────────────────────┐
+│  BFF Server (Node.js sidecar)                           │
+│  Router → Handlers → Storage Cache                     │
+└────────────────────────┬────────────────────────────────┘
+                         │ storage adapter
+┌────────────────────────▼────────────────────────────────┐
+│  Storage Backend                                        │
+│  jsonl / mongodb / memory                              │
+└─────────────────────────────────────────────────────────┘
+```
+
+三层分离：
+- **前端层**：React 组件通过 `useStore` 消费 jotai atom
+- **BFF 层**：Node.js sidecar server，代理存储请求，支持多租户
+- **存储层**：可插拔后端（JSONL 文件、MongoDB、内存）
+
+---
+
+## 模块映射表
+
+| 模块 | 文件 | 职责 |
+|------|------|------|
+| `createStore` | `src/createStore.ts` | 创建多 atom 持久化 store |
+| `waitForServer` | `src/createStore.ts` | 等待 auto-start server 就绪 |
+| `createPersistedAtom` | `src/atomCreator.ts` | 单个 atom + loading 状态 |
+| `useStore` | `src/useStore.ts` | React hook，消费 store |
+| `debouncer` | `src/debouncer.ts` | 写冲突防抖（800ms default，ms 不一致时替换实例） |
+| `remoteStorage` | `src/storage/adapters/remoteStorage.ts` | 客户端 HTTP 适配器 |
+| `HttpTransport` | `src/storage/transport.ts` | HTTP GET/POST/DELETE 原语（含错误详情提取） |
+| `RestStorageProtocol` | `src/storage/protocol.ts` | REST 风格协议封装（支持 live entityId 引用） |
+| `startServer` | `src/server/index.ts` | BFF 服务端单例启动 |
+| `createStorageHandlers` | `src/server/handlers.ts` | 请求 → storage 分发 + 缓存 + 过期清理 |
+| `Router` | `src/server/router.ts` | 路径 → handler 匹配（:key 参数） |
+| `EntityIdCache` | `src/server/entityIdCache.ts` | JSONL 多租户隔离 |
+| `jsonlStorage` | `src/storage/jsonl.ts` | 文件落盘 `{dir}/{entityId}/{encodeURIComponent(key)}.jsonl` |
+| `mongodbStorage` | `src/storage/mongodb.ts` | MongoDB 落盘 `state_{entityId}` collection，upsert 模式 |
+| `memoryStorage` | `src/storage/memory.ts` | 内存存储（测试/开发） |
+| `createNodeStore` | `src/nodeStore.ts` | Node.js 环境专用（非 React），含 5s 超时 waitForLoad |
+
+---
+
+## 数据流详解
+
+### 1. 初始化流程
+
+```typescript
+const store = createStore('entity-A', config, { storage: adapter });
+
+// 内部执行
+adapter.setEntityId('entity-A')           // 设置租户 ID
+for (atomConfig of config) {
+  createPersistedAtom(atomConfig, entityId, storage, { debounceMs })
+  // → 创建 baseAtom（初始值 defaultValue）
+  // → 创建 loadingAtom（初始值 true）
+  // → baseAtom.onMount = (setValue, unmount) => {
+  //     storage.get(key).then(setValue).catch(console.error)
+  //     return () => debouncerMap.cancel(`${entityId}:${key}`)  // unmount cleanup
+  //   }
+}
+
+// remote 模式下 auto-start server（fire-and-forget）
+import('./server').then(({ startServer }) => {
+  serverInitPromise = startServer().then(() => void 0);
+});
+```
+
+### 2. 读取流程（React 组件）
+
+```
+useStore(store)
+→ buildStoreResult(store)
+  → useAtom(atom) for each config[key]
+  → baseAtom.get() // 同步返回 jotai store 中的当前值
+```
+
+**注意**：`storage.get()` 只在 `onMount` 时调用一次，结果写入 baseAtom。后续读取直接走 jotai store 内部状态，不涉及 storage。
+
+### 3. 写入流程（带防抖 + unmount 取消）
+
+```
+setTheme('dark')
+→ writeAtom.write(dark)
+  → baseAtom.set(dark)           // 本地立即更新，UI 同步响应
+  → debouncer.debounce(key, saveFn, 800ms)
+    → storage.set(key, dark)     // 延迟写入后端
+    // unmount 时：debouncerMap.cancel(`${entityId}:${key}`) 取消 pending 写入
+```
+
+- `immediate: true` 的 atom 跳过防抖，直接 `storage.set()`
+- 防抖 key 格式：`${entityId}:${config.key}`，避免跨 store 干扰
+- **ms 不一致时**：替换已有 debouncer 实例，确保延迟时间正确
+
+### 4. 远程写入（remoteStorage 路径）
+
+```
+setTheme('dark')
+→ writeAtom.write(dark)
+  → baseAtom.set(dark)
+  → debouncer.debounce(...)
+    → storage.set(key, value)
+      → HttpTransport.post('/storage/set/:key', { value, ...backendConfig })
+        → BFF server: POST /storage/set/:key
+          → handlers.handleSet()
+          → getCachedStorage(config, entityId)
+          → storage.set(key, value)
+```
+
+### 5. Node.js 服务端（BFF）
+
+```
+http.createServer()
+→ Router.handle(req, res)
+  → matched route: /storage/get/:key
+    → handlers.handleGet(req, res, { key })
+      → resolveStorage(req)        // 解析 body + url config
+      → storage.get(key)
+      → res.json({ value })
+```
+
+---
+
+## 多租户隔离策略
+
+### Server 端
+
+- **JSONL**：每个 `entityId` 对应独立目录 `{jsonlDir}/{entityId}/`
+- **MongoDB**：每个 `entityId` 对应独立 collection `state_{entityId}`
+- **Storage Cache**：`Map<cacheKey, { adapter, lastUsed }>`，TTL 5min，**full LRU 驱逐（满时全部驱逐直到有空间）**
+
+### Client 端
+
+- `remoteStorage.setEntityId(id)` 更新 `entityId.current`（live 引用，protocol 层每次请求实时读取）
+- 后续所有请求在 protocol 层拼入 query param `?entityId=xxx`
+
+---
+
+## 关键设计决策
+
+### 为什么 atom 初始值用 defaultValue 而非从 storage 加载？
+
+jotai 要求 atom 必须有同步初始值。`createPersistedAtom` 创建时传入 `defaultValue`，然后通过 `onMount` 异步从 storage 覆盖。
+
+```typescript
+const baseAtom = atom(config.defaultValue);  // 同步默认值
+baseAtom.onMount = (setValue) => {
+  storage.get(key)
+    .then((value) => { if (value != null) setValue(value); })
+    .catch((err) => { console.error(`[bff-store] Failed to load atom "${key}":`, err); })
+    .finally(() => { /* loadingAtom = false */ });
+};
+```
+
+### 为什么需要 loadingAtom？
+
+`onMount` 是异步的，React 组件可能在数据加载完成前就开始 render。`loadingAtom` 跟踪所有 atom 的加载状态，合并为 `useStore` 返回的 `isLoading` 布尔值。
+
+### 防抖 DebouncerMap 为什么用 module-level 单例？
+
+所有 atom 共享同一个 `DebouncerMap` 实例，确保同一 `entityId:key` 的多次写入只触发一次延迟保存。ms 不一致时替换已有实例。
+
+### unmount 时为什么要 cancel pending writes？
+
+组件卸载后，写入回调可能仍在计时器队列中，若不取消会导致：
+1. 写入操作在组件销毁后执行
+2. `getDefaultStore()` 在已销毁的组件上下文中被调用
+
+---
+
+## 路由表（服务端）
+
+| Method | Path | Handler |
+|--------|------|---------|
+| GET | `/storage/get/:key` | `handleGet` |
+| POST | `/storage/set/:key` | `handleSet` |
+| DELETE | `/storage/delete/:key` | `handleDelete` |
+| POST | `/storage/batch-get` | `handleBatchGet` |
+| POST | `/storage/batch-set` | `handleBatchSet` |
+| GET | `/health` | `handleHealth` |
+
+---
+
+## 已修复 Bug 清单（Post-Mortem 2026-07-05）
+
+| # | Severity | Location | Bug | Fix |
+|---|----------|----------|-----|-----|
+| 1 | High | `createStore.ts` | server 启动 fire-and-forget | 引入 `serverInitPromise` + `waitForServer()` |
+| 3 | Medium | `handlers.ts` | 缓存满时只驱逐 1 个 entry | 改为 `while` 循环直到有空间 |
+| 4 | Medium | `transport.ts` | HTTP 错误 body 丢失 | `res.clone().json()` 读取错误详情 |
+| 5 | Low | `debouncer.ts` | ms 不一致时忽略新值 | ms 不同时替换已有 debouncer |
+| 7 | High | `jsonl.ts` | `.` `-` 等分隔符替换为 `_` 导致 key 碰撞 | 改用 `encodeURIComponent(key)` |
+| 8 | Medium | `handlers.ts` | `getStorageForRequest` 死代码 | 已删除 |
+| 9 | Low | `nodeStore.ts` | `waitForLoad` 无限等待 | 添加 5s 超时 reject |
+| 10 | Low | `handlers.ts` | `parseBody` 失败静默忽略 | 改为 `console.warn` |
+| 11 | High | `mongodb.ts` | `insertOne` 无限积累旧版本 | 改用 `updateOne` + `upsert: true` |
+| 12 | High | `remoteStorage.ts` | `setEntityId` 不生效（闭包捕获快照） | 传入对象引用 `{ current }` |
+| 14 | Low | `server/index.ts` | `isServerRunning()` 未使用 | 已删除 |
+| 15 | Medium | `atomCreator.ts` | unmount 时 pending writes 丢失 | `onMount` 返回 cleanup 调用 `cancel()` |
+| 17 | Low | `handlers.ts` | `handleHealth` 参数未使用 | `req` → `_req` |
+| 18 | Low | `atomCreator.ts` | storage.get 失败静默忽略 | 添加 `console.error` 记录 |
+
+### 未修复（设计选择）
+
+| # | Reason |
+|---|--------|
+| BUG-6 | module-level `debouncerMap` 通过 `entityId:key` 隔离键名，实际无跨 store 干扰 |
+| BUG-13 | `createStorageFromTransport.get` 所有错误返回 null — 符合 storage graceful degradation 哲学 |
+
+---
+
+## 配置文件
+
+| 文件 | 用途 |
+|------|------|
+| `tsup.config.ts` | 多入口打包（index, jsonl-entry, mongodb-entry, server/entry, cli） |
+| `tsconfig.json` | TypeScript 配置 |
+| `vitest.config.ts` | 测试配置 |
+| `package.json` | 导出字段：`import` → `dist/index.mjs` |

package/docs/LOCAL_LINK_STRATEGIES.md

@@ -0,0 +1,117 @@
+# 本地包链接策略
+
+## 背景
+
+开发 bff-store 时，需要在项目中测试自己的包。常见的链接方式有三种。
+
+---
+
+## 方式一：`file:` 路径（当前使用）
+
+### 配置
+
+```json
+// tests/next_test/package.json
+{
+  "dependencies": {
+    "bff-store": "file:../../dist"
+  }
+}
+```
+
+npm install 后会创建 symlink：
+
+```
+tests/next_test/node_modules/bff-store -> bff-store/dist
+```
+
+### 优点
+- 简单直接，改完 `npm run build` 就生效
+- 无需额外命令
+
+### 缺点
+- 不是真实 npm 安装行为，可能有边界情况
+- 路径固定，不够灵活
+
+---
+
+## 方式二：`npm link`（推荐本地开发）
+
+### 配置
+
+```bash
+# 1. 在 bff-store 目录注册全局链接
+cd bff-store
+npm link
+
+# 2. 在目标项目链接全局包
+cd tests/next_test
+npm link bff-store
+```
+
+### 原理
+
+```
+bff-store/ (全局注册的包)
+    ↓
+tests/next_test/node_modules/bff-store -> 全局包的 symlink
+```
+
+### 优点
+- 更接近真实 npm 安装行为
+- 全局一份，多个项目共用
+- 可同时开发多个相互依赖的包
+
+### 缺点
+- 需要两条命令
+- 全局状态管理可能混乱
+
+### 清理
+
+```bash
+cd tests/next_test
+npm unlink bff-store
+
+cd bff-store
+npm link remove bff-store
+```
+
+---
+
+## 方式三：发布到 npm（正式发布）
+
+### 配置
+
+```bash
+# 1. 登录 npm
+npm login
+
+# 2. 发布（需要 package.json 的 name 是唯一的）
+npm publish
+
+# 3. 在项目中使用
+npm install bff-store
+```
+
+### 优点
+- 真实用户安装方式
+- 版本管理规范
+
+### 缺点
+- 需要 npm 账号
+- 版本管理，每次改动都要发版
+- 发布后不能即时生效
+
+---
+
+## 总结
+
+| 方式 | 即时生效 | 配置复杂度 | 接近真实安装 |
+|------|---------|-----------|------------|
+| `file:` | ✅ | 简单 | 一般 |
+| `npm link` | ✅ | 中等 | ✅ |
+| `npm publish` | ❌ | 需要版本管理 | ✅ |
+
+**本地开发推荐**：`npm link` 或保持 `file:`
+
+**正式发布**：用 `npm publish`

package/docs/bugs/01-server-async-startup.high.md

@@ -0,0 +1,34 @@
+# BUG-01: server 异步启动未等待
+
+**Severity**: High
+**Location**: `src/createStore.ts:47-53`
+**Type**: Async Fire-and-Forget
+
+## 问题
+
+`createStore` 中对 `remote` 存储类型自动启动 server 时，使用 `import().then()` 的 fire-and-forget 模式：
+
+```typescript
+import('./server').then(({ startServer }) => {
+  serverInitPromise = startServer().then(() => void 0).catch(...);
+});
+```
+
+`createStore` 是同步函数，立即返回，但 server 可能尚未启动完成，导致后续 remote storage 操作立即失败。
+
+## 修复
+
+引入 module-level `serverInitPromise` 追踪启动状态，并导出 `waitForServer()` 供调用者等待：
+
+```typescript
+let serverInitPromise: Promise<unknown> | null = null;
+
+export function waitForServer(): Promise<void> | undefined {
+  return serverInitPromise as Promise<void> | undefined;
+}
+```
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (69 passed)

package/docs/bugs/03-storage-cache-eviction.md

@@ -0,0 +1,40 @@
+# BUG-03: storage cache 驱逐不充分
+
+**Severity**: Medium
+**Location**: `src/server/handlers.ts:85-96`
+**Type**: Cache Eviction
+
+## 问题
+
+缓存满时（`MAX_CACHE_SIZE=10`）只驱逐 1 个最旧 entry，但新 adapter 创建后会再次超过限制：
+
+```typescript
+if (storageCache.size >= MAX_CACHE_SIZE) {
+  storageCache.delete(oldestKey);  // 只删 1 个
+}
+// 再次 check: size 可能仍 >= MAX_CACHE_SIZE
+```
+
+## 修复
+
+改为 `while` 循环，直到有空间：
+
+```typescript
+while (storageCache.size >= MAX_CACHE_SIZE && storageCache.size > 0) {
+  let oldestKey: string | null = null;
+  let oldestTime = Infinity;
+  for (const [k, entry] of storageCache.entries()) {
+    if (entry.lastUsed < oldestTime) {
+      oldestTime = entry.lastUsed;
+      oldestKey = k;
+    }
+  }
+  if (oldestKey) storageCache.delete(oldestKey);
+  else break;  // 防止无限循环
+}
+```
+
+## 验证
+
+- Build: ✅
+- Tests: ✅ (69 passed)