53e0065e3e
配置 SSOT（TOML + .env） 统一错误契约 Auth 与事务边界 Redis / Celery 可靠性:业务 Redis（DB/0）与 Celery broker/backend（DB/1）显式拆分；连接池、sync client 可观测性（OpenTelemetry + LGTM）
175 lines
6.3 KiB
Markdown
175 lines
6.3 KiB
Markdown
# 岁月留书 (Life Echo)
|
||
|
||
> 一个基于实时 WebSocket 长连接的智能语音对话回忆录生成系统
|
||
|
||
## 📖 项目简介
|
||
|
||
**岁月留书 (Life Echo)** 是一个创新的回忆录生成平台，通过 AI 智能对话引导用户回顾人生历程，并将口语对话自动整理为结构化的回忆录章节，最终生成精美的 PDF 电子书。
|
||
|
||
后端侧：会话轮次以 DB `conversation_messages` 为真源、Redis 为缓存；实时对话编排统一走 `ChatOrchestrator`；图像任务为 `generate_story_image`（正文）与 `generate_chapter_cover`（章节封面）。详见 [api/README.md](api/README.md)。
|
||
|
||
### 核心功能
|
||
|
||
- 🎙️ **实时语音对话** - 基于 WebSocket 的实时双向语音交互
|
||
- 🤖 **智能访谈引导** - AI Agent 根据传记结构动态引导用户讲述人生故事
|
||
- 📝 **自动内容整理** - 将口语对话自动整理为优雅的书面语章节
|
||
- 📚 **结构化回忆录** - 基于传记结构自动组织章节内容
|
||
- 📄 **PDF 导出** - 生成精美的回忆录 PDF 文档
|
||
- 💾 **本地数据存储** - Android 端使用 Room 数据库实现离线数据管理
|
||
|
||
## 🏗️ 项目结构
|
||
|
||
|
||
```
|
||
life-echo/
|
||
├── api/ # 后端（FastAPI，uv + Alembic）
|
||
│ ├── app/
|
||
│ │ ├── main.py # 对外 API 入口
|
||
│ │ ├── internal_main.py # 内部评测 API 入口
|
||
│ │ ├── core/ # 配置、DB、日志、Redis、LLM 调用等
|
||
│ │ ├── ports/ # 供应商能力协议（ASR/TTS/LLM/…）
|
||
│ │ ├── adapters/ # ports 的具体实现（腾讯、OpenAI、Whisper 等）
|
||
│ │ ├── agents/ # 对话与回忆录编排 Agent
|
||
│ │ ├── features/ # 按域拆分：auth、conversation、memoir、memory、evaluation…
|
||
│ │ └── tasks/ # Celery 任务入口
|
||
│ ├── alembic/ # 数据库迁移
|
||
│ ├── tests/ # pytest
|
||
│ ├── main.py # uvicorn 兼容入口
|
||
│ └── README.md
|
||
├── app-expo/ # 移动端（Expo Router + React Native）
|
||
├── app-eval-web/ # 内部评测 Web（Vite，仅本机开发，不打包进预发/生产 Docker）
|
||
└── docs/ # 设计与运维文档
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- **后端开发**：
|
||
- Python 3.10+
|
||
- Docker & Docker Compose（用于 PostgreSQL、Redis）
|
||
- LLM API Key（DeepSeek 或兼容 OpenAI 的服务）
|
||
|
||
### 后端服务启动
|
||
|
||
详细步骤请参考 [api/README.md](api/README.md)
|
||
|
||
```bash
|
||
# 1. 进入 API 目录
|
||
cd api
|
||
|
||
# 2. 安装依赖
|
||
uv sync --dev
|
||
|
||
# 3. 配置环境变量（创建 .env 文件）
|
||
# 参考 api/README.md 中的环境变量配置说明
|
||
|
||
# 4. 启动 PostgreSQL 和 Redis
|
||
docker compose -f docker-compose.dev.yml up -d
|
||
|
||
# 5. 数据库迁移
|
||
# uv run alembic upgrade head
|
||
|
||
# 6. 启动 FastAPI 服务
|
||
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
||
|
||
# 7. 启动 Celery Worker（另一个终端）
|
||
uv run celery -A tasks.celery_app worker --loglevel=info --pool=solo
|
||
```
|
||
|
||
数据库 schema 迁移的正式标准是 Alembic；当前仓库已引入脚手架，`api/migrations/*.sql` 保留为历史/一次性 SQL 脚本，详情见 `api/README.md`。
|
||
|
||
### 后端开发工具链
|
||
|
||
后端开发环境通过 `uv sync --dev` 安装开发工具，当前约定如下：
|
||
|
||
- `ruff`：负责 `lint` + `format`
|
||
- `pytest`：统一测试入口
|
||
- `pytest-asyncio`：负责 `async def` 测试和异步 fixture
|
||
- `pytest-cov`：负责覆盖率统计
|
||
- `pyright`：负责类型检查，但不替代测试和 `lint`
|
||
|
||
常用命令详见 `api/README.md`。
|
||
|
||
## 🛠️ 技术栈
|
||
|
||
### 后端技术栈
|
||
|
||
| 技术 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| FastAPI | 0.115.0 | Web 框架，REST API 和 WebSocket |
|
||
| LangChain | 0.3.7 | AI Agent 框架（对话引导、内容整理） |
|
||
| PostgreSQL | 17 | 关系型数据库 |
|
||
| SQLAlchemy + Alembic | 2.0.36 / 1.18+ | ORM 与数据库 schema migration |
|
||
| Redis | 7 | 缓存和会话存储 |
|
||
| Celery | 5.3 | 异步任务队列 |
|
||
| OpenAI API | - | ASR（语音识别）、TTS（语音合成） |
|
||
| DeepSeek API | - | LLM（大语言模型） |
|
||
| ReportLab + WeasyPrint | - | PDF 生成 |
|
||
|
||
## 📚 文档导航
|
||
|
||
## 🔐 认证系统
|
||
|
||
系统使用 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）和反馈系统
|
||
|
||
### 开发中功能
|
||
|
||
- 🔄 更多传记结构模板
|
||
- 🔄 图片上传与管理
|
||
- 🔄 章节编辑功能
|
||
- 🔄 多语言支持
|
||
|
||
## 🔒 安全注意事项
|
||
|
||
1. **环境变量安全**：确保 `.env` 文件不被提交到版本控制
|
||
2. **SECRET_KEY 安全**：生产环境必须使用强随机字符串
|
||
3. **CORS 配置**：本地 `API_CORS_ORIGINS` 可留空；生产/staging 须设为前端域名（逗号分隔），否则浏览器无法携带 credentials 跨域
|
||
4. **API Key 安全**：妥善保管 LLM API Key
|
||
5. **密码安全**：密码使用 bcrypt 哈希存储
|
||
|
||
## 🤝 贡献指南
|
||
|
||
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
|
||
- 发送反馈（应用内反馈功能）
|
||
|
||
---
|
||
|
||
**岁月留书** - 让每一段人生故事都被温柔记录 ✨
|