# HarborForge 开发计划

**版本**: 0.3.0  
**日期**: 2026-03-19  
**状态**: 开发中

---

## 1. 项目概述

HarborForge 是一个 **AI Agent 与人类协同的任务管理平台**，用于管理项目、里程碑、任务和提案(Propose)。

### 核心特性
- 项目驱动的任务管理
- 里程碑(Milestone)状态机管理
- 任务(Task)状态机管理
- 提案(Propose)工作流
- 角色权限系统(RBAC)
- 服务器监控集成
- Webhook 扩展能力
- OpenClaw 插件生态

---

## 2. 系统架构

### 2.1 整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│                         客户端层                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ Web Frontend │  │ OpenClaw CLI │  │ OpenClaw Plugin      │  │
│  │ (React/Vite) │  │              │  │ (Server Monitor)     │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬───────────┘  │
└─────────┼─────────────────┼─────────────────────┼──────────────┘
          │                 │                     │
          └─────────────────┼─────────────────────┘
                            │ HTTP/WebSocket
┌───────────────────────────▼─────────────────────────────────────┐
│                      HarborForge.Backend                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  FastAPI + SQLAlchemy + MySQL                            │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │   │
│  │  │ Projects│ │Milestones│ │  Tasks  │ │Proposes │       │   │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘       │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │   │
│  │  │  Auth   │ │  RBAC   │ │ Monitor │ │ Webhooks│       │   │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘       │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
          │
          └──────────────────────────────────────────────────────┐
                                                                 │
┌────────────────────────────────────────────────────────────────▼┐
│                      外部集成                                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │  LLM Providers│  │  Keycloak    │  │  AbstractWizard      │  │
│  │ (Claude/etc) │  │   (Auth)     │  │ (Config Management)  │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 模块划分

| 模块 | 技术栈 | 职责 |
|------|--------|------|
| **Backend** | FastAPI + SQLAlchemy + MySQL | REST API + WebSocket，业务逻辑 |
| **Frontend** | React + Vite + TypeScript | 用户界面，管理后台 |
| **OpenclawPlugin** | Node.js + TypeScript | OpenClaw 集成，服务器监控 |
| **Backend.Test** | pytest | 独立测试套件 |
| **Frontend.Test** | Playwright | E2E 测试 |

---

## 3. 数据模型

### 3.1 核心实体关系

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Project   │◄────┤  Milestone  │◄────┤    Task     │
│             │     │             │     │             │
│ - id        │     │ - id        │     │ - id        │
│ - name      │     │ - title     │     │ - title     │
│ - owner_id  │     │ - status    │     │ - status    │
│ - project_code│   │ - project_id│     │ - type      │
└──────┬──────┘     └─────────────┘     └──────┬──────┘
       │                                        │
       │         ┌─────────────┐              │
       └────────►│   Propose   │◄─────────────┘
                 │             │
                 │ - id        │
                 │ - title     │
                 │ - status    │
                 │ - feat_task_id (accept时创建)
                 └─────────────┘
```

### 3.2 状态机定义

#### Milestone 状态
```
open ──freeze──► freeze ──start──► undergoing ──close──► closed
  │                               │
  │                               └──auto-complete──► completed
  │
  └──────────────────────────────────────────────────► closed
```

#### Task 状态
```
open ──assign+start──► undergoing ──finish+comment──► completed ──close──► closed
  │                                                    │
  │                                                    └──reopen──► open
  │
  └──pending──► undergoing ──(同上)
```

#### Propose 状态
```
open ──accept──► accepted (创建 feature story task)
  │
  └──reject──► rejected ──reopen──► open
```

---

## 4. API 接口设计

### 4.1 认证接口

```yaml
POST /auth/token
  # JWT 登录
  Body: { username: string, password: string }
  Response: { access_token: string, token_type: "bearer" }

GET /users/me
  # 获取当前用户信息
  Headers: Authorization: Bearer {token}
```

### 4.2 项目接口

```yaml
GET    /projects
  # 列表（支持分页）
  Query: { page: int, page_size: int }

POST   /projects
  # 创建
  Body: { name: string, description?: string, project_code?: string }

GET    /projects/{id}
  # 详情

PATCH  /projects/{id}
  # 更新

DELETE /projects/{id}
  # 删除（需确认）
