@whispering233/ai-editor-db 0.0.1

package/dist/queries/migration.js

@@ -0,0 +1,260 @@
+// @whispering233/ai-editor-db schema 演进：删库重建（S1.1）+ 未来版本拒绝（E4）+ 增量迁移（E5）
+//
+// 单一事实来源：doc/design/decisions.md 决策 13（MVP 删库重建 + E5 增补「v0.1.0 发布终止
+// 删库重建」）与修订（2026-08）——
+// - 以 data.db 的 PRAGMA user_version 为准判定版本；三态分流：
+//   - user_version === SCHEMA_VERSION → 正常打开
+//   - user_version > SCHEMA_VERSION（未来版本，E4）→ **拒绝打开**（提示升级程序，
+//     不触发任何重建/备份/写操作，数据原封不动）——堵「装新版后回退旧版 → 降级清零」
+//   - user_version < SCHEMA_VERSION（旧版本，E5）→ **有迁移路径**（MIGRATIONS 存在
+//     从当前版本到目标版本的连续链）→ runMigrations 前向迁移（数据保全，迁移前
+//     时间戳快照）；**无迁移路径** → 删库重建兜底（决策 13，备份 v{n}.bak 留档）
+// - 重建时同步重置 outline.json（先备份为 outline.json.v{n}.bak，n=旧版本号）、清空回收站
+// - 旧 data.db 一并备份为 data.db.v{n}.bak；备份带版本号、不覆盖旧备份（多次重建各自留档）
+// - project.json 的 schema_version 仅用于 JSON 结构判断（与 user_version 不同维度），重建不修改 project.json
+// - 决策 13 增补（E5）：删库重建策略于 v0.1.0 发布终止——增量迁移机制替代
+// 触发语义（doc/api/endpoints.md 第 68-70 行）：open 时检测，重建完成后向客户端提示。
+import { copyFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { closeDatabase, openDatabase } from "../connection.js";
+import { getUserVersion, SCHEMA_VERSION, setUserVersion } from "../schema.js";
+import { OUTLINE_FILE_NAME, writeOutlineFile } from "../storage/outline.js";
+import { MIGRATIONS } from "../migrations/index.js";
+/** data.db 文件名（决策 8：项目根目录，与 server middleware 的常量一致） */
+export const DATA_DB_FILE_NAME = "data.db";
+/**
+ * data.db user_version 高于当前程序版本（E4 拒绝打开专用错误）。
+ *
+ * 语义（release-review §一 风险 2）：用户安装新版程序后回退旧版 → 旧版程序打开高版本库，
+ * 若按「不匹配即重建」处理会把用户全部数据重建清零（且备份仅配合旧版本回滚，普通用户
+ * 不可自救）。E4 起该分支改为拒绝打开并抛出本错误——**不触发任何重建/备份/写操作**，
+ * 数据文件原封不动；上层（server open 路由）捕获后转 409 + 明确提示升级程序。
+ *
+ * 独立于 import 侧的 SCHEMA_VERSION_MISMATCH（备份导入校验）：本错误是**打开已存在项目**
+ * 时发现项目版本高于程序版本；SCHEMA_VERSION_MISMATCH 是导入 zip 备份时版本不匹配。
+ */
+export class SchemaVersionError extends Error {
+    /** 项目 data.db 的实际 user_version（未来版本） */
+    version;
+    /** 当前程序支持的版本 */
+    current;
+    constructor(version, current) {
+        super(`项目 data.db 版本 (${version}) 高于当前程序版本 (${current})，请升级程序后打开`);
+        this.name = "SchemaVersionError";
+        this.version = version;
+        this.current = current;
+    }
+}
+/**
+ * schema 版本检测 + 版本对齐的高层入口（open 流程调用，endpoints.md 第 68-70 行）。
+ *
+ * - user_version 与 SCHEMA_VERSION **匹配**：直接返回，db 为原连接，rebuilt=false。
+ * - user_version **> SCHEMA_VERSION（未来版本，E4）**：**拒绝打开**——关闭连接并抛
+ *   `SchemaVersionError`（提示升级程序），不触发任何重建/备份/写操作，数据原封不动。
+ * - user_version **< SCHEMA_VERSION（旧版本）**：
+ *   - **有迁移路径**（opts.migrations 中存在从当前版本到 SCHEMA_VERSION 的连续迁移链，
+ *     默认 MIGRATIONS）→ runMigrations 前向迁移（迁移前时间戳快照，数据保全完整）
+ *   - **无迁移路径** → rebuildProjectStorage 删库重建兜底（决策 13，E5 迁移机制
+ *     覆盖不到的历史版本保留；备份 v{n}.bak 留档）
+ *
+ * @param opts.migrations 迁移集注入（默认 MIGRATIONS；测试注入假迁移）
+ * @throws SchemaVersionError 未来版本拒绝打开（连接已由本函数关闭，无句柄泄漏）
+ * @throws 备份/重建/迁移过程中的 I/O 错误；迁移失败时版本停在前一迁移后（快照保留）
+ */
+export function ensureSchemaCompatible(db, dir, dbPath, opts = {}) {
+    const current = getUserVersion(db);
+    if (current === SCHEMA_VERSION) {
+        return { db, result: { rebuilt: false, toVersion: SCHEMA_VERSION, backups: [] } };
+    }
+    // E4：未来版本拒绝打开（先关连接防句柄泄漏，再抛错；数据文件零触碰）
+    if (current > SCHEMA_VERSION) {
+        closeDatabase(db);
+        throw new SchemaVersionError(current, SCHEMA_VERSION);
+    }
+    // E5：旧版本——有迁移路径 → 前向迁移（数据保全）；无迁移路径 → 重建兜底
+    if (hasMigrationPath(current, SCHEMA_VERSION, opts.migrations ?? MIGRATIONS)) {
+        try {
+            const { snapshot } = runMigrations(db, {
+                migrations: opts.migrations ?? MIGRATIONS,
+                targetVersion: SCHEMA_VERSION,
+                dbPath,
+            });
+            return {
+                db,
+                result: {
+                    rebuilt: false,
+                    migrated: true,
+                    fromVersion: current,
+                    toVersion: SCHEMA_VERSION,
+                    backups: snapshot === null ? [] : [snapshot],
+                },
+            };
+        }
+        catch (err) {
+            // ora-3 S2：迁移中途失败 → 关闭本次打开的连接（对比 E4 拒绝分支与重建分支
+            // 均关连接；迁移失败语义 = open 未生效，不留句柄）后 rethrow
+            closeDatabase(db);
+            throw err;
+        }
+    }
+    return rebuildProjectStorage(db, dir, dbPath, current);
+}
+/**
+ * 判定从 fromVersion 到 targetVersion 是否存在**连续迁移链**（E5 纯函数）：
+ * (fromVersion, targetVersion] 区间内每个版本号都恰好有迁移条目 → true。
+ * 连续性是硬要求——跳版本迁移意味着中间版本的数据形态未经处理，拒绝走迁移路径。
+ *
+ * @param migrations 迁移集（默认 MIGRATIONS；测试注入）
+ */
+export function hasMigrationPath(fromVersion, targetVersion, migrations = MIGRATIONS) {
+    // from >= target 无迁移需求（相等/未来版本由调用方分支处理），视为「无需求即有路径」
+    if (fromVersion >= targetVersion)
+        return true;
+    for (let v = fromVersion + 1; v <= targetVersion; v++) {
+        if (!migrations.some((m) => m.version === v))
+            return false;
+    }
+    return true;
+}
+/**
+ * 前向执行缺失的增量迁移（E5 核心）：
+ *
+ * 1. **迁移前快照一次**（整批；若提供 dbPath）：checkpoint 后复制 data.db →
+ *    `data.db.v{from}.{YYYYMMDDHHmmssZ}.bak`（时间戳命名，不覆盖旧备份）——
+ *    失败重试时现场保留（每次调用生成新时间戳快照，旧快照不删）
+ * 2. **逐个执行** (fromVersion, targetVersion] 区间内按 version 升序的迁移：
+ *    每个迁移一个事务（`db.transaction`）：`up(db)` + `setUserVersion(m.version)`
+ *    **原子提交**——「迁移成功 ⇒ 版本已写入；失败 ⇒ 版本未变」；失败时该迁移整体
+ *    回滚（含 DDL 与已写数据）、后续迁移不执行、异常向上传播（快照保留供重试）
+ *
+ * @param opts.dbPath data.db 绝对路径（提供则迁移前快照；缺省跳过快照——纯逻辑调用）
+ * @returns 实际执行的迁移（升序）与快照路径（未快照为 null）
+ */
+export function runMigrations(db, opts = {}) {
+    const migrations = (opts.migrations ?? MIGRATIONS).slice().sort((a, b) => a.version - b.version);
+    const targetVersion = opts.targetVersion ?? SCHEMA_VERSION;
+    const fromVersion = getUserVersion(db);
+    const pending = migrations.filter((m) => m.version > fromVersion && m.version <= targetVersion);
+    if (pending.length === 0)
+        return { applied: [], snapshot: null };
+    // 1. 迁移前快照（整批一次）：checkpoint 把 WAL 合并进主文件（连接打开期间写入的数据
+    //    在 WAL 中，直接复制主文件会缺数据）→ 复制带时间戳快照
+    let snapshot = null;
+    if (opts.dbPath !== undefined) {
+        checkpointWal(db);
+        snapshot = snapshotDbFile(opts.dbPath, fromVersion);
+    }
+    // 2. 逐个执行（每迁移一个事务，up + setUserVersion 原子）
+    const applied = [];
+    for (const m of pending) {
+        db.transaction(() => {
+            m.up(db);
+            setUserVersion(db, m.version);
+        })();
+        applied.push(m);
+    }
+    return { applied, snapshot };
+}
+/**
+ * 迁移前快照 data.db → `data.db.v{n}.{YYYYMMDDHHmmssSSSZ}.bak`（E5）：
+ * 复用 rebuild 备份的复制语义（copyFileSync 复制主文件），命名带 UTC 时间戳
+ * （含毫秒：20260804T173000.123Z）——同版本多次迁移/重试各自留档，不覆盖。
+ * WAL 一致性同 backupDbFile：调用方需先 checkpoint（runMigrations 已做）。
+ */
+export function snapshotDbFile(dbPath, fromVersion) {
+    const ts = new Date().toISOString().replace(/[-:]/g, ""); // 20260804T173000.123Z（保留毫秒）
+    const backupPath = `${dbPath}.v${fromVersion}.${ts}.bak`;
+    copyFileSync(dbPath, backupPath);
+    return backupPath;
+}
+/**
+ * WAL checkpoint（TRUNCATE）：把 WAL 内容合并回主文件并截断（busy>0 说明有其他连接
+ * 在写——MVP 单进程单连接，不检查）。供**导出前**调用（E1：release-review §二）——
+ * 保证 data.db 主文件为完整快照，导出 zip 内的 data.db 无需附带 -wal/-shm。
+ */
+export function checkpointWal(db) {
+    db.pragma("wal_checkpoint(TRUNCATE)");
+}
+/**
+ * 删库重建全流程（决策 13）：
+ *
+ * 1. **checkpoint + 关闭连接**：`wal_checkpoint(TRUNCATE)` 把 WAL 内容合并回主文件并截断，
+ *    然后关闭连接——保证后续复制的是完整快照（WAL 一致性取舍见 backupDbFile 注释）
+ * 2. **备份 data.db** → `data.db.v{n}.bak`（n=旧版本号；文件复制，原文件随后删除重建）
+ * 3. **备份 outline.json** → `outline.json.v{n}.bak`（文件复制；非 SQLite 文件无 WAL 问题，
+ *    复制保留原始字节，不存在时跳过备份）
+ * 4. **删除旧库文件**（data.db + -wal + -shm，checkpoint 后 -wal 已截断但文件仍在，一并删除）
+ * 5. **重建空库**：openDatabase（自动建表）→ setUserVersion(SCHEMA_VERSION)
+ * 6. **重置 outline.json**：写最小空树（严格三层空树，决策 19；与 T2.2 readOutlineFile
+ *    缺失语义的空树同形）——顶层 schema_version 同步写 SCHEMA_VERSION（决策 13 修订）
+ *
+ * **清空回收站**：新库四张表全空，软删行（deleted_at 非 NULL）天然不存在，无需单独操作。
+ * **project.json 不动**：其 schema_version 仅用于 JSON 结构判断（决策 13），id/name 跨启动稳定。
+ *
+ * **崩溃窗口（MVP 可接受）**：步骤 4（删除旧库）与步骤 5（重建空库）之间进程崩溃 →
+ * 磁盘上无 data.db（下次 open 自动重建空库），且旧库备份已留档不丢数据；
+ * 但同版本号多次重建会覆盖旧备份（命名 v{n}.bak 不带时间戳，决策 13 修订的
+ * 「各自留档」仅对不同版本号成立）——MVP 阶段无真实用户数据，可接受。
+ *
+ * @param db 待重建的连接（流程内关闭；调用方丢弃原引用，使用返回值中的新连接）
+ * @param dir 项目根目录
+ * @param dbPath data.db 绝对路径
+ * @param oldVersion 重建前的旧版本号（备份文件名与 fromVersion 用）
+ * @returns 新连接（已开库、版本号已写、表已建）+ 重建结果
+ */
+export function rebuildProjectStorage(db, dir, dbPath, oldVersion) {
+    // 1. WAL 合并回主文件后关闭连接（busy>0 说明有其他连接在写——MVP 单进程单连接，不检查）
+    checkpointWal(db);
+    closeDatabase(db);
+    // 2/3. 备份（复制而非 rename：原文件在重建流程中继续使用/删除）
+    const dbBackup = backupDbFile(dbPath, oldVersion);
+    const outlineBackup = backupOutlineFile(dir, oldVersion);
+    // 4. 删除旧库文件（含 WAL/SHM 伴生文件）
+    rmSync(dbPath, { force: true });
+    rmSync(`${dbPath}-wal`, { force: true });
+    rmSync(`${dbPath}-shm`, { force: true });
+    // 5. 重建空库并写版本号（openDatabase 自动建表 + WAL + synchronous=FULL）
+    const fresh = openDatabase(dbPath);
+    setUserVersion(fresh, SCHEMA_VERSION);
+    // 6. 重置 outline.json 为最小空树（决策 13 修订：顶层 schema_version 同步写入）
+    const emptyTree = { id: "root", type: "root", schema_version: SCHEMA_VERSION, children: [] };
+    writeOutlineFile(dir, emptyTree);
+    const backups = [dbBackup, ...(outlineBackup === null ? [] : [outlineBackup])];
+    return {
+        db: fresh,
+        result: { rebuilt: true, fromVersion: oldVersion, toVersion: SCHEMA_VERSION, backups },
+    };
+}
+/**
+ * 备份 data.db 主文件 → `data.db.v{n}.bak`（决策 13：备份带版本号、不覆盖旧备份）。
+ *
+ * **WAL 一致性取舍**：调用方必须在连接关闭前先执行 `wal_checkpoint(TRUNCATE)`（rebuildProjectStorage
+ * 已做）——checkpoint 后主文件即完整快照，只需复制主文件；-wal/-shm 内容已合并进主文件
+ * （TRUNCATE 后 -wal 为空文件），不再复制。若库处于 DELETE journal 模式（从未开过 WAL），
+ * 主文件本身即全部数据，同样安全。
+ *
+ * @returns 备份文件绝对路径
+ */
+export function backupDbFile(dbPath, oldVersion) {
+    const backupPath = `${dbPath}.v${oldVersion}.bak`;
+    copyFileSync(dbPath, backupPath);
+    return backupPath;
+}
+/**
+ * 备份 outline.json → `outline.json.v{n}.bak`（决策 13 修订：重建时同步重置并留档）。
+ *
+ * 取舍：用复制而非 rename——outline.json 不是 SQLite 文件、无 WAL 问题，复制保留原始字节
+ * （含格式/顺序）；rename 会把原文件移走，与「随后重置为空树」的流程相斥。
+ * outline.json 不存在（异常状态）时跳过备份返回 null——重置仍会执行（写空树）。
+ *
+ * @returns 备份文件绝对路径；文件不存在返回 null
+ */
+export function backupOutlineFile(dir, oldVersion) {
+    const src = join(dir, OUTLINE_FILE_NAME);
+    if (!existsSync(src))
+        return null;
+    const backupPath = join(dir, `${OUTLINE_FILE_NAME}.v${oldVersion}.bak`);
+    copyFileSync(src, backupPath);
+    return backupPath;
+}
+//# sourceMappingURL=migration.js.map

package/dist/queries/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.js","sourceRoot":"","sources":["../../src/queries/migration.ts"],"names":[],"mappings":"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"}

package/dist/queries/outline-ops.d.ts

@@ -0,0 +1,126 @@
+import type { OutlineFileNode, OutlineNodeType } from "@whispering233/ai-editor-shared";
+/** 大纲操作错误码（server 层映射 HttpError，见文件头注释） */
+export type OutlineErrorCode = "NODE_NOT_FOUND" | "PARENT_NOT_FOUND" | "INVALID_HIERARCHY" | "OUTLINE_ANCESTOR_DELETED";
+/** 大纲操作错误：带 code，供上层精确映射 HTTP 语义（替代 message 字符串匹配） */
+export declare class OutlineError extends Error {
+    readonly code: OutlineErrorCode;
+    constructor(code: OutlineErrorCode, message: string);
+}
+/**
+ * 严格三层约束校验（决策 19）：childType 能否挂 parentType 下。
+ * volume → root；chapter → volume 或 root；scene → 必须 chapter。
+ */
+export declare function assertCanHold(parentType: "root" | OutlineNodeType, childType: OutlineNodeType): void;
+/**
+ * 创建大纲节点（POST /api/v1/outline，endpoints.md 第 550-577 行）：
+ * 读树 → 校验父存在 + 三层约束 → 生成 id（shared generateOutlineNodeId：vol-/ch-/sc- 前缀）
+ * → 插入父 children 尾部 → **父节点 updated_at 统一更新**（决策 19）→ 原子写回。
+ *
+ * @param updatedAt ISO 8601 由调用方（应用层）传入，模块不生成时间
+ * @param data 节点结构化信息（决策 23，可选；校验由路由层按层级 schema 执行，本模块仅透传存储）
+ * @returns 新建节点（含 id/type/title/updated_at/data）
+ * @throws OutlineError PARENT_NOT_FOUND（父不存在）/ INVALID_HIERARCHY（三层违反）
+ */
+export declare function createOutlineNode(dir: string, input: {
+    type: Exclude<OutlineNodeType, "root">;
+    title: string;
+    parentId: string;
+    summary?: string;
+    data?: Record<string, unknown>;
+    updatedAt: string;
+}): OutlineFileNode;
+/**
+ * 更新大纲节点信息（PUT /api/v1/outline/:nodeId，endpoints.md 第 579-597 行）：
+ * title/summary 更新 + 节点 updated_at 统一更新（决策 19），原子写回；
+ * data **浅合并**（决策 23：未传字段保留，与实体 updateEntity 的 data 浅合并同语义）。
+ * @throws OutlineError NODE_NOT_FOUND
+ */
+export declare function updateOutlineNodeInfo(dir: string, nodeId: string, patch: {
+    title?: string;
+    summary?: string;
+    data?: Record<string, unknown>;
+}, updatedAt: string): void;
+/**
+ * 移动大纲节点（PUT /api/v1/outline/:nodeId/move，endpoints.md 第 599-621 行）：
+ * 从原父移除 → 插入新父指定 order（0-based；同父重排 = 移除后插入）→
+ * 三层约束校验（同 create）→ 新旧父 updated_at 统一更新（决策 19）→ 原子写回。
+ * order 越界时 clamp 到有效范围（拖拽场景边界值，宽松处理）。
+ *
+ * @returns { previousParentId, newParentId }（endpoints.md 语义；root 用 "root"）
+ * @throws OutlineError NODE_NOT_FOUND / PARENT_NOT_FOUND / INVALID_HIERARCHY
+ */
+export declare function moveOutlineNode(dir: string, nodeId: string, input: {
+    parentId: string;
+    order: number;
+}, updatedAt: string): {
+    previousParentId: string;
+    newParentId: string;
+};
+/**
+ * 软删大纲节点（DELETE /api/v1/outline/:nodeId，endpoints.md 第 623-640 行，决策 12）：
+ * 标记 deleted + deleted_at，**递归软删整棵子树**（本体保留可还原）。
+ * 已软删节点再次软删：幂等重标（不报错）。
+ *
+ * @returns { children } 级联软删的子节点数（不含自身）
+ *   —— relations/deltas 的级联软删由上层（S2.2）组合 relation/delta 模块处理（本模块边界）
+ * @throws OutlineError NODE_NOT_FOUND
+ */
+export declare function deleteOutlineNode(dir: string, nodeId: string, updatedAt: string): {
+    children: number;
+};
+/**
+ * 还原软删大纲节点（POST /api/v1/trash/outline/:nodeId/restore，endpoints.md 第 694-711 行）：
+ * 清除 deleted/deleted_at → **递归还原子树**（仍软删的子孙一并还原，决策 12 修订）→
+ * **祖先链校验**：存在软删祖先 → 抛 OUTLINE_ANCESTOR_DELETED（409 语义，决策 12 修订，
+ * 杜绝「可见节点挂在不可见父」的畸形树——校验在还原前执行，祖先必须已还原）。
+ *
+ * @returns { children } 级联还原的子节点数
+ * @throws OutlineError NODE_NOT_FOUND / OUTLINE_ANCESTOR_DELETED
+ */
+export declare function restoreOutlineNode(dir: string, nodeId: string, updatedAt: string): {
+    children: number;
+};
+/**
+ * 物理删除大纲节点（DELETE /api/v1/trash/outline/:nodeId，endpoints.md 第 726-736 行）：
+ * 从树中移除整棵子树（递归，文件内物理清除，不可恢复）。
+ * 边界：不涉及 data.db（relations/deltas 的物理清除由上层组合）；
+ * 不更新父节点 updated_at——purge 属回收站清理，节点已消失，
+ * 基于它的提案快照必然失效（节点不存在），父版本戳无需联动。
+ * @throws OutlineError NODE_NOT_FOUND
+ */
+export declare function purgeOutlineNode(dir: string, nodeId: string): void;
+/** 回收站节点条目（GET /api/v1/trash nodes 项，endpoints.md 第 668-674 行） */
+export interface DeletedOutlineNodeInfo {
+    id: string;
+    type: Exclude<OutlineNodeType, "root">;
+    title: string;
+    deleted_at: string;
+}
+/**
+ * 回收站列表（大纲侧）：收集整棵树中 deleted 标记的节点（含子树中的软删节点），
+ * 按 deleted_at 倒序（回收站排序约定，schema.md：跨 SQLite 与 outline.json 统一 ISO 格式）。
+ */
+export declare function listDeletedNodes(dir: string): DeletedOutlineNodeInfo[];
+/** 章节序条目（决策 21）：全局章序号（跨卷连续） */
+export interface ChapterOrderInfo {
+    chapterId: string;
+    /** 全局章序号，从 1 起（root → 卷 → 章先序遍历，跨卷连续累计） */
+    chapterNumber: number;
+}
+/**
+ * 章节序推导（决策 21）：按大纲树先序遍历编号——root → 卷 → 章；
+ * 全局章序号**跨卷连续**；直接挂 root 的 chapter 按兄弟顺序编号（决策 19 允许）；
+ * scene 归入所属章，不单独编号（见 getChapterNumber）。
+ */
+export declare function deriveChapterOrder(dir: string): ChapterOrderInfo[];
+/**
+ * 节点所属章序号（决策 21）：
+ * - scene → 所属 chapter 的全局序号（严格三层下 scene 的父必为 chapter）
+ * - chapter → 自身序号
+ * - volume / root / 节点不存在 → null（卷无章节号；不存在防御性返回 null 供上层展示）
+ */
+export declare function getChapterNumber(dir: string, nodeId: string): {
+    chapterId: string;
+    chapterNumber: number;
+} | null;
+//# sourceMappingURL=outline-ops.d.ts.map

package/dist/queries/outline-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline-ops.d.ts","sourceRoot":"","sources":["../../src/queries/outline-ops.ts"],"names":[],"mappings":"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"}