martial/martial-web
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5bbe374ebf737f3d0c9131e5f9d55666eac665a5
martial-web/doc/schedule/versions/CHANGELOG.md
宅房 5b806e29b7
Some checks failed
continuous-integration/drone/push Build is failing
Details
fix bugs
2025-12-11 16:56:19 +08:00

5.7 KiB
Raw Blame History

编排系统文档更新日志

记录编排系统文档的所有版本更新历史

版本规范

  • 主版本号 (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

Reference in New Issue View Git Blame Copy Permalink