# 光湖网站后端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

<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>