martial-master/docs/前后端架构说明.md

# BladeX 完整架构说明

## 一、BladeX 完整系统架构

BladeX 是一个**前后端分离**的企业级微服务架构，完整的系统包含多个项目：

```
BladeX 完整架构
├── 后端项目（当前）
│   ├── martial-master              # Spring Boot 后端 API（当前项目）
│   └── martial-tool                # BladeX 框架核心（依赖库）
│
├── 前端项目（独立仓库）
│   ├── Saber (推荐)                # Vue 3 + Element Plus 管理后台 ⭐
│   └── Sword (旧版)                # Vue 2 + Avue 管理后台（已不推荐）
│
└── 可选组件
    ├── BladeX-Auth                 # 独立认证中心（微服务版）
    ├── BladeX-Gateway              # 网关服务（微服务版）
    └── BladeX-Register             # 注册中心（Nacos）
```

### 当前项目状态

根据 `CLAUDE.md` 的说明：
```
"The frontend is a separate Vue.js project (not in this repository)"
```

**当前您手上只有后端项目** `martial-master`，前端管理系统是独立的项目。

---

## 二、前端管理系统 - Saber

### 2.1 Saber 是什么？

**Saber** 是 BladeX 官方的 Vue 3 管理后台系统，提供可视化的管理界面。

**主要功能**：
- 🏠 **仪表盘**：数据统计、图表展示
- 👥 **用户管理**：用户增删改查、角色分配
- 🔐 **权限管理**：角色管理、菜单管理、权限分配
- 🏢 **组织架构**：部门管理、岗位管理
- 📋 **系统管理**：字典管理、参数配置、日志查看
- 🗂️ **资源管理**：文件上传、OSS 配置
- ⚙️ **开发工具**：代码生成器、数据源管理
- 🥋 **业务功能**：武术比赛管理（根据菜单配置）

### 2.2 Saber 技术栈

```
前端框架：Vue 3
UI 组件：Element Plus
状态管理：Pinia
路由：Vue Router 4
构建工具：Vite
HTTP 库：Axios
```

### 2.3 Saber 项目地址

**官方仓库**（需要授权访问）：
```
Gitee: https://gitee.com/smallc/Saber
GitHub: https://github.com/chillzhuang/Saber
```

**注意**：BladeX 是商业框架，完整源码需要购买授权。

### 2.4 Saber 运行端口

根据配置文件中的线索：
```yaml
# application-dev.yml
blade:
  token:
    domain: http://127.0.0.1:1888  # 前端地址
```

**默认端口**：`1888`（开发环境）

---

## 三、前后端交互流程

```
┌─────────────────────────────────────────────────────────────┐
│                    用户浏览器                                  │
└──────────────┬──────────────────────────────────────────────┘
               │
               │ http://localhost:1888
               ▼
┌──────────────────────────────────────────────────────────────┐
│              Saber 前端 (Vue 3)                               │
│  - 登录页面                                                    │
│  - 仪表盘                                                      │
│  - 用户管理                                                    │
│  - 权限管理                                                    │
│  - 武术比赛管理（调用后端 API）                                │
└──────────────┬───────────────────────────────────────────────┘
               │
               │ HTTP 请求（JSON）
               │ POST /blade-auth/token
               │ GET /blade-system/user/list
               │ GET /api/martial/competition/list
               ▼
┌──────────────────────────────────────────────────────────────┐
│         martial-master 后端 (Spring Boot)                     │
│  http://localhost:8123                                        │
│                                                                │
│  ├── /blade-auth/**      → 认证模块                           │
│  ├── /blade-system/**    → 系统管理                           │
│  ├── /blade-desk/**      → 仪表盘                             │
│  ├── /blade-resource/**  → 资源管理                           │
│  ├── /blade-develop/**   → 开发工具                           │
│  └── /api/martial/**     → 武术比赛（您的业务）               │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
        ┌──────────────┐
        │    MySQL     │
        │  Redis       │
        └──────────────┘
```

---

## 四、当前项目的使用方式

### 方式一：仅使用 API（当前可用）✅

**适合场景**：
- 前端单独开发
- 移动端开发
- API 集成测试

**访问方式**：
```
Knife4j API 文档：http://localhost:8123/doc.html

直接调用 API：
POST http://localhost:8123/blade-auth/token
GET  http://localhost:8123/api/martial/competition/list
```

**优点**：
- ✅ 无需前端，可以直接测试 API
- ✅ 适合后端开发和调试

**缺点**：
- ❌ 没有可视化界面
- ❌ 需要手动构造 HTTP 请求

---

### 方式二：搭配 Saber 前端（需要获取源码）

**步骤 1：获取 Saber 源码**

如果您有 BladeX 授权，可以从官方获取 Saber 源码：
```bash
# Gitee
git clone https://gitee.com/smallc/Saber.git

# GitHub
git clone https://github.com/chillzhuang/Saber.git
```

**步骤 2：配置后端地址**

```javascript
// Saber/src/config/website.js
export default {
  // 后端 API 地址
  apiUrl: 'http://localhost:8123',

  // Token 存储键
  tokenHeader: 'Blade-Auth',

  // 其他配置...
}
```

**步骤 3：安装依赖并启动**

```bash
cd Saber

# 安装依赖
npm install
# 或
yarn install

# 启动开发服务器
npm run dev
# 或
yarn dev
```

**步骤 4：访问**

```
浏览器访问：http://localhost:1888

默认账号：
用户名：admin
密码：admin
```

**步骤 5：使用管理后台**

