扩展OpenAPI模块增加钻石充值提取功能

任务时间: 2025年06月14日 21:34:10 CST
任务内容: 扩展 OpenAPI 模块，增加钻石充值/提取的能力，每个开发者都分配一个充值专用账户/提取专用账户

1. 任务背景

用户需要在 OpenAPI 模块中增加钻石充值和提取功能，为每个开发者应用分配专用的充值账户和提取账户，实现安全的资金管理。

2. 实施方案

2.1 权限范围扩展

在 SCOPE_TYPE 枚举中添加 FUND_RECHARGE 和 FUND_WITHDRAW 权限
设置适当的风险级别和权限依赖关系
完善权限描述和分类

2.2 开发者账户管理

创建 DeveloperAccountService 服务类
充值账户用户ID：100000 + 应用ID
提取账户用户ID：200000 + 应用ID
自动创建和管理开发者专用账户

2.3 Handler机制实现

创建 DiamondRechargeHandler 处理充值逻辑
创建 DiamondWithdrawHandler 处理提取逻辑
集成 Fund 模块的服务和验证

2.4 验证系统

创建 DiamondRechargeValidation 和 DiamondWithdrawValidation 验证类
创建 DiamondAmountValidator 和 UserExistenceValidator 验证器
支持钻石10位小数精度验证

3. 核心代码变更

3.1 权限范围扩展

// SCOPE_TYPE.php 新增权限
case FUND_RECHARGE = 'FUND_RECHARGE';       // 钻石充值权限
case FUND_WITHDRAW = 'FUND_WITHDRAW';       // 钻石提取权限

3.2 开发者账户服务

// DeveloperAccountService.php 核心方法
public static function getRechargeUserId(int $appId): int
{
    return self::RECHARGE_USER_ID_START + $appId; // 100000 + appId
}

public static function getWithdrawUserId(int $appId): int
{
    return self::WITHDRAW_USER_ID_START + $appId; // 200000 + appId
}

3.3 API路由

// 新增的API路由
POST /api/openapi/diamond/recharge        // 钻石充值
POST /api/openapi/diamond/withdraw        // 钻石提取
GET  /api/openapi/diamond/recharge-balance // 充值账户余额
GET  /api/openapi/diamond/withdraw-balance // 提取账户余额

4. 功能特性

4.1 钻石充值功能

从开发者充值账户转账到用户钻石账户
支持订单号关联和备注信息
完整的余额验证和事务处理
详细的操作日志记录

4.2 钻石提取功能

从用户钻石账户转账到开发者提取账户
支持订单号关联和备注信息
完整的余额验证和事务处理
详细的操作日志记录

4.3 账户管理功能

自动创建开发者专用账户
账户余额查询和监控
账户状态检查和验证
支持多应用独立管理

4.4 数据验证功能

钻石金额10位小数精度验证
用户存在性和状态验证
完整的错误处理和提示
类型安全的数据传递

5. 技术实现

5.1 Handler机制

继承 BaseHandler 基类
实现权限验证和业务逻辑分离
统一的响应格式和错误处理
完整的日志记录机制

5.2 验证系统

遵循项目标准的验证规范
使用 ValidationCore 和 Validator 基类
支持复杂的业务验证逻辑
类型安全的属性定义

5.3 服务集成

集成 Fund 模块的 FundService
使用钻石币种 FUND_CURRENCY_TYPE::ZUANSHI
支持钻石账户 FUND_TYPE::FUND2
完整的事务处理机制

6. 测试验证

6.1 单元测试

DiamondOperationTest - 基础功能测试
DiamondApiTest - API接口测试
覆盖权限、验证、账户管理等核心功能
8个测试用例，31个断言全部通过

6.2 功能测试

权限范围枚举扩展测试
开发者账户服务测试
钻石精度处理测试
错误边界情况测试

7. 使用示例

7.1 钻石充值

POST /api/openapi/diamond/recharge
{
    "user_id": 12345,
    "amount": 100.5,
    "order_id": "ORDER_20250614_001",
    "remark": "游戏内购买道具"
}

7.2 钻石提取

POST /api/openapi/diamond/withdraw
{
    "user_id": 12345,
    "amount": 50.25,
    "order_id": "WITHDRAW_20250614_001",
    "remark": "用户提现"
}

7.3 查询账户余额

GET /api/openapi/diamond/recharge-balance  // 查询充值账户余额
GET /api/openapi/diamond/withdraw-balance  // 查询提取账户余额

8. 安全考虑

8.1 权限控制

充值需要 FUND_RECHARGE 权限
提取需要 FUND_WITHDRAW 权限
查询需要 FUND_READ 权限
权限风险级别设置为4（高风险）

8.2 数据验证

严格的金额格式和精度验证
用户存在性和状态验证
账户余额充足性验证
完整的事务回滚机制

8.3 操作日志

记录所有充值和提取操作
包含应用ID、用户ID、金额等关键信息
支持操作追踪和审计
异常情况详细记录

9. 文件变更清单

新增文件

app/Module/OpenAPI/Services/DeveloperAccountService.php - 开发者账户管理服务
app/Module/OpenAPI/Handlers/Fund/DiamondRechargeHandler.php - 钻石充值Handler
app/Module/OpenAPI/Handlers/Fund/DiamondWithdrawHandler.php - 钻石提取Handler
app/Module/OpenAPI/Validations/DiamondRechargeValidation.php - 充值验证类
app/Module/OpenAPI/Validations/DiamondWithdrawValidation.php - 提取验证类
app/Module/OpenAPI/Validators/DiamondAmountValidator.php - 钻石金额验证器
app/Module/OpenAPI/Validators/UserExistenceValidator.php - 用户存在性验证器
app/Module/OpenAPI/Tests/DiamondOperationTest.php - 功能测试
app/Module/OpenAPI/Tests/DiamondApiTest.php - API测试

修改文件

app/Module/OpenAPI/Enums/SCOPE_TYPE.php - 扩展权限范围
app/Module/OpenAPI/Controllers/ApiController.php - 添加新的API方法
app/Module/OpenAPI/Services/RouteRegistrationService.php - 注册新路由
app/Module/OpenAPI/Services/HandlerRegistrationService.php - 注册新Handler
app/Module/OpenAPI/README.md - 更新文档说明

10. 后续建议

10.1 功能扩展

支持批量充值/提取操作
添加充值/提取限额配置
实现自动对账和结算功能
支持多币种充值/提取

10.2 监控完善

添加实时余额监控
实现异常交易告警
完善操作统计分析
支持财务报表生成

10.3 安全增强

添加操作频率限制
实现多重签名验证
支持风险控制规则
完善审计日志系统

11. 总结

成功扩展了 OpenAPI 模块的钻石充值/提取功能，实现了：

✅ 完整的权限体系 - 新增专用权限范围，支持细粒度控制
✅ 自动账户管理 - 为每个开发者应用分配专用账户
✅ 安全的资金操作 - 完整的验证和事务处理机制
✅ 标准的API接口 - 遵循项目规范的Handler机制
✅ 完善的测试覆盖 - 全面的单元测试和功能测试
✅ 详细的文档说明 - 完整的使用指南和示例

该功能为 OpenAPI 模块提供了强大的资金管理能力，支持开发者安全、便捷地进行钻石充值和提取操作。

142134-扩展OpenAPI模块增加钻石充值提取功能.md 6.9 KB Permalink History Raw