From 5314077f3b7eac7a2524673392f13a619bf57994 Mon Sep 17 00:00:00 2001 From: iammm0 Date: Mon, 26 Jan 2026 11:54:03 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新根目录README.md，完善项目说明 - 更新api/README.md，添加API文档说明 - 新增api/docs/README.md文档 - 新增app-android/README.md文档 - 新增app-android/doc/文档目录 --- README.md | 258 ++++++++++---- api/README.md | 54 ++- api/docs/README.md | 84 +++++ app-android/README.md | 440 ++++++++++++++++++++++++ app-android/doc/透明化导航栏使用指南.md | 169 +++++++++ 5 files changed, 938 insertions(+), 67 deletions(-) create mode 100644 api/docs/README.md create mode 100644 app-android/README.md create mode 100644 app-android/doc/透明化导航栏使用指南.md diff --git a/README.md b/README.md index 07763ef..dab760e 100644 --- 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 应用入口 -├── app-android/ # Android 应用 +├── 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 层（Compose） -│ └── feature/ # 功能模块 -└── doc/ # 文档 - ├── 开发计划.md - └── 数据库设计.md +│ ├── 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) -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 +- 发送反馈（应用内反馈功能） + +--- + +**往事拾遗** - 让每一段人生故事都被温柔记录 ✨ + diff --git a/api/README.md b/api/README.md index 6c5dbf3..a5bab37 100644 --- 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 文档 ### 认证系统 diff --git a/api/docs/README.md b/api/docs/README.md new file mode 100644 index 0000000..33bb637 --- /dev/null +++ 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 文档** - 让开发更简单 📚✨ diff --git a/app-android/README.md b/app-android/README.md new file mode 100644 index 0000000..2d34036 --- /dev/null +++ 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 +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> { + // 先从本地数据库获取 + // 然后从网络获取并更新本地数据库 + } +} +``` + +## 🔧 开发指南 + +### 添加新的屏幕 + +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** - 让每一段人生故事都被温柔记录 📱✨ diff --git a/app-android/doc/透明化导航栏使用指南.md b/app-android/doc/透明化导航栏使用指南.md new file mode 100644 index 0000000..162b8fc --- /dev/null +++ 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) + ) + ) +} +```