# WebAPP

**Repository Path**: AI_Coding_fan/web

## Basic Information

- **Project Name**: WebAPP
- **Description**: 智能文档管理与语音朗读平台：上传 PDF/DOCX/TXT 文档 → 自动提取文本 → 一键转为高质量语音 → 在线播放或下载 MP3。
- **Primary Language**: HTML
- **License**: Not specified
- **Default Branch**: Web
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-31
- **Last Updated**: 2026-05-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📄 DocVoice · 文档语音助手

## 项目名称
**DocVoice** — 智能文档管理与语音合成平台

## 一句话介绍
上传 PDF/DOCX/TXT 文档 → 自动提取文本 → 一键转为高质量语音 → 在线播放或下载 MP3。

---

## 目标用户
- **学生和学者**：将课程资料、论文转为语音，通勤时"听"资料
- **职场人士**：将会议纪要、工作报告转为语音，高效回听
- **视障/阅读障碍用户**：通过语音获取文档内容
- **多任务场景用户**：解放双眼，边做其他事边听文档

---

## 痛点来源
在日常学习和工作中，我们经常面临以下问题：

1. **阅读效率受限**：长篇文档需要大量时间逐字阅读，无法利用碎片时间
2. **文档管理混乱**：本地文件散落各处，查找和回顾困难
3. **语音回听低效**：传统录音文件回听耗时，无法快速获取关键信息
4. **格式兼容问题**：不同格式文档（PDF/DOCX/TXT）需要不同软件打开

---

## 核心创意
将**文档解析**与**AI语音合成**相结合，实现"文档上传 → 自动解析 → 语音输出"的闭环体验：

```
用户上传文档 ──► 系统自动提取文本 ──► 一键生成语音 ──► 在线播放/下载 MP3
     │                  │                      │
  PDF/DOCX/TXT     PyPDF2/docx         edge-tts (微软晓晓)
```

1. 用户上传任意格式文档（PDF / DOCX / TXT）
2. 系统自动解析文档内容，提取纯文本
3. 调用微软 Edge TTS 服务将文本转为自然语音（MP3）
4. 支持在线播放和一键下载，方便移动场景使用
5. 用户注册登录系统，个人文档和语音独立管理

---

## 主要功能

### 基础功能
| # | 功能 | 说明 |
|---|------|------|
| 1 | **文档上传** | 支持 PDF、DOCX、TXT 三种格式，限制 10MB |
| 2 | **自动解析** | 上传后自动提取文本内容，多编码兼容（UTF-8/GBK/GB18030） |
| 3 | **语音合成** | 基于微软 Edge TTS，使用自然语音"微软晓晓"（zh-CN-XiaoxiaoNeural） |
| 4 | **在线播放** | 语音中心页面内置 HTML5 音频播放器 |
| 5 | **MP3 下载** | 一键下载生成的 MP3 文件到本地 |
| 6 | **文档管理** | 查看文档列表、详情，支持删除操作 |
| 7 | **文本预览** | 文档详情页展示提取的完整文本内容 |

### 用户系统功能
| # | 功能 | 说明 |
|---|------|------|
| 8 | **用户注册** | 用户名 + 邮箱 + 密码注册 |
| 9 | **用户登录** | Django 内置认证系统 |
| 10 | **数据隔离** | 每个用户只能查看和管理自己的文档和语音 |
| 11 | **个人中心** | 查看个人信息 |

---

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| **后端框架** | Django 6.0.5 | Python Web 框架 |
| **数据库** | SQLite | 轻量级数据库（可扩展至 PostgreSQL/MySQL） |
| **前端** | HTML5 + CSS3 + Bootstrap 5.3 | 响应式 UI，蓝色主题 |
| **文档解析** | PyPDF2 + python-docx | PDF/DOCX 文本提取 |
| **语音合成** | edge-tts 7.2.8 | 微软 Edge TTS（异步，WebSocket） |
| **认证系统** | Django Auth | 内置用户认证和会话管理 |
| **模板引擎** | Django Templates | 模板继承和组件复用 |

---