```

### 4.3 里程碑接口

```yaml
GET    /projects/{project_id}/milestones
  # 列表
  Query: { status: "open|freeze|undergoing|completed|closed" }

POST   /projects/{project_id}/milestones
  # 创建
  Body: { title: string, description?: string, due_date?: datetime }

GET    /projects/{project_id}/milestones/{id}
  # 详情

PATCH  /projects/{project_id}/milestones/{id}
  # 更新（仅在 open 状态允许修改大部分字段）

DELETE /projects/{project_id}/milestones/{id}
  # 删除

# 状态机动作
POST   /projects/{project_id}/milestones/{id}/freeze
POST   /projects/{project_id}/milestones/{id}/start
POST   /projects/{project_id}/milestones/{id}/close

# 预检接口
GET    /projects/{project_id}/milestones/{id}/preflight
  # 返回 { can_freeze: bool, can_start: bool, reasons: [...] }
```

### 4.4 任务接口

```yaml
GET    /projects/{project_id}/tasks
  # 列表
  Query: { 
    status: "open|pending|undergoing|completed|closed",
    assignee_id: int,
    milestone_id: int,
    task_type: "issue|story|test|..."
  }

POST   /projects/{project_id}/tasks
  # 创建
  Body: {
    title: string,
    milestone_id: int,
    task_type: "issue|story|test|maintenance|research|review|resolution",
    priority: "low|medium|high|critical",
    assignee_id?: int
  }

GET    /projects/{project_id}/tasks/{id}
  # 详情（包含 comments）

PATCH  /projects/{project_id}/tasks/{id}
  # 更新
  # 注意：undergoing/completed/closed 状态限制 body 编辑

DELETE /projects/{project_id}/tasks/{id}
  # 删除

# 状态机动作
POST   /projects/{project_id}/tasks/{id}/transition
  Body: { 
    action: "open|start|finish|close|reopen",
    comment?: string,  # finish 时必填
    close_reason?: string  # close 时可选
  }
```

### 4.5 Propose 接口

```yaml
GET    /projects/{project_id}/proposes
  # 列表

POST   /projects/{project_id}/proposes
  # 创建
  Body: { title: string, description?: string }

GET    /projects/{project_id}/proposes/{id}
  # 详情

PATCH  /projects/{project_id}/proposes/{id}
  # 更新（仅在 open 状态允许）

# 状态机动作
POST   /projects/{project_id}/proposes/{id}/accept
  Body: { milestone_id: int }  # 指定 milestone 创建 feature story task

POST   /projects/{project_id}/proposes/{id}/reject

POST   /projects/{project_id}/proposes/{id}/reopen
  # rejected -> open
```

### 4.6 监控接口

```yaml
GET /monitor/public/overview
  # 公开概览数据

# 管理接口
GET    /monitor/admin/servers
POST   /monitor/admin/servers
DELETE /monitor/admin/servers/{id}
POST   /monitor/admin/servers/{id}/api-key
DELETE /monitor/admin/servers/{id}/api-key

# 服务器上报（插件调用）
POST /monitor/server/heartbeat-v2
  Headers:
    X-API-Key: string
  Body:
    identifier: string
    openclaw_version: string        # 远程主机上的 OpenClaw 版本
    plugin_version: string          # harbor-forge 插件版本
    cpu_pct: float
    mem_pct: float
    disk_pct: float
    swap_pct: float
    load_avg: [float, float, float]
    uptime_seconds: int
    agents: [...]
```

### 4.7 其他接口

```yaml
# 评论
GET  /projects/{project_id}/tasks/{task_id}/comments
POST /projects/{project_id}/tasks/{task_id}/comments

# 角色权限
GET  /roles
GET  /roles/{id}
POST /roles
PATCH /roles/{id}
DELETE /roles/{id}

# Webhook
GET  /webhooks
POST /webhooks
DELETE /webhooks/{id}

# Dashboard
GET /dashboard/stats?project_id={id}

