kindergarten_java/reading-platform-frontend/README.md

少儿智慧阅读平台 - 前端

Vue 3 + TypeScript + Vite + Ant Design Vue

重要提醒（必读）

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

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

# 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 检查无法通过

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

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

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

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

本地开发

环境要求

• Node.js 18+
• npm 9+

安装依赖

npm install

启动开发服务器

npm run dev

访问：http://localhost:5173

构建生产版本

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