## 项目结构

```
tts_project/
├── manage.py                    # Django 管理入口
├── db.sqlite3                   # SQLite 数据库
├── README.md                    # 项目文档（本文件）
│
├── tts_project/                 # 项目配置包
│   ├── settings.py              # 全局配置（数据库/静态文件/登录等）
│   ├── urls.py                  # 根路由分发
│   ├── wsgi.py                  # WSGI 入口
│   └── asgi.py                  # ASGI 入口
│
├── users/                       # 用户模块 App
│   ├── models.py                # 使用 Django 内置 User 模型
│   ├── views.py                 # 注册 / 登录 / 登出 / 个人中心
│   ├── urls.py                  # 用户路由 (app_name='users')
│   ├── forms.py                 # RegisterForm（注册表单验证）
│   └── templates/users/         # 用户相关模板
│       ├── login.html
│       ├── register.html
│       └── profile.html
│
├── documents/                   # 文档模块 App
│   ├── models.py                # Document 模型
│   ├── views.py                 # 上传 / 列表 / 详情 / 删除
│   ├── urls.py                  # 文档路由 (app_name='documents')
│   ├── forms.py                 # DocumentUploadForm
│   ├── utils.py                 # 文本提取 + TTS 引擎（核心）
│   └── templates/documents/     # 文档相关模板
│       ├── upload.html
│       ├── document_list.html
│       ├── document_detail.html
│       └── delate_confirm.html
│
├── audios/                      # 音频模块 App
│   ├── models.py                # Audio 模型
│   ├── views.py                 # 生成 / 详情 / 下载 / 删除
│   ├── urls.py                  # 音频路由 (app_name='audios')
│   └── templates/audios/        # 音频相关模板
│       ├── audio_home.html
│       ├── audio_detail.html
│       └── audio_delete_confirm.html
│
├── templates/                   # 全局模板
│   ├── base.html                # 基础布局（导航栏 + 消息提示 + 页脚）
│   ├── home.html                # 首页（功能展示 + CTA）
│   └── registration/            # Django Auth 内置模板
│       └── login.html
│
├── static/                      # 静态资源（CSS/JS/图片）
│   ├── css/
│   ├── js/
│   └── img/
│
└── media/                       # 用户上传的文件和生成的音频
    ├── documents/               # 上传的文档文件
    └── audios/                  # 生成的 MP3 文件
```

---

## 数据模型

### Document（文档）

| 字段 | 类型 | 说明 |
|------|------|------|
| `user` | ForeignKey(User) | 上传用户 |
| `title` | CharField(255) | 文档标题 |
| `file` | FileField | 上传的文件 |
| `file_type` | CharField(20) | 文件类型（pdf/docx/txt） |
| `extracted_text` | TextField | 提取的文本内容 |
| `status` | CharField | 状态：uploaded / parsed / failed |
| `uploaded_at` | DateTimeField | 上传时间 |

### Audio（音频）

| 字段 | 类型 | 说明 |
|------|------|------|
| `user` | ForeignKey(User) | 所属用户 |
| `document` | OneToOne(Document) | 关联文档（一对一） |
| `audio_file` | FileField | MP3 文件 |
| `lang` | CharField(10) | 语言（默认 zh-cn） |
| `duration` | FloatField | 时长（秒） |
| `status` | CharField | 状态：generating / completed / failed |
| `created_at` | DateTimeField | 创建时间 |

### 模型关系

```
User (Django 内置)
  │
  ├── documents (ForeignKey) ──► Document
  │                                │
  │                                └── audio (OneToOne) ──► Audio
  │                                                             ├── audio_file (MP3)
  │                                                             ├── lang
  │                                                             ├── duration
  │                                                             └── status
  │
  └── audios (ForeignKey) ──► Audio
```

---

## URL 路由一览

