# PM-Agent v2.0 需求与设计文档

**版本**: v2.0  
**创建日期**: 2026-02-22  
**作者**: Agent3 (产品经理) / Agent4 (架构师)  
**状态**: DRAFT

---

## 一、版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| v1.0 | 2026-02-17 | 初始版本：多模态输入、材料处理、Git发布 |
| v1.1 | 2026-02-17 | Git数据同步、跨项目查询、状态反馈 |
| v1.2 | 2026-02-19 | 保密项目文档隔离功能 |
| v2.0 | 2026-02-22 | ConfMan集成、VersionClient、版本前端展示 |

---

## 二、背景

v1.2已完成与oc-collab的深度集成，实现数据闭环。v2.0需要实现配置管理和版本管理能力的集成。

---

## 三、功能需求

### F-031: ConfManClient集成

**需求描述**：开发conf-man CLI封装客户端，集成配置管理和版本管理能力

**详细说明**：
1. 封装conf-man CLI命令调用
2. 实现路径查询：data/config/log/temp目录
3. 实现文件路径查询：todo-db/state/lock文件
4. 实现环境信息查询：environment/test-mode

**验收标准**：
- [ ] 实现ConfManClient类
- [ ] 支持所有conf-man path命令
- [ ] 支持所有conf-man file命令
- [ ] 支持env和test-mode查询
- [ ] 错误处理和异常捕获

---

### F-032: VersionClient开发

**需求描述**：开发版本管理客户端，调用conf-man版本管理功能

**详细说明**：
1. 实现版本列表查询
2. 实现版本详情查询
3. 实现版本登记
4. 实现版本发布
5. 实现依赖查询

**验收标准**：
- [ ] list_versions() 返回版本列表
- [ ] show_version() 返回版本详情
- [ ] register_version() 登记新版本
- [ ] release_version() 发布版本
- [ ] get_dependencies() 返回依赖列表
- [ ] 项目管理：create/list/show

---

### F-033: 版本信息前端展示

**需求描述**：在PM-Agent前端展示版本信息

**详细说明**：
1. 创建版本信息页面/组件
2. 显示当前系统版本
3. 显示所有已登记版本列表
4. 显示版本详情（组件、依赖）
5. 支持版本切换查看

**验收标准**：
- [ ] 页面展示当前版本
- [ ] 版本列表展示
- [ ] 版本详情弹窗/页面
- [ ] 与ConfManClient API对接
- [ ] 响应式UI设计

---

### F-034: 集成测试

**需求描述**：验证ConfMan和VersionClient功能正确性

**详细说明**：
1. ConfManClient单元测试
2. VersionClient单元测试
3. API集成测试
4. 前端版本展示测试
5. 端到端测试

**验收标准**：
- [ ] 单元测试覆盖率 > 80%
- [ ] 所有API接口测试通过
- [ ] 前端组件测试通过
- [ ] E2E测试场景通过

---

## 四、技术架构

### 4.1 技术选型

| 技术 | 选型 | 说明 |
|------|------|------|
| 配置管理 | conf-man CLI | 封装conf-man命令 |
| 版本管理 | conf-man version | 版本管理功能 |
| 后端框架 | FastAPI | 已有 |
| 前端框架 | Vue.js | 已有 |

### 4.2 文件结构

```
backend/
├── integrations/
│   └── conf_man_client.py     # F-031: conf-man 模块导入封装
├── services/
│   └── version_service.py    # F-032: 版本服务 (调用VersionClient)
├── api/routes/
│   └── version.py            # F-033: 版本API (后续开发)
frontend/src/
├── api/
│   └── version.ts            # F-033: 版本API调用 (后续开发)
└── views/
    └── VersionView.vue       # F-033: 版本信息页面 (待开发)
```

---

## 五、模块详细设计

### 5.1 ConfManClient (F-031)

**文件**: `backend/integrations/conf_man_client.py`

**实现方式**: 模块导入（而非CLI调用），支持测试mock注入

**核心方法**:

