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

---

四、后端工程师

开发环境要求

• 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 编译报错，说明接口有变化，根据错误提示修改调用代码即可。不需要问后端接口格式，类型定义就是答案。

新增页面

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 查看