# 盗单处理管理

<cite>
**本文档中引用的文件**  
- [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)
</cite>

## 目录
1. [简介](#简介)
2. [核心组件](#核心组件)
3. [API端点说明](#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](file://api/merchant/v1/steal.go#L1-L116)
- [merchant_v1_steal_create.go](file://internal/controller/merchant/merchant_v1_steal_create.go#L1-L25)
- [steal_rule.go](file://internal/service/steal_rule.go#L1-L41)
- [steal_rule.go](file://internal/model/steal_rule.go#L1-L34)

## 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](file://api/merchant/v1/steal.go#L1-L116)

## 数据结构与匹配逻辑

### 盗单规则数据结构
盗单规则的核心数据结构为`MerchantHiddenConfig`，包含以下关键字段：
- `name`: 规则名称
- `merchantUid`: 关联的商户ID
- `roadUid`: 通道ID
- `amount`: 偷卡金额间隔
- `faceAmount`: 偷卡面额
- `delayDurationMin` / `delayDurationMax`: 处理延迟时间范围
- `enable`: 启用状态
- `strategy`: 处理策略
- `amountRule`: 金额规则数组

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

```mermaid
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](file://api/merchant/v1/steal.go#L25-L45)
- [merchant_v1_steal_create.go](file://internal/controller/merchant/merchant_v1_steal_create.go#L10-L15)

## 集成与执行时机

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

## 权限控制机制

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

## 错误处理与监控建议

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

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

**错误处理来源**
- [merchant_v1_steal_create.go](file://internal/controller/merchant/merchant_v1_steal_create.go#L10-L15)

## 使用示例

### 创建盗单规则
```http
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]
}
```

### 查询盗单统计
```http
GET /merchant/config/stealRule/stats?current=1&pageSize=10&dateRange[0]=2023-01-01&dateRange[1]=2023-12-31
```

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