# 数据库索引与关系

<cite>
**本文档引用的文件**
- [schema.prisma](file://server/prisma/schema.prisma)
- [database-structure.md](file://docs/database-structure.md)
- [migration.sql](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql)
- [index.ts](file://server/src/models/index.ts)
- [performance.ts](file://server/src/middleware/performance.ts)
- [cache.ts](file://server/src/middleware/cache.ts)
- [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts)
- [book-generator.service.ts](file://server/src/modules/book-generator/book-generator.service.ts)
</cite>

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

## 简介

本文件为AI有声书生成平台的数据库索引与关系详细文档。项目采用Prisma ORM + MySQL数据库架构，专注于有声书生成流程中的数据建模与索引优化。文档深入解释了唯一索引、复合索引、外键约束等在不同场景下的应用，并详细说明实体间的一对一、一对多、多对多关系映射及关系完整性保证机制。同时提供了查询性能优化策略、索引选择原则、查询计划分析以及数据库设计最佳实践。

## 项目结构

该项目采用前后端分离架构，数据库层通过Prisma ORM进行抽象，主要涉及以下关键文件：

```mermaid
graph TB
subgraph "数据库层"
PRISMA[schema.prisma]
MIGRATION[migration.sql]
end
subgraph "业务层"
STORE[book-generator.store.ts]
SERVICE[book-generator.service.ts]
end
subgraph "中间件层"
PERF[performance.ts]
CACHE[cache.ts]
end
subgraph "文档层"
DOCS[database-structure.md]
end
PRISMA --> STORE
STORE --> SERVICE
PERF --> STORE
CACHE --> STORE
DOCS --> PRISMA
MIGRATION --> PRISMA
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)
- [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts)
- [performance.ts](file://server/src/middleware/performance.ts)
- [cache.ts](file://server/src/middleware/cache.ts)
- [database-structure.md](file://docs/database-structure.md)
- [migration.sql](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)
- [database-structure.md](file://docs/database-structure.md)

## 核心组件

### 数据库模型概览

项目采用Prisma Schema定义数据库模型，包含用户、订单、播放记录、收藏、评论、书籍、章节、视频项目等多个核心实体。每个实体都配备了相应的索引策略以优化查询性能。

### 关键实体关系

```mermaid
erDiagram
USER ||--o{ ORDER : "创建"
USER ||--o{ FAVORITE : "收藏"
USER ||--o{ COMMENT : "评论"
USER ||--o{ PLAY_RECORD : "播放记录"
USER ||--o{ DRAFT : "草稿"
USER ||--o{ PLAYLIST : "播放列表"
USER ||--o{ SIGN_RECORD : "签到"
USER ||--o{ SUBSCRIPTION : "订阅"
USER ||--o{ TOKEN_USAGE : "令牌使用"
USER ||--o{ AUDIO_RECORD : "音频记录"
USER ||--o{ PLATFORM_ACCOUNT : "平台账号"
USER ||--o{ VIDEO_MATERIAL : "视频素材"
BOOK ||--o{ BOOK_CHAPTER : "包含"
BOOK ||--o{ FAVORITE : "被收藏"
BOOK ||--o{ VIDEO_PROJECT : "视频项目"
BOOK_CHAPTER ||--o{ COMMENT : "被评论"
BOOK_CHAPTER ||--o{ PLAY_RECORD : "播放记录"
BOOK_CHAPTER ||--o{ PLAYLIST_ITEM : "播放列表项"
BOOK_CHAPTER ||--o{ VIDEO_PROJECT : "视频项目"
SUBSCRIPTION_PLAN ||--o{ SUBSCRIPTION : "提供"
SUBSCRIPTION ||--o{ ORDER : "购买"
PLAYLIST ||--o{ PLAYLIST_ITEM : "包含"
PLAYLIST_ITEM ||--|| BOOK_CHAPTER : "关联章节"
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)

## 架构概览

### 数据库索引策略

项目采用了多层次的索引策略来确保查询性能：

#### 唯一索引
- 用户手机号和OpenID唯一性约束
- 订单号唯一性约束
- 用户偏好唯一性约束
- 收藏组合唯一性约束
- 章节组合唯一性约束
- 平台账号组合唯一性约束
- 音频记录ID唯一性约束
- 令牌余额用户唯一性约束

#### 复合索引
- 用户ID+创建时间（订单、搜索历史、播放记录等）
- 用户ID+状态（书籍、订阅、视频项目等）
- 书籍ID+父ID（章节层级查询）
- 书籍ID+层级（章节结构查询）
- 播放列表ID+排序（播放列表项）

#### 外键约束
- 所有关系均设置适当的外键约束
- 支持级联删除和RESTRICT操作
- 确保数据一致性

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)
- [migration.sql](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql)

## 详细组件分析

### 用户管理系统

#### 用户表索引设计

```mermaid
classDiagram
class User {
+Int id
+String phone
+String openid
+String nickname
+String avatar
+Int memberLevel
+DateTime memberExpireAt
+Int dailyUsage
+String lastUsageDate
+DateTime createdAt
+DateTime updatedAt
+Int usedAudioMinutes
+DateTime subscriptionResetDate
@@index(phone)
@@index(openid)
@@unique(phone)
@@unique(openid)
}
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

#### 用户偏好管理

用户偏好表采用一对一关系，通过用户ID建立唯一关联：

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Store as "BookStore"
participant DB as "数据库"
Client->>Store : 获取用户偏好
Store->>DB : SELECT * FROM UserPreference WHERE userId = ?
DB-->>Store : 用户偏好记录
Store-->>Client : 返回偏好设置
Note over Client,DB : 确保每个用户只有一个偏好配置
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)

### 书籍与章节管理

#### 书籍章节层级结构

项目实现了三级目录结构（章→节→小节），通过组合唯一索引确保每本书的层级唯一性：

```mermaid
flowchart TD
Start([开始]) --> CheckBook["检查书籍ID"]
CheckBook --> GetChapters["查询所有章节"]
GetChapters --> SortChapters["按层级和序号排序"]
SortChapters --> BuildTree["构建树形结构"]
BuildTree --> Level1{"层级=1?"}
Level1 --> |是| ProcessChapter["处理章节"]
Level1 --> |否| Level2{"层级=2?"}
Level2 --> |是| ProcessSection["处理节"]
Level2 --> |否| Level3["处理小节"]
ProcessChapter --> AddToTree["添加到树"]
ProcessSection --> AddToTree
Level3 --> AddToTree
AddToTree --> NextChapter{"还有章节?"}
NextChapter --> |是| SortChapters
NextChapter --> |否| ReturnTree["返回完整树"]
```

**图表来源**
- [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts)

#### 章节内容管理

章节表支持复杂的内容管理，包括大纲、摘要、关键知识点等：

```mermaid
classDiagram
class BookChapter {
+Int id
+Int bookId
+Int parentId
+Int level
+Int number
+String title
+String summary
+String keyPoints
+Int estimatedWords
+String content
+Int wordCount
+String contentError
+DateTime generatedAt
+String audioUrl
+Int audioDuration
+String videoUrl
+Int videoDuration
+Boolean isPublic
+String genStage
+String status
@@unique(bookId, parentId, level, number)
@@index(bookId)
@@index(bookId, parentId)
@@index(bookId, level)
}
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)
- [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts)

### 订单与订阅系统

#### 订单查询优化

订单系统采用复合索引优化常见查询场景：

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Service as "BookGeneratorService"
participant Store as "BookStore"
participant DB as "数据库"
Client->>Service : 获取用户书籍列表
Service->>Store : getAllByUser(userId)
Store->>DB : SELECT * FROM Book
WHERE userId = ? OR userId IS NULL
ORDER BY updatedAt DESC, id DESC
DB-->>Store : 书籍列表
Store-->>Service : 返回结果
Service-->>Client : 书籍数据
Note over Client,DB : 利用复合索引优化排序和过滤
```

**图表来源**
- [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts)

#### 订阅计划管理

订阅计划表支持复杂的查询和排序需求：

```mermaid
classDiagram
class SubscriptionPlan {
+Int id
+String name
+Int level
+Decimal priceMonthly
+Decimal priceYearly
+String description
+String features
+Boolean isRecommended
+Boolean isActive
+Int sortOrder
+Int dailyGenerations
+Int perGenerationLimit
+Int monthlyTokens
+Int monthlyMinutes
+Int yearlyTokens
+Int voiceOptions
+String audioQuality
+Boolean apiAccess
+Boolean batchProcessing
+Boolean teamManagement
+Boolean overageEnabled
+Decimal overagePrice
+DateTime createdAt
+DateTime updatedAt
@@index(level)
@@index(isActive, sortOrder)
}
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)
- [book-generator.store.ts](file://server/src/modules/book-generator/book-generator.store.ts)

### 播放记录与收藏系统

#### 播放记录优化

播放记录表采用复合唯一索引确保用户对章节的播放记录唯一性：

```mermaid
classDiagram
class PlayRecord {
+Int id
+Int userId
+Int chapterId
+Float progress
+Float duration
+DateTime updatedAt
+DateTime createdAt
@@unique(userId, chapterId)
@@index(userId)
@@index(chapterId)
}
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

#### 收藏管理

收藏表支持用户对书籍的收藏功能，采用组合唯一索引防止重复收藏：

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "收藏API"
participant Store as "BookStore"
participant DB as "数据库"
Client->>API : 添加收藏
API->>Store : createFavorite(userId, bookId)
Store->>DB : INSERT INTO Favorite (userId, bookId)
DB-->>Store : 插入成功
Store-->>API : 返回收藏结果
API-->>Client : 收藏成功
Note over Client,DB : 利用唯一索引防止重复收藏
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)

## 依赖分析

### 数据库连接管理

项目通过Prisma Client管理数据库连接，确保连接池的有效利用：

```mermaid
graph LR
APP[应用服务器] --> PRISMA[Prisma Client]
PRISMA --> MYSQL[MySQL数据库]
subgraph "连接管理"
CONNECT[连接建立]
POOL[连接池]
DISCONNECT[连接释放]
end
APP --> CONNECT
CONNECT --> POOL
POOL --> MYSQL
MYSQL --> DISCONNECT
DISCONNECT --> POOL
```

**图表来源**
- [index.ts](file://server/src/models/index.ts)

### 查询性能监控

系统集成了性能监控中间件，用于跟踪API响应时间和慢查询：

```mermaid
flowchart TD
Request[HTTP请求] --> Monitor[性能监控中间件]
Monitor --> Next[下一个中间件]
Next --> Handler[业务处理器]
Handler --> Response[响应返回]
Monitor --> Metrics[收集指标]
Metrics --> SlowCheck{慢请求?}
SlowCheck --> |是| Log[记录慢查询]
SlowCheck --> |否| Header[设置响应头]
Log --> Header
Header --> End[完成]
```

**图表来源**
- [performance.ts](file://server/src/middleware/performance.ts)

**章节来源**
- [index.ts](file://server/src/models/index.ts)
- [performance.ts](file://server/src/middleware/performance.ts)

## 性能考虑

### 索引选择原则

基于项目实际使用场景，推荐以下索引选择策略：

#### 高频查询场景
1. **用户相关查询**：`userId` 单列索引
2. **状态过滤查询**：`(userId, status)` 复合索引
3. **时间排序查询**：`(userId, createdAt)` 复合索引
4. **层级查询**：`(bookId, level)` 复合索引

#### 复杂查询优化
1. **树形结构查询**：`(bookId, parentId)` 复合索引
2. **唯一性约束**：组合唯一索引确保数据完整性
3. **全文搜索**：考虑使用MySQL全文索引（如需）

### 查询计划分析

```mermaid
flowchart TD
Query[SQL查询] --> Explain[EXPLAIN分析]
Explain --> Key[索引使用情况]
Explain --> Rows[扫描行数]
Explain --> Extra[额外信息]
Key --> Optimize{需要优化?}
Rows --> Optimize
Extra --> Optimize
Optimize --> |是| AddIndex[添加索引]
Optimize --> |否| Monitor[监控性能]
AddIndex --> Test[测试查询]
Test --> Optimize
```

### 缓存策略

系统实现了多层次缓存机制：

```mermaid
graph TB
subgraph "缓存层次"
REDIS[Redis缓存]
MEMORY[内存缓存]
DATABASE[数据库缓存]
end
subgraph "缓存策略"
TTL[TTL控制]
INVALID[失效策略]
LOAD[加载策略]
end
REDIS --> TTL
MEMORY --> INVALID
DATABASE --> LOAD
```

**图表来源**
- [cache.ts](file://server/src/middleware/cache.ts)

**章节来源**
- [performance.ts](file://server/src/middleware/performance.ts)
- [cache.ts](file://server/src/middleware/cache.ts)

## 故障排除指南

### 常见索引问题

1. **索引未生效**
   - 检查查询条件是否使用了索引列
   - 确认数据类型匹配
   - 验证索引统计信息

2. **索引碎片化**
   - 定期重建索引
   - 监控索引使用率
   - 优化插入/更新频率

3. **查询性能下降**
   - 分析查询执行计划
   - 检查索引选择性
   - 考虑查询重写

### 数据一致性检查

```mermaid
flowchart TD
Start[开始检查] --> CheckFK[检查外键约束]
CheckFK --> CheckUnique[检查唯一约束]
CheckUnique --> CheckIndex[检查索引完整性]
CheckIndex --> CheckData[检查数据一致性]
CheckData --> Issues{发现问题?}
Issues --> |是| Fix[修复问题]
Issues --> |否| Complete[检查完成]
Fix --> Verify[验证修复]
Verify --> CheckFK
```

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)
- [migration.sql](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql)

## 结论

本项目的数据库设计充分考虑了AI有声书生成平台的业务特点，通过合理的索引策略、外键约束和关系设计，确保了数据的完整性、一致性和查询性能。主要优势包括：

1. **多层次索引策略**：针对不同查询场景优化索引设计
2. **清晰的关系映射**：通过外键约束确保数据一致性
3. **性能监控机制**：实时监控查询性能和慢查询
4. **缓存优化**：多层次缓存提升系统响应速度
5. **扩展性强**：支持未来业务增长和功能扩展

建议在生产环境中持续监控索引使用情况，定期分析查询性能，并根据实际业务需求调整索引策略。