kindergarten_java/docs/开发协作指南.md

少儿智慧阅读平台 · 开发协作指南

本文档面向：后端工程师、前端工程师、测试工程师、原型开发工程师 目标：让每个人清楚自己该做什么、怎么做，无需反复沟通。

---

一、项目概览

线上访问地址

用途	地址
前端页面	http://8.148.151.56:8081
接口文档	http://8.148.151.56:3002/doc.html
代码仓库	http://8.148.151.56:3000/tonytech/kindergarten_java

共享数据库（开发服务器）

本地开发和服务器共用同一个数据库，数据实时同步。

项目	值
Host	8.148.151.56
Port	3306
数据库名	reading_platform
用户名	root
密码	reading_platform_pwd
JDBC URL	jdbc:mysql://8.148.151.56:3306/reading_platform?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true

用 DBeaver / Navicat / TablePlus 等 GUI 工具填入以上信息即可直连查看数据。

测试账号

角色	账号	密码
超级管理员	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. 克隆项目

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 报错的地方 = 需要适配的地方。

协作模式说明

为什么选择 OpenAPI 规范驱动开发？

协作方式	优点	缺点	适用场景
OpenAPI 规范驱动（当前）	类型安全、零沟通成本、可并行开发	需要遵守规范	推荐：常规功能开发
一人全流程开发	速度快（单人）	资源浪费、难以深度优化	仅适用于原型验证
按模块一人包干	责任清晰	接口对齐成本高、错误发现晚	不推荐

关键优势：

1. 类型安全 - TypeScript 自动校验接口参数和返回值
2. 零沟通成本 - 接口定义就是 contract，不需要问"这个字段要不要"
3. 并行开发 - 后端写接口时，前端可以基于规范提前写页面框架
4. 自动同步 - npm run api:update 一键同步，不会有人用旧接口

---

四、后端工程师

新功能开发检查清单

步骤	后端工程师	前端工程师	说明
1. 需求确认	评估接口可行性	评估页面结构	确保需求可实现
2. 接口设计	写 Swagger 注解	确认接口需求	api-spec.yml 作为 contract
3. 代码开发	实现 Controller	开发 Vue 页面	可并行开发
4. 本地联调	docker compose up	npm run dev	对齐测试账号登录
5. 提交代码	提交后端代码	Git Pull 后提交	一次性提交所有改动

开发环境要求

• Docker Desktop（必须，用于本地启动服务）
• IDE：IntelliJ IDEA（推荐，用于编写 Java 代码）
• Java 17+ / Maven 3.8+（可选，仅在需要 IDE 内直接运行时安装）

本地启动（推荐：Docker Compose）

# 在项目根目录执行
git pull origin main
docker compose up --build

启动完成后（约 2-3 分钟，看到 Started ReadingPlatformApplication 日志）访问：

• 本地前端：http://localhost:3000
• 本地接口文档：http://localhost:8080/doc.html

数据库说明：本地后端直接连接开发服务器的共享数据库（8.148.151.56:3306）， 本地和服务器数据完全同步，在本地创建的数据在服务器也能看到，反之亦然。

注意：本地 Flyway 自动迁移已关闭（SPRING_FLYWAY_ENABLED=false）。 需要新增数据库字段时，先在本地写好 SQL 脚本，提交代码后由服务器自动执行迁移。

仅启动后端（不重新构建前端）

docker compose up --build backend

新增或修改接口

第一步：在对应 Controller 里添加方法，写好 Swagger 注解

// 示例：新增一个接口
@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));
}

第二步：接口写好后，更新前端的规范文件

# 在 reading-platform-frontend 目录下执行
cd ../reading-platform-frontend
npm install          # 首次需要安装依赖
npm run api:update   # 拉取最新规范 + 重新生成 TypeScript 代码

第三步：提交所有变更

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 迁移脚本，不要直接在数据库里改表结构。

# 新建迁移脚本（文件名按序号递增）
touch reading-platform-java/src/main/resources/db/migration/V7__your_description.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 插件）

本地启动

cd reading-platform-frontend
npm install
npm run dev

访问：http://localhost:5173（本地开发，自动代理到测试服务器接口）

调用接口的正确方式

使用自动生成的函数，不要手写 axios 请求：

// ✅ 正确：用生成的函数，有完整类型提示
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 } })

获取最新接口定义

当后端提交了接口变更后：

git pull                  # 拉取最新代码
# src/api/generated/ 已自动更新，TypeScript 报红的地方 = 需要适配的地方

如果遇到 TypeScript 编译报错，说明接口有变化，根据错误提示修改调用代码即可。不需要问后端接口格式，类型定义就是答案。

新功能开发检查清单

步骤	前端工程师	后端工程师	说明
1. 需求确认	评估页面结构	评估接口可行性	确保需求可实现
2. 接口设计	确认接口需求	写 Swagger 注解	api-spec.yml 作为 contract
3. 代码开发	开发 Vue 页面	实现 Controller	可并行开发
4. 本地联调	npm run dev	docker compose up	对齐测试账号登录
5. 提交代码	Git Pull 后提交	提交后端代码	一次性提交所有改动

前端 Mock 数据（可选）

在后端接口未完成时，前端可基于 api-spec.yml 使用 Mock 数据：

// 使用 mockjs 或 orval 的 mock 功能
import { mockGetStudentPage } from '@/api/generated/mock'

const { data } = await mockGetStudentPage({ page: 1, size: 10 })

新增页面

src/views/
├── admin/      # 超管功能
├── school/     # 学校管理功能
├── teacher/    # 教师功能
└── parent/     # 家长功能

在对应目录下新建 .vue 文件，然后在 src/router/index.ts 注册路由。

提交代码

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. 截图（如有）

---

七、原型开发工程师

原型工程师需要同时改前端页面和后端逻辑，按以下流程操作。

修改前端页面（无接口变更）

# 直接修改 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
④ 修改前端页面，使用新的接口函数
⑤ 一次性提交所有改动

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. 随代码一起提交

git add reading-platform-java/src/main/resources/db/migration/
git commit -m "feat(db): 学生表新增年级字段"

---

八、Git 提交规范

提交信息格式

类型(范围): 简短描述

类型：
  feat      新功能
  fix       Bug 修复
  chore     配置、依赖等杂项
  refactor  重构（不影响功能）
  docs      文档修改

示例

feat(backend): 新增课程评价接口
feat(frontend): 新增课程评价页面
fix(backend): 修复分页参数未生效的问题
feat: 学生档案新增健康信息字段   # 前后端同时改
chore(api): 同步最新接口规范

常用 Git 命令

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"

git pull --rebase   # 先拉取最新代码，合并后再推送
git push origin main

Q：本地启动后端报数据库连接失败

• 确认能访问开发服务器：ping 8.148.151.56
• 确认开发服务器 MySQL 容器正在运行（联系管理员）
• 检查 docker-compose.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 查看