# class-session-analysis

**Repository Path**: ibdp/class-session-analysis

## Basic Information

- **Project Name**: class-session-analysis
- **Description**: 课堂总结分析接口服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Class Session Analysis (课堂会话分析系统)

## 项目用途

课堂会话分析系统，从课程视频 + PPT 课件输入，通过 11 步异步分析管线自动生成：

- **ASR 语音识别** — 转写课堂录音为带时间戳的 SRT 字幕
- **OCR 文字提取** — 提取视频帧和 PPT 页面中的文字内容
- **字幕修正** — 利用大模型对 ASR 结果进行语义修正
- **课堂总结** — 多维度 AI 课堂分析报告
- **思维导图** — 自动生成大纲文本并渲染为图片
- **时间轴分段** — 按知识点/主题划分课堂阶段

## 依赖环境

### 运行时

| 组件 | 版本 | 说明 |
|------|------|------|
| Java | 17+ | 运行环境 |
| MySQL | 8.0 | 数据持久化 |
| ffmpeg | 任意 | 音视频处理（Docker 镜像内置） |
| Docker | 任意 | 部署方式（推荐） |

### 构建

| 组件 | 版本 |
|------|------|
| Maven | 3.9+ |
| JDK | 17+ |

## 项目结构

```
class-session-analysis/
├── pom.xml                        # 父 POM (Spring Boot 3.2.5)
├── Dockerfile                     # Docker 镜像构建 (eclipse-temurin:17-jre + ffmpeg)
├── doc/                           # 文档
├── class-session-common/          # 公共模块：DTO、实体类、枚举
├── class-session-dao/             # 数据访问层：MyBatis-Plus Mapper
├── class-session-service/         # 业务逻辑 + 外部服务客户端
├── class-session-task/            # 异步分析任务引擎 + 11 个步骤实现
├── class-session-web/             # REST 控制器 + Token 拦截器
└── class-session-app/             # Spring Boot 入口 + application.yml
```

## 外部组件

| 服务 | 用途 | 默认地址 |
|------|------|----------|
| **SenseVoice** | ASR 语音识别 | `http://localhost:8100` |
| **PDF-Extract-Kit** | OCR 文字识别（PPT/视频帧） | `http://localhost:9898` |
| **DeepSeek / OpenAI 兼容 LLM** | 字幕修正、总结、思维导图、时间轴分段 | 通过 `llm.url` 配置 |

## 分析管线

11 步顺序执行，任一步骤失败则整个任务终止：

| # | 步骤 | 功能 |
|---|------|------|
| 1 | `audio-extract` | 从视频中提取音频 (ffmpeg → WAV) |
| 2 | `video-frame-extract` | 从视频中提取关键帧 (ffmpeg → JPG) |
| 3 | `sense-voice-asr` | 语音识别 (SenseVoice → SRT) |
| 4 | `video-frame-ocr` | 视频帧 OCR (PDF-Extract-Kit)，支持抽样和并行 |
| 5 | `ppt-ocr` | PPT 页面 OCR (PDF-Extract-Kit) |
| 6 | `srt-correction` | SRT 字幕 LLM 修正 |
| 7 | `save-final-srt` | 保存修正后 SRT 文件 |
| 8 | `class-summary` | LLM 生成课堂总结 |
| 9 | `mindmap-outline` | LLM 生成思维导图大纲 |
| 10 | `mindmap-image` | 渲染思维导图图片 |
| 11 | `timeline-segment` | LLM 对课堂内容进行时间轴分段 |

**任务生命周期：** `PENDING(0) → RUNNING(1) → COMPLETED(2)` 或 `→ FAILED(3)`

## REST API

所有 API 统一前缀 `/api/v1`，除 `/token` 外均需在请求头中携带 `X-Token`。

### 1. 获取 Token

```
POST /api/v1/token
```

**响应：**
```json
{
  "code": 0,
  "data": {
    "token": "uuid-string",
    "expiredAt": "2026-06-14T00:00:00"
  }
}
```

### 2. 上传视频

```
POST /api/v1/video/upload
Content-Type: multipart/form-data

token: <token>
file:  <bk.mp4>
```

**限制：** 仅支持 `mp4`，最大 800MB

**响应：**
```json
{
  "code": 0,
  "data": {
    "fileId": 15,
    "fileName": "bk.mp4",
    "fileSize": 51000000
  }
}
```

### 3. 上传 PPT

```
POST /api/v1/ppt/upload
Content-Type: multipart/form-data

token: <token>
file:  <ppt.pptx>
```

**限制：** 支持 `ppt`/`pptx`，最大 100MB

**响应：**
```json
{
  "code": 0,
  "data": {
    "fileId": 15,
    "fileName": "ppt.pptx",
    "fileSize": 69775902
  }
}
```

### 4. 开始分析

```
POST /api/v1/analysis/start
Content-Type: application/json
X-Token: <token>

{
  "token": "<token>",
  "videoFileId": 15,
  "pptFileId": 15
}
```

**响应：**
```json
{
  "code": 0,
  "data": {
    "taskId": "task-xxxxxxxxxxxx",
    "status": "PENDING"
  }
}
```

### 5. 查询进度

```
GET /api/v1/analysis/{taskId}/status
X-Token: <token>
```

