# 模板快速使用指南

## 三种使用方式

### 🚀 方式一: 自动化脚本 (最推荐)

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

# 2. 按提示输入项目信息
# 3. 脚本会自动完成所有配置
# 4. 进入新项目目录开始开发
```

**优点**:
- ✅ 一键创建，无需手动配置
- ✅ 自动替换所有配置项
- ✅ 自动生成安全的 SECRET_KEY
- ✅ 自动初始化 Git 仓库

---

### 📋 方式二: 手动复制

```bash
# 1. 复制项目
cp -r /path/to/pager /path/to/your-new-project
cd /path/to/your-new-project

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

# 3. 配置后端
cd backend
cp .env.example .env
# 编辑 .env 文件，修改必要配置

# 4. 配置前端
cd frontend
# 编辑 package.json，修改项目名称

# 5. 初始化 Git
git init
git add .
git commit -m "Initial commit"
```

---

### 🔗 方式三: Git 模板方式

```bash
# 1. 克隆为模板
git clone /path/to/pager your-new-project
cd your-new-project

# 2. 移除原有 Git 历史
rm -rf .git

# 3. 按方式二的步骤 3-5 操作
```

---

## 核心配置清单

### ✅ 必须修改的配置

**后端 `backend/.env`:**
```bash
# 1. 数据库连接 (必须)
DATABASE_URL=postgresql://user:pass@host:port/dbname

# 2. 密钥 (必须，生产环境)
SECRET_KEY=<生成一个长随机字符串>

# 3. AI API Key (如需 AI 功能)
OPENROUTER_API_KEY=<your-api-key>
```

**前端 `frontend/package.json`:**
```json
{
  "name": "your-project-name-frontend"
}
```

**前端 `frontend/index.html`:**
```html
<title>Your Project Name</title>
```

---

### 🔧 可选修改的配置

**端口配置:**
- 后端: `backend/main.py` 或 `.env` 中的 `PORT`
- 前端: `vite.config.js` 中的 `server.port`

**API 地址:**
- `frontend/src/config/index.js`

---

## 快速命令参考

### 开发环境

```bash
# 后端
cd backend
pip install -r requirements.txt  # 安装依赖
python main.py                   # 启动服务

# 前端
cd frontend
npm install                      # 安装依赖
npm run dev                      # 启动开发服务器

# 或使用启动脚本
./start.sh                       # 同时启动前后端
./status.sh                      # 查看运行状态
./stop.sh                        # 停止所有服务
```

### 数据库操作

```bash
cd backend
python main.py                   # 首次运行自动创建表
python migrate_db.py             # 手动迁移数据库
```

### 生产构建

```bash
# 前端构建
cd frontend
npm run build                    # 构建到 dist/ 目录
npm run preview                  # 预览生产构建

# 后端生产运行
cd backend
uvicorn main:app --host 0.0.0.0 --port 8888
```

---

## 项目结构速览

```
your-project/
├── backend/                  # FastAPI 后端
│   ├── main.py              # 主应用 (所有 API 在这里)
│   ├── .env                 # 环境变量 (从 .env.example 复制)
│   └── requirements.txt     # Python 依赖
│
├── frontend/                 # Vue 3 前端
│   ├── src/
│   │   ├── views/           # 页面组件
│   │   ├── stores/          # Pinia 状态管理
│   │   ├── router/          # 路由配置
│   │   └── config/          # 配置管理
│   └── package.json         # 前端依赖
│
├── create-from-template.sh  # 模板创建脚本
├── TEMPLATE_GUIDE.md        # 完整使用指南
└── start.sh                 # 开发启动脚本
```

---

## 开发工作流

### 添加新功能

**1. 后端 API:**
```python
# backend/main.py
@app.get("/api/your-endpoint")
async def your_endpoint(current_user: User = Depends(get_current_user)):
    return {"message": "Hello"}
```

**2. 前端页面:**
```bash
# 创建组件
touch frontend/src/views/YourPage.vue

# 注册路由 (frontend/src/router/index.js)
{
  path: '/your-page',
  component: () => import('../views/YourPage.vue')
}
```

**3. 状态管理:**
```javascript
// frontend/src/stores/yourStore.js
import { defineStore } from 'pinia'

export const useYourStore = defineStore('your-store', () => {
  // 定义状态和方法
})
```

---

## 常见问题速查

| 问题 | 解决方法 |
|------|---------|
| 端口被占用 | 修改 `.env` 中的 `PORT` 或 `vite.config.js` |
| CORS 错误 | 检查 `backend/main.py` 的 CORS 配置 |
| 数据库连接失败 | 检查 `DATABASE_URL` 格式和数据库服务状态 |
| 前端请求失败 | 检查 `frontend/src/config/index.js` 的 API_BASE_URL |
| JWT 认证失败 | 确保 `SECRET_KEY` 正确且前后端一致 |

---

## 安全检查清单

- [ ] 修改了 `SECRET_KEY` (生产环境必须)
- [ ] 不提交 `.env` 文件到 Git
- [ ] 生产环境设置 `DEBUG=false`
- [ ] 限制 CORS 允许的域名
- [ ] 使用 HTTPS (生产环境)
- [ ] 定期更新依赖包
- [ ] 保护 API keys 安全

---

## 生成安全密钥

```bash
# 方法 1: OpenSSL
openssl rand -base64 32

# 方法 2: Python
python -c "import secrets; print(secrets.token_urlsafe(32))"

# 方法 3: Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
```

---

## 部署选项

### Docker
```bash
docker-compose up -d
```

### PM2
```bash
pm2 start backend/main.py --name api
pm2 serve frontend/dist 3000 --name frontend
```

### 云服务器
- 阿里云 ECS
- 腾讯云 CVM
- AWS EC2
- DigitalOcean Droplet

---

## 获取帮助

- 📖 完整文档: `TEMPLATE_GUIDE.md`
- 🏗️ 项目架构: `CLAUDE.md`
- 📋 部署指南: `README.md`
- ⚙️ 配置说明: `backend/.env.example`

---

## 下一步

1. ✅ 使用 `create-from-template.sh` 创建新项目
2. ✅ 配置 `backend/.env`
3. ✅ 安装依赖 (后端+前端)
4. ✅ 启动开发服务器
5. ✅ 开始开发你的功能

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