| 路径 | 视图 | 说明 | 需要登录 |
|------|------|------|----------|
| `/` | home | 首页（功能展示） | 否 |
| `/users/register/` | register_view | 用户注册 | 否 |
| `/users/login/` | login_view | 用户登录 | 否 |
| `/users/logout/` | logout_view | 用户登出 | 否 |
| `/users/profile/` | profile_view | 个人中心 | 是 |
| `/documents/upload/` | upload_document | 上传文档 | 是 |
| `/documents/list/` | document_list | 文档列表 | 是 |
| `/documents/detail/<id>/` | document_detail | 文档详情 | 是 |
| `/documents/delete/<id>/` | delete_document | 删除文档 | 是 |
| `/audios/` | audio_home | 语音中心 | 是 |
| `/audios/generate/<doc_id>/` | generate_audio | 生成语音 | 是 |
| `/audios/detail/<id>/` | audio_detail | 音频详情 | 是 |
| `/audios/download/<id>/` | download_audio | 下载 MP3 | 是 |
| `/audios/delete/<id>/` | delete_audio | 删除音频 | 是 |

---

## 核心业务流程

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ 用户注册  │───►│ 用户登录  │───►│ 上传文档  │───►│ 自动解析  │───►│ 文档列表  │
│ /register │    │ /login   │    │ /upload  │    │ PDF/DOCX │    │ /list    │
└──────────┘    └──────────┘    └──────────┘    │   /TXT   │    └──────────┘
                                                └────┬─────┘
                                                     │
                                                     ▼
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ 下载MP3  │◄───│ 语音中心  │◄───│ 生成语音  │◄───│ 文档详情  │
│/download │    │ /audios  │    │/generate │    │ /detail  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
                                     │
                                     ▼
                            ┌─────────────────┐
                            │   edge-tts      │
                            │                 │
                            │ 文本 ──► MP3    │
                            │                 │
                            │ WebSocket ──►   │
                            │ speech.platform │
                            │ .bing.com       │
                            │                 │
                            │ 语音: 微软晓晓   │
                            │ zh-CN-Xiaoxiao  │
                            │ Neural (女声)    │
                            └─────────────────┘
```

---

## 运行说明

### 环境要求
- Python 3.8+
- 现代浏览器（Chrome / Edge 推荐）
- 网络连接（TTS 功能需要访问微软服务器）

### 安装步骤

```bash
# 1. 克隆项目或进入项目目录
cd tts_project

# 2. 创建并激活虚拟环境（推荐）
python -m venv .venv
.venv\Scripts\activate   # Windows
# source .venv/bin/activate  # Linux/Mac

# 3. 安装依赖
pip install django edge-tts PyPDF2 python-docx

# 4. 初始化数据库（首次运行）
python manage.py migrate

# 5. 创建超级用户（可选，用于访问 Django Admin）
python manage.py createsuperuser

# 6. 启动开发服务器
python manage.py runserver

