95 lines
4.9 KiB
Markdown
95 lines
4.9 KiB
Markdown
|
# 光湖网站后端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>
|