audio_codebuddy/.qoder/repowiki/zh/content/数据库设计/用户数据模型/用户数据模型.md

用户数据模型

本文档引用的文件

• schema.prisma
• auth.controller.ts
• auth.service.ts
• preferences.controller.ts
• preferences.service.ts
• user.ts
• index.ts
• index.ts

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构概览
5. 详细组件分析
6. 依赖关系分析
7. 性能考虑
8. 故障排除指南
9. 结论

简介

本文件为AI有声书生成平台的用户数据模型详细文档。重点解释User模型的字段定义、数据类型和约束条件，包括手机号、OpenID、昵称、头像等基本信息字段；详细说明会员等级、过期时间、使用统计等会员相关字段的作用和业务含义；解释用户偏好设置模型UserPreference的配置项，包括播放速度、音质、主题、默认音色等个性化设置；并提供用户数据的CRUD操作示例，包括用户注册、登录验证、信息更新等常见场景的实现方法。

项目结构

用户数据模型主要分布在以下位置：

• 数据库模型定义：server/prisma/schema.prisma
• 用户认证模块：server/src/modules/auth/
• 用户偏好设置模块：server/src/modules/preferences/
• 前端用户状态管理：my-uniapp-vue3/src/store/user.ts
• 类型定义：server/src/types/index.ts

• 数据库连接：server/src/models/index.ts

  graph TB
  subgraph "前端应用"
  UI[用户界面]
  Store[Pinia用户状态]
  end
  subgraph "后端服务"
  AuthCtrl[认证控制器]
  AuthSvc[认证服务]
  PrefCtrl[偏好控制器]
  PrefSvc[偏好服务]
  DB[(MySQL数据库)]
  end
  UI --> Store
  Store --> AuthCtrl
  Store --> PrefCtrl
  AuthCtrl --> AuthSvc
  PrefCtrl --> PrefSvc
  AuthSvc --> DB
  PrefSvc --> DB
  

图表来源

• auth.controller.ts:1-94
• preferences.controller.ts:1-50
• user.ts:1-107

章节来源

• schema.prisma:10-38
• auth.controller.ts:1-94
• preferences.controller.ts:1-50

核心组件

User模型字段定义

User模型是用户数据的核心实体，包含以下关键字段：

基本信息字段

• id: 整数类型，自增主键
• phone: 字符串类型，唯一索引，支持空值
• openid: 字符串类型，唯一索引，支持空值
• nickname: 字符串类型，默认值"用户"
• avatar: 字符串类型，默认值空字符串

会员相关字段

• memberLevel: 整数类型，默认值0，表示会员等级
• memberExpireAt: 日期时间类型，会员到期时间
• dailyUsage: 整数类型，默认值0，每日使用次数统计
• lastUsageDate: 字符串类型，默认值空字符串，最后使用日期

使用统计字段

• usedAudioMinutes: 整数类型，默认值0，累计使用的音频分钟数
• subscriptionResetDate: 日期时间类型，订阅重置日期

时间戳字段

• createdAt: 日期时间类型，默认当前时间
• updatedAt: 日期时间类型，自动更新

关系字段

• comments: 评论关联
• drafts: 草稿关联
  
• favorites: 收藏关联
• orders: 订单关联
• playRecords: 播放记录关联
• playlists: 播放列表关联
• signRecords: 签到记录关联
• subscriptions: 订阅关联
• tokenBalance: 令牌余额关联
• tokenUsages: 令牌使用记录关联
• preferences: 用户偏好设置关联

索引配置

• 对phone字段建立索引
• 对openid字段建立索引

章节来源

• schema.prisma:10-38

UserPreference模型字段定义

UserPreference模型用于存储用户的个性化偏好设置：

播放设置

• playSpeed: 浮点数类型，默认值1.0，播放速度
• autoPlayNext: 布尔类型，默认值true，自动播放下一章
• wifiOnlyDownload: 布尔类型，默认值false，仅WiFi下载

音质和主题

• quality: 字符串类型，默认值"standard"，音质设置
• theme: 字符串类型，默认值"light"，界面主题