# 7. 打开浏览器访问
# http://127.0.0.1:8000
```

### 使用说明

#### 首次使用
1. 访问 http://127.0.0.1:8000
2. 点击"登录后上传"或导航栏"登录"
3. 点击注册链接创建新账户
4. 登录后即可使用全部功能

#### 上传文档
1. 点击"上传文档"按钮
2. 选择 PDF、DOCX 或 TXT 文件（不超过 10MB）
3. 可选填写文档标题（不填则自动使用文件名）
4. 点击上传，系统自动解析文本

#### 生成语音
1. 在文档详情页点击"生成语音"
2. 系统自动调用微软 TTS 服务合成语音
3. 等待几秒后（取决于文本长度），语音生成完成
4. 可在当前页面在线播放，或跳转语音中心管理

#### 管理语音
1. 点击导航栏"语音中心"
2. 查看所有已生成的语音，支持在线播放
3. 点击"下载"保存 MP3 到本地
4. 点击"详情"查看更多信息
5. 点击"重新生成"可重新合成语音

---

## 当前不足与后续改进方向

### 当前不足
1. **依赖外部 TTS 服务**：需要网络连接才能生成语音，不支持离线使用
2. **单一语音选择**：目前仅支持微软晓晓（女声），未提供语音切换界面
3. **无文本分段**：长文档一次性合成，可能等待时间较长
4. **移动端适配有限**：主要针对桌面浏览器优化
5. **无 API 文档**：缺少接口文档，不便于二次开发

### 后续改进方向
1. **多语音选择**：添加语音切换功能，支持微软晓晓/云希/晓伊等多种语音
2. **离线 TTS 支持**：集成 pyttsx3 作为离线备选方案
3. **文本分段合成**：长文本自动分段，并行合成，提升速度
4. **AI 摘要功能**：接入大模型 API，自动生成文档摘要并转为语音
5. **批量操作**：支持批量上传和批量生成语音
6. **导出格式扩展**：支持导出为字幕文件（SRT）、音频笔记等格式
7. **移动端优化**：开发 PWA 或小程序版本
8. **生产环境部署**：迁移至 PostgreSQL，使用 Gunicorn + Nginx 部署

---

## 开发迭代过程

### 第一次迭代：基础框架搭建
- 搭建 Django 项目基础框架
- 创建 users / documents / audios 三个 App
- 完成基础页面 UI 设计（Bootstrap 5）

### 第二次迭代：文档上传与解析
- 实现文档上传功能（PDF / DOCX / TXT）
- 集成 PyPDF2 和 python-docx 进行文本提取
- 完成文档列表和详情页面

### 第三次迭代：语音合成集成
- 集成 gTTS（Google TTS）实现文本转语音
- 实现语音生成、播放和下载功能
- 完成语音中心页面

### 第四次迭代：TTS 引擎升级
- 发现 gTTS 在国内网络环境下不可用
- 替换为 edge-tts（微软 Edge TTS），国内可正常访问
- 解决异步兼容问题，封装同步调用接口

### 第五次迭代：用户系统完善
- 完善用户注册、登录、登出流程
- 实现数据隔离（每个用户独立管理文档和语音）
- 添加个人中心页面

### 第六次迭代：优化与完善
- 优化错误处理和用户反馈
- 清理冗余模板文件
- 修复 Document 模型字段引用错误
- 完善项目文档

---

## 技术架构

```
┌─────────────────────────────────────────────────────────┐
│                      前端展示层                           │
│  Bootstrap 5 + HTML5 + Django Templates                 │
│  base.html → home.html / document_*.html / audio_*.html  │
└────────────────────────┬────────────────────────────────┘
                         │ HTTP Request/Response
┌────────────────────────▼────────────────────────────────┐
│                      Django 后端                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │  users/  │  │documents/│  │ audios/  │              │
│  │  认证模块 │  │  文档模块 │  │  语音模块 │              │
│  └──────────┘  └────┬─────┘  └────┬─────┘              │
│                     │             │                     │
│              ┌──────▼─────┐       │                     │
│              │  utils.py  │       │                     │
│              │ ┌────────┐ │       │                     │
│              │ │文本提取 │ │       │                     │
│              │ │ PyPDF2 │ │       │                     │
│              │ │ docx   │ │       │                     │
│              │ ├────────┤ │       │                     │
│              │ │ TTS    │◄┼───────┘                     │
│              │ │edge-tts│ │                             │
│              │ └────────┘ │                             │
│              └────────────┘                             │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│                      数据存储层                           │
│  ┌──────────────┐     ┌──────────────────┐              │
│  │   SQLite     │     │  media/ 文件存储  │              │
│  │  db.sqlite3  │     │  documents/      │              │
│  │              │     │  audios/         │              │
│  └──────────────┘     └──────────────────┘              │
└─────────────────────────────────────────────────────────┘
```

---

## 依赖清单

| 包名 | 版本 | 用途 |
|------|------|------|
| Django | 6.0.5 | Web 框架 |
| edge-tts | 7.2.8 | 微软 Edge TTS 语音合成 |
| PyPDF2 | latest | PDF 文本提取 |
| python-docx | latest | DOCX 文本提取 |
| aiohttp | >=3.8.0 | edge-tts 异步 HTTP 依赖 |
| certifi | >=2023.11.17 | SSL 证书验证 |

---

## License
MIT License

---

> 📄 **DocVoice** — 让每份文档都能"说话"