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
|