En
745f4e4b06
- 添加 api-generator.bat/api-generator.sh 脚本，简化后端接口修改后的前端 API 同步流程 - 新增 reading-platform-frontend/README.md，说明 API 开发协作规范 - 更新 docs/开发协作指南.md，补充协作模式说明和新功能开发检查清单 - 同步最新 API 规范和生成的 TypeScript 类型代码 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
122 lines
2.9 KiB
Markdown
122 lines
2.9 KiB
Markdown
# 少儿智慧阅读平台 - 前端
|
||
|
||
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
|