docs: add round 4 debug report - sub-services and database integrity

2026-05-20 14:37:40 +08:00
parent 3adf0137cc
commit d239b958df
1 changed files with 231 additions and 0 deletions
@@ -0,0 +1,231 @@
+# 持续性调试第4轮: 子服务调试 + 数据库完整性
+
+> **日期**: 2026-05-20 (UTC+8 14:28 CST)
+> **状态**: ✅ 全部通过
+> **Go 版本**: 1.26.2
+
+---
+
+## 1. 编译与启动
+
+| 服务 | 端口 | 状态 | 编译 | 进程 PID |
+|------|------|------|------|----------|
+| Gateway | 8080 | ✅ 运行中 | 已有 | 19265 |
+| AI-Core | 8081 | ✅ 运行中 | 已有 | 15037 |
+| IoT Debug Service | 8083 | ✅ 运行中 | 已有 | 3063 |
+| Memory Service | 8091 | ✅ 运行中 | 已有 | 2434 |
+| Tool Engine | 8092 | ✅ 运行中 | 本轮新建 | 29391 |
+| Voice Service | 8093 | ✅ 运行中 | 已有 | 7641 |
+
+**Tool Engine** 为本轮唯一需要编译和启动的服务。编译命令:
+```bash
+cd backend && go build -o tool-engine/cmd/tool-engine ./tool-engine/cmd/
+```
+启动时传入环境变量: `PORT=8092`, `IOT_SERVICE_URL=http://localhost:8083`, `DB_URL=postgres://...`, `DATA_DIR=/tmp/cyrene_data`。
+
+---
+
+## 2. 健康检查
+
+### 2.1 Memory Service (8091)
+```json
+{"status": "ok", "service": "memory-service"}
+```
+数据库连接正常 (`IsReady() == true`)，pgvector extension 已加载。
+
+### 2.2 Tool Engine (8092)
+```json
+{"status": "ok", "service": "tool-engine"}
+```
+已注册 **13 个工具**: calculator, datetime, text, crypto, random, markdown, json_ops, file_ops, http_request, web_search, web_fetch, iot_query, iot_control。
+
+IoT 客户端已连接到 `http://localhost:8083`。
+
+### 2.3 IoT Debug Service (8083)
+```json
+{"status": "ok", "service": "iot-debug-service"}
+```
+模拟 **8 个设备**: 客厅灯, 卧室灯, 客厅空调, 卧室空调, 客厅窗帘, 温度传感器, 湿度传感器, 智能门锁。
+
+传感器波动模拟每 30 秒运行一次。
+
+### 2.4 Voice Service (8093)
+```json
+{
+  "status": "ok",
+  "service": "voice-service",
+  "stt": {"available": true, "model_loaded": true, "model_name": "ggml-small.bin"},
+  "tts": {"available": false, "engine": "fallback (silent WAV)", "edge_tts": false}
+}
+```
+- **STT (Whisper)**: ✅ 可用，模型已加载 (`ggml-small.bin`)，支持 zh/en/ja/ko/auto
+- **TTS (Edge-TTS)**: ⚠️ 降级 — `edge-tts` Python 包未安装，当前使用 fallback silent WAV。安装命令: `pip install edge-tts`
+
+### 2.5 Gateway (8080)
+```json
+{"status": "ok", "service": "cyrene-gateway", "ws_connections": 0}
+```
+
+---
+
+## 3. Gateway 转发测试
+
+### 3.1 Memory CRUD (通过 Gateway)
+
+| 操作 | 端点 | 方法 | 结果 |
+|------|------|------|------|
+| 列出记忆 | `/api/v1/memory` | GET | ✅ 返回已有记忆 |
+| 创建记忆 | `/api/v1/memory` | POST | ✅ `{"status":"saved"}` |
+| 搜索记忆 | `/api/v1/memory/search?q=测试` | GET | ✅ 匹配成功 |
+
+认证令牌: `admin_yeij0942` (JWT 验证通过)
+
+### 3.2 注意事项
+
+Memory Service 端点实际路径为 `/api/v1/memories` (复数)，Gateway 通过 [`memory_handler.go`](backend/gateway/internal/handler/memory_handler.go:29) 代理到正确路径。搜索功能将 Gateway 的 `GET /api/v1/memory/search?q=xxx` 转发为 `POST /api/v1/memories/query`。
+
+---
+
+## 4. 工具引擎功能验证
+
+### 4.1 计算器
+```bash
+POST /api/v1/tools/calculator/execute
+{"arguments": {"expression": "2+3*4"}}
+→ {"output": "表达式: 2+3*4\n结果: 14"}
+```
+✅ 正确计算 (优先乘除)
+
+### 4.2 日期时间
+```bash
+POST /api/v1/tools/datetime/execute
+{"arguments": {"action": "now"}}
+→ {"output": "当前时间: 2026-05-20 14:27:13\n时区: Local\nUnix时间戳: 1779258433"}
+```
+✅ 时间戳正确
+
+### 4.3 加密哈希
+```bash
+POST /api/v1/tools/crypto/execute
+{"arguments": {"action": "hash", "algorithm": "sha256", "input": "hello"}}
+→ {"output": "哈希算法: sha256\n输入长度: 5 字节\n哈希值 (hex): 2cf24dba..."}
+```
+✅ SHA256 哈希正确 (与 `echo -n hello | sha256sum` 一致)
+
+### 4.4 调用日志存储
+- 数据库表 `tool_call_logs` 已创建并可使用
+- 调用日志异步写入（go routine 方式）
+
+---
+
+## 5. IoT 端点测试
+
+| 操作 | 端点 | 方法 | 结果 |
+|------|------|------|------|
+| 列出设备 | `/api/v1/devices` | GET | ✅ 返回 8 个设备 |
+| 获取设备 | `/api/v1/devices/light-livingroom` | GET | ✅ 含状态历史 |
+| 切换灯光 | `/api/v1/devices/light-livingroom/toggle` | POST | ✅ on→off/off→on |
+| 设置温度 | `/api/v1/devices/ac-livingroom/set` | POST | ✅ 温度设为 28°C |
+
+设备状态历史正确记录，状态变更带时间戳。
+
+---
+
+## 6. 数据库完整性
+
+### 6.1 表清单 (15/15)
+
+| # | 表名 | 用途 | 服务 |
+|---|------|------|------|
+| 1 | `users` | 用户账户认证 | Gateway |
+| 2 | `sessions` | 会话管理 | Gateway |
+| 3 | `messages` | 消息存储 | Gateway |
+| 4 | `memories` | 旧版记忆表 | Gateway |
+| 5 | `memory_entries` | 新版记忆表 (pgvector) | Memory Service |
+| 6 | `thinking_logs` | 自主思考日志 | Memory Service |
+| 7 | `tool_call_logs` | 工具调用日志 | Tool Engine |
+| 8 | `reminders` | 提醒 | Gateway |
+| 9 | `daily_briefings` | 每日简报 | Gateway |
+| 10 | `automation_rules` | 自动化规则 | Gateway |
+| 11 | `automation_scenes` | 自动化场景 | Gateway |
+| 12 | `files` | 文件管理 | Gateway |
+| 13 | `knowledge_bases` | 知识库 | Gateway |
+| 14 | `knowledge_documents` | 知识文档 | Gateway |
+| 15 | `knowledge_chunks` | 知识分块 (含全文搜索) | Gateway |
+
+### 6.2 新增 `users` 表结构
+
+| 列 | 类型 | 约束 |
+|----|------|------|
+| `id` | INTEGER | PK, NOT NULL |
+| `username` | VARCHAR(255) | NOT NULL, UNIQUE |
+| `password_hash` | VARCHAR(255) | NOT NULL |
+| `is_admin` | BOOLEAN | NULLABLE |
+| `created_at` | TIMESTAMPTZ | NULLABLE |
+| `updated_at` | TIMESTAMPTZ | NULLABLE |
+
+索引: `users_pkey` (btree id), `users_username_key` (unique btree username), `idx_users_username` (btree username)
+
+### 6.3 外键关系 (3)
+
+| 子表 | 列 | 父表 | 引用列 | 约束名 |
+|------|----|------|---------|--------|
+| `messages` | `session_id` | `sessions` | `id` | `messages_session_id_fkey` |
+| `knowledge_documents` | `kb_id` | `knowledge_bases` | `id` | `knowledge_documents_kb_id_fkey` |
+| `knowledge_chunks` | `doc_id` | `knowledge_documents` | `id` | `knowledge_chunks_doc_id_fkey` |
+
+### 6.4 索引统计
+
+- 总计: **58 个索引**
+- 所有表均有主键索引 (btree)
+- 性能关键索引覆盖: `user_id`, `session_id`, `created_at`, `category`, `priority`, `importance`, `status`
+- 全文搜索: `knowledge_chunks` 有 GIN 索引 (`idx_kc_tsv_gin`)
+- 唯一约束: `users(username)`, `daily_briefings(user_id, date)`
+- JSONB: `tool_call_logs` 使用 JSONB 存储参数
+
+### 6.5 注意事项
+
+- `memories` 和 `memory_entries` 是两套独立的记忆表。`memory_entries` 是 Memory Service 通过 pgvector 管理的版本，包含向量嵌入和更丰富的元数据（importance, keywords, source, access_count 等）。`memories` 是 Gateway 的旧版表。
+- `users` 表使用 INTEGER 自增 ID，而非 UUID。Gateway 认证生成 `admin_{username}` 格式的 user_id，但不与数据库 `id` 直接关联。
+
+---
+
+## 7. 系统时间
+
+```
+UTC:      Wed May 20 06:28:13 UTC 2026
+北京时间:   Wed May 20 14:28:13 CST 2026
+```
+
+时间正常，与预期一致。
+
+---
+
+## 8. 总结
+
+### 通过 ✅
+- 所有 4 个子服务编译成功并运行
+- 所有健康检查返回 `"ok"`
+- Gateway 正确转发 Memory CRUD 请求
+- Tool Engine 13 个工具全部注册，计算器/日期/加密工具验证通过
+- IoT 设备模拟器 8 个设备正常工作，Toggle/Set 属性测试通过
+- 数据库 15 张表完整，58 个索引，3 个外键关系正确
+- `users` 表结构完整，含唯一用户名约束和管理员标记
+
+### 待改进 ⚠️
+- **Voice Service TTS 降级**: `edge-tts` Python 包未安装，当前使用 silent WAV fallback。建议安装: `pip install edge-tts`
+- **双记忆表**: `memories` 和 `memory_entries` 共存，可能造成混淆，建议迁移合并
+- **users 表 ID 类型**: 使用 INTEGER 自增和 VARCHAR user_id 的混合策略，未来可统一为 UUID
+
+---
+
+## 9. 端口占用全景
+
+| 端口 | 服务 | PID | 二进制 |
+|------|------|-----|--------|
+| 8080 | Gateway | 19265 | `/home/aska/Code/Cyrene/backend/gateway/cmd/gateway` |
+| 8081 | AI-Core | 15037 | `./main` |
+| 8083 | IoT Debug | 3063 | `/home/aska/Code/Cyrene/backend/iot-debug-service/main` |
+| 8091 | Memory | 2434 | `/home/aska/Code/Cyrene/backend/memory-service/main` |
+| 8092 | Tool Engine | 29391 | `/home/aska/Code/Cyrene/backend/tool-engine/cmd/tool-engine` |
+| 8093 | Voice | 7641 | `/home/aska/Code/Cyrene/backend/voice-service/main` |