markbase/docs/fskit-research/ZFS_MVP_DESIGN.md

# ZFS MVP（最小可用版本）设计 ⭐⭐⭐⭐⭐

## 功能拆解策略

**用户要求**：不需要实现所有ZFS功能，先将ZFS拆解

**MVP原则**：最小功能集，验证可行性

---

## ZFS功能拆解分析

### Core Features（核心功能）

**Level 1: 基础挂载** ⭐⭐⭐⭐⭐ (MVP)
- Pool import（导入现有pool）
- Dataset mount（挂载dataset）
- File read（读取文件）
- Directory listing（目录列举）
- **工作量**：约200-300行

**Level 2: 基础写入** ⭐⭐⭐⭐⭐
- File write（写入文件）
- File create（创建文件）
- Directory create（创建目录）
- **工作量**：约100-150行

**Level 3: 基础属性** ⭐⭐⭐⭐
- Get attributes（获取属性）
- Set attributes（设置属性）
- Extended attributes（xattr）
- **工作量**：约100-150行

---

### Advanced Features（高级功能）- 暂不实现

**Level 4: Pool管理** ⭐⭐⭐⭐ (延后)
- Pool create（创建pool）
- Pool destroy（删除pool）
- Vdev management（设备管理）
- **工作量**：约500+行

**Level 5: Snapshot** ⭐⭐⭐⭐ (延后)
- Snapshot create（创建快照）
- Snapshot rollback（回滚快照）
- Snapshot list（快照列表）
- **工作量**：约300+行

**Level 6: Compression** ⭐⭐⭐⭐ (延后)
- Compression on/off
- Compression algorithm选择
- **工作量**：约200+行

**Level 7: Send/Receive** ⭐⭐⭐⭐ (延后)
- ZFS send（发送流）
- ZFS receive（接收流）
- **工作量**：约500+行

---

## MVP必需FSKit Operations

### 必需实现（最小集）

**FSVolume.Operations 必需方法**（约10个）：
```swift
// Level 1: 基础挂载和读取
func activate(options: FSTaskOptions) async throws -> FSItem
func lookupItem(named: FSFileName, inDirectory: FSItem) async throws -> (FSItem, FSFileName)
func enumerateDirectory(...) async throws -> FSDirectoryVerifier

// Level 2: 基础写入
func createItem(named: FSFileName, type: FSItem.ItemType, ...) async throws -> (FSItem, FSFileName)
func removeItem(...) async throws

// Level 3: 属性
func attributes(_ item: FSItem) async throws -> FSItem.Attributes

// 必需辅助方法（约5个）
func deactivate(options: FSDeactivateOptions) async throws
func synchronize(flags: FSSynchronizeFlags) async throws
func reclaimItem(_ item: FSItem) async throws
```

**可选延后**（约8个）：
```swift
// 高级功能，MVP不实现
func readSymbolicLink(...) async throws -> FSFileName
func createSymbolicLink(...) async throws -> (FSItem, FSFileName)
func createLink(...) async throws -> FSFileName
func renameItem(...) async throws -> FSFileName
func getXattr(...) async throws -> Data
func setXattr(...) async throws
func listXattrs(...) async throws -> [String]
func removeXattr(...) async throws
```

---

## MVP实现策略 ⭐⭐⭐⭐⭐

### Phase 1: Level 1基础挂载（约200行）

**核心功能**：
- Pool import（读取现有ZFS pool metadata）
- Dataset mount（创建FSVolume）
- File read（通过libzfs user-space）
- Directory listing（列举dataset文件）

**FSKit实现**：
- `activate`: 返回root item
- `lookupItem`: 查找文件/目录
- `enumerateDirectory`: 列举目录内容
- `attributes`: 基础属性

**预计工作量**：约200行 Swift + 100行 C（libzfs wrapper）

---

### Phase 2: Level 2基础写入（约100行）

**核心功能**：
- File write（写入数据）
- File create（创建新文件）
- Directory create（创建目录）

**FSKit实现**：
- `createItem`: 创建文件/目录
- `removeItem`: 删除文件/目录
- OpenClose + IO operations

**预计工作量**：约100行 Swift

---

### Phase 3: Level 3基础属性（约100行）

