aaa

example/项目需求文档.md

@@ -0,0 +1,132 @@
+# 文思泉涌 - 项目需求文档
+
+## 1. 项目概述
+
+**项目名称**：文思泉涌  
+**应用类型**：Android 原生应用  
+**包名**：com.ruilaizi.example  
+
+本应用是一款 **AI 文本生成助手**，核心功能为集成云端大语言模型（LLM）API，为用户提供简洁、高效、响应迅速的文本生成工具。用户通过输入提示词，应用调用 AI 服务并**实时流式返回**高质量文本，支持基础编辑与多次生成。
+
+---
+
+## 2. 核心功能规格
+
+### 2.1 用户输入模块
+
+| 功能点 | 说明 |
+|--------|------|
+| **多行文本输入框** | 显著的多行输入框，用于输入生成提示（Prompt）。 |
+| **预设提示按钮** | 输入框上方提供 3～5 个常用预设，点击可快速填充。当前实现：写一封工作邮件、生成一段产品描述、写一段短故事开头、总结以下内容要点、写一首小诗。 |
+| **生成长度** | 滑块调节：短 / 中 / 长，对应 AI 的 `max_tokens` 参数（如 256 / 512 / 1024）。 |
+| **创意程度** | 滑块调节：保守 / 平衡 / 创意，对应 AI 的 `temperature` 参数（如 0.3 / 0.7 / 1.2）。 |
+
+### 2.2 AI 处理与生成模块
+
+| 功能点 | 说明 |
+|--------|------|
+| **加载反馈** | 点击「生成」后界面显示加载动画（如环形进度条）。 |
+| **API 调用** | 通过 HTTPS 请求调用云端 AI API（如 OpenAI GPT、Google Gemini 或国内合规同类 API）。 |
+| **流式响应** | 实时流式接收生成文本，逐字或逐句显示在结果区域，模拟打字机效果。 |
+
+### 2.3 结果展示与交互模块
+
+| 功能点 | 说明 |
+|--------|------|
+| **结果展示** | 生成结果在可滚动的文本区域内清晰展示，与输入区明显区分（如卡片样式）。 |
+| **复制** | 一键复制全部生成文本到系统剪贴板。 |
+| **重新生成** | 基于原提示词和参数再次调用 AI 生成新内容。 |
+| **编辑/续写** | 将当前生成结果作为新的输入，允许用户修改后继续生成。 |
+
+---
+
+## 3. 技术实现要点
+
+### 3.1 开发框架
+
+- **原生 Android 开发（Java）**，充分利用平台特性，保证性能与体验。
+
+### 3.2 AI 集成
+
+| 项目 | 说明 |
+|------|------|
+| **方式** | 集成**云端 API**，首选 OpenAI GPT API 或 Google Gemini API。 |
+| **网络层** | 使用 HttpURLConnection / OkHttp 处理请求，配合线程与 Handler 实现异步与流式解析。 |
+| **流式响应** | 使用 SSE（Server-Sent Events）或流式接口，解析 `data:` 行并抽取内容，逐段回调 UI。 |
+| **安全** | API 密钥**不得**硬编码。使用 **EncryptedSharedPreferences** 或 Android Keystore 加密存储；更佳方案为部署轻量后端网关转发请求，由后端保管密钥。 |
+
+### 3.3 架构
+
+- **MVVM**：`ViewModel` + `LiveData` 管理 UI 状态与数据，提高可测试性与可维护性。
+
+### 3.4 本地存储
+
+- 使用 **Room** 数据库轻量缓存用户最近生成记录（如最近 10 条），支持离线查看。
+
+---
+
+## 4. UI/UX 设计规范
+
+### 4.1 设计语言
+
+- 遵循 **Material Design 3**（Material Components）规范。
+
+### 4.2 界面布局
+
+- 主界面采用**垂直线性布局**，从上至下依次为：
+  - 预设提示区 → 输入区 → 参数控制区（生成长度、创意程度）→「生成」按钮 → 结果展示区 → 操作按钮栏（复制、重新生成、编辑/续写）。
+- **色彩主题**：柔和、专注的配色（如深蓝/浅灰背景、白色卡片）。
+
+### 4.3 交互反馈
+
+- 所有按钮点击需有视觉反馈（Ripple 效果）。
+- 网络请求时必须有明确的加载状态提示。
+- 生成成功或操作完成（如复制）后，使用 **Snackbar** 提供轻量级提示。
+
+---
+
+## 5. 非功能性要求
+
+| 项目 | 要求 |
+|------|------|
+| **性能** | 应用启动时间应小于 2 秒；生成请求的首次响应时间尽可能短；流式接收过程需流畅无卡顿。 |
+| **兼容性** | 最低支持 **Android API Level 24（Android 7.0）**，targetSdk 34。 |
+
+---
+
+## 6. 项目结构概览
+
+```
+app/
+├── src/main/
+│   ├── java/com/ruilaizi/example/
+│   │   ├── MainActivity.java              # 主界面
+│   │   ├── BaseApplication.java
+│   │   ├── data/
+│   │   │   ├── api/                        # API Key、流式接口、OpenAI SSE 实现
+│   │   │   ├── db/                         # Room 实体、DAO、Database
+│   │   │   └── repository/                 # GenerationRepository
+│   │   ├── ui/
+│   │   │   └── MainViewModel.java         # 主界面 MVVM ViewModel
+│   │   ├── base/                           # BaseActivity 等
+│   │   ├── dialog/                         # LoadingDialog 等
+│   │   └── utils/
+│   ├── res/
+│   │   ├── layout/activity_main.xml       # 主界面布局
+│   │   ├── values/strings.xml, colors.xml, styles.xml
+│   │   └── ...
+│   └── AndroidManifest.xml
+└── build.gradle
+```
+
+---
+
+## 7. 配置与扩展说明
+
+- **API Base URL**：在 `build.gradle` 的 `buildConfigField "API_BASE_URL"` 中配置，默认指向 OpenAI；可改为自建网关或国内合规 API。
+- **API Key**：在应用内「设置」中配置，或通过后端网关免填。
+- 更换为 **Gemini** 或其他流式 API 时，只需实现/替换 `AIService` 实现类并在 Repository 中注入即可。
+
+---
+
+*文档版本：1.0 | 与当前实现保持一致*