# 开发文档目录

## 概述

本目录包含项目的详细开发文档，每个重要功能模块都有对应的详细文档。

## 文档列表

### 认证系统
- [认证系统开发文档](./认证系统开发文档.md) - 完整的Token认证系统实现文档
  - 系统架构设计
  - 核心组件详解
  - 业务流程说明
  - 数据库设计
  - 客户端集成示例
  - 安全考虑事项
  - 性能优化建议
  - 监控和日志
  - 部署注意事项
- [API快速测试指南](./API快速测试指南.md) - 认证系统API的快速测试方法
  - cURL命令测试
  - JavaScript/浏览器测试
  - 完整的HTML测试页面
  - 错误排查指南
  - 性能测试方法

### 异常处理系统
- [异常处理使用指南](./异常处理使用指南.md) - 简化的异常处理使用方法
  - 三个核心方法：throw、error、fail
  - 统一JSON响应格式
  - 控制器、服务类、中间件、模型使用示例
  - 最佳实践和性能考虑
  - 测试接口和迁移指南
- [全局异常处理开发文档](./全局异常处理开发文档.md) - 详细的系统架构文档
  - 系统架构和组件说明
  - 异常分类和处理流程
  - 错误码规范和管理
  - 日志记录和安全考虑
  - 性能优化和监控
  - 调试技巧和扩展开发

### 认证缓存系统
- [Token认证缓存服务使用指南](./Token认证缓存服务使用指南.md) - 高性能认证缓存系统
  - 智能缓存策略和动态缓存时间
  - Redis/文件缓存支持和健康检查
  - 中间件集成和自动清理
  - 性能优化和故障排查
  - 监控统计和最佳实践
  - 扩展开发指南

## 文档规范

### 文档命名规范
- 使用中文命名，便于理解
- 格式：`功能模块名称开发文档.md`
- 示例：`用户管理开发文档.md`、`权限系统开发文档.md`

### 文档结构规范
每个功能文档应包含以下部分：
1. **概述** - 功能简介和目标
2. **系统架构** - 整体结构和组件关系
3. **核心组件详细说明** - 各组件的职责和实现
4. **业务流程** - 主要业务流程图和说明
5. **数据库设计** - 相关表结构和关系
6. **使用方法** - 客户端和服务端集成示例
7. **配置说明** - 相关配置文件和环境变量
8. **安全考虑** - 安全特性和注意事项
9. **性能优化** - 优化建议和最佳实践
10. **监控和日志** - 监控指标和日志规范
11. **注意事项** - 开发、部署、维护注意事项
12. **技术支持** - 常见问题和扩展资源

### 更新规范
- 每次重大功能更新后及时更新文档
- 文档版本号与功能版本保持同步
- 记录文档修改历史和责任人

## 项目概况

### 技术栈
- **后端框架**: Laravel 12
- **认证方案**: Laravel Sanctum (Token认证)
- **数据库**: MySQL
- **API风格**: RESTful API
- **响应格式**: 统一JSON格式 (BaseController)

### 开发原则
- 遵循Laravel最佳实践
- 统一的错误处理和响应格式
- 完整的文档和注释
- 安全第一的开发理念
- 性能优化考虑

## 快速开始

### 开发环境搭建
1. 克隆项目代码
2. 安装依赖：`composer install`
3. 配置环境变量：复制 `.env.example` 到 `.env`
4. 生成应用密钥：`php artisan key:generate`
5. 运行数据库迁移：`php artisan migrate`
6. 运行种子数据：`php artisan db:seed --class=AdminUserSeeder`
7. 启动开发服务器：`php artisan serve`

### 测试账户
- **管理员**: username: `admin`, password: `123456`
- **测试用户**: username: `test`, password: `123456`

### 接口测试
使用提供的测试文档进行接口测试：
- 登录获取Token：`POST /admin/auth/login`
- 访问受保护接口：携带 `Authorization: Bearer {token}` 头

## 版本历史

### v1.0 (2024-12)
- ✅ 完成Token认证系统
- ✅ 统一API响应格式
- ✅ 多设备登录管理
- ✅ 完整的开发文档

## 贡献指南

### 添加新功能文档
1. 在 `docs/` 目录创建新的文档文件
2. 按照文档结构规范编写内容
3. 更新本 README.md 文件，添加新文档链接
4. 提交代码并更新版本记录

### 文档审核
- 技术负责人审核文档内容的准确性
- 确保文档格式符合规范
- 验证示例代码的可执行性

---

**维护者**: 开发团队  
**最后更新**: 2024年12月