# 项目模板使用指南

## 概述

这是一个生产级的 FastAPI + Vue 3 全栈应用模板，包含完整的用户认证、文件上传、数据库操作和现代化前端界面。

## 模板特性

### 后端 (FastAPI)
- ✅ RESTful API 设计
- ✅ JWT 身份认证
- ✅ SQLAlchemy ORM (支持 PostgreSQL/SQLite)
- ✅ 文件上传处理
- ✅ PDF 处理能力
- ✅ AI 模型集成 (Claude, Gemini)
- ✅ 自动 API 文档 (Swagger/OpenAPI)
- ✅ CORS 配置
- ✅ 环境变量管理

### 前端 (Vue 3)
- ✅ Composition API
- ✅ Element Plus UI 组件库
- ✅ Pinia 状态管理
- ✅ Vue Router 路由
- ✅ Vite 构建工具
- ✅ 响应式设计
- ✅ 统一配置管理
- ✅ API 服务封装

## 快速开始

### 方法一: 使用自动化脚本 (推荐)

```bash
# 1. 运行创建脚本
./create-from-template.sh

# 2. 根据提示输入项目信息
Project name: my-awesome-app
Display name: My Awesome App
Database name: myapp_db
API port: 8888
Frontend port: 3000

# 3. 脚本会自动:
#    - 创建新项目目录
#    - 复制所有文件
#    - 替换配置项
#    - 清理临时文件
#    - 初始化 git 仓库
```

### 方法二: 手动创建

#### 1. 复制项目

```bash
# 复制整个项目到新目录
cp -r /path/to/pager /path/to/your-new-project
cd /path/to/your-new-project

# 清理不需要的文件
rm -rf .git backend/__pycache__ backend/wordmaster.db backend/uploads/* frontend/node_modules frontend/dist
```

#### 2. 配置后端

```bash
cd backend

# 复制环境变量配置
cp .env.example .env

# 编辑 .env 文件，修改以下配置:
# - DATABASE_URL: 数据库连接字符串
# - SECRET_KEY: JWT 密钥 (必须修改!)
# - OPENROUTER_API_KEY: AI API 密钥 (如需要)
# - AI_MODEL: AI 模型选择

# 安装依赖
pip install -r requirements.txt

# 初始化数据库
python main.py
```

#### 3. 配置前端

```bash
cd frontend

# 编辑 package.json
# 修改 "name": "your-project-frontend"

# 安装依赖
npm install

# 配置开发环境变量 (可选)
# 编辑 .env.development
# VITE_API_BASE_URL=http://localhost:8888/api
```

#### 4. 修改项目名称和品牌

需要修改的文件:

**后端:**
- `backend/main.py`: 数据库名称、应用描述
- `backend/.env`: 数据库连接字符串

**前端:**
- `frontend/package.json`: 项目名称
- `frontend/index.html`: 页面标题
- `frontend/src/config/index.js`: API 端口配置

#### 5. 启动项目

```bash
# 后端 (在 backend 目录)
python main.py
# 或
uvicorn main:app --host 0.0.0.0 --port 8888 --reload

# 前端 (在 frontend 目录)
npm run dev
```

## 项目结构详解

```
your-project/
├── backend/                    # FastAPI 后端
│   ├── main.py                # 主应用文件 (所有 API 端点)
│   ├── requirements.txt       # Python 依赖
│   ├── .env.example          # 环境变量示例
│   ├── migrate_db.py         # 数据库迁移脚本
│   ├── pdf_splitter_*.py     # PDF 处理模块
│   ├── claude_exam_parser.py # AI 解析器
│   ├── utils/                # 工具函数
│   └── uploads/              # 文件上传目录
│
├── frontend/                  # Vue 3 前端
│   ├── src/
│   │   ├── main.js           # 应用入口
│   │   ├── App.vue           # 根组件
│   │   ├── router/           # 路由配置
│   │   ├── stores/           # Pinia 状态管理
│   │   ├── views/            # 页面组件
│   │   ├── components/       # 可复用组件
│   │   ├── config/           # 配置管理
│   │   └── services/         # API 服务
│   ├── package.json          # 前端依赖
│   └── vite.config.js        # Vite 配置
│
├── start.sh                   # 开发启动脚本
├── stop.sh                    # 停止脚本
├── status.sh                  # 状态检查脚本
├── template.config.json       # 模板配置
└── TEMPLATE_GUIDE.md         # 本文档
```

## 核心功能模块

### 1. 用户认证系统

**后端实现** (`backend/main.py`):
```python
# 注册
@app.post("/api/auth/register")

# 登录
@app.post("/api/auth/login")

# 获取当前用户
def get_current_user(credentials: HTTPAuthorizationCredentials)
```

**前端实现** (`frontend/src/stores/auth.js`):
```javascript
// 登录
async login(username, password)

// 注册
async register(username, password)

// 登出
logout()

// 自动加载用户信息
loadUser()
```

