# 设备ID采集机制

<cite>
**本文档引用的文件**
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go)
- [device_id_record.go](file://internal/logic/restriction/device_id_record.go)
- [v_1_restrict_client_access_record.go](file://internal/dao/internal/v_1_restrict_client_access_record.go)
- [v_1_restrict_client_access_ip_relation.go](file://internal/dao/internal/v_1_restrict_client_access_ip_relation.go)
- [utils.go](file://utility/utils/utils.go)
- [v_1_restrict_client_access_record.go](file://internal/model/do/v_1_restrict_client_access_record.go)
- [v_1_restrict_client_access_ip_relation.go](file://internal/model/do/v_1_restrict_client_access_ip_relation.go)
- [v_1_restrict_client_access_record.go](file://internal/model/entity/v_1_restrict_client_access_record.go)
</cite>

## 目录
1. [简介](#简介)
2. [采集接口实现原理](#采集接口实现原理)
3. [数据传输格式与安全保护](#数据传输格式与安全保护)
4. [设备信息标准化处理](#设备信息标准化处理)
5. [隐私合规与数据最小化](#隐私合规与数据最小化)
6. [异常处理与降级策略](#异常处理与降级策略)
7. [数据库设计](#数据库设计)

## 简介
kami_backend系统实现了完整的设备ID采集机制，用于收集和分析客户端设备信息。该机制通过HTTP请求采集设备指纹、浏览器特征和网络信息，为系统安全、用户行为分析和反欺诈提供基础数据支持。采集过程注重隐私保护和数据最小化原则，确保符合相关法律法规要求。

## 采集接口实现原理

设备ID采集通过RESTful API接口实现，客户端在初始化时发送加密的设备信息到服务器。服务器端通过`restriction_v1_user_info_collection.go`中的`UserInfoCollection`方法处理采集请求。

采集流程如下：
1. 客户端收集设备信息并加密传输
2. 服务器解密并验证数据完整性
3. 提取HTTP请求中的实际IP地址
4. 比较采集IP与请求IP判断是否使用代理
5. 将设备信息存储到数据库

```mermaid
sequenceDiagram
participant Client as 客户端
participant Server as 服务器
participant DB as 数据库
Client->>Server : POST /v1/userInfoCollection
Server->>Server : 解密请求数据
Server->>Server : 验证签名完整性
Server->>Server : 获取客户端真实IP
Server->>Server : 检测代理使用情况
Server->>DB : 存储设备信息
DB-->>Server : 存储结果
Server-->>Client : 返回响应
```

**图示来源**
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L31-L59)

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

## 数据传输格式与安全保护

### 数据传输格式
客户端采集的数据采用JSON格式，并通过AES-CBC加密后进行Base64编码传输。传输的数据结构包含以下字段：

| 字段 | 类型 | 描述 |
|------|------|------|
| ips | 字符串数组 | 客户端采集到的所有IP地址 |
| deviceId | 字符串 | 设备唯一标识ID |
| deviceModel | 字符串 | 设备型号信息 |
| userAgent | 字符串 | 浏览器用户代理字符串 |
| sign | 字符串 | 数据签名，用于验证完整性 |

### 安全保护措施
系统采用多层安全保护机制确保数据传输和存储的安全性：

1. **传输加密**：使用AES-CBC算法对敏感数据进行加密
2. **数据完整性验证**：通过MD5签名验证数据未被篡改
3. **身份验证**：结合设备ID和IP地址进行访问控制
4. **防重放攻击**：通过会话ID和时间戳机制防止重放攻击

```mermaid
flowchart TD
A[原始设备数据] --> B[JSON序列化]
B --> C[MD5签名生成]
C --> D[添加签名字段]
D --> E[AES-CBC加密]
E --> F[Base64编码]
F --> G[HTTP传输]
G --> H[Base64解码]
H --> I[AES-CBC解密]
I --> J[JSON反序列化]
J --> K[签名验证]
K --> L[数据存储]
```

**图示来源**
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L0-L33)
- [device_id_record.go](file://internal/logic/restriction/device_id_record.go#L0-L44)

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

## 设备信息标准化处理

### 特征提取
系统对采集到的设备信息进行标准化处理和特征提取，主要包括：

1. **IP地址分析**：区分公网IP和私网IP，识别IPv4和IPv6地址
2. **设备模型归类**：将设备型号归类为PC、移动设备等类别
3. **浏览器特征提取**：从User-Agent中提取浏览器类型、版本和操作系统信息
4. **代理检测**：通过比较采集IP和请求IP判断是否使用代理或VPN

### 数据标准化
采集到的原始数据经过以下标准化处理：

```mermaid
classDiagram
class RestrictionDeviceInput {
+[]string IPs
+string RemoteIP
+string DeviceID
+string DeviceModel
+string UserAgent
}
class V1RestrictClientAccessRecord {
+int Id
+string VisitorId
+string DeviceModel
+string UserAgent
+bool IsUseProxy
+*gtime.Time CreatedAt
+*gtime.Time UpdatedAt
+*gtime.Time DeletedAt
}
class V1RestrictClientAccessIpRelation {
+int Id
+string Ip
+bool IsRemoteIp
+int RestrictIpRecordId
+int RestrictClientAccessRecordId
+string SessionId
+*gtime.Time CreatedAt
+*gtime.Time UpdatedAt
+*gtime.Time DeletedAt
}
RestrictionDeviceInput --> V1RestrictClientAccessRecord : "转换"
RestrictionDeviceInput --> V1RestrictClientAccessIpRelation : "关联"
```

**图示来源**
- [device_id_record.go](file://internal/logic/restriction/device_id_record.go#L0-L44)
- [v_1_restrict_client_access_record.go](file://internal/model/entity/v_1_restrict_client_access_record.go#L0-L21)

**本节来源**
- [device_id_record.go](file://internal/logic/restriction/device_id_record.go#L0-L113)
- [utils.go](file://utility/utils/utils.go#L0-L65)

## 隐私合规与数据最小化

### 隐私合规考虑
系统在设备信息采集过程中严格遵守隐私保护原则：

1. **知情同意**：在采集前明确告知用户并获取同意
2. **数据最小化**：仅采集业务必需的最少信息
3. **目的限制**：采集的数据仅用于安全验证和反欺诈等合法目的
4. **存储期限**：设置合理的数据保留期限，定期清理过期数据

### 数据最小化实现
系统通过以下方式实现数据最小化原则：

- 仅采集必要的设备标识信息，不收集个人身份信息
- 对IP地址进行适当脱敏处理
- 限制数据访问权限，仅授权人员可访问
- 定期审计数据使用情况，确保合规性

**本节来源**
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L0-L60)
- [device_id_record.go](file://internal/logic/restriction/device_id_record.go#L0-L113)

## 异常处理与降级策略

### 异常情况处理
系统对采集过程中的各种异常情况进行妥善处理：

1. **解密失败**：返回验证失败错误，记录日志供分析
2. **签名验证失败**：拒绝请求，防止数据篡改
3. **数据解析失败**：返回格式错误，提示客户端重新发送
4. **数据库存储失败**：返回服务器错误，触发重试机制

### 降级策略
当设备采集服务出现故障时，系统采用以下降级策略：

1. **服务降级**：暂时关闭非关键的设备信息采集功能
2. **缓存使用**：使用最近一次成功的设备信息作为备用
3. **异步处理**：将采集请求加入队列，后续重试处理
4. **监控告警**：实时监控采集成功率，异常时及时告警

```mermaid
flowchart TD
A[采集请求] --> B{服务是否正常?}
B --> |是| C[正常处理]
B --> |否| D[启用降级策略]
D --> E[使用缓存数据]
E --> F[记录降级日志]
F --> G[发送监控告警]
C --> H[返回成功]
D --> H
H --> I[客户端处理]
```

**图示来源**
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L31-L59)
- [device_id_record.go](file://internal/logic/restriction/device_id_record.go#L0-L44)

**本节来源**
- [restriction_v1_user_info_collection.go](file://internal/controller/restriction/restriction_v1_user_info_collection.go#L0-L60)
- [device_id_record.go](file://internal/logic/restriction/device_id_record.go#L0-L113)

## 数据库设计

### 数据表结构
设备ID采集机制涉及两个核心数据表：

#### 访问记录表 (restrict_client_access_record)
存储设备的基本访问信息，包括设备ID、设备型号、User-Agent和代理使用情况。

```mermaid
erDiagram
V1RestrictClientAccessRecord {
int id PK
string visitor_id
string device_model
string user_agent
bool is_use_proxy
datetime created_at
datetime updated_at
datetime deleted_at
}
```

#### IP关联表 (restrict_client_access_ip_relation)
存储IP地址与访问记录的关联关系，用于分析设备的网络访问模式。

```mermaid
erDiagram
V1RestrictClientAccessIpRelation {
int id PK
string ip
bool is_remote_ip
int restrict_ip_record_id FK
int restrict_client_access_record_id FK
string session_id
datetime created_at
datetime updated_at
datetime deleted_at
}
V1RestrictClientAccessRecord ||--o{ V1RestrictClientAccessIpRelation : "包含"
```

**图示来源**
- [v_1_restrict_client_access_record.go](file://internal/dao/internal/v_1_restrict_client_access_record.go#L33-L73)
- [v_1_restrict_client_access_ip_relation.go](file://internal/dao/internal/v_1_restrict_client_access_ip_relation.go#L0-L95)

**本节来源**
- [v_1_restrict_client_access_record.go](file://internal/dao/internal/v_1_restrict_client_access_record.go#L0-L93)
- [v_1_restrict_client_access_ip_relation.go](file://internal/dao/internal/v_1_restrict_client_access_ip_relation.go#L0-L95)
- [v_1_restrict_client_access_record.go](file://internal/model/do/v_1_restrict_client_access_record.go#L0-L23)
- [v_1_restrict_client_access_ip_relation.go](file://internal/model/do/v_1_restrict_client_access_ip_relation.go#L0-L24)
- [v_1_restrict_client_access_record.go](file://internal/model/entity/v_1_restrict_client_access_record.go#L0-L21)