st/server/model/app/README.md

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 中注册，启动服务时会自动创建表：

// 在 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 中自动安装：

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. 检查日志确认表创建成功

# 启动服务
go run main.go

# 查看日志
# [GVA] pgvector extension is ready
# [GVA] vector indexes created successfully
# [GVA] register table success

📝 开发建议

1. 查询时使用预加载避免 N+1 问题：

   db.Preload("User").Preload("Character").Find(&chats)
   

2. 向量搜索示例：

   db.Order("embedding <=> ?", queryVector).Limit(10).Find(&memories)
   

3. JSONB 查询示例：

   db.Where("ai_settings->>'model' = ?", "gpt-4").Find(&users)
   

---

创建日期: 2026-02-10
维护者: 开发团队