将 doc/ 目录重组为更标准的结构： 目录变更： - doc/ → docs/ (文档目录，只包含 .md 文件) - doc/sql/ → database/ (数据库脚本目录) - database/bladex/ (BladeX 框架数据库) - database/flowable/ (Flowable 工作流数据库) - database/martial-db/ (武术系统业务数据库) - database/upgrade/ (数据库升级脚本) - doc/script/ → scripts/ (部署和运维脚本) - scripts/docker/ (Docker 部署脚本) - scripts/fatjar/ (Fat JAR 启动脚本) 优势： - 符合标准项目结构规范 - 文档、数据库、脚本分离更清晰 - 便于维护和查找 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
n72595987@gmail.com
432
docs/前后端架构说明.md
Normal file
432
docs/前后端架构说明.md
Normal file
@@ -0,0 +1,432 @@
|
||||
# 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 源码
|
||||
Reference in New Issue
Block a user