# smart-speech-analyzer

**Repository Path**: singlr/smart-speech-analyzer

## Basic Information

- **Project Name**: smart-speech-analyzer
- **Description**: 智能语音分析
- **Primary Language**: C#
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能语音分析系统（Smart Speech Analyzer）

基于 .NET 8 + Vue 3 构建的实时语音内容违规检测系统，对接第三方语音转文字流，通过 Ollama + Qwen 大模型实时检测文本内容是否包含违规词，并将检测结果结构化存储到数据库。

本系统与芋道框架（ruoyi-vue-pro）共享同一 MySQL 数据库，用户认证使用芋道的 `system_users` 表，业务表使用 `t_voice_` 前缀。

---

## 功能特性

### 功能清单

| 模块     | 功能      | 说明                                              |
| ------ | ------- | ----------------------------------------------- |
| 违规词管理  | 增删改查    | 支持违规词的创建、编辑、删除（逻辑删除）、查看详情                       |
| 违规词管理  | 分类管理    | 按违禁类型分类（违法违规、色情低俗、政治敏感、其他）                      |
| 违规词管理  | 严重等级    | 1-5 级严重等级评定，以 ★ 星级显示（悬停显示低/中/高危）                |
| 违规词管理  | 启用/禁用   | 支持单条违规词的启用/禁用状态切换，禁用的词不参与检测                     |
| 违规词管理  | 关键词搜索   | 支持按违规词内容或描述进行模糊搜索                               |
| 违规词管理  | 分类筛选    | 按违禁类型筛选，快速定位特定分类的违规词                            |
| 违规词管理  | 状态筛选    | 按启用/禁用状态筛选                                      |
| 违规词管理  | 分页查询    | 支持分页浏览，可选每页 10/20/50/100 条                      |
| 语音结果处理 | 历史查询    | 分页查看所有检测记录，支持按违规状态、风险等级、时间范围筛选                  |
| 语音结果处理 | 风险等级星级  | 检测结果风险等级使用违规词的严重等级星级（1-5星，命中多个取最高），以 ★ 显示       |
| 语音结果处理 | 文本高亮标红  | 检测文本中命中的违规词自动标红显示（红色加粗下划线），直观展示命中位置             |
| 语音结果处理 | 命中词详情提示 | 鼠标悬停标红文字显示违规词描述 tooltip，点击弹出详情弹窗                |
| 语音结果处理 | 匹配违规词标签 | 匹配违规词列以标签形式展示所有命中的违规词（来自检测结果 JSON 的 results 数组） |
| 语音结果处理 | 人工判定状态列 | 列表中直接显示每条记录的判定状态：未判定 / AI 正确 / 漏报 / 误报          |
| 语音结果处理 | 详情查看    | 查看单条检测结果的完整信息，包括高亮标红文本、命中标签、AI 分析说明             |
| 人工判定   | 人工复核    | 对检测结果进行人工判定：AI 正确 / 漏报 / 误报                     |
| 人工判定   | AI 分析展示 | 判定弹窗中展示 AI 分析说明（analysis 字段）                    |
| 人工判定   | 指定敏感词   | 误报时可填写被误判的敏感词，多个用逗号分隔                           |
| 人工判定   | 备注说明    | 支持为人工判定添加备注说明                                   |
| 人工判定   | 判定详情查看  | 已判定的记录可查看完整的判定详情（判定类型、AI 判定、人工判定、误判词、备注、判定时间）   |
| AI 自学习 | 蒸馏提炼    | 基于人工纠偏记录，通过大模型自动提炼审核补充规则                        |
| AI 自学习 | 异步执行    | 蒸馏任务通过 Hangfire 后台队列异步执行，不阻塞主流程                 |
| AI 自学习 | 增量优化    | 每次只处理新增纠偏记录，结合上一版规则增量优化                         |
| AI 自学习 | 规则注入    | 检测时自动注入学习规则到提示词，持续优化检测准确率                       |

### 违规词管理详细说明

