bff-store 0.1.0

package/docs/BUG_FIX_SESSION_2026-06-03.md

@@ -0,0 +1,171 @@
+# Bug Fix Session — 2026-06-03
+
+本次会话诊断并修复了 4 个 bug，覆盖类型解析、协议层、存储适配器三个层面。
+
+---
+
+## Bug 1 (P0): `'backend' does not exist in type 'RemoteStorageOptions'`
+
+### 现象
+
+`tests/next_test` 中 `"bff-store": "file:../../dist"` 安装时，TypeScript 报错：
+
+```
+Object literal may only specify known properties, and 'backend' does not exist in type 'RemoteStorageOptions'.ts(2353)
+```
+
+### 根因
+
+**因素一（主因）：dist/package.json 路径错误。** 根目录 `package.json` 的路径字段带有 `./dist/` 前缀：
+
+```json
+"main": "dist/index.js",
+"exports": { ".": { "types": "./dist/index.d.ts", ... } }
+```
+
+当通过 `"file:../../dist"` 本地安装时，包根目录就是 `dist/` 本身，`./dist/index.d.ts` 解析为 `dist/dist/index.d.ts` —— 文件不存在。
+
+| 场景 | 包根目录 | `./dist/index.d.ts` 解析 | 存在? |
+|------|----------|-------------------------|------|
+| npm 发布 | 项目根 | `项目根/dist/index.d.ts` | 是 |
+| `file:../../dist` | `dist/` | `dist/dist/index.d.ts` | 否 |
+
+**因素二（助推）：全局安装了旧版本。** 本地 symlink 解析失败后，TypeScript 沿目录树向上查找，在 `/Users/Admin/node_modules/bff-store/` 找到旧版 v0.1.1，该版本 `RemoteStorageOptions` 无 `backend` 字段。
+
+### 修复
+
+1. **新增** `scripts/adapt-dist-package.js` — 构建后将 `dist/package.json` 路径改写为相对 dist/：
+   - `dist/index.js` → `index.js`
+   - `./dist/index.d.ts` → `./index.d.ts`
+   - `./dist/storage/...` → `./storage/...`
+
+2. **修改** `package.json` build 脚本：
+   ```
+   "build": "tsup && cp package.json dist/package.json && node scripts/adapt-dist-package.js && for f in dist/*.d.mts; do cp \"$f\" \"${f%.d.mts}.d.ts\"; done"
+   ```
+
+### 涉及文件
+
+| 文件 | 操作 |
+|------|------|
+| `scripts/adapt-dist-package.js` | 新增 |
+| `package.json` | 修改 build 脚本 |
+
+---
+
+## Bug 2 (P0): GET/DELETE 请求拿不到 `mongoUrl`
+
+### 现象
+
+BFF 模式下，POST (`/storage/set`) 正常，但 GET (`/storage/get`) 返回：
+
+```
+{"error":"Error: mongoUrl is required for mongodb backend"}
+```
+
+### 根因
+
+`src/storage/protocol.ts` 的 `buildUrl` / `buildBatchGetUrl` / `buildBatchSetUrl` 方法只将 `backend` 和 `entityId` 拼入 URL query params，`mongoUrl`、`mongoDb`、`jsonlDir` 仅通过 POST body 传递（`createStorageWithProtocol` 中将 `backendConfig` spread 到 body）。
+
+GET/DELETE 无 body → server 端 `resolveStorage` 从 URL query params 解析不到 `mongoUrl` → 尝试 `mongodbStorage({ url: undefined })` → 抛错。
+
+### 修复
+
+抽取 `appendBackendParams()` 方法，将全部 backend 参数拼入 URL query params：
+
+```typescript
+private appendBackendParams(params: URLSearchParams): void {
+  if (this.backendConfig.backend)   params.set('backend', this.backendConfig.backend);
+  if (this.backendConfig.mongoUrl)  params.set('mongoUrl', this.backendConfig.mongoUrl);
+  if (this.backendConfig.mongoDb)   params.set('mongoDb', this.backendConfig.mongoDb);
+  if (this.backendConfig.jsonlDir)  params.set('jsonlDir', this.backendConfig.jsonlDir);
+}
+```
+
+### 涉及文件
+
+| 文件 | 操作 |
+|------|------|
+| `src/storage/protocol.ts` | 新增 `appendBackendParams()`，`buildUrl` / `buildBatchGetUrl` / `buildBatchSetUrl` 调用之 |
+
+---
+
+## Bug 3 (P2): JSONL adapter 静默失败（entityId 默认 null）
+
+### 现象
+
+BFF server 使用 JSONL backend 时，SET 返回 `{"success":true}` 但数据未写入磁盘，GET 返回 `{"value":null}`。
+
+### 根因
+
+`src/storage/jsonl.ts` 中 `entityId` 初始值为 `null`，GET 和 SET 操作均有 `if (!entityId) return` 守卫，导致静默跳过。对比 MongoDB adapter 默认 `currentEntityId = 'default'`，行为不一致。
+
+### 修复
+
+```typescript
+// Before
+let entityId: string | null = null;
+
+// After
+let entityId: string = 'default';
+```
+
+### 涉及文件
+
+| 文件 | 操作 |
+|------|------|
+| `src/storage/jsonl.ts` | `entityId` 默认值 `null` → `'default'` |
+
+---
+
+## Bug 4 (P2): MongoDB 副本集连接失败
+
+### 现象
+
+BFF server 连接 MongoDB 时报：
+
+```
+MongoServerSelectionError: connection <monitor> to 172.16.42.101:27017 closed
+TopologyDescription { type: 'ReplicaSetNoPrimary', setName: 'rs0' }
+```
+
+### 根因
+
+`localhost:27017` 属于副本集 `rs0`，成员地址 `172.16.42.101:27017`。MongoDB driver 自动发现副本集后切换到该地址，但该地址网络不通。
+
+### 修复
+
+在 MongoDB URL 中拼接 `?directConnection=true&authSource=admin` 绕过副本集发现。
+
+```typescript
+const mongoUrl = `mongodb://${user}:${pwd}@${host}/${db}?directConnection=true&authSource=admin`;
+```
+
+### 涉及文件
+
+| 文件 | 操作 |
+|------|------|
+| `tests/next_test/src/app/page.tsx` | 添加 URL 参数 |
+
+---
+
+## 测试覆盖
+
+| 文件 | 内容 |
+|------|------|
+| `tests/next_test/test-types.ts` | 原始 bug 用例 — `backend: 'jsonl'` |
+| `tests/next_test/test-similar-root.tsx` | 同上 .tsx 版本 |
+| `tests/next_test/test-regression-remote-storage.ts` | 全参数组合：jsonl / mongodb / 可选字段 / 默认构造 |
+| `tests/next_test/src/app/test-similar.tsx` | .tsx 中 remoteStorage 类型测试 |
+| `tests/next_test/src/app/test-regression-store.tsx` | createStore + remoteStorage 组合测试 |
+| `tests/next_test/src/app/test-mongodb.tsx` | MongoDB 前端组件测试 |
+| `tests/next_test/test-mongodb-direct.ts` | mongodbStorage 直接调用测试脚本 |
+| `tests/next_test/test-mongodb-remote.ts` | remoteStorage → MongoDB 路由测试脚本 |
+| `tests/next_test/src/app/page.tsx` | 浏览器端到端测试（可切换 jsonl/mongodb） |
+
+## 验证结果
+
+- `npm run build`（项目根）：构建成功
+- `npx tsc --noEmit`（tests/next_test）：0 errors
+- `curl` 测试 JSONL SET/GET/DELETE 全链路：通过
+- `curl` 测试 MongoDB SET/GET/DELETE 全链路：通过

package/docs/IMPLEMENTATION.md

@@ -0,0 +1,333 @@
+# 核心实现详解
+
+## 1. Storage 接口
+
+```typescript
+// src/storage/base.ts
+export interface Storage {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T): Promise<void>;
+  remove(key: string): Promise<void>;
+  getMultiple?<T>(keys: string[]): Promise<Map<string, T>>;  // 可选：批量读取
+  setMultiple?<T>(entries: Map<string, T>): Promise<void>;    // 可选：批量写入
+}
+```
+
+所有存储适配器都实现此接口，实现存储层的可插拔。
+
+### 1.1 JSONL 存储
+
+**文件结构**: `{dir}/{entityId}/{key}.jsonl`
+
+每行一条 JSON，方便追溯历史和追加写入：
+
+```jsonl
+{"key":"theme","value":"科幻小说","timestamp":1704067200000}
+{"key":"theme","value":"奇幻小说","timestamp":1704067201000}
+```
+
+读取时取最后一行（最新值），写入时 append。
+
+```typescript
+// src/storage/jsonl.ts
+export function jsonlStorage(options?: JsonlStorageOptions): JsonlStorageInstance {
+  const baseDir = options?.dir ?? './sessions';
+
+  const storage: Storage = {
+    async get<T>(key: string): Promise<T | null> {
+      const filePath = getFilePath(entityId, key);
+      if (!fs.existsSync(filePath)) return null;
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const lines = content.trim().split('\n').filter(Boolean);
+      if (lines.length === 0) return null;
+
+      // 取最后一行
+      const lastLine = lines[lines.length - 1];
+      const entry: JsonlEntry = JSON.parse(lastLine);
+      return entry.value as T;
+    },
+
+    async set<T>(key: string, value: T): Promise<void> {
+      const filePath = getFilePath(entityId, key);
+      const entry = { key, value, timestamp: Date.now() };
+      const line = JSON.stringify(entry) + '\n';
+      fs.appendFileSync(filePath, line, 'utf-8');
+    },
+  };
+
+  return { storage, name: 'jsonl', setEntityId };
+}
+```
+
+### 1.2 MongoDB 存储
+
+使用 MongoDB 的 append-only 模式，每次写入插入新文档，读取时取最新：
+
+```typescript
+// src/storage/mongodb.ts
+const storage: Storage = {
+  async get<T>(key: string): Promise<T | null> {
+    const entry = await collection.findOne(
+      { key },
+      { sort: { timestamp: -1 } }  // 按时间倒序，取第一条
+    );
+    return entry?.value as T ?? null;
+  },
+
+  async set<T>(key: string, value: T): Promise<void> {
+    await collection.insertOne({
+      key,
+      value,
+      timestamp: Date.now(),
+    });
+  },
+};
+```
+
+---
+
+## 2. Atom 创建器
+
+### 2.1 核心逻辑
+
+```typescript
+// src/atomCreator.ts
+export function createPersistedAtom<T>(
+  config: AtomConfig<T>,
+  storage: Storage,
+  options?: { immediate?: boolean; debounceMs?: number }
+): PersistedAtomWithLoading<T> {
+  // 1. 创建基础 atom
+  const baseAtom = atom<T>(config.defaultValue);
+  const loadingAtom = atom<boolean>(true);
+
+  // 2. onMount 时从 storage 加载初始值
+  baseAtom.onMount = (setValue) => {
+    storage.get<T>(config.key)
+      .then((value) => {
+        if (value !== null) setValue(value);
+      })
+      .finally(() => {
+        store.set(loadingAtom, false);  // 标记加载完成
+      });
+  };
+
+  // 3. 创建写 atom，自动持久化
+  const writeAtom = atom(
+    (get) => get(baseAtom),
+    (get, set, update) => {
+      const newValue = typeof update === 'function'
+        ? update(get(baseAtom))
+        : update;
+
+      set(baseAtom, newValue);  // 先更新本地
+
+      // 保存到 storage
+      if (options?.immediate) {
+        storage.set(config.key, newValue);  // 立即保存
+      } else {
+        debouncedSave(config.key, newValue);  // 防抖保存
+      }
+    }
+  );
+
+  return { atom: writeAtom, loadingAtom };
+}
+```
+
+### 2.2 防抖保存
+
+使用 WeakMap 缓存每个 atom 的 debounced 函数：
+
+```typescript
+const debouncedSaveMap = new WeakMap<object, { timer: Timer; fn: Function }>();
+
+function debounce(fn: Function, ms: number): Function {
+  let timer: Timer | null = null;
+  return (...args) => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      fn(...args);
+      timer = null;
+    }, ms);
+  };
+}
+```
+
+---
+
+## 3. Store 工厂
+
+### 3.1 createStore
+
+批量创建 atoms：
+
+```typescript
+// src/createStore.ts
+export function createStore(
+  entityId: string,
+  config: AtomConfigs,
+  options?: { storage: Storage; debounceMs?: number }
+): Store {
+  const storage = options.storage;
+  const debounceMs = options.debounceMs ?? 800;
+
+  const atoms = {};
+  const loadingAtoms = {};
+
+  for (const atomConfig of config) {
+    const result = createPersistedAtom(atomConfig, storage, {
+      immediate: atomConfig.immediate,
+      debounceMs,
+    });
+    atoms[atomConfig.key] = result.atom;
+    loadingAtoms[atomConfig.key] = result.loadingAtom;
+  }
+
+  return { entityId, config, atoms, loadingAtoms };
+}
+```
+
+### 3.2 原子配置
+
+```typescript
+interface AtomConfig<T = unknown> {
+  key: string;           // 状态键名
+  defaultValue: T;       // 默认值
+  type?: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  immediate?: boolean;   // 是否立即保存（不用 debounce）
+}
+```
+
+`immediate: true` 用于 critical data（如 chapterOutline），避免 debounce 延迟。
+
+---
+
+## 4. useStore Hook
+
+### 4.1 核心实现
+
+```typescript
+// src/useStore.ts
+export function useStore(store: Store): UseStoreReturn {
+  const [isLoading, setIsLoading] = useState(true);
+
+  // 订阅所有 loading atoms
+  useEffect(() => {
+    const storeInstance = getDefaultStore();
+    const loadingAtoms = Object.values(store.loadingAtoms);
+
+    const checkLoadingStatus = () => {
+      const states = loadingAtoms.map(atom => storeInstance.get(atom));
+      setIsLoading(states.some(s => s === true));
+    };
+
+    checkLoadingStatus();
+
+    // 订阅变化
+    const unsubscribers = loadingAtoms.map(atom =>
+      storeInstance.sub(atom, checkLoadingStatus)
+    );
+
+    return () => unsubscribers.forEach(unsub => unsub());
+  }, [store.loadingAtoms]);
+
+  // 为每个 atom 调用 useAtom
+  const result = {};
+  for (const config of store.config) {
+    const [value, setter] = useAtom(store.atoms[config.key]);
+    result[config.key] = value;
+    result[`set${capitalize(config.key)}`] = setter;
+  }
+
+  return { ...result, isLoading };
+}
+```
+
+### 4.2 使用示例
+
+```typescript
+const config = [
+  { key: 'theme', defaultValue: '' },
+  { key: 'characters', defaultValue: [] },
+] as const;
+
+const store = createStore('novel-123', config, { storage });
+
+function NovelEditor() {
+  const { theme, characters, setTheme, setCharacters, isLoading } = useStore(store);
+
+  if (isLoading) return <Loading />;
+
+  return (
+    <div>
+      <input value={theme} onChange={e => setTheme(e.target.value)} />
+      <CharacterList characters={characters} onUpdate={setCharacters} />
+    </div>
+  );
+}
+```
+
+---
+
+## 5. 类型系统
+
+### 5.1 类型导出
+
+```typescript
+// src/types.ts
+export interface Store {
+  entityId: string;
+  config: AtomConfigs;
+  atoms: StoreAtoms;
+  loadingAtoms: StoreLoadingAtoms;
+}
+
+export type UseStoreReturn = Record<string, any> & { isLoading: boolean };
+```
+
+### 5.2 类型安全
+
+虽然使用了 `as const` 和泛型，但由于 JavaScript 动态特性，返回类型使用 `Record<string, any>` 保证灵活性。
+
+---
+
+## 6. 数据流
+
+```
+用户操作
+    │
+    ▼
+useStore Hook
+    │
+    ├── useAtom(store.atoms.xxx) → 更新 React 组件
+    │
+    ▼
+writeAtom (jotai)
+    │
+    ├── set(baseAtom, newValue) → 立即更新本地状态
+    │
+    ▼
+debouncedSave / storage.set()
+    │
+    ▼
+Storage Adapter (JSONL / MongoDB / Memory)
+    │
+    ▼
+持久化存储
+```
+
+---
+
+## 7. 与原系统对比
+
+| 特性 | 原系统 (novel-simple-persist.ts) | 新系统 (bff-store) |
+|------|--------------------------------|--------------------------|
+| 配置方式 | 硬编码 ATOM_CONFIGS | 数组配置，通用 |
+| 存储层 | API 调用 (enhancedNovelClientAPI) | 可插拔 Adapter |
+| 单例模式 | NovelAtomsSingleton 强制单例 | 可选，不强制 |
+| MongoDB | 通过 API | 直连 |
+| JSONL | 无 | 原生支持 |
+| 加载状态 | loadingAtoms | loadingAtoms |
+| Debounce | 800ms | 可配置 |

package/docs/PLAN.md

@@ -0,0 +1,153 @@
+# Plan: 提取 Jotai 状态管理为独立工具包 `bff-store`
+
+## Context
+
+当前项目 `pro_novel` 中有一套基于 jotai 的状态管理系统，分散在 `persist.ts` 和 `novel-simple-persist.ts` 中。存在以下问题：
+- 与业务强耦合，难以跨项目复用
+- 存储层耦合了 API（`enhancedNovelClientAPI`）
+- 单例模式固定，难以按需使用
+
+**目标**: 提取为独立 npm 包，配置驱动批量创建 atoms，存储层可插拔（默认 JSONL）。
+
+---
+
+## 核心 API 设计
+
+```typescript
+// 1. 状态配置数组 - 一次定义多个状态
+const config = [
+  { key: 'theme', defaultValue: '' },
+  { key: 'characters', defaultValue: [] },
+  { key: 'chapters', defaultValue: [] },
+] as const;
+
+// 2. 创建 store 实例
+const store = createStore('novel-123', config, {
+  storage: jsonlStorage({ dir: './sessions' }),  // 默认
+  // storage: mongodbStorage({ url: 'mongodb://...' }),
+  debounceMs: 800,
+});
+
+// 3. React Hook 使用
+function NovelEditor() {
+  const { theme, characters, setTheme, setCharacters } = useStore(store);
+}
+
+// 4. 非 React 环境直接操作 atoms
+store.atoms.theme.set('new theme');
+```
+
+---
+
+## 目录结构
+
+```
+bff-store/
+├── src/
+│   ├── index.ts                    # 公共 API 导出
+│   ├── types.ts                    # 类型定义
+│   ├── createStore.ts              # 核心工厂函数
+│   ├── useStore.ts                 # React Hook
+│   ├── atomCreator.ts              # 单个 atom 创建逻辑
+│   └── storage/
+│       ├── base.ts                 # Storage interface
+│       ├── memory.ts               # 内存存储（开发用）
+│       ├── jsonl.ts                # JSONL 文件存储（默认）
+│       └── mongodb.ts              # MongoDB 存储（可选）
+├── docs/
+│   └── PLAN.md                     # 本文档
+├── package.json
+└── README.md
+```
+
+---
+
+## 实现步骤
+
+### Step 1: 创建基础类型和接口 (`types.ts`, `storage/base.ts`)
+
+- 定义 `AtomConfig` - 单个状态配置 `{ key, defaultValue, type?, immediate? }`
+- 定义 `Storage` interface - `get(key)`, `set(key, value)`, `remove(key)`
+- 定义 `StoreOptions` - 存储适配器、debounce 配置
+
+### Step 2: 实现存储适配器 (`storage/`)
+
+| 文件 | 职责 |
+|------|------|
+| `memory.ts` | 内存 Map，简单开发/测试用 |
+| `jsonl.ts` | JSONL 文件存储，按 entityId 分文件，`sessions/{entityId}/{key}.jsonl` |
+| `mongodb.ts` | MongoDB 存储，collection per entityId |
+
+**JSONL 格式** (每行一条 JSON):
+```
+{"key":"theme","value":"科幻小说","timestamp":1704067200000}
+{"key":"theme","value":"奇幻小说","timestamp":1704067201000}
+```
+
+### Step 3: 实现 atom 创建器 (`atomCreator.ts`)
+
+- `createPersistedAtom(config, storage, options)` → 返回 `{ atom, loadingAtom }`
+- onMount 时从 storage 加载初始值
+- 写入时 debounce 保存到 storage
+
+### Step 4: 实现 store 工厂 (`createStore.ts`)
+
+- 输入: `entityId`, `config[]`, `options`
+- 批量创建 atoms，返回 `{ atoms, loadingAtoms }`
+- 支持分片并发创建（复用现有 `createAtomsInChunks` 逻辑）
+
+### Step 5: 实现 React Hook (`useStore.ts`)
+
+- `useStore(store)` - 自动订阅所有 atoms
+- 返回 `{ ...data, ...setters, isLoading }`
+- 优化: useMemo 缓存返回值，避免不必要的 re-render
+
+### Step 6: 导出公共 API (`index.ts`)
+
+```typescript
+export { createStore, useStore };
+export { jsonlStorage, mongodbStorage, memoryStorage };
+export type { AtomConfig, Store, Storage, StoreOptions };
+```
+
+---
+
+## 关键文件修改
+
+| 文件 | 操作 |
+|------|------|
+| `src/app/store/persist.ts` | 保留基础版，工具包独立后可删除 |
+| `src/app/store/novel-simple-persist.ts` | 逐步迁移到工具包 |
+
+---
+
+## 验证方案
+
+1. **单元测试**: `vitest` 测试 atom 创建、存储适配器
+2. **集成测试**: 创建 mock store，验证 CRUD + Hook 联动
+3. **手动验证**: 在现有项目中引入工具包，替换 `novel-simple-persist.ts`
+
+---
+
+## 实现状态
+
+✅ 已完成：
+- [x] 项目脚手架 (package.json, tsconfig.json)
+- [x] 类型定义 (types.ts)
+- [x] 存储接口 (storage/base.ts)
+- [x] 存储适配器 (memory.ts, jsonl.ts, mongodb.ts)
+- [x] atom 创建器 (atomCreator.ts)
+- [x] store 工厂 (createStore.ts)
+- [x] React Hook (useStore.ts)
+- [x] 公共 API 导出 (index.ts)
+- [x] 构建配置和输出
+- [x] README.md
+
+---
+
+## 下一步
+
+1. 编写单元测试 (vitest)
+2. 在 pro_novel 项目中引入工具包
+3. 改造 `novel-simple-persist.ts` 使用新工具包
+4. 考虑添加更多存储适配器 (IndexedDB, Redis 等)