# 设计方案 2: DocOS (Document Object System) [详细设计版]

## 1. 定位与目标

DocOS 是构建在 VGCS 之上的逻辑层，负责处理文档结构的演进（裂变、聚合）。
它不操作 Git Hash，而是操作逻辑路径。它通过 `ContextStore` 接口与底层交互。

## 2. 数据结构定义

### 2.1 逻辑节点 (DocNode)

这屏蔽了底层是 `File` 还是 `Dir` 的差异。

```rust
#[derive(Debug, Serialize, Deserialize)]
pub enum DocNodeKind {
    Leaf,       // 纯内容节点 (对应文件)
    Composite,  // 复合节点 (对应目录，含 index.md)
}

#[derive(Debug, Serialize, Deserialize)]
pub struct DocNode {
    pub name: String,
    pub path: String, // 逻辑路径 e.g., "Analysis/Revenue"
    pub kind: DocNodeKind,
    pub children: Vec<DocNode>, // 仅 Composite 有值
}
```

## 3. 核心接口定义 (DocManager Trait)

```rust
pub trait DocManager {
    /// 基于最新的 Commit 重新加载状态
    fn reload(&mut self, commit_hash: &str) -> Result<()>;

    /// 获取当前文档树大纲
    fn get_outline(&self) -> Result<DocNode>;

    /// 读取节点内容
    /// 逻辑：
    /// - Leaf: 读 `path`
    /// - Composite: 读 `path/index.md`
    fn read_content(&self, path: &str) -> Result<String>;

    // --- 写入操作 (Buffer Action) ---
    
    /// 写入内容 (Upsert)
    /// 逻辑：
    /// - 路径存在且是 Leaf -> 覆盖
    /// - 路径存在且是 Composite -> 覆盖 index.md
    /// - 路径不存在 -> 创建 Leaf
    fn write_content(&mut self, path: &str, content: &str);

    /// 插入子章节 (Implies Promotion)
    /// 逻辑：
    /// - 如果 parent 是 Leaf -> 执行 Promote (Rename Leaf->Dir/index.md) -> 创建 Child
    /// - 如果 parent 是 Composite -> 直接创建 Child
    fn insert_subsection(&mut self, parent_path: &str, name: &str, content: &str);

    /// 提交变更
    fn save(&mut self, message: &str) -> Result<String>;
}
```
## 4. 关键演进逻辑 (Implementation Specs)

### 4.1 裂变 (Promote Leaf to Composite)
假设 `path = "A"` 是 Leaf (对应文件 `A`).
Action `insert_subsection("A", "B")`:
1.  Read content of `A`.
2.  Delete file `A` (in transaction).
3.  Write content to `A/index.md`.
4.  Write new content to `A/B`.
*注意*: Git 会将其视为 Delete + Add，或 Rename。VGCS 底层会处理。

### 4.2 聚合 (Demote Composite to Leaf) - *Optional*
假设 `path = "A"` 是 Composite (目录 `A/`).
Action `demote("A")`:
1.  Read `A/index.md`.
2.  Concatenate children content (Optional policy).
3.  Delete dir `A/`.
4.  Write content to file `A`.

### 4.3 路径规范
*   **Root**: `/` (对应 Repo Root).
*   **Meta**: `_meta.json` (用于存储手动排序信息，如果需要).
*   **Content File**:
    *   Leaf: `Name` (No extension assumption, or `.md` default).
    *   Composite: `Name/index.md`.

## 5. 实现依赖
DocOS 需要持有一个 `Box<dyn Transaction>` 实例。
所有的 `write_*` 操作都只是在调用 Transaction 的 `write`。
只有调用 `save()` 时，Transaction 才会 `commit`。

## 6. 错误处理
*   `PathNotFound`: 读不存在的路径。
*   `PathCollision`: 尝试创建已存在的文件。
*   `InvalidOperation`: 尝试在 Leaf 节点下创建子节点（需显式调用 Promote 或 insert_subsection）。

