# evolva

**Repository Path**: codershui/evolva

## Basic Information

- **Project Name**: evolva
- **Description**: Evolva 是一个现代化的 AI 聊天移动应用，采用前后端分离架构，支持跨平台部署。项目结合了最新的前端框架 Vue 3 和后端框架 FastAPI，通过 Capacitor 实现原生移动应用体验
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-10-24
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Evolva - AI Chat Mobile Application

<div align="center">

![Evolva Logo](https://via.placeholder.com/150x150?text=Evolva)

**基于 Vue 3 + FastAPI + Capacitor 的现代化 AI 聊天移动应用**

[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=for-the-badge&logo=fastapi)](https://fastapi.tiangolo.com/)
[![Vue.js](https://img.shields.io/badge/Vue.js-35495E?style=for-the-badge&logo=vuedotjs&logoColor=4FC08D)](https://vuejs.org/)
[![Capacitor](https://img.shields.io/badge/Capacitor-119EFF?style=for-the-badge&logo=capacitor&logoColor=white)](https://capacitorjs.com/)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)

</div>

## 📱 项目简介

Evolva 是一个现代化的 AI 聊天移动应用，采用前后端分离架构，支持跨平台部署。项目结合了最新的前端框架 Vue 3 和后端框架 FastAPI，通过 Capacitor 实现原生移动应用体验。

### ✨ 核心特性

- **🤖 智能 AI 对话** - 集成 OpenAI 等 AI 服务，支持实时流式响应
- **📱 移动优先设计** - 基于 Vant UI 的移动端组件库，完美适配手机
- **⚡ 高性能架构** - FastAPI 异步后端 + Vue 3 组合式 API
- **🔐 安全认证** - JWT 令牌认证，密码哈希加密
- **💬 实时通信** - WebSocket 和 SSE 支持实时聊天
- **📱 跨平台部署** - Capacitor 支持 Android/iOS 原生应用
- **🎯 用户体验** - 打字机效果，快速问题模板，聊天历史

## 🏗️ 项目架构

### 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| **前端** | Vue 3 + TypeScript | 现代化前端框架 |
| **UI 组件** | Vant UI | 移动端组件库 |
| **状态管理** | Pinia | Vue 官方状态管理 |
| **路由** | Vue Router | 单页面应用路由 |
| **构建工具** | Vite | 快速构建工具 |
| **移动框架** | Capacitor | 跨平台移动应用 |
| **后端** | FastAPI + Python | 高性能异步 API |
| **数据库** | SQLAlchemy + SQLite/PostgreSQL | ORM 和数据库 |
| **缓存** | Redis | 会话和缓存管理 |
| **认证** | JWT + bcrypt | 安全认证系统 |

### 项目结构

```
Evolva/
├── backend/                    # FastAPI 后端服务
│   ├── app/
│   │   ├── api/v1/            # API 端点 (认证、用户、聊天)
│   │   ├── chatbot/           # AI 聊天机器人模块
│   │   ├── core/              # 核心配置、数据库、安全
│   │   ├── models/            # 数据模型 (用户、聊天等)
│   │   └── schemas/           # Pydantic 数据模式
│   ├── main.py               # 应用入口点
│   └── requirements.txt      # Python 依赖
├── frontend/                  # Vue 3 移动前端
│   ├── src/
│   │   ├── api/              # API 客户端服务
│   │   ├── components/       # 可复用 Vue 组件
│   │   ├── router/           # Vue Router 配置
│   │   ├── stores/           # Pinia 状态管理
│   │   ├── views/            # 页面组件 (聊天、登录、个人资料)
│   │   └── styles/           # 全局样式
│   ├── android/              # Capacitor Android 平台
│   ├── package.json          # Node.js 依赖
│   └── capacitor.config.ts   # Capacitor 配置
└── README.md                 # 项目文档
```

## 🚀 快速开始

### 环境要求

- **Node.js**: 16+
- **Python**: 3.8+
- **Redis**: 6+
- **OpenAI API Key**: 必需

### 后端启动

1. **安装依赖**
```bash
cd backend
pip install -r requirements.txt
```

2. **配置环境变量**
```bash
cp .env.example .env
# 编辑 .env 文件，配置必要的环境变量
```

3. **启动后端服务**
```bash
# 开发模式
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 生产模式
uvicorn main:app --host 0.0.0.0 --port 8000
```

4. **访问 API 文档**
- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`

### Docker 启动（推荐）

#### 解决内存不足问题
如果遇到内存不足错误（exit code: 137），请使用以下方法：

**方法1：使用构建脚本**
```bash
# 使用自动构建脚本（会尝试多种构建策略）
./build.sh
```

**方法2：手动选择构建方式**
```bash
# 轻量级构建（推荐）
docker build -f Dockerfile.light -t evolva-backend .

# 极简构建（内存占用最小）
docker build -f Dockerfile.minimal -t evolva-backend .

# 限制内存使用
docker build --memory=2g --memory-swap=2g -t evolva-backend .
```

#### 开发环境
```bash
# 使用开发配置启动所有服务
cp backend/.env.example .env
# 编辑 .env 文件，配置必要的环境变量

docker-compose -f docker-compose.dev.yml up --build
```

#### 生产环境
```bash
# 使用生产配置启动所有服务
docker-compose up --build -d
```

#### 仅构建后端镜像
```bash
# 构建 Docker 镜像
docker build -t evolva-backend .

# 运行容器
docker run -d -p 8000:8000 -e OPENAI_API_KEY=your-key evolva-backend
```

### 前端启动

1. **安装依赖**
```bash
cd frontend
npm install
```

2. **配置环境变量**
```bash
# 创建 .env 文件
cp .env.example .env.local
# 编辑 .env.local 文件，配置 API 地址等
```

3. **启动开发服务器**
```bash
npm run dev
```

4. **访问前端应用**
- 开发服务器: `http://localhost:3000`

### 移动应用构建

1. **添加移动平台**
```bash
cd frontend
npx cap add android
npx cap add ios
```

2. **构建应用**
```bash
npm run build
npx cap sync
```

3. **打开 IDE**
```bash
npx cap open android
npx cap open ios
```

## 📋 功能特性

### 🔐 用户认证
- **多种登录方式**: 手机号+密码、手机号+验证码
- **安全认证**: JWT 令牌，密码哈希加密
- **用户管理**: 注册、登录、个人信息管理

### 🤖 AI 聊天
- **实时流式响应**: SSE 技术实现打字机效果
- **多 AI 提供商**: OpenAI、模拟提供商（开发用）
- **聊天历史**: 会话管理，消息历史记录
- **快速问题**: 预设问题模板

### 📱 移动体验
- **原生应用**: Capacitor 提供原生功能
- **触摸优化**: Vant UI 移动端组件
- **离线支持**: 本地存储用户会话
- **推送通知**: 消息推送支持

### 🔄 实时通信
- **WebSocket**: 实时双向通信
- **SSE 流**: AI 响应流式传输
- **连接管理**: 自动重连和错误处理

## 🔧 开发指南

### 后端开发

#### 添加新的 API 端点
1. 在 `backend/app/api/v1/endpoints/` 创建新的端点文件
2. 在 `backend/app/api/v1/api.py` 注册路由
3. 定义对应的数据模型和模式

#### 数据库操作
```python
from app.core.database import get_db
from app.models.user import User

async def get_user_by_id(user_id: int):
    async with get_db() as db:
        user = await db.get(User, user_id)
        return user
```

### 前端开发

#### 添加新页面
1. 在 `frontend/src/views/` 创建新的页面组件
2. 在 `frontend/src/router/index.ts` 添加路由
3. 在 `frontend/src/stores/` 添加状态管理（如果需要）

#### API 调用示例
```typescript
import { userApi } from '@/api/user'

const getUserInfo = async () => {
  try {
    const response = await userApi.getCurrentUser()
    return response.data
  } catch (error) {
    console.error('获取用户信息失败:', error)
  }
}
```

### 环境配置

#### 后端环境变量 (.env)
```env
# 基础配置
DEBUG=true
HOST=0.0.0.0
PORT=8000

# 安全配置
SECRET_KEY=your-secret-key-here

# 数据库配置
DATABASE_URL=sqlite+aiosqlite:///./evolva.db

# Redis 配置
REDIS_URL=redis://localhost:6379

# AI 服务配置
OPENAI_API_KEY=your-openai-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
```

#### 前端环境变量 (.env.local)
```env
VITE_API_BASE_URL=http://localhost:8000/api/v1
VITE_WS_BASE_URL=ws://localhost:8000
VITE_APP_TITLE=Evolva
```

## 🧪 测试

### 后端测试
```bash
cd backend
pytest

# 带覆盖率报告
pytest --cov=app
```

### 前端测试
```bash
cd frontend
npm run test

# 单元测试
npm run test:unit

# E2E 测试
npm run test:e2e
```

#### 前端构建
```bash
cd frontend
npm run build
```

### 移动应用发布

#### Android
1. 构建发布版本
2. 签名 APK
3. 上传到 Google Play

#### iOS
1. 构建发布版本
2. 使用 Xcode 打包
3. 提交到 App Store

## 🐛 故障排除

### 常见问题

#### 1. 后端启动失败
- 检查 Python 版本和依赖
- 验证环境变量配置
- 确保 Redis 服务运行

#### 2. 前端构建失败
- 检查 Node.js 版本
- 清除 node_modules 重新安装
- 验证 TypeScript 配置

#### 3. 移动应用问题
- 运行 `npx cap sync` 同步代码
- 检查 Capacitor 配置
- 验证原生权限配置

#### 4. AI 服务不可用
- 检查 OpenAI API Key
- 验证网络连接
- 查看 API 使用额度

## 🤝 贡献指南

我们欢迎各种形式的贡献！

### 贡献流程
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](LICENSE) 文件了解详情。

## 📞 支持

如果您遇到问题或有建议：

- 📧 **邮箱**: [联系邮箱]
- 🐛 **Issues**: [GitHub Issues]
- 💬 **讨论**: [GitHub Discussions]

## 🙏 致谢

感谢以下开源项目：

- [FastAPI](https://fastapi.tiangolo.com/) - 现代化 Python Web 框架
- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [Capacitor](https://capacitorjs.com/) - 跨平台移动应用运行时
- [Vant UI](https://vant-ui.github.io/vant/) - 移动端 Vue 组件库
- [OpenAI](https://openai.com/) - AI 服务提供商

---

<div align="center">

**Evolva - 让 AI 对话更智能，让移动体验更美好**

</div>