140 lines
4.2 KiB
Markdown
140 lines
4.2 KiB
Markdown
# HarborForge Backend
|
||
|
||
Agent/人类协同任务管理平台 - FastAPI 后端
|
||
|
||
## API Endpoints (38)
|
||
|
||
### Auth
|
||
- `POST /auth/token` - 登录获取 JWT token
|
||
- `GET /auth/me` - 获取当前用户信息
|
||
|
||
### Issues
|
||
|
||
> Issues 和 Search 列表接口返回分页格式：`{items, total, page, page_size, total_pages}`
|
||
> Issues 支持排序参数：`sort_by` (created_at/priority/title/due_date/status), `sort_order` (asc/desc)
|
||
> Issues 支持额外过滤：`assignee_id`, `tag`
|
||
|
||
|
||
> Issues 和 Search 列表接口返回分页格式：
|
||
> Issues 支持排序参数： (created_at/priority/title/due_date/status), (asc/desc)
|
||
> Issues 支持额外过滤：,
|
||
- `POST /issues` - 创建 issue（支持 resolution 决议案类型）
|
||
- `GET /issues` - 列表（分页、排序、按 assignee/tag 过滤）（支持按 project/status/type 过滤）
|
||
- `GET /issues/{id}` - 详情
|
||
- `PATCH /issues/{id}` - 更新
|
||
- `DELETE /issues/{id}` - 删除
|
||
- `POST /issues/{id}/transition` - 状态变更（触发 webhook）
|
||
- `GET /search/issues?q=keyword` - 搜索
|
||
|
||
### Comments
|
||
- `POST /comments` - 创建评论
|
||
- `GET /issues/{id}/comments` - 列表
|
||
- `PATCH /comments/{id}` - 更新
|
||
- `DELETE /comments/{id}` - 删除
|
||
|
||
### Projects
|
||
- `POST /projects` - 创建
|
||
- `GET /projects` - 列表
|
||
- `GET /projects/{id}` - 详情
|
||
- `PATCH /projects/{id}` - 更新
|
||
- `DELETE /projects/{id}` - 删除
|
||
|
||
### Project Members
|
||
- `POST /projects/{id}/members` - 添加成员
|
||
- `GET /projects/{id}/members` - 列表
|
||
- `DELETE /projects/{id}/members/{user_id}` - 移除
|
||
|
||
### Users
|
||
- `POST /users` - 注册
|
||
- `GET /users` - 列表
|
||
- `GET /users/{id}` - 详情
|
||
- `PATCH /users/{id}` - 更新
|
||
|
||
### Webhooks
|
||
- `POST /webhooks` - 创建
|
||
- `GET /webhooks` - 列表
|
||
- `GET /webhooks/{id}` - 详情
|
||
- `PATCH /webhooks/{id}` - 更新
|
||
- `DELETE /webhooks/{id}` - 删除
|
||
- `GET /webhooks/{id}/logs` - 投递日志
|
||
|
||
### System
|
||
- `GET /health` - 健康检查
|
||
- `GET /version` - 版本信息
|
||
- `GET /dashboard/stats` - 统计面板
|
||
|
||
### Milestones
|
||
- `POST /milestones` - 创建里程碑
|
||
- `GET /milestones` - 列表（支持按 project/status 过滤）
|
||
- `GET /milestones/{id}` - 详情
|
||
- `PATCH /milestones/{id}` - 更新
|
||
- `DELETE /milestones/{id}` - 删除
|
||
- `GET /milestones/{id}/issues` - 里程碑下的 issue 列表
|
||
- `GET /milestones/{id}/progress` - 里程碑完成进度
|
||
|
||
### Notifications
|
||
- `GET /notifications` - 列表（支持 user_id, unread_only 过滤）
|
||
- `GET /notifications/count` - 未读通知计数
|
||
- `POST /notifications/{id}/read` - 标记已读
|
||
- `POST /notifications/read-all` - 全部标记已读
|
||
|
||
### Issue Assignment
|
||
- `POST /issues/{id}/assign` - 指派 issue（自动发送通知）
|
||
|
||
### Webhook Retry
|
||
- `POST /webhooks/{id}/retry/{log_id}` - 重试失败的 webhook 投递
|
||
|
||
### Time Tracking (Work Logs)
|
||
- `POST /worklogs` - 记录工时
|
||
- `GET /issues/{id}/worklogs` - 某 issue 的工时记录
|
||
- `GET /issues/{id}/worklogs/summary` - 某 issue 工时汇总
|
||
- `GET /users/{id}/worklogs` - 某用户的工时记录
|
||
- `DELETE /worklogs/{id}` - 删除工时记录
|
||
- `GET /projects/{id}/worklogs/summary` - 项目工时汇总（按用户分组）
|
||
|
||
### Export
|
||
- `GET /export/issues` - 导出 issues CSV
|
||
- `GET /issues/overdue` - 逾期未完成的 issue
|
||
|
||
## CLI
|
||
|
||
```bash
|
||
# 环境变量
|
||
export HARBORFORGE_URL=http://localhost:8000
|
||
export HARBORFORGE_TOKEN=<your-token>
|
||
|
||
# 命令
|
||
python3 cli.py login <username> <password>
|
||
python3 cli.py issues [-p project_id] [-t type] [-s status]
|
||
python3 cli.py create-issue "title" -p 1 -r 1 [-t resolution --summary "..." --positions "..." --pending "..."]
|
||
python3 cli.py search "keyword"
|
||
python3 cli.py transition <issue_id> <new_status>
|
||
python3 cli.py stats [-p project_id]
|
||
python3 cli.py projects
|
||
python3 cli.py users
|
||
python3 cli.py milestones [-p project_id]
|
||
python3 cli.py milestone-progress <milestone_id>
|
||
python3 cli.py notifications -u <user_id> [--unread]
|
||
python3 cli.py overdue [-p project_id]
|
||
python3 cli.py log-time <issue_id> <user_id> <hours> [-d "description"]
|
||
python3 cli.py worklogs <issue_id>
|
||
python3 cli.py health
|
||
python3 cli.py version
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
- Python 3.11 + FastAPI
|
||
- SQLAlchemy + MySQL
|
||
- JWT (python-jose)
|
||
- Docker
|
||
|
||
## Issue Types
|
||
|
||
| Type | 用途 |
|
||
|------|------|
|
||
| task | 普通任务 |
|
||
| story | 用户故事 |
|
||
| test | 测试用例 |
|
||
| resolution | 决议案（Agent 僵局提交）|
|