违规词管理是系统的核心基础模块，为 AI 大模型检测提供敏感词参考库。

**功能描述：**

- **违规词维护**：支持新增、编辑、删除违规词，每条违规词包含词内容、分类、严重等级、描述等属性。删除采用逻辑删除机制，数据不会物理丢失。
- **分类体系**：内置四种违禁类型分类——违法违规、色情低俗、政治敏感、其他，方便对违规词进行归类管理。
- **严重等级评定**：采用 1-5 级星级评分制，前端以 ★ 星级直观展示（1-2星绿色=低危，3-4星橙色=中危，5星红色=高危），鼠标悬停显示等级文字。检测结果的风险等级直接使用命中违规词中最高的星级。
- **启用/禁用控制**：每条违规词可独立控制启用状态，禁用的词不会被注入到 AI 检测的敏感词参考库中，实现灵活的检测策略调整。
- **多维度检索**：支持关键词模糊搜索（匹配词内容或描述）、分类筛选、状态筛选三种查询方式，可组合使用快速定位目标违规词。
- **分页浏览**：列表支持分页展示，可选每页 10/20/50/100 条记录，按创建时间倒序排列。

**数据表结构（t_voice_sensitive_word）：**

| 字段                                              | 类型           | 说明                    |
| ----------------------------------------------- | ------------ | --------------------- |
| id                                              | bigint       | 自增主键                  |
| word                                            | varchar(200) | 违规词内容（必填）             |
| category                                        | varchar(100) | 分类（违法违规/色情低俗/政治敏感/其他） |
| severity                                        | int          | 严重等级（1-5）             |
| status                                          | int          | 状态（0=启用, 1=禁用）        |
| description                                     | varchar(500) | 描述说明                  |
| creator/create_time/updater/update_time/deleted | -            | 芋道 BaseDO 基础字段        |

---

## 技术栈

### 后端

| 技术              | 版本        | 说明              |
| --------------- | --------- | --------------- |
| .NET            | 8.0       | 运行时框架           |
| Furion          | 4.9.9.21  | 应用框架            |
| SqlSugar        | 5.1.4.160 | ORM 框架          |
| MySQL           | 8.0+      | 关系型数据库          |
| JWT             | -         | 身份认证            |
| BCrypt.Net-Next | 4.0.3     | 密码加密            |
| Hangfire        | -         | 后台任务调度（AI 蒸馏队列） |
| Mapster         | 7.4.0     | 对象映射            |

### 前端

| 技术           | 版本   | 说明       |
| ------------ | ---- | -------- |
| Vue          | 3.4+ | 前端框架     |
| Element Plus | 2.7+ | UI 组件库   |
| Vite         | 5.2+ | 构建工具     |
| Vue Router   | 4.3+ | 路由管理     |
| Pinia        | 2.1+ | 状态管理     |
| Axios        | 1.7+ | HTTP 客户端 |

---

## 项目结构