音色和音量

• defaultVoiceId: 字符串类型，可空，默认值"cherry"，默认音色ID
• defaultVolume: 整数类型，默认值50，默认音量

关系字段

• userId: 整数类型，唯一索引，关联User模型
• user: User模型关联

章节来源

• schema.prisma:79-92

架构概览

用户数据模型采用分层架构设计，确保数据的一致性和完整性：

classDiagram
class User {
+int id
+string phone
+string openid
+string nickname
+string avatar
+int memberLevel
+datetime memberExpireAt
+int dailyUsage
+string lastUsageDate
+int usedAudioMinutes
+datetime subscriptionResetDate
+datetime createdAt
+datetime updatedAt
}
class UserPreference {
+int id
+int userId
+float playSpeed
+string quality
+string theme
+string defaultVoiceId
+int defaultVolume
+boolean autoPlayNext
+boolean wifiOnlyDownload
+datetime createdAt
+datetime updatedAt
}
class AuthController {
+sendCode()
+login()
+getUserInfo()
+updateUserInfo()
}
class PreferenceController {
+getPreferences()
+updatePreferences()
}
class AuthService {
+generateSmsCode()
+verifySmsCode()
+generateToken()
+loginWithPhone()
+getUserInfo()
}
class PreferenceService {
+getPreferences()
+updatePreferences()
}
UserPreference --> User : "belongsTo"
AuthController --> AuthService : "uses"
PreferenceController --> PreferenceService : "uses"
AuthService --> User : "manages"
PreferenceService --> UserPreference : "manages"

图表来源

• schema.prisma:10-92
• auth.controller.ts:1-94
• preferences.controller.ts:1-50

详细组件分析

用户认证流程

用户认证流程涉及手机号登录和验证码验证机制：

sequenceDiagram
participant Client as 客户端
participant AuthCtrl as 认证控制器
participant AuthSvc as 认证服务
participant DB as 数据库
Client->>AuthCtrl : POST /auth/login (phone, code)
AuthCtrl->>AuthSvc : loginWithPhone(phone, code)
AuthSvc->>DB : 查询用户 (phone)
DB-->>AuthSvc : 用户信息或null
alt 用户不存在
AuthSvc->>DB : 创建新用户
DB-->>AuthSvc : 新用户ID
end
AuthSvc->>AuthSvc : 生成JWT Token
AuthSvc-->>AuthCtrl : 返回token和用户信息
AuthCtrl-->>Client : 登录成功响应

图表来源

• auth.controller.ts:32-52
• auth.service.ts:44-97

登录验证逻辑

登录验证包含以下步骤：

1. 验证手机号格式（11位数字，以1开头）
2. 验证验证码（开发环境跳过验证）
3. 查找或创建用户记录
4. 生成JWT访问令牌
5. 返回用户信息和登录状态

章节来源

• auth.controller.ts:32-52
• auth.service.ts:44-97

用户偏好设置管理

用户偏好设置采用upsert策略，确保每个用户都有对应的偏好配置：

flowchart TD
Start([获取用户偏好]) --> CheckUser["检查用户ID"]
CheckUser --> FindPref["查询现有偏好设置"]
FindPref --> Exists{"存在偏好设置?"}
Exists --> |是| ReturnExisting["返回现有设置"]
Exists --> |否| UpsertDefault["upsert默认设置"]
UpsertDefault --> CreateDefault["创建默认偏好设置"]
CreateDefault --> ReturnCreated["返回新建设置"]
ReturnExisting --> End([结束])
ReturnCreated --> End

图表来源

• preferences.service.ts:8-28

偏好设置初始化

当用户首次访问时，系统会自动创建默认偏好设置：

• 播放速度：1.0倍速
• 音质：standard标准质量
• 主题：light浅色主题
• 默认音色：cherry樱桃音色
• 默认音量：50
• 自动播放：启用
• 仅WiFi下载：禁用

章节来源

• preferences.service.ts:8-28

前端用户状态管理

前端使用Pinia进行用户状态管理，提供完整的用户生命周期控制：

