214 lines
6.3 KiB
Markdown
214 lines
6.3 KiB
Markdown
# App 前台应用数据模型
|
||
|
||
## 📋 模型列表
|
||
|
||
本目录包含所有前台用户应用相关的数据模型，与管理后台的 `system` 模块完全独立。
|
||
|
||
### 1. 用户相关模型
|
||
|
||
| 文件 | 模型 | 表名 | 说明 |
|
||
|------|------|------|------|
|
||
| `app_user.go` | `AppUser` | `app_users` | 前台用户表 |
|
||
| `app_user_session.go` | `AppUserSession` | `app_user_sessions` | 用户会话表 |
|
||
|
||
### 2. AI 角色相关模型
|
||
|
||
| 文件 | 模型 | 表名 | 说明 |
|
||
|------|------|------|------|
|
||
| `ai_character.go` | `AICharacter` | `ai_characters` | AI 角色表 |
|
||
| `ai_character.go` | `AppUserFavoriteCharacter` | `app_user_favorite_characters` | 用户收藏角色表 |
|
||
|
||
### 3. 对话相关模型
|
||
|
||
| 文件 | 模型 | 表名 | 说明 |
|
||
|------|------|------|------|
|
||
| `ai_chat.go` | `AIChat` | `ai_chats` | 对话表 |
|
||
| `ai_chat.go` | `AIChatMember` | `ai_chat_members` | 群聊成员表 |
|
||
| `ai_message.go` | `AIMessage` | `ai_messages` | 消息表 |
|
||
| `ai_message.go` | `AIMessageSwipe` | `ai_message_swipes` | 消息变体表 |
|
||
|
||
### 4. 向量记忆模型
|
||
|
||
| 文件 | 模型 | 表名 | 说明 |
|
||
|------|------|------|------|
|
||
| `ai_memory.go` | `AIMemoryVector` | `ai_memory_vectors` | 向量记忆表（使用 pgvector） |
|
||
|
||
### 5. AI 服务配置模型
|
||
|
||
| 文件 | 模型 | 表名 | 说明 |
|
||
|------|------|------|------|
|
||
| `ai_provider.go` | `AIProvider` | `ai_providers` | AI 提供商配置表 |
|
||
| `ai_provider.go` | `AIModel` | `ai_models` | AI 模型配置表 |
|
||
|
||
### 6. 文件管理模型
|
||
|
||
| 文件 | 模型 | 表名 | 说明 |
|
||
|------|------|------|------|
|
||
| `ai_file.go` | `AIFile` | `ai_files` | 文件表 |
|
||
|
||
### 7. 其他模型
|
||
|
||
| 文件 | 模型 | 表名 | 说明 |
|
||
|------|------|------|------|
|
||
| `ai_preset.go` | `AIPreset` | `ai_presets` | 对话预设表 |
|
||
| `ai_world_info.go` | `AIWorldInfo` | `ai_world_info` | 世界书表 |
|
||
| `ai_usage_stat.go` | `AIUsageStat` | `ai_usage_stats` | 使用统计表 |
|
||
|
||
## 🔧 使用说明
|
||
|
||
### 1. 数据库自动迁移
|
||
|
||
所有模型已在 `initialize/gorm.go` 中注册，启动服务时会自动创建表：
|
||
|
||
```go
|
||
// 在 RegisterTables() 函数中已注册
|
||
app.AppUser{},
|
||
app.AppUserSession{},
|
||
app.AICharacter{},
|
||
app.AppUserFavoriteCharacter{},
|
||
app.AIChat{},
|
||
app.AIChatMember{},
|
||
app.AIMessage{},
|
||
app.AIMessageSwipe{},
|
||
app.AIMemoryVector{},
|
||
app.AIProvider{},
|
||
app.AIModel{},
|
||
app.AIFile{},
|
||
app.AIPreset{},
|
||
app.AIWorldInfo{},
|
||
app.AIUsageStat{},
|
||
```
|
||
|
||
### 2. PostgreSQL 向量扩展
|
||
|
||
向量记忆功能依赖 `pgvector` 扩展，已在 `initialize/gorm_pgsql_extension.go` 中自动安装：
|
||
|
||
```sql
|
||
CREATE EXTENSION IF NOT EXISTS vector;
|
||
CREATE INDEX idx_memory_vectors_embedding ON ai_memory_vectors
|
||
USING hnsw (embedding vector_cosine_ops);
|
||
```
|
||
|
||
### 3. 外键关系
|
||
|
||
模型之间的关系已通过 GORM 标签定义：
|
||
|
||
- `AppUser` ← `AppUserSession`（一对多）
|
||
- `AppUser` ← `AICharacter`（一对多，创建者）
|
||
- `AppUser` ← `AIChat`（一对多）
|
||
- `AppUser` ← `AppUserFavoriteCharacter`（多对多，通过中间表）
|
||
- `AICharacter` ← `AppUserFavoriteCharacter`（多对多，通过中间表）
|
||
- `AICharacter` ← `AIChat`（一对多）
|
||
- `AIChat` ← `AIMessage`（一对多）
|
||
- `AIChat` ← `AIChatMember`（多对多，通过中间表）
|
||
- `AICharacter` ← `AIChatMember`（多对多，通过中间表）
|
||
- `AIMessage` ← `AIMessageSwipe`（一对多）
|
||
- `AIProvider` ← `AIModel`（一对多）
|
||
|
||
### 4. JSONB 字段
|
||
|
||
以下字段使用 PostgreSQL 的 JSONB 类型：
|
||
|
||
- `AppUser.AISettings` - AI 相关配置
|
||
- `AppUser.Preferences` - 用户偏好设置
|
||
- `AICharacter.CardData` - 角色卡片数据
|
||
- `AICharacter.Tags` - 角色标签
|
||
- `AICharacter.ExampleMessages` - 消息示例
|
||
- `AIChat.Settings` - 对话设置
|
||
- `AIMessage.GenerationParams` - AI 生成参数
|
||
- `AIMessage.Metadata` - 消息元数据
|
||
- `AIMemoryVector.Metadata` - 记忆元数据
|
||
- `AIProvider.APIConfig` - API 配置
|
||
- `AIModel.Config` - 模型配置
|
||
- `AIFile.RelatedTo` - 文件关联对象
|
||
- `AIFile.Metadata` - 文件元数据
|
||
- `AIPreset.Config` - 预设配置
|
||
- `AIWorldInfo.TriggerConfig` - 触发条件配置
|
||
|
||
### 5. 向量字段
|
||
|
||
`AIMemoryVector.Embedding` 使用 `pgvector.Vector` 类型，维度为 1536（OpenAI text-embedding-ada-002）。
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **不要修改 system 包**：所有管理后台相关的模型在 `model/system/` 包中，**不要修改**
|
||
2. **表名前缀**：
|
||
- 前台用户相关：`app_*`
|
||
- AI 功能相关：`ai_*`
|
||
- 系统管理相关：`sys_*`（不修改）
|
||
3. **UUID 生成**：`AppUser.UUID` 使用数据库自动生成（PostgreSQL 的 `gen_random_uuid()`）
|
||
4. **软删除**：所有模型继承 `global.GVA_MODEL`，自动支持软删除
|
||
5. **时间字段**：`CreatedAt`、`UpdatedAt`、`DeletedAt` 由 GORM 自动管理
|
||
|
||
## 📊 ER 图关系
|
||
|
||
```
|
||
AppUser (前台用户)
|
||
├── AppUserSession (会话)
|
||
├── AICharacter (创建的角色)
|
||
├── AIChat (对话)
|
||
├── AppUserFavoriteCharacter (收藏的角色)
|
||
├── AIMemoryVector (记忆)
|
||
├── AIProvider (AI 提供商配置)
|
||
├── AIFile (文件)
|
||
├── AIPreset (预设)
|
||
├── AIWorldInfo (世界书)
|
||
└── AIUsageStat (使用统计)
|
||
|
||
AICharacter (AI 角色)
|
||
├── AIChat (对话)
|
||
├── AIChatMember (群聊成员)
|
||
├── AppUserFavoriteCharacter (被收藏)
|
||
└── AIMemoryVector (记忆)
|
||
|
||
AIChat (对话)
|
||
├── AIMessage (消息)
|
||
├── AIChatMember (群聊成员)
|
||
└── AIMemoryVector (记忆)
|
||
|
||
AIMessage (消息)
|
||
└── AIMessageSwipe (消息变体)
|
||
|
||
AIProvider (AI 提供商)
|
||
└── AIModel (AI 模型)
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
1. 确保 PostgreSQL 已安装 pgvector 扩展
|
||
2. 配置 `config.yaml` 中的数据库连接
|
||
3. 启动服务，AutoMigrate 会自动创建所有表
|
||
4. 检查日志确认表创建成功
|
||
|
||
```bash
|
||
# 启动服务
|
||
go run main.go
|
||
|
||
# 查看日志
|
||
# [GVA] pgvector extension is ready
|
||
# [GVA] vector indexes created successfully
|
||
# [GVA] register table success
|
||
```
|
||
|
||
## 📝 开发建议
|
||
|
||
1. 查询时使用预加载避免 N+1 问题：
|
||
```go
|
||
db.Preload("User").Preload("Character").Find(&chats)
|
||
```
|
||
|
||
2. 向量搜索示例：
|
||
```go
|
||
db.Order("embedding <=> ?", queryVector).Limit(10).Find(&memories)
|
||
```
|
||
|
||
3. JSONB 查询示例：
|
||
```go
|
||
db.Where("ai_settings->>'model' = ?", "gpt-4").Find(&users)
|
||
```
|
||
|
||
---
|
||
|
||
**创建日期**: 2026-02-10
|
||
**维护者**: 开发团队
|