# 快速开始指南

## 1. 环境准备

### 必需环境

- Node.js >= 20.19+
- pnpm >= 8.0

### 安装 pnpm

```bash
npm install -g pnpm
```

## 2. 项目初始化

### 克隆项目

```bash
git clone <repository-url>
cd content-frontend
```

### 安装依赖

```bash
pnpm install
```

## 3. 配置后端地址

### 复制环境变量文件

```bash
cp .env.example .env.development
```

### 修改后端地址

编辑 `.env.development`：

```bash
# 修改为你的后端地址
VITE_API_BASE_URL=http://localhost:8080
```

## 4. 启动开发服务器

```bash
pnpm dev
```

项目将在 `http://localhost:3000` 启动。

## 5. 代理配置说明

### 开发环境

开发环境下，所有 API 请求会通过 Vite 代理转发到后端：

```
前端: http://localhost:3000
后端: http://localhost:8080

请求流程:
http://localhost:3000/sys/user/list
    ↓ (Vite 代理)
http://localhost:8080/sys/user/list
```

### 代理规则

在 `vite.config.ts` 中配置：

```typescript
proxy: {
  "/api": {
    target: "http://localhost:8080",
    changeOrigin: true,
    rewrite: (path) => path.replace(/^\/api/, ""),
  },
  "/sys": {
    target: "http://localhost:8080",
    changeOrigin: true,
  },
}
```

## 6. 测试接口连接

### 方式一：浏览器控制台

打开浏览器控制台，执行：

```javascript
fetch('/sys/user/list')
  .then(r => r.json())
  .then(console.log)
```

### 方式二：使用示例页面

访问示例页面测试 API：

```
http://localhost:3000/examples/api-usage
```

## 7. 常见问题

### 问题 1: 端口被占用

**错误信息：**
```
Port 3000 is in use
```

**解决方案：**

修改 `vite.config.ts` 中的端口：

```typescript
server: {
  port: 3001, // 改为其他端口
}
```

### 问题 2: 代理不生效

**原因：** 请求路径不匹配代理规则

**解决方案：**

确保 API 请求路径以 `/api` 或 `/sys` 开头：

```typescript
// ✅ 正确
http.get("/sys/user/list");

// ❌ 错误
http.get("http://localhost:8080/sys/user/list");
```

### 问题 3: 跨域问题

**原因：** 后端未配置 CORS

**解决方案：**

1. 使用 Vite 代理（推荐）
2. 或在后端配置 CORS

### 问题 4: Token 无法携带

**原因：** Cookie 配置问题

**解决方案：**

在代理配置中添加：

```typescript
"/api": {
  target: "http://localhost:8080",
  changeOrigin: true,
  cookieDomainRewrite: "localhost",
}
```

## 8. 构建生产版本

### 构建

```bash
pnpm build
```

构建产物在 `dist` 目录。

### 预览

```bash
pnpm preview
```

### 生产环境配置

编辑 `.env.production`：

```bash
# 生产环境后端地址
VITE_API_BASE_URL=https://api.example.com
```

## 9. 部署

### 方式一：静态文件部署

将 `dist` 目录部署到任意静态文件服务器（Nginx、Apache 等）。

### 方式二：Docker 部署

```dockerfile
FROM nginx:alpine
COPY dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

### Nginx 配置示例

```nginx
server {
    listen 80;
    server_name example.com;

    root /usr/share/nginx/html;
    index index.html;

    # 前端路由
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api {
        proxy_pass http://backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /sys {
        proxy_pass http://backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 10. 开发建议

### 目录结构

```
src/
├── layouts/      # 布局组件
├── pages/        # 页面组件
├── components/   # 通用组件
├── services/     # API 服务
├── hooks/        # 自定义 Hooks
├── contexts/     # React Context
├── utils/        # 工具函数
└── types/        # 类型定义
```

### 代码规范

- 使用 TypeScript 严格模式
- 组件使用函数式组件
- 使用 Hooks 管理状态
- API 请求使用封装的服务层

### Git 提交规范

```bash
feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建/工具相关
```

## 11. 下一步

- 阅读 [权限系统使用指南](./PERMISSION_GUIDE.md)
- 阅读 [API 请求封装指南](./API_GUIDE.md)
- 阅读 [Vite 代理配置指南](./PROXY_GUIDE.md)
- 查看示例代码 `src/examples/`

## 12. 获取帮助

- 查看项目文档
- 提交 Issue
- 联系开发团队