# Drama-Fusion-Platform 核心交互系统分析报告

> 生成时间: 2026-06-27 | 项目: /root/drama-fusion-platform | 微服务架构 (Spring Boot + Vue3/Vite)

---

## 目录

1. [基于时间线的弹幕系统](#1-基于时间线的弹幕系统)
2. [基于时间线的商品卡片系统](#2-基于时间线的商品卡片系统)
3. [基于 OpenIM 的消息和剧群系统](#3-基于-openim-的消息和剧群系统)
4. [讨论区（评论）系统](#4-讨论区评论系统)
5. [系统集成关系与数据流](#5-系统集成关系与数据流)

---

## 1. 基于时间线的弹幕系统

### 1.1 系统概述

弹幕系统实现了**播放器时间轴**与弹幕内容的实时关联，支持**AI自动生成弹幕**和**WebSocket实时广播**。弹幕数据按时间点（`mm:ss` 格式）与分集（episode）绑定，播放器按时间点匹配展示。

### 1.2 微服务分布

| 微服务 | 职责 | 端口 |
|--------|------|------|
| drama-content-service | 弹幕CRUD、分集关联查询 | 8102 |
| drama-ai-service | AI弹幕生成、WebSocket实时推送 | 8105 |

### 1.3 数据库表结构

**t_bullet_commentary（弹幕内容表）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| episode_id | bigint | 分集ID（关联 t_episode） |
| time_point | varchar(32) | 出现时间点（mm:ss） |
| content | text | 弹幕文字内容 |
| type | varchar(32) | 弹幕类型（normal/highlight/ai） |
| author | varchar(64) | 弹幕作者 |
| create_time | datetime | 创建时间 |

**t_bullet_message（弹幕消息表 - AI服务用）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| user_id | bigint | 用户ID |
| drama_id | bigint | 短剧ID |
| time_point | varchar(16) | 出现时间点 |
| content | text | 弹幕文字 |
| type | varchar(32) | 弹幕类型 |
| author | varchar(64) | 作者 |

### 1.4 核心API端点

**content-service (8102)**

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/content/bullets?episodeId=` | 获取某集弹幕列表 |
| POST | `/api/content/bullets` | 添加单条弹幕 |
| DELETE | `/api/content/bullets/{id}` | 删除弹幕 |
| POST | `/api/content/bullets/batch` | 批量导入弹幕(JSON) |
| POST | `/api/content/bullets/import` | 文件导入弹幕(JSON/CSV) |
| GET | `/api/content/dramas/{dramaId}/bullets` | 获取整部剧所有弹幕 |

**ai-service (8105)**

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/ai/bullets?episodeId=&timePoint=` | 获取AI弹幕 |
| POST | `/api/ai/bullet/push?dramaId=` | WebSocket推送弹幕 |
| GET | `/api/ai/bullet/list?dramaId=&timePoint=` | 按时间点获取弹幕列表 |

### 1.5 WebSocket 实时弹幕推送

```
Endpoint: /ws/bullet (STOMP over SockJS)
订阅主题: /topic/bullet/{dramaId}
```

```
用户发送弹幕 → POST /api/ai/bullet/push
  → 持久化到 t_bullet_message
  → messagingTemplate.convertAndSend("/topic/bullet/" + dramaId, payload)
  → 所有订阅该剧的用户实时接收弹幕
```

### 1.6 前端管理页面

- **弹幕管理**: `drama-frontend-admin/src/pages/dramas/Bullets.vue`
  - 按分集和类型筛选
  - 单条添加 / 批量导入 / 删除
  - 时间点格式: `mm:ss`

- **弹幕关联(复用)**: `drama-frontend-admin/src/pages/dramas/Relations.vue`
  - Tab: 弹幕关联 / 商品卡片关联
  - 同时管理弹幕与商品的剧集关联

### 1.7 弹幕类型分类

| 类型 | 说明 | 示例 |
|------|------|------|
| normal | 普通用户弹幕 | "哈哈哈好看" |
| highlight | 剧情亮点标注 | "⚠️高能预警" |
| ai | AI自动生成 | "这段演技炸裂💯" |

---

## 2. 基于时间线的商品卡片系统

### 2.1 系统概述

商品卡片系统将**道具资产**（来自有赞/电商平台同步）与**短剧分集**在**时间轴**上进行关联，播放到指定时间点时，商品卡片从底部滑出，观众可点击进入购买流程。

核心数据流：
```
CP上传商品 → product-sync(8089) → 道具资产(t_prop_asset)
CP后台 → 关联配置(t_drama_product_rel) → 设定时间点+分集
APP播放器 → 按时间点展示商品卡片
```

### 2.2 数据库表结构

**t_drama_product_rel（短剧-商品关联表）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| drama_id | bigint | 短剧ID |
| episode_id | bigint | 分集ID（可选，为空则全剧展示） |
| product_id | bigint | 商品道具ID |
| time_point | varchar(16) | 出现时间点（mm:ss） |
| create_time | datetime | 创建时间 |

**t_prop_asset（道具资产表）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| cp_user_id | bigint | CP用户ID |
| product_id | bigint | 商品ID |
| product_name | varchar(255) | 商品名称 |
| product_image | varchar(512) | 商品图片 |
| retail_price | decimal(10,2) | 价格 |
| create_time | datetime | 创建时间 |

**t_drama（短剧主表）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| cp_user_id | bigint | CP账号ID |
| title | varchar(255) | 剧名 |
| cover | varchar(512) | 封面 |
| hot_score | decimal(3,1) | 热度评分 |
| ad_revenue | decimal(12,2) | 广告收益 |

### 2.3 核心API端点

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/content/props` | 获取CP道具资产列表 |
| POST | `/api/content/props` | 添加道具资产（+ 调用8089分销签约） |
| GET | `/api/content/props/{propId}/linked-dramas` | 获取道具已关联的短剧 |

**商品关联CRUD通过 `t_drama_product_rel` 表实现**，在 ContentController 中通过 props 相关方法实现绑定逻辑。

### 2.4 前端管理页面

- **商品管理**: `drama-frontend-admin/src/pages/products/Index.vue`
  - 商品分类、卡片展示、搜索
  - 详情页: `Detail.vue`
  - 创建/编辑: `Form.vue`

- **道具资产**: `drama-frontend-admin/src/pages/props/Index.vue`
  - 从商品中选择道具
  - 关联到短剧分集
  - 设置时间点（mm:ss）

- **关联管理**: `drama-frontend-admin/src/pages/dramas/Relations.vue`
  - Tab页面: 弹幕关联 + 商品卡片关联
  - 设定分集、时间点

### 2.5 商品卡片展示逻辑

```
播放器进度到达 time_point (mm:ss格式)
  → 查询 t_drama_product_rel WHERE drama_id=? AND episode_id=? AND time_point=?
  → 获取关联的 product_id
  → 查询道具资产信息(名称/图片/价格)
  → 底部滑出卡片(带购买按钮)
  → 点击 → 跳转有赞/拼多多购买链接
```

### 2.6 签约同步流程

```
POST /api/content/props
  → 调用 8089 /api/sync/props?cpUserId= 获取商品列表
  → 调用 8089 /api/sync/props/sign 签约
  → 写入 t_prop_asset
```

---

## 3. 基于 OpenIM 的消息和剧群系统

### 3.1 系统概述

基于 **OpenIM SDK** 构建的消息系统，实现：
- **用户-用户单聊**（IM私信）
- **剧群聊天**（每部短剧自动创建群组）
- **AI助手接入**（@AI解说员触发 DeepSeek AI 自动回复）
- **WebHook 回调**（OpenIM 消息事件实时处理）

### 3.2 微服务分布

| 微服务 | 职责 |
|--------|------|
| drama-user-service | OpenIM 用户注册、群组管理、IM消息收发、DeepSeek AI对话 |
| drama-ai-service | OpenIM WebHook 回调处理、AI消息回复 |

### 3.3 OpenIM 配置

```
openim.api-url: http://172.16.0.66:10002
openim.secret: openIM123
openim.admin-user-id: imAdmin
openim.platform-id: 10
```

### 3.4 核心API端点

**UserController (drama-user-service)**

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/user/im/chat` | IM对话(AI回复) |
| POST | `/api/user/im/chat/stream` | IM流式对话(SSE) |
| GET | `/api/user/im/friends` | 获取好友列表 |
| GET | `/api/user/im/unread` | 获取未读消息 |
| GET | `/api/user/im/history/{peerImId}` | 获取聊天历史 |
| GET | `/api/user/im/friend-requests` | 获取好友申请 |

**DramaSocialController (剧群)**

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/social/dramas/{dramaId}/join` | 用户加入剧群 |
| POST | `/api/social/dramas/{dramaId}/send` | 发消息到剧群（@AI触发回复） |

**ImWebhookController (ai-service)**

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/ai/webhook/im-callback` | OpenIM消息回调入口 |
| POST | `/api/ai/webhook/im-callback/{command}` | OpenIM带命令回调 |

### 3.5 OpenIM 集成流程

**用户注册**
```
UserController.adminCreateUser()
  → registerToIM(user)
  → OpenImClient.registerUser("drama_user_" + userId, nickname, avatar)
  → 自动添加 ai_assistant 为好友
```

**剧群创建**
```
DramaSocialController.joinGroup()
  → 检查是否≥2个角色（含AI）
  → OpenImClient.createGroup("drama_"+dramaId, dramaTitle, members)
  → 自动将 AI解说员 设为群主
```

**AI 自动回复**
```
用户发送消息(@AI解说员)
  → ImWebhookController.imCallback()
  → DeepSeek API 对话
  → OpenImClient.sendGroupMsg() 回复到群
```

### 3.6 数据库表

**t_drama_character（剧群角色表）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| drama_id | bigint | 短剧ID |
| phone | varchar(20) | 手机号（角色用户） |
| role_name | varchar(100) | 角色名 |
| nickname | varchar(200) | 昵称 |
| im_id | varchar(200) | OpenIM用户ID |
| im_ok | tinyint | IM注册状态 |
| create_time | datetime | 创建时间 |

### 3.7 AI对话集成

**DeepSeekClient (AI对话服务)**

| 配置项 | 默认值 |
|--------|--------|
| api-url | https://api.deepseek.com/v1/chat/completions |
| model | deepseek-chat |
| max_tokens | 300 (同步) / 500 (流式) |

- `chat()`: 同步阻塞对话，返回完整回复
- `chatStream()`: SSE流式对话，逐token推送

### 3.8 前端页面

- **剧群管理**: `drama-frontend-admin/src/pages/dramas/Group.vue`
  - 添加角色用户（手机号注册）
  - 至少2个角色自动建群
  - AI为群主，无需验证

- **主面板**: `drama-frontend-admin/src/pages/dashboard/Index.vue`
  - 短剧列表中"剧群"快捷入口

---

## 4. 讨论区（评论）系统

### 4.1 系统概述

评论系统为**短剧级别**提供用户讨论交流功能，支持**多级回复**（评论-回复嵌套结构）。

### 4.2 数据库表结构

**t_drama_comment（短剧评论表）**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| drama_id | bigint | 短剧ID |
| episode_num | int | 分集号（可选） |
| user_id | bigint | 评论用户ID |
| user_name | varchar(64) | 用户昵称 |
| content | text | 评论内容 |
| parent_id | bigint | 父评论ID（0=顶层） |
| reply_to_user_id | bigint | 回复目标用户ID |
| reply_to_user_name | varchar(64) | 回复目标用户昵称 |
| create_time | datetime | 创建时间 |

### 4.3 API端点

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/user/comment` | 获取评论列表（可公开访问） |
| POST | `/api/user/comment` | 发表评论/回复 |
| DELETE | `/api/user/comment/{id}` | 删除评论（作者本人） |

**评论鉴权**：Gateway JwtAuthFilter 配置 `/api/user/comment` 为白名单路径（读取公开），发表/删除在控制器内部自行鉴权。

### 4.4 前端组件

- **评论组件**: 嵌入短剧播放页面的评论区
- **管理后台**: admin 中的评论审核模块（通过 `t_content_audit_log` 表记录审核流水）

---

## 5. 系统集成关系与数据流

### 5.1 整体架构

```
┌─────────────────────────────────────────────┐
│  API Gateway (8080) + Nacos                  │
│  ┌─────────┬─────────┬─────────┬──────────┐  │
│  │content  │user     │ai       │product-s│  │
│  │8102     │8101     │8105     │ync(8089)│  │
│  ├─────────┼─────────┼─────────┼──────────┤  │
│  │•弹幕CRUD│•IM/剧群 │•AI弹幕  │•商品同步│  │
│  │•商品关联│•DeepSeek│•WebSocket│•有赞签约│  │
│  │•评论    │•OpenIM  │•WebHook │•道具资产│  │
│  └─────────┴─────────┴─────────┴──────────┘  │
│           MySQL (drama_fusion)                │
│           Redis (127.0.0.1:6379)              │
│           OpenIM (172.16.0.66:10002)          │
└─────────────────────────────────────────────┘
```

### 5.2 关键数据流

```
弹幕系统:
  CP后台 → POST /content/bullets → t_bullet_commentary
  APP播放 → GET /content/dramas/{id}/bullets → 按episode_id+time_point渲染
  AI实时 → POST /ai/bullet/push → WebSocket广播

商品卡片系统:
  商品同步 → 8089 /api/sync/props → t_prop_asset
  关联配置 → POST /content/props → t_drama_product_rel
  APP播放 → time_point触发 → 查询关联商品 → 卡片展示

消息/剧群系统:
  用户注册 → registerToIM() → OpenIM API → 自动加ai_assistant好友
  剧群创建 → joinGroup() → createGroup() → AI为群主
  消息回调 → WebHook → DeepSeek AI → sendGroupMsg 回复

评论系统:
  用户发表 → POST /comment → t_drama_comment
  审核流水 → t_content_audit_log
```

### 5.3 数据库表关系

```
t_drama (短剧主表)
  ├── t_episode (分集表) FK: drama_id
  │     └── t_bullet_commentary (弹幕) FK: episode_id
  ├── t_drama_comment (评论) FK: drama_id
  ├── t_drama_product_rel (商品关联) FK: drama_id + episode_id
  │     └── t_prop_asset (道具资产) FK: product_id
  └── t_drama_character (剧群角色) FK: drama_id

t_user (用户表)
  ├── t_bullet_message (弹幕消息带用户ID)
  ├── t_drama_comment (评论带user_id)
  └── OpenIM: "drama_user_{id}" 格式注册
```

### 5.4 技术栈

| 层级 | 技术 |
|------|------|
| 后端框架 | Spring Boot 3.2.5 |
| ORM | MyBatis-Plus 3.5.5 |
| 服务发现 | Nacos 2.3.2 |
| API网关 | Spring Cloud Gateway |
| 消息推送 | STOMP over WebSocket (SockJS) |
| IM平台 | OpenIM (172.16.0.66:10002) |
| AI对话 | DeepSeek Chat API |
| 数据库 | MySQL 8.0 |
| 缓存 | Redis |
| 外部电商 | 有赞/拼多多/京东联盟 |
| 前端 | Vue 3 + Vite + Arco Design |
| 构建 | Maven (Java) + npm (Vue) |

---

> 报告结束。Generated by DeepSeek TUI.