```python
class ConfManClient:
    """conf-man 配置管理客户端（模块导入方式）"""
    
    def __init__(self, conf_man_module=None):
        """
        初始化客户端
        
        Args:
            conf_man_module: 用于测试的mock模块，默认为None时导入实际conf-man模块
        """
        self._conf_man = conf_man_module
    
    def _get_conf_man(self):
        """获取conf-man模块（延迟加载）"""
        if self._conf_man is None:
            import conf_man
            self._conf_man = conf_man
        return self._conf_man
    
    def get_data_dir(self) -> str:
        """获取数据目录"""
        return self._get_conf_man().path.data()
    
    def get_config_dir(self) -> str:
        """获取配置目录"""
        return self._get_conf_man().path.config()
    
    def get_log_dir(self) -> str:
        """获取日志目录"""
        return self._get_conf_man().path.log()
    
    def get_temp_dir(self) -> str:
        """获取临时目录"""
        return self._get_conf_man().path.temp()
    
    def get_todo_db_path(self) -> str:
        """获取TODO数据库路径"""
        return self._get_conf_man().file.todo_db()
    
    def get_lock_file_path(self, name: str) -> str:
        """获取锁文件路径"""
        return self._get_conf_man().file.lock(name)
    
    def get_environment(self) -> dict:
        """获取环境信息"""
        return self._get_conf_man().env.get()
    
    def is_test_mode(self) -> bool:
        """检查是否为测试模式"""
        return self._get_conf_man().test_mode.is_enabled()
```

**错误处理**:

```python
class ConfManError(Exception):
    """conf-man调用异常"""

class ConfManNotFoundError(ConfManError):
    """conf-man模块未找到"""

class ConfManExecutionError(ConfManError):
    """模块执行失败"""
```

---

### 5.2 VersionClient (F-032)

**文件**: `backend/integrations/version_client.py`

**核心方法**:

```python
class VersionClient:
    """版本管理客户端"""
    
    def __init__(self, cli_path: str = "conf-man"):
        self.cli_path = cli_path
    
    def list_versions(self, project: str = None) -> List[Version]:
        """列出所有版本"""
        args = ["version", "list"]
        if project:
            args.extend(["--project", project])
        result = self._run_command(args)
        return [Version(**v) for v in json.loads(result)]
    
    def show_version(self, version: str) -> VersionDetail:
        """显示版本详情"""
        result = self._run_command(["version", "show", version])
        return VersionDetail(**json.loads(result))
    
    def register_version(
        self,
        version: str,
        description: str = None,
        components: List[str] = None
    ) -> str:
        """登记新版本"""
        args = ["version", "register", version]
        if description:
            args.extend(["--description", description])
        if components:
            for comp in components:
                args.extend(["--component", comp])
        return self._run_command(args)
    
    def release_version(self, version: str, target: str = None) -> str:
        """发布版本"""
        args = ["version", "release", version]
        if target:
            args.extend(["--target", target])
        return self._run_command(args)
    
    def get_dependencies(self, version: str) -> List[Dependency]:
        """获取版本依赖"""
        result = self._run_command(["version", "deps", version])
        return [Dependency(**d) for d in json.loads(result)]
    
    def create_project(self, name: str) -> str:
        """创建版本项目"""
        return self._run_command(["version", "project", "create", name])
    
    def _run_command(self, args: List[str]) -> str:
        """执行conf-man version命令"""
        pass
```

---

### 5.3 前端版本展示 (F-033)

**组件**: `frontend/src/views/VersionView.vue`

**功能**:
1. 显示当前系统版本
2. 版本列表展示
3. 版本详情弹窗
4. 版本切换

**API调用**:

```typescript
// 获取版本列表
async function fetchVersions() {
  const response = await fetch('/api/versions')
  return response.json()
}

// 获取版本详情
async function fetchVersionDetail(version: string) {
  const response = await fetch(`/api/versions/${version}`)
  return response.json()
}
```

---

## 六、API设计

### 6.1 版本API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/versions | 获取版本列表 |
| GET | /api/versions/{version} | 获取版本详情 |
| POST | /api/versions | 登记新版本 |
| POST | /api/versions/{version}/release | 发布版本 |

### 6.2 响应格式

```json
// GET /api/versions
{
  "versions": [
    {
      "version": "v1.0.0",
      "status": "released",
      "created_at": "2026-02-01T10:00:00Z"
    },
    {
      "version": "v1.1.0",
      "status": "draft",
      "created_at": "2026-02-15T10:00:00Z"
    }
  ]
}

// GET /api/versions/v1.0.0
{
  "version": "v1.0.0",
  "description": "初始版本",
  "components": ["backend", "frontend", "cli"],
  "dependencies": [],
  "released_at": "2026-02-01T12:00:00Z"
}
```

