# cursor_trea_rules_backend_frontend

**Repository Path**: no5689/cursor_trea_rules_backend_frontend

## Basic Information

- **Project Name**: cursor_trea_rules_backend_frontend
- **Description**: cursor_trea_rules_backend_frontend
cursor和trea规则
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-05
- **Last Updated**: 2025-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: cursor, trea, FastAPI, vue3, vite

## README



# 🌟 Cursor Trae Rules - 前后端全栈项目规范（布道师级）

> **作者：5689** | **邮箱：5689uno.@gmail.com** | **仓库：https://github.com/5689uno/5689**

> 基于 Vue 3 + TypeScript + Tailwind CSS + FastAPI 构建的现代化全栈应用，支持用户认证、前后端联调和完整的开发规范。

---

## 📋 项目概述

这是一个为 **Cursor AI 开发助手** 量身打造的布道师级全栈项目规范，包含前端和后端两个子项目，实现了完整的用户认证系统和前后端联调功能。
项目遵循现代化工程实践，提供完整的开发、测试、部署解决方案。

### 🎯 项目特色

- ✅ **现代化技术栈**: Vue 3 + TypeScript + Tailwind CSS + FastAPI + MySQL + JWT + Pinia
- ✅ **完整用户认证**: 注册、登录、权限控制、状态管理、Token自动刷新
- ✅ **前后端联调**: 跨域解决、API代理、统一错误处理、接口文档
- ✅ **自动数据库初始化**: 启动时自动创建表和默认管理员账户
- ✅ **工程化规范**: ESLint、Prettier、Black、Flake8、代码规范、测试覆盖
- ✅ **布道师级文档**: 详细的开发规范和最佳实践指导
- ✅ **异步优先**: 全面采用异步编程模式，提升性能
- ✅ **类型安全**: 完整的类型注解和验证机制
- ✅ **容器化部署**: Docker + Docker Compose 一键部署
- ✅ **AI集成支持**: 预留AI功能接口，支持DeepSeek、Dify、Coze平台集成

---

## 🏗️ 项目结构

项目分为两个主要部分：
- **Backend**：使用 Python 3.12.9 + FastAPI 构建，提供统一的 API 接口
- **Frontend**：基于 Vue 3 + TypeScript + Tailwind CSS + Vite 构建，实现现代前端界面

---

## 🚀 快速开始

### 📦 环境要求
- **Python**: 3.12.9
- **Node.js**: >= 16.0.0
- **MySQL**: >= 8.0
- **Conda**: 用于Python虚拟环境管理
- **Git**: 版本控制

---

### 🔧 环境配置

#### 1. 克隆项目

```bash
git clone https://github.com/5689uno/5689.git
cd cursor_trea_rules_backend_frontend
```

#### 2. 后端配置

```bash
# 切换到后端目录
cd backend

# 创建并激活conda虚拟环境
conda create -n py3129 python=3.12.9
conda activate py3129

# 安装依赖
pip install -r requirements-cpu.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库连接信息
```

#### 3. 前端配置

```bash
# 切换到前端目录
cd ../frontend

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
```

#### 4. 数据库配置

```sql
-- 创建数据库
CREATE DATABASE backend_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建用户（可选）
CREATE USER 'backend_user'@'localhost' IDENTIFIED BY '123456';
GRANT ALL PRIVILEGES ON backend_db.* TO 'backend_user'@'localhost';
FLUSH PRIVILEGES;
```

> ⚠️ **重要提醒**: 数据库root用户密码设置为 `123456`

---

## 🏃‍♂️ 启动项目

### 1. 启动后端服务（端口9001）

```bash
cd backend
conda activate py3129
python main.py
```

### 2. 启动前端服务（端口9002）

```bash
cd frontend
npm run dev
```

### 🔐 默认管理员账户

```
用户名: admin
密码: Admin@2025
邮箱: admin@example.com
权限: 管理员
```

> ⚠️ **重要提醒**: 所有接口运行后必须测试，然后解决问题，确保前后端联调正常

---

## 🌐 访问地址

- **前端应用**: http://localhost:9002
- **后端API**: http://localhost:9001
- **API文档**: http://localhost:9001/docs
- **ReDoc文档**: http://localhost:9001/redoc

## 🔐 用户认证系统

### 🎯 功能特性

- ✅ **用户注册**: 支持用户名/邮箱/密码注册，自动验证唯一性
- ✅ **用户登录**: 支持用户名密码登录，返回JWT Token
- ✅ **密码加密**: 使用bcrypt + salt双重加密保护
- ✅ **权限控制**: 支持普通用户和管理员权限区分
- ✅ **状态管理**: 前端使用Pinia管理认证状态
- ✅ **路由守卫**: 自动检查登录状态和权限
- ✅ **Token管理**: 自动添加Authorization头，处理过期
- ✅ **自动初始化**: 后端启动时自动创建数据库表和默认管理员

### 📡 认证API接口

| 接口 | 方法 | 前端路径 | 后端路径 | 说明 |
|------|------|----------|----------|------|
| 用户注册 | POST | `/api/auth/register` | `/auth/register` | 新用户注册 |
| 用户登录 | POST | `/api/auth/login` | `/auth/login` | 用户名密码登录 |
| 获取用户信息 | GET | `/api/auth/profile` | `/auth/profile` | 获取当前用户信息 |
| 用户登出 | POST | `/api/auth/logout` | `/auth/logout` | 用户退出登录 |

