docs: 更新项目文档

- 更新根目录README.md，完善项目说明 - 更新api/README.md，添加API文档说明 - 新增api/docs/README.md文档 - 新增app-android/README.md文档 - 新增app-android/doc/文档目录
2026-01-26 11:54:03 +08:00
parent 8c219ab1b1
commit 5314077f3b
5 changed files with 938 additions and 67 deletions
--- a/README.md
+++ b/README.md
@@ -1,96 +1,238 @@
 # 往事拾遗 (Life Echo)

-一个基于实时 WebSocket 长连接的语音对话回忆录生成系统。
+> 一个基于实时 WebSocket 长连接的智能语音对话回忆录生成系统

-## 项目结构
+## 📖 项目简介
+
+**往事拾遗 (Life Echo)** 是一个创新的回忆录生成平台，通过 AI 智能对话引导用户回顾人生历程，并将口语对话自动整理为结构化的回忆录章节，最终生成精美的 PDF 电子书。
+
+### 核心功能
+
+- 🎙️ **实时语音对话** - 基于 WebSocket 的实时双向语音交互
+- 🤖 **智能访谈引导** - AI Agent 根据传记结构动态引导用户讲述人生故事
+- 📝 **自动内容整理** - 将口语对话自动整理为优雅的书面语章节
+- 📚 **结构化回忆录** - 基于传记结构自动组织章节内容
+- 📄 **PDF 导出** - 生成精美的回忆录 PDF 文档
+- 💾 **本地数据存储** - Android 端使用 Room 数据库实现离线数据管理
+
+## 🏗️ 项目结构

 ```
 life-echo/
 ├── api/                          # 后端服务（FastAPI）
-│   ├── agents/            # LangChain Agent
-│   ├── database/          # 数据库模型和连接
-│   ├── routers/          # API 路由
-│   ├── services/         # 业务服务（ASR、TTS、PDF）
-│   └── main.py           # 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 层（Compose）
-│           └── feature/  # 功能模块
-└── doc/                  # 文档
-    ├── 开发计划.md
-    └── 数据库设计.md
+│           ├── 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)

-1. 安装依赖：
 ```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
 ```

-2. 配置环境变量：
+### Android 应用启动
+
+详细步骤请参考 [app-android/README.md](app-android/README.md)
+
 ```bash
