# 光湖工单数据库设计

下一轮指引: 完成后→GH-API-001连接此数据库 · seed.sql需包含4个Agent初始数据
仓库路径: /guanghu-self-hosted/web-database/
优先级: P0
分支名: feat/gh-web-database
创建时间: 2026年4月25日 15:30
审核结果: ✅ PASS（架构驱动重审确认）· 霜砚 · 2026-04-25T16:13+08:00

━━━ 架构定位 ━━━
GH-DB-001 = 系统地基层。定义5张表的权威schema。
所有上层模块（GH-API-001/GH-INT-001/GH-CHAT-001）都引用此schema。

━━━ 架构验证 ━━━
✅ GH-INT-001集成spec引用chat_messages表做消息持久化 → 本工单有此表
✅ GH-API-001工单要求「连接GH-DB-001设计的表」→ 本工单定义了权威schema
✅ PersonaDB跨层连接: agents.persona_db_ref FK→personas(id)
✅ 6枚举用gh_前缀 → 与PersonaDB同实例不冲突
✅ work_orders表的status枚举7值 → 覆盖完整工单生命周期

━━━ 代码审核（逐文件·维持原判）━━━
schema.sql(185行) ✅ · indexes.sql(60行) ✅ · seed.sql(45行) ✅ · migrations/001_init.sql(123行) ✅ · http://README.md(97行) ✅
约束检查: 10/10全通过

━━━ 结论 ━━━
架构验证通过 · 代码审核通过 · schema是全系统权威数据结构 · PASS确认
开发内容: 【目标】光湖网站工单系统数据库 · 替代Notion数据库的自有工单引擎

【技术栈】PostgreSQL 15+ · 与PersonaDB同实例

【表设计】
1. work_orders — 工单主表
   id(UUID PK) / code(VARCHAR UNIQUE 如GH-WEB-001) / title / status(ENUM: pending/developing/self_checking/reviewing/approved/completed/suspended) / assigned_agent(FK→agents) / priority(ENUM: P0/P1/P2) / phase(VARCHAR) / dev_content(TEXT) / constraints(TEXT) / branch_name / repo_path / self_check_result(TEXT) / review_result(TEXT) / next_guide(TEXT) / created_at / updated_at

2. agents — Agent注册表
   id(UUID PK) / code(VARCHAR UNIQUE 如A05) / name(如译典) / role(如配置开发) / status(ENUM: online/offline/busy) / last_heartbeat(TIMESTAMP) / boot_config_ref(TEXT) / persona_db_ref(FK→personas) / created_at

3. execution_logs — 执行日志
   id(UUID PK) / order_id(FK→work_orders) / agent_id(FK→agents) / action(ENUM: claimed/started/self_checked/submitted/reviewed) / git_commit(VARCHAR) / detail(JSONB) / created_at

4. review_records — 审核记录
   id(UUID PK) / order_id(FK→work_orders) / reviewer(VARCHAR) / result(ENUM: pass/fail/revision_needed) / detail(TEXT) / created_at

5. chat_messages — 聊天消息(预留)
   id(UUID PK) / sender(VARCHAR) / receiver(VARCHAR) / content(TEXT) / msg_type(ENUM: text/command/system) / created_at

【索引】
- work_orders: status + assigned_agent组合索引 / code唯一索引 / created_at降序
- execution_logs: order_id + created_at / agent_id
- agents: code唯一索引

【交付物】
- schema.sql(建表+枚举+约束) / indexes.sql(索引) / seed.sql(初始Agent数据: 译典/培园/录册/霜砚Web) / migrations/001_init.sql(可复现迁移) / http://README.md
状态: 已完成
约束: PostgreSQL 15+ · 与PersonaDB(Phase-0-004)同实例不冲突 · snake_case · UTF-8 · COMMENT ON全表全列 · 外键约束完整 · 执行顺序: schema→indexes→seed · 禁触persona-db目录 · 编号前缀GH-DB
编号: GH-DB-001
自检结果: ⚡ 自动唤醒确认 · 译典A05 · 2026-04-25T15:46+08:00

━━━ Phase NOW 自检清单 ━━━
✅ 检查1：触发器正常
  · http://notion.page.created on 半体工单 → enabled ✅
  · agent.mentioned → enabled ✅
  · http://notion.page.updated on 半体工单 → enabled ✅ (额外)
✅ 检查2：工单数据库连接正常
  · 读取「⚡ 半体工单」成功
  · GH-DB-001 存在 · 负责Agent=译典A05 ✅
  · 状态=待审查（开发已完成）
⚠️ 检查3：GitHub仓库访问部分通过
  · 仓库根目录可访问 ✅
  · /guanghu-self-hosted/ 在main分支不存在（feature分支未合并）
  · feat/gh-web-database 分支上 /guanghu-self-hosted/web-database/ 5文件全在 ✅
  · schema.sql(10018B) indexes.sql(2533B) seed.sql(1214B) migrations/ http://README.md(3702B)
✅ 检查4：指令页已更新
  · 🚨 架构重排通知 section 存在 ✅
  · GH-* 前缀已记录 ✅
  · 新工单GH-DB-001内容摘要已存在 ✅
✅ 检查5：自动唤醒确认
  · 收到霜砚广播消息 → 已被唤醒 ✅
  · 触发链路正常 ✅

━━━ 自检结论：4/5 PASS · 1/5 部分通过 ━━━
说明：检查3 /guanghu-self-hosted/ 在main分支不存在是预期行为——所有feature分支尚未合并到main。在feat/gh-web-database分支上文件完整。

━━━ GH-DB-001 开发状态 ━━━
开发已完成 · 等待审查
Commit: 17e7d010a7c9ef5a5f2cd9e60dea5e7e2f32768d
分支: feat/gh-web-database
交付物: schema.sql / indexes.sql / seed.sql / migrations/001_init.sql / http://README.md
5表+6枚举+7索引+4Agent种子数据
负责Agent: 译典A05
阶段编号: Phase-NOW-003

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