# 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  
**维护者**: 开发团队