127 lines
3.5 KiB
Markdown
127 lines
3.5 KiB
Markdown
## ADDED Requirements
|
||
|
||
### Requirement: 系统必须使用临时目录进行 staging
|
||
|
||
工具必须在系统临时目录中创建 staging 区域，组装完整的目标文件树后再移动到最终位置。
|
||
|
||
#### Scenario: 创建 staging 目录
|
||
|
||
- **WHEN** 开始安装事务
|
||
- **THEN** 系统在 `/tmp/` 或 `os.TempDir()` 创建唯一的临时目录（如 `skillmgr-xxxxx/`）
|
||
|
||
#### Scenario: Staging 目录结构与目标一致
|
||
|
||
- **WHEN** 在 staging 中组装文件
|
||
- **THEN** staging 目录结构必须与最终目标目录结构完全一致
|
||
|
||
---
|
||
|
||
### Requirement: 系统必须先完整复制到 staging
|
||
|
||
工具必须将所有源文件完整复制到 staging 目录，应用平台适配规则。
|
||
|
||
#### Scenario: 复制所有文件到 staging
|
||
|
||
- **WHEN** 执行 Stage 阶段
|
||
- **THEN** 系统根据平台适配器返回的文件映射，将所有文件复制到 staging
|
||
|
||
#### Scenario: 复制失败回滚
|
||
|
||
- **WHEN** 复制过程中任何文件失败
|
||
- **THEN** 系统删除 staging 目录，报错终止，不影响目标目录
|
||
|
||
---
|
||
|
||
### Requirement: 系统必须验证 staging 完整性
|
||
|
||
工具必须在提交前验证 staging 目录中的文件完整性。
|
||
|
||
#### Scenario: 验证文件数量
|
||
|
||
- **WHEN** 所有文件复制到 staging
|
||
- **THEN** 系统验证 staging 中文件数量与预期映射表一致
|
||
|
||
---
|
||
|
||
### Requirement: 系统必须原子性提交 staging
|
||
|
||
工具必须在 staging 验证通过后，将整个 staging 目录移动到目标位置。
|
||
|
||
#### Scenario: 同文件系统移动
|
||
|
||
- **WHEN** staging 和目标在同一文件系统
|
||
- **THEN** 系统使用 `os.Rename()` 原子性移动
|
||
|
||
#### Scenario: 跨文件系统复制
|
||
|
||
- **WHEN** `os.Rename()` 失败（跨文件系统）
|
||
- **THEN** 系统 fallback 到递归复制 + 删除 staging
|
||
|
||
#### Scenario: 覆盖已存在目录
|
||
|
||
- **WHEN** 目标目录已存在（用户已确认覆盖）
|
||
- **THEN** 系统先删除目标目录，再移动 staging
|
||
|
||
---
|
||
|
||
### Requirement: 系统必须在失败时自动回滚
|
||
|
||
工具必须在任何阶段失败时，自动清理 staging 目录，不留垃圾文件。
|
||
|
||
#### Scenario: Stage 阶段失败
|
||
|
||
- **WHEN** 文件复制到 staging 失败
|
||
- **THEN** 系统删除 staging 目录，不修改目标
|
||
|
||
#### Scenario: Commit 阶段失败
|
||
|
||
- **WHEN** 移动 staging 到目标失败
|
||
- **THEN** 系统删除 staging 目录，目标目录保持原状（或已删除的状态）
|
||
|
||
#### Scenario: defer 确保清理
|
||
|
||
- **WHEN** 事务对象被销毁
|
||
- **THEN** 系统使用 defer 确保 staging 目录被清理
|
||
|
||
---
|
||
|
||
### Requirement: 系统必须提供事务接口
|
||
|
||
工具必须提供清晰的事务接口，包含 Stage、Commit、Rollback 方法。
|
||
|
||
#### Scenario: 创建事务对象
|
||
|
||
- **WHEN** 开始安装流程
|
||
- **THEN** 系统创建 Transaction 对象，包含 stagingDir、targetDir、fileMap 字段
|
||
|
||
#### Scenario: 调用 Stage 方法
|
||
|
||
- **WHEN** 调用 `transaction.Stage()`
|
||
- **THEN** 系统执行文件复制到 staging
|
||
|
||
#### Scenario: 调用 Commit 方法
|
||
|
||
- **WHEN** 调用 `transaction.Commit()`
|
||
- **THEN** 系统将 staging 移动到目标
|
||
|
||
#### Scenario: 调用 Rollback 方法
|
||
|
||
- **WHEN** 调用 `transaction.Rollback()`
|
||
- **THEN** 系统删除 staging 目录
|
||
|
||
---
|
||
|
||
### Requirement: 系统必须确保目标目录的父目录存在
|
||
|
||
工具必须在提交前确保目标目录的父目录已创建。
|
||
|
||
#### Scenario: 创建父目录
|
||
|
||
- **WHEN** 提交 staging 到目标
|
||
- **THEN** 系统先创建目标目录的父目录（如 `~/.claude/skills/`）
|
||
|
||
#### Scenario: 父目录创建失败
|
||
|
||
- **WHEN** 父目录创建失败（权限不足等）
|
||
- **THEN** 系统报错，回滚 staging
|