kami_backend/.qoder/repowiki/zh/content/API端点参考/商户管理API/盗单处理管理.md

盗单处理管理

**本文档中引用的文件** - [steal.go](file://api/merchant/v1/steal.go) - [merchant_v1_steal_create.go](file://internal/controller/merchant/merchant_v1_steal_create.go) - [merchant_v1_steal_list.go](file://internal/controller/merchant/merchant_v1_steal_list.go) - [merchant_v1_steal_update.go](file://internal/controller/merchant/merchant_v1_steal_update.go) - [merchant_v1_steal_delete.go](file://internal/controller/merchant/merchant_v1_steal_delete.go) - [merchant_v1_steal_status_get.go](file://internal/controller/merchant/merchant_v1_steal_status_get.go) - [merchant_v1_steal_status_set.go](file://internal/controller/merchant/merchant_v1_steal_status_set.go) - [merchant_v1_steal_stats.go](file://internal/controller/merchant/merchant_v1_steal_stats.go) - [merchant_v1_steal_record_list.go](file://internal/controller/merchant/merchant_v1_steal_record_list.go) - [steal_rule.go](file://internal/service/steal_rule.go) - [steal_rule.go](file://internal/model/steal_rule.go)

目录

1. 简介
2. 核心组件
3. API端点说明
4. 数据结构与匹配逻辑
5. 集成与执行时机
6. 权限控制机制
7. 错误处理与监控建议
8. 使用示例
9. 结论

简介

本文档详细描述了盗单处理管理API的设计与实现，涵盖盗单规则的创建、查询、更新、删除、状态管理、统计和记录查询等核心功能。该系统旨在通过灵活的规则配置，自动识别并处理潜在的盗单行为，保障商户交易安全。API设计遵循RESTful规范，提供清晰的接口定义和统一的响应格式。

核心组件

本系统的核心组件包括API定义层、控制器层、服务层和数据模型层。API定义层（steal.go）负责声明所有端点的HTTP方法、路径和数据结构；控制器层（如merchant_v1_steal_create.go等）处理请求并调用服务层；服务层（steal_rule.go）封装业务逻辑；数据模型层（steal_rule.go in model）定义数据传输对象。

核心组件来源

• steal.go
• merchant_v1_steal_create.go
• steal_rule.go
• steal_rule.go

API端点说明

以下表格详细列出了盗单处理管理的所有API端点。

端点名称	HTTP方法	URL路径	功能描述
merchant_v1_steal_create	POST	/merchant/config/stealRule/create	创建新的盗单规则
merchant_v1_steal_list	GET	/merchant/config/stealRule/list	查询盗单规则列表
merchant_v1_steal_update	POST	/merchant/config/stealRule/update	更新指定的盗单规则
merchant_v1_steal_delete	DELETE	/merchant/config/stealRule/update	删除指定的盗单规则
merchant_v1_steal_status_get	GET	/merchant/config/stealRule/status	获取全局盗单功能状态
merchant_v1_steal_status_set	POST	/merchant/config/stealRule/status	设置全局盗单功能状态
merchant_v1_steal_stats	GET	/merchant/config/stealRule/stats	获取盗单统计信息
merchant_v1_steal_record_list	GET	/merchant/config/stealRule/record	查询盗单处理记录

API端点来源

• steal.go

数据结构与匹配逻辑

盗单规则数据结构

盗单规则的核心数据结构为MerchantHiddenConfig，包含以下关键字段：

• name: 规则名称
• merchantUid: 关联的商户ID
• roadUid: 通道ID
• amount: 偷卡金额间隔
• faceAmount: 偷卡面额
• delayDurationMin / delayDurationMax: 处理延迟时间范围
• enable: 启用状态
• strategy: 处理策略
• amountRule: 金额规则数组

匹配与处理逻辑

系统通过比较订单金额与amountRule中的规则进行匹配。在merchant_v1_steal_create.go中，创建规则时会校验amountRule中的每个值是否不大于faceAmount，确保规则的合理性。匹配成功后，根据配置的策略和延迟时间执行相应的处理动作。

flowchart TD
Start([接收到订单]) --> CheckStatus["检查盗单功能全局状态"]
CheckStatus --> |关闭| End1([正常处理])
CheckStatus --> |开启| MatchRule["匹配盗单规则"]
MatchRule --> RuleMatched{"规则匹配?"}
RuleMatched --> |否| End2([正常处理])
RuleMatched --> |是| ApplyStrategy["应用处理策略"]
ApplyStrategy --> Delay["延迟 delayDurationMin-Max"]
Delay --> Execute["执行盗单处理"]
Execute --> Log["记录处理日志"]
Log --> End3([完成])

数据结构来源

• steal.go
• merchant_v1_steal_create.go

集成与执行时机

盗单处理模块深度集成于订单处理流程中。当一个新订单进入系统后，订单处理服务会首先调用盗单规则服务进行匹配检查。此检查发生在订单验证和支付处理之前，作为风险控制的第一道防线。如果订单被识别为潜在盗单，则会根据配置的策略（如延迟处理、标记、拒绝等）进行相应操作，而不是立即执行正常的订单流程。

权限控制机制

系统通过基于角色的访问控制（RBAC）来确保只有授权用户可以修改盗单规则。所有对盗单规则的写操作（创建、更新、删除、状态设置）都需要经过身份验证和权限校验。控制器层通过中间件验证用户身份和权限，只有具备“盗单设置”标签（tags:"偷卡设置"）权限的用户才能访问这些API端点。

错误处理与监控建议

错误处理

系统在merchant_v1_steal_create.go中实现了基础的业务逻辑校验，例如检查偷卡金额是否超过面额。对于无效请求，服务会返回带有明确错误信息的响应。所有API调用都应进行异常捕获，确保不会因内部错误导致服务中断。

监控建议

1. 日志监控：记录所有盗单规则的变更和处理记录，便于审计和追溯。
2. 统计分析：定期使用merchant_v1_steal_stats端点分析盗单发生频率和金额，评估规则有效性。
3. 告警机制：当盗单处理量异常激增时，触发告警通知管理员。
4. 性能监控：监控盗单规则匹配的响应时间，避免影响正常订单处理速度。

错误处理来源

• merchant_v1_steal_create.go

使用示例

创建盗单规则

POST /merchant/config/stealRule/create
Content-Type: application/json

{
  "name": "高风险订单监控",
  "merchantUid": "mch_123",
  "roadUid": "road_456",
  "amount": 100,
  "faceAmount": 500,
  "delayDurationMin": 300,
  "delayDurationMax": 600,
  "enable": 1,
  "strategy": 1,
  "amountRule": [101, 201, 301, 401]
}

查询盗单统计

GET /merchant/config/stealRule/stats?current=1&pageSize=10&dateRange[0]=2023-01-01&dateRange[1]=2023-12-31

结论

本文档全面介绍了盗单处理管理API的各个方面。该系统提供了一套完整的工具，使商户能够灵活地配置和管理盗单风险。通过精确的规则定义、严格的权限控制和详尽的监控能力，系统能够有效识别和处理潜在的盗单行为，保护商户利益。建议定期审查和更新盗单规则，以应对不断变化的风险模式。