---

## 七、数据库设计

### 7.1 新增配置表

**文件**: 无新增数据库，使用现有结构

---

## 八、测试策略

### 8.1 单元测试详细清单

#### ConfManClient 单元测试 (15个)

| # | 测试用例名称 | 测试内容 |
|---|-------------|----------|
| 1 | test_get_data_dir_success | 测试获取数据目录成功 |
| 2 | test_get_config_dir_success | 测试获取配置目录成功 |
| 3 | test_get_log_dir_success | 测试获取日志目录成功 |
| 4 | test_get_temp_dir_success | 测试获取临时目录成功 |
| 5 | test_get_todo_db_path_success | 测试获取TODO数据库路径成功 |
| 6 | test_get_lock_file_path_success | 测试获取锁文件路径成功 |
| 7 | test_get_environment_success | 测试获取环境信息成功 |
| 8 | test_is_test_mode_true | 测试测试模式启用 |
| 9 | test_is_test_mode_false | 测试测试模式未启用 |
| 10 | test_module_not_found | 测试模块未找到异常 |
| 11 | test_conf_man_error | 测试conf-man执行异常 |
| 12 | test_lazy_load_module | 测试延迟加载模块 |
| 13 | test_mock_module_injection | 测试mock模块注入 |
| 14 | test_empty_lock_name | 测试空锁文件名 |
| 15 | test_concurrent_access | 测试并发访问 |

#### VersionClient 单元测试 (20个)

| # | 测试用例名称 | 测试内容 |
|---|-------------|----------|
| 1 | test_list_versions_empty | 测试版本列表为空 |
| 2 | test_list_versions_with_data | 测试版本列表有数据 |
| 3 | test_list_versions_filter_by_project | 测试按项目过滤版本 |
| 4 | test_show_version_success | 测试显示版本详情成功 |
| 5 | test_show_version_not_found | 测试版本不存在 |
| 6 | test_register_version_success | 测试登记新版本成功 |
| 7 | test_register_version_with_description | 测试带描述登记版本 |
| 8 | test_register_version_with_components | 测试带组件登记版本 |
| 9 | test_release_version_success | 测试发布版本成功 |
| 10 | test_release_version_with_target | 测试带目标发布版本 |
| 11 | test_get_dependencies_success | 测试获取依赖成功 |
| 12 | test_get_dependencies_empty | 测试依赖为空 |
| 13 | test_create_project_success | 测试创建项目成功 |
| 14 | test_cli_execution_error | 测试CLI执行错误 |
| 15 | test_invalid_json_response | 测试无效JSON响应 |
| 16 | test_timeout_handling | 测试超时处理 |
| 17 | test_empty_version_string | 测试空版本字符串 |
| 18 | test_special_chars_in_version | 测试版本号特殊字符 |
| 19 | test_concurrent_registration | 测试并发登记 |
| 20 | test_version_sorting | 测试版本排序 |

#### 版本API 单元测试 (10个)

| # | 测试用例名称 | 测试内容 |
|---|-------------|----------|
| 1 | test_get_versions_list_api | 测试获取版本列表API |
| 2 | test_get_version_detail_api | 测试获取版本详情API |
| 3 | test_post_register_version_api | 测试登记版本API |
| 4 | test_post_release_version_api | 测试发布版本API |
| 5 | test_api_error_handling | 测试API错误处理 |
| 6 | test_api_validation | 测试API参数验证 |
| 7 | test_api_authentication | 测试API认证 |
| 8 | test_api_rate_limiting | 测试API限流 |
| 9 | test_api_response_format | 测试API响应格式 |
| 10 | test_api_concurrent_requests | 测试API并发请求 |

#### 前端组件 单元测试 (8个)

| # | 测试用例名称 | 测试内容 |
|---|-------------|----------|
| 1 | test_version_list_rendering | 测试版本列表渲染 |
| 2 | test_version_detail_display | 测试版本详情显示 |
| 3 | test_version_switching | 测试版本切换 |
| 4 | test_api_integration | 测试API集成 |
| 5 | test_error_display | 测试错误显示 |
| 6 | test_loading_state | 测试加载状态 |
| 7 | test_empty_state | 测试空状态 |
| 8 | test_responsive_layout | 测试响应式布局 |

