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. 克隆项目

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

### 协作模式说明

#### 为什么选择 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）

```bash
# 在项目根目录执行
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 脚本，提交代码后由**服务器**自动执行迁移。

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

```bash
docker compose up --build backend
```

### 新增或修改接口

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

### 新功能开发检查清单

| 步骤 | 前端工程师 | 后端工程师 | 说明 |
|-----|-----------|-----------|------|
| 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 数据：

```typescript
// 使用 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` 注册路由。

### 提交代码

```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：本地启动后端报数据库连接失败**
- 确认能访问开发服务器：`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 查看