markbase/docs/fskit-research/ZFS_MVP_OPERATIONS.md

# ZFS MVP FSKit Operations 清单 ⭐⭐⭐⭐⭐

## Level 1: 基础挂载和读取（约200行）

### 必需实现（6个核心方法）

```swift
// 1. Volume激活 - 返回root item
func activate(options: FSTaskOptions) async throws -> FSItem {
    // 返回ZFS dataset的root目录
    return rootItem
}

// 2. 文件查找 - lookup文件/目录
func lookupItem(
    named name: FSFileName,
    inDirectory directory: FSItem
) async throws -> (FSItem, FSFileName) {
    // 调用libzfs查找文件
    // 返回找到的item和名称
}

// 3. 目录列举 - enumerate目录内容
func enumerateDirectory(
    _ directory: FSItem,
    startingAt cookie: FSDirectoryCookie,
    verifier: FSDirectoryVerifier,
    attributes: FSItem.GetAttributesRequest?,
    packer: FSDirectoryEntryPacker
) async throws -> FSDirectoryVerifier {
    // 调用libzfs列举目录
    // 使用packer添加每个item
}

// 4. 属性获取 - 获取文件属性
func attributes(_ item: FSItem) async throws -> FSItem.Attributes {
    // 调用libzfs获取属性
    // 返回Attributes对象
}

// 5. Volume同步 - 同步数据
func synchronize(flags: FSSynchronizeFlags) async throws {
    // 调用zfs sync
}

// 6. Volume停用 - 停用volume
func deactivate(options: FSDeactivateOptions = []) async throws {
    // 清理volume
}
```

---

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

### 必需实现（3个方法）

```swift
// 7. 文件创建 - 创建新文件/目录
func createItem(
    named name: FSFileName,
    type: FSItem.ItemType,
    inDirectory directory: FSItem,
    attributes: FSItem.SetAttributesRequest
) async throws -> (FSItem, FSFileName) {
    // 调用libzfs创建文件
}

// 8. 文件删除 - 删除文件/目录
func removeItem(
    _ item: FSItem,
    named name: FSFileName,
    fromDirectory directory: FSItem
) async throws {
    // 调用libzfs删除文件
}

// 9. Item回收 - 回收资源
func reclaimItem(_ item: FSItem) async throws {
    // 清理item资源
}
```

---

## OpenClose + IO Operations（约50行）

```swift
// 10. 打开文件
func open(_ item: FSItem, options: FSTaskOptions) async throws -> FSFileHandle {
    // 返回file handle
}

// 11. 关闭文件
func close(_ handle: FSFileHandle) async throws {
    // 清理handle
}

// 12. 读取数据
func read(
    _ handle: FSFileHandle,
    buffer: UnsafeMutableRawBufferPointer,
    options: FSTaskOptions
) async throws -> Int {
    // 调用libzfs读取数据到buffer
}

// 13. 写入数据
func write(
    _ handle: FSFileHandle,
    buffer: UnsafeRawBufferPointer,
    options: FSTaskOptions
) async throws -> Int {
    // 调用libzfs写入buffer数据
}
```

---

## 延后实现（MVP不实现）

**高级功能（8个方法）- Level 3+**:
```swift
// 延后：符号链接
func readSymbolicLink(_ item: FSItem) 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 Operations总清单

**必需实现**：约13个方法
- activate ✅
- lookupItem ✅
- enumerateDirectory ✅
- attributes ✅
- synchronize ✅
- deactivate ✅
- createItem ✅
- removeItem ✅
- reclaimItem ✅
- open ✅
- close ✅
- read ✅
- write ✅

**延后实现**：约8个方法
- readSymbolicLink ❌
- createSymbolicLink ❌
- createLink ❌
- renameItem ❌
- getXattr ❌
- setXattr ❌
- listXattrs ❌
- removeXattr ❌

**总计**：13个必需 + 8个延后 = 21个operations

---

## MVP工作量细分

**Level 1（6 methods）**: 约150行
- activate (20行)
- lookupItem (30行)
- enumerateDirectory (40行)
- attributes (20行)
- synchronize (20行)
- deactivate (20行)

**Level 2（3 methods）**: 约80行
- createItem (30行)
- removeItem (30行)
- reclaimItem (20行)

**OpenClose + IO（4 methods）**: 约60行
- open (15行)
- close (15行)
- read (15行)
- write (15行)

**总计**：约290行 Swift + 约200行 C wrapper = 约490行

---