```
smart-speech-analyzer/
├── backend/                                    # 后端项目
│   ├── SmartSpeechAnalyzer.sln                # 解决方案文件
│   └── src/
│       ├── SmartSpeechAnalyzer.Core/           # 核心层
│       │   ├── Entities/                        # 数据实体
│       │   │   ├── BaseEntity.cs                  # 基础实体（芋道 BaseDO 规范）
│       │   │   ├── SystemUser.cs                  # 用户实体（映射芋道 system_users 表）
│       │   │   ├── SensitiveWord.cs              # 违规词实体
│       │   │   ├── DetectionSession.cs           # 检测会话实体
│       │   │   ├── DetectionResult.cs            # 检测结果实体
│       │   │   ├── HumanJudgment.cs              # 人工纠偏记录实体
│       │   │   └── LearnedRule.cs                # AI 蒸馏规则实体
│       │   ├── Dtos/                            # 数据传输对象
│       │   │   ├── CommonDtos.cs                 # 通用 DTO
│       │   │   ├── SensitiveWordDtos.cs          # 违规词 DTO
│       │   │   └── DetectionDtos.cs              # 检测相关 DTO
│       │   ├── AppDbContext.cs                  # SqlSugar 数据库上下文
│       │   └── GlobalUsings.cs                  # 全局 using
│       ├── SmartSpeechAnalyzer.Application/    # 应用层
│       │   ├── Interfaces/                      # 服务接口
│       │   │   └── IServiceInterfaces.cs        # 所有服务接口定义
│       │   └── Services/                        # 服务实现
│       │       ├── AuthService.cs                # 用户认证服务
│       │       ├── SensitiveWordService.cs       # 违规词管理服务
│       │       ├── DetectionService.cs           # 检测业务服务
│       │       ├── OllamaService.cs              # Ollama 大模型服务
│       │       └── AsrWebSocketService.cs        # ASR WebSocket 接收服务
│       └── SmartSpeechAnalyzer.Web.Entry/      # Web 入口层
│           ├── Controllers/                     # API 控制器
│           │   ├── AuthController.cs             # 认证控制器
│           │   ├── SensitiveWordController.cs    # 违规词控制器
│           │   └── DetectionController.cs        # 检测控制器
│           ├── Properties/
│           │   └── launchSettings.json           # 启动配置
│           ├── Program.cs                        # 应用启动入口
│           ├── appsettings.json                  # 应用配置
│           └── appsettings.Development.json      # 开发环境配置
├── frontend/                                   # 前端项目
│   ├── index.html                               # HTML 入口
│   ├── package.json                             # 依赖配置
│   ├── vite.config.js                           # Vite 配置
│   └── src/
│       ├── main.js                              # 应用入口
│       ├── App.vue                              # 根组件
│       ├── styles.css                           # 全局样式
│       ├── api/                                 # API 接口
│       │   ├── auth.js                           # 认证接口
│       │   ├── sensitiveWord.js                  # 违规词接口
│       │   └── detection.js                      # 检测接口
│       ├── views/                               # 页面组件
│       │   ├── Login.vue                         # 登录页
│       │   ├── Layout.vue                        # 布局框架
│       │   ├── Monitor.vue                       # 实时监控页
│       │   ├── SensitiveWords.vue                # 违规词管理页
│       │   └── Results.vue                       # 检测结果页
│       ├── router/                              # 路由
│       │   └── index.js                          # 路由配置
│       ├── stores/                              # 状态管理
│       │   └── auth.js                           # 认证状态
│       └── utils/                               # 工具函数
│           └── request.js                        # Axios 封装
└── README.md                                    # 项目说明文档
```

---

## 环境要求

- **操作系统**：Windows 10+ / macOS 10.14+ / Linux
- **.NET SDK**：8.0.x
- **Node.js**：18.x 或更高版本
- **MySQL**：8.0+ 数据库服务
- **Ollama**：最新版，需拉取 qwen3.6 模型

---

## 快速开始

### 第一步：准备环境

1. 安装 [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)

