# 前端 API 路径对齐修复总结

## 修复日期
2026-03-13

## 问题背景

后端所有 Controller 统一使用 `/api/v1/` 前缀：
- 超管端：`/api/v1/admin/*`
- 学校端：`/api/v1/school/*`
- 教师端：`/api/v1/teacher/*`
- 家长端：`/api/v1/parent/*`
- 认证：`/api/v1/auth/*`
- 文件：`/api/v1/files/*`

但前端适配层的 API 路径缺少 `/v1` 前缀，导致请求失败。

## 修复的文件

### 1. 适配层文件（手动修复）

| 文件 | 修复内容 |
|------|----------|
| `src/api/auth.ts` | `/auth/xxx` → `/v1/auth/xxx` |
| `src/api/school.ts` | `/school/xxx` → `/v1/school/xxx` |
| `src/api/teacher.ts` | 使用生成的 API，无需手动修复 |
| `src/api/parent.ts` | `/parent/xxx` → `/v1/parent/xxx` |
| `src/api/growth.ts` | `/school/xxx` → `/v1/school/xxx`<br>`/teacher/xxx` → `/v1/teacher/xxx` |
| `src/api/task.ts` | `/school/xxx` → `/v1/school/xxx`<br>`/teacher/xxx` → `/v1/teacher/xxx` |
| `src/api/resource.ts` | `/admin/xxx` → `/v1/admin/xxx` |
| `src/api/package.ts` | `/school/xxx` → `/v1/school/xxx` |
| `src/api/file.ts` | 已正确使用 `/api/v1/files` ✅ |

### 2. 生成的 API 文件（自动修复）

| 文件 | 修复方式 |
|------|----------|
| `src/api/generated/index.ts` | 使用 sed 批量替换：<br>`/api/xxx` → `/api/v1/xxx` |

### 3. Orval 配置（预防未来问题）

| 文件 | 修复内容 |
|------|----------|
| `orval.config.ts` | 添加 transformer 配置，在生成时自动修复路径 |

## 验证方法

### 1. 启动服务
```bash
# 启动后端
cd reading-platform-java
mvn spring-boot:run

# 启动前端（新终端）
cd reading-platform-frontend
npm run dev
```

### 2. 测试 API 调用
使用浏览器开发者工具检查 API 请求路径：
- 登录功能（`/v1/auth/login`）
- 学校端接口（`/v1/school/xxx`）
- 教师端接口（`/v1/teacher/xxx`）
- 家长端接口（`/v1/parent/xxx`）
- 超管端接口（`/v1/admin/xxx`）

### 3. 运行 E2E 测试
```bash
npm run test:e2e
```

## 注意事项

1. **生成的 API 文件**: `src/api/generated/index.ts` 是 Orval 自动生成的，不应手动修改
2. **重新生成**: 当需要重新生成 API 时，确保后端服务正在运行，然后执行：
   ```bash
   npm run api:update
   ```
3. **orval 配置**: `orval.config.ts` 中已添加 transformer，下次生成时会自动修复路径

## 修复完成检查清单

- [x] auth.ts API 路径修复
- [x] school.ts API 路径修复
- [x] parent.ts API 路径修复
- [x] growth.ts API 路径修复
- [x] task.ts API 路径修复
- [x] resource.ts API 路径修复
- [x] package.ts API 路径修复
- [x] generated/index.ts 路径修复
- [x] orval.config.ts 配置更新