diff --git a/docs/开发协作指南.md b/docs/开发协作指南.md new file mode 100644 index 0000000..1c67360 --- /dev/null +++ b/docs/开发协作指南.md @@ -0,0 +1,401 @@ +# 少儿智慧阅读平台 · 开发协作指南 + +> 本文档面向：**后端工程师、前端工程师、测试工程师、原型开发工程师** +> 目标：让每个人清楚自己该做什么、怎么做，无需反复沟通。 + +--- + +## 一、项目概览 + +### 线上访问地址 + +| 用途 | 地址 | +|---|---| +| **前端页面** | http://8.148.151.56:8081 | +| **接口文档** | http://8.148.151.56:3002/doc.html | +| **代码仓库** | http://8.148.151.56:3000/tonytech/kindergarten_java | + +### 测试账号 + +| 角色 | 账号 | 密码 | +|---|---|---| +| 超级管理员 | admin | admin123 | +| 学校管理员 | school | 123456 | +| 教师 | teacher1 | 123456 | +| 家长 | parent1 | 123456 | + +### 技术栈 + +| 层级 | 技术 | +|---|---| +| 前端 | Vue 3 + TypeScript + Ant Design Vue + Vite | +| 后端 | Java 17 + Spring Boot 3 + MyBatis-Plus | +| 数据库 | MySQL 8.0 | +| 部署 | Docker + Nginx | + +--- + +## 二、环境准备（所有人） + +### 1. 安装 Git + +- Windows：https://git-scm.com/download/win +- Mac：`brew install git` +- 安装后验证：`git --version` + +### 2. 克隆项目 + +```bash +git clone http://tonytech:cnh05791@8.148.151.56:3000/tonytech/kindergarten_java.git +cd kindergarten_java +``` + +### 3. 项目结构 + +``` +kindergarten_java/ +├── reading-platform-java/ # 后端（Java Spring Boot） +│ ├── src/main/java/ # Java 源码 +│ ├── src/main/resources/ # 配置文件、数据库迁移脚本 +│ └── Dockerfile +│ +├── reading-platform-frontend/ # 前端（Vue 3） +│ ├── src/ +│ │ ├── views/ # 页面组件（admin/school/teacher/parent） +│ │ ├── api/ +│ │ │ ├── generated/ # ⚠️ 自动生成，不要手动修改 +│ │ │ └── index.ts # axios 实例配置 +│ │ └── stores/ # Pinia 状态管理 +│ ├── api-spec.yml # OpenAPI 接口规范（后端更新后提交） +│ └── orval.config.ts # API 代码生成配置 +│ +└── docs/ # 项目文档 +``` + +--- + +## 三、核心协作机制 + +本项目采用 **OpenAPI 规范驱动开发**，前后端通过规范文件对齐接口，不需要口头沟通接口格式。 + +``` +后端工程师 前端工程师 + │ │ + │ 写 Java Controller │ + │ + Swagger 注解 │ + │ │ + │ 运行 npm run api:update ───────→│ git pull + │ 提交 api-spec.yml │ src/api/generated/ 自动更新 + │ 提交 generated/ ───────→│ TypeScript 类型保证接口正确 + │ │ + └── 推送到 git → 自动部署上线 ──────┘ +``` + +**前后端唯一的同步方式**：后端改了接口 → 更新 `api-spec.yml` → 前端 `git pull` → TypeScript 报错的地方 = 需要适配的地方。 + +--- + +## 四、后端工程师 + +### 开发环境要求 + +- Java 17+（`java -version` 验证） +- Maven 3.8+（`mvn -version` 验证） +- MySQL 8.0（或 Docker 启动） +- IDE：IntelliJ IDEA（推荐） + +### 本地启动 + +```bash +cd reading-platform-java + +# 用 dev 配置（连本地 MySQL） +mvn spring-boot:run -Dspring-boot.run.profiles=dev +``` + +启动后访问： +- 接口文档：http://localhost:8080/doc.html +- OpenAPI 数据：http://localhost:8080/v3/api-docs + +### 新增或修改接口 + +**第一步**：在对应 Controller 里添加方法，写好 Swagger 注解 + +```java +// 示例：新增一个接口 +@Operation(summary = "获取学生列表", description = "支持分页和姓名搜索") +@GetMapping("/students") +public Result> getStudents( + @Parameter(description = "页码，从1开始") @RequestParam(defaultValue = "1") int page, + @Parameter(description = "每页数量") @RequestParam(defaultValue = "10") int size, + @Parameter(description = "姓名关键词") @RequestParam(required = false) String name +) { + return Result.success(studentService.getPage(page, size, name)); +} +``` + +**第二步**：接口写好后，更新前端的规范文件 + +```bash +# 在 reading-platform-frontend 目录下执行 +cd ../reading-platform-frontend +npm install # 首次需要安装依赖 +npm run api:update # 拉取最新规范 + 重新生成 TypeScript 代码 +``` + +**第三步**：提交所有变更 + +```bash +cd .. # 回到项目根目录 +git add reading-platform-java/ +git add reading-platform-frontend/api-spec.yml +git add reading-platform-frontend/src/api/generated/ +git commit -m "feat(backend): 新增学生列表接口" +git push origin main +``` + +> 推送后服务器会**自动部署**，约 2-3 分钟生效。 + +### 数据库变更 + +所有数据库改动必须通过 Flyway 迁移脚本，**不要直接在数据库里改表结构**。 + +```bash +# 新建迁移脚本（文件名按序号递增） +touch reading-platform-java/src/main/resources/db/migration/V7__your_description.sql +``` + +```sql +-- V7__add_student_grade.sql 示例 +ALTER TABLE students ADD COLUMN grade VARCHAR(20) COMMENT '年级'; +``` + +脚本提交后，后端启动时 Flyway 会自动执行。 + +--- + +## 五、前端工程师 + +### 开发环境要求 + +- Node.js 18+（`node -v` 验证） +- npm 9+（`npm -v` 验证） +- IDE：VS Code（推荐安装 Volar 插件） + +### 本地启动 + +```bash +cd reading-platform-frontend +npm install +npm run dev +``` + +访问：http://localhost:5173（本地开发，自动代理到测试服务器接口） + +### 调用接口的正确方式 + +**使用自动生成的函数**，不要手写 axios 请求： + +```typescript +// ✅ 正确：用生成的函数，有完整类型提示 +import { getStudentPage } from '@/api/generated/api' +import type { Student } from '@/api/generated/model' + +const { data } = await getStudentPage({ page: 1, size: 10, name: '张' }) +// data 类型自动推断为 PageResult + +// ❌ 错误：不要手写请求 +const res = await request.get('/api/v1/school/students', { params: { page: 1 } }) +``` + +### 获取最新接口定义 + +当后端提交了接口变更后： + +```bash +git pull # 拉取最新代码 +# src/api/generated/ 已自动更新，TypeScript 报红的地方 = 需要适配的地方 +``` + +> 如果遇到 TypeScript 编译报错，说明接口有变化，根据错误提示修改调用代码即可。**不需要问后端接口格式**，类型定义就是答案。 + +### 新增页面 + +``` +src/views/ +├── admin/ # 超管功能 +├── school/ # 学校管理功能 +├── teacher/ # 教师功能 +└── parent/ # 家长功能 +``` + +在对应目录下新建 `.vue` 文件，然后在 `src/router/index.ts` 注册路由。 + +### 提交代码 + +```bash +git add reading-platform-frontend/src/ +git commit -m "feat(frontend): 新增学生列表页面" +git push origin main +``` + +--- + +## 六、测试工程师 + +### 接口测试 + +直接使用接口文档页面测试，无需额外工具： + +1. 打开 http://8.148.151.56:3002/doc.html +2. 点击右上角「调试」或接口右侧「测试」 +3. 填写参数，点击「发送」 +4. 查看响应结果 + +**登录获取 Token**（测试需要鉴权的接口）： + +1. 找到 `Auth → 登录` 接口 +2. 发送登录请求，复制响应中的 `token` +3. 点击右上角「Authorize」，填入 `Bearer {token}` +4. 之后所有请求都会自动带上 Token + +### 前端功能测试 + +- 测试地址：http://8.148.151.56:8081 +- 每次有代码推送后约 2-3 分钟自动更新 + +### 提 Bug + +在 git 仓库提 Issue，描述： +1. 操作步骤 +2. 期望结果 +3. 实际结果 +4. 截图（如有） + +--- + +## 七、原型开发工程师 + +原型工程师需要同时改前端页面和后端逻辑，按以下流程操作。 + +### 修改前端页面（无接口变更） + +```bash +# 直接修改 src/views/ 下的 .vue 文件 +git add reading-platform-frontend/src/views/ +git commit -m "feat(ui): 修改学生列表页布局" +git push origin main +``` + +### 修改涉及接口变更 + +按以下顺序操作： + +``` +① 修改后端 Java 代码（Controller / Service / Entity） +② 本地启动后端验证接口正常 +③ 更新接口规范：cd reading-platform-frontend && npm run api:update +④ 修改前端页面，使用新的接口函数 +⑤ 一次性提交所有改动 +``` + +```bash +git add reading-platform-java/src/ +git add reading-platform-frontend/api-spec.yml +git add reading-platform-frontend/src/api/generated/ +git add reading-platform-frontend/src/views/ +git commit -m "feat: 学生列表新增年级筛选功能" +git push origin main +``` + +### 修改数据库结构 + +1. 新建 Flyway 脚本（`V7__描述.sql`） +2. 本地验证迁移脚本正确 +3. 随代码一起提交 + +```bash +git add reading-platform-java/src/main/resources/db/migration/ +git commit -m "feat(db): 学生表新增年级字段" +``` + +--- + +## 八、Git 提交规范 + +### 提交信息格式 + +``` +类型(范围): 简短描述 + +类型： + feat 新功能 + fix Bug 修复 + chore 配置、依赖等杂项 + refactor 重构（不影响功能） + docs 文档修改 +``` + +### 示例 + +```bash +feat(backend): 新增课程评价接口 +feat(frontend): 新增课程评价页面 +fix(backend): 修复分页参数未生效的问题 +feat: 学生档案新增健康信息字段 # 前后端同时改 +chore(api): 同步最新接口规范 +``` + +### 常用 Git 命令 + +```bash +git pull # 拉取最新代码（每天开始工作前执行） +git status # 查看当前改了哪些文件 +git add 文件路径 # 暂存指定文件 +git add reading-platform-frontend/ # 暂存整个目录 +git commit -m "feat: 描述" # 提交 +git push origin main # 推送到服务器（触发自动部署） +git log --oneline -10 # 查看最近10条提交记录 +git diff # 查看未提交的改动 +``` + +--- + +## 九、自动部署说明 + +推送代码后服务器会自动完成部署，**无需手动操作**。 + +``` +git push origin main + ↓ 约 2-3 分钟 +服务器自动：git pull → docker build → docker restart + ↓ +http://8.148.151.56:8081 更新完成 +``` + +如果推送后超过 5 分钟页面未更新，可能是构建失败，联系管理员查看日志。 + +--- + +## 十、常见问题 + +**Q：推送失败，提示"rejected"** +```bash +git pull --rebase # 先拉取最新代码，合并后再推送 +git push origin main +``` + +**Q：本地启动后端报数据库连接失败** +- 确认本地 MySQL 已启动 +- 检查 `application-dev.yml` 中数据库账号密码是否正确 + +**Q：运行 `npm run api:update` 报错** +- 确认服务器后端正在运行（http://8.148.151.56:3002 可访问） +- 或直接 `git pull` 使用已提交的 `api-spec.yml`，运行 `npm run api:gen` + +**Q：前端 TypeScript 报错，提示类型不匹配** +- 这是正常现象，说明后端接口有变化 +- 查看 `src/api/generated/` 里的新类型定义，按提示修改调用代码 + +**Q：想查看某个接口的详细参数** +- 打开 http://8.148.151.56:3002/doc.html 查看