-cp .env.example .env
-# 编辑 .env 文件，填入 OPENAI_API_KEY
+# 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
 ```

-3. 初始化数据库：
-```python
-from api.database import init_db
-init_db()
-```
+## 🛠️ 技术栈

-4. 启动服务：
-```bash
-uvicorn api.main:app --reload --host 0.0.0.0 --port 8000
-```
+### 后端技术栈

-### Android 设置
+| 技术 | 版本 | 用途 |
+|------|------|------|
+| 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 生成 |

-1. 使用 Android Studio 打开 `app-android` 目录
+### Android 技术栈

-2. 同步 Gradle 依赖
+| 技术 | 版本 | 用途 |
+|------|------|------|
+| Kotlin | 1.9+ | 编程语言 |
+| Jetpack Compose | - | 声明式 UI 框架 |
+| Ktor | - | HTTP 客户端和 WebSocket |
+| Room | - | 本地数据库（SQLite） |
+| Coroutines + Flow | - | 异步编程和响应式数据流 |
+| DataStore | - | 键值对存储（Token 管理） |
+| Coil | - | 图片加载库 |

-3. 配置 API 地址（如需要）：
-   - 编辑 `app-android/app/src/main/java/com/huaga/life_echo/config/AppConfig.kt`
-   - 修改 `BASE_URL` 和 `WS_BASE_URL`
+## 📚 文档导航

-4. 运行应用
+### 项目文档

-## 功能特性
+- [开发计划](docs/开发计划.md) - 项目开发计划与任务分解
+- [数据库设计](docs/数据库设计.md) - 数据库表结构设计
+- [Agent 设计](docs/AGENT.md) - AI Agent 工作流程设计

- ✅ 实时 WebSocket 长连接对话
- ✅ 基于访谈问题的智能对话引导
- ✅ 自动将口语整理为书面语章节
- ✅ 基于传记结构的章节组织
+### 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 本地数据存储
+- ✅ Android 本地数据存储（Room）
+- ✅ 离线数据同步
+- ✅ 用户套餐与订单管理
+- ✅ 常见问题（FAQ）和反馈系统

-## 技术栈
+### 开发中功能

-**后端：**
- FastAPI + WebSocket
- LangChain（对话 Agent + 整理 Agent）
- SQLAlchemy + SQLite
- OpenAI API（ASR、TTS、LLM）
+- 🔄 更多传记结构模板
+- 🔄 图片上传与管理
+- 🔄 章节编辑功能
+- 🔄 多语言支持

-**Android：**
- Kotlin + Jetpack Compose
- Ktor WebSocket Client
- Room Database
- Coroutines + Flow
+## 📝 开发指南

-## 开发计划
+### 添加新的 API 路由

-详细开发计划请查看 [doc/开发计划.md](docs/开发计划.md)
+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
+- 发送反馈（应用内反馈功能）
+
+---
+
+**往事拾遗** - 让每一段人生故事都被温柔记录 ✨
+
--- a/api/README.md
+++ b/api/README.md
@@ -24,9 +24,14 @@ Life Echo API 是一个智能对话系统，通过 WebSocket 实时连接，使
 api/
 ├── main.py                 # FastAPI 应用入口
 ├── requirements.txt        # Python 依赖
+├── Dockerfile              # Docker 镜像构建文件
+├── docker-compose.yml      # 生产环境 Docker Compose
+├── docker-compose.dev.yml  # 开发环境 Docker Compose
 ├── agents/                 # LangChain Agent
 │   ├── conversation_agent.py    # 对话引导 Agent
 │   ├── memory_agent.py          # 记忆整理 Agent
+│   ├── memoir_processor.py      # 回忆录处理器
+│   ├── state_schema.py          # 状态模式定义
 │   └── prompts/                 # Agent 提示词
 │       ├── conversation_prompts.py
 │       └── memory_prompts.py
@@ -38,15 +43,36 @@ api/
 │   ├── conversations.py   # 对话管理 API
 │   ├── chapters.py        # 章节管理 API
 │   ├── books.py           # 回忆录管理 API
-│   └── websocket.py       # WebSocket 端点
-├── dependencies/           # 依赖注入
-│   └── auth.py            # 认证依赖（获取当前用户）
-└── services/              # 业务服务
-    ├── auth_service.py    # 认证服务（密码哈希、JWT）
-    ├── asr_service.py     # 语音识别服务
-    ├── tts_service.py       # 语音合成服务
-    ├── pdf_service.py       # PDF 生成服务
-    └── llm_service.py       # LLM 服务（DeepSeek/兼容 OpenAI 的 LLM）
+│   ├── websocket.py       # WebSocket 端点
+│   ├── memoir_state.py    # 回忆录状态 API
+│   ├── user.py            # 用户信息 API
+│   ├── plans.py           # 套餐管理 API
+│   ├── orders.py          # 订单管理 API
+│   ├── quota.py           # 配额管理 API
+│   ├── tasks.py           # 任务管理 API
+│   ├── faqs.py            # 常见问题 API
+│   └── feedback.py        # 反馈 API
+├── middleware/            # 中间件
+│   └── auth.py            # 认证中间件
+├── services/              # 业务服务
+│   ├── auth_service.py    # 认证服务（密码哈希、JWT）
+│   ├── asr_service.py     # 语音识别服务
+│   ├── tts_service.py     # 语音合成服务
+│   ├── pdf_service.py     # PDF 生成服务
+│   ├── llm_service.py     # LLM 服务（DeepSeek/兼容 OpenAI 的 LLM）
+│   ├── memoir_state_service.py  # 回忆录状态服务
+│   ├── redis_service.py   # Redis 服务
+│   └── task_tracker.py    # 任务追踪服务
+├── tasks/                 # Celery 后台任务
+│   ├── celery_app.py      # Celery 应用配置
+│   └── memoir_tasks.py    # 回忆录处理任务
+└── docs/                  # 详细文档
+    ├── README.md          # 文档索引
+    ├── 本地开发环境配置.md
+    ├── WebSocket快速测试指南.md
+    ├── WebSocket测试文档.md
+    ├── 文字交流模式说明.md
+    └── 测试脚本使用说明.md
 ```

 ## 环境配置
