imetting/project.md

# 项目设计文档：iMeeting (智慧会议)

## 1. 项目概述

**项目名称**: iMeeting (智慧会议)

**目标**: 为需要参加大量会议的专业人士、团队管理者和企业员工，提供一个高效、智能的会议记录与内容管理平台。通过AI技术，将非结构化的会议音视频内容，转化为易于检索、回顾和分发的结构化信息，从而节省用户整理会议纪要的时间，提升信息流转效率。

**核心价值**:
- **解放生产力**: 自动化的会议转录和摘要，让用户从繁琐的记录工作中解放出来。
- **信息不丢失**: 精准记录每一次会议的细节，确保关键信息和决策得到妥善保存。
- **高效回顾**: 通过时间轴、发言人和关键词，快速定位会议内容。
- **便捷分享**: 轻松分享会议纪要、材料和关键节点给相关人员。

## 2. 核心功能

- **会议管理**: 创建、编辑、删除会议，管理参会人员。
- **音频上传与处理**: 上传会议音频，触发后台异步任务进行语音转文字和说话人分离。
- **智能转录内容**: 提供带时间轴、可编辑、可播放的会议文稿。
- **发言人管理**: 自动识别发言人并支持用户自定义标签。
- **AI会议纪要**: 异步生成会议摘要，支持用户自定义提示词，并可多次生成。
- **用户与权限管理**: 支持管理员对用户进行增删改查和密码重置。

## 3. 技术栈

- **后端**: Python 3.9+, FastAPI
- **数据库**: MySQL 5.7+
- **缓存与任务队列**: Redis
- **AI服务**: 阿里云通义千问 (语音识别、LLM)
- **前端**: React (Vite) + Ant Design
- **部署**: Docker, Nginx

## 4. 异步任务设计

项目包含两大核心异步任务：**语音转录**和**AI总结**，均通过后台任务实现，以避免长时间阻塞API请求。

### 4.1. 语音转录 (Async Transcription)

- **触发**: 用户上传音频文件 (`POST /meetings/upload-audio`) 成功后自动触发。
- **实现**: `AsyncTranscriptionService` 调用阿里云 `Dashscope` 的 `paraformer-v2` 模型进行异步语音识别。
    1.  **启动任务**: 调用 `Transcription.async_call`，获取一个外部任务ID (`paraformer_task_id`)。
    2.  **创建内部任务**: 生成一个系统内部的业务ID (`business_task_id`)，并将两个ID的映射关系及任务元数据存入 `transcript_tasks` 表和Redis缓存。
    3.  **状态查询**: 前端通过 `GET /transcription/tasks/{task_id}/status` 或 `GET /meetings/{meeting_id}/transcription/status` 轮询任务状态。
    4.  **获取结果**: 服务端在查询状态时，若发现外部任务已完成，则通过 `Transcription.fetch` 获取结果URL，下载JSON格式的转录数据。
    5.  **数据入库**: 解析JSON数据，将包含发言人ID、时间戳和文本的 `transcript_segments` 存入数据库。
- **关键代码**: `backend/app/services/async_transcription_service.py`

### 4.2. AI总结 (Async LLM Summary)

- **触发**: 用户在会议详情页点击“生成纪要” (`POST /meetings/{meeting_id}/generate-summary-async`)。
- **实现**: `AsyncMeetingService` 利用后台任务执行器处理会议纪要异步任务。
    1.  **创建任务**: 生成一个任务ID (`task_id`)，并将任务元数据（会议ID、用户提示词、模型编码等）存入 `llm_tasks` 表和 Redis 缓存，立即返回任务ID给前端。
    2.  **后台执行**: `_process_task` 函数在后台运行，它按顺序执行：获取转录稿、构建消息、调用 LLM API、保存总结并导出 Markdown 文件。
    3.  **状态与进度更新**: 在执行的每个关键步骤，都会更新Redis中的任务状态和进度百分比 (`processing`, `10%`, `30%` ...)。
    4.  **状态查询**: 前端通过 `GET /llm-tasks/{task_id}/status` 轮询任务状态和进度。
    5.  **结果获取**: 任务完成后，状态变为 `completed`，`llm_tasks.result` 保存导出的 Markdown 文件路径，失败原因则记录在 `error_message` 中。
- **关键代码**: `backend/app/services/async_meeting_service.py`

### 4.3. 声纹采集
## 前端UI要素

### Dashboard 声纹状态显示
- **未采集**：显示"采集声纹"按钮（醒目样式，如橙色或主题色）
- **已采集**：显示波纹图标（可使用音频波形SVG或动画效果）

### 声纹采集对话框
- 标题："声纹采集"
- 朗读文本显示区域（滚动文本）
- 录制按钮："开始录制" / "正在录制..."
- 进度显示：
  - 圆形进度环（推荐）
  - 或倒计时文字："10s" → "9s" → ... → "0s"
- 提示信息："请在安静环境下，用自然语速朗读上述文字"
- 操作按钮："取消" / "重新录制"

### 音频波形图标示例
可以使用类似这样的SVG图标：
```html
<svg viewBox="0 0 24 24" class="voice-wave-icon">
  <path d="M12 2v20M8 6v12M16 6v12M4 9v6M20 9v6" />
</svg>
```
## 文件存储结构

```
uploads/
└── voiceprint/
    └── {user_id}/
        └── timestamp.wav  # 采集时间为文件名。
```

**存储说明：**
- 每个用户只保留一个声纹文件
- 用户目录在首次采集时创建

## 声纹朗读模板配置

朗读模板配置在 `config/system_config.json` 中：