# 健康检查
GET /health
GET /version
```

---

## 5. 安全设计

### 5.1 认证
- **JWT Token**: 基于 `python-jose`，有效期 configurable
- **API Key**: 支持服务间调用
- **Admin 权限**: `users.is_admin` 字段控制

### 5.2 项目权限 (RBAC)

| 角色 | 权限范围 |
|------|----------|
| admin | 全局所有操作 |
| owner | 项目内所有操作 |
| mgr | 里程碑/任务管理，接受/拒绝 propose |
| dev | 任务操作，创建 propose |
| guest | 只读访问 |

### 5.3 监控插件安全

```
1. 服务器注册
2. 管理员生成 API Key
3. 插件将 API Key 写入 OpenClaw plugin config
4. sidecar 通过 X-API-Key 调用 /monitor/server/heartbeat-v2
5. 服务端按 API Key 识别并接收遥测
```

---

## 6. 开发里程碑

### P0 - 基础框架 ✅
- [x] 项目初始化 (FastAPI + SQLAlchemy)
- [x] 用户认证 (JWT)
- [x] Docker Compose 部署

### P1 - 核心 CRUD ✅
- [x] Projects CRUD
- [x] Milestones CRUD
- [x] Tasks CRUD
- [x] Comments

### P2 - 权限系统 ✅
- [x] Role/Permission 模型
- [x] RBAC 中间件
- [x] 项目成员管理

### P3 - 里程碑状态机 ✅
- [x] freeze/start/close 动作
- [x] 自动完成钩子
- [x] 编辑限制

### P4 - 任务依赖 ✅
- [x] depend_on 字段
- [x] 依赖检查工具
- [x] 批量操作

### P5 - 任务状态机 ✅
- [x] open/start/finish/close/reopen
- [x] 负责人检查
- [x] 完成时必须评论
- [x] 编辑限制

### P6 - Propose 系统 ✅
- [x] Propose CRUD
- [x] accept/reject/reopen
- [x] accept 时创建 feature story task

### P7 - 任务类型重构 ✅
- [x] 移除 task 类型
- [x] issue 作为默认
- [x] 前端同步更新

### P8 - 里程碑预检 ✅
- [x] preflight 接口
- [x] 前端按钮状态

### P9 - 任务操作 UI ✅
- [x] 操作按钮
- [x] 完成评论弹窗
- [x] 关闭原因弹窗

### P10 - Propose UI ✅
- [x] Propose 列表页
- [x] Propose 详情页
- [x] 编辑弹窗（仅 open 状态）

### P11 - 监控后端 ✅
- [x] Provider 账户管理
- [x] 服务器注册/挑战
- [x] 心跳接收
- [x] WebSocket 支持

### P12 - CLI 工具 ✅
- [x] 命令行交互
- [x] Webhook 管理
- [x] 配置查看

### P13 - 测试 ✅
- [x] Backend 单元测试 (pytest)
- [x] 里程碑状态机测试
- [x] 任务状态机测试
- [x] Propose 测试
- [x] Frontend E2E 测试

### P14 - OpenClaw 集成 🔄
- [x] Plugin 架构设计
- [x] 遥测服务器
- [x] 安装脚本
- [ ] 完整测试

### P15 - 文档与发布 📋
- [ ] API 文档 (OpenAPI)
- [ ] 部署文档
- [ ] 用户手册
- [ ] v1.0 发布

---

## 7. 远程服务器通信协议

### 7.1 注册流程

```mermaid
sequenceDiagram
    participant Admin
    participant Monitor
    participant Server
    participant Plugin

    Admin->>Monitor: POST /admin/servers
    Monitor->>Admin: { challenge_uuid, expires_at }
    
    Admin->>Server: 配置 challenge_uuid
    
    Plugin->>Monitor: GET /public/server-public-key
    Monitor->>Plugin: { public_key_pem, key_id }
    
    Plugin->>Plugin: 加密 payload
    Note right of Plugin: RSA-OAEP + SHA256
    
    Plugin->>Monitor: POST /server/heartbeat
    Note right of Plugin: 或 WS /server/ws
    
    Monitor->>Monitor: 验证 challenge_uuid
    Monitor->>Monitor: 验证 timestamp (防重放)
    Monitor->>Monitor: 存储 server_state
```

### 7.2 心跳协议

**HTTP Heartbeat:**
```http
POST /monitor/server/heartbeat
Content-Type: application/json
X-Server-Identifier: vps.t1
X-Challenge-UUID: abc-123-def

