kknongchang_2506/AiWork/202506/181445-URS余额检查功能实现.md

URS余额检查功能实现

任务概述

完成URS系统的余额检查（check）功能，允许URS系统查询用户在农场系统中的钻石余额和提取费用信息。

实现内容

1. 完善UrsCheckWebhook处理器

文件: ThirdParty/Urs/Webhook/UrsCheckWebhook.php

功能:

• 处理URS系统发送的余额检查请求
• 验证请求参数（user_id, amount）
• 查找URS用户对应的农场用户
• 获取用户钻石余额
• 计算提取手续费
• 检查余额是否足够提取
• 返回详细的余额和费用信息

关键方法:

• handler(): 主处理方法，验证参数并调用核心逻辑
• processCheck(): 核心余额检查逻辑
• validateCheckRequest(): 请求参数验证

2. 核心业务逻辑

processCheck方法实现:

1. 用户映射查找: 根据URS用户ID查找对应的农场用户ID
2. 手续费计算: 使用TransferThirdPartyService计算提取手续费
3. 余额获取: 获取用户钻石余额（fund_id=2）
4. 余额检查: 判断余额是否足够支付本金+手续费
5. 结果返回: 返回详细的检查结果

3. 返回数据格式

{
    "check": true/false,           // 是否允许提取
    "diamond_balance": "49.9950",  // 钻石余额
    "principal_total": "10.0000",  // 本金总数
    "fee_total": "0.0000",         // 手续费总数
    "required_total": "10.0000",   // 所需总数
    "message": "余额充足，允许提取"  // 状态消息
}

测试验证

测试脚本

文件: test_urs_check_webhook.php

功能:

• 模拟URS系统发送余额检查请求
• 正确生成签名验证
• 测试多种场景
• 验证响应结果

测试场景和结果

场景1：余额充足

用户ID: 10003 (URS) -> 39026 (农场)
检查金额: 10.0000 钻石
用户余额: 49.9950 钻石
手续费: 0.0000 钻石
所需总额: 10.0000 钻石
结果: ✅ 允许提取

场景2：余额不足

用户ID: 10003 (URS) -> 39026 (农场)
检查金额: 1000000.0000 钻石
用户余额: 49.9950 钻石
手续费: 0.0000 钻石
所需总额: 1000000.0000 钻石
结果: ❌ 不允许提取（余额不足）

场景3：零余额用户

用户ID: 88888 (URS) -> 39036 (农场)
检查金额: 50.0000 钻石
用户余额: 0.0000 钻石
手续费: 0.0000 钻石
所需总额: 50.0000 钻石
结果: ❌ 不允许提取（余额不足）

技术要点

1. 签名验证

• 使用与WebhookDispatchService一致的签名算法
• 参数按字母顺序排序
• 使用HMAC-SHA256生成签名

2. 余额计算

• 钻石余额从存储格式（分）转换为显示格式（元）
• 使用number_format($balance / 10000, 4)进行格式化
• 保持4位小数精度

3. 手续费计算

• 调用TransferThirdPartyService::calculateWithdrawFee方法
• 支持汇率转换和手续费率计算
• 返回详细的费用信息

4. 错误处理

• 完整的异常捕获和日志记录
• 详细的错误信息返回
• 支持调试和问题排查

5. 用户映射处理

• 自动查找URS用户到农场用户的映射关系
• 处理用户不存在的情况
• 记录详细的查询日志

配置要求

Transfer应用配置

• 应用ID: 2 (urs)
• 关联第三方应用ID: 11 (out_id3字段)
• 手续费配置（当前为0%）
• 汇率配置（当前为1:1）

URS用户映射

• 表: kku_urs_promotion_user_mappings
• 字段: urs_user_id -> farm_user_id
• 状态: status = 1 (激活)

钻石账户

• 资金类型ID: 2 (钻石)
• 存储格式: 分（整数）
• 显示格式: 元（4位小数）

部署说明

1. 代码部署: 确保UrsCheckWebhook文件已更新
2. 配置检查: 验证Transfer应用配置正确
3. 权限验证: 确保Webhook路由可访问
4. 测试验证: 运行测试脚本验证功能正常

日志记录

成功日志

URS余额检查完成 {
    "urs_user_id": "10003",
    "farm_user_id": 39026,
    "amount": "10.0000",
    "diamond_balance": "49.9950",
    "fee_amount": "0.0000",
    "required_total": "10.0000",
    "is_allowed": true
}

警告日志

URS余额检查失败：未找到用户映射关系 {
    "urs_user_id": "99999",
    "amount": "50.0000"
}

后续优化

1. 缓存机制: 添加余额查询缓存，提高响应速度
2. 限额控制: 添加单次和日累计提取限额检查
3. 风控机制: 添加异常检测和风险控制
4. 监控告警: 添加关键指标监控和异常告警
5. 性能优化: 优化数据库查询和计算逻辑

相关文档

• Transfer模块文档
• URS推广系统文档
• Webhook处理机制文档
• 第三方服务集成规范
• URS提取功能实现文档