武术赛事管理系统 - 后端 API

基于 BladeX 4.0.1 企业级框架构建的武术比赛管理系统后端服务。

在线访问

服务	地址	说明
后端 API	https://martial-api.aitisai.com	Spring Boot 服务
管理后台	https://martial-admin.aitisai.com	Web 管理端
用户端	https://martial.aitisai.com	报名小程序 H5
裁判端	https://martial-mini.aitisai.com	裁判评分小程序
OSS 存储	https://martial-oss.aitisai.com	MinIO 对象存储
MinIO 控制台	https://martial-minio.aitisai.com	MinIO 管理界面

技术栈

• 框架: Spring Boot 3.2.4 + BladeX 4.0.1
• 语言: Java 17
• 数据库: MySQL 8.0 + Redis 7
• ORM: MyBatis-Plus
• 数据库迁移: Flyway
• 对象存储: MinIO
• 反向代理: Caddy
• 容器化: Docker Compose

快速开始

环境要求

• Docker & Docker Compose

一键部署（推荐）

确保目录结构如下：

martial/
├── martial-tool/       # BladeX 框架（必需）
├── martial-master/     # 后端项目
├── martial-web/        # 管理后台前端
├── martial-mini/       # 用户端小程序
└── martial-admin-mini/ # 裁判端小程序

cd martial/martial-master

# 首次部署（完整构建，约5-6分钟）
docker compose up -d

# 查看构建日志
docker compose logs -f martial-api

# 查看服务状态
docker compose ps

服务启动后：

• API 服务: http://localhost:8123
• API 文档: http://localhost:8123/doc.html

快速构建（开发迭代）

# 只做后端打包（不会重建容器）
./scripts/deploy-backend.sh --skip-docker

# 打包 + 重建并重启 martial-api 容器
./scripts/deploy-backend.sh

说明：

• ./scripts/ensure-martial-tool-installed.sh 会自动检测 martial-tool 是否已安装到本地 Maven 仓库。
• 只有在以下情况才会重新执行 martial-tool 的 mvn install：
  • 本地 Maven 仓库缺少 BladeX 依赖产物。
  • martial-tool 代码发生变化（基于 git 状态检测）。
• ./scripts/deploy-backend.sh 默认会执行后端打包，并重建/重启 martial-api 容器（等价于一次后端重新部署）。
• ./scripts/deploy-backend.sh --skip-docker 仅执行后端打包，不会触发 Docker 重建或容器重启。
• 日常迭代只改后端业务代码时，会跳过 martial-tool 编译，减少构建时间。

详细的 Docker 部署说明请参考 Docker 部署指南

项目结构

martial-master/
├── src/main/java/org/springblade/
│   ├── modules/martial/          # 武术比赛核心业务
│   │   ├── controller/           # 接口控制器
│   │   ├── service/              # 业务逻辑
│   │   ├── mapper/               # 数据访问
│   │   └── pojo/                 # 实体类
│   └── ...                       # BladeX 框架模块
├── src/main/resources/
│   ├── application.yml           # 主配置
│   ├── application-dev.yml       # 开发环境
│   ├── application-prod.yml      # 生产环境
│   └── db/migration/             # Flyway 迁移脚本
├── database/                     # SQL管理目录（init/flowable/upgrade）
├── docs/                         # 项目文档
├── docker-compose.yml            # Docker 编排配置
├── Dockerfile.fullbuild          # 完整构建（含 martial-tool）
└── Dockerfile.quick              # 快速构建（需预编译 JAR）

Docker Compose 服务

服务	端口	说明
martial-api	8123	后端 API 服务
martial-mysql	3306	MySQL 数据库
martial-redis	6379	Redis 缓存
minio	9000/9001	对象存储

数据库迁移

项目使用 Flyway 管理数据库版本，应用启动时自动执行迁移。

添加新迁移：

# 在 src/main/resources/db/migration/ 创建脚本
# 命名规范: V{版本号}__{描述}.sql
# 示例: V3__add_new_table.sql

详细说明：docs/DATABASE_MIGRATION.md

开发文档

文档	说明
CLAUDE.md	项目完整说明
docs/开发指南.md	开发规范
docs/架构说明.md	架构设计
docs/DATABASE_MIGRATION.md	数据库迁移指南

相关仓库

仓库	说明
martial-master	后端 API
martial-web	管理后台前端
martial-mini	用户端小程序
martial-admin-mini	裁判端小程序

许可协议

本项目基于 BladeX 商业框架 构建，需遵守 BladeX 商业授权许可协议。

---

最后更新: 2024-12-29