登录后，您可以在 Saber 管理后台中：
- 📊 查看仪表盘数据
- 👥 管理用户和角色
- 📋 配置菜单权限
- 🥋 使用武术比赛管理功能（需要先配置菜单）

---

### 方式三：使用第三方 API 工具（临时方案）

如果暂时没有 Saber 源码，可以使用：

**Postman / Apifox / Insomnia**
```
1. 先调用登录接口获取 Token：
   POST http://localhost:8123/blade-auth/token
   Body: {
     "tenantId": "000000",
     "username": "admin",
     "password": "admin",
     "grant_type": "captcha",
     "scope": "all"
   }

2. 复制返回的 access_token

3. 在后续请求中添加 Header：
   Blade-Auth: bearer <access_token>

4. 调用业务接口：
   GET http://localhost:8123/api/martial/competition/list
```

**VS Code REST Client 扩展**
```http
### 1. 登录获取 Token
POST http://localhost:8123/blade-auth/token
Content-Type: application/json

{
  "tenantId": "000000",
  "username": "admin",
  "password": "admin",
  "grant_type": "captcha",
  "scope": "all"
}

### 2. 调用业务接口
GET http://localhost:8123/api/martial/competition/list
Blade-Auth: bearer {{token}}
```

---

## 五、模块启动管理

### 5.1 单体架构（当前项目）

**当前项目是单体应用**，所有模块在一个进程中运行：

```
java -jar blade-api.jar

启动后，所有模块同时可用：
✅ auth 模块
✅ system 模块
✅ resource 模块
✅ desk 模块
✅ develop 模块
✅ martial 模块
✅ job 模块
```

**没有独立的模块启动管理**，因为不是微服务架构。

---

### 5.2 微服务架构（可选升级）

如果升级到微服务版本，架构会变成：

```
BladeX 微服务架构
├── BladeX-Register (Nacos)      # 注册中心，管理所有服务
├── BladeX-Gateway               # 网关服务
├── BladeX-Auth                  # 认证服务
├── BladeX-System                # 系统服务
├── BladeX-Resource              # 资源服务
├── BladeX-Desk                  # 工作台服务
└── Martial-Service              # 武术比赛服务（您的业务）
```

**此时会有管理界面**：

**Nacos 控制台**：
```
地址：http://localhost:8848/nacos
功能：
- 查看所有注册的服务
- 服务健康检查
- 配置管理
- 服务上下线
```

**Sentinel 控制台**（可选）：
```
地址：http://localhost:8858
功能：
- 流量控制
- 熔断降级
- 系统负载保护
```

**Spring Boot Admin**（可选）：
```
地址：http://localhost:7002
功能：
- 监控所有 Spring Boot 应用
- 查看日志
- 查看 JVM 信息
- 健康检查
```

---

## 六、常见疑问解答

### Q1: 为什么没有找到管理界面？

**A**: 当前项目是**纯后端 API 项目**，前端管理系统（Saber）是独立的项目，需要单独获取和部署。

### Q2: 如何获取 Saber 前端源码？

**A**:
- 如果您有 BladeX 授权，从官方仓库获取
- 如果是开源版本，部分功能可能不可用
- 可以联系 BladeX 官方获取试用版

### Q3: 没有 Saber 可以开发吗？

**A**: 可以！
- 使用 Knife4j API 文档测试：http://localhost:8123/doc.html
- 使用 Postman/Apifox 调用 API
- 自己开发前端（任何技术栈都可以）

### Q4: 如何查看系统运行状态？

**A**:
- 查看日志：`tail -f application.log`
- 健康检查：http://localhost:8123/actuator/health
- Druid 监控：http://localhost:8123/druid
- Knife4j 文档：http://localhost:8123/doc.html

### Q5: 这个项目是微服务吗？

**A**: 当前是**单体应用**（Monolithic），但使用了模块化设计。如果需要，可以升级为微服务架构。

---

## 七、推荐的开发方式

### 当前阶段（无 Saber）

```
1. 后端开发：
   - 在 VS Code 中开发业务逻辑
   - 使用 F5 调试运行

2. 接口测试：
   - 使用 Knife4j：http://localhost:8123/doc.html
   - 使用 Postman/Apifox

3. 数据库操作：
   - 使用 Navicat/DBeaver 连接 MySQL
   - 执行 SQL 查看数据
```

### 有 Saber 前端时

```
1. 启动后端：
   cd martial-master
   mvn spring-boot:run

2. 启动前端：
   cd Saber
   npm run dev

3. 访问管理后台：
   http://localhost:1888

4. 全栈开发：
   - 后端改代码 → 前端调用 API
   - 前端页面 → 调用后端接口
```

---

## 八、总结

| 组件 | 状态 | 地址 | 说明 |
|------|------|------|------|
| **后端 API** | ✅ 有 | http://localhost:8123 | 当前项目 |
| **API 文档** | ✅ 有 | http://localhost:8123/doc.html | Knife4j |
| **Druid 监控** | ✅ 有 | http://localhost:8123/druid | 数据库监控 |
| **前端管理系统** | ❌ 无 | http://localhost:1888 | Saber（需单独获取） |
| **模块管理界面** | ❌ 无 | - | 单体应用，无需管理 |

**关键点**：
- ✅ 后端可以独立运行和开发
- ✅ 使用 Knife4j 可以完成所有测试
- ❌ 如需可视化管理界面，需要部署 Saber 前端
- ❌ 单体架构下没有"模块启动管理"的概念

---

**建议**：
1. 现阶段专注后端 API 开发
2. 使用 Knife4j 测试接口
3. 如需前端，可以自己用 Vue/React 开发，或等待获取 Saber 源码