# 光湖网站后端API 下一轮指引: 完成后→与GH-WEB-001前端联调 · 然后对接GH-SCHED-001调度器 仓库路径: /guanghu-self-hosted/web-api/ 优先级: P0 分支名: feat/gh-web-api 创建时间: 2026年4月25日 15:30 审核结果: ⚠️ CONDITIONAL PASS（架构驱动重审·降级）· 霜砚 · 2026-04-25T16:13+08:00 ━━━ 架构定位 ━━━ GH-API-001 = 中间层。FastAPI后端，连接GH-DB-001的表，为前端和集成层提供数据接口。 工单开发内容明确要求:「连接GH-DB-001设计的表 · asyncpg连接池」 ━━━ 架构验证 ━━━ 🔴 问题1 · Schema不对齐（约束违反·阻塞集成） 工单要求「连接GH-DB-001设计的表」但代码自定义了简化schema: · 表名: orders(API) vs work_orders(DB) ← 不一致 · 主键: SERIAL(API) vs UUID(DB) ← 不一致 · 列名: order_code vs code / description vs dev_content ← 不一致 · Agent表: agent_code/capabilities/prefix vs code/name/role/persona_db_ref ← 不一致 后果: GH-INT-001集成时API无法直接连接DB层 定性: 这不是并行开发分歧·是约束违反·工单说连接DB的表·代码没连 🟡 问题2 · 缺chat_messages端点 GH-INT-001集成spec要求「消息持久化API: /chat/messages端点对接chat_messages表」 GH-API-001未提供此端点 后果: 聊天消息持久化接口需要集成层自己写·打破架构分工 ━━━ 代码质量（维持原判·优秀）━━━ ✅ FastAPI+asyncpg+Pydantic v2 · ✅ 16端点(超规格) · ✅ 13 pytest(超约束) ✅ 零硬编码 · ✅ HMAC验证 · ✅ 事务调度 · ✅ 目录隔离 ━━━ 需要培园A04修正 ━━━ 1. SQL中所有表名/列名对齐GH-DB-001的schema(work_orders/code/dev_content等) 2. 主键类型从SERIAL改为UUID(使用gen_random_uuid()) 3. Agent表字段对齐DB定义(code/name/role/persona_db_ref) 4. 新增/chat/messages端点(CRUD·对接chat_messages表) 5. 修正后重新提交审查 ━━━ 结论 ━━━ 代码质量优秀·但架构不对齐·需修正后重审 状态回退: 已完成→待开发（需schema对齐+补端点） 开发内容: 【目标】光湖网站后端API · 工单引擎+Agent管理+GitHub集成 【技术栈】FastAPI + asyncpg + Pydantic v2 + uvicorn 【API端点】 1. /api/health — 健康检查 2. /api/orders — 工单CRUD(GET列表/POST创建/PATCH更新/GET详情) 3. /api/orders/{id}/claim — Agent领取工单 4. /api/orders/{id}/self-check — 提交自检结果 5. /api/orders/{id}/review — 提交审核结果 6. /api/agents — Agent注册+列表+心跳 7. /api/agents/{id}/status — Agent状态更新 8. /api/dispatch — 任务分发(查询待开发工单→匹配Agent→下发) 9. /api/webhook/github — GitHub Webhook接收(push/PR事件) 10. /api/auth/token — JWT认证(预留·Phase 2实现) 【数据库】 - 连接GH-DB-001设计的表 - asyncpg连接池 · 环境变量配置 【与Phase 0集成】 - 工具回执: 调用tool-receipt模块记录Agent操作 - Boot Protocol: 预留启动Agent接口 【交付物】 - http://main.py(FastAPI app + lifespan) / http://config.py(Pydantic Settings) / http://models.py(请求/响应模型) / routes/ (http://orders.py + http://agents.py + http://dispatch.py + http://webhook.py) / http://db.py(连接池) / requirements.txt / http://README.md 状态: 待开发 约束: Python 3.10+ · FastAPI · asyncpg · Pydantic v2 · UTF-8 · 环境变量配置·零硬编码 · 目录隔离: 仅操作web-api/ · 禁触其他模块 · CORS配置(允许前端域名) · 编号前缀GH-API · 测试: 至少10条pytest用例 编号: GH-API-001 自检结果: ⚡ 自动唤醒确认 · 培园A04 · 2026-04-25T15:46+08:00 □ 检查1 ✅ 触发器正常：http://notion.page.created(enabled) + agent.mentioned(enabled) □ 检查2 ✅ 工单数据库连接正常：能读取半体工单·GH-API-001/GH-SCHED-001可见·负责Agent=培园A04 □ 检查3 ⚠️ GitHub访问正常·仓库根可读·/guanghu-self-hosted/在main不存在(预期·代码在feature分支) □ 检查4 ✅ 指令页已更新：有架构重排通知·GH-*前缀·新工单摘要 □ 检查5 ✅ 自动唤醒正常（本次由@提及触发） 负责Agent: 培园A04 阶段编号: Phase-NOW-002