### 8.2 测试覆盖矩阵

| 模块 | 单元测试 | 集成测试 | E2E | 覆盖率目标 |
|------|---------|---------|-----|-----------|
| ConfManClient | 15 | 3 | - | 85% |
| VersionClient | 20 | 5 | 2 | 85% |
| 版本API | 10 | 5 | - | 90% |
| 前端组件 | 8 | 2 | 2 | 80% |
| **总计** | **53** | **15** | **4** | **82.5%** |

### 8.3 集成测试场景

| 测试场景 | 说明 | 状态 |
|---------|------|------|
| ConfMan可用性检测 | conf-man模块是否可用 | 🔄 进行中 |
| 版本创建流程 | 完整版本管理流程 | ⚠️ 待详细设计 |
| 前端版本展示 | 版本页面功能 | ⚠️ 待详细设计 |
| 多项目版本管理 | 多项目场景测试 | ⚠️ 待详细设计 |

### 8.4 E2E测试场景

```python
def test_e2e_version_lifecycle():
    """版本全生命周期"""
    # 1. 创建项目
    # 2. 登记版本
    # 3. 发布版本
    # 4. 查询版本
    # 5. 获取依赖

def test_e2e_frontend_integration():
    """前端集成"""
    # 1. 前端调用API
    # 2. 展示版本列表
    # 3. 查看版本详情

def test_e2e_confman_integration():
    """ConfMan集成"""
    # 1. 查询数据目录
    # 2. 查询配置目录
    # 3. 查询环境信息

def test_e2e_error_recovery():
    """错误恢复"""
    # 1. 模拟网络错误
    # 2. 验证错误提示
    # 3. 重试机制
```

### 8.5 测试数据准备

| 数据类型 | 准备方法 |
|---------|----------|
| 版本数据 | 使用conf-man创建测试版本 |
| 项目数据 | 使用conf-man创建测试项目 |
| 依赖数据 | 使用conf-man创建测试依赖 |
| 前端数据 | Mock API响应 |

### 8.6 测试环境配置

| 环境 | 配置要求 |
|------|---------|
| 开发环境 | conf-man本地安装 |
| 测试环境 | conf-man mock服务 |
| CI环境 | Docker容器运行 |

---

## 九、工时预估

| 模块 | 开发 | 测试 | 总计 |
|------|------|------|------|
| F-031 ConfManClient | 4h | 1h | 5h |
| F-032 VersionClient | 5h | 2h | 7h |
| F-033 前端展示 | 3h | 2h | 5h |
| F-034 集成测试 | 3h | 3h | 6h |
| **总计** | **15h** | **8h** | **23h** |

> 注：根据agent6评审建议，调整测试工时以覆盖详细的测试用例

---

## 十、依赖关系

| 模块 | 依赖 |
|------|------|
| F-031 ConfManClient | conf-man CLI |
| F-032 VersionClient | conf-man CLI, F-031 |
| F-033 前端展示 | F-032 API |
| F-034 集成测试 | F-031, F-032, F-033 |

---

## 十一、实现状态

| 功能 | 状态 | 说明 |
|------|------|------|
| F-031 ConfManClient | 🔄 部分实现 | 路径查询、环境查询已实现，测试mock注入已完成 |
| F-032 VersionClient | ✅ 已实现 | CLI封装完成，list_versions/show_version等方法 |
| F-033 前端展示 | ❌ 未开始 | 待开发 |
| F-034 集成测试 | 🔄 进行中 | 部分E2E测试已完成 |

---

## 十三、风险与应对

| 风险 | 可能性 | 影响 | 应对 |
|------|--------|------|------|
| conf-man CLI不可用 | 低 | 高 | 提供mock实现用于测试 |
| 版本数据格式变化 | 中 | 中 | 做好版本兼容 |
| 前端展示兼容 | 低 | 中 | 响应式设计 |

---

## 十四、评审清单

- [ ] 需求完整性
- [ ] 技术方案可行性
- [ ] API设计合理性
- [ ] 测试覆盖充分性
- [ ] 工时评估准确性
- [ ] 风险识别完整性

---

**文档状态**: DRAFT  
**创建人**: Agent3 (产品经理)  
**架构师**: Agent4 (架构师)
