task-board/API-V2.md

# API v2 升级说明

## 🎉 新功能概览

### 1. 项目管理
- 所有任务必须隶属于项目
- 项目由人类创建和管理

### 2. 协作规约
- 每个项目可设置协作规约
- 智能体领取任务时会收到规约提醒
- 智能体必须严格遵守规约内容

### 3. 信息共享清单
- 每个项目维护共享笔记列表
- 人类和智能体都可以添加/编辑
- 支持 CRUD 操作

### 4. 任务增强
- **Markdown 支持**: 任务描述使用 Markdown 格式
- **附件管理**: 支持文件上传（最大 10MB）
- **子任务**: 支持父子任务关系
- **任务类型**: requirement（需求）| design（设计）| development（开发）| testing（测试）| deployment（部署）
- **新状态流**: initial（初始）→ in_progress（进行中）→ testing_pending（待测试）→ testing（测试中）→ completed（完成）

## 📡 API 端点

### 项目管理

#### 创建项目
```http
POST /api/projects
Content-Type: application/json

{
  "name": "项目名称",
  "description": "项目描述",
  "created_by": "human"
}
```

#### 获取所有项目
```http
GET /api/projects
```

#### 获取项目详情
```http
GET /api/projects/:id
```

#### 更新项目
```http
PUT /api/projects/:id
Content-Type: application/json

{
  "name": "新名称",
  "description": "新描述",
  "status": "active" | "archived"
}
```

### 协作规约

#### 设置项目协作规约
```http
POST /api/projects/:projectId/rules
Content-Type: application/json

{
  "content": "协作规约内容（Markdown）",
  "created_by": "human"
}
```

#### 获取协作规约
```http
GET /api/projects/:projectId/rules
```

### 信息共享清单

#### 添加共享笔记
```http
POST /api/projects/:projectId/notes
Content-Type: application/json

{
  "content": "笔记内容（Markdown）",
  "created_by": "human" | "agent_id"
}
```

#### 获取共享笔记列表
```http
GET /api/projects/:projectId/notes
```

#### 更新共享笔记
```http
PUT /api/projects/:projectId/notes/:noteId
Content-Type: application/json

{
  "content": "更新后的内容"
}
```

#### 删除共享笔记
```http
DELETE /api/projects/:projectId/notes/:noteId
```

### 任务管理（增强）

#### 创建任务
```http
POST /api/tasks
Content-Type: application/json

{
  "project_id": "项目ID",  // 必填
  "parent_task_id": "父任务ID",  // 可选，创建子任务时使用
  "title": "任务标题",
  "description": "# 任务描述\n\n使用 **Markdown** 格式",
  "task_type": "development",  // requirement | design | development | testing | deployment
  "priority": "normal",  // low | normal | high
  "created_by": "human"
}
```

#### 获取任务列表
```http
GET /api/tasks?project_id=xxx&status=initial&root=true

参数：
- project_id: 按项目过滤
- status: initial | in_progress | testing_pending | testing | completed
- parent_task_id: 获取某任务的子任务
- root=true: 只获取根任务（无父任务）
```

#### 获取任务详情（含子任务和附件）
```http
GET /api/tasks/:id

响应:
{
  "id": "xxx",
  "title": "...",
  ...
  "subtasks": [ ... ],  // 子任务列表
  "attachments": [ ... ]  // 附件列表
}
```

#### 领取任务（智能体会收到协作规约）
```http
POST /api/tasks/:id/claim
Content-Type: application/json

{
  "agent_id": "智能体ID"
}

响应（如果项目有协作规约）:
{
  "message": "任务领取成功",
  "collaboration_rules": "项目协作规约内容",
  "notice": "⚠️ 请严格遵守项目协作规约"
}
```

#### 更新任务
```http
PUT /api/tasks/:id
Content-Type: application/json

{
  "status": "in_progress",
  "description": "更新描述",
  "task_type": "testing",
  "priority": "high",
  "result": "任务结果"
}
```

### 附件管理

#### 上传附件
```http
POST /api/tasks/:taskId/attachments
Content-Type: multipart/form-data

file: [文件]
uploaded_by: "human" | "agent_id"

限制：单文件最大 10MB
```

#### 获取任务附件列表
```http
GET /api/tasks/:taskId/attachments

响应:
[
  {
    "id": "xxx",
    "filename": "...",
    "original_name": "原始文件名",
    "file_size": 12345,
    "mime_type": "image/png",
    "url": "/uploads/xxx",
    ...
  }
]
```

