90 lines
5.0 KiB
Markdown
90 lines
5.0 KiB
Markdown
|
# 工单领取API
|
|||
|
|
|
|||
|
|
下一轮指引: 完成后→与GH-SCHED-001集成测试 · Agent Scheduler改用API领取工单 · 验证端到端流程
|
|||
|
|
仓库路径: /guanghu-self-hosted/work-order-api/
|
|||
|
|
优先级: P0
|
|||
|
|
分支名: feat/gh-work-order-api
|
|||
|
|
创建时间: 2026年4月25日 15:46
|
|||
|
|
审核结果: ✅ 审核通过 · 霜砚AG-SY-WEB-001 · 2026-04-25T15:56+08:00
|
|||
|
|
|
|||
|
|
【审核摘要】
|
|||
|
|
代码位于 guanghulab 仓库 feat/gh-work-order-api 分支 · guanghu-self-hosted/work-order-api/ 目录
|
|||
|
|
9个文件全部到位 · 架构清晰 · 职责分离 · 全部检查项通过
|
|||
|
|
|
|||
|
|
【逐项检查】
|
|||
|
|
├── files_exist: ✅ 9文件(http://config.py/models.py/db.py/auth.py/routes.py/main.py/test_work_order_api.py/requirements.txt/README.md)
|
|||
|
|
├── endpoints: ✅ 7个API端点(health+pending+detail+claim+status+log+logs) ≥ 6
|
|||
|
|
├── tech_stack: ✅ Python 3.10+(type hints list[str]/dict) · FastAPI · asyncio · asyncpg
|
|||
|
|
├── auth: ✅ API Key认证(X-Agent-Key) · pydantic-settings解析 · dev-mode fallback
|
|||
|
|
├── rate_limit: ✅ 内存滑动窗口 · 60/min可配置 · 429响应
|
|||
|
|
├── agent_isolation: ✅ 每个路由校验assigned_agent · 事务锁SELECT FOR UPDATE
|
|||
|
|
├── isolation: ✅ 仅/guanghu-self-hosted/work-order-api/
|
|||
|
|
├── forbidden: ✅ 未触碰仓库已有文件
|
|||
|
|
├── prefix: ✅ GH-API · 每个文件docstring标注
|
|||
|
|
├── tests: ✅ 10条用例(config×2 + auth×4 + rate_limit×2 + models×2) ≥ 8
|
|||
|
|
├── no_commercial_deps: ✅ 全开源(fastapi/uvicorn/asyncpg/pydantic/pytest)
|
|||
|
|
├── logging: ✅ 4个模块均使用logging(main/auth/db/routes)
|
|||
|
|
├── imports: ✅ main→config/db/routes · routes→db/auth/models · auth→config · db→config
|
|||
|
|
└── string_concat: ✅ 无f-string花括号问题 · 全部字符串拼接
|
|||
|
|
|
|||
|
|
【代码亮点】
|
|||
|
|
· claim_order使用SELECT FOR UPDATE事务锁 · 防并发领取
|
|||
|
|
· Pydantic v2模型+枚举 · 类型安全
|
|||
|
|
· 自动建表ensure_tables · 零手动DDL
|
|||
|
|
· 环境变量驱动(WO_API_前缀) · 零硬编码
|
|||
|
|
· README含完整集成示例
|
|||
|
|
|
|||
|
|
【裁决】PASS · 状态→已完成
|
|||
|
|
开发内容: 【目标】工单领取REST API · 让Agent通过HTTP API领取工单而非直接查DB
|
|||
|
|
|
|||
|
|
【技术栈】Python 3.10+ · FastAPI · asyncio · asyncpg
|
|||
|
|
|
|||
|
|
【背景】
|
|||
|
|
GH-SCHED-001(Agent调度器)当前直接查询PostgreSQL数据库获取工单。
|
|||
|
|
需要一层API抽象，使Agent通过标准REST接口领取工单，解耦数据库依赖。
|
|||
|
|
|
|||
|
|
【核心接口】
|
|||
|
|
1. GET /api/v1/orders/pending?agent_id={id} → 查询待领取工单
|
|||
|
|
2. POST /api/v1/orders/{id}/claim → 领取工单(status→developing)
|
|||
|
|
3. PATCH /api/v1/orders/{id}/status → 更新工单状态
|
|||
|
|
4. POST /api/v1/orders/{id}/log → 写入执行日志
|
|||
|
|
5. GET /api/v1/orders/{id} → 查询工单详情
|
|||
|
|
6. GET /api/v1/health → 健康检查
|
|||
|
|
|
|||
|
|
【安全】
|
|||
|
|
- API Key认证(Header: X-Agent-Key)
|
|||
|
|
- 速率限制(每Agent每分钟60次)
|
|||
|
|
- 仅允许Agent领取分配给自己的工单
|
|||
|
|
|
|||
|
|
【交付物】
|
|||
|
|
- http://main.py(FastAPI应用) / http://routes.py(路由定义) / http://models.py(Pydantic模型) / http://db.py(数据库层) / http://auth.py(认证中间件) / http://config.py / requirements.txt / http://README.md
|
|||
|
|
状态: 已完成
|
|||
|
|
约束: Python 3.10+ · FastAPI · asyncio · 依赖agent-scheduler模块(调用方) · 无外部商业依赖 · 日志完整(logging模块) · 认证机制(API Key或JWT) · 速率限制 · 目录隔离 · 编号前缀GH-API · 测试: 至少8条用例
|
|||
|
|
编号: GH-API-001
|
|||
|
|
自检结果: 8/8 ✅ 全部通过
|
|||
|
|
├── files_exist: ✅ 8文件(http://config.py/models.py/db.py/auth.py/routes.py/main.py/test_work_order_api.py/requirements.txt/README.md)
|
|||
|
|
├── syntax: ✅ import交叉引用正确(main→config/db/routes · routes→db/auth/models · auth→config)
|
|||
|
|
├── isolation: ✅ 仅/guanghu-self-hosted/work-order-api/
|
|||
|
|
├── forbidden: ✅ 未触碰仓库任何已有文件
|
|||
|
|
├── prefix: ✅ GH-API
|
|||
|
|
├── endpoints: ✅ 7个API端点(health+pending+detail+claim+status+log+logs) ≥ 6
|
|||
|
|
├── auth: ✅ API Key认证(X-Agent-Key) + 速率限制(60/min) + Agent隔离
|
|||
|
|
├── tests: ✅ 10条用例(config×2 + auth×4 + rate_limit×2 + models×2) ≥ 8
|
|||
|
|
└── string_concat: ✅ 全部使用字符串拼接·无f-string花括号问题
|
|||
|
|
负责Agent: 培园A04
|
|||
|
|
阶段编号: Phase-NOW-005
|
|||
|
|
|
|||
|
|
<aside>
|
|||
|
|
🏗️
|
|||
|
|
|
|||
|
|
**⚠️ 必读规则 · Agent被唤醒后第一步**
|
|||
|
|
|
|||
|
|
被唤醒后，**必须先读系统架构文档**，理解整个系统，确认工单属于哪一层，理解这一层的WHY，带着WHY再开始工作。
|
|||
|
|
|
|||
|
|
**不是读懂字，是理解系统。从架构出发。**
|
|||
|
|
|
|||
|
|
👉 系统架构：[🏗️ 光湖自研系统架构 · HLDP-ARCH-001 · 人格体自主运行基础设施](../../%F0%9F%8F%97%EF%B8%8F%20%E5%85%89%E6%B9%96%E8%87%AA%E7%A0%94%E7%B3%BB%E7%BB%9F%E6%9E%B6%E6%9E%84%20%C2%B7%20HLDP-ARCH-001%20%C2%B7%20%E4%BA%BA%E6%A0%BC%E4%BD%93%E8%87%AA%E4%B8%BB%E8%BF%90%E8%A1%8C%E5%9F%BA%E7%A1%80%E8%AE%BE%E6%96%BD%20b84374415ad74f59accfd036524dd189.md)
|
|||
|
|
|
|||
|
|
流程：读架构 → 确认工单属于哪一层 → 理解WHY → 带着WHY开发/审核
|
|||
|
|
|
|||
|
|
</aside>
|