Merge pull request 'feat: sync monitor API key integration across submodules' (#4) from feat/milestone-propose-state-machine into main

Reviewed-on: #4

DEVELOPMENT_PLAN.md

@@ -0,0 +1,650 @@
+# 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          # harborforge-monitor 插件版本
+    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 注册服务器，获取 challenge_uuid
+# 2. 在服务器安装插件
+node scripts/install.mjs
+
+# 3. 配置 ~/.openclaw/openclaw.json
+{
+  "plugins": {
+    "harborforge-monitor": {
+      "enabled": true,
+      "challengeUuid": "YOUR_CHALLENGE_UUID"
+    }
+  }
+}
+
+# 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