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

# 环境变量
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 僵局提交）