life-echo/README.md

# 岁月留书 (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 等）
│   │   ├── 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 | 异步任务队列 |
| 腾讯云 ASR/TTS | - | 语音识别（`16k_zh_large`）、语音合成 |
| 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
- 发送反馈（应用内反馈功能）

---

**岁月留书** - 让每一段人生故事都被温柔记录 ✨