docs: 新增开发协作指南（前后端/测试/原型工程师）
This commit is contained in:
parent
076d832a42
commit
3f3ed084f7
401
docs/开发协作指南.md
Normal file
401
docs/开发协作指南.md
Normal file
@ -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<PageResult<Student>> 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<Student>
|
||||
|
||||
// ❌ 错误：不要手写请求
|
||||
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 查看
|
||||
Loading…
Reference in New Issue
Block a user