### 🔄 前后端联调流程

1. **前端发起请求**: `http://localhost:9002/api/auth/login`
2. **Vite代理转发**: 自动转发到 `http://localhost:9001/auth/login`
3. **后端处理请求**: FastAPI处理认证逻辑
4. **返回JWT Token**: 后端返回Token和用户信息
5. **前端存储Token**: Pinia状态管理 + localStorage持久化
6. **自动添加Header**: 后续请求自动添加 `Authorization: Bearer <token>`

---

## 🛡️ 功能特性

- **统一响应格式工具**：提供标准的 API 响应格式。
- **数据库操作工具**：支持 MySQL、SQLite、PostgreSQL，提供基础增删改查功能。
- **日志管理工具**：支持控制台和文件日志输出。
- **文件管理工具**：支持异步文件操作。
- **OCR 工具**：提供图像识别功能，支持 Tesseract OCR。
- **Redis 操作工具**：支持连接池、分布式锁、计数器等。
- **邮件和飞书通知工具**：统一整合邮件和飞书通知，支持多级别告警。
- **安全增强**：使用 JWT 进行用户认证，支持密码加密和用户权限管理。

---

## 🧪 测试

### 🔬 后端测试
- 基础测试：
  ```bash
  cd backend
  pytest
  ```
- 生成覆盖率报告：
  ```bash
  pytest --cov=.
  ```
- 测试特定模块：
  ```bash
  pytest tests/test_user.py
  ```

### 🎭 前端测试
- 运行单元测试：
  ```bash
  cd frontend
  npm run test:unit
  ```
- 生成覆盖率报告：
  ```bash
  npm run test:coverage
  ```

---

## 🔍 API 测试

- **用户注册**
  ```http
  POST /api/auth/register
  Content-Type: application/json

  {
    "username": "admin",
    "email": "admin@example.com",
    "password": "123456"
  }
  ```

- **用户登录**
  ```http
  POST /api/auth/login
  Content-Type: application/json

  {
    "username": "admin",
    "password": "123456"
  }
  ```

---

## 🛠️ 技术栈

### 🚀 后端技术栈
- **Python 3.10+**
- **FastAPI**
- **SQLAlchemy**
- **Pydantic**
- **Tesseract OCR**
- **Redis**
- **JWT**
- **bcrypt**

### 🎨 前端技术栈
- **Vue3**
- **Vite**
- **Axios**
- **Vue Router**
- **Pinia/Vuex**
- **ESLint**
- **Prettier**

---

## 📚 开发规范

- **文件命名**：使用小写字母和下划线，如 `user_model.py`。
- **代码风格**：后端使用 PEP8，前端使用 Vue3 最佳实践。
- **环境变量**：所有敏感配置应通过 `.env` 文件管理。
- **日志输出**：所有模块应使用统一的日志工具。
- **错误处理**：后端提供统一的异常处理机制。
- **API 文档**：后端自动提供 Swagger 文档（访问 http://localhost:9001/docs）。

---

## 📁 目录结构优化建议

- **Backend**
  - `middleware/`：认证、CORS、日志中间件。
  - `models/`：数据模型定义。
  - `services/`：业务逻辑处理。
  - `utils/`：工具类模块。
  - `exceptions/`：异常处理模块。
  - `api/`：API 路由和接口定义。

- **Frontend**
  - `src/api/`：API 请求配置。
  - `src/stores/`：状态管理。
  - `src/utils/`：本地存储、工具函数。
  - `src/views/`：页面组件。
  - `src/router/`：路由管理。

---

## 📦 依赖管理

- **后端依赖**
  - `requirements-cpu.txt`：适用于开发环境。
  - `requirements-gpu.txt`：适用于生产环境（包含 AI 相关库）。

- **前端依赖**
  - `package.json`：基础依赖和开发依赖。

---

## 📦 部署

### Docker 部署示例：
- 后端 Dockerfile：
  ```dockerfile
  FROM python:3.10
  WORKDIR /app
  COPY backend/ .
  RUN pip install -r requirements-cpu.txt
  CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "9001"]
  ```
- 前端 Dockerfile：
  ```dockerfile
  FROM node:18
  WORKDIR /app
  COPY frontend/ .
  RUN npm install
  CMD ["npm", "run", "preview"]
  ```

---

## 🧰 工具配置

- **VS Code 配置**：`.vscode/settings.json`
- **预提交钩子**：`.pre-commit-config.yaml`
- **代码格式化**：使用 Prettier 和 ESLint。
- **性能监控**：提供 `monitor_tool.py` 用于监控系统性能。

---

## 📚 相关文档

- **后端文档**：http://localhost:9001/docs
- **前端文档**：https://vuejs.org/guide/introduction.html

---

## 🤝 贡献指南

1. Fork 项目
2. 创建新分支
3. 提交 Pull Request
4. 遵循提交规范（如 feat、fix、docs 等）

---

## 📄 许可证

本项目遵循 MIT 许可证。

---

## 📞 联系方式

如有问题或建议，请联系作者 5689。

---

## 🎉 致谢

感谢所有为本项目做出贡献的开发者和社区支持。