# 武术赛事管理系统 - 后端 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/ # 裁判端小程序
```

```bash
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

### 快速构建（开发迭代）

如果已经手动编译过 JAR，可以使用快速构建：

```bash
# 先编译 martial-tool（首次）
cd ../martial-tool && mvn clean install -DskipTests

# 编译 martial-master
cd ../martial-master && mvn clean package -DskipTests

# 使用快速构建 Dockerfile
docker compose build martial-api --build-arg DOCKERFILE=Dockerfile.quick
```

## 项目结构

```
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/                     # 数据库初始化脚本
├── 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 管理数据库版本，应用启动时自动执行迁移。

**添加新迁移：**
```bash
# 在 src/main/resources/db/migration/ 创建脚本
# 命名规范: V{版本号}__{描述}.sql
# 示例: V3__add_new_table.sql
```

详细说明：[docs/DATABASE_MIGRATION.md](./docs/DATABASE_MIGRATION.md)

## 开发文档

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

## 相关仓库

| 仓库 | 说明 |
|------|------|
| [martial-master](https://git.waypeak.work/martial/martial-master) | 后端 API |
| [martial-web](https://git.waypeak.work/martial/martial-web) | 管理后台前端 |
| [martial-mini](https://git.waypeak.work/martial/martial-mini) | 用户端小程序 |
| [martial-admin-mini](https://git.waypeak.work/martial/martial-admin-mini) | 裁判端小程序 |

## 许可协议

本项目基于 **BladeX 商业框架** 构建，需遵守 [BladeX 商业授权许可协议](https://license.bladex.cn)。

---

**最后更新**: 2024-12-29