aitsc/example/项目需求文档.md

文思泉涌 - 项目需求文档

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 | 与当前实现保持一致