# 少儿智慧阅读平台 - 前端

Vue 3 + TypeScript + Vite + Ant Design Vue

## 重要提醒（必读）

### 🚨 接口变更后必须执行的步骤

当后端修改了 API 接口后，**必须**执行以下步骤：

```bash
# 1. 拉取最新代码
git pull

# 2. 更新 API 规范并重新生成类型代码
npm run api:update

# 3. 检查生成的文件
git status
# 应该看到 api-spec.yml 和 src/api/generated/ 下的文件有变化

# 4. 提交所有改动
git add api-spec.yml src/api/generated/
git commit -m "chore(api): 同步最新接口规范"
git push
```

### ⚠️ 如果跳过这一步会发生什么？

- TypeScript 编译报错（类型不匹配）
- 代码中会出现红色波浪线
- CI 检查无法通过

### 🔍 如何确认接口是否有变更？

```bash
# 查看最近提交
git log --oneline -10

# 查看 api-spec.yml 是否有未提交的改动
git diff api-spec.yml

# 查看生成的文件是否与远程一致
git status src/api/generated/
```

## 本地开发

### 环境要求

- Node.js 18+
- npm 9+

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
npm run dev
```

访问：http://localhost:5173

## 构建生产版本

```bash
npm run build
```

## API 相关命令

| 命令 | 说明 |
|------|------|
| `npm run dev` | 启动开发服务器 |
| `npm run build` | 构建生产版本 |
| `npm run api:fetch` | 从后端拉取最新 API 规范 (api-spec.json) |
| `npm run api:gen` | 根据规范生成 TypeScript 代码 |
| `npm run api:update` | **拉取 + 生成**（后端改接口后必须执行） |

## 项目结构

```
reading-platform-frontend/
├── src/
│   ├── views/        # 页面组件
│   │   ├── admin/    # 超管功能
│   │   ├── school/   # 学校管理
│   │   ├── teacher/  # 教师功能
│   │   └── parent/   # 家长功能
│   ├── api/
│   │   ├── generated/  # ⚠️ 自动生成，不要手动修改
│   │   └── index.ts    # axios 实例
│   └── stores/       # Pinia 状态管理
├── api-spec.yml      # ⚠️ OpenAPI 规范（后端更新后提交）
└── orval.config.ts   # API 代码生成配置
```

## 注意事项

1. **不要手动修改** `src/api/generated/` 下的文件
2. **不要提交** 修改后的 `api-spec.yml` 但不提交 `generated/`
3. 每次开始工作前先执行 `git pull && npm run api:update`
4. 提交代码前使用 `git status` 检查是否有多余/遗漏的文件

## 常见问题

**Q：运行 `npm run api:update` 报错？**
- 确认后端正在运行：http://8.148.151.56:3002
- 或者直接 `git pull` 使用已提交的规范，运行 `npm run api:gen`

**Q：TypeScript 报错类型不匹配？**
- 说明后端接口有变化
- 执行 `npm run api:update` 重新生成类型

**Q：想查看某个接口的详细参数？**
- 打开 `src/api/generated/api.ts` 查看
- 或访问 http://8.148.151.56:3002/doc.html