ed77095a37
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
三层架构增强: - L0 index.md: 用户功能清单+跨模块数据流全景图+导航树增强 (92→143行) - L1 8个模块页标准化: 功能清单/API接口/测试链路/已知问题 routing(252→326) chat(101→157) saas(153→230) memory(182→333) butler(137→179) middleware(121→159) hands-skills(218→257) pipeline(111→156) - L1 新增2页: security.md(157行) data-model.md(180行) - L2 feature-map.md: 33条端到端功能链路映射(408行) 维护机制: CLAUDE.md §8.3 wiki触发规则 5→9条 设计文档: docs/superpowers/specs/2026-04-21-wiki-systematic-overhaul-design.md
181 lines
6.9 KiB
Markdown
181 lines
6.9 KiB
Markdown
---
|
||
title: 数据模型
|
||
updated: 2026-04-21
|
||
status: active
|
||
tags: [module, database, schema]
|
||
---
|
||
|
||
# 数据模型
|
||
|
||
> 从 [[index]] 导航。关联模块: [[saas]] [[memory]]
|
||
|
||
## 设计思想
|
||
|
||
**双存储架构: PostgreSQL (SaaS 多租户) + SQLite (本地单用户)**
|
||
|
||
- PostgreSQL: SaaS 后端，42 表，42 CREATE TABLE，支持多用户/多 Agent/计费/知识库
|
||
- SQLite: 本地桌面端，记忆存储 + 会话持久化 + FTS5 全文索引
|
||
- 两者通过 SaaS relay + 配置同步实现数据桥接
|
||
|
||
## 功能清单
|
||
|
||
| 功能 | 描述 | 存储层 | 状态 |
|
||
|------|------|--------|------|
|
||
| 用户管理 | 账户 CRUD + 角色权限 | PostgreSQL | ✅ |
|
||
| 认证数据 | JWT + 密码 + TOTP | PostgreSQL | ✅ |
|
||
| 计费系统 | 订阅/支付/发票/配额 | PostgreSQL | ✅ |
|
||
| 知识库 | 分类/条目/向量/结构化 | PostgreSQL | ✅ |
|
||
| 模型管理 | Provider/模型/Key 池 | PostgreSQL | ✅ |
|
||
| Agent 配置 | 模板/分配/行业 | PostgreSQL | ✅ |
|
||
| 本地会话 | 会话/消息持久化 | SQLite | ✅ |
|
||
| 本地记忆 | 记忆 CRUD + FTS5 搜索 | SQLite | ✅ |
|
||
| 用户画像 | 结构化偏好/兴趣 | SQLite | ✅ |
|
||
| 轨迹记录 | 工具调用链 + 压缩摘要 | SQLite | ✅ |
|
||
|
||
## 代码逻辑
|
||
|
||
### PostgreSQL (SaaS) — 42 表
|
||
|
||
**迁移文件**: `crates/zclaw-saas/migrations/` (21 up + 17 down)
|
||
|
||
#### 认证与账户域 (5 表)
|
||
|
||
| 表 | 说明 | 关键关系 |
|
||
|----|------|---------|
|
||
| `accounts` | 用户账户 (邮箱/密码/pwv/角色) | → api_tokens, operation_logs, subscriptions |
|
||
| `api_tokens` | API 访问令牌 | FK → accounts |
|
||
| `roles` | 角色定义 | — |
|
||
| `permission_templates` | 权限模板 | — |
|
||
| `refresh_tokens` | JWT 刷新令牌 (单次使用) | FK → accounts |
|
||
|
||
#### Provider 与模型域 (6 表)
|
||
|
||
| 表 | 说明 | 关键关系 |
|
||
|----|------|---------|
|
||
| `providers` | LLM Provider 配置 | → models, provider_keys |
|
||
| `models` | 模型定义 (白名单) | FK → providers |
|
||
| `provider_keys` | 加密 API Key 池 | FK → providers, accounts |
|
||
| `key_usage_window` | Key RPM/TPM 滑动窗口 | — |
|
||
| `model_groups` | 模型组 (故障转移) | → model_group_members |
|
||
| `model_group_members` | 组成员 | FK → model_groups, providers |
|
||
|
||
#### 计费域 (5 表)
|
||
|
||
| 表 | 说明 | 关键关系 |
|
||
|----|------|---------|
|
||
| `billing_plans` | 计费计划目录 | → subscriptions |
|
||
| `billing_subscriptions` | 用户订阅 | FK → accounts, billing_plans |
|
||
| `billing_invoices` | 发票 | FK → accounts, subscriptions, plans |
|
||
| `billing_payments` | 支付记录 | FK → billing_invoices, accounts |
|
||
| `billing_usage_quotas` | 用量配额 | FK → accounts, billing_plans |
|
||
|
||
#### 知识库域 (7 表)
|
||
|
||
| 表 | 说明 | 关键关系 |
|
||
|----|------|---------|
|
||
| `knowledge_categories` | 分类 (自引用 parent_id) | → knowledge_items |
|
||
| `knowledge_items` | 知识条目 | FK → categories, accounts |
|
||
| `knowledge_chunks` | 向量分块 (pgvector) | FK → knowledge_items |
|
||
| `knowledge_versions` | 版本历史 | FK → items, chunks, accounts |
|
||
| `knowledge_usage` | 使用统计 | FK → knowledge_items |
|
||
| `structured_sources` | 结构化数据源 | FK → accounts |
|
||
| `structured_rows` | 结构化行数据 | FK → structured_sources |
|
||
|
||
#### 其他域 (19 表)
|
||
|
||
| 域 | 表 | 说明 |
|
||
|----|----|------|
|
||
| API & Relay | `account_api_keys`, `usage_records`, `relay_tasks` | API Key/用量/异步任务 |
|
||
| 配置 | `config_items`, `config_sync_log` | KV 配置/同步日志 |
|
||
| Prompt | `prompt_templates`, `prompt_versions`, `prompt_sync_status` | 模板/版本/同步 |
|
||
| Agent | `agent_templates` | Agent 模板配置 |
|
||
| 设备 | `devices` | 设备管理 |
|
||
| 遥测 | `operation_logs`, `telemetry_reports`, `saas_schema_version` | 操作日志/统计/版本 |
|
||
| 调度 | `scheduled_tasks` | 定时任务 |
|
||
| 限流 | `rate_limit_events` | 限流事件日志 |
|
||
| Webhook | `webhook_subscriptions`, `webhook_deliveries` | Webhook 订阅/投递 |
|
||
| 行业 | `industries`, `account_industries` | 行业配置/账户关联 |
|
||
|
||
### SQLite 本地存储
|
||
|
||
**zclaw-memory** (`crates/zclaw-memory/src/schema.rs`):
|
||
|
||
| 表 | 说明 | 版本 |
|
||
|----|------|------|
|
||
| `agents` | Agent 定义 | v1 |
|
||
| `sessions` | 聊天会话 | v1, FK → agents |
|
||
| `messages` | 会话消息 | v1, FK → sessions |
|
||
| `kv_store` | Agent KV 存储 | v1, FK → agents |
|
||
| `facts` | 提取的事实 | v2, FK → agents |
|
||
| `user_profiles` | 用户画像 | v2 |
|
||
| `trajectory_events` | 工具调用链事件 | v3 |
|
||
| `compressed_trajectories` | 压缩轨迹摘要 | v3 |
|
||
| `hand_runs` | Hand 执行追踪 | v1 |
|
||
| `schema_version` | 迁移版本 | v1 |
|
||
|
||
**zclaw-growth** (`crates/zclaw-growth/src/storage/sqlite.rs`):
|
||
|
||
| 表 | 说明 |
|
||
|----|------|
|
||
| `memories` | 记忆条目 (uri, memory_type, content, keywords, importance, access_count) |
|
||
| `metadata` | KV 元数据 |
|
||
|
||
**FTS5 虚拟表**:
|
||
|
||
| 虚拟表 | 定义 | 分词器 |
|
||
|--------|------|--------|
|
||
| `memories_fts` | `fts5(uri, content, keywords)` | `trigram` (CJK 支持) |
|
||
|
||
> FTS5 使用 `trigram` 分词器（从 `unicode61` 迁移）支持中文/日文/韩文。CJK 查询零结果时 fallback 到 LIKE 搜索。
|
||
|
||
## 数据流
|
||
|
||
```
|
||
桌面端聊天
|
||
→ SQLite: sessions + messages (本地持久化)
|
||
→ SaaS Relay: relay_tasks (异步任务追踪)
|
||
→ PostgreSQL: usage_records (用量记录)
|
||
|
||
记忆管道
|
||
→ SQLite: memories + memories_fts (FTS5 全文索引)
|
||
→ SQLite: facts + user_profiles (结构化提取)
|
||
→ PostgreSQL: knowledge_chunks (pgvector 向量, embedding deferred)
|
||
|
||
计费闭环
|
||
→ PostgreSQL: billing_usage_quotas (实时递增)
|
||
→ PostgreSQL: billing_subscriptions → invoices → payments
|
||
→ Worker: aggregate_usage (聚合器调度)
|
||
```
|
||
|
||
## 测试链路
|
||
|
||
| 功能 | 测试文件 | 覆盖状态 |
|
||
|------|---------|---------|
|
||
| 全模块 | `crates/zclaw-saas/tests/` (17 文件) | ✅ |
|
||
| SQL 迁移 | `crates/zclaw-saas/migrations/` (21 up) | ✅ 启动时自动执行 |
|
||
| 本地存储 | `crates/zclaw-memory/src/store.rs` (20 tests) | ✅ |
|
||
| 用户画像 | `crates/zclaw-memory/src/user_profile_store.rs` (20 tests) | ✅ |
|
||
| 轨迹存储 | `crates/zclaw-memory/src/trajectory_store.rs` (9 tests) | ✅ |
|
||
| 记忆存储 | `crates/zclaw-growth/src/storage/sqlite.rs` (6 tests) | ✅ |
|
||
|
||
## 关联模块
|
||
|
||
- [[saas]] — PostgreSQL 由 SaaS 后端管理
|
||
- [[memory]] — SQLite 本地记忆存储 + FTS5
|
||
- [[routing]] — relay_tasks 异步任务追踪
|
||
|
||
## 关键文件
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `crates/zclaw-saas/migrations/` | 21 up SQL 迁移 (42 CREATE TABLE) |
|
||
| `crates/zclaw-saas/src/models/` | 数据模型 struct 定义 |
|
||
| `crates/zclaw-memory/src/schema.rs` | SQLite schema 定义 |
|
||
| `crates/zclaw-growth/src/storage/sqlite.rs` | FTS5 + TF-IDF 存储 |
|
||
| `docker-compose.yml` | PostgreSQL 容器配置 |
|
||
|
||
## 已知问题
|
||
|
||
- ⚠️ **pgvector embedding 生成未实现** — 索引就绪，`generate_embedding.rs` Worker 逻辑 deferred
|
||
- ⚠️ **FTS5 CJK 零结果** — trigram 分词器已启用，极短查询可能仍 fallback 到 LIKE
|