# 概要设计文档：PM-Agent v1.2.0

**版本**: v1 (DRAFT)
**创建日期**: 2026-02-19
**作者**: Agent 3 (PM Agent产品经理)
**关联需求**: requirements_pm_agent_v1.2.0_DRAFT.md
**版本号**: 1.2.0

---

## 一、设计目标

v1.2.0的核心目标：
1. **Git数据同步** - 从oc-collab项目拉取数据
2. **跨项目查询** - 调用oc-collab CLI获取状态
3. **动态状态反馈** - 接收状态变更通知
4. **Dashboard完善** - 显示真实项目进度

---

## 二、功能模块

### 模块划分

| 模块ID | 模块名称 | 功能ID | 优先级 |
|--------|----------|--------|--------|
| M21 | Git同步服务 | F-021 | P0 |
| M22 | oc-collab CLI封装 | F-022 | P0 |
| M23 | 状态反馈服务 | F-023 | P0 |
| M24 | Dashboard进度 | F-024 | P1 |
| M25 | 问题跟踪同步 | F-025 | P1 |
| M26 | 项目文档汇总 | F-026 | P2 |

---

## 三、技术架构

### 3.1 技术选型

| 技术 | 选型 | 说明 |
|------|------|------|
| Git同步 | GitPython | 仓库克隆/同步 |
| CLI调用 | subprocess | 调用oc-collab命令 |
| 定时任务 | schedule | 轮询状态变更 |
| 数据解析 | JSON | 解析CLI返回 |
| 数据库 | SQLite | 已有 |

### 3.2 文件结构

```
backend/
├── services/
│   ├── git_sync_service.py      # M21: Git同步服务
│   ├── oc_collab_client.py      # M22: oc-collab CLI封装
│   ├── status_feedback.py       # M23: 状态反馈服务
│   └── document_fetcher.py      # M26: 文档拉取
├── api/
│   └── routes/
│       ├── sync.py              # 同步API
│       └── progress.py          # 进度API
└── models/
    └── database.py              # 扩展数据模型

frontend/src/
├── views/
│   ├── DashboardView.vue        # M24: 进度显示
│   └── IssuesView.vue           # M25: 问题跟踪
└── api/
    └── sync.ts                  # 同步API调用
```

---

## 四、模块设计

### 4.1 M21: Git同步服务

**功能**: 定期从oc-collab项目仓库拉取数据

**核心方法**:
```python
class GitSyncService:
    def __init__(self, base_path: str):
        self.base_path = base_path
    
    def sync_project(self, project_name: str, git_repo: str) -> bool:
        """同步单个项目"""
    
    def sync_all(self) -> Dict[str, bool]:
        """同步所有项目"""
    
    def get_last_sync_time(self, project_name: str) -> Optional[str]:
        """获取最后同步时间"""
```

### 4.2 M22: oc-collab CLI封装

**功能**: 调用oc-collab命令查询项目状态

**依赖**: oc-collab v2.3.3 F-AT-11

**错误处理（重点）**：

```python
class OcCollabClient:
    def __init__(self):
        self.env = {"OC_COLLAB_INTERNAL": "PM-Agent"}
        self.timeout = 30
        self.max_retries = 3
    
    def _call_cli(self, args: List[str]) -> Dict:
        """调用CLI并处理异常"""
        for attempt in range(self.max_retries):
            try:
                result = subprocess.run(
                    ["oc-collab"] + args,
                    env=self.env,
                    capture_output=True,
                    text=True,
                    timeout=self.timeout
                )
                if result.returncode == 0:
                    return json.loads(result.stdout)
                else:
                    raise OcCollabError(result.stderr)
            except subprocess.TimeoutExpired:
                if attempt == self.max_retries - 1:
                    raise OcCollabError("CLI调用超时")
            except json.JSONDecodeError:
                raise OcCollabError("返回数据解析失败")
```

**核心方法**:
```python
class OcCollabClient:
    def __init__(self):
        self.env = {"OC_COLLAB_INTERNAL": "PM-Agent"}
    
    def get_project_status(self, project_name: str) -> Dict:
        """调用 oc-collab project <name> status --json"""
    
    def get_project_todos(self, project_name: str, status: str = None) -> List[Dict]:
        """调用 oc-collab project <name> todos --json"""
    
    def get_project_progress(self, project_name: str) -> Dict:
        """调用 oc-collab project <name> progress --json"""
    
    def get_changes(self, project_name: str, since: str) -> List[Dict]:
        """调用 oc-collab project <name> changes --since=<time> --json"""
```

### 4.3 M23: 状态反馈服务

**功能**: 接收oc-collab状态变更通知

