# 风控限制API

<cite>
**本文档中引用的文件**  
- [province.go](file://api/restriction/v1/province.go)
- [collection.go](file://api/restriction/v1/collection.go)
- [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go)
- [restriction_v1_query_all_province.go](file://internal/controller/restriction/restriction_v1_query_all_province.go)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go)
- [restriction_v1_block_order.go](file://internal/controller/restriction/restriction_v1_block_order.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)
- [ip_record.go](file://internal/logic/restriction/ip_record.go)
- [location.go](file://utility/integration/restriction/location.go)
- [consts.go](file://utility/integration/restriction/consts.go)
- [impl.go](file://utility/integration/restriction/impl.go)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介
本文档详细描述了风控限制API的功能实现，涵盖IP限制、地域限制和用户信息收集等核心功能。系统通过多级风控策略实现对用户访问行为的精细化控制，包括基于IP地理位置的访问控制、设备识别与限制、卡密关联限制等功能。API设计遵循RESTful规范，提供清晰的端点定义和安全的数据交互机制。

## 项目结构
风控限制功能主要分布在API层、控制器层、服务逻辑层和集成工具层，形成清晰的分层架构。各层职责分明，确保功能的可维护性和可扩展性。

```mermaid
graph TB
subgraph "API层"
A[province.go]
B[collection.go]
end
subgraph "控制器层"
C[restriction_v1_check_ip_allowed.go]
D[restriction_v1_query_all_province.go]
E[restriction_v1_user_info_collection.go]
F[restriction_v1_block_order.go]
end
subgraph "服务逻辑层"
G[restriction.go]
H[ip_record.go]
end
subgraph "集成工具层"
I[location.go]
J[consts.go]
K[impl.go]
end
A --> C
B --> E
B --> F
C --> G
D --> G
E --> G
F --> G
G --> H
G --> I
I --> J
I --> K
```

**图示来源**  
- [province.go](file://api/restriction/v1/province.go)
- [collection.go](file://api/restriction/v1/collection.go)
- [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go)
- [restriction_v1_query_all_province.go](file://internal/controller/restriction/restriction_v1_query_all_province.go)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go)
- [restriction_v1_block_order.go](file://internal/controller/restriction/restriction_v1_block_order.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)
- [ip_record.go](file://internal/logic/restriction/ip_record.go)
- [location.go](file://utility/integration/restriction/location.go)
- [consts.go](file://utility/integration/restriction/consts.go)
- [impl.go](file://utility/integration/restriction/impl.go)

**本节来源**  
- [api/restriction/v1](file://api/restriction/v1)
- [internal/controller/restriction](file://internal/controller/restriction)

## 核心组件
风控限制系统的核心组件包括IP地理位置查询、地域限制检查、用户信息收集和订单封禁功能。系统通过集成多个第三方IP定位服务实现高可用的地理位置识别，并结合商户部署策略进行访问控制决策。所有限制记录持久化存储于数据库，支持后续审计和分析。

**本节来源**  
- [restriction.go](file://internal/logic/restriction/restriction.go#L0-L173)
- [location.go](file://utility/integration/restriction/location.go#L0-L38)

## 架构概述
系统采用分层架构设计，从API接口到服务逻辑再到外部集成，形成完整的风控处理链路。API层定义清晰的端点契约，控制器层处理请求调度，服务层实现核心业务逻辑，集成层提供外部服务访问能力。

```mermaid
graph TD
Client[客户端] --> API[API接口]
API --> Controller[控制器]
Controller --> Service[服务逻辑]
Service --> Cache[(缓存)]
Service --> Database[(数据库)]
Service --> External[第三方服务]
External --> CSDN[CSDN]
External --> PCOnline[PCOnline]
External --> IP66[IP66]
External --> MeiTu[美图]
```

**图示来源**  
- [restriction.go](file://internal/logic/restriction/restriction.go)
- [location.go](file://utility/integration/restriction/location.go)
- [impl.go](file://utility/integration/restriction/impl.go)

## 详细组件分析

### IP访问控制分析
系统通过多源IP地理位置服务实现高可用的IP定位功能，采用重试机制确保查询成功率。当主要服务失败时，自动切换到备用服务，保证系统稳定性。

#### 类图
```mermaid
classDiagram
class Location {
<<interface>>
+QueryLocationByIP(ctx, ip) Response, error
}
class CSDNClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class PcOnlineClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class OlToolsClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class IdCdClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class MeiTuClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class VoClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class DBIPClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class QJQQClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class IQIYIClient {
+QueryLocationByIP(ctx, ip) Response, error
}
class IP66Client {
+QueryLocationByIP(ctx, ip) Response, error
}
Location <|-- CSDNClient
Location <|-- PcOnlineClient
Location <|-- OlToolsClient
Location <|-- IdCdClient
Location <|-- MeiTuClient
Location <|-- VoClient
Location <|-- DBIPClient
Location <|-- QJQQClient
Location <|-- IQIYIClient
Location <|-- IP66Client
```

**图示来源**  
- [location.go](file://utility/integration/restriction/location.go#L0-L38)
- [impl.go](file://utility/integration/restriction/impl.go#L0-L44)

### 省份查询分析
提供获取全国所有省份列表的API接口，支持前端下拉选择等场景。系统维护完整的省份列表，包括特殊行政区和海外地区。

#### 序列图
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API接口"
participant Controller as "控制器"
participant Service as "服务层"
Client->>API : GET /restriction/location/getAllProvince
API->>Controller : 调用QueryAllProvince
Controller->>Service : 调用GetAllProvince
Service-->>Controller : 返回省份列表
Controller-->>API : 返回响应
API-->>Client : 返回省份列表
```

**图示来源**  
- [province.go](file://api/restriction/v1/province.go#L0-L28)
- [restriction_v1_query_all_province.go](file://internal/controller/restriction/restriction_v1_query_all_province.go#L0-L15)
- [restriction.go](file://internal/logic/restriction/restriction.go#L45-L47)

### 用户信息收集分析
实现用户设备信息收集功能，通过加密数据传输确保信息安全。系统验证数据签名防止篡改，并记录设备指纹用于后续风控决策。

#### 流程图
```mermaid
flowchart TD
Start([开始]) --> Decrypt["解密请求数据"]
Decrypt --> Validate["验证数据签名"]
Validate --> SignatureValid{"签名有效?"}
SignatureValid --> |否| ReturnError["返回签名错误"]
SignatureValid --> |是| GetRemoteIP["获取客户端IP"]
GetRemoteIP --> CheckProxy["检查是否使用代理"]
CheckProxy --> SaveDevice["保存设备信息"]
SaveDevice --> End([结束])
ReturnError --> End
```

**图示来源**  
- [collection.go](file://api/restriction/v1/collection.go#L0-L23)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L0-L60)
- [restriction.go](file://internal/logic/restriction/restriction.go)

**本节来源**  
- [collection.go](file://api/restriction/v1/collection.go#L0-L23)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L0-L60)

## 依赖分析
系统依赖多个外部IP定位服务和内部服务组件，形成复杂的依赖网络。通过接口抽象降低耦合度，支持服务的灵活替换和扩展。

```mermaid
graph TD
RestrictionService --> IPRecordService
RestrictionService --> MerchantDeployInfoService
RestrictionService --> OrderSummaryService
RestrictionService --> Database
RestrictionService --> CSDNService
RestrictionService --> PCOnlineService
RestrictionService --> IP66Service
RestrictionService --> MeiTuService
```

**图示来源**  
- [restriction.go](file://internal/logic/restriction/restriction.go)
- [location.go](file://utility/integration/restriction/location.go)
- [consts.go](file://utility/integration/restriction/consts.go)

**本节来源**  
- [restriction.go](file://internal/logic/restriction/restriction.go#L0-L173)
- [location.go](file://utility/integration/restriction/location.go#L0-L38)

## 性能考虑
系统通过缓存IP地理位置信息减少外部服务调用，提高响应速度。采用并发处理和重试机制平衡性能与可靠性，确保在高并发场景下的稳定运行。

## 故障排除指南
常见问题包括IP定位服务不可用、数据签名验证失败和数据库连接异常。建议检查网络连接、服务配置和密钥设置，确保各组件正常运行。

**本节来源**  
- [restriction_v1_check_ip_allowed.go](file://internal/controller/restriction/restriction_v1_check_ip_allowed.go#L0-L69)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L0-L60)
- [impl.go](file://utility/integration/restriction/impl.go#L0-L44)

## 结论
风控限制API提供了完整的访问控制解决方案，通过多维度限制策略保障系统安全。系统设计考虑了高可用性、安全性和可扩展性，能够满足复杂的业务场景需求。