# 用户信息收集API

<cite>
**本文档引用文件**   
- [collection.go](file://api/restriction/v1/collection.go)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)
- [restriction.go](file://internal/service/restriction.go)
- [user_info.go](file://internal/model/user_info.go)
- [v_1_user_info.go](file://internal/dao/v_1_user_info.go)
- [aes_ecb.go](file://utility/verify/aes_ecb.go)
- [v_1_restrict_client_access_record.go](file://internal/dao/internal/v_1_restrict_client_access_record.go)
- [v_1_restrict_ip_record.go](file://internal/dao/internal/v_1_restrict_ip_record.go)
</cite>

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

## 简介
本文档详细描述了用户信息收集API的技术实现，重点介绍restraint_v1_user_info_collection端点的功能。该接口用于收集用户设备信息和访问行为数据，为风控决策提供支持。文档涵盖HTTP方法、请求参数结构、数据验证规则、响应模式、数据隐私保护措施、信息加密传输、存储安全策略以及与风控规则引擎的集成方式。同时说明该功能在反欺诈和异常行为检测中的应用，并提供性能优化建议。

## 项目结构
用户信息收集功能主要分布在API层、控制器层、服务层和数据访问层。核心功能位于restriction模块中，涉及用户设备信息收集、IP记录管理、访问行为分析等。

```mermaid
graph TB
subgraph "API层"
collection[api/restriction/v1/collection.go]
end
subgraph "控制器层"
controller[internal/controller/restriction/restriction_v1_user_info_collection.go]
end
subgraph "服务层"
service[internal/service/restriction.go]
end
subgraph "逻辑层"
logic[internal/logic/restriction/restriction.go]
end
subgraph "数据访问层"
dao[internal/dao/v_1_user_info.go]
record[internal/dao/internal/v_1_restrict_*]
end
collection --> controller
controller --> service
service --> logic
logic --> dao
logic --> record
```

**Diagram sources**
- [collection.go](file://api/restriction/v1/collection.go)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go)
- [restriction.go](file://internal/service/restriction.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)
- [v_1_user_info.go](file://internal/dao/v_1_user_info.go)

**Section sources**
- [collection.go](file://api/restriction/v1/collection.go)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go)

## 核心组件
用户信息收集API的核心组件包括请求处理、数据解密、签名验证、设备信息存储和IP记录管理。系统通过加密传输保护用户隐私，使用AES-CBC加密算法确保数据安全，并通过MD5签名验证保证数据完整性。

**Section sources**
- [collection.go](file://api/restriction/v1/collection.go)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go)
- [aes_ecb.go](file://utility/verify/aes_ecb.go)

## 架构概述
用户信息收集系统的架构分为四个主要层次：API接口层负责接收客户端请求，控制器层处理业务逻辑，服务层提供统一的服务接口，数据访问层负责与数据库交互。系统通过分层设计实现了关注点分离，提高了代码的可维护性和可扩展性。

```mermaid
graph TD
Client[客户端] --> API[API接口层]
API --> Controller[控制器层]
Controller --> Service[服务层]
Service --> DAO[数据访问层]
DAO --> Database[(数据库)]
style Client fill:#f9f,stroke:#333
style Database fill:#ccf,stroke:#333
```

**Diagram sources**
- [collection.go](file://api/restriction/v1/collection.go)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go)
- [restriction.go](file://internal/service/restriction.go)

## 详细组件分析

### 用户信息收集分析
用户信息收集功能通过POST请求接收加密的用户行为数据，经过解密和验证后存储到数据库中，用于后续的风控分析。

#### 请求处理流程
```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "API接口"
participant Controller as "控制器"
participant Service as "服务层"
participant DAO as "数据访问层"
Client->>API : POST /restriction/collection/userInfo
API->>Controller : 转发请求
Controller->>Controller : AES-CBC解密数据
Controller->>Controller : MD5签名验证
Controller->>Service : 调用SaveDeviceInfo
Service->>DAO : 存储设备信息
DAO-->>Service : 返回结果
Service-->>Controller : 返回结果
Controller-->>Client : 响应结果
```

**Diagram sources**
- [collection.go](file://api/restriction/v1/collection.go#L1-L23)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L0-L60)

#### 数据模型
```mermaid
classDiagram
class UserInfoCollectionReq {
+string Data
}
class responseModel {
+[]string IPs
+string DeviceID
+string DeviceModel
+string UserAgent
}
class responseWithSign {
+string Sign
}
class RestrictionDeviceInput {
+[]string IPs
+string RemoteIP
+string DeviceID
+string DeviceModel
+string UserAgent
}
UserInfoCollectionReq --> responseWithSign : "解密后"
responseWithSign --> responseModel : "组合"
responseModel --> RestrictionDeviceInput : "转换"
```

**Diagram sources**
- [collection.go](file://api/restriction/v1/collection.go#L1-L23)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L0-L60)
- [restriction.go](file://internal/model/restriction.go#L11-L17)

**Section sources**
- [collection.go](file://api/restriction/v1/collection.go#L1-L23)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L0-L60)

### 数据验证与安全
系统实现了多层次的数据验证和安全保护机制，确保用户信息的完整性和安全性。

#### 数据验证流程
```mermaid
flowchart TD
Start([开始]) --> Decrypt["AES-CBC解密"]
Decrypt --> DecryptSuccess{"解密成功?"}
DecryptSuccess --> |否| ReturnError["返回验证失败"]
DecryptSuccess --> |是| ParseJSON["解析JSON"]
ParseJSON --> ParseSuccess{"解析成功?"}
ParseSuccess --> |否| ReturnError
ParseSuccess --> |是| VerifySign["验证MD5签名"]
VerifySign --> SignValid{"签名有效?"}
SignValid --> |否| ReturnError
SignValid --> |是| CheckIP["检查IP一致性"]
CheckIP --> Process["处理业务逻辑"]
Process --> End([结束])
ReturnError --> End
```

**Diagram sources**
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L0-L60)
- [aes_ecb.go](file://utility/verify/aes_ecb.go#L0-L90)

## 依赖分析
用户信息收集功能依赖于多个核心组件和服务，形成了完整的依赖链。

```mermaid
graph LR
collection[API定义] --> controller[控制器]
controller --> service[服务接口]
service --> logic[业务逻辑]
logic --> dao[数据访问]
dao --> database[(数据库)]
controller --> crypto[加密组件]
crypto --> aes[AES-CBC]
crypto --> md5[MD5]
logic --> config[数据库配置]
logic --> utils[工具库]
```

**Diagram sources**
- [collection.go](file://api/restriction/v1/collection.go)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go)
- [restriction.go](file://internal/service/restriction.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)
- [aes_ecb.go](file://utility/verify/aes_ecb.go)

**Section sources**
- [collection.go](file://api/restriction/v1/collection.go)
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go)
- [restriction.go](file://internal/service/restriction.go)
- [restriction.go](file://internal/logic/restriction/restriction.go)

## 性能考虑
用户信息收集API在设计时考虑了性能优化，通过合理的缓存策略、数据库索引和异步处理机制确保系统的高效运行。建议在高并发场景下使用连接池和批量处理来进一步提升性能。

## 故障排除指南
当用户信息收集API出现问题时，可按照以下步骤进行排查：
1. 检查请求数据是否正确加密
2. 验证MD5签名是否匹配
3. 确认数据库连接是否正常
4. 检查AES密钥和IV是否正确
5. 查看日志中的错误信息

**Section sources**
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L0-L60)
- [aes_ecb.go](file://utility/verify/aes_ecb.go#L0-L90)

## 结论
用户信息收集API通过安全的加密传输和严格的验证机制，有效地收集用户设备信息和访问行为数据，为风控决策提供了可靠的数据支持。系统设计合理，层次分明，具有良好的可维护性和扩展性，能够满足反欺诈和异常行为检测的需求。