**响应：**
```json
{
  "code": 0,
  "data": {
    "taskId": "task-xxxxxxxxxxxx",
    "status": "RUNNING",
    "progress": 50,
    "currentStep": "ppt-ocr",
    "startedAt": "2026-06-13T00:43:41",
    "completedAt": null,
    "errorMessage": null
  }
}
```

**status 枚举：** `PENDING` / `RUNNING` / `COMPLETED` / `FAILED`

### 6. 获取结果

```
GET /api/v1/analysis/{taskId}/result
X-Token: <token>
```

**响应：**
```json
{
  "code": 0,
  "data": {
    "taskId": "task-xxxxxxxxxxxx",
    "status": "COMPLETED",
    "summary": {
      "content": "好的，作为一名教育分析专家...（总结全文）",
      "dimensions": null
    },
    "mindmap": {
      "outline": "课堂分析图谱...（大纲文本）",
      "imageBase64": "iVBORw0KGgo...（Base64 图片）",
      "imageFormat": "image/png"
    },
    "subtitle": {
      "content": "1\n00:00:00,000 --> 00:00:07,000\n...（完整 SRT）",
      "language": "zh",
      "srtFilePath": "/data/classSessionAnalysis/srt/...srt"
    },
    "timelineSegments": [
      {
        "order": 1,
        "name": "课堂导入与问题提出",
        "startTime": 0.0,
        "endTime": 70.0,
        "description": "教师通过学生写作片段引入..."
      }
    ],
    "pptOcrResults": [
      {
        "pageNumber": 1,
        "markdownContent": "# 智能巡课平台..."
      }
    ]
  }
}
```

## 配置文件说明 (`application.yml`)

### 服务端口

```yaml
server:
  port: 8200                                    # 应用监听端口
  servlet.multipart.max-file-size: 800MB        # 上传文件大小上限
```

### 数据库

```yaml
spring.datasource:
  url: jdbc:mysql://127.0.0.1:3308/classSessionAnalysis?useUnicode=true&characterEncoding=utf-8
  username: root
  password: ****                                 # 数据库密码
  hikari.maximum-pool-size: 20                  # 连接池上限
```

### 文件存储

```yaml
storage:
  base-path: /data/classSessionAnalysis          # 数据根目录
  video-dir: videos                              # 视频存储子目录
  ppt-dir: ppts                                  # PPT 存储子目录
  ppt-image-dir: ppt_images                      # PPT 页面图片子目录
  audio-dir: audio                               # 音频文件子目录
  frame-dir: frames                              # 视频帧子目录
  srt-dir: srt                                   # SRT 字幕文件子目录
```

### Token

```yaml
token.expire-hours: 24                           # Token 过期时间（小时）
```

### OCR 参数

```yaml
ocr:
  frame-sample-interval: 60                      # 视频帧抽样间隔（每 N 帧处理 1 帧）
  parallelism: 2                                 # OCR 并行线程数
```

### 外部服务

```yaml
external:
  sense-voice:
    base-url: http://192.168.100.5:8100          # SenseVoice ASR 服务地址
    request-timeout: 300000                      # 请求超时（毫秒）

  pdf-extract-kit:
    base-url: http://192.168.100.5:9898          # PDF-Extract-Kit OCR 服务地址
    api-path-prefix: /api/v1/recognition         # API 路径前缀
    poll-interval: 3000                          # 任务轮询间隔（毫秒）
    max-poll-retries: 15                         # 最大轮询次数
```

### LLM

```yaml
llm:
  url: https://api.deepseek.com/v1/chat/completions  # LLM API 地址
  api-key: sk-****                                    # API 密钥
  model: deepseek-chat                                 # 模型名称
  temperature: 0.3                                     # 生成温度
  max-tokens: 4096                                     # 最大输出 Token
  timeout: 120000                                      # 请求超时（毫秒）
```

## 构建与部署

### 1. 编译

```bash
mvn clean package -DskipTests
```

### 2. 构建 Docker 镜像

```bash
docker build -t class-session-app:latest .
```

### 3. 启动容器

```bash
docker run -d --name class-session-app \
  --network host \
  -v /data/classSessionAnalysis:/data/classSessionAnalysis \
  class-session-app:latest
```

> `--network host` 使容器直接使用宿主机网络，确保能访问宿主机上的 MySQL (127.0.0.1:3308) 和外部服务。
> `/data/classSessionAnalysis` 需已存在且有正确权限。

### 4. 查看日志

```bash
docker logs -f class-session-app
```

## 数据库表结构

核心业务表（15 个）：

| 表 | 用途 |
|----|------|
| `token_info` | Token 管理 |
| `video_file` | 视频文件记录 |
| `ppt_file` | PPT 文件记录 |
| `ppt_page_image` | PPT 页面图片 |
| `analysis_task` | 分析任务 |
| `audio_file` | 音频文件 |
| `video_frame` | 视频帧 |
| `frame_ocr_result` | 视频帧 OCR 结果 |
| `ppt_ocr_result` | PPT OCR 结果 |
| `srt_subtitle` | SRT 字幕（原始 + 修正） |
| `srt_correction_log` | SRT 修正日志 |
| `class_summary` | 课堂总结 |
| `mindmap_outline` | 思维导图大纲 |
| `mindmap_image` | 思维导图图片 |
| `video_timeline_segment` | 时间轴分段 |