**核心方法**:
```python
class StatusFeedbackService:
    def __init__(self, client: OcCollabClient, storage: TodoStorage):
        self.client = client
        self.last_check_time = None
    
    def poll_changes(self) -> List[Change]:
        """轮询状态变更"""
    
    def update_local_status(self, changes: List[Change]):
        """更新本地状态"""
    
    def start_polling(self, interval: int = 60):
        """启动定时轮询"""
```

### 4.4 M24: Dashboard进度

**功能**: 显示项目真实进度

**数据来源**:
- 需求完成情况（从oc-collab获取）
- BUG修复情况（从oc-collab获取）
- TODO完成情况（从oc-collab获取）

**进度计算**:
```
进度 = (需求完成数/需求总数 × 40%) + (BUG解决数/BUG总数 × 30%) + (TODO完成数/TODO总数 × 30%)
```

### 4.5 M25: 问题跟踪同步

**功能**: 问题跟踪页面显示真实状态

**核心方法**:
```python
class IssueSyncService:
    def sync_bugs(self, project_name: str) -> List[Bug]:
        """同步BUG列表"""
    
    def sync_requirements(self, project_name: str) -> List[Requirement]:
        """同步需求列表"""
```

### 4.6 M26: 项目文档汇总

**功能**: 从oc-collab项目拉取开发文档

**核心方法**:
```python
class DocumentFetcher:
    def fetch_docs(self, project_path: str) -> List[Document]:
        """从项目仓库拉取文档"""
    
    def search(self, keyword: str) -> List[Document]:
        """搜索文档"""
```

---

## 五、API设计

### 5.1 同步API

```bash
# 手动触发同步
POST /api/sync/project/{project_name}
Response: {"status": "success", "synced_at": "2026-02-19T10:00:00Z"}

# 同步所有项目
POST /api/sync/all
Response: {"status": "success", "projects": {...}}

# 获取同步状态
GET /api/sync/status
Response: {"projects": {"金融法院": {"last_sync": "2026-02-19T10:00:00Z", "status": "ok"}}}
```

### 5.2 进度API

```bash
# 获取项目进度
GET /api/progress/{project_name}
Response: {
  "project": "金融法院",
  "progress": 65,
  "requirements": {"total": 10, "completed": 5, "in_progress": 3},
  "bugs": {"total": 3, "resolved": 2, "open": 1},
  "todos": {"total": 8, "completed": 5, "pending": 3}
}

# 获取所有项目进度汇总
GET /api/progress/summary
Response: {"total_projects": 5, "avg_progress": 45}
```

### 5.3 配置API

```bash
# 获取同步配置
GET /api/config/sync
Response: {"interval": 3600, "enabled": true}

# 设置同步间隔
PUT /api/config/sync
Body: {"interval": 3600}
Response: {"status": "success"}
```

---

## 六、数据模型扩展

### 新增表：project_sync_status

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键 |
| project_id | Integer | 外键 |
| last_sync_time | DateTime | 最后同步时间 |
| sync_status | String | 同步状态 |
| requirements_count | Integer | 需求总数 |
| requirements_completed | Integer | 需求完成数 |
| bugs_count | Integer | BUG总数 |
| bugs_resolved | Integer | BUG解决数 |
| todos_count | Integer | TODO总数 |
| todos_completed | Integer | TODO完成数 |

---

## 七、配置文件

### sync_config.yaml

```yaml
sync:
  # 同步间隔（秒）
  interval: 3600
  
  # 是否启用自动同步
  auto_sync: true
  
  # 同步超时时间（秒）
  timeout: 300

projects:
  - name: "金融法院"
    git_repo: "/path/to/金融法院"
    enabled: true
  
  - name: "阳光执法"
    git_repo: "/path/to/阳光执法"
    enabled: true
```

---

## 八、工时预估

| 模块 | 工时 |
|------|------|
| M21 Git同步服务 | 4h |
| M22 oc-collab CLI封装 | 3h |
| M23 状态反馈服务 | 4h |
| M24 Dashboard进度 | 3h |
| M25 问题跟踪同步 | 2h |
| M26 项目文档汇总 | 3h |
| 前端开发 | 4h |
| 测试与调试（含错误处理） | 7h |
| **总计** | **30h** |

---

## 九、依赖关系

| 模块 | 依赖 |
|------|------|
| M22 oc-collab CLI封装 | oc-collab v2.3.3 F-AT-11 |
| M23 状态反馈服务 | M22 + oc-collab v2.3.3 F-AT-01 |
| M24 Dashboard进度 | M22 |
| M25 问题跟踪同步 | M22 |
| M26 项目文档汇总 | M21 |

---

## 十、验收标准

| 模块 | 验收标准数 |
|------|-----------|
| M21-M23 | 12 |
| M24-M26 | 9 |
| **总计** | **21** |