**核心功能**：
- Get/set attributes
- Extended attributes（ZFS properties）

**FSKit实现**：
- `attributes`: 完整属性
- XattrOperations（可选）

**预计工作量**：约100行 Swift

---

## MVP总工作量评估 ⭐⭐⭐⭐⭐

**重新评估**：

| 方面 | MVP工作量 | 评估 |
|------|----------|------|
| **FSKit Volume** | 约400-500行 | ⭐⭐⭐⭐ 大幅降低 |
| **libzfs wrapper** | 约200行 | ⭐⭐⭐⭐ |
| **测试和文档** | 约100行 | ⭐⭐⭐⭐ |
| **总工作量** | **约700-800行** | ⭐⭐⭐⭐⭐ |
| **开发时间** | **约2-3 weeks** | ⭐⭐⭐⭐⭐ |

**对比**：
- 完整ZFS：15-20 months → MVP：**2-3 weeks**
- 从 ⭐⭐⭐ → ⭐⭐⭐⭐⭐

---

## MVP架构设计 ⭐⭐⭐⭐⭐

```
ZFS MVP (Level 1-3)
│
├── FSKit Layer (Swift)
│   ├── HelloFS (FSUnaryFileSystem)
│   │   ├── probeResource (接受ZFS pool)
│   │   ├── loadResource (加载dataset)
│   │   └── unloadResource
│   │
│   ├── ZFSVolume (FSVolume + 必需protocols)
│   │   ├── activate (返回root)
│   │   ├── lookupItem (查找文件)
│   │   ├── enumerateDirectory (列举目录)
│   │   ├── createItem (创建文件)
│   │   ├── removeItem (删除文件)
│   │   ├── attributes (获取属性)
│   │   └── deactivate
│   │
│   └── ZFSItem (FSItem)
│       ├── name, id, attributes
│       └── content (Data)
│
├── libzfs Wrapper (C + Swift FFI)
│   ├── zpool_import (导入pool)
│   ├── zfs_open (打开dataset)
│   ├── zfs_read (读取数据)
│   ├── zfs_write (写入数据)
│   └── zfs_list (列举文件)
│
└── ZFS User-Space Core (C)
    ├── SPA (Storage Pool Allocator)
    ├── DMU (Data Management Unit)
    ├── DSL (Dataset Layer)
    └── ZPL (ZFS POSIX Layer)
```

---

## MVP优先级 ⭐⭐⭐⭐⭐

**立即实现**（Level 1）：
1. ✅ Pool import（读取现有pool）
2. ✅ Dataset mount（创建FSVolume）
3. ✅ File read（读取文件）
4. ✅ Directory listing

**次要实现**（Level 2）：
5. ⏸️ File write
6. ⏸️ File create/delete

**延后实现**（Level 3+）：
7. ⏸️ Advanced attributes
8. ⏸️ Snapshot operations
9. ⏸️ Compression
10. ⏸️ Send/receive

---

## MVP验证目标 ⭐⭐⭐⭐⭐

**验证目标**：
- ✅ 能导入现有ZFS pool
- ✅ 能挂载ZFS dataset
- ✅ 能读取ZFS文件
- ✅ 能列举ZFS目录
- ✅ 基础功能可用

**不验证**（延后）：
- ❌ Pool创建
- ❌ Snapshot操作
- ❌ 高级压缩
- ❌ Send/receive

---

## MVP vs 完整ZFS对比

| 功能 | MVP | 完整ZFS | 差距 |
|------|-----|---------|------|
| Pool管理 | Import only | Create/Destroy/Vdev | 90%减少 |
| Dataset | Mount only | Create/Destroy/Snapshot | 80%减少 |
| File Ops | Read/Write/Create | Full POSIX | 50%减少 |
| Attributes | Basic | Full + xattr | 60%减少 |
| Snapshot | ❌ None | ✅ Full | 100%减少 |
| Compression | ❌ None | ✅ lz4/zstd | 100%减少 |
| Send/Receive | ❌ None | ✅ Full | 100%减少 |
| **工作量** | **700行** | **135,000行** | **99%减少** |
| **时间** | **2-3 weeks** | **15-20 months** | **95%减少** |

---