#### 删除附件
```http
DELETE /api/tasks/:taskId/attachments/:attachmentId
```

### 统计信息（增强）

```http
GET /api/stats

响应:
{
  "total_agents": 5,
  "active_agents": 2,
  "total_projects": 3,
  "total_tasks": 20,
  "tasks_by_status": {
    "initial": 5,
    "in_progress": 3,
    "testing_pending": 2,
    "testing": 1,
    "completed": 9
  },
  "tasks_by_type": {
    "requirement": 4,
    "design": 3,
    "development": 8,
    "testing": 3,
    "deployment": 2
  }
}
```

## 🗄️ 数据库变更

### 新增表

1. **projects** - 项目表
   - id, name, description, created_by, created_at, updated_at, status

2. **collaboration_rules** - 协作规约表
   - id, project_id, content, created_by, created_at, updated_at

3. **project_notes** - 项目共享笔记表
   - id, project_id, content, created_by, created_at, updated_at

4. **attachments** - 附件表
   - id, task_id, filename, original_name, file_path, file_size, mime_type, uploaded_by, uploaded_at

### 修改表

**tasks** 表新增字段：
- `project_id` - 所属项目（外键，必填）
- `parent_task_id` - 父任务ID（外键，可选）
- `task_type` - 任务类型（requirement/design/development/testing/deployment）
- 状态值更新为：initial | in_progress | testing_pending | testing | completed

## 🔧 使用示例

### Python 客户端示例

```python
import requests

API_BASE = "http://localhost:3000/api"

# 1. 创建项目
project = requests.post(f"{API_BASE}/projects", json={
    "name": "智能客服系统",
    "description": "基于 AI 的客服系统开发项目"
}).json()

project_id = project['id']

# 2. 设置协作规约
requests.post(f"{API_BASE}/projects/{project_id}/rules", json={
    "content": """
# 协作规约

1. **代码规范**: 严格遵循 PEP 8
2. **提交规范**: 每次提交必须包含测试
3. **沟通规范**: 遇到问题及时在共享清单记录
4. **测试要求**: 覆盖率不低于 80%
    """
})

# 3. 创建任务
task = requests.post(f"{API_BASE}/tasks", json={
    "project_id": project_id,
    "title": "设计数据库架构",
    "description": "## 需求\n\n设计用户、会话、消息三张表",
    "task_type": "design",
    "priority": "high"
}).json()

task_id = task['id']

# 4. 智能体注册并领取任务
agent = requests.post(f"{API_BASE}/agents/register", json={
    "name": "数据库设计专家",
    "type": "design",
    "capabilities": ["database_design", "sql"]
}).json()

response = requests.post(f"{API_BASE}/tasks/{task_id}/claim", json={
    "agent_id": agent['id']
}).json()

# 智能体会收到协作规约
if 'collaboration_rules' in response:
    print("收到协作规约:")
    print(response['collaboration_rules'])

# 5. 添加共享笔记
requests.post(f"{API_BASE}/projects/{project_id}/notes", json={
    "content": "数据库已选择 PostgreSQL 15",
    "created_by": agent['id']
})

# 6. 上传附件（设计图）
with open('database_schema.png', 'rb') as f:
    requests.post(
        f"{API_BASE}/tasks/{task_id}/attachments",
        files={'file': f},
        data={'uploaded_by': agent['id']}
    )

# 7. 完成任务
requests.put(f"{API_BASE}/tasks/{task_id}", json={
    "status": "completed",
    "result": "数据库架构设计完成，详见附件"
})
```

## 📝 迁移指南

如果你有使用 v1 版本的数据，需要：

1. **备份数据库**
```bash
pg_dump agent_tasks > backup.sql
```

2. **运行 v2 服务**（会自动创建新表）
```bash
node server-v2.js
```

3. **手动迁移任务**
   - 创建一个默认项目
   - 将所有 v1 任务关联到该项目

## 🚀 部署

使用 `server-v2.js` 替代 `server-postgres.js`:

```bash
DB_HOST=localhost DB_PORT=5433 DB_PASSWORD=postgres node server-v2.js
```

或更新 `package.json`:
```json
{
  "scripts": {
    "start": "node server-v2.js"
  }
}
```

## ⚠️ 重要变更

1. **所有任务必须属于项目** - 创建任务时 `project_id` 为必填
2. **任务状态变更** - 从 3 个状态扩展到 5 个状态
3. **新增任务类型** - 必须指定任务类型
4. **协作规约强制推送** - 智能体领取任务时自动获取规约