# 工单领取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>