修复: DOC-09+10 df-workflow/df-storage 模块文档过期修正

- DOC-09 df-workflow 4 处:NodeRegistry 删 Default impl(无 panic 铁律)+conditions 默认 true→false(B-260614-02)+try_recv_human_approval 已删+set_waiting/set_skipped 已删(仅 set_cancelled 唯一旁路)+set_* 签名 &mut→&self。
- DOC-10 df-storage:V8→V13 + 表数 13 业务表(+schema_version)+Repo 13(12 impl_repo!+1 手写 SettingsRepo)+MIGRATION_VERSION 常量已删(版本靠 schema_version 表)+迁移表补 V9-V13+knowledges DDL 补 reasoning 列。
主代理抽查:过期项仅历史说明残留。批4

docs/03-模块文档/df-storage-存储层-2026-06-12.md

@@ -1,12 +1,12 @@
 # df-storage 存储层
 
-> 创建: 2026-06-10 | 最后更新: 2026-06-14
+> 创建: 2026-06-10 | 最后更新: 2026-06-15
 
 ---
 
 ## 概述
 
-df-storage 是 DevFlow 的数据持久化层，基于 SQLite (rusqlite)，负责连接管理、Schema 迁移（V1-V8）和 CRUD 操作。全部 Repo 由 `impl_repo!` 宏自动生成。
+df-storage 是 DevFlow 的数据持久化层，基于 SQLite (rusqlite)，负责连接管理、Schema 迁移（V1-V13）和 CRUD 操作。绝大多数 Repo 由 `impl_repo!` 宏自动生成，KV 类表（`app_settings`）手写 Repo。
 
 ---
 
@@ -15,27 +15,36 @@ df-storage 是 DevFlow 的数据持久化层，基于 SQLite (rusqlite)，负责
 | 功能 | 状态 |
 |------|------|
 | SQLite 连接管理 | ✅ |
-| Schema 迁移 V1-V8 | ✅ |
-| impl_repo! 宏 CRUD | ✅ |
+| Schema 迁移 V1-V13 | ✅ |
+| impl_repo! 宏 CRUD（12 Repo） | ✅ |
+| KV 类手写 Repo（SettingsRepo） | ✅ |
 | KnowledgeRepo（含向量）| ✅ Sprint 15 |
+| KnowledgeEventsRepo（生命线审计）| ✅ |
 | 事务支持 | ⬜ 按需 |
 
 ---
 
-## 数据表（V1-V8 迁移历史）
+## 数据表（V1-V13 迁移历史）
 
 | 版本 | 新增/变更 |
 |------|-----------|
 | V1 | ideas / projects / tasks / releases / workflow_executions / node_executions（6 张基础表 + 4 索引）|
 | V2 | ideas 加 promoted_to/ai_analysis/scores；tasks 加 workflow_def_id/base_branch；workflow_executions 加 project_id/task_id；新建 branches 表（含 2 索引）|
-| V3 | ai_providers / ai_conversations / ai_tool_executions（AI 功能 3 张表）|
-| V4 | 幂等补列：ai_conversations.archived（PRAGMA 探测，兼容坏库）|
-| V5 | 幂等补列：ai_conversations.prompt_tokens / completion_tokens / model / models（Token 用量）|
-| V6 | 幂等补列：ai_conversations.skill（技能注入）|
+| V3 | 新建 **ai_conversations** 表（archived 列交 v4 幂等补建）|
+| V4 | 幂等补列：ai_conversations.archived（PRAGMA 探测，兼容坏库——历史 v3 写入版本号但 ALTER 未生效，统一交 v4 修复）|
+| V5 | 幂等补列：ai_conversations.prompt_tokens / completion_tokens（Token 用量）|
+| V6 | 幂等补列：ai_conversations.models（对话级多 model 记录）|
 | V7 | 新建 **knowledges** 表（Sprint 15）|
 | V8 | 幂等补列：knowledges.embedding BLOB（Phase 5.5 向量检索）|
+| V9 | 新建 **ai_providers** + **ai_tool_executions** 表（历史遗漏补建，CREATE TABLE IF NOT EXISTS 幂等）|
+| V10 | 幂等补列：knowledges.reasoning；新建 **knowledge_events** 事件表（追加型审计，支撑生命线视图，含 3 索引）|
+| V11 | 幂等补列：projects.deleted_at（软删回收站）|
+| V12 | 幂等补列：projects.path / projects.stack（项目绑定真实代码目录 + 技术栈）|
+| V13 | 新建 **app_settings** 表（通用应用设置 KV，前端 localStorage 迁移目标）|
 
