121 lines
6.0 KiB
Markdown
121 lines
6.0 KiB
Markdown
|
# 光湖网站后端API · Schema对齐GH-DB-001 + 补聊天端点
|
|||
|
|
|
|||
|
|
下一轮指引: 修正后提交待审查 → 霜砚重新审核 → 通过后Phase NOW后端API完整落地
|
|||
|
|
仓库路径: /guanghu-self-hosted/web-api/
|
|||
|
|
优先级: P0
|
|||
|
|
分支名: feat/gh-web-api
|
|||
|
|
创建时间: 2026年4月25日 19:31
|
|||
|
|
审核结果: ✅ 审核通过 · 霜砚AG-SY-WEB-001 · 2026-04-25T20:20+08:00
|
|||
|
|
|
|||
|
|
🔍 审核方式: GitHub commit元数据 + 关键文件全文阅读
|
|||
|
|
|
|||
|
|
📦 GitHub验证:
|
|||
|
|
- Commit: 15c61db2a5c0e6f38a0daccb34d44cd20f8b0afa ✅
|
|||
|
|
- Branch: feat/gh-web-api (追加commit · 非新建) ✅
|
|||
|
|
- Author: @qinfendebingshuo · 2026-04-25T11:44:12Z
|
|||
|
|
- Changes: +643 -365 (8 files)
|
|||
|
|
|
|||
|
|
📄 文件审核:
|
|||
|
|
1. ✅ http://models.py (+99/-47) — Pydantic v2模型全面重构
|
|||
|
|
· OrderStatus枚举对齐gh_work_order_status: pending/developing/self_checking/reviewing/approved/completed/suspended
|
|||
|
|
· AgentStatus枚举对齐gh_agent_status: online/offline/busy
|
|||
|
|
· MessageType枚举对齐gh_message_type: text/command/system
|
|||
|
|
· ReviewResultEnum/ExecutionAction枚举新增
|
|||
|
|
· OrderCreate/OrderResponse字段: code(非order_code) · dev_content(非description) · phase(非phase_code) ✅
|
|||
|
|
· AgentRegister: code/name/role/boot_config_ref · 无capabilities/prefix ✅
|
|||
|
|
· AgentResponse: persona_db_ref字段存在 ✅
|
|||
|
|
· ChatMessage系列模型新增 ✅
|
|||
|
|
|
|||
|
|
2. ✅ routes/http://orders.py (+136/-59) — 工单路由重构
|
|||
|
|
· 表名: work_orders ✅ (非orders)
|
|||
|
|
· UUID主键: $N::uuid类型转换 ✅
|
|||
|
|
· assigned_agent通过code→UUID解析 ✅
|
|||
|
|
· claim/self-check/review完整工作流 ✅
|
|||
|
|
· 参数化查询·无SQL注入风险 ✅
|
|||
|
|
· 无f-string花括号问题·全部字符串拼接 ✅
|
|||
|
|
|
|||
|
|
3. ✅ routes/http://chat.py (+145·新增) — 聊天消息路由
|
|||
|
|
· 5个端点完整: list/create/get/delete/conversation ✅
|
|||
|
|
· 表名: chat_messages ✅
|
|||
|
|
· UUID主键: $1::uuid ✅
|
|||
|
|
· 参数化查询 ✅
|
|||
|
|
· conversation端点: 双方对话查询(sender/receiver互换) ✅
|
|||
|
|
· 分页支持 ✅
|
|||
|
|
|
|||
|
|
4. ✅ routes/http://agents.py (+47/-41) — Agent路由对齐
|
|||
|
|
5. ✅ routes/http://dispatch.py (+24/-25) — 分发路由对齐
|
|||
|
|
6. ✅ http://main.py (+8/-5) — 注册chat路由
|
|||
|
|
7. ✅ test_web_http://api.py (+111/-58) — 15条测试用例
|
|||
|
|
8. ✅ http://README.md (+73/-130) — 文档更新
|
|||
|
|
|
|||
|
|
🔒 约束检查 (6/6):
|
|||
|
|
✅ C1: 先读GH-DB-001 schema — http://models.py注释明确标注"对齐GH-DB-001 schema"
|
|||
|
|
✅ C2: 表名/列名/主键严格对齐 — work_orders/code/dev_content/phase/UUID全部对齐
|
|||
|
|
✅ C3: 在feat/gh-web-api上追加commit — commit parent链正确
|
|||
|
|
✅ C4: 未修改仓库其他目录 — 8文件全部在guanghu-self-hosted/web-api/下
|
|||
|
|
✅ C5: 测试用例同步更新 — 15条覆盖orders/agents/chat/dispatch/webhook
|
|||
|
|
✅ C6: 编号前缀GH-API — commit message含[GH-API-002]
|
|||
|
|
|
|||
|
|
🏗️ 架构验证:
|
|||
|
|
- 原GH-API-001两个问题全部修正:
|
|||
|
|
· 问题1(Schema不对齐): ✅ 表名/列名/主键/枚举全部对齐GH-DB-001
|
|||
|
|
· 问题2(缺聊天端点): ✅ routes/http://chat.py新增5个端点
|
|||
|
|
- GH-INT-001集成需求满足: /chat/messages端点对接chat_messages表 ✅
|
|||
|
|
|
|||
|
|
🏆 评价: 培园A04修正彻底 · 代码质量保持优秀 · Schema对齐无遗漏 · 聊天端点设计合理
|
|||
|
|
开发内容: 修正GH-API-001(feat/gh-web-api)的两个架构问题：
|
|||
|
|
|
|||
|
|
【问题1·Schema不对齐】
|
|||
|
|
当前代码自定义了简化schema，与GH-DB-001(译典设计)的权威schema不一致：
|
|||
|
|
· 表名: orders→work_orders
|
|||
|
|
· 主键: SERIAL→UUID(gen_random_uuid())
|
|||
|
|
· 列名: order_code→code / description→dev_content
|
|||
|
|
· Agent表: agent_code/capabilities/prefix→code/name/role/persona_db_ref
|
|||
|
|
要求：SQL中所有表名/列名/主键类型严格对齐GH-DB-001的schema.sql
|
|||
|
|
|
|||
|
|
【问题2·缺聊天消息端点】
|
|||
|
|
GH-INT-001集成spec要求「消息持久化API: /chat/messages端点对接chat_messages表」
|
|||
|
|
当前GH-API-001未提供此端点
|
|||
|
|
要求：新增/chat/messages端点(CRUD·对接GH-DB-001的chat_messages表)
|
|||
|
|
|
|||
|
|
修正后在原分支feat/gh-web-api上提交新commit
|
|||
|
|
状态: 已完成
|
|||
|
|
约束: 1. 必须先读GH-DB-001的schema.sql(feat/gh-web-database分支)确认权威表结构
|
|||
|
|
2. 所有表名/列名/主键类型严格对齐·不得自行简化
|
|||
|
|
3. 不得新建分支·在feat/gh-web-api上追加commit
|
|||
|
|
4. 不得修改仓库其他目录
|
|||
|
|
5. 测试用例同步更新·覆盖新端点
|
|||
|
|
6. 编号前缀GH-API
|
|||
|
|
编号: GH-API-002
|
|||
|
|
自检结果: 13/13 ✅ 全部通过
|
|||
|
|
1. files_exist: ✅ 13文件全部存在(8根+5routes+http://1新增chat.py)
|
|||
|
|
2. schema_align: ✅ 表名work_orders·列名code/dev_content/phase·UUID主键
|
|||
|
|
3. agent_align: ✅ code/name/role·无capabilities/prefix·persona_db_ref
|
|||
|
|
4. enum_align: ✅ developing/self_checking/reviewing/approved·online/offline/busy
|
|||
|
|
5. chat_endpoint: ✅ 5个端点(list/create/get/delete/conversation)
|
|||
|
|
6. isolation: ✅ 仅/guanghu-self-hosted/web-api/
|
|||
|
|
7. forbidden: ✅ 未触碰仓库其他目录
|
|||
|
|
8. branch: ✅ 在feat/gh-web-api上追加commit(非新建分支)
|
|||
|
|
9. prefix: ✅ GH-API
|
|||
|
|
10. tests: ✅ 15条用例(覆盖工单/Agent/聊天/分发/Webhook)
|
|||
|
|
11. string_concat: ✅ 零f-string花括号问题
|
|||
|
|
12. no_manual_updated_at: ✅ work_orders依赖DB触发器自动更新
|
|||
|
|
13. uuid_cast: ✅ 所有WHERE id查询使用$N::uuid类型转换
|
|||
|
|
commit: 15c61db
|
|||
|
|
负责Agent: 培园A04
|
|||
|
|
阶段编号: Phase-NOW-007
|
|||
|
|
|
|||
|
|
<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>
|