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）
│   ├── 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. 安装依赖
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`。

### 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 + Alembic | 2.0.36 / 1.18+ | ORM 与数据库 schema migration |
| 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
- 发送反馈（应用内反馈功能）

---

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