# OpenAPI模块

OpenAPI模块提供了完整的API管理平台，支持应用管理、多种认证方式、权限控制、频率限制、Webhook回调、统计分析等功能。

## 🚀 功能特性

### 核心功能
- **应用管理**: 创建和管理API应用，支持应用状态控制
- **多种认证方式**: API Key、JWT、OAuth2、签名认证、Basic Auth、Bearer Token
- **权限控制**: 基于SCOPE的细粒度权限管理系统
- **频率限制**: 多维度API调用频率限制（分钟/小时/天/周/月）
- **IP白名单**: 支持精确IP、CIDR、通配符匹配
- **日志记录**: 详细的API调用日志和错误追踪
- **统计分析**: 完整的API使用统计和性能监控
- **Webhook支持**: 事件驱动的回调机制，支持重试和签名验证

### 管理功能
- **后台管理**: 完整的后台管理界面
- **实时监控**: API调用实时监控和告警
- **数据导出**: 日志和统计数据导出
- **批量操作**: 支持批量管理应用和密钥
- **API测试**: 内置API测试工具

## 📦 安装配置

### 1. 模块注册
确保模块已在 `config/app.php` 中注册：
```php
'providers' => [
    // ...
    App\Module\OpenAPI\Providers\OpenAPIServiceProvider::class,
],
```

### 2. 数据库迁移
运行SQL文件创建相关表：
```bash
# 执行数据库SQL文件
mysql -u username -p database_name < app/Module/OpenAPI/Databases/GenerateSql/openapi_tables.sql
```

### 3. 环境变量配置
在 `.env` 文件中添加配置：
```env
# OpenAPI基础配置
OPENAPI_LOGGING_ENABLED=true
OPENAPI_STATS_ENABLED=true

# 频率限制配置
OPENAPI_RATE_LIMIT_PER_MINUTE=60
OPENAPI_RATE_LIMIT_PER_HOUR=1000
OPENAPI_RATE_LIMIT_PER_DAY=10000

# Webhook配置
OPENAPI_WEBHOOK_TIMEOUT=30
OPENAPI_WEBHOOK_RETRY_COUNT=3

# 缓存配置
OPENAPI_CACHE_DRIVER=redis
OPENAPI_CACHE_TTL=3600
```

### 4. 发布配置文件（可选）
```bash
php artisan vendor:publish --provider="App\Module\OpenAPI\Providers\OpenAPIServiceProvider"
```

## 核心功能

### 1. 应用管理
- 第三方应用注册和审核
- API密钥生成和管理
- 应用状态控制（启用/禁用）
- 应用信息维护

### 2. 认证授权
- API Key认证
- OAuth2.0认证
- JWT Token认证
- 签名认证

### 3. 权限控制
- API权限范围管理
- 细粒度权限控制
- 动态权限分配
- 权限继承机制

### 4. 访问控制
- 频率限制（QPS、QPM、QPD）
- IP白名单控制
- 时间窗口限制
- 并发连接控制

### 5. 钻石充值/提取
- 开发者专用账户管理
- 钻石充值到用户账户
- 从用户账户提取钻石
- 账户余额查询和监控

### 6. 监控统计
- 实时调用监控
- 调用日志记录
- 统计分析报表
- 性能指标监控

### 7. 开发支持
- 自动生成API文档
- 多语言SDK支持
- 在线调试工具
- 错误码说明

## 设计原则

### 1. 安全性
- 多层次认证机制
- 敏感信息加密存储
- 访问日志完整记录
- 异常行为监控

### 2. 稳定性
- 限流保护机制
- 熔断降级策略
- 异常处理完善
- 服务监控告警

### 3. 易用性
- 简洁的API设计
- 完善的文档支持
- 丰富的SDK支持
- 友好的错误提示

### 4. 扩展性
- 插件化架构设计
- 支持自定义认证
- 灵活的权限配置
- 可扩展的监控指标

## 与现有模块的关系

### 依赖关系
- **OAuth模块**: 复用OAuth2.0认证机制
- **User模块**: 依赖用户信息进行认证
- **Admin模块**: 使用后台管理组件
- **System模块**: 依赖系统配置和日志

### 服务提供
- 为第三方应用提供API接入服务
- 为内部系统提供API管理能力
- 为开发者提供完整的开发工具链

## 开发规范

### 1. 命名规范
- 控制器以`Controller`结尾
- 服务类以`Service`结尾
- 中间件以`Middleware`结尾
- 模型以`OpenApi`开头

### 2. 代码规范
- 遵循PSR-4自动加载标准
- 使用PHP 8.0+语法特性
- 完善的注释和文档
- 严格的类型声明

### 3. API规范
- 遵循RESTful设计原则
- 统一的响应格式
- 完整的错误码体系
- 版本控制机制

## 使用示例

### 1. 应用注册
```php
use App\Module\OpenAPI\Services\OpenApiService;

$apiService = new OpenApiService();
$app = $apiService->createApp([
    'name' => '第三方应用',
    'description' => '应用描述',
    'callback_url' => 'https://example.com/callback',
    'scopes' => ['FUND_READ', 'FUND_RECHARGE', 'FUND_WITHDRAW']
]);
```

### 2. 钻石充值
```php
// POST /api/openapi/diamond/recharge
$response = $client->post('/api/openapi/diamond/recharge', [
    'user_id' => 12345,
    'amount' => 100.5,
    'order_id' => 'ORDER_20250614_001',
    'remark' => '游戏内购买道具'
]);
```

### 3. 钻石提取
```php
// POST /api/openapi/diamond/withdraw
$response = $client->post('/api/openapi/diamond/withdraw', [
    'user_id' => 12345,
    'amount' => 50.25,
    'order_id' => 'WITHDRAW_20250614_001',
    'remark' => '用户提现'
]);
```

### 4. 查询账户余额
```php
// GET /api/openapi/diamond/recharge-balance
$rechargeBalance = $client->get('/api/openapi/diamond/recharge-balance');

// GET /api/openapi/diamond/withdraw-balance
$withdrawBalance = $client->get('/api/openapi/diamond/withdraw-balance');
```

## 开发状态

- 📋 **规划阶段**: 模块设计和架构规划
- 🚧 **开发中**: 核心功能开发
- ✅ **已完成**: 基础框架搭建

## 版本历史

- **v0.1.0** (计划中) - 基础架构搭建
- **v0.2.0** (计划中) - 认证授权实现
- **v0.3.0** (计划中) - 权限控制完善
- **v1.0.0** (计划中) - 正式版本发布

## 注意事项

1. **安全考虑**: API密钥和敏感信息需要加密存储
2. **性能考虑**: 高频API调用需要优化性能
3. **兼容性**: 保持与现有OAuth模块的兼容性
4. **监控**: 重要操作需要完整的日志记录
5. **文档**: 保持API文档的及时更新

## 后续规划

1. **功能扩展**: 添加更多认证方式和权限控制
2. **性能优化**: 优化高并发场景下的性能
3. **监控完善**: 完善监控指标和告警机制
4. **SDK扩展**: 支持更多编程语言的SDK
5. **文档完善**: 完善开发者文档和示例