# PM-Agent v1.2 提案：Git数据同步与进度追踪

**提案编号**: PROPOSAL_2026-02-019  
**版本**: v1.0  
**日期**: 2026-02-18  
**作者**: Agent 3 (产品经理)

---

## 一、提案背景

### 1.1 v1.1版本现状

v1.1版本开发已基本完成，实现了：
- 客户/项目管理 (CRUD)
- 材料上传与处理 (OCR/语音转写)
- 材料去重 (SHA256)
- 模板转换 (基础API)

### 1.2 发现的问题

根据测试和用户反馈，发现以下问题：

| 问题 | 影响 |
|------|------|
| Dashboard进度为空 | 无法查看项目真实进度 |
| 路线图不显示 | oc-collab/pm-agent项目数据未同步 |
| BUG/PROPOSAL生成未实现 | 自动化流程不完整 |
| 状态反馈未实现 | 无法追踪问题解决状态 |

**核心原因**: 缺少与Git仓库的数据同步机制

---

## 二、提案目标

### 2.1 核心目标

实现PM-Agent与Git仓库（GitHub/Gitee/oc-collab）的双向数据同步：

1. **从Git获取数据**
   - 获取issues列表（BUG/需求）
   - 获取里程碑/路线图数据
   - 获取commits记录
   - 同步项目进度

2. **推送到Git**
   - 自动创建issues（BUG报告/需求）
   - 自动创建里程碑
   - 自动更新状态

### 2.2 预期效果

- Dashboard显示真实项目进度
- 路线图展示完整
- 自动化流程闭环
- 状态实时同步

---

## 三、功能需求

### 3.1 F-015: Git数据同步服务

**描述**: 从Git仓库同步项目数据

**验收标准**:
- [ ] 支持GitHub/Gitee API认证
- [ ] 定时同步issues数据
- [ ] 同步里程碑/路线图数据
- [ ] 同步commits记录
- [ ] 支持手动触发同步
- [ ] 记录同步日志

### 3.2 F-016: 进度数据展示

**描述**: 在Dashboard展示真实进度

**验收标准**:
- [ ] 显示项目issues统计（总数/进行中/已完成）
- [ ] 显示里程碑进度
- [ ] 显示最近commits
- [ ] 支持按时间范围筛选

### 3.3 F-017: 路线图展示

**描述**: 在专属页面展示项目路线图

**验收标准**:
- [ ] 显示当前版本里程碑
- [ ] 显示下版本计划
- [ ] 显示时间线
- [ ] 支持点击查看详情

### 3.4 F-018: 自动化报告生成

**描述**: 自动生成BUG报告和需求文档

**验收标准**:
- [ ] 根据材料自动生成BUG issue
- [ ] 根据材料自动生成需求issue
- [ ] 支持自定义issue模板
- [ ] 自动添加到项目

### 3.5 F-019: 状态同步反馈

**描述**: 监听Git状态变化，实时更新

**验收标准**:
- [ ] 监听issue状态变更
- [ ] 监听milestone变更
- [ ] 实时推送到前端
- [ ] 支持WebSocket推送

---

## 四、技术方案

### 4.1 架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                      PM-Agent                           │
├─────────────────────────────────────────────────────────────┤
│  前端(Vue)                                              │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │
│  │Dashboard│ │路线图   │ │问题跟踪 │ │材料处理 │       │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘       │
└───────┼───────────┼───────────┼───────────┼────────────┘
        │           │           │           │
        └───────────┴─────┬─────┴───────────┘
                          │
┌────────────────────────┼────────────────────────────────┐
│                   后端(FastAPI)                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │ GitSyncService│  │IssueService │  │ MilestoneSvc│    │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘    │
│         │                │                │              │
│         └────────────────┼────────────────┘              │
│                          │                               │
│  ┌──────────────────────┼──────────────────────────┐  │
│  │              GitHub/Gitee API                  │  │
│  └─────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
```

### 4.2 数据模型

```python
class GitSyncConfig:
    """Git同步配置"""
    id: int
    project_id: int
    provider: str  # github/gitee
    repo_url: str
    access_token: str
    sync_interval: int  # 分钟
    last_sync: datetime
    
class GitIssue:
    """Git Issue映射"""
    id: int
    git_issue_id: str
    project_id: int
    number: int
    title: str
    state: str  # open/closed
    labels: list
    milestone: str
    created_at: datetime
    updated_at: datetime

class Milestone:
    """里程碑"""
    id: int
    git_milestone_id: str
    project_id: int
    title: str
    state: str
    due_on: datetime
    description: str
```

### 4.3 API设计

| API | 方法 | 功能 |
|-----|------|------|
| /api/sync/config | GET/POST | 同步配置 |
| /api/sync/trigger | POST | 手动触发同步 |
| /api/issues/from-git | GET | 获取Git issues |
| /api/milestones | GET | 获取里程碑 |
| /api/dashboard/git-stats | GET | Git统计数据 |

---

## 五、工时预估

| 功能 | 工时 | 说明 |
|------|------|------|
| F-015 Git同步服务 | 8h | 核心服务 |
| F-016 进度展示 | 4h | Dashboard增强 |
| F-017 路线图 | 6h | 新页面开发 |
| F-018 报告生成 | 6h | 自动化 |
| F-019 状态反馈 | 8h | WebSocket |
| **总计** | **32h** | |

---

## 六、依赖关系

```
F-015 Git同步服务
    ↓
F-016 进度展示 ← F-015
F-017 路线图   ← F-015
F-018 报告生成 ← F-015
F-019 状态反馈 ← F-015
```

---

## 七、风险与应对

| 风险 | 影响 | 应对方案 |
|------|------|----------|
| Git API限流 | 同步失败 | 增加缓存+重试机制 |
| Token安全问题 | 安全风险 | 加密存储+权限控制 |
| 数据冲突 | 同步不一致 | 记录冲突+人工确认 |

---

## 八、签署确认

| 角色 | 签署人 | 日期 | 确认 |
|------|--------|------|------|
| 产品负责人 | Agent 3 | 2026-02-18 | ✅ |
| 架构师 | Agent 4 | - | ⏳ |

---

**提案版本**: v1.0  
**状态**: DRAFT
