tyapi-server/internal/infrastructure/external/alicloud/README.md

# 阿里云二要素验证服务

这个服务提供了调用阿里云身份证二要素验证API的功能，用于验证姓名和身份证号码是否匹配。

## 功能特性

- 身份证二要素验证（姓名 + 身份证号）
- 支持详细验证结果返回
- 支持简单布尔值判断
- 错误处理和中文错误信息

## 配置说明

### 必需配置

- `Host`: 阿里云API的域名地址
- `AppCode`: 阿里云市场应用的AppCode

### 配置示例

```go
host := "https://kzidcardv1.market.alicloudapi.com"
appCode := "您的AppCode"
```

## 使用方法

### 1. 创建服务实例

```go
service := NewAlicloudService(host, appCode)
```

### 2. 调用API

#### 身份证二要素验证示例

```go
// 构建请求参数
params := map[string]interface{}{
    "name":   "张三",
    "idcard": "110101199001011234",
}

// 调用API
responseBody, err := service.CallAPI("api-mall/api/id_card/check", params)
if err != nil {
    log.Printf("验证失败: %v", err)
    return
}

// 解析完整响应结构
var response struct {
    Msg     string `json:"msg"`
    Success bool   `json:"success"`
    Code    int    `json:"code"`
    Data    struct {
        Birthday string `json:"birthday"`
        Result   int    `json:"result"`
        Address  string `json:"address"`
        OrderNo  string `json:"orderNo"`
        Sex      string `json:"sex"`
        Desc     string `json:"desc"`
    } `json:"data"`
}

if err := json.Unmarshal(responseBody, &response); err != nil {
    log.Printf("响应解析失败: %v", err)
    return
}

// 检查响应状态
if response.Code != 200 {
    log.Printf("API返回错误: code=%d, msg=%s", response.Code, response.Msg)
    return
}

idCardData := response.Data

// 判断验证结果
if idCardData.Result == 1 {
    fmt.Println("身份证信息验证通过")
} else {
    fmt.Println("身份证信息验证失败")
}
```

#### 通用API调用

```go
// 调用其他阿里云API
params := map[string]interface{}{
    "param1": "value1",
    "param2": "value2",
}

responseBody, err := service.CallAPI("your/api/path", params)
if err != nil {
    log.Printf("API调用失败: %v", err)
    return
}

// 根据具体API的响应结构进行解析
// 每个API的响应结构可能不同，需要根据API文档定义相应的结构体
var response struct {
    Msg  string      `json:"msg"`
    Code int         `json:"code"`
    Data interface{} `json:"data"`
}

if err := json.Unmarshal(responseBody, &response); err != nil {
    log.Printf("响应解析失败: %v", err)
    return
}

// 处理响应数据
fmt.Printf("响应数据: %s\n", string(responseBody))
```

## 响应格式

### 通用响应结构

```json
{
    "msg": "成功",
    "success": true,
    "code": 200,
    "data": {
        // 具体的业务数据
    }
}
```

### 身份证验证响应示例

#### 成功响应 (code: 200)

```json
{
    "msg": "成功",
    "success": true,
    "code": 200,
    "data": {
        "birthday": "19840816",
        "result": 1,
        "address": "浙江省杭州市淳安县",
        "orderNo": "202406271440416095174",
        "sex": "男",
        "desc": "不一致"
    }
}
```

#### 参数错误响应 (code: 400)

```json
{
    "msg": "请输入有效的身份证号码",
    "code": 400,
    "data": null
}
```

### 错误响应

```json
{
    "msg": "AppCode无效",
    "success": false,
    "code": 400
}
```

## 错误处理

服务定义了以下错误类型：

- `ErrDatasource`: 数据源异常
- `ErrSystem`: 系统异常
- `ErrInvalid`: 身份证信息不匹配

## 注意事项

1. 请确保您的AppCode有效且有足够的调用额度
2. 身份证号码必须是18位有效格式
3. 姓名必须是真实有效的姓名
4. 建议在生产环境中添加适当的重试机制和超时设置
5. 请遵守阿里云API的使用规范和频率限制

## 依赖

- Go 1.16+
- 标准库：`net/http`, `encoding/json`, `net/url`