2. 安装 [Node.js](https://nodejs.org/) (推荐 v18+)

3. 安装并配置 MySQL 数据库

4. 安装 Ollama 并拉取模型：
   
   ```bash
   # 安装 Ollama（官网下载）
   # 拉取 qwen3.6 模型
   ollama pull qwen3.6
   ```

### 第二步：准备数据库

本系统与芋道框架共享同一 MySQL 数据库，需确保：

1. **芋道框架已部署**：`system_users` 表已存在且有可用用户
2. **业务表自动创建**：首次启动时自动创建 `t_voice_` 前缀的业务表

```sql
-- 业务表由系统自动创建，无需手动执行
-- t_voice_sensitive_word       违规词表
-- t_voice_detection_session    检测会话表
-- t_voice_detection_result     检测结果表
-- t_voice_human_judgment       人工判定表
-- t_voice_learned_rule         AI 蒸馏规则表
```

### 第三步：配置后端

编辑后端配置文件 `backend/src/SmartSpeechAnalyzer.Web.Entry/appsettings.json`：

```json
{
  "ConnectionStrings": {
    "Default": "Server=localhost;Port=3306;Database=SmartSpeechAnalyzer;Uid=root;Pwd=你的数据库密码;AllowPublicKeyRetrieval=True;CharSet=utf8mb4;"
  },
  "JWT": {
    "SecretKey": "smart_speech_analyzer_secret_key_must_be_long_enough_2024",
    "Issuer": "SmartSpeechAnalyzer",
    "Audience": "SmartSpeechAnalyzer",
    "ExpiredTime": 7200
  },
  "Ollama": {
    "BaseUrl": "http://localhost:11434",
    "Model": "qwen3.6"
  },
  "AsrWebSocket": {
    "Url": "ws://localhost:8080/asr"
  },
  "Cors": {
    "AllowedOrigins": "http://localhost:5173"
  }
}
```

### 第四步：启动后端

```bash
cd backend/src/SmartSpeechAnalyzer.Web.Entry
dotnet run
```

后端启动后：

- 应用地址：`http://localhost:5000`
- Swagger 文档：`http://localhost:5000/swagger`

> **注意**：首次启动会自动创建 `t_voice_` 前缀的业务表。用户数据由芋道框架管理，不在本系统初始化。

### 第五步：启动前端

```bash
cd frontend
npm install     # 首次运行需要安装依赖
npm run dev     # 启动开发服务器
```

前端启动后访问：`http://localhost:5173`

### 第六步：登录系统

使用系统管理员账户登录：

- **用户名**：`admin`
- **密码**：`admin123`

> 用户数据存储在芋道框架的 `system_users` 表中，如已部署芋道框架，也可使用芋道中配置的其他用户登录。

---

## 站点访问方式

### 开发环境

启动后端和前端服务后，通过以下地址访问系统：

| 服务           | 地址                               | 说明                    |
| ------------ | -------------------------------- | --------------------- |
| 前端页面         | `http://localhost:5173`          | 系统主入口，登录后使用各项功能       |
| 后端 API       | `http://localhost:5000`          | 后端服务地址，前端通过代理访问       |
| Swagger 文档   | `http://localhost:5000/swagger`  | 后端 API 接口文档，可在线调试     |
| Hangfire 仪表盘 | `http://localhost:5000/hangfire` | 后台任务监控，查看 AI 蒸馏任务执行状态 |

### 生产环境

部署后根据实际配置访问，建议使用反向代理（Nginx/IIS）统一入口：

| 服务        | 推荐部署方式        | 默认端口     |
| --------- | ------------- | -------- |
| 前端静态资源    | Nginx / IIS   | 80 / 443 |
| 后端服务      | 系统服务 / Docker | 5000     |
| MySQL 数据库 | 独立数据库服务器      | 3306     |
| Ollama 服务 | 独立 AI 服务器     | 11434    |

### 登录说明

- **默认管理员账号**：用户名 `admin`，密码 `admin123`
- 用户体系与芋道框架共享，可通过芋道管理后台创建更多用户
- 登录成功后 Token 自动保存在浏览器本地，有效期为 2 小时

### 功能模块入口

登录系统后，左侧菜单栏提供以下功能入口：

| 菜单    | 功能说明               |
| ----- | ------------------ |
| 实时监控  | 查看实时检测会话和统计数据      |
| 违规词管理 | 维护违规词库（增删改查、分类、等级） |
| 检测结果  | 查询历史检测记录、人工判定、查看详情 |

---

## 配置详解

### 数据库配置（ConnectionStrings）

| 参数       | 说明                |
| -------- | ----------------- |
| Server   | MySQL 服务器地址       |
| Port     | MySQL 端口（默认 3306） |
| Database | 数据库名称             |
| Uid      | 数据库用户名            |
| Pwd      | 数据库密码             |
| CharSet  | 字符集（建议 utf8mb4）   |

### JWT 配置

| 参数          | 说明                   |
| ----------- | -------------------- |
| SecretKey   | 密钥，用于签名令牌（生产环境请务必修改） |
| Issuer      | 令牌颁发者                |
| Audience    | 令牌接收方                |
| ExpiredTime | 令牌过期时间（秒）            |

### Ollama 配置

| 参数      | 说明                            |
| ------- | ----------------------------- |
| BaseUrl | Ollama 服务地址                   |
| Model   | 使用的大模型名称（如 qwen3.6、qwen2.5 等） |

### ASR WebSocket 配置

| 参数  | 说明                            |
| --- | ----------------------------- |
| Url | 第三方 ASR 语音转文字服务的 WebSocket 地址 |

---

## API 接口

### 认证接口

| 方法   | 路径                   | 说明            | 认证  |
| ---- | -------------------- | ------------- | --- |
| POST | `/api/auth/login`    | 用户登录，获取 Token | 否   |
| GET  | `/api/auth/userinfo` | 获取当前用户信息      | 是   |

### 违规词管理接口

| 方法     | 路径                               | 说明          | 认证  |
| ------ | -------------------------------- | ----------- | --- |
| GET    | `/api/sensitiveword/list`        | 获取违规词分页列表   | 是   |
| GET    | `/api/sensitiveword/all-enabled` | 获取所有已启用的违规词 | 否   |
| GET    | `/api/sensitiveword/{id}`        | 获取违规词详情     | 是   |
| POST   | `/api/sensitiveword`             | 新增违规词       | 是   |
| PUT    | `/api/sensitiveword/{id}`        | 更新违规词       | 是   |
| DELETE | `/api/sensitiveword/{id}`        | 删除违规词       | 是   |

### 检测接口

| 方法   | 路径                                        | 说明                   | 认证  |
| ---- | ----------------------------------------- | -------------------- | --- |
| POST | `/api/detection/detect`                   | 对文本进行违规检测            | 否   |
| GET  | `/api/detection/results`                  | 获取检测结果分页列表           | 是   |
| GET  | `/api/detection/results/{id}`             | 获取检测结果详情             | 是   |
| GET  | `/api/detection/sessions`                 | 获取检测会话列表             | 是   |
| POST | `/api/detection/sessions/start`           | 开始新的检测会话             | 否   |
| POST | `/api/detection/sessions/end/{sessionId}` | 结束检测会话               | 否   |
| POST | `/api/detection/judgment`                 | 提交人工判定（纠偏）           | 是   |
| GET  | `/api/detection/judgment/{resultId}`      | 获取指定结果的人工判定记录        | 是   |
| POST | `/api/detection/distill`                  | 触发 AI 蒸馏（将纠偏记录提炼为规则） | 是   |

---

## 检测流程说明

系统的核心检测流程如下：

```
第三方 ASR 服务
      │
      ▼  WebSocket 语音流
  AsrWebSocketService  ── 接收实时文字流
      │
      ▼
  DetectionService
      │
      ├─► 从数据库获取所有违规词
      │
      ├─► 调用 OllamaService
      │       │
      │       ▼
      │   Ollama (Qwen 大模型)
      │   进行语义分析和违规检测
      │       │
      │       ▼
      │   返回结构化检测结果
      │
      ▼
  将检测结果（JSON）保存到 MySQL 数据库
```

### 检测结果 JSON 结构

大模型输出的检测结果严格遵循以下 JSON 结构：

| 字段                    | 类型             | 说明                           |
| --------------------- | -------------- | ---------------------------- |
| sessionId             | string         | 会话 ID                        |
| originalText          | string         | 原始检测文本                       |
| detectionTime         | string         | 检测时间（格式：yyyy-MM-dd HH:mm:ss） |
| audio                 | string \| null | 音频标识或 URL（可选）                |
| hasSensitiveContent   | string         | 是否包含违禁词（"是" 或 "否"）           |
| results               | array          | 命中的敏感词详情列表                   |
| results[].word        | string         | 命中的敏感词                       |
| results[].startIndex  | number         | 在文本中的起始位置（从 0 开始）            |
| results[].endIndex    | number         | 在文本中的结束位置                    |
| results[].description | string         | 触发说明（如：第7个字到第8个字触发敏感词「赌博」）   |
| riskLevel             | number         | 风险等级（0-5，0=无风险，5=极高）         |
| analysis              | string \| null | 分析说明                         |
| modelUsed             | string         | 使用的 AI 模型名称                  |
| processingDurationMs  | number         | 处理耗时（毫秒）                     |

#### 检测结果 JSON 示例（包含违规内容）

```json
{
  "sessionId": "a1b2c3d4e5f6",
  "originalText": "这个网站涉及赌博和毒品信息，请注意安全。",
  "detectionTime": "2026-07-13 16:29:00",
  "audio": null,
  "hasSensitiveContent": "是",
  "results": [
    {
      "word": "赌博",
      "startIndex": 7,
      "endIndex": 8,
      "description": "第7个字到第8个字触发敏感词「赌博」"
    },
    {
      "word": "毒品",
      "startIndex": 10,
      "endIndex": 11,
      "description": "第10个字到第11个字触发敏感词「毒品」"
    }
  ],
  "riskLevel": 4,
  "analysis": "文本中明确提及赌博和毒品，属于高危违规内容",
  "modelUsed": "qwen3.6",
  "processingDurationMs": 520
}
```

#### 检测结果 JSON 示例（无违规内容）

```json
{
  "sessionId": "a1b2c3d4e5f6",
  "originalText": "今天天气真好，我们去公园散步吧。",
  "detectionTime": "2026-07-13 16:30:00",
  "audio": null,
  "hasSensitiveContent": "否",
  "results": [],
  "riskLevel": 0,
  "analysis": "文本内容正常，未检测到违规词",
  "modelUsed": "qwen3.6",
  "processingDurationMs": 280
}
```

### 大模型提示词

系统会结合以下信息构建检测提示词：

- **敏感词参考库**：从数据库获取的所有已启用违规词
- **历史上下文**：同一会话中的前文内容（用于语境判断）
- **当前待检测文本**：需要重点审核的目标文本

审核规则：

1. 结合上下文判断是否存在违规（谐音、隐喻、变体、黑话等）
2. 如果上下文是在讲述"防骗科普"或"新闻播报"，则不判定为违规
3. 严格输出 JSON 格式，不输出其他解释性文字

---

## 检测结果查询

检测结果查询页面用于查看和管理所有历史检测记录，支持多维度筛选和详细信息展示。

### 列表展示

检测结果列表包含以下核心列：

| 列名    | 说明                                                  |
| ----- | --------------------------------------------------- |
| 检测时间  | 检测执行的时间                                             |
| 检测文本  | 原始待检测文本，**命中的违规词自动标红**（红色加粗下划线），鼠标悬停显示违规词描述，点击可弹出详情 |
| 是否违规  | 违规（红色标签）/ 正常（绿色标签）                                  |
| 风险等级  | ★ 星级显示（1-5星），使用命中违规词中最高的严重等级星级，悬停显示等级文字（低危/中危/高危）   |
| 匹配违规词 | 以标签形式展示所有命中的违规词（来自检测结果 JSON 的 results 数组）           |
| 检测模型  | 使用的 AI 模型名称                                         |
| 人工判定  | 判定状态：未判定 / AI 正确 / 漏报 / 误报                          |
| 操作    | 详情、人工判定按钮                                           |

### 文本高亮标红功能

系统会解析每条检测结果的 JSON（`detectedResultJson` 字段中的 `results` 数组），根据每个命中词的 `startIndex` 和 `endIndex` 在原始文本中定位并标红显示。

**标红规则：**

- 标红样式：红色文字 + 加粗 + 红色下划线
- 悬停提示：鼠标移到标红文字上，tooltip 显示该违规词的 `description` 描述内容
- 点击弹窗：点击标红文字弹出详情框，显示违规词名称和完整描述说明

### 筛选功能

支持以下筛选条件，可组合使用：

- **违规状态**：仅违规 / 仅正常
- **最低风险等级**：低危及以上 / 中危及以上 / 高危
- **时间范围**：自定义开始时间和结束时间

---

## 人工判定功能

在检测结果查询页面，可以对每条检测结果进行人工复核，列表中直接显示判定状态（未判定 / AI 正确 / 漏报 / 误报）。

### 判定类型说明

| 判定类型  | 说明                     | 操作                      |
| ----- | ---------------------- | ----------------------- |
| AI 正确 | AI 的判定结果正确，无需纠正        | 直接提交，保持原判定结果           |
| 漏报    | AI 判为合规但实际违规             | 选择应被检测到但漏掉的违规词（支持多选）     |
| 误报    | AI 判为违规但实际合规             | 选择被误判的违规词（支持多选）        |

### 操作流程

1. 在「检测结果」页面找到目标记录，列表中可直接查看判定状态
2. 点击「人工判定」按钮打开判定弹窗
3. 弹窗中可查看 AI 原始判定结果（文本、违规状态、风险等级、命中违规词）
4. 弹窗中展示 **AI 分析说明**（analysis 字段，蓝色背景卡片）
5. 选择判定类型（AI 正确 / 漏报 / 误报）

#### 漏报/误报操作（二级联动违规词选择）

当选择「漏报」或「误报」时，需要通过二级联动选择关联的违规词：

1. **选择分类**：从违规词分类列表中选择分类（如政治敏感、色情低俗、暴力恐怖等）
2. **选择违规词**：系统自动显示该分类下的违规词列表，可多选
3. **填写备注**（可选）：添加人工备注说明
4. **提交**：判定结果保存到数据库，并触发 AI 蒸馏任务

### 详情查看

- 点击「详情」按钮可查看检测结果的完整信息，包括人工判定状态
- 已判定的记录在详情中可点击「查看判定详情」查看完整判定记录
- 详情弹窗底部也提供「人工判定」快捷入口

### 数据表结构（t_voice_human_judgment）

所有业务实体遵循芋道 BaseDO 规范：bigint 自增主键 + creator/create_time/updater/update_time/deleted 基础字段。

| 字段                                              | 类型           | 说明                                  |
| ----------------------------------------------- | ------------ | ----------------------------------- |
| id                                              | bigint       | 自增主键                                |
| detection_result_id                             | bigint       | 关联的检测结果 ID                          |
| original_text                                   | text         | 原始文本（冗余存储）                          |
| ai_judgment                                     | bit          | AI 原始判定（true=违规）                      |
| human_judgment_                                 | bit          | 人工判定（true=违规）                        |
| judgment_type                                   | int          | 0=AI正确, 1=漏报, 2=误报                  |
| wrong_sensitive_word                            | varchar(200) | 误判/漏报的敏感词（兼容旧数据）                   |
| sensitive_word_ids                              | varchar(500) | 选中的违规词 ID 列表（JSON 数组，支持多选）           |
| comment                                         | varchar(500) | 人工备注                                |
| creator/create_time/updater/update_time/deleted | -            | 芋道 BaseDO 基础字段                      |

---

## AI 自学习（蒸馏）功能

系统支持基于人工纠偏记录和当前违规词库，通过大模型自动提炼「审核补充规则」，注入到后续检测的提示词中，形成持续优化闭环。

### 工作流程

```
人工判定（提交判定结果）
      │
      ├─► 保存到 t_voice_human_judgment 表
      │     - 判定类型（AI正确/漏报/误报）
      │     - 选中的违规词ID列表
      │     - 备注说明
      │
      ▼
  触发 AI 蒸馏（Hangfire 后台任务）
      │
      ▼
  AiDistillationJob.DistillRuleAsync
      │
      ├─► 收集所有纠偏记录（误报、漏报）
      ├─► 获取当前违规词库（按分类分组）
      ├─► 连同上一版规则一起发送给大模型
      ├─► 大模型提炼出精简的审核补充规则
      └─► 保存新规则到数据库（版本递增）
      │
      ▼
  后续检测时自动注入最新学习规则到提示词
```

### 蒸馏规则生成逻辑

每次人工判定提交后，系统自动触发 Hangfire 后台任务进行 AI 蒸馏：

1. **收集纠偏记录**：查询所有未删除的人工判定记录（误报、漏报）
2. **获取违规词库**：查询所有启用的违规词，按分类分组
3. **构建蒸馏提示词**：
   - 当前违规词库（按分类展示）
   - 上一版学习规则
   - 所有纠偏记录（包含选中的违规词和备注）
4. **AI 提炼规则**：大模型总结误报/漏报模式，提炼语境规则
5. **保存新规则**：生成新版本规则存入 `t_voice_learned_rule` 表
6. **下次检测使用**：检测时自动读取最新版本规则作为提示词

### 关键设计

- **Hangfire 后台队列**：蒸馏任务通过 `ai-distillation` 队列异步执行，保证顺序处理，不阻塞主流程
- **全量蒸馏**：每次基于所有纠偏记录和当前违规词库进行蒸馏，确保规则完整性
- **版本管理**：规则按版本号递增保存，检测时自动使用最新版本
- **规则注入**：检测时从数据库读取最新的学习规则，自动附加到系统提示词中
- **纯文本输出**：AI 返回的规则为纯文本格式（不使用 Markdown），节省上下文空间
- **Hangfire 仪表盘**：可通过 `/hangfire` 路径查看后台蒸馏任务的执行状态（需登录）

---

## 自定义与扩展

### 修改大模型提示词

编辑 `OllamaService.cs` 中的 `_systemPrompt` 字段，可以自定义大模型的检测规则和输出格式。

### 调整蒸馏规则

编辑 `OllamaService.cs` 中的 `DistillJudgmentsToRuleAsync` 方法，可以修改 AI 蒸馏时的提示词和要求。

### 对接新的 ASR 服务

编辑 `AsrWebSocketService.cs`，修改 `ProcessMessage` 方法来适配不同的消息格式。

### 扩展数据库表

在 `Entities` 目录下添加新的实体类，然后在 `AppDbContext.cs` 的 `InitTables` 中注册即可自动创建表。

---

## 生产部署（可选）

### 使用 Docker 部署后端

```dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 5000

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY backend/ .
RUN dotnet restore "SmartSpeechAnalyzer.sln"
RUN dotnet build "src/SmartSpeechAnalyzer.Web.Entry/SmartSpeechAnalyzer.Web.Entry.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "src/SmartSpeechAnalyzer.Web.Entry/SmartSpeechAnalyzer.Web.Entry.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "SmartSpeechAnalyzer.Web.Entry.dll"]
```

### 前端生产构建

```bash
cd frontend
npm run build
```

构建产物在 `frontend/dist` 目录，可部署到 Nginx 等静态文件服务器。

---

## 常见问题

### Q: 首次启动报数据库连接错误？

A: 请检查 `appsettings.json` 中的数据库连接字符串是否正确，MySQL 服务是否已启动。

### Q: 调用检测接口报 Ollama 连接错误？

A: 请确保 Ollama 服务已启动，并且已经拉取了 qwen3.6 模型（`ollama pull qwen3.6`）。

### Q: 前端无法访问后端 API？

A: 请检查前端 `vite.config.js` 中的代理配置是否正确，后端服务是否正常启动。也可以在 `appsettings.json` 中调整 CORS 配置。

### Q: 如何修改默认管理员密码？

A: 用户认证使用芋道框架的 `system_users` 表，请通过芋道管理后台修改用户密码。

### Q: 检测响应速度慢？

A: 大模型检测速度取决于硬件性能，可以考虑：

- 使用更小的模型（如 qwen3.6:0.5b）
- 减少提示词长度
- 对文本进行分段批量检测

---

## 开源协议

本项目仅供学习和研究使用。

---

## 技术支持

如在使用过程中有任何问题，可通过以下方式获取帮助：

- 查看代码注释（所有代码均包含中文注释）
- 参考 Swagger API 文档
- 检查后端日志输出