pangu-user-platform/docs/05-技术方案/基础数据模块技术方案_v1.0.md

# 盘古用户平台 - 基础数据模块技术方案

---

| 文档信息     | 内容                                |
| -------- | --------------------------------- |
| **文档版本** | V1.0                              |
| **项目名称** | 盘古用户平台（Pangu User Platform）       |
| **模块名称** | 基础数据管理（年级、班级、学科、区域）               |
| **编写团队** | pangu                             |
| **创建日期** | 2026-01-31                        |
| **审核状态** | 待评审                               |

---

## 修订记录

| 版本   | 日期         | 修订人   | 修订内容 |
| ---- | ---------- | ----- | ---- |
| V1.0 | 2026-01-31 | pangu | 初稿   |

---

## 目录

1. [模块概述](#1-模块概述)
2. [需求分析](#2-需求分析)
3. [系统设计](#3-系统设计)
4. [前端技术方案](#4-前端技术方案)
5. [后端技术方案](#5-后端技术方案)
6. [数据库设计](#6-数据库设计)
7. [接口设计](#7-接口设计)
8. [开发计划](#8-开发计划)
9. [测试方案](#9-测试方案)
10. [风险与应对](#10-风险与应对)

---

## 1. 模块概述

### 1.1 模块定位

基础数据模块是盘古用户平台的核心支撑模块，负责管理系统运行所需的基础字典数据。这些数据被学校管理、学生管理等业务模块广泛引用，是整个系统数据完整性的基础保障。

### 1.2 功能范围

| 子模块   | 功能描述              | 数据特性     |
| ----- | ----------------- | -------- |
| 年级管理  | 管理年级字典数据（一年级~高三等） | 字典型、被学校引用 |
| 班级管理  | 管理班级字典数据（1班~10班等） | 字典型、被学校引用 |
| 学科管理  | 管理学科字典数据（语文、数学等）  | 字典型、被学生引用 |
| 区域管理  | 管理省-市-区三级区域树      | 树形、被学校引用 |

> **说明**：区域管理的核心逻辑是管理每个区域下的学校信息，区域只被学校表直接引用，会员和学生通过学校间接关联区域。

### 1.3 关联关系

```
基础数据模块关联图：

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   年级管理    │────▶│  学校-年级    │────▶│   学校管理    │
│  (pg_grade) │     │ 关联表       │     │ (pg_school) │
└─────────────┘     └─────────────┘     └─────────────┘
                            │
                            ▼
┌─────────────┐     ┌─────────────┐
│   班级管理    │────▶│  学校-班级    │
│  (pg_class) │     │ 关联表       │
└─────────────┘     └─────────────┘
                            │
                            ▼
┌─────────────┐     ┌─────────────┐
│   学科管理    │────▶│   学生管理    │
│ (pg_subject)│     │ (pg_student)│
└─────────────┘     └─────────────┘

┌─────────────┐
│   区域管理    │────▶ 学校（区域ID）
│ (pg_region) │
└─────────────┘

> 区域通过学校间接关联会员和学生，删除区域时只需检查学校引用
```

---

## 2. 需求分析

### 2.1 功能需求

#### 2.1.1 年级管理

| 功能编号    | 功能名称   | 功能描述            | 优先级 |
| ------- | ------ | --------------- | :-: |
| GRD-001 | 年级列表查询 | 按名称、编码、状态筛选分页查询 | P0  |
| GRD-002 | 新增年级   | 创建年级，编码自动生成     | P0  |
| GRD-003 | 编辑年级   | 修改年级名称、排序、状态    | P0  |
| GRD-004 | 删除年级   | 软删除（需检查学校引用）    | P1  |
| GRD-005 | 年级选项   | 供下拉选择使用的选项列表    | P0  |

**业务规则：**
- 年级编码自动生成，格式：GRD + 3位序号（如GRD001）
- 删除前检查是否被学校-年级关联表引用，有则不允许删除
- 所有删除为软删除（del_flag = 1）

#### 2.1.2 班级管理

| 功能编号    | 功能名称   | 功能描述            | 优先级 |
| ------- | ------ | --------------- | :-: |
| CLS-001 | 班级列表查询 | 按名称、编码、状态筛选分页查询 | P0  |
| CLS-002 | 新增班级   | 创建班级，编码自动生成     | P0  |
| CLS-003 | 编辑班级   | 修改班级名称、排序、状态    | P0  |
| CLS-004 | 删除班级   | 软删除（需检查学校引用）    | P1  |
| CLS-005 | 班级选项   | 供下拉选择使用的选项列表    | P0  |

**业务规则：**
- 班级编码自动生成，格式：CLS + 3位序号（如CLS001）
- 删除前检查是否被学校-班级关联表引用，有则不允许删除

#### 2.1.3 学科管理

| 功能编号    | 功能名称   | 功能描述            | 优先级 |
| ------- | ------ | --------------- | :-: |
| SUB-001 | 学科列表查询 | 按名称、编码、状态筛选分页查询 | P0  |
| SUB-002 | 新增学科   | 创建学科信息          | P0  |
| SUB-003 | 编辑学科   | 修改学科名称、排序、状态    | P0  |
| SUB-004 | 删除学科   | 软删除（需检查学生引用）    | P1  |
| SUB-005 | 学科选项   | 供下拉选择使用的选项列表    | P0  |

**业务规则：**
- 学科编码自动生成，格式：SUB + 3位序号（如SUB001）
- 删除前检查是否被学生表引用，有则不允许删除

#### 2.1.4 区域管理

| 功能编号    | 功能名称  | 功能描述                | 优先级 |
| ------- | ----- | ------------------- | :-: |
| REG-001 | 区域树查询 | 树形展示省-市-区层级结构       | P0  |
| REG-002 | 新增区域  | 在指定节点下新增区域          | P0  |
| REG-003 | 编辑区域  | 修改区域名称              | P0  |
| REG-004 | 删除区域  | 软删除（需检查子级和学校/会员引用）  | P1  |
| REG-005 | 新增下级  | 在当前区域下新增子区域（自动带入父级） | P0  |

**业务规则：**
- 区域编码自动生成，格式：区分层级
  - 省级：REG + 2位序号（如REG01）
  - 市级：父编码 + 2位序号（如REG0101）
  - 区级：父编码 + 2位序号（如REG010101）
- 新增下级时自动带入父级区域信息
- 删除前检查：
  - 是否有子级区域，有则不允许删除
  - 是否被学校引用，有则不允许删除

### 2.2 角色权限

| 功能     | 超级管理员 | 分公司用户 | 学校用户 |
| ------ | :---: | :---: | :--: |
| 年级管理   | ✓     | ✓     | ✗    |
| 班级管理   | ✓     | ✓     | ✗    |
| 学科管理   | ✓     | ✓     | ✗    |
| 区域管理   | ✓     | ✗     | ✗    |

### 2.3 非功能需求

| 需求类型   | 需求描述            |
| ------ | --------------- |
| 性能需求   | 列表查询响应时间 ≤ 200ms |
| 数据完整性  | 删除前必须检查引用关系     |
| 缓存需求   | 区域树数据需缓存，减少查询压力 |
| 日志需求   | 增删改操作需记录操作日志    |

---

## 3. 系统设计

### 3.1 模块架构

```
基础数据模块架构：

┌─────────────────────────────────────────────────────────────────┐
│                         前端层 (Vue 3)                           │
├────────────────┬────────────────┬───────────────┬───────────────┤
│   GradeView    │   ClassView    │  SubjectView  │  RegionView   │
│   年级管理页面    │   班级管理页面    │   学科管理页面   │   区域管理页面   │
└───────┬────────┴───────┬────────┴───────┬───────┴───────┬───────┘
        │                │                │               │
        ▼                ▼                ▼               ▼
┌─────────────────────────────────────────────────────────────────┐
│                       API层 (Axios)                              │
│     grade.js      class.js      subject.js      region.js       │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      后端层 (Spring Boot)                        │
├────────────────┬────────────────┬───────────────┬───────────────┤
│ GradeController│ ClassController│SubjectController│RegionController│
└───────┬────────┴───────┬────────┴───────┬───────┴───────┬───────┘
        │                │                │               │
        ▼                ▼                ▼               ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Service层                                   │
│   GradeService   ClassService   SubjectService   RegionService  │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Mapper层 (MyBatis Plus)                    │
│   GradeMapper    ClassMapper    SubjectMapper    RegionMapper   │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        MySQL 8.0                                 │
│   pg_grade       pg_class       pg_subject       pg_region      │
└─────────────────────────────────────────────────────────────────┘
```

### 3.2 技术选型

| 层次  | 技术           | 版本    | 说明     |
| --- | ------------ | ----- | ------ |
| 前端  | Vue          | 3.5.x | 视图框架   |
| 前端  | Element Plus | 2.x   | UI组件库  |
| 前端  | Pinia        | 3.x   | 状态管理   |
| 后端  | Spring Boot  | 3.3.x | 应用框架   |
| 后端  | MyBatis Plus | 3.5.x | ORM框架  |
| 数据库 | MySQL        | 8.0   | 关系数据库  |
| 缓存  | Redis        | 7.x   | 区域树缓存  |

### 3.3 目录结构

**前端目录结构：**

```
pangu-ui/src/
├── api/
│   ├── grade.js          # 年级API
│   ├── class.js          # 班级API
│   ├── subject.js        # 学科API
│   └── region.js         # 区域API
├── mock/
│   ├── grade.js          # 年级Mock
│   ├── class.js          # 班级Mock
│   ├── subject.js        # 学科Mock
│   └── region.js         # 区域Mock
└── views/base/
    ├── grade/
    │   └── index.vue     # 年级管理页面
    ├── class/
    │   └── index.vue     # 班级管理页面
    ├── subject/
    │   └── index.vue     # 学科管理页面
    └── region/
        └── index.vue     # 区域管理页面
```

**后端目录结构：**

```
pangu-admin/src/main/java/com/pangu/
├── base/
│   ├── controller/
│   │   ├── GradeController.java
│   │   ├── ClassController.java
│   │   ├── SubjectController.java
│   │   └── RegionController.java
│   ├── service/
│   │   ├── IGradeService.java
│   │   ├── IClassService.java
│   │   ├── ISubjectService.java
│   │   ├── IRegionService.java
│   │   └── impl/
│   │       ├── GradeServiceImpl.java
│   │       ├── ClassServiceImpl.java
│   │       ├── SubjectServiceImpl.java
│   │       └── RegionServiceImpl.java
│   ├── mapper/
│   │   ├── GradeMapper.java
│   │   ├── ClassMapper.java
│   │   ├── SubjectMapper.java
│   │   └── RegionMapper.java
│   └── domain/
│       ├── Grade.java
│       ├── PgClass.java
│       ├── Subject.java
│       └── Region.java
└── resources/mapper/base/
    ├── GradeMapper.xml
    ├── ClassMapper.xml
    ├── SubjectMapper.xml
    └── RegionMapper.xml
```

---

## 4. 前端技术方案

### 4.1 页面设计

#### 4.1.1 年级/班级/学科管理（列表页通用模式）

```
┌─────────────────────────────────────────────────────────────────┐
│ 搜索区域                                                         │
├─────────────────────────────────────────────────────────────────┤
│ [名称输入框] [状态下拉] [搜索按钮] [重置按钮]                       │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ 操作区域                                                         │
├─────────────────────────────────────────────────────────────────┤
│ [新增按钮]                                                       │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ 数据表格                                                         │
├─────────┬─────────┬──────┬──────┬────────────┬─────────────────┤
│ 名称     │ 编码     │ 排序  │ 状态  │ 创建时间    │ 操作           │
├─────────┼─────────┼──────┼──────┼────────────┼─────────────────┤
│ 一年级   │ GRD001  │ 1    │ 正常  │ 2026-01-01 │ [编辑] [删除]   │
│ 二年级   │ GRD002  │ 2    │ 正常  │ 2026-01-01 │ [编辑] [删除]   │
└─────────┴─────────┴──────┴──────┴────────────┴─────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ 分页区域                                                         │
│                          共 12 条  < 1 2 >  10条/页              │
└─────────────────────────────────────────────────────────────────┘
```

#### 4.1.2 区域管理（树形表格模式）

```
┌─────────────────────────────────────────────────────────────────┐
│ 操作区域                                                         │
├─────────────────────────────────────────────────────────────────┤
│ [新增按钮] [展开全部] [折叠全部]                                   │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│ 树形表格                                                         │
├────────────────────┬─────────┬────────────┬────────────────────┤
│ 区域名称            │ 区域编码  │ 创建时间    │ 操作              │
├────────────────────┼─────────┼────────────┼────────────────────┤
│ ▼ 湖北             │ REG01   │ 2026-01-01 │ [新增下级][编辑][删除]│
│   ▼ 武汉           │ REG0101 │ 2026-01-01 │ [新增下级][编辑][删除]│
│     ├ 武昌区        │ REG010101│2026-01-01 │ [编辑][删除]        │
│     ├ 汉口区        │ REG010102│2026-01-01 │ [编辑][删除]        │
│     └ 汉阳区        │ REG010103│2026-01-01 │ [编辑][删除]        │
│   └ 黄冈           │ REG0102 │ 2026-01-01 │ [新增下级][编辑][删除]│
│ ► 北京             │ REG02   │ 2026-01-01 │ [新增下级][编辑][删除]│
└────────────────────┴─────────┴────────────┴────────────────────┘
```

### 4.2 组件设计

#### 4.2.1 通用组件结构

```vue
<!-- views/base/grade/index.vue 示例结构 -->
<template>
  <div class="app-container">
    <!-- 搜索区域 -->
    <el-card shadow="never" class="search-wrapper">
      <el-form :model="queryParams" :inline="true">
        <!-- 搜索表单项 -->
      </el-form>
    </el-card>

    <!-- 表格区域 -->
    <el-card shadow="never" style="margin-top: 12px">
      <!-- 操作按钮 -->
      <el-row :gutter="10" style="margin-bottom: 12px">
        <el-col :span="1.5">
          <el-button type="primary" :icon="Plus" @click="handleAdd">新增</el-button>
        </el-col>
      </el-row>

      <!-- 数据表格 -->
      <el-table v-loading="loading" :data="tableData" border stripe>
        <!-- 表格列定义 -->
      </el-table>

      <!-- 分页组件 -->
      <el-pagination />
    </el-card>

    <!-- 新增/编辑弹窗 -->
    <el-dialog v-model="dialogVisible" :title="dialogTitle">
      <el-form ref="formRef" :model="form" :rules="rules">
        <!-- 表单项 -->
      </el-form>
    </el-dialog>
  </div>
</template>
```

#### 4.2.2 年级管理组件

**核心功能实现：**

```javascript
// 年级管理核心逻辑
const queryParams = ref({
  pageNum: 1,
  pageSize: 10,
  gradeName: '',
  status: ''
})

const form = ref({
  gradeId: null,
  gradeName: '',
  gradeCode: '',
  orderNum: 0,
  status: '0'
})

const rules = {
  gradeName: [
    { required: true, message: '请输入年级名称', trigger: 'blur' },
    { max: 50, message: '年级名称长度不能超过50个字符', trigger: 'blur' }
  ]
}

// 新增时自动生成编码
const handleAdd = () => {
  form.value = {
    gradeId: null,
    gradeName: '',
    gradeCode: '', // 由后端生成
    orderNum: tableData.value.length + 1,
    status: '0'
  }
  dialogVisible.value = true
}

// 删除前检查引用
const handleDelete = async (row) => {
  try {
    await ElMessageBox.confirm(
      `确定要删除年级"${row.gradeName}"吗？删除后不可恢复！`,
      '删除确认',
      { type: 'warning' }
    )
    const res = await deleteGrade(row.gradeId)
    if (res.code === 200) {
      ElMessage.success('删除成功')
      getList()
    } else {
      // 被引用时后端返回错误信息
      ElMessage.error(res.msg || '删除失败')
    }
  } catch {
    // 用户取消
  }
}
```

#### 4.2.3 区域管理组件

**树形表格核心逻辑：**

```javascript
// 区域管理核心逻辑
import { ref, onMounted } from 'vue'
import { getRegionTree, addRegion, updateRegion, deleteRegion } from '@/api/region'

const treeData = ref([])
const expandedRowKeys = ref([])

// 获取区域树
const getTree = async () => {
  const res = await getRegionTree()
  if (res.code === 200) {
    treeData.value = res.data
  }
}

// 新增下级
const handleAddChild = (row) => {
  dialogTitle.value = '新增下级区域'
  form.value = {
    regionId: null,
    parentId: row.regionId,
    regionName: '',
    level: row.level + 1,
    parentName: row.regionName  // 显示用
  }
  dialogVisible.value = true
}

// 展开/折叠全部
const toggleExpandAll = (expand) => {
  if (expand) {
    // 收集所有非叶子节点的ID
    const getAllKeys = (nodes) => {
      let keys = []
      nodes.forEach(node => {
        if (node.children && node.children.length > 0) {
          keys.push(node.regionId)
          keys = keys.concat(getAllKeys(node.children))
        }
      })
      return keys
    }
    expandedRowKeys.value = getAllKeys(treeData.value)
  } else {
    expandedRowKeys.value = []
  }
}

// 删除区域（检查子级）
const handleDelete = async (row) => {
  // 检查是否有子级
  if (row.children && row.children.length > 0) {
    ElMessage.warning('该区域下有子区域，不能删除')
    return
  }
  // 执行删除（后端还会检查是否被学校引用）
  // ...
}
```

### 4.3 API接口封装

#### 4.3.1 年级管理API

```javascript
// api/grade.js
import request from '@/utils/request'

/**
 * 获取年级分页列表
 */
export function getGradeList(params) {
  return request({
    url: '/api/grade/list',
    method: 'get',
    params
  })
}

/**
 * 获取年级选项列表（下拉用）
 */
export function getGradeOptions() {
  return request({
    url: '/api/grade/options',
    method: 'get'
  })
}

/**
 * 获取年级详情
 */
export function getGradeDetail(gradeId) {
  return request({
    url: `/api/grade/${gradeId}`,
    method: 'get'
  })
}

/**
 * 新增年级
 */
export function addGrade(data) {
  return request({
    url: '/api/grade',
    method: 'post',
    data
  })
}

/**
 * 修改年级
 */
export function updateGrade(data) {
  return request({
    url: '/api/grade',
    method: 'put',
    data
  })
}

/**
 * 删除年级
 */
export function deleteGrade(gradeId) {
  return request({
    url: `/api/grade/${gradeId}`,
    method: 'delete'
  })
}
```

#### 4.3.2 区域管理API

```javascript
// api/region.js
import request from '@/utils/request'

/**
 * 获取区域树
 */
export function getRegionTree() {
  return request({
    url: '/api/region/tree',
    method: 'get'
  })
}

/**
 * 获取区域详情
 */
export function getRegionDetail(regionId) {
  return request({
    url: `/api/region/${regionId}`,
    method: 'get'
  })
}

/**
 * 新增区域
 */
export function addRegion(data) {
  return request({
    url: '/api/region',
    method: 'post',
    data
  })
}

/**
 * 修改区域
 */
export function updateRegion(data) {
  return request({
    url: '/api/region',
    method: 'put',
    data
  })
}

/**
 * 删除区域
 */
export function deleteRegion(regionId) {
  return request({
    url: `/api/region/${regionId}`,
    method: 'delete'
  })
}
```

### 4.4 Mock数据

```javascript
// mock/grade.js 示例
import Mock from 'mockjs'

const gradeData = [
  { gradeId: 1, gradeName: '一年级', gradeCode: 'GRD001', orderNum: 1, status: '0', createTime: '2026-01-01 10:00:00' },
  { gradeId: 2, gradeName: '二年级', gradeCode: 'GRD002', orderNum: 2, status: '0', createTime: '2026-01-01 10:00:00' },
  // ...更多数据
]

// 获取年级列表
Mock.mock(/\/api\/grade\/list/, 'get', (options) => {
  const url = new URL('http://localhost' + options.url)
  const gradeName = url.searchParams.get('gradeName') || ''
  const status = url.searchParams.get('status')
  const pageNum = parseInt(url.searchParams.get('pageNum')) || 1
  const pageSize = parseInt(url.searchParams.get('pageSize')) || 10

  let list = gradeData.filter(item => {
    let match = true
    if (gradeName) {
      match = match && item.gradeName.includes(gradeName)
    }
    if (status !== null && status !== '') {
      match = match && item.status === status
    }
    return match
  })

  const total = list.length
  const start = (pageNum - 1) * pageSize
  const rows = list.slice(start, start + pageSize)

  return {
    code: 200,
    msg: '查询成功',
    total,
    rows
  }
})
```

### 4.5 路由配置

```javascript
// router/index.js
{
  path: '/base',
  component: Layout,
  redirect: '/base/grade',
  name: 'Base',
  meta: { title: '基础数据', icon: 'Setting' },
  children: [
    {
      path: 'grade',
      name: 'Grade',
      component: () => import('@/views/base/grade/index.vue'),
      meta: { title: '年级管理' }
    },
    {
      path: 'class',
      name: 'Class',
      component: () => import('@/views/base/class/index.vue'),
      meta: { title: '班级管理' }
    },
    {
      path: 'subject',
      name: 'Subject',
      component: () => import('@/views/base/subject/index.vue'),
      meta: { title: '学科管理' }
    },
    {
      path: 'region',
      name: 'Region',
      component: () => import('@/views/base/region/index.vue'),
      meta: { title: '区域管理' }
    }
  ]
}
```

---

## 5. 后端技术方案

### 5.1 Controller层设计

#### 5.1.1 年级管理Controller

```java
/**
 * 年级管理Controller
 * @author pangu
 */
@RestController
@RequestMapping("/api/grade")
public class GradeController extends BaseController {

    @Autowired
    private IGradeService gradeService;

    /**
     * 获取年级分页列表
     */
    @GetMapping("/list")
    public TableDataInfo list(Grade grade) {
        startPage();
        List<Grade> list = gradeService.selectGradeList(grade);
        return getDataTable(list);
    }

    /**
     * 获取年级选项列表（下拉用）
     */
    @GetMapping("/options")
    public AjaxResult options() {
        List<Grade> list = gradeService.selectGradeOptions();
        return success(list);
    }

    /**
     * 获取年级详情
     */
    @GetMapping("/{gradeId}")
    public AjaxResult getInfo(@PathVariable Long gradeId) {
        return success(gradeService.selectGradeById(gradeId));
    }

    /**
     * 新增年级
     */
    @PostMapping
    @Log(title = "年级管理", businessType = BusinessType.INSERT)
    public AjaxResult add(@Validated @RequestBody Grade grade) {
        // 检查名称是否重复
        if (!gradeService.checkGradeNameUnique(grade)) {
            return error("年级名称已存在");
        }
        grade.setCreateBy(getUsername());
        return toAjax(gradeService.insertGrade(grade));
    }

    /**
     * 修改年级
     */
    @PutMapping
    @Log(title = "年级管理", businessType = BusinessType.UPDATE)
    public AjaxResult edit(@Validated @RequestBody Grade grade) {
        if (!gradeService.checkGradeNameUnique(grade)) {
            return error("年级名称已存在");
        }
        grade.setUpdateBy(getUsername());
        return toAjax(gradeService.updateGrade(grade));
    }

    /**
     * 删除年级
     */
    @DeleteMapping("/{gradeId}")
    @Log(title = "年级管理", businessType = BusinessType.DELETE)
    public AjaxResult remove(@PathVariable Long gradeId) {
        // 检查是否被学校引用
        if (gradeService.checkGradeExistSchool(gradeId)) {
            return error("该年级已被学校使用，不能删除");
        }
        return toAjax(gradeService.deleteGradeById(gradeId));
    }
}
```

#### 5.1.2 区域管理Controller

```java
/**
 * 区域管理Controller
 * @author pangu
 */
@RestController
@RequestMapping("/api/region")
public class RegionController extends BaseController {

    @Autowired
    private IRegionService regionService;

    /**
     * 获取区域树
     */
    @GetMapping("/tree")
    public AjaxResult tree() {
        List<Region> list = regionService.selectRegionTree();
        return success(list);
    }

    /**
     * 获取区域详情
     */
    @GetMapping("/{regionId}")
    public AjaxResult getInfo(@PathVariable Long regionId) {
        return success(regionService.selectRegionById(regionId));
    }

    /**
     * 新增区域
     */
    @PostMapping
    @Log(title = "区域管理", businessType = BusinessType.INSERT)
    public AjaxResult add(@Validated @RequestBody Region region) {
        region.setCreateBy(getUsername());
        return toAjax(regionService.insertRegion(region));
    }

    /**
     * 修改区域
     */
    @PutMapping
    @Log(title = "区域管理", businessType = BusinessType.UPDATE)
    public AjaxResult edit(@Validated @RequestBody Region region) {
        // 父级不能设为自己或自己的子级
        if (region.getParentId().equals(region.getRegionId())) {
            return error("父级区域不能选择自己");
        }
        region.setUpdateBy(getUsername());
        return toAjax(regionService.updateRegion(region));
    }

    /**
     * 删除区域
     */
    @DeleteMapping("/{regionId}")
    @Log(title = "区域管理", businessType = BusinessType.DELETE)
    public AjaxResult remove(@PathVariable Long regionId) {
        // 检查是否有子区域
        if (regionService.hasChildRegion(regionId)) {
            return error("存在下级区域，不能删除");
        }
        // 检查是否被学校/会员引用
        if (regionService.checkRegionExistSchool(regionId)) {
            return error("该区域已被学校使用，不能删除");
        }
        if (regionService.checkRegionExistMember(regionId)) {
            return error("该区域已被会员使用，不能删除");
        }
        return toAjax(regionService.deleteRegionById(regionId));
    }
}
```

### 5.2 Service层设计

#### 5.2.1 年级管理Service

```java
/**
 * 年级管理Service接口
 * @author pangu
 */
public interface IGradeService {
    
    /**
     * 查询年级分页列表
     */
    List<Grade> selectGradeList(Grade grade);
    
    /**
     * 查询年级选项列表
     */
    List<Grade> selectGradeOptions();
    
    /**
     * 查询年级详情
     */
    Grade selectGradeById(Long gradeId);
    
    /**
     * 新增年级
     */
    int insertGrade(Grade grade);
    
    /**
     * 修改年级
     */
    int updateGrade(Grade grade);
    
    /**
     * 删除年级
     */
    int deleteGradeById(Long gradeId);
    
    /**
     * 校验年级名称是否唯一
     */
    boolean checkGradeNameUnique(Grade grade);
    
    /**
     * 检查年级是否被学校使用
     */
    boolean checkGradeExistSchool(Long gradeId);
}
```

```java
/**
 * 年级管理Service实现
 * @author pangu
 */
@Service
public class GradeServiceImpl implements IGradeService {

    @Autowired
    private GradeMapper gradeMapper;
    
    @Autowired
    private SchoolGradeMapper schoolGradeMapper;

    @Override
    public List<Grade> selectGradeList(Grade grade) {
        return gradeMapper.selectGradeList(grade);
    }
    
    @Override
    public List<Grade> selectGradeOptions() {
        Grade grade = new Grade();
        grade.setStatus("0"); // 只查启用的
        return gradeMapper.selectGradeList(grade);
    }

    @Override
    public Grade selectGradeById(Long gradeId) {
        return gradeMapper.selectGradeById(gradeId);
    }

    @Override
    public int insertGrade(Grade grade) {
        // 生成年级编码
        grade.setGradeCode(generateGradeCode());
        grade.setCreateTime(DateUtils.getNowDate());
        return gradeMapper.insertGrade(grade);
    }
    
    /**
     * 生成年级编码：GRD + 3位序号
     */
    private String generateGradeCode() {
        String maxCode = gradeMapper.selectMaxGradeCode();
        if (StringUtils.isEmpty(maxCode)) {
            return "GRD001";
        }
        int num = Integer.parseInt(maxCode.substring(3)) + 1;
        return String.format("GRD%03d", num);
    }

    @Override
    public int updateGrade(Grade grade) {
        grade.setUpdateTime(DateUtils.getNowDate());
        return gradeMapper.updateGrade(grade);
    }

    @Override
    public int deleteGradeById(Long gradeId) {
        return gradeMapper.deleteGradeById(gradeId);
    }

    @Override
    public boolean checkGradeNameUnique(Grade grade) {
        Long gradeId = grade.getGradeId() == null ? -1L : grade.getGradeId();
        Grade info = gradeMapper.checkGradeNameUnique(grade.getGradeName());
        return info == null || info.getGradeId().equals(gradeId);
    }

    @Override
    public boolean checkGradeExistSchool(Long gradeId) {
        int count = schoolGradeMapper.countByGradeId(gradeId);
        return count > 0;
    }
}
```

#### 5.2.2 区域管理Service

```java
/**
 * 区域管理Service接口
 * @author pangu
 */
public interface IRegionService {
    
    /**
     * 查询区域树
     */
    List<Region> selectRegionTree();
    
    /**
     * 查询区域详情
     */
    Region selectRegionById(Long regionId);
    
    /**
     * 新增区域
     */
    int insertRegion(Region region);
    
    /**
     * 修改区域
     */
    int updateRegion(Region region);
    
    /**
     * 删除区域
     */
    int deleteRegionById(Long regionId);
    
    /**
     * 是否存在子区域
     */
    boolean hasChildRegion(Long regionId);
    
    /**
     * 检查区域是否被学校使用
     */
    boolean checkRegionExistSchool(Long regionId);
}
```

```java
/**
 * 区域管理Service实现
 * @author pangu
 */
@Service
public class RegionServiceImpl implements IRegionService {

    @Autowired
    private RegionMapper regionMapper;
    
    @Autowired
    private SchoolMapper schoolMapper;
    
    @Autowired
    private RedisCache redisCache;
    
    private static final String REGION_TREE_KEY = "region_tree";

    @Override
    public List<Region> selectRegionTree() {
        // 优先从缓存获取
        List<Region> cacheList = redisCache.getCacheObject(REGION_TREE_KEY);
        if (cacheList != null) {
            return cacheList;
        }
        
        // 查询所有区域
        List<Region> regionList = regionMapper.selectRegionList(new Region());
        // 构建树形结构
        List<Region> tree = buildRegionTree(regionList);
        
        // 放入缓存（24小时）
        redisCache.setCacheObject(REGION_TREE_KEY, tree, 24, TimeUnit.HOURS);
        
        return tree;
    }
    
    /**
     * 构建区域树
     */
    private List<Region> buildRegionTree(List<Region> regionList) {
        List<Region> rootList = new ArrayList<>();
        Map<Long, Region> regionMap = regionList.stream()
            .collect(Collectors.toMap(Region::getRegionId, r -> r));
        
        for (Region region : regionList) {
            if (region.getParentId() == 0) {
                rootList.add(region);
            } else {
                Region parent = regionMap.get(region.getParentId());
                if (parent != null) {
                    if (parent.getChildren() == null) {
                        parent.setChildren(new ArrayList<>());
                    }
                    parent.getChildren().add(region);
                }
            }
        }
        return rootList;
    }

    @Override
    public int insertRegion(Region region) {
        // 设置层级和祖级列表
        if (region.getParentId() == 0) {
            region.setLevel(1);
            region.setAncestors("0");
        } else {
            Region parent = regionMapper.selectRegionById(region.getParentId());
            region.setLevel(parent.getLevel() + 1);
            region.setAncestors(parent.getAncestors() + "," + parent.getRegionId());
        }
        
        // 生成区域编码
        region.setRegionCode(generateRegionCode(region));
        region.setCreateTime(DateUtils.getNowDate());
        
        int rows = regionMapper.insertRegion(region);
        
        // 清除缓存
        if (rows > 0) {
            redisCache.deleteObject(REGION_TREE_KEY);
        }
        
        return rows;
    }
    
    /**
     * 生成区域编码
     */
    private String generateRegionCode(Region region) {
        if (region.getParentId() == 0) {
            // 省级：REG + 2位序号
            String maxCode = regionMapper.selectMaxCodeByLevel(1);
            if (StringUtils.isEmpty(maxCode)) {
                return "REG01";
            }
            int num = Integer.parseInt(maxCode.substring(3)) + 1;
            return String.format("REG%02d", num);
        } else {
            // 市/区级：父编码 + 2位序号
            Region parent = regionMapper.selectRegionById(region.getParentId());
            String maxCode = regionMapper.selectMaxCodeByParent(region.getParentId());
            if (StringUtils.isEmpty(maxCode)) {
                return parent.getRegionCode() + "01";
            }
            String suffix = maxCode.substring(parent.getRegionCode().length());
            int num = Integer.parseInt(suffix) + 1;
            return parent.getRegionCode() + String.format("%02d", num);
        }
    }

    @Override
    public int updateRegion(Region region) {
        region.setUpdateTime(DateUtils.getNowDate());
        int rows = regionMapper.updateRegion(region);
        
        // 清除缓存
        if (rows > 0) {
            redisCache.deleteObject(REGION_TREE_KEY);
        }
        
        return rows;
    }

    @Override
    public int deleteRegionById(Long regionId) {
        int rows = regionMapper.deleteRegionById(regionId);
        
        // 清除缓存
        if (rows > 0) {
            redisCache.deleteObject(REGION_TREE_KEY);
        }
        
        return rows;
    }

    @Override
    public boolean hasChildRegion(Long regionId) {
        int count = regionMapper.countChildByParentId(regionId);
        return count > 0;
    }

    @Override
    public boolean checkRegionExistSchool(Long regionId) {
        int count = schoolMapper.countByRegionId(regionId);
        return count > 0;
    }
}
```

### 5.3 Mapper层设计

#### 5.3.1 年级Mapper

```java
/**
 * 年级Mapper接口
 * @author pangu
 */
public interface GradeMapper {
    
    /**
     * 查询年级列表
     */
    List<Grade> selectGradeList(Grade grade);
    
    /**
     * 查询年级详情
     */
    Grade selectGradeById(Long gradeId);
    
    /**
     * 新增年级
     */
    int insertGrade(Grade grade);
    
    /**
     * 修改年级
     */
    int updateGrade(Grade grade);
    
    /**
     * 删除年级（软删除）
     */
    int deleteGradeById(Long gradeId);
    
    /**
     * 校验年级名称唯一
     */
    Grade checkGradeNameUnique(String gradeName);
    
    /**
     * 查询最大编码
     */
    String selectMaxGradeCode();
}
```

```xml
<!-- GradeMapper.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" 
  "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.pangu.base.mapper.GradeMapper">

    <resultMap id="GradeResult" type="Grade">
        <id property="gradeId" column="grade_id"/>
        <result property="gradeCode" column="grade_code"/>
        <result property="gradeName" column="grade_name"/>
        <result property="orderNum" column="order_num"/>
        <result property="status" column="status"/>
        <result property="createBy" column="create_by"/>
        <result property="createTime" column="create_time"/>
        <result property="updateBy" column="update_by"/>
        <result property="updateTime" column="update_time"/>
    </resultMap>

    <sql id="selectGradeVo">
        select grade_id, grade_code, grade_name, order_num, status, 
               create_by, create_time, update_by, update_time
        from pg_grade
        where del_flag = '0'
    </sql>

    <select id="selectGradeList" parameterType="Grade" resultMap="GradeResult">
        <include refid="selectGradeVo"/>
        <if test="gradeName != null and gradeName != ''">
            AND grade_name like concat('%', #{gradeName}, '%')
        </if>
        <if test="status != null and status != ''">
            AND status = #{status}
        </if>
        order by order_num
    </select>

    <select id="selectGradeById" parameterType="Long" resultMap="GradeResult">
        <include refid="selectGradeVo"/>
        AND grade_id = #{gradeId}
    </select>

    <insert id="insertGrade" parameterType="Grade" useGeneratedKeys="true" keyProperty="gradeId">
        insert into pg_grade (
            grade_code, grade_name, order_num, status, 
            create_by, create_time, del_flag
        ) values (
            #{gradeCode}, #{gradeName}, #{orderNum}, #{status}, 
            #{createBy}, #{createTime}, '0'
        )
    </insert>

    <update id="updateGrade" parameterType="Grade">
        update pg_grade
        <set>
            <if test="gradeName != null and gradeName != ''">grade_name = #{gradeName},</if>
            <if test="orderNum != null">order_num = #{orderNum},</if>
            <if test="status != null">status = #{status},</if>
            update_by = #{updateBy},
            update_time = #{updateTime}
        </set>
        where grade_id = #{gradeId}
    </update>

    <update id="deleteGradeById" parameterType="Long">
        update pg_grade set del_flag = '1' where grade_id = #{gradeId}
    </update>

    <select id="checkGradeNameUnique" parameterType="String" resultMap="GradeResult">
        <include refid="selectGradeVo"/>
        AND grade_name = #{gradeName}
        limit 1
    </select>

    <select id="selectMaxGradeCode" resultType="String">
        select max(grade_code) from pg_grade where del_flag = '0'
    </select>

</mapper>
```

### 5.4 实体类设计

```java
/**
 * 年级实体类
 * @author pangu
 */
@Data
@TableName("pg_grade")
public class Grade extends BaseEntity {
    
    /** 年级ID */
    @TableId(type = IdType.AUTO)
    private Long gradeId;
    
    /** 年级编码 */
    @NotBlank(message = "年级编码不能为空")
    private String gradeCode;
    
    /** 年级名称 */
    @NotBlank(message = "年级名称不能为空")
    @Size(max = 50, message = "年级名称长度不能超过50个字符")
    private String gradeName;
    
    /** 显示顺序 */
    private Integer orderNum;
    
    /** 状态（0正常 1停用）*/
    private String status;
    
    /** 删除标志（0存在 1删除）*/
    @TableLogic
    private String delFlag;
}
```

```java
/**
 * 区域实体类
 * @author pangu
 */
@Data
@TableName("pg_region")
public class Region extends BaseEntity {
    
    /** 区域ID */
    @TableId(type = IdType.AUTO)
    private Long regionId;
    
    /** 父区域ID */
    private Long parentId;
    
    /** 区域名称 */
    @NotBlank(message = "区域名称不能为空")
    @Size(max = 100, message = "区域名称长度不能超过100个字符")
    private String regionName;
    
    /** 区域编码 */
    private String regionCode;
    
    /** 层级（1省 2市 3区）*/
    private Integer level;
    
    /** 祖级列表 */
    private String ancestors;
    
    /** 显示顺序 */
    private Integer orderNum;
    
    /** 状态（0正常 1停用）*/
    private String status;
    
    /** 删除标志（0存在 1删除）*/
    @TableLogic
    private String delFlag;
    
    /** 子区域 */
    @TableField(exist = false)
    private List<Region> children;
}
```

---

## 6. 数据库设计

### 6.1 表结构

参考《数据库设计文档_v1.0.md》中的：
- `pg_grade` - 年级字典表
- `pg_class` - 班级字典表
- `pg_subject` - 学科表
- `pg_region` - 区域表

### 6.2 初始化数据

#### 6.2.1 年级数据

```sql
INSERT INTO pg_grade (grade_id, grade_code, grade_name, order_num, status, create_time, del_flag) VALUES
(1, 'GRD001', '一年级', 1, '0', NOW(), '0'),
(2, 'GRD002', '二年级', 2, '0', NOW(), '0'),
(3, 'GRD003', '三年级', 3, '0', NOW(), '0'),
(4, 'GRD004', '四年级', 4, '0', NOW(), '0'),
(5, 'GRD005', '五年级', 5, '0', NOW(), '0'),
(6, 'GRD006', '六年级', 6, '0', NOW(), '0'),
(7, 'GRD007', '七年级', 7, '0', NOW(), '0'),
(8, 'GRD008', '八年级', 8, '0', NOW(), '0'),
(9, 'GRD009', '九年级', 9, '0', NOW(), '0'),
(10, 'GRD010', '高一', 10, '0', NOW(), '0'),
(11, 'GRD011', '高二', 11, '0', NOW(), '0'),
(12, 'GRD012', '高三', 12, '0', NOW(), '0');
```

#### 6.2.2 班级数据

```sql
INSERT INTO pg_class (class_id, class_code, class_name, order_num, status, create_time, del_flag) VALUES
(1, 'CLS001', '1班', 1, '0', NOW(), '0'),
(2, 'CLS002', '2班', 2, '0', NOW(), '0'),
(3, 'CLS003', '3班', 3, '0', NOW(), '0'),
(4, 'CLS004', '4班', 4, '0', NOW(), '0'),
(5, 'CLS005', '5班', 5, '0', NOW(), '0'),
(6, 'CLS006', '6班', 6, '0', NOW(), '0'),
(7, 'CLS007', '7班', 7, '0', NOW(), '0'),
(8, 'CLS008', '8班', 8, '0', NOW(), '0'),
(9, 'CLS009', '9班', 9, '0', NOW(), '0'),
(10, 'CLS010', '10班', 10, '0', NOW(), '0');
```

#### 6.2.3 学科数据

```sql
INSERT INTO pg_subject (subject_id, subject_code, subject_name, order_num, status, create_time, del_flag) VALUES
(1, 'SUB001', '语文', 1, '0', NOW(), '0'),
(2, 'SUB002', '数学', 2, '0', NOW(), '0'),
(3, 'SUB003', '英语', 3, '0', NOW(), '0'),
(4, 'SUB004', '物理', 4, '0', NOW(), '0'),
(5, 'SUB005', '化学', 5, '0', NOW(), '0'),
(6, 'SUB006', '生物', 6, '0', NOW(), '0'),
(7, 'SUB007', '历史', 7, '0', NOW(), '0'),
(8, 'SUB008', '地理', 8, '0', NOW(), '0'),
(9, 'SUB009', '政治', 9, '0', NOW(), '0'),
(10, 'SUB010', '体育', 10, '0', NOW(), '0'),
(11, 'SUB011', '音乐', 11, '0', NOW(), '0'),
(12, 'SUB012', '美术', 12, '0', NOW(), '0');
```

#### 6.2.4 区域数据

```sql
-- 省级
INSERT INTO pg_region (region_id, parent_id, region_name, region_code, level, ancestors, order_num, status, create_time, del_flag) VALUES
(1, 0, '湖北', 'REG01', 1, '0', 1, '0', NOW(), '0'),
(2, 0, '北京', 'REG02', 1, '0', 2, '0', NOW(), '0'),
(3, 0, '香港', 'REG03', 1, '0', 3, '0', NOW(), '0'),
(4, 0, '吉宁', 'REG04', 1, '0', 4, '0', NOW(), '0');

-- 市级（湖北）
INSERT INTO pg_region (region_id, parent_id, region_name, region_code, level, ancestors, order_num, status, create_time, del_flag) VALUES
(11, 1, '武汉', 'REG0101', 2, '0,1', 1, '0', NOW(), '0'),
(12, 1, '黄冈', 'REG0102', 2, '0,1', 2, '0', NOW(), '0');

-- 区级（武汉）
INSERT INTO pg_region (region_id, parent_id, region_name, region_code, level, ancestors, order_num, status, create_time, del_flag) VALUES
(111, 11, '武昌区', 'REG010101', 3, '0,1,11', 1, '0', NOW(), '0'),
(112, 11, '汉口区', 'REG010102', 3, '0,1,11', 2, '0', NOW(), '0'),
(113, 11, '汉阳区', 'REG010103', 3, '0,1,11', 3, '0', NOW(), '0'),
(114, 11, '江夏区', 'REG010104', 3, '0,1,11', 4, '0', NOW(), '0'),
(115, 11, '新洲区', 'REG010105', 3, '0,1,11', 5, '0', NOW(), '0'),
(116, 11, '黄陂区', 'REG010106', 3, '0,1,11', 6, '0', NOW(), '0');

-- 区级（黄冈）
INSERT INTO pg_region (region_id, parent_id, region_name, region_code, level, ancestors, order_num, status, create_time, del_flag) VALUES
(121, 12, '黄州区', 'REG010201', 3, '0,1,12', 1, '0', NOW(), '0'),
(122, 12, '红安县', 'REG010202', 3, '0,1,12', 2, '0', NOW(), '0'),
(123, 12, '麻城市', 'REG010203', 3, '0,1,12', 3, '0', NOW(), '0');
```

---

## 7. 接口设计

### 7.1 接口清单

#### 7.1.1 年级管理接口

| 接口地址                 | 方法     | 说明       |
| -------------------- | ------ | -------- |
| GET /api/grade/list  | GET    | 获取年级分页列表 |
| GET /api/grade/options | GET  | 获取年级选项列表 |
| GET /api/grade/{id}  | GET    | 获取年级详情   |
| POST /api/grade      | POST   | 新增年级     |
| PUT /api/grade       | PUT    | 修改年级     |
| DELETE /api/grade/{id} | DELETE | 删除年级     |

#### 7.1.2 班级管理接口

| 接口地址                 | 方法     | 说明       |
| -------------------- | ------ | -------- |
| GET /api/class/list  | GET    | 获取班级分页列表 |
| GET /api/class/options | GET  | 获取班级选项列表 |
| GET /api/class/{id}  | GET    | 获取班级详情   |
| POST /api/class      | POST   | 新增班级     |
| PUT /api/class       | PUT    | 修改班级     |
| DELETE /api/class/{id} | DELETE | 删除班级     |

#### 7.1.3 学科管理接口

| 接口地址                   | 方法     | 说明       |
| ---------------------- | ------ | -------- |
| GET /api/subject/list  | GET    | 获取学科分页列表 |
| GET /api/subject/options | GET  | 获取学科选项列表 |
| GET /api/subject/{id}  | GET    | 获取学科详情   |
| POST /api/subject      | POST   | 新增学科     |
| PUT /api/subject       | PUT    | 修改学科     |
| DELETE /api/subject/{id} | DELETE | 删除学科     |

#### 7.1.4 区域管理接口

| 接口地址                  | 方法     | 说明     |
| --------------------- | ------ | ------ |
| GET /api/region/tree  | GET    | 获取区域树  |
| GET /api/region/{id}  | GET    | 获取区域详情 |
| POST /api/region      | POST   | 新增区域   |
| PUT /api/region       | PUT    | 修改区域   |
| DELETE /api/region/{id} | DELETE | 删除区域   |

### 7.2 接口详情

#### 7.2.1 获取年级分页列表

**请求**

```
GET /api/grade/list?gradeName=年级&status=0&pageNum=1&pageSize=10
```

**响应**

```json
{
  "code": 200,
  "msg": "查询成功",
  "total": 12,
  "rows": [
    {
      "gradeId": 1,
      "gradeCode": "GRD001",
      "gradeName": "一年级",
      "orderNum": 1,
      "status": "0",
      "createTime": "2026-01-01 10:00:00"
    }
  ]
}
```

#### 7.2.2 新增年级

**请求**

```
POST /api/grade
Content-Type: application/json

{
  "gradeName": "学前班",
  "orderNum": 0,
  "status": "0"
}
```

**响应**

```json
{
  "code": 200,
  "msg": "新增成功"
}
```

#### 7.2.3 删除年级（被引用时）

**请求**

```
DELETE /api/grade/1
```

**响应**

```json
{
  "code": 500,
  "msg": "该年级已被学校使用，不能删除"
}
```

#### 7.2.4 获取区域树

**请求**

```
GET /api/region/tree
```

**响应**

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "regionId": 1,
      "parentId": 0,
      "regionName": "湖北",
      "regionCode": "REG01",
      "level": 1,
      "children": [
        {
          "regionId": 11,
          "parentId": 1,
          "regionName": "武汉",
          "regionCode": "REG0101",
          "level": 2,
          "children": [
            {
              "regionId": 111,
              "parentId": 11,
              "regionName": "武昌区",
              "regionCode": "REG010101",
              "level": 3,
              "children": null
            }
          ]
        }
      ]
    }
  ]
}
```

---

## 8. 开发计划

### 8.1 阶段划分

| 阶段   | 任务                   | 工时    | 交付物                |
| ---- | -------------------- | ----- | ------------------ |
| 阶段一  | 数据库表创建、初始化数据         | 0.5天  | SQL脚本              |
| 阶段二  | 后端接口开发（年级、班级、学科）     | 1天    | Controller/Service |
| 阶段三  | 后端接口开发（区域管理）         | 0.5天  | Controller/Service |
| 阶段四  | 前端页面开发（年级、班级、学科）     | 1天    | Vue页面              |
| 阶段五  | 前端页面开发（区域管理-树形表格）    | 0.5天  | Vue页面              |
| 阶段六  | 联调测试、Bug修复           | 0.5天  | 测试报告               |
| **合计** |                      | **4天** |                    |

### 8.2 里程碑

| 里程碑  | 时间节点       | 交付内容             |
| ---- | ---------- | ---------------- |
| M1   | 第1天结束      | 数据库就绪、后端接口完成     |
| M2   | 第3天结束      | 前端页面完成           |
| M3   | 第4天结束      | 联调测试完成，功能上线      |

### 8.3 任务分解

#### 阶段一：数据库（0.5天）

- [x] 创建 pg_grade 表
- [x] 创建 pg_class 表
- [x] 创建 pg_subject 表
- [x] 创建 pg_region 表
- [x] 初始化年级数据（12条）
- [x] 初始化班级数据（10条）
- [x] 初始化学科数据（12条）
- [x] 初始化区域数据（湖北省数据）

#### 阶段二：后端-年级/班级/学科（1天）

- [ ] Grade 实体类
- [ ] GradeMapper + XML
- [ ] GradeService 接口及实现
- [ ] GradeController（含权限注解）
- [ ] Class 实体类
- [ ] ClassMapper + XML
- [ ] ClassService 接口及实现
- [ ] ClassController
- [ ] Subject 实体类
- [ ] SubjectMapper + XML
- [ ] SubjectService 接口及实现
- [ ] SubjectController
- [ ] 单元测试

#### 阶段三：后端-区域管理（0.5天）

- [ ] Region 实体类
- [ ] RegionMapper + XML
- [ ] RegionService 接口及实现（含缓存）
- [ ] RegionController
- [ ] 单元测试

#### 阶段四：前端-年级/班级/学科（1天）

- [ ] grade API 封装
- [ ] grade Mock 数据
- [ ] grade/index.vue 页面
- [ ] class API 封装
- [ ] class Mock 数据
- [ ] class/index.vue 页面
- [ ] subject API 封装
- [ ] subject Mock 数据
- [ ] subject/index.vue 页面
- [ ] 路由配置

#### 阶段五：前端-区域管理（0.5天）

- [ ] region API 封装
- [ ] region Mock 数据
- [ ] region/index.vue 页面（树形表格）
- [ ] 展开/折叠全部功能
- [ ] 新增下级功能

#### 阶段六：联调测试（0.5天）

- [ ] 前后端联调
- [ ] 功能测试
- [ ] Bug修复
- [ ] 代码Review

---

## 9. 测试方案

### 9.1 测试范围

| 测试类型  | 测试内容               |
| ----- | ------------------ |
| 单元测试  | Service层核心方法       |
| 接口测试  | 所有API接口            |
| 功能测试  | 前端页面操作             |
| 边界测试  | 删除被引用数据、名称重复等      |
| 性能测试  | 区域树查询响应时间          |

### 9.2 测试用例

#### 9.2.1 年级管理测试用例

| 用例编号       | 测试场景         | 前置条件     | 测试步骤              | 预期结果              |
| ---------- | ------------ | -------- | ----------------- | ----------------- |
| TC-GRD-001 | 新增年级-正常      | 登录后台     | 输入年级名称，点击确定       | 新增成功，列表显示新数据      |
| TC-GRD-002 | 新增年级-名称重复    | 已存在"一年级" | 新增"一年级"           | 提示"年级名称已存在"       |
| TC-GRD-003 | 编辑年级-正常      | 存在年级数据   | 修改名称，点击确定         | 修改成功              |
| TC-GRD-004 | 删除年级-未被引用    | 年级未被学校使用 | 点击删除，确认           | 删除成功              |
| TC-GRD-005 | 删除年级-被引用     | 年级已被学校使用 | 点击删除，确认           | 提示"该年级已被学校使用，不能删除" |
| TC-GRD-006 | 搜索年级-按名称     | 存在多条数据   | 输入关键字搜索           | 返回匹配数据            |
| TC-GRD-007 | 搜索年级-按状态     | 存在启用/禁用  | 选择状态筛选            | 返回对应状态数据          |

#### 9.2.2 区域管理测试用例

| 用例编号       | 测试场景       | 前置条件     | 测试步骤          | 预期结果              |
| ---------- | ---------- | -------- | ------------- | ----------------- |
| TC-REG-001 | 查看区域树      | 存在区域数据   | 进入区域管理页面      | 显示树形结构            |
| TC-REG-002 | 展开/折叠全部    | 存在多级区域   | 点击展开全部        | 全部节点展开            |
| TC-REG-003 | 新增省级区域     | 登录后台     | 点击新增，输入名称     | 新增成功              |
| TC-REG-004 | 新增下级区域     | 存在父区域    | 点击新增下级        | 弹窗自动带入父级          |
| TC-REG-005 | 删除区域-有子级   | 区域有子节点   | 点击删除          | 提示"存在下级区域，不能删除"   |
| TC-REG-006 | 删除区域-被学校引用 | 区域被学校使用  | 点击删除          | 提示"该区域已被学校使用，不能删除" |
| TC-REG-007 | 删除区域-正常    | 区域无子级无引用 | 点击删除，确认       | 删除成功              |

### 9.3 性能测试

| 测试项       | 测试方法                | 指标要求       |
| --------- | ------------------- | ---------- |
| 区域树查询     | 模拟100条区域数据          | 响应时间 ≤ 200ms |
| 区域树缓存命中   | 连续请求区域树             | 第二次 ≤ 50ms  |
| 年级列表分页查询  | 模拟1000条数据           | 响应时间 ≤ 200ms |

---

## 10. 风险与应对

### 10.1 技术风险

| 风险点     | 影响程度 | 应对措施                 |
| ------- | ---- | -------------------- |
| 区域树性能问题 | 中    | 使用Redis缓存，设置合理过期时间   |
| 数据引用关系复杂 | 中    | 删除前严格检查，提供友好的错误提示    |
| 编码生成冲突  | 低    | 使用数据库max函数 + 锁机制保证唯一 |

### 10.2 业务风险

| 风险点      | 影响程度 | 应对措施            |
| -------- | ---- | --------------- |
| 初始数据不完整  | 中    | 与业务方确认初始数据范围    |
| 权限控制遗漏   | 高    | 严格按照权限矩阵实现，测试验证 |

### 10.3 进度风险

| 风险点     | 影响程度 | 应对措施          |
| ------- | ---- | ------------- |
| 需求变更    | 中    | 预留缓冲时间        |
| 联调问题多   | 中    | 尽早进行前后端联调     |

---

## 审核意见

| 评审角色 | 评审人 | 评审日期 | 评审意见 | 签字 |
| ---- | --- | ---- | ---- | -- |
| 技术负责人 |     |      |      |    |
| 前端负责人 |     |      |      |    |
| 后端负责人 |     |      |      |    |
| 测试负责人 |     |      |      |    |

---

*文档结束*