# 用户数据模型

<cite>
**本文档引用的文件**
- [schema.prisma](file://server/prisma/schema.prisma)
- [auth.controller.ts](file://server/src/modules/auth/auth.controller.ts)
- [auth.service.ts](file://server/src/modules/auth/auth.service.ts)
- [preferences.controller.ts](file://server/src/modules/preferences/preferences.controller.ts)
- [preferences.service.ts](file://server/src/modules/preferences/preferences.service.ts)
- [user.ts](file://my-uniapp-vue3/src/store/user.ts)
- [index.ts](file://server/src/types/index.ts)
- [index.ts](file://server/src/models/index.ts)
</cite>

## 目录
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

```mermaid
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](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [preferences.controller.ts:1-50](file://server/src/modules/preferences/preferences.controller.ts#L1-L50)
- [user.ts:1-107](file://my-uniapp-vue3/src/store/user.ts#L1-L107)

**章节来源**
- [schema.prisma:10-38](file://server/prisma/schema.prisma#L10-L38)
- [auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [preferences.controller.ts:1-50](file://server/src/modules/preferences/preferences.controller.ts#L1-L50)

## 核心组件

### 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](file://server/prisma/schema.prisma#L10-L38)

### 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](file://server/prisma/schema.prisma#L79-L92)

## 架构概览

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

```mermaid
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](file://server/prisma/schema.prisma#L10-L92)
- [auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [preferences.controller.ts:1-50](file://server/src/modules/preferences/preferences.controller.ts#L1-L50)

## 详细组件分析

### 用户认证流程

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

```mermaid
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](file://server/src/modules/auth/auth.controller.ts#L32-L52)
- [auth.service.ts:44-97](file://server/src/modules/auth/auth.service.ts#L44-L97)

#### 登录验证逻辑

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

**章节来源**
- [auth.controller.ts:32-52](file://server/src/modules/auth/auth.controller.ts#L32-L52)
- [auth.service.ts:44-97](file://server/src/modules/auth/auth.service.ts#L44-L97)

### 用户偏好设置管理

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

```mermaid
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](file://server/src/modules/preferences/preferences.service.ts#L8-L28)

#### 偏好设置初始化

当用户首次访问时，系统会自动创建默认偏好设置：
- 播放速度：1.0倍速
- 音质：standard标准质量
- 主题：light浅色主题
- 默认音色：cherry樱桃音色
- 默认音量：50
- 自动播放：启用
- 仅WiFi下载：禁用

**章节来源**
- [preferences.service.ts:8-28](file://server/src/modules/preferences/preferences.service.ts#L8-L28)

### 前端用户状态管理

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

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

**图表来源**
- [user.ts:7-107](file://my-uniapp-vue3/src/store/user.ts#L7-L107)

**章节来源**
- [user.ts:7-107](file://my-uniapp-vue3/src/store/user.ts#L7-L107)

## 依赖关系分析

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

```mermaid
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](file://server/prisma/schema.prisma#L1-L8)
- [auth.service.ts:1-5](file://server/src/modules/auth/auth.service.ts#L1-L5)
- [preferences.service.ts:1-3](file://server/src/modules/preferences/preferences.service.ts#L1-L3)
- [index.ts:1-3](file://server/src/models/index.ts#L1-L3)

### 数据库连接管理

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

**章节来源**
- [index.ts:1-15](file://server/src/models/index.ts#L1-L15)

## 性能考虑

### 索引优化策略

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](file://server/src/modules/auth/auth.controller.ts#L14-L16)
- [preferences.controller.ts:13-24](file://server/src/modules/preferences/preferences.controller.ts#L13-L24)
- [user.ts:18-30](file://my-uniapp-vue3/src/store/user.ts#L18-L30)

## 结论

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

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

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