ddf3d46a51
将 IP:端口形式的地址替换为域名： - http://154.30.6.21:8123 → https://martial-api.johnsion.club - http://154.30.6.21:8080 → https://martial-ci.johnsion.club - http://154.30.6.21 → https://martial.johnsion.club - http://localhost:8123/doc.html → https://martial-doc.johnsion.club 更新的文件： - docs/README.md: 新人入门路径增加域名说明 - docs/CI-CD部署总结.md: 所有访问地址替换为域名，标记域名配置已完成 本地开发相关的 localhost 配置保持不变。 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
143 lines
4.9 KiB
Markdown
143 lines
4.9 KiB
Markdown
# 项目文档索引
|
||
|
||
## 📚 开发文档
|
||
|
||
### 1. [前后端架构说明.md](./前后端架构说明.md) 🆕
|
||
**理解 BladeX 完整系统架构和前后端分离**
|
||
|
||
- BladeX 完整系统架构（后端 + 前端 Saber）
|
||
- Saber 前端管理系统介绍
|
||
- 前后端交互流程
|
||
- 如何在没有前端的情况下开发
|
||
- 单体架构 vs 微服务架构
|
||
- 模块启动管理说明
|
||
|
||
**适合阅读时机**：
|
||
- ✅ 想了解完整的系统架构时
|
||
- ✅ 疑惑"管理界面在哪里"时
|
||
- ✅ 需要配置前后端联调时
|
||
- ✅ 想了解如何获取前端源码时
|
||
|
||
---
|
||
|
||
### 2. [架构说明.md](./架构说明.md)
|
||
**理解 BladeX 后端框架的架构设计**
|
||
|
||
- 为什么这个项目的结构看起来"乱"？
|
||
- BladeX 架构 vs 传统 Spring Boot 架构对比
|
||
- common、modules、job 目录的职责划分
|
||
- 架构设计理念分析
|
||
- 与标准架构的映射关系
|
||
|
||
**适合阅读时机**：
|
||
- ✅ 刚接触项目，对后端架构感到困惑时
|
||
- ✅ 想理解为什么要这样设计时
|
||
- ✅ 需要向团队解释项目结构时
|
||
|
||
---
|
||
|
||
### 3. [开发指南.md](./开发指南.md)
|
||
**在 BladeX 框架下高效开发的实用指南**
|
||
|
||
包含内容：
|
||
- 📖 快速开始：环境准备、核心目录
|
||
- 🔧 标准开发流程：完整的功能开发步骤（从数据库到API）
|
||
- 📝 代码规范：命名、注解、包结构
|
||
- 💡 常见场景：查询、分页、关联、事务等实战示例
|
||
- ✅ 最佳实践：Service、Controller、异常处理、缓存
|
||
- 🐛 调试技巧：VS Code 调试、日志、SQL 调试
|
||
- ❓ 常见问题：继承选择、Mapper 配置、分页等
|
||
|
||
**适合阅读时机**：
|
||
- ✅ 准备开始开发新功能时
|
||
- ✅ 遇到具体技术问题时
|
||
- ✅ 需要参考代码示例时
|
||
|
||
---
|
||
|
||
## 🎯 快速导航
|
||
|
||
### 我想...
|
||
|
||
| 需求 | 推荐文档 | 章节 |
|
||
|------|---------|------|
|
||
| 了解完整系统架构（前端+后端） | [前后端架构说明.md](./前后端架构说明.md) | 一、BladeX 完整系统架构 |
|
||
| 管理界面在哪里？ | [前后端架构说明.md](./前后端架构说明.md) | 二、前端管理系统 - Saber |
|
||
| 如何获取/配置前端 | [前后端架构说明.md](./前后端架构说明.md) | 四、当前项目的使用方式 |
|
||
| 理解后端架构设计 | [架构说明.md](./架构说明.md) | 二、目录结构对比 |
|
||
| 理解为什么架构"乱" | [架构说明.md](./架构说明.md) | 三、架构特点分析 |
|
||
| 知道代码应该放哪里 | [架构说明.md](./架构说明.md) | 八、实际开发时如何思考 |
|
||
| 开发一个新功能 | [开发指南.md](./开发指南.md) | 二、标准开发流程 |
|
||
| 学习代码规范 | [开发指南.md](./开发指南.md) | 三、代码规范 |
|
||
| 查看查询示例 | [开发指南.md](./开发指南.md) | 四、常见开发场景 |
|
||
| 学习最佳实践 | [开发指南.md](./开发指南.md) | 五、最佳实践 |
|
||
| 调试代码 | [开发指南.md](./开发指南.md) | 六、调试技巧 |
|
||
| 解决常见问题 | [开发指南.md](./开发指南.md) | 七、常见问题 |
|
||
|
||
---
|
||
|
||
## 📋 其他文档
|
||
|
||
### 项目配置与说明
|
||
|
||
- [CLAUDE.md](../CLAUDE.md) - 项目整体说明、技术栈、构建命令
|
||
- [.vscode/DEBUG_GUIDE.md](../.vscode/DEBUG_GUIDE.md) - VS Code 调试配置指南
|
||
|
||
### 数据库文档
|
||
|
||
- [sql/mysql/martial-competition-tables.sql](./sql/mysql/martial-competition-tables.sql) - 武术比赛表结构
|
||
- [sql/mysql/martial-competition-menu.sql](./sql/mysql/martial-competition-menu.sql) - 菜单权限配置
|
||
|
||
---
|
||
|
||
## 🚀 新人入门路径
|
||
|
||
### 第一天：环境准备
|
||
1. 阅读 [CLAUDE.md](../CLAUDE.md) 了解项目概况
|
||
2. 配置开发环境（JDK、Maven、MySQL、Redis）
|
||
3. 启动项目，访问 https://martial-doc.johnsion.club（生产环境）或 http://localhost:8123/doc.html（本地开发）
|
||
|
||
### 第二天：理解架构
|
||
1. 阅读 [前后端架构说明.md](./前后端架构说明.md) 了解完整系统
|
||
2. 阅读 [架构说明.md](./架构说明.md) 理解后端设计
|
||
3. 浏览项目目录结构
|
||
4. 查看现有代码示例（`modules/system/`）
|
||
|
||
### 第三天：动手开发
|
||
1. 阅读 [开发指南.md](./开发指南.md)
|
||
2. 按照"标准开发流程"完成一个简单的 CRUD 功能
|
||
3. 测试接口
|
||
|
||
### 第四天：深入学习
|
||
1. 学习复杂查询、关联查询
|
||
2. 掌握调试技巧
|
||
3. 解决遇到的问题
|
||
|
||
---
|
||
|
||
## 💡 学习建议
|
||
|
||
### 对于初学者
|
||
- 先看 **开发指南** 的"快速开始"和"标准开发流程"
|
||
- 边看边实践，动手写一个 CRUD 功能
|
||
- 遇到问题查看"常见问题"章节
|
||
|
||
### 对于有经验的开发者
|
||
- 快速浏览 **架构说明**，理解 BladeX 的特点
|
||
- 重点关注 **开发指南** 的"最佳实践"
|
||
- 参考"常见场景"进行复杂功能开发
|
||
|
||
### 对于团队 Leader
|
||
- 使用 **架构说明** 向团队解释项目结构
|
||
- 制定基于 **开发指南** 的团队规范
|
||
- 组织 Code Review 时参考"代码规范"
|
||
|
||
---
|
||
|
||
## 🔄 文档更新
|
||
|
||
本文档会根据项目实际情况持续更新。如有问题或建议，请及时反馈。
|
||
|
||
**最后更新**：2025-11-29
|
||
**维护者**：开发团队
|