59 KiB

Raw Blame History

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

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

修订记录

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

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 目录结构

前端目录结构：

frontend/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 通用组件结构

<!-- 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 年级管理组件

核心功能实现：

// 年级管理核心逻辑
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 区域管理组件

树形表格核心逻辑：

// 区域管理核心逻辑
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

// 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

// 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数据

// 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 路由配置

// 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

/**
 * 年级管理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

/**
 * 区域管理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

/**
 * 年级管理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);
}

/**
 * 年级管理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

/**
 * 区域管理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);
}

/**
 * 区域管理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

/**
 * 年级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();
}

<!-- 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 实体类设计

/**
 * 年级实体类
 * @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;
}

/**
 * 区域实体类
 * @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 年级数据

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 班级数据

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 学科数据

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 区域数据

-- 省级
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

响应

{
  "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"
}

响应

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

7.2.3 删除年级（被引用时）

请求

DELETE /api/grade/1

响应

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

7.2.4 获取区域树

请求

GET /api/region/tree

响应

{
  "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天）

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

阶段二：后端-年级/班级/学科（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 进度风险

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

审核意见

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

文档结束

59 KiB Raw Blame History Unescape Escape

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

修订记录

目录

1. 模块概述

1.1 模块定位

1.2 功能范围

1.3 关联关系

2. 需求分析

2.1 功能需求

2.1.1 年级管理

2.1.2 班级管理

2.1.3 学科管理

2.1.4 区域管理

2.2 角色权限

2.3 非功能需求

3. 系统设计

3.1 模块架构

3.2 技术选型

3.3 目录结构

4. 前端技术方案

4.1 页面设计

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

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

4.2 组件设计

4.2.1 通用组件结构

4.2.2 年级管理组件

4.2.3 区域管理组件

4.3 API接口封装

4.3.1 年级管理API

4.3.2 区域管理API

4.4 Mock数据

4.5 路由配置

5. 后端技术方案

5.1 Controller层设计

5.1.1 年级管理Controller

5.1.2 区域管理Controller

5.2 Service层设计

5.2.1 年级管理Service

5.2.2 区域管理Service

5.3 Mapper层设计

5.3.1 年级Mapper

5.4 实体类设计

6. 数据库设计

6.1 表结构

6.2 初始化数据

6.2.1 年级数据

6.2.2 班级数据

6.2.3 学科数据

6.2.4 区域数据

7. 接口设计

7.1 接口清单

7.1.1 年级管理接口

7.1.2 班级管理接口

7.1.3 学科管理接口

7.1.4 区域管理接口

7.2 接口详情

7.2.1 获取年级分页列表

7.2.2 新增年级

7.2.3 删除年级（被引用时）

7.2.4 获取区域树

8. 开发计划

8.1 阶段划分

8.2 里程碑

8.3 任务分解

阶段一：数据库（0.5天）

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

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

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

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

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

9. 测试方案

9.1 测试范围

9.2 测试用例

9.2.1 年级管理测试用例

9.2.2 区域管理测试用例

9.3 性能测试

10. 风险与应对

10.1 技术风险

10.2 业务风险

59 KiB

Raw Blame History