204 lines
5.7 KiB
Markdown
204 lines
5.7 KiB
Markdown
# 编排系统文档更新日志
|
||
|
||
> 记录编排系统文档的所有版本更新历史
|
||
|
||
## 版本规范
|
||
|
||
- **主版本号 (Major)**: 重大功能变更或架构调整，如 v1.0 → v2.0
|
||
- **次版本号 (Minor)**: 功能新增或优化，如 v1.0 → v1.1
|
||
- **修订号 (Patch)**: 文档修正、补充说明，如 v1.0.1 → v1.0.2
|
||
|
||
---
|
||
|
||
## [v1.0] - 2025-12-10
|
||
|
||
### 新增内容
|
||
|
||
#### 系统概述
|
||
- 功能简介：自动编排、手动调整、场地管理、草稿保存、锁定发布、数据导出
|
||
- 技术栈：Vue 2.x + Element UI + Spring Boot + MyBatis Plus + MySQL 8.0
|
||
|
||
#### 架构设计
|
||
- 系统架构图（前端层、后端层、数据库层）
|
||
- 模块划分（前端模块、后端模块）
|
||
- 详细的文件结构说明
|
||
|
||
#### 数据库设计
|
||
- 核心表设计（4张表）
|
||
- `martial_schedule_group` - 赛程编排分组表
|
||
- `martial_schedule_detail` - 赛程编排明细表
|
||
- `martial_schedule_participant` - 赛程编排参赛者关联表
|
||
- `martial_schedule_status` - 赛程编排状态表
|
||
- 关联表说明（`martial_athlete`, `martial_venue`）
|
||
- 表关系图和关键字段说明
|
||
- 完整的建表SQL和索引设计
|
||
|
||
#### 后端实现
|
||
- Controller层实现
|
||
- `MartialScheduleArrangeController` - 编排控制器
|
||
- 主要接口：获取编排结果、保存草稿、完成并锁定、手动触发编排
|
||
- Service层实现
|
||
- 核心方法：`getScheduleResult()` - 获取编排结果
|
||
- 核心方法：`saveDraftSchedule()` - 保存编排草稿
|
||
- 数据流程和事务处理
|
||
- Mapper层实现
|
||
- 关键SQL查询（LEFT JOIN优化）
|
||
- 避免N+1查询问题的最佳实践
|
||
|
||
#### 前端实现
|
||
- 页面结构（index.vue）
|
||
- 头部布局（返回按钮、标题、异常组按钮）
|
||
- Tab切换（竞赛分组、场地）
|
||
- 场地选择器、时间段选择器
|
||
- 竞赛分组列表和表格
|
||
- 底部操作按钮
|
||
- 核心数据结构
|
||
- 基础信息字段
|
||
- UI状态字段
|
||
- 编排数据结构
|
||
- 核心方法实现
|
||
- `loadScheduleData()` - 加载编排数据
|
||
- `handleSaveDraft()` - 保存草稿
|
||
- `handleMoveUp/Down()` - 上移/下移
|
||
- `markAsException()` - 标记异常
|
||
- API调用（activitySchedule.js）
|
||
- `getScheduleResult()` - 获取编排结果
|
||
- `saveDraftSchedule()` - 保存草稿
|
||
- `saveAndLockSchedule()` - 保存并锁定
|
||
|
||
#### 数据流转
|
||
- 完整流程图（8个步骤）
|
||
- 用户进入页面 → 前端加载 → 后端查询 → 数据返回 → 前端渲染 → 用户操作 → 保存草稿 → 完成编排
|
||
- 数据库操作流程
|
||
- 查询编排数据的SQL
|
||
- 保存草稿数据的事务处理
|
||
|
||
#### 核心功能
|
||
- 场地和时间段过滤（计算属性实现）
|
||
- 参赛者顺序调整（上移、下移）
|
||
- 分组移动（跨场地、跨时间段）
|
||
- 异常标记（异常组管理）
|
||
- 草稿保存（增量更新）
|
||
- 完成编排（锁定机制）
|
||
|
||
#### API接口文档
|
||
- GET `/api/martial/schedule/result` - 获取编排结果
|
||
- POST `/api/martial/schedule/save-draft` - 保存编排草稿
|
||
- POST `/api/martial/schedule/save-and-lock` - 完成编排并锁定
|
||
- GET `/api/martial/venue/list-by-competition` - 获取场地列表
|
||
- GET `/api/martial/competition/detail` - 获取赛事详情
|
||
- 包含请求参数、响应示例、错误码说明
|
||
|
||
#### 关键代码解析
|
||
- 计算属性 `filteredCompetitionGroups` 的实现原理
|
||
- 生成时间段列表的算法
|
||
- 保存草稿的数据转换逻辑
|
||
- 后端数据组装的性能优化
|
||
|
||
#### 使用指南
|
||
- 管理员操作流程（进入页面、查看数据、调整编排、保存草稿、完成编排）
|
||
- 常见问题解答
|
||
- 为什么编排数据为空？
|
||
- 为什么无法编辑？
|
||
- 保存草稿失败怎么办？
|
||
- 开发调试方法
|
||
- 前端调试技巧
|
||
- 后端调试技巧
|
||
- 数据库调试SQL
|
||
|
||
#### 附录
|
||
- 数据字典（编排状态、项目类型、参赛者状态）
|
||
- 相关文档链接
|
||
- 更新日志
|
||
|
||
### 文档特色
|
||
|
||
- **完整性**：覆盖从前端到后端、从UI到数据库的完整技术栈
|
||
- **实用性**：包含大量代码示例和实际操作流程
|
||
- **可读性**：清晰的章节结构、流程图、表格说明
|
||
- **可维护性**：详细的注释和说明，便于后续维护
|
||
|
||
### 文件信息
|
||
|
||
- **文件名**: `schedule-complete-guide.md`
|
||
- **文件大小**: ~62 KB
|
||
- **总行数**: 1857 行
|
||
- **主要章节**: 11 个
|
||
- **代码示例**: 50+ 个
|
||
- **SQL语句**: 10+ 个
|
||
- **流程图**: 5 个
|
||
|
||
---
|
||
|
||
## 版本对比
|
||
|
||
| 版本 | 发布日期 | 主要内容 | 文件大小 | 行数 |
|
||
|------|----------|----------|----------|------|
|
||
| v1.0 | 2025-12-10 | 初始版本，完整技术方案 | ~62 KB | 1857 |
|
||
|
||
---
|
||
|
||
## 待规划版本
|
||
|
||
### v1.1 (计划中)
|
||
|
||
可能的更新方向：
|
||
|
||
- **性能优化章节**
|
||
- 前端虚拟滚动优化
|
||
- 后端分页查询优化
|
||
- 缓存策略设计
|
||
|
||
- **扩展功能**
|
||
- 批量操作功能
|
||
- 撤销/重做功能
|
||
- 编排历史记录
|
||
|
||
- **集成测试**
|
||
- 单元测试用例
|
||
- 集成测试方案
|
||
- 性能测试报告
|
||
|
||
### v2.0 (未来)
|
||
|
||
可能的重大更新：
|
||
|
||
- 微服务架构改造
|
||
- 前端升级到 Vue 3
|
||
- 实时协同编排功能
|
||
- AI智能编排算法
|
||
|
||
---
|
||
|
||
## 文档维护说明
|
||
|
||
### 更新规范
|
||
|
||
1. **修改主文档**
|
||
- 所有修改都在 `schedule-complete-guide.md` 中进行
|
||
- 更新文档头部的版本信息和更新日期
|
||
|
||
2. **发布新版本**
|
||
- 确定版本号（根据修改程度）
|
||
- 复制主文档到 `versions/vX.X/` 目录
|
||
- 更新本 CHANGELOG.md 文件
|
||
- 更新 README.md 中的版本信息
|
||
|
||
3. **归档旧版本**
|
||
- 不再维护的文档移到 `archive/` 目录
|
||
- 在文档顶部添加 **已废弃** 标记
|
||
|
||
### 版本命名示例
|
||
|
||
```
|
||
v1.0 - 初始版本
|
||
v1.1 - 新增性能优化章节
|
||
v1.1.1 - 修正API文档中的错误
|
||
v1.2 - 新增集成测试章节
|
||
v2.0 - 架构重构，升级到Vue 3
|
||
```
|
||
|
||
---
|
||
|
||
**文档最后更新**: 2025-12-10
|