# Pig Integration

<cite>
**本文档中引用的文件**   
- [api.go](file://utility/integration/pig/api.go)
- [api_test.go](file://utility/integration/pig/api_test.go)
- [account_login.go](file://internal/logic/camel_oil/account_login.go)
- [cron_tasks.go](file://internal/logic/camel_oil/cron_tasks.go)
- [cache.go](file://utility/cache/cache.go)
- [camel_oil_api.go](file://utility/integration/camel_oil_api/api.go)
</cite>

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

## 介绍
Pig Integration 文档详细介绍了在 kami_backend 项目中集成 Pig 接码平台的实现。该集成主要用于骆驼加油业务场景中的手机号获取和验证码检测。系统通过与 Pig 平台的 API 交互，自动化完成账号注册、验证码接收和登录流程，从而支持批量账号管理和订单处理。

## 项目结构
该项目是一个基于 Go 语言的后端服务，采用模块化设计，主要分为 API 接口层、业务逻辑层、数据访问层和集成服务层。Pig 集成位于 `utility/integration/pig` 目录下，作为独立的集成模块被业务逻辑层调用。

```mermaid
graph TD
subgraph "API Layer"
API[api/]
end
subgraph "Business Logic Layer"
Logic[internal/logic/]
end
subgraph "Integration Layer"
Integration[utility/integration/]
Pig[pig/]
CamelOilApi[camel_oil_api/]
KamiGateway[kami_gateway/]
end
subgraph "Data Access Layer"
DAO[internal/dao/]
end
API --> Logic
Logic --> Integration
Integration --> Pig
Integration --> CamelOilApi
Logic --> DAO
```

**Diagram sources**
- [project_structure](file://project_structure)

**Section sources**
- [project_structure](file://project_structure)

## 核心组件
Pig 集成的核心组件包括 `InternalClient` 结构体及其方法，如 `NewClient`、`getToken`、`GetAccountInfo` 和 `CheckVerifyCode`。这些组件共同实现了与 Pig 平台的认证、账号信息获取和验证码检测功能。

**Section sources**
- [api.go](file://utility/integration/pig/api.go#L1-L116)

## 架构概述
Pig 集成的架构设计遵循了客户端-服务器模式，其中 `InternalClient` 作为客户端与 Pig 平台的服务器进行 HTTP 通信。该集成通过缓存机制优化了 token 的获取，避免了频繁的认证请求，提高了系统的整体性能。

```mermaid
sequenceDiagram
participant Logic as 骆驼油业务逻辑
participant PigClient as Pig客户端
participant PigServer as Pig服务器
Logic->>PigClient : GetAccountInfo()
PigClient->>PigClient : getToken()
PigClient->>PigClient : 检查缓存中的token
alt 缓存命中
PigClient-->>PigClient : 返回缓存的token
else 缓存未命中
PigClient->>PigServer : POST /sms/?api=login
PigServer-->>PigClient : 返回token
PigClient->>PigClient : 缓存token
end
PigClient->>PigServer : POST /sms?api=getPhone
PigServer-->>PigClient : 返回手机号
PigClient-->>Logic : 返回手机号
```

**Diagram sources**
- [api.go](file://utility/integration/pig/api.go#L1-L116)

## 详细组件分析

### Pig 客户端分析
Pig 客户端实现了与 Pig 接码平台的完整交互流程，包括认证、账号信息获取和验证码检测。

#### Pig 客户端结构
```mermaid
classDiagram
class InternalClient {
+Client *gclient.Client
+NewClient() *InternalClient
+getToken(ctx context.Context) (string, error)
+GetAccountInfo(ctx context.Context) (string, error)
+CheckVerifyCode(ctx context.Context, phone string) (code string, received bool, err error)
}
InternalClient --> gclient.Client : "使用"
```

**Diagram sources**
- [api.go](file://utility/integration/pig/api.go#L1-L116)

#### 账号登录流程
```mermaid
flowchart TD
Start([开始登录]) --> GetPhone["获取手机号 (GetAccountInfo)"]
GetPhone --> SendCaptcha["发送验证码"]
SendCaptcha --> WaitCaptcha["等待验证码"]
WaitCaptcha --> CheckCode["检测验证码 (CheckVerifyCode)"]
CheckCode --> CodeReceived{"验证码已接收?"}
CodeReceived --> |否| WaitCaptcha
CodeReceived --> |是| Login["执行登录"]
Login --> End([登录完成])
```

**Diagram sources**
- [account_login.go](file://internal/logic/camel_oil/account_login.go#L1-L137)
- [cron_tasks.go](file://internal/logic/camel_oil/cron_tasks.go#L1-L242)

**Section sources**
- [api.go](file://utility/integration/pig/api.go#L1-L116)
- [account_login.go](file://internal/logic/camel_oil/account_login.go#L1-L137)

### 验证码检测任务分析
验证码检测任务是骆驼加油业务中的关键定时任务，负责定期检查待验证账号的验证码接收情况，并完成登录流程。

#### 验证码检测任务流程
```mermaid
flowchart TD
Start([开始任务]) --> QueryAccounts["查询待验证码账号"]
QueryAccounts --> Loop{"遍历账号"}
Loop --> GetPhone["获取账号手机号"]
GetPhone --> CheckCode["检测验证码 (CheckVerifyCode)"]
CheckCode --> CodeReceived{"验证码已接收?"}
CodeReceived --> |否| ContinueLoop["继续下一个账号"]
CodeReceived --> |是| ExecuteLogin["执行登录"]
ExecuteLogin --> UpdateStatus["更新账号状态为在线"]
UpdateStatus --> LogSuccess["记录成功日志"]
ContinueLoop --> Loop
Loop --> EndLoop{"遍历完成?"}
EndLoop --> |是| End([任务完成])
```

**Diagram sources**
- [cron_tasks.go](file://internal/logic/camel_oil/cron_tasks.go#L169-L241)

**Section sources**
- [cron_tasks.go](file://internal/logic/camel_oil/cron_tasks.go#L169-L241)

## 依赖分析
Pig 集成依赖于多个内部和外部组件，形成了一个复杂的依赖网络。

```mermaid
graph TD
PigClient[utility/integration/pig@InternalClient] --> GClient[github.com/gogf/gf/v2/net/gclient]
PigClient --> Cache[utility/cache]
PigClient --> GLog[github.com/gogf/gf/v2/os/glog]
PigClient --> GTime[github.com/gogf/gf/v2/os/gtime]
CamelOilLogic[internal/logic/camel_oil@sCamelOil] --> PigClient
CamelOilLogic --> CamelOilApi[utility/integration/camel_oil_api]
CamelOilLogic --> DAO[internal/dao]
CamelOilLogic --> Config[utility/config]
Cache --> Redis[github.com/gogf/gf/v2/contrib/nosql/redis/v2]
```

**Diagram sources**
- [api.go](file://utility/integration/pig/api.go#L1-L116)
- [account_login.go](file://internal/logic/camel_oil/account_login.go#L1-L137)
- [cron_tasks.go](file://internal/logic/camel_oil/cron_tasks.go#L1-L242)

**Section sources**
- [api.go](file://utility/integration/pig/api.go#L1-L116)
- [account_login.go](file://internal/logic/camel_oil/account_login.go#L1-L137)
- [cron_tasks.go](file://internal/logic/camel_oil/cron_tasks.go#L1-L242)

## 性能考虑
Pig 集成在设计时充分考虑了性能优化，主要体现在以下几个方面：

1. **Token 缓存**：通过 Redis 缓存 Pig 平台的认证 token，有效期为 24 小时，避免了频繁的认证请求。
2. **单例模式**：`InternalClient` 使用 sync.OnceFunc 确保全局唯一实例，减少了资源消耗。
3. **HTTP 客户端复用**：使用 g.Client() 创建的客户端实例被复用，避免了频繁创建和销毁 HTTP 客户端的开销。

**Section sources**
- [api.go](file://utility/integration/pig/api.go#L1-L116)
- [cache.go](file://utility/cache/cache.go#L1-L220)

## 故障排除指南
在使用 Pig 集成时可能遇到以下常见问题及解决方案：

1. **获取 token 失败**：检查 Pig 平台的用户名和密码是否正确，确保网络连接正常。
2. **获取手机号失败**：确认 Pig 平台是否有可用的手机号资源，检查 API 接口是否正常。
3. **验证码检测超时**：增加检测间隔时间，或检查 Pig 平台的短信发送是否正常。
4. **登录失败**：检查骆驼加油平台的登录接口是否正常，确认验证码是否正确。

**Section sources**
- [api.go](file://utility/integration/pig/api.go#L1-L116)
- [account_login.go](file://internal/logic/camel_oil/account_login.go#L1-L137)
- [cron_tasks.go](file://internal/logic/camel_oil/cron_tasks.go#L1-L242)

## 结论
Pig Integration 在 kami_backend 项目中扮演着关键角色，为骆驼加油业务提供了稳定的手机号获取和验证码检测能力。该集成设计合理，性能优化到位，通过与骆驼加油平台和内部业务逻辑的紧密配合，实现了自动化账号管理和订单处理流程。未来可以考虑增加更多的错误处理和重试机制，进一步提高系统的稳定性和可靠性。