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