@@ -167,6 +193,16 @@ docker-compose logs -f
 - API 文档: http://localhost:8000/docs
 - 健康检查: http://localhost:8000/health

+## 📚 详细文档
+
+更多详细文档请参考 [docs/README.md](docs/README.md)：
+
+- **[本地开发环境配置](docs/本地开发环境配置.md)** - 开发环境搭建指南
+- **[WebSocket 快速测试指南](docs/WebSocket快速测试指南.md)** - WebSocket 快速测试
+- **[WebSocket 测试文档](docs/WebSocket测试文档.md)** - WebSocket 详细接口文档
+- **[文字交流模式说明](docs/文字交流模式说明.md)** - 文字对话模式功能说明
+- **[测试脚本使用说明](docs/测试脚本使用说明.md)** - 自动化测试脚本指南
+
 ## API 文档

 ### 认证系统
--- a/api/docs/README.md
+++ b/api/docs/README.md
@@ -0,0 +1,84 @@
+# API 文档索引
+
+> Life Echo API 详细文档目录
+
+## 📚 文档导航
+
+### 🚀 快速开始
+
+- **[本地开发环境配置](./本地开发环境配置.md)** - 详细的开发环境搭建指南
+  - 架构概述
+  - 前置要求
+  - 快速启动步骤
+  - 服务说明（FastAPI、Redis、Celery）
+  - 生产环境部署
+  - 常见问题
+
+### 🔌 WebSocket 文档
+
+- **[WebSocket 快速测试指南](./WebSocket快速测试指南.md)** - 快速上手 WebSocket 测试
+  - 连接地址
+  - 消息类型速查
+  - 测试场景
+  - 常见问题
+
+- **[WebSocket 测试文档](./WebSocket测试文档.md)** - WebSocket 接口详细文档
+  - 接口信息
+  - 消息类型定义
+  - 消息格式规范
+  - 完整测试示例
+  - 错误处理
+
+### 💬 功能说明
+
+- **[文字交流模式说明](./文字交流模式说明.md)** - 文字对话模式详细说明
+  - 功能特性
+  - WebSocket 消息格式
+  - 使用流程
+  - 已移除/保留的功能
+  - 注意事项
+
+### 🧪 测试文档
+
+- **[测试脚本使用说明](./测试脚本使用说明.md)** - 自动化测试脚本使用指南
+  - 前置条件
+  - 运行测试
+  - 测试流程
+  - 自定义测试内容
+  - 常见问题
+
+## 📖 文档分类
+
+### 按用途分类
+
+| 文档 | 用途 | 适合人群 |
+|------|------|----------|
+| 本地开发环境配置 | 环境搭建 | 新开发者 |
+| WebSocket 快速测试指南 | 快速测试 | 前端开发者、测试人员 |
+| WebSocket 测试文档 | 详细接口文档 | 后端开发者、集成开发者 |
+| 文字交流模式说明 | 功能说明 | 所有开发者 |
+| 测试脚本使用说明 | 自动化测试 | 测试人员、CI/CD |
+
+### 按阶段分类
+
+**开发阶段**：
+1. [本地开发环境配置](./本地开发环境配置.md) - 搭建开发环境
+2. [文字交流模式说明](./文字交流模式说明.md) - 了解功能特性
+
+**测试阶段**：
+1. [WebSocket 快速测试指南](./WebSocket快速测试指南.md) - 快速测试
+2. [WebSocket 测试文档](./WebSocket测试文档.md) - 详细测试
+3. [测试脚本使用说明](./测试脚本使用说明.md) - 自动化测试
+
+## 🔗 相关链接
+
+- [API README](../README.md) - API 服务主文档
+- [项目根目录 README](../../README.md) - 项目总览
+
+## 📝 文档更新
+
+文档会随着项目发展持续更新。如有问题或建议，请提交 Issue 或 Pull Request。
+
+---
+
+**Life Echo API 文档** - 让开发更简单 📚✨
--- a/app-android/README.md
+++ b/app-android/README.md
@@ -0,0 +1,440 @@
+# 往事拾遗 Android 应用
+
+> Life Echo Android 客户端 - 基于 Jetpack Compose 的现代化 Android 应用
+
+## 📱 项目简介
+
+**往事拾遗 Android 应用**是 Life Echo 平台的移动端客户端，提供流畅的语音对话体验和回忆录管理功能。应用采用现代化的 Android 开发技术栈，实现优雅的用户界面和流畅的交互体验。
+
+### 核心功能
+
+- 🎙️ **实时语音对话** - 通过 WebSocket 实现实时语音交互
+- 💬 **智能对话引导** - AI Agent 引导用户进行回忆录访谈
+- 📚 **回忆录管理** - 查看和管理生成的回忆录章节
+- 📄 **PDF 导出** - 导出回忆录为 PDF 文档
+- 👤 **用户中心** - 账户管理、套餐升级、订单查询
+- 💾 **离线存储** - 使用 Room 数据库实现本地数据存储
+- 🌙 **深色模式** - 支持深色主题和浅色主题切换
+
+## 🛠️ 技术栈
+
+| 技术 | 版本/说明 | 用途 |
+|------|-----------|------|
+| **Kotlin** | 1.9+ | 编程语言 |
+| **Jetpack Compose** | Latest | 声明式 UI 框架 |
+| **Ktor** | Latest | HTTP 客户端和 WebSocket |
+| **Room** | Latest | 本地数据库（SQLite） |
+| **Coroutines + Flow** | Latest | 异步编程和响应式数据流 |
+| **DataStore Preferences** | 1.0.0 | 键值对存储（Token 管理） |
+| **Coil** | Latest | 图片加载库 |
+| **Navigation Compose** | Latest | 导航管理 |
+| **ViewModel** | Latest | MVVM 架构支持 |
+| **Material 3** | Latest | Material Design 3 组件 |
+
+## 📁 项目结构
+
+```
+app-android/
+├── app/
+│   ├── build.gradle.kts          # 应用级构建配置
+│   └── src/
+│       └── main/
+│           ├── AndroidManifest.xml
+│           ├── java/com/huaga/life_echo/
+│           │   ├── MainActivity.kt          # 主 Activity
+│           │   │
+│           │   ├── config/
+│           │   │   └── AppConfig.kt         # 应用配置（API 地址等）
+│           │   │
+│           │   ├── data/                    # 数据层
+│           │   │   ├── auth/
+│           │   │   │   └── TokenManager.kt  # Token 管理
+│           │   │   ├── database/            # Room 数据库
+│           │   │   │   ├── AppDatabase.kt
+│           │   │   │   ├── Book.kt
+│           │   │   │   ├── Chapter.kt
+│           │   │   │   ├── Conversation.kt
+│           │   │   │   └── ...
+│           │   │   ├── preferences/
+│           │   │   │   └── TokenPreferences.kt
+│           │   │   └── repository/          # Repository 模式
+│           │   │       ├── ChapterRepository.kt
+│           │   │       ├── ConversationRepository.kt
+│           │   │       └── ...
+│           │   │
+│           │   ├── network/                 # 网络层
+│           │   │   ├── ApiService.kt        # REST API 服务
+│           │   │   ├── AuthService.kt       # 认证服务
+│           │   │   ├── WebSocketClient.kt   # WebSocket 客户端
+│           │   │   ├── interceptors/
+│           │   │   │   └── AuthInterceptor.kt
+│           │   │   └── models/              # 数据模型
+│           │   │       ├── AuthModels.kt
+│           │   │       ├── ConversationModels.kt
+│           │   │       └── ...
+│           │   │
+│           │   ├── ui/                      # UI 层
+│           │   │   ├── screens/             # 屏幕组件
+│           │   │   │   ├── LoginScreen.kt
+│           │   │   │   ├── RegisterScreen.kt
+│           │   │   │   ├── CreateMemoryScreen.kt
+│           │   │   │   ├── MyMemoirScreen.kt
+│           │   │   │   ├── ProfileScreen.kt
+│           │   │   │   └── ...
+│           │   │   ├── components/          # 可复用组件
+│           │   │   │   ├── chat/            # 聊天相关组件
+│           │   │   │   ├── memoir/         # 回忆录相关组件
+│           │   │   │   ├── payment/         # 支付相关组件
+│           │   │   │   └── common/          # 通用组件
+│           │   │   ├── theme/               # 主题配置
+│           │   │   │   ├── Color.kt
+│           │   │   │   ├── Theme.kt
+│           │   │   │   └── Type.kt
+│           │   │   └── viewmodel/           # ViewModel
+│           │   │       ├── AuthViewModel.kt
+│           │   │       ├── CreateMemoryViewModel.kt
+│           │   │       └── ...
+│           │   │
+│           │   ├── navigation/              # 导航管理
+│           │   │   ├── AppNavigation.kt
+│           │   │   └── NavigationTransitions.kt
+│           │   │
+│           │   ├── feature/                 # 功能模块
+│           │   │   └── voice/
+│           │   │       └── VoiceRecorder.kt # 语音录制
+│           │   │
+│           │   └── utils/                   # 工具类
+│           │       ├── AnimationUtils.kt
+│           │       ├── PaymentUtils.kt
+│           │       └── ...
+│           │
+│           └── res/                         # 资源文件
+│               ├── values/
+│               │   ├── strings.xml          # 字符串资源
+│               │   ├── colors.xml           # 颜色资源
+│               │   └── themes.xml           # 主题资源
+│               └── xml/
+│                   └── network_security_config.xml
+│
+├── build.gradle.kts                        # 项目级构建配置
+├── settings.gradle.kts                     # 项目设置
+├── gradle.properties                       # Gradle 属性
+└── README.md                               # 本文档
+```
+
+## 🚀 快速开始
+
+### 前置要求
+
+- **Android Studio** Hedgehog | 2023.1.1 或更高版本
+- **JDK** 11 或更高版本
+- **Android SDK** API 24 (Android 7.0) 或更高版本
+- **Gradle** 8.0+（项目已包含 Gradle Wrapper）
+
+### 环境配置
+
+1. **克隆项目**
+
+```bash
+git clone <repository-url>
+cd life-echo/app-android
+```
+
+2. **使用 Android Studio 打开项目**
+
+   - 打开 Android Studio
+   - 选择 `File -> Open`
+   - 选择 `app-android` 目录
+   - 等待 Gradle 同步完成
+
+3. **配置 API 地址**
+
+   编辑 `app/src/main/java/com/huaga/life_echo/config/AppConfig.kt`：
+
+   ```kotlin
+   object AppConfig {
+       // 开发环境配置
+       // 物理机测试：使用实际的内网IP地址（如 192.168.10.9）
+       const val BASE_URL = "http://192.168.10.9:8000"
+       const val WS_BASE_URL = "ws://192.168.10.9:8000"
+       
+       // Android模拟器测试：使用 10.0.2.2 来访问主机
+       // const val BASE_URL = "http://10.0.2.2:8000"
+       // const val WS_BASE_URL = "ws://10.0.2.2:8000"
+       
+       // 生产环境配置：公网地址
+       // const val BASE_URL = "https://api.lifeecho.com"
+       // const val WS_BASE_URL = "wss://api.lifeecho.com"
+   }
+   ```
+
+   **注意事项**：
+   - 从 Android 9 (API 28) 开始，默认禁止明文 HTTP 流量
+   - 开发环境已在 `network_security_config.xml` 中配置允许明文流量
+   - 生产环境应使用 HTTPS 并移除明文流量配置
+
+4. **确保后端服务运行**
+
+   确保后端 API 服务已启动并可以访问（参考 [api/README.md](../api/README.md)）
+
+5. **运行应用**
+
+   - 连接 Android 设备或启动模拟器
+   - 点击 `Run` 按钮（或使用快捷键 `Shift+F10`）
+   - 选择目标设备
+   - 等待应用安装和启动
+
+## 📱 应用功能
+
+### 认证功能
+
+- **用户注册** - 手机号注册，支持昵称和邮箱
+- **用户登录** - 手机号 + 密码登录
+- **Token 管理** - 自动管理访问令牌和刷新令牌
+- **自动登录** - 支持记住登录状态
+
+### 对话功能
+
+- **实时语音对话** - WebSocket 实时双向通信
+- **语音录制** - 支持实时音频录制和发送
+- **语音播放** - TTS 音频自动播放
+- **对话历史** - 查看历史对话记录
+- **对话管理** - 创建、查看、结束对话
+
+### 回忆录功能
+
+- **章节列表** - 查看所有回忆录章节
+- **章节阅读** - 优雅的章节阅读界面
+- **全文阅读** - 查看完整回忆录内容
+- **PDF 导出** - 导出回忆录为 PDF 文档
+- **章节整理** - 将对话内容整理为章节
+
+### 用户中心
+
+- **账户信息** - 查看和编辑用户信息
+- **套餐管理** - 查看当前套餐，升级套餐
+- **订单查询** - 查看历史订单
+- **数据导出** - 导出所有用户数据
+- **设置** - 语言、主题、通知等设置
+- **常见问题** - FAQ 列表
+- **反馈** - 提交反馈和联系客服
+
+## 🏗️ 架构设计
+
+### MVVM 架构
+
+应用采用 **MVVM（Model-View-ViewModel）** 架构模式：
+
+```
+┌─────────────┐
+│    View     │  (Compose UI)
+│  (Screen)   │
+└──────┬──────┘
+       │
+       │ observe
+       ▼
+┌─────────────┐
+│ ViewModel   │  (状态管理、业务逻辑)
+└──────┬──────┘
+       │
+       │ use
+       ▼
+┌─────────────┐
+│ Repository  │  (数据访问抽象)
+└──────┬──────┘
+       │
+       ├─────────┐
+       │         │
+       ▼         ▼
+┌──────────┐ ┌──────────┐
+│   Room   │ │ Network  │
+│ Database │ │  API     │
+└──────────┘ └──────────┘
+```
+
+### 数据流
+
+1. **UI 层（Compose）**：使用 `@Composable` 函数构建界面
+2. **ViewModel**：管理 UI 状态，处理用户交互
+3. **Repository**：统一数据访问接口，协调本地数据库和网络 API
+4. **数据源**：
+   - **Room Database**：本地 SQLite 数据库（离线数据）
+   - **Network API**：REST API 和 WebSocket（服务器数据）
+
+### 关键组件
+
+#### TokenManager
+
+管理用户认证令牌：
+
+```kotlin
+// 保存 Token
+TokenManager.saveTokens(accessToken, refreshToken)
+
+// 获取 Token
+val accessToken = TokenManager.getAccessToken()
+
+// 检查登录状态
+val isLoggedIn = TokenManager.isLoggedIn
+```
+
+#### WebSocketClient
+
+WebSocket 连接管理：
+
+```kotlin
+// 连接 WebSocket
+webSocketClient.connect(conversationId, accessToken)
+
+// 发送消息
+webSocketClient.sendAudio(audioData)
+
+// 接收消息
+webSocketClient.onMessage { message ->
+    // 处理消息
+}
+```
+
+#### Repository 模式
+
+统一数据访问：
+
+```kotlin
+class ConversationRepository(
+    private val apiService: ApiService,
+    private val conversationDao: ConversationDao
+) {
+    suspend fun getConversations(): Flow<List<Conversation>> {
+        // 先从本地数据库获取
+        // 然后从网络获取并更新本地数据库
+    }
+}
+```
+
+## 🔧 开发指南
+
+### 添加新的屏幕
+
+1. 在 `ui/screens/` 目录创建新的 Screen Composable
+2. 在 `navigation/AppNavigation.kt` 中添加路由
+3. 创建对应的 ViewModel（如需要）
+4. 在导航图中注册新屏幕
+
+### 添加新的 API 接口
+
+1. 在 `network/ApiService.kt` 中添加接口定义
+2. 在 `network/models/` 中添加对应的数据模型
+3. 在相应的 Repository 中调用新接口
+
+### 添加新的数据库表
+
+1. 在 `data/database/` 中创建 Entity 类
+2. 创建对应的 DAO 接口
+3. 在 `AppDatabase.kt` 中注册 Entity 和 DAO
+4. 更新数据库版本号
+
+### 添加新的 UI 组件
+
+1. 在 `ui/components/` 目录创建组件
+2. 使用 `@Composable` 注解
+3. 遵循 Material Design 3 设计规范
+
+## 🧪 测试
+
+### 单元测试
+
+```bash
+./gradlew test
+```
+
+### 集成测试
+
+```bash
+./gradlew connectedAndroidTest
+```
+
+## 📦 构建发布
+
+### Debug 构建
+
+```bash
+./gradlew assembleDebug
+```
+
+### Release 构建
+
+1. 配置签名密钥（在 `app/build.gradle.kts` 中）
+2. 构建 Release APK：
+
+```bash
+./gradlew assembleRelease
+```
+
+3. 构建 Release AAB（Google Play）：
+
+```bash
+./gradlew bundleRelease
+```
+
+## 🔒 安全注意事项
+
+1. **网络配置**：
+   - 开发环境允许明文 HTTP（仅用于开发）
+   - 生产环境必须使用 HTTPS
+   - 配置 `network_security_config.xml` 限制允许的域名
+
+2. **Token 存储**：
+   - Token 存储在 DataStore Preferences 中
+   - 不要将 Token 存储在 SharedPreferences 或日志中
+
+3. **API Key**：
+   - 不要在代码中硬编码 API Key
+   - 使用 BuildConfig 或环境变量
+
+4. **ProGuard/R8**：
+   - 启用代码混淆（Release 构建）
+   - 配置 ProGuard 规则保护敏感代码
+
+## 🐛 常见问题
+
+### WebSocket 连接失败
+
+**问题**：无法连接到 WebSocket 服务器
+
+**解决方案**：
+1. 检查 `AppConfig.kt` 中的 `WS_BASE_URL` 是否正确
+2. 确认后端服务正在运行
+3. 检查网络权限（`INTERNET`）是否已添加
+4. 如果是模拟器，使用 `10.0.2.2` 代替 `localhost`
+
+### 音频录制失败
+
+**问题**：无法录制音频
+
+**解决方案**：
+1. 检查 `RECORD_AUDIO` 权限是否已申请
+2. 确认设备支持音频录制
+3. 检查音频格式配置
+
+### 数据库迁移失败
+
+**问题**：应用更新后数据库迁移失败
+
+**解决方案**：
+1. 检查数据库版本号是否正确递增
+2. 确认 Migration 类已正确实现
+3. 测试数据库迁移逻辑
+
+## 📚 相关文档
+
+- [项目根目录 README](../README.md) - 项目总览
+- [API 文档](../api/README.md) - 后端 API 文档
+- [WebSocket 测试文档](../api/docs/WebSocket快速测试指南.md) - WebSocket 测试指南
+
+## 📄 许可证
+
+MIT License
+
+---
+
+**往事拾遗 Android** - 让每一段人生故事都被温柔记录 📱✨
--- a/app-android/doc/透明化导航栏使用指南.md
+++ b/app-android/doc/透明化导航栏使用指南.md
@@ -0,0 +1,169 @@
+# 透明化顶部导航栏使用指南
+
+## 概述
+
+本项目提供了两种方式来实现透明化顶部导航栏：
+
+1. **TransparentTopAppBar** - 用于标准 Material3 TopAppBar 的透明化组件
+2. **ChatHeader** - 自定义聊天头部组件，已支持透明化选项
+
+## 使用方法
+
+### 1. 使用 TransparentTopAppBar（推荐）
+
+`TransparentTopAppBar` 是一个可复用的透明化 TopAppBar 组件，提供了三种透明化模式：
+
+#### 完全透明模式
+
+```kotlin
+Scaffold(
+    topBar = {
+        TransparentTopAppBar(
+            title = { Text("页面标题") },
+            navigationIcon = {
+                IconButton(onClick = { navController?.popBackStack() }) {
+                    Icon(
+                        imageVector = AppIcons.ArrowBack,
+                        contentDescription = "返回"
+                    )
+                }
+            },
+            transparencyType = TransparencyType.FULLY_TRANSPARENT,
+            titleContentColor = MaterialTheme.colorScheme.onSurface,
+            navigationIconContentColor = MaterialTheme.colorScheme.onSurface
+        )
+    }
+) { paddingValues ->
+    // 页面内容
+}
+```
+
+#### 半透明模式
+
+```kotlin
+TransparentTopAppBar(
+    title = { Text("页面标题") },
+    transparencyType = TransparencyType.SEMI_TRANSPARENT,
+    backgroundColor = MaterialTheme.colorScheme.surface,
+    alpha = 0.7f, // 透明度值（0.0-1.0）
+    titleContentColor = MaterialTheme.colorScheme.onSurface
+)
+```
+
+#### 渐变透明模式（推荐）
+
+```kotlin
+TransparentTopAppBar(
+    title = { Text("页面标题") },
+    transparencyType = TransparencyType.GRADIENT,
+    backgroundColor = MaterialTheme.colorScheme.surface,
+    gradientColors = listOf(
+        MaterialTheme.colorScheme.surface.copy(alpha = 0.95f), // 顶部较不透明
+        MaterialTheme.colorScheme.surface.copy(alpha = 0.0f)   // 底部完全透明
+    ),
+    titleContentColor = MaterialTheme.colorScheme.onSurface
+)
+```
+
+### 2. 使用 ChatHeader 透明化
+
+`ChatHeader` 组件已支持透明化选项：
+
+#### 完全透明
+
+```kotlin
+ChatHeader(
+    title = "聊天标题",
+    isOnline = true,
+    onBackClick = { navController?.popBackStack() },
+    isTransparent = true,
+    transparencyType = 0 // 完全透明
+)
+```
+
+#### 半透明
+
+```kotlin
+ChatHeader(
+    title = "聊天标题",
+    isOnline = true,
+    onBackClick = { navController?.popBackStack() },
+    isTransparent = true,
+    transparencyType = 1, // 半透明
+    alpha = 0.6f // 透明度
+)
+```
+
+#### 渐变透明
+
+```kotlin
+ChatHeader(
+    title = "聊天标题",
+    isOnline = true,
+    onBackClick = { navController?.popBackStack() },
+    isTransparent = true,
+    transparencyType = 2 // 渐变透明
+)
+```
+
+## 透明化类型说明
+
+### TransparencyType 枚举
+
+- **FULLY_TRANSPARENT** - 完全透明，背景完全透明
+- **SEMI_TRANSPARENT** - 半透明，可以设置 alpha 值控制透明度
+- **GRADIENT** - 渐变透明，从顶部到底部逐渐变透明，视觉效果更自然
+
+## 注意事项
+
+1. **状态栏处理**：组件已自动处理状态栏的内边距（`windowInsetsPadding(WindowInsets.statusBars)`），确保内容不会被状态栏遮挡。
+
+2. **文字颜色**：使用透明化时，需要根据背景调整文字颜色以确保可读性：
+   - 透明背景：使用 `MaterialTheme.colorScheme.onSurface`
+   - 深色背景：使用 `Color.White`
+   - 浅色背景：使用 `Color.Black` 或 `MaterialTheme.colorScheme.onSurface`
+
+3. **性能考虑**：渐变透明模式使用了 `Brush.verticalGradient`，性能略低于其他模式，但视觉效果更好。
+
+4. **主题适配**：建议使用 `MaterialTheme.colorScheme` 中的颜色，以确保在不同主题（亮色/暗色）下都能正常显示。
+
+## 示例
+
+参考 `AboutScreen.kt` 中的实现示例。
+
+## 应用到其他屏幕
+
+要将透明化应用到其他使用 TopAppBar 的屏幕，只需：
+
+1. 导入 `TransparentTopAppBar` 和 `TransparencyType`
+2. 将 `TopAppBar` 替换为 `TransparentTopAppBar`
+3. 选择合适的 `transparencyType`
+4. 调整文字颜色以确保可读性
+
+例如，更新 `FeedbackScreen`：
+
+```kotlin
+import com.huaga.life_echo.ui.components.common.TransparentTopAppBar
+import com.huaga.life_echo.ui.components.common.TransparencyType
+
+// 在 Scaffold 中
+topBar = {
+    TransparentTopAppBar(
+        title = { Text("反馈与客服") },
+        navigationIcon = {
+            IconButton(onClick = { navController?.popBackStack() }) {
+                Icon(
+                    imageVector = AppIcons.ArrowBack,
+                    contentDescription = "返回",
+                    tint = MaterialTheme.colorScheme.onSurface
+                )
+            }
+        },
+        transparencyType = TransparencyType.GRADIENT,
+        gradientColors = listOf(
+            MaterialTheme.colorScheme.surface.copy(alpha = 0.95f),
+            MaterialTheme.colorScheme.surface.copy(alpha = 0.0f)
+        )
+    )
+}
+```