{
  "identifier": "vps.t1",
  "challenge_uuid": "abc-123-def",
  "timestamp": "2026-03-19T14:00:00Z",
  "cpu_pct": 12.5,
  "mem_pct": 41.2,
  "disk_pct": 62.0,
  "swap_pct": 0.0,
  "uptime_sec": 86400,
  "load_avg_1m": 0.5,
  "platform": "linux",
  "hostname": "vps.t1",
  "openclaw_version": "1.2.3",
  "openclaw_agent_count": 3,
  "openclaw_agents": [
    { "id": "dev", "name": "Developer", "status": "running" }
  ]
}
```

**WebSocket 连接:**
```javascript
// 1. 建立连接
const ws = new WebSocket('wss://monitor.example.com/monitor/server/ws');

// 2. 发送加密握手
ws.send(JSON.stringify({
  encrypted_payload: "base64_encoded_rsa_encrypted_json"
}));

// 3. 接收确认
// Server: { "status": "authenticated" }

// 4. 定期发送遥测
setInterval(() => {
  ws.send(JSON.stringify({
    type: "telemetry",
    data: { /* 同上 */ }
  }));
}, 30000);
```

### 7.3 加密格式

```python
# Payload 结构 (加密前)
{
  "identifier": "vps.t1",
  "challenge_uuid": "uuid-from-admin",
  "nonce": "random-128bit-hex",  # 防重放
  "ts": "2026-03-19T14:00:00Z"   # UTC ISO8601，10分钟有效期
}

# 加密
encrypted = RSA_OAEP_SHA256_encrypt(
  plaintext=json.dumps(payload),
  public_key=monitor_public_key
)

# 传输 (base64)
encrypted_payload_b64 = base64.b64encode(encrypted).decode()
```

---

## 8. 技术规范

### 8.1 代码规范
- **Backend**: PEP8, Black formatter, mypy type hints
- **Frontend**: ESLint, Prettier, strict TypeScript
- **Commits**: Conventional Commits (`feat:`, `fix:`, `test:`, `docs:`)

### 8.2 数据库规范
- 所有表必须有 `id` (PK, auto_increment)
- 时间字段使用 `DateTime(timezone=True)`
- 枚举使用 SQLAlchemy `Enum` + `values_callable`
- 外键必须建索引

### 8.3 API 规范
- RESTful 设计
- 统一响应格式: `{ data: ..., error?: ..., message?: ... }`
- HTTP 状态码规范使用
- 分页: `{ items: [...], total: N, page: 1, page_size: 20 }`

### 8.4 测试规范
- 测试覆盖率 > 80%
- 单元测试: SQLite in-memory
- E2E 测试: 独立 Docker 环境
- CI: GitHub Actions / Gitea Actions

---

## 9. 部署架构

### 9.1 生产环境

```yaml
# docker-compose.prod.yml
services:
  mysql:
    image: mysql:8.0
    volumes:
      - mysql_data:/var/lib/mysql
    
  backend:
    build: ./HarborForge.Backend
    environment:
      - DATABASE_URL=mysql+pymysql://...
      - SECRET_KEY=${SECRET_KEY}
    
  frontend:
    build: ./HarborForge.Frontend
    
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl
```

### 9.2 监控插件部署

```bash
# 1. 在 Monitor 注册服务器并生成 API Key
# 2. 在服务器安装插件
node scripts/install.mjs

# 3. 配置 ~/.openclaw/openclaw.json
{
  "plugins": {
    "entries": {
      "harbor-forge": {
        "enabled": true,
        "config": {
          "enabled": true,
          "apiKey": "YOUR_API_KEY",
          "monitor_port": 9100
        }
      }
    }
  }
}

# 4. 重启 Gateway
openclaw gateway restart
```

---

## 10. 参考资源

### 代码仓库
- `HarborForge.Backend` - FastAPI 后端
- `HarborForge.Frontend` - React 前端
- `HarborForge.Test` - 测试套件
- `HarborForge.OpenclawPlugin` - OpenClaw 插件

### 关键文件
- `app/models/` - SQLAlchemy 模型
- `app/api/routers/` - API 路由
- `app/schemas/schemas.py` - Pydantic 模型
- `app/services/` - 业务逻辑
- `tests/` - 测试文件

### 外部依赖
- FastAPI 0.109
- SQLAlchemy 2.0
- React 18 + Vite 5
- OpenClaw Gateway

---

**文档版本**: 0.3.0  
**最后更新**: 2026-03-19  
**维护者**: HarborForge Team