5314077f3b
- 更新根目录README.md，完善项目说明 - 更新api/README.md，添加API文档说明 - 新增api/docs/README.md文档 - 新增app-android/README.md文档 - 新增app-android/doc/文档目录
239 lines
7.6 KiB
Markdown
239 lines
7.6 KiB
Markdown
# 往事拾遗 (Life Echo)
|
||
|
||
> 一个基于实时 WebSocket 长连接的智能语音对话回忆录生成系统
|
||
|
||
## 📖 项目简介
|
||
|
||
**往事拾遗 (Life Echo)** 是一个创新的回忆录生成平台，通过 AI 智能对话引导用户回顾人生历程，并将口语对话自动整理为结构化的回忆录章节，最终生成精美的 PDF 电子书。
|
||
|
||
### 核心功能
|
||
|
||
- 🎙️ **实时语音对话** - 基于 WebSocket 的实时双向语音交互
|
||
- 🤖 **智能访谈引导** - AI Agent 根据传记结构动态引导用户讲述人生故事
|
||
- 📝 **自动内容整理** - 将口语对话自动整理为优雅的书面语章节
|
||
- 📚 **结构化回忆录** - 基于传记结构自动组织章节内容
|
||
- 📄 **PDF 导出** - 生成精美的回忆录 PDF 文档
|
||
- 💾 **本地数据存储** - Android 端使用 Room 数据库实现离线数据管理
|
||
|
||
## 🏗️ 项目结构
|
||
|
||
```
|
||
life-echo/
|
||
├── api/ # 后端服务（FastAPI）
|
||
│ ├── agents/ # LangChain Agent（对话引导、记忆整理）
|
||
│ ├── database/ # 数据库模型和连接（PostgreSQL）
|
||
│ ├── routers/ # API 路由（REST + WebSocket）
|
||
│ ├── services/ # 业务服务（ASR、TTS、PDF、LLM）
|
||
│ ├── tasks/ # Celery 后台任务
|
||
│ ├── docs/ # API 详细文档
|
||
│ ├── main.py # FastAPI 应用入口
|
||
│ └── README.md # API 服务文档
|
||
│
|
||
├── app-android/ # Android 应用
|
||
│ └── app/
|
||
│ └── src/main/java/com/huaga/life_echo/
|
||
│ ├── data/ # 数据层（Room、Repository）
|
||
│ ├── network/ # 网络层（WebSocket、REST API）
|
||
│ ├── ui/ # UI 层（Jetpack Compose）
|
||
│ ├── feature/ # 功能模块（语音录制等）
|
||
│ └── navigation/ # 导航管理
|
||
│ └── README.md # Android 应用文档
|
||
│
|
||
└── docs/ # 项目文档
|
||
├── 开发计划.md # 开发计划与任务分解
|
||
├── 数据库设计.md # 数据库设计文档
|
||
├── AGENT.md # Agent 设计文档
|
||
└── v1_features_*.md # 功能需求文档
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- **后端开发**：
|
||
- Python 3.10+
|
||
- Docker & Docker Compose（用于 PostgreSQL、Redis）
|
||
- LLM API Key（DeepSeek 或兼容 OpenAI 的服务）
|
||
|
||
- **Android 开发**：
|
||
- Android Studio Hedgehog | 2023.1.1+
|
||
- JDK 11+
|
||
- Android SDK（API 24+）
|
||
|
||
### 后端服务启动
|
||
|
||
详细步骤请参考 [api/README.md](api/README.md)
|
||
|
||
```bash
|
||
# 1. 进入 API 目录
|
||
cd api
|
||
|
||
# 2. 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 3. 配置环境变量（创建 .env 文件）
|
||
# 参考 api/README.md 中的环境变量配置说明
|
||
|
||
# 4. 启动 PostgreSQL 和 Redis
|
||
docker-compose -f docker-compose.dev.yml up -d
|
||
|
||
# 5. 启动 FastAPI 服务
|
||
uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
||
|
||
# 6. 启动 Celery Worker（另一个终端）
|
||
celery -A tasks.celery_app worker --loglevel=info --pool=solo
|
||
```
|
||
|
||
### Android 应用启动
|
||
|
||
详细步骤请参考 [app-android/README.md](app-android/README.md)
|
||
|
||
```bash
|
||
# 1. 使用 Android Studio 打开项目
|
||
# File -> Open -> 选择 app-android 目录
|
||
|
||
# 2. 同步 Gradle 依赖
|
||
# Android Studio 会自动同步，或点击 Sync Now
|
||
|
||
# 3. 配置 API 地址（开发环境）
|
||
# 编辑 app/src/main/java/com/huaga/life_echo/config/AppConfig.kt
|
||
# 修改 BASE_URL 和 WS_BASE_URL
|
||
|
||
# 4. 运行应用
|
||
# 点击 Run 按钮或使用快捷键 Shift+F10
|
||
```
|
||
|
||
## 🛠️ 技术栈
|
||
|
||
### 后端技术栈
|
||
|
||
| 技术 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| FastAPI | 0.115.0 | Web 框架，REST API 和 WebSocket |
|
||
| LangChain | 0.3.7 | AI Agent 框架（对话引导、内容整理） |
|
||
| PostgreSQL | 17 | 关系型数据库 |
|
||
| SQLAlchemy | 2.0.36 | ORM 框架 |
|
||
| Redis | 7 | 缓存和会话存储 |
|
||
| Celery | 5.3 | 异步任务队列 |
|
||
| OpenAI API | - | ASR（语音识别）、TTS（语音合成） |
|
||
| DeepSeek API | - | LLM（大语言模型） |
|
||
| ReportLab + WeasyPrint | - | PDF 生成 |
|
||
|
||
### Android 技术栈
|
||
|
||
| 技术 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Kotlin | 1.9+ | 编程语言 |
|
||
| Jetpack Compose | - | 声明式 UI 框架 |
|
||
| Ktor | - | HTTP 客户端和 WebSocket |
|
||
| Room | - | 本地数据库（SQLite） |
|
||
| Coroutines + Flow | - | 异步编程和响应式数据流 |
|
||
| DataStore | - | 键值对存储（Token 管理） |
|
||
| Coil | - | 图片加载库 |
|
||
|
||
## 📚 文档导航
|
||
|
||
### 项目文档
|
||
|
||
- [开发计划](docs/开发计划.md) - 项目开发计划与任务分解
|
||
- [数据库设计](docs/数据库设计.md) - 数据库表结构设计
|
||
- [Agent 设计](docs/AGENT.md) - AI Agent 工作流程设计
|
||
|
||
### API 文档
|
||
|
||
- [API README](api/README.md) - API 服务完整文档
|
||
- [本地开发环境配置](api/docs/本地开发环境配置.md) - 开发环境搭建指南
|
||
- [WebSocket 快速测试指南](api/docs/WebSocket快速测试指南.md) - WebSocket 测试文档
|
||
- [WebSocket 测试文档](api/docs/WebSocket测试文档.md) - WebSocket 详细测试说明
|
||
|
||
### Android 文档
|
||
|
||
- [Android README](app-android/README.md) - Android 应用完整文档
|
||
|
||
## 🔐 认证系统
|
||
|
||
系统使用 JWT（JSON Web Token）进行认证，采用访问令牌（Access Token）+ 刷新令牌（Refresh Token）机制：
|
||
|
||
- **访问令牌**：有效期 2 小时，用于 API 请求认证
|
||
- **刷新令牌**：有效期 30 天，用于刷新访问令牌
|
||
|
||
详细认证流程请参考 [api/README.md#认证系统](api/README.md#认证系统)
|
||
|
||
## 🌟 功能特性
|
||
|
||
### 已实现功能
|
||
|
||
- ✅ 用户注册与登录（手机号 + 密码）
|
||
- ✅ JWT 认证系统（访问令牌 + 刷新令牌）
|
||
- ✅ 实时 WebSocket 语音对话
|
||
- ✅ AI 智能对话引导（基于传记结构）
|
||
- ✅ 语音识别（ASR）和语音合成（TTS）
|
||
- ✅ 对话内容自动整理为章节
|
||
- ✅ 回忆录章节管理
|
||
- ✅ PDF 导出功能
|
||
- ✅ Android 本地数据存储（Room）
|
||
- ✅ 离线数据同步
|
||
- ✅ 用户套餐与订单管理
|
||
- ✅ 常见问题（FAQ）和反馈系统
|
||
|
||
### 开发中功能
|
||
|
||
- 🔄 更多传记结构模板
|
||
- 🔄 图片上传与管理
|
||
- 🔄 章节编辑功能
|
||
- 🔄 多语言支持
|
||
|
||
## 📝 开发指南
|
||
|
||
### 添加新的 API 路由
|
||
|
||
1. 在 `api/routers/` 目录创建新的路由文件
|
||
2. 定义路由函数
|
||
3. 在 `api/main.py` 中注册路由
|
||
|
||
### 添加新的数据库模型
|
||
|
||
1. 在 `api/database/models.py` 中定义模型类
|
||
2. 继承 `Base`
|
||
3. 运行数据库迁移
|
||
|
||
### 添加新的 Android 功能
|
||
|
||
1. 在 `app-android/app/src/main/java/com/huaga/life_echo/` 下创建功能模块
|
||
2. 遵循 MVVM 架构模式
|
||
3. 使用 Compose 构建 UI
|
||
|
||
## 🔒 安全注意事项
|
||
|
||
1. **环境变量安全**：确保 `.env` 文件不被提交到版本控制
|
||
2. **SECRET_KEY 安全**：生产环境必须使用强随机字符串
|
||
3. **CORS 配置**：生产环境应限制为特定域名
|
||
4. **API Key 安全**：妥善保管 LLM API Key
|
||
5. **密码安全**：密码使用 bcrypt 哈希存储
|
||
|
||
详细安全建议请参考 [api/README.md#安全注意事项](api/README.md#安全注意事项)
|
||
|
||
## 🤝 贡献指南
|
||
|
||
1. Fork 本项目
|
||
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 开启 Pull Request
|
||
|
||
## 📄 许可证
|
||
|
||
MIT License
|
||
|
||
## 📮 联系方式
|
||
|
||
如有问题或建议，请通过以下方式联系：
|
||
|
||
- 提交 Issue
|
||
- 发送反馈（应用内反馈功能）
|
||
|
||
---
|
||
|
||
**往事拾遗** - 让每一段人生故事都被温柔记录 ✨
|
||
|