---

## 十一、评审补充建议

### 1. 实现顺序

**建议先实现M22（CLI封装）**，因为其他模块（M23/M24/M25）都依赖它。

### 2. 错误处理（重点）

M22 CLI封装需要处理以下异常：

| 异常类型 | 处理方式 |
|----------|----------|
| CLI调用超时 | 重试3次，超时返回错误 |
| 网络异常 | 返回离线状态，记录日志 |
| 权限问题 | 返回"未认证"提示 |
| 项目不存在 | 返回404错误 |
| JSON解析失败 | 返回原始输出，记录日志 |

### 3. 配置管理

项目仓库配置纳入配置管理子系统：

```yaml
# config/projects.yaml
sync:
  interval: 3600
  auto_sync: true

projects:
  - name: "金融法院"
    git_repo: "/path/to/金融法院"
    enabled: true
  
  - name: "阳光执法"
    git_repo: "/path/to/阳光执法"
    enabled: true
```

---

# PM-Agent v2.0 概要设计

## 设计目标

v2.0的核心目标：
1. **ConfMan集成** - 集成conf-man配置管理和版本管理
2. **版本管理客户端** - VersionClient封装版本管理功能
3. **版本信息展示** - 前端展示版本信息

---

## 功能模块

| 模块ID | 模块名称 | 功能ID | 优先级 |
|--------|----------|--------|--------|
| M31 | ConfManClient | F-031 | P0 |
| M32 | VersionClient | F-032 | P0 |
| M33 | 版本信息前端 | F-033 | P1 |
| M34 | 集成测试 | F-034 | P0 |

---

## 技术架构

### 技术选型

| 技术 | 选型 | 说明 |
|------|------|------|
| CLI调用 | subprocess | 调用conf-man命令 |
| 数据解析 | JSON | 解析CLI返回 |
| 前端框架 | Vue.js | 已有 |

### 文件结构

```
backend/
├── integrations/
│   └── conf_man_client.py      # M31: ConfManClient
├── api/
│   └── routes/
│       └── version.py          # M32: 版本API
└── services/
    └── version_service.py      # M32: VersionClient

frontend/src/
├── views/
│   └── VersionView.vue         # M33: 版本信息页面
└── api/
    └── version.ts              # M33: 版本API调用
```

---

## 模块设计

### M31: ConfManClient

**功能**: 封装conf-man CLI调用

**核心方法**:
- `get_data_dir()` - 获取数据目录
- `get_config_dir()` - 获取配置目录
- `get_log_dir()` - 获取日志目录
- `get_todo_db_path()` - 获取TODO数据库路径
- `get_state_file_path()` - 获取状态文件路径
- `get_environment()` - 获取当前环境
- `is_test_mode()` - 检查测试模式

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

---

### M32: VersionClient

**功能**: 封装conf-man版本管理功能

**核心方法**:
- `list_versions()` - 列出版本
- `show_version(version)` - 版本详情
- `register_version(version, manifest, test_report)` - 登记版本
- `release_version(version)` - 发布版本
- `get_dependencies(version)` - 获取依赖
- `list_projects()` - 项目列表
- `show_project(name)` - 项目详情

**文件**: `backend/services/version_service.py`

---

### M33: 版本信息前端

**功能**: 前端展示版本信息

**页面结构**:
- 当前版本显示
- 版本列表组件
- 版本详情弹窗

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

---

### M34: 集成测试

**功能**: 验证ConfManClient和VersionClient功能正确性

**测试框架设计** (可独立开展):

| 测试类型 | 说明 | 依赖 |
|----------|------|------|
| API集成测试 | 测试后端API接口 | 不依赖 |
| E2E测试 | 端到端场景测试 | 不依赖 |
| Mock测试 | 使用mock进行单元测试 | 不依赖 |

**测试文件结构**:
```
tests/
├── unit/
│   ├── test_conf_man_client.py
│   └── test_version_service.py
├── integration/
│   └── test_version_api.py
└── e2e/
    └── test_version_flow.py
```

**可独立开展的测试**:
- API测试框架搭建
- E2E测试场景设计
- Mock测试用例编写

**依赖实现的测试** (需等待M31/M32):
- ConfManClient单元测试
- VersionClient单元测试

---

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| v1 | 2026-02-19 | 初始版本 |
| v2 | 2026-02-19 | 评审补充：实现顺序、错误处理、配置管理 |
| v2.0 | 2026-02-22 | 新增ConfMan集成、VersionClient、版本展示 |
| v2.1 | 2026-02-22 | 评审补充：M34测试框架设计，可独立开展 |

---

*文档版本: v2.1*
*创建日期: 2026-02-22*
*状态: DRAFT*