### 2. 数据库模型

**基础模型结构** (`backend/main.py`):
```python
class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    username = Column(String, unique=True)
    password_hash = Column(String)
    created_at = Column(DateTime)

# 添加你自己的模型
class YourModel(Base):
    __tablename__ = "your_table"
    # 定义字段...
```

### 3. 文件上传

**后端示例**:
```python
@app.post("/api/upload")
async def upload_file(
    file: UploadFile = File(...),
    current_user: User = Depends(get_current_user)
):
    # 保存到 uploads/{user_id}/
    file_path = f"uploads/{current_user.id}/{file.filename}"
    # 处理文件...
    return {"file_path": file_path}
```

**前端示例** (使用 Element Plus):
```vue
<el-upload
  :action="uploadUrl"
  :headers="headers"
  :on-success="handleSuccess"
>
  <el-button>上传文件</el-button>
</el-upload>
```

### 4. 状态管理 (Pinia)

创建新的 store (`frontend/src/stores/yourStore.js`):
```javascript
import { defineStore } from 'pinia'
import { ref } from 'vue'

export const useYourStore = defineStore('your-store', () => {
  const data = ref([])

  async function fetchData() {
    // API 调用...
  }

  return { data, fetchData }
})
```

### 5. 路由配置

添加新路由 (`frontend/src/router/index.js`):
```javascript
{
  path: '/your-page',
  name: 'YourPage',
  component: () => import('../views/YourPage.vue'),
  meta: { requiresAuth: true }  // 需要登录
}
```

## 自定义和扩展

### 添加新的 API 端点

在 `backend/main.py` 中:
```python
@app.get("/api/your-endpoint")
async def your_endpoint(
    current_user: User = Depends(get_current_user),
    db: Session = Depends(get_db)
):
    # 你的逻辑
    return {"data": "your data"}
```

### 添加新的前端页面

1. 创建组件: `frontend/src/views/YourPage.vue`
```vue
<template>
  <div class="your-page">
    <h1>{{ title }}</h1>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const title = ref('Your Page Title')
</script>
```

2. 在路由中注册 (见上面路由配置)

### 修改数据库模型

1. 编辑 `backend/main.py` 中的模型定义
2. 运行迁移:
```bash
cd backend
python migrate_db.py
```

## 部署指南

### 环境变量配置

**生产环境必须修改**:
```bash
# backend/.env
SECRET_KEY=your-very-long-random-secret-key-min-32-chars
DATABASE_URL=postgresql://user:password@host:port/dbname
```

### Docker 部署

创建 `Dockerfile` (后端):
```dockerfile
FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8888"]
```

创建 `Dockerfile` (前端):
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
CMD ["npm", "run", "preview"]
```

### Nginx 配置

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        root /var/www/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://localhost:8888;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 最佳实践

### 1. 安全性
- ✅ 修改默认 SECRET_KEY
- ✅ 使用 HTTPS (生产环境)
- ✅ 限制 CORS 源
- ✅ 定期更新依赖
- ✅ 不要提交 .env 文件

### 2. 性能优化
- ✅ 启用数据库索引
- ✅ 使用连接池
- ✅ 前端代码分割
- ✅ 静态资源 CDN
- ✅ API 响应缓存

### 3. 开发规范
- ✅ 遵循 RESTful API 设计
- ✅ 使用 TypeScript (可选)
- ✅ 编写单元测试
- ✅ 代码审查
- ✅ Git 提交规范

## 常见问题

### Q: 如何切换数据库?

**从 SQLite 到 PostgreSQL:**
```python
# 修改 DATABASE_URL
DATABASE_URL = "postgresql://user:password@localhost:5432/dbname"

# 重新创建表
python main.py
```

### Q: 如何添加新的 AI 模型?

编辑 `backend/.env`:
```bash
AI_MODEL=google/gemini-3-pro-preview
# 或
AI_MODEL=openai/gpt-4o
```

### Q: 前端如何跨域请求?

开发环境在 `vite.config.js` 配置代理:
```javascript
export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:8888',
        changeOrigin: true
      }
    }
  }
})
```

### Q: 如何部署到云服务器?

1. 购买云服务器 (阿里云/腾讯云/AWS)
2. 配置安全组开放端口
3. 使用 Docker 或 PM2 部署
4. 配置域名和 HTTPS

## 模板更新

如果模板有更新，你可以:

1. **选择性合并**:
```bash
git remote add template /path/to/template
git fetch template
git cherry-pick <commit-hash>
```

2. **手动更新**:
比较新旧文件，手动复制需要的功能

## 技术支持

- 查看 `CLAUDE.md` 了解详细项目文档
- 查看 `README.md` 了解部署指南
- FastAPI 文档: https://fastapi.tiangolo.com
- Vue 3 文档: https://vuejs.org
- Element Plus 文档: https://element-plus.org

## 许可证

MIT License - 自由使用和修改

---

**祝你的项目开发顺利!** 🚀