-### knowledges 表（V7）
+> **当前共 13 张业务表**：ideas / projects / tasks / releases / workflow_executions / node_executions / branches / ai_conversations / ai_providers / ai_tool_executions / knowledges / knowledge_events / app_settings。另有一张内部表 `schema_version`（仅记录版本号，无业务语义）。
+
+### knowledges 表（V7 建表 + V8/V10 补列）
 
 ```sql
 CREATE TABLE IF NOT EXISTS knowledges (
@@ -52,6 +61,7 @@ CREATE TABLE IF NOT EXISTS knowledges (
     source_ref      TEXT,
     created_at      TEXT NOT NULL,                  -- 毫秒字符串
     updated_at      TEXT NOT NULL,
+    reasoning       TEXT,                           -- V10 补列，AI 提炼「为何值得沉淀」依据
     embedding       BLOB                            -- V8 补列，f32 little-endian
 );
 CREATE INDEX IF NOT EXISTS idx_knowledges_status ON knowledges(status);
@@ -67,21 +77,25 @@ CREATE INDEX IF NOT EXISTS idx_knowledges_reuse_count ON knowledges(reuse_count
 
 列名白名单（ALLOWED_COLUMNS）防 SQL 注入，各 Repo 声明各自允许的列。
 
-### 已注册 Repo 列表
+> KV 类表（`app_settings` 无固定 schema，按 key 读写）不走 `impl_repo!` 宏，由手写 `SettingsRepo` 直接 SQL 操作。
 
-| Repo | 表 |
-|------|----|
-| IdeaRepo | ideas |
-| ProjectRepo | projects |
-| TaskRepo | tasks |
-| ReleaseRepo | releases |
-| WorkflowRepo | workflow_executions |
-| NodeExecutionRepo | node_executions |
-| BranchRepo | branches |
-| AiProviderRepo | ai_providers |
-| AiConversationRepo | ai_conversations |
-| AiToolExecutionRepo | ai_tool_executions |
-| **KnowledgeRepo** | **knowledges** |
+### 已注册 Repo 列表（12 宏生成 + 1 手写 = 13）
+
+| Repo | 表 | 生成方式 |
+|------|----|---------|
+| IdeaRepo | ideas | impl_repo! |
+| ProjectRepo | projects | impl_repo! |
+| TaskRepo | tasks | impl_repo! |
+| ReleaseRepo | releases | impl_repo! |
+| WorkflowRepo | workflow_executions | impl_repo! |
+| NodeExecutionRepo | node_executions | impl_repo! |
+| BranchRepo | branches | impl_repo! |
+| AiProviderRepo | ai_providers | impl_repo! |
+| AiConversationRepo | ai_conversations | impl_repo! |
+| AiToolExecutionRepo | ai_tool_executions | impl_repo! |
+| **KnowledgeRepo** | **knowledges** | impl_repo!（+ 向量/检索自定义方法）|
+| **KnowledgeEventsRepo** | **knowledge_events** | impl_repo!（+ list_by_knowledge 等自定义方法）|
+| **SettingsRepo** | **app_settings** | 手写（KV 表不走宏）|
 
 ---
 
@@ -111,14 +125,17 @@ fn cosine_similarity(a: &[f32], b: &[f32]) -> f32   // 点积 / (‖a‖‖b‖
 
 ## 迁移幂等设计
 
-迁移机制：`schema_version` 表记录当前版本，`MIGRATION_VERSION` 常量为目标版本，`run()` 按 `current_version < N` 顺序应用各版本。
+迁移机制：`schema_version` 表记录已应用版本，`run()` 读出 `MAX(version)` 作 `current_version`，按 `current_version < N` 顺序应用 V1…V13（每版应用后 `INSERT` 对应版本号）。当前最新目标版本为 **13**。
+
+> 注：早期版本曾用 `MIGRATION_VERSION` 常量，现已无此常量——版本号直接散落在各 `if current_version < N` 分支，由 `schema_version` 表动态跟踪。
 
 ### v4 解法：PRAGMA 探测列存在性
 
 关键列补建不依赖版本号，用 `PRAGMA table_info(<table>)` 探测实际 schema，缺列才 `ALTER TABLE ADD COLUMN`。
 
 - 对新库（列已由建表带入）、老库（DDL 正常生效）、坏库（版本号已写入但 DDL 漏生效）三种情况都安全幂等。
-- V5/V6/V8 均复用此模式。
+- V4/V5/V6/V8/V10/V11/V12 均复用此模式（补列迁移）。
+- V9/V10/V13 用 `CREATE TABLE IF NOT EXISTS` 幂等建表（老库已有表则跳过）。
 
 ---
 
@@ -128,9 +145,9 @@ fn cosine_similarity(a: &[f32], b: &[f32]) -> f32   // 点积 / (‖a‖‖b‖
 crates/df-storage/src/
 ├── lib.rs          — 模块入口，导出公共 API
 ├── db.rs           — SQLite 连接管理（Database struct）
-├── migrations.rs   — V1-V8 迁移逻辑，MIGRATION_VERSION=8
-├── models.rs       — 全部 *Record struct（含 KnowledgeRecord）
-└── crud.rs         — impl_repo! 宏 + 全部 Repo（含 KnowledgeRepo）
+├── migrations.rs   — V1-V13 迁移逻辑（schema_version 表跟踪版本）
+├── models.rs       — 全部 *Record struct（含 KnowledgeRecord / KnowledgeEventRecord）
+└── crud.rs         — impl_repo! 宏 + 全部 Repo（含 KnowledgeRepo / KnowledgeEventsRepo / SettingsRepo）
 ```
 
 ---