aifastdb-devplan 1.0.0 → 1.0.1

package/dist/dev-plan-document-store.d.ts

@@ -0,0 +1,309 @@
+/**
+ * DevPlanDocumentStore — 基于 EnhancedDocumentStore 的开发计划存储实现
+ *
+ * 使用 aifastdb 的 EnhancedDocumentStore（JSONL 持久化）作为存储引擎。
+ * 实现 IDevPlanStore 接口，是 DevPlan 系统的两个存储后端之一。
+ *
+ * 特性：
+ * - JSONL 格式存储，人类可读，利于 Git 版本管理
+ * - 通过 tags 做索引查询
+ * - Append-only 存储，更新通过 delete + put 实现
+ */
+import type { IDevPlanStore } from './dev-plan-interface';
+import type { DevPlanSection, DevPlanDocInput, DevPlanDoc, MainTaskInput, MainTask, SubTaskInput, SubTask, CompleteSubTaskResult, ProjectProgress, ModuleInput, Module, ModuleDetail, ModuleStatus, TaskStatus, TaskPriority, SyncGitResult, DevPlanStoreConfig, DevPlanExportedGraph } from './types';
+/**
+ * 基于 EnhancedDocumentStore 的开发计划存储
+ *
+ * 管理项目的开发计划文档和任务，使用三个 EnhancedDocumentStore 实例：
+ * - docStore: 文档片段 (Markdown 内容)
+ * - taskStore: 任务 (主任务 + 子任务层级)
+ * - moduleStore: 功能模块
+ */
+export declare class DevPlanDocumentStore implements IDevPlanStore {
+    private docStore;
+    private taskStore;
+    private moduleStore;
+    private projectName;
+    constructor(projectName: string, config: DevPlanStoreConfig);
+    /**
+     * 保存文档片段
+     *
+     * 如果同 section（+subSection）已存在，会覆盖旧版本。
+     */
+    saveSection(input: DevPlanDocInput): string;
+    /**
+     * 获取文档片段
+     */
+    getSection(section: DevPlanSection, subSection?: string): DevPlanDoc | null;
+    /**
+     * 列出项目的所有文档片段
+     *
+     * 对同一 section(+subSection) 的多个历史版本做去重，仅保留最新版。
+     */
+    listSections(): DevPlanDoc[];
+    /**
+     * 更新文档片段内容
+     */
+    updateSection(section: DevPlanSection, content: string, subSection?: string): string;
+    /**
+     * 搜索文档片段
+     *
+     * 先对历史版本去重（同 listSections），再做关键词过滤。
+     */
+    searchSections(query: string, limit?: number): DevPlanDoc[];
+    /**
+     * 删除文档片段
+     */
+    deleteSection(section: DevPlanSection, subSection?: string): boolean;
+    /**
+     * 创建主任务（开发阶段）
+     */
+    createMainTask(input: MainTaskInput): MainTask;
+    /**
+     * 幂等导入主任务（Upsert）
+     *
+     * - 如果主任务不存在 → 创建新任务
+     * - 如果主任务已存在 → 更新标题/描述/优先级等字段，但保留已有的更高级状态
+     *   （例如已完成的任务不会被重置为 pending）
+     * - updatedAt 保证严格递增，不会与历史版本重复
+     *
+     * @param input 主任务输入
+     * @param options.preserveStatus 若为 true（默认），则不覆盖已完成的状态
+     * @param options.status 导入时的目标状态（默认 pending）
+     * @returns 创建或更新后的主任务
+     */
+    upsertMainTask(input: MainTaskInput, options?: {
+        preserveStatus?: boolean;
+        status?: TaskStatus;
+    }): MainTask;
+    /**
+     * 获取主任务
+     *
+     * 由于 JSONL append-only 存储会保留历史版本，
+     * 需要按 metadata.updatedAt 降序取最新版本。
+     */
+    getMainTask(taskId: string): MainTask | null;
+    /**
+     * 列出主任务
+     *
+     * 对同一 taskId 的多个历史版本做去重，仅保留最新版。
+     */
+    listMainTasks(filter?: {
+        status?: TaskStatus;
+        priority?: TaskPriority;
+        moduleId?: string;
+    }): MainTask[];
+    /**
+     * 更新主任务状态
+     */
+    updateMainTaskStatus(taskId: string, status: TaskStatus): MainTask | null;
+    /**
+     * 添加子任务
+     */
+    addSubTask(input: SubTaskInput): SubTask;
+    /**
+     * 幂等导入子任务（Upsert）
+     *
+     * - 如果子任务不存在 → 创建新子任务
+     * - 如果子任务已存在 → 更新标题/描述等字段，但保留已有的更高级状态
+     *   （例如已完成的任务不会被重置为 pending）
+     * - updatedAt 保证严格递增，不会与历史版本重复
+     *
+     * @param input 子任务输入
+     * @param options.preserveStatus 若为 true（默认），则不覆盖已完成的状态
+     * @param options.status 导入时的目标状态（默认 pending）
+     * @returns 创建或更新后的子任务
+     */
+    upsertSubTask(input: SubTaskInput, options?: {
+        preserveStatus?: boolean;
+        status?: TaskStatus;
+    }): SubTask;
+    /**
+     * 获取子任务
+     *
+     * 取同一 taskId 的最新版本（以 metadata.updatedAt 判定）。
+     */
+    getSubTask(taskId: string): SubTask | null;
+    /**
+     * 列出某主任务下的所有子任务
+     *
+     * 对同一 taskId 的多个历史版本做去重，仅保留最新版。
+     */
+    listSubTasks(parentTaskId: string, filter?: {
+        status?: TaskStatus;
+    }): SubTask[];
+    /**
+     * 更新子任务状态
+     *
+     * @param options.completedAtCommit - 完成时的 Git commit hash（仅 status=completed 时有效）
+     * @param options.revertReason - 回退原因（仅 status 从 completed 变为 pending 时有效）
+     */
+    updateSubTaskStatus(taskId: string, status: TaskStatus, options?: {
+        completedAtCommit?: string;
+        revertReason?: string;
+    }): SubTask | null;
+    /**
+     * 完成子任务 — 核心自动化方法
+     *
+     * 自动处理：
+     * 1. 获取当前 Git HEAD 的 short SHA 用于锚定
+     * 2. 更新子任务状态为 completed，写入 completedAt 时间戳和 completedAtCommit
+     * 3. 重新计算主任务的 completedSubtasks 计数
+     * 4. 如果全部子任务完成，自动标记主任务为 completed
+     * 5. 如果主任务完成，更新 milestones 文档
+     */
+    completeSubTask(taskId: string): CompleteSubTaskResult;
+    /**
+     * 手动完成主任务（跳过子任务检查）
+     */
+    completeMainTask(taskId: string): MainTask;
+    /**
+     * 获取项目整体进度
+     */
+    getProgress(): ProjectProgress;
+    /**
+     * 导出完整的 Markdown 文档
+     */
+    exportToMarkdown(): string;
+    /**
+     * 导出仅任务进度的简洁 Markdown
+     */
+    exportTaskSummary(): string;
+    /**
+     * 创建功能模块
+     */
+    createModule(input: ModuleInput): Module;
+    /**
+     * 获取功能模块（含自动计算的 taskCount/docCount）
+     */
+    getModule(moduleId: string): Module | null;
+    /**
+     * 列出所有功能模块
+     */
+    listModules(filter?: {
+        status?: ModuleStatus;
+    }): Module[];
+    /**
+     * 更新功能模块
+     */
+    updateModule(moduleId: string, updates: {
+        name?: string;
+        description?: string;
+        status?: ModuleStatus;
+    }): Module | null;
+    /**
+     * 删除功能模块
+     */
+    deleteModule(moduleId: string): boolean;
+    /**
+     * 获取模块详情 — 包含关联的任务和文档
+     */
+    getModuleDetail(moduleId: string): ModuleDetail | null;
+    /**
+     * 将存储的更改刷到磁盘
+     */
+    sync(): void;
+    /**
+     * 获取项目名称
+     */
+    getProjectName(): string;
+    /**
+     * 获取文档的有效 updatedAt 时间戳。
+     *
+     * EnhancedDocumentStore 使用 append-only JSONL 存储，修改文档时实际上
+     * 是 delete 旧文档 + put 新文档。因此同一逻辑文档可能存在多个物理版本。
+     * 必须通过 metadata.updatedAt 来判断哪个是最新的"可用文档"，
+     * 其余的都是"历史文档"。
+     *
+     * 优先级：metadata.updatedAt > metadata.createdAt > doc.createdAt
+     */
+    private getDocUpdatedAt;
+    /**
+     * 确保当前时间戳严格大于参考时间戳。
+     *
+     * EnhancedDocumentStore 使用 append-only JSONL 存储，保留所有历史版本。
+     * 版本选择通过 metadata.updatedAt 判定最新文档。
+     * 如果 delete+put 发生在同一毫秒内，新旧版本的 updatedAt 相同，
+     * 会导致去重时可能选中旧版本（如 pending 状态），造成状态丢失。
+     *
+     * 本方法在 delete 之后、put 之前调用，自旋等待直到时间戳前进，
+     * 从而保证新版本的 updatedAt 一定大于旧版本。
+     */
+    private ensureTimestampAfter;
+    /**
+     * 删除文档并确保后续 put 的 updatedAt 严格大于被删文档。
+     *
+     * 使用 metadata.updatedAt 作为参考时间戳（而非 doc.createdAt），
+     * 因为版本选择是基于 metadata.updatedAt 进行的。
+     */
+    private deleteAndEnsureTimestampAdvance;
+    /**
+     * 对同一 taskId 的多个历史版本做去重，仅保留最新版（metadata.updatedAt 最大）。
+     *
+     * 由于 EnhancedDocumentStore 使用 append-only JSONL 存储，
+     * delete+put 操作会在文件中保留历史版本。重新加载时所有版本都会出现，
+     * 因此需要在查询层面进行去重。
+     *
+     * 使用 metadata.updatedAt（而非 doc.createdAt）作为版本判定依据，
+     * 确保"最近更新时间"的文档才是可用文档，其余为历史文档。
+     */
+    private deduplicateByTaskId;
+    private docToDevPlanDoc;
+    private docToMainTask;
+    private docToModule;
+    private docToSubTask;
+    /**
+     * 刷新主任务的子任务计数
+     */
+    private refreshMainTaskCounts;
+    /**
+     * 当主任务完成时自动更新 milestones 文档
+     */
+    private autoUpdateMilestones;
+    /**
+     * 🆕 获取当前 Git HEAD 的 short SHA
+     *
+     * 在非 Git 仓库或 Git 不可用时返回 undefined，不阻断正常流程。
+     */
+    private getCurrentGitCommit;
+    /**
+     * 🆕 检查 commit 是否是 target 的祖先
+     *
+     * 使用 `git merge-base --is-ancestor` 命令。
+     * 如果 commit 不存在或不可达，返回 false（视为需要回退）。
+     */
+    private isAncestor;
+    /**
+     * 🆕 回退子任务状态
+     *
+     * 将已完成的子任务回退为 pending，记录回退原因，
+     * 清空 completedAtCommit 和 completedAt。
+     * 同时刷新父主任务的计数。
+     */
+    private revertSubTask;
+    /**
+     * 🆕 同步检查所有已完成任务与 Git 历史的一致性
+     *
+     * 对每个 status=completed 且有 completedAtCommit 的子任务：
+     * 1. 检查 completedAtCommit 是否是当前 HEAD 的祖先
+     * 2. 如果不是（说明 Git 发生了回滚），回退任务状态为 pending
+     * 3. 记录 revertReason
+     *
+     * @param dryRun 如果为 true，只返回哪些任务会被回退，不实际修改数据
+     * @returns 同步结果，包含被回退的任务列表
+     */
+    syncWithGit(dryRun?: boolean): SyncGitResult;
+    /**
+     * 生成文本进度条
+     */
+    private progressBar;
+    /**
+     * EnhancedDocumentStore 不支持图谱导出，返回 null。
+     * 如需图谱可视化，请使用 SocialGraphV2 引擎（DevPlanGraphStore）。
+     */
+    exportGraph(_options?: {
+        includeDocuments?: boolean;
+        includeModules?: boolean;
+    }): DevPlanExportedGraph | null;
+}
+//# sourceMappingURL=dev-plan-document-store.d.ts.map

package/dist/dev-plan-document-store.d.ts.map

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