# 项目文档索引

## 📚 开发文档

### 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. 启动项目，访问 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
**维护者**：开发团队