```json
{
  "voiceprint": {
    "template_text": "我正在进行声纹采集，这段语音将用于身份识别和验证。声纹技术能够准确识别每个人独特的声音特征，就像指纹一样独一无二。请保持自然的语速和音量进行朗读。",
    "duration_seconds": 10,
    "sample_rate": 16000,
    "channels": 1
  }
}
```

**配置说明：**
- `template_text`: 用户朗读的标准文本
- `duration_seconds`: 建议录制时长（秒）
- `sample_rate`: 音频采样率（Hz）
- `channels`: 声道数（1=单声道）

## 5. API 接口文档

### 5.1. 认证接口 (`/auth`)

- `POST /auth/login`: 用户登录。
    - **Request**: `LoginRequest` (username, password)
    - **Response**: `LoginResponse` (user_info, token)
- `POST /auth/logout`: 用户登出，使当前Token失效。
- `POST /auth/logout-all`: 登出该用户的所有设备。
- `GET /auth/me`: 获取当前登录用户的信息。
- `POST /auth/refresh`: 刷新当前用户的Token。

### 5.2. 用户管理接口 (`/users`)

> **权限**: 以下接口均需要管理员权限 (role_id=1)。

- `GET /roles`: 获取所有角色列表。
- `POST /users`: 创建新用户。
    - **Request**: `CreateUserRequest`
- `GET /users`: 分页获取用户列表。
- `GET /users/{user_id}`: 获取指定用户的详细信息。
- `PUT /users/{user_id}`: 更新用户信息。
    - **Request**: `UpdateUserRequest`
- `DELETE /users/{user_id}`: 删除用户。
- `POST /users/{user_id}/reset-password`: 重置用户密码为默认值。
- `PUT /users/{user_id}/password`: 修改用户密码 (管理员无需旧密码)。

### 5.3. 会议与转录接口 (`/meetings`)

- `GET /meetings`: 获取会议列表，可通过 `user_id` 过滤。
- `POST /meetings`: 创建新会议。
    - **Request**: `CreateMeetingRequest`
- `GET /meetings/{meeting_id}`: 获取单个会议的详细信息，包含转录状态。
- `PUT /meetings/{meeting_id}`: 更新会议信息（标题、时间、参会人等）。
- `DELETE /meetings/{meeting_id}`: 删除会议及所有相关数据。
- `GET /meetings/{meeting_id}/edit`: 获取用于编辑页面的会议信息。

#### 音频与转录

- `POST /meetings/upload-audio`: 上传音频文件，并自动开始异步转录。
    - **Form Data**: `audio_file`, `meeting_id`, `force_replace`
- `GET /meetings/{meeting_id}/audio`: 获取会议关联的音频文件信息。
- `GET /meetings/{meeting_id}/transcript`: 获取会议的完整转录稿 (`TranscriptSegment` 列表)。
- `POST /meetings/{meeting_id}/transcription/start`: 手动触发指定会议的转录任务。
- `GET /meetings/{meeting_id}/transcription/status`: 获取会议最新的转录任务状态。
- `GET /transcription/tasks/{task_id}/status`: 根据任务ID获取转录状态。

#### 内容编辑

- `PUT /meetings/{meeting_id}/speaker-tags`: 更新单个发言人的标签。
- `PUT /meetings/{meeting_id}/speaker-tags/batch`: 批量更新多个发言人的标签。
- `PUT /meetings/{meeting_id}/transcript/batch`: 批量更新转录内容文本。

#### AI 总结

- `POST /meetings/{meeting_id}/generate-summary-async`: **异步**生成会议纪要。
    - **Request**: `GenerateSummaryRequest` (user_prompt)
    - **Response**: 返回一个任务ID，用于轮询状态。
- `GET /llm-tasks/{task_id}/status`: 获取AI总结任务的状态和进度。
- `GET /meetings/{meeting_id}/llm-tasks`: 获取指定会议的所有AI总结任务历史。
- `GET /meetings/{meeting_id}/latest-llm-task`: 获取会议最新的AI总结任务状态（此方法被替代）。

#### 其他

- `POST /meetings/{meeting_id}/upload-image`: 上传图片，用于在Markdown纪要中引用。

### 声纹采集功能 API

### 1. 获取用户声纹状态
- **GET** `/voiceprint/{user_id}`
- **描述**：获取指定用户的声纹采集状态
- **权限**：需要登录，只能查询自己的声纹状态（管理员可查询所有）

### 2. 获取朗读模板
- **GET** `/voiceprint/template`
- **描述**：获取声纹采集的标准朗读文本
- **权限**：需要登录

### 3. 上传声纹音频（同步处理）
- **POST** `/voiceprint/{user_id}`
- **描述**：上传声纹音频文件，同步处理并返回结果
- **权限**：需要登录，只能上传自己的声纹（管理员可操作所有）

### 4. 删除/重新采集声纹
- **DELETE** `/voiceprint/{user_id}`
- **描述**：删除用户的声纹数据，允许重新采集
- **权限**：需要登录，只能删除自己的声纹（管理员可操作所有）


## 6. 数据库设计

详细的数据库表结构、字段和关系图已被迁移到独立的文档中。

**[-> 点击查看数据库设计文档](./database.md)**

## 7. 未来展望

- **实时转录**: 支持对正在进行的会议进行实时语音转文字。
- **日历集成**: 与 Google Calendar, Outlook Calendar 集成，自动导入会议安排。
- **行动项提取**: AI自动识别会议中的待办事项 (Action Items)。
- **跨会议搜索**: 对用户的所有会议内容进行全文语义搜索。
- **移动端应用**: 开发 iOS 和 Android 版本的原生应用。