stateDiagram-v2
[*] --> 未登录
未登录 --> 发送验证码 : sendCode()
发送验证码 --> 等待验证码 : 等待用户输入
等待验证码 --> 已登录 : login()
已登录 --> 获取用户信息 : fetchUserInfo()
已登录 --> 获取会员状态 : fetchMemberStatus()
已登录 --> 更新用户信息 : updateUserInfo()
已登录 --> 登出 : logout()
登出 --> 未登录 : 清除状态
获取用户信息 --> 已登录 : 更新本地状态
获取会员状态 --> 已登录 : 更新会员信息
更新用户信息 --> 已登录 : 保存到本地存储

图表来源

• user.ts:7-107

章节来源

• user.ts:7-107

依赖关系分析

用户数据模型的依赖关系体现了清晰的分层设计：

graph LR
subgraph "数据层"
Schema[schema.prisma]
Prisma[Prisma Client]
end
subgraph "服务层"
AuthSvc[AuthService]
PrefSvc[PreferenceService]
Models[Models Index]
end
subgraph "控制器层"
AuthCtrl[AuthController]
PrefCtrl[PreferenceController]
end
subgraph "类型定义"
Types[Index Types]
end
subgraph "前端状态"
UserStore[User Store]
end
Schema --> Prisma
Prisma --> AuthSvc
Prisma --> PrefSvc
AuthCtrl --> AuthSvc
PrefCtrl --> PrefSvc
AuthSvc --> Models
PrefSvc --> Models
AuthCtrl --> Types
PrefCtrl --> Types
UserStore --> AuthCtrl
UserStore --> PrefCtrl

图表来源

• schema.prisma:1-8
• auth.service.ts:1-5
• preferences.service.ts:1-3
• index.ts:1-3

数据库连接管理

数据库连接通过Prisma Client统一管理，确保连接池的有效利用和错误处理：

章节来源

• index.ts:1-15

性能考虑

索引优化策略

User模型建立了关键字段的索引以提升查询性能：

• phone字段索引：支持手机号快速查找
• openid字段索引：支持第三方登录快速匹配
• 复合索引：订单表按用户ID和创建时间建立索引

缓存策略

前端采用本地存储缓存用户状态：

• Token持久化存储
• 用户信息本地缓存
• 偏好设置同步存储

异步处理

• 验证码存储使用内存Map（生产环境建议Redis）
• JWT令牌生成异步处理
• 用户偏好设置upsert操作

故障排除指南

常见问题及解决方案

用户登录失败

症状：手机号登录时报错 原因：

• 手机号格式不正确
• 验证码验证失败
• 数据库连接异常

解决方法：

1. 检查手机号格式验证规则
2. 确认验证码存储和过期机制
3. 验证数据库连接状态

偏好设置获取异常

症状：用户偏好设置无法加载 原因：

• 用户ID为空或无效
• 数据库连接问题
• 权限验证失败

解决方法：

1. 确认用户认证状态
2. 检查数据库连接日志
3. 验证用户偏好设置表结构

前端状态同步问题

症状：用户状态不同步 原因：

• 本地存储损坏
• 网络请求失败
• Token过期

解决方法：

1. 清理本地存储数据
2. 检查网络连接状态
3. 重新登录获取新Token

章节来源

• auth.controller.ts:14-16
• preferences.controller.ts:13-24
• user.ts:18-30

结论

AI有声书生成平台的用户数据模型设计合理，具有以下特点：

1. 完整性：涵盖用户基本信息、会员状态、使用统计和个性化偏好
2. 扩展性：支持多种登录方式（手机号、OpenID）和第三方集成
3. 一致性：通过Prisma ORM确保数据一致性和关系完整性
4. 性能：合理的索引设计和缓存策略提升系统性能
5. 安全性：JWT令牌机制保障用户身份安全

该模型为平台的用户管理提供了坚实的数据基础，支持从基础用户注册到高级个性化设置的完整功能需求。通过清晰的分层架构和完善的错误处理机制，确保了系统的稳定性和可维护性。