# ZXChain SDK 使用文档

## 初始化客户端

SDK 不主动读取 `.env`，需要自己管理配置，并把凭据传给 SDK。

```go
import "git.yuanzoo.cn/zhangzhengqiang/popi-zxl"

client, err := zxchainsdk.NewSDKClient(
    os.Getenv("ZXCHAIN_SECRET_ID"),
    os.Getenv("ZXCHAIN_SECRET_KEY"),
    os.Getenv("ZXCHAIN_PRIVATE_KEY"),
)
if err != nil {
    log.Fatalf("初始化至信链客户端失败: %v", err)
}
```

需要的环境变量：

- `ZXCHAIN_SECRET_ID`：至信链访问密钥 ID。
- `ZXCHAIN_SECRET_KEY`：至信链访问密钥。
- `ZXCHAIN_PRIVATE_KEY`：至信链私钥，用于签名存证请求。
- `COS_BUCKET_URL`：证书上传 COS 桶地址。
- `COS_PUBLIC_BASE_URL`：证书公开访问基础地址。
- `COS_SECRET_ID`：COS 访问密钥 ID。
- `COS_SECRET_KEY`：COS 访问密钥。
- `ZXCHAIN_CERTIFICATE_FONT_PATH`：可选。证书绘制使用的中文字体路径；Windows 可用 `C:/Windows/Fonts/msyh.ttc`。

## 存证和生成证书并一起返回

`h4` 对应 SDK 方法：

```go
CreateSimpleHashAttestationCertificate(ctx, request)
```

它会完成以下流程：

```text
从 WorkPreviewURL 下载作品预览图
计算作品预览图 EvidenceHash
生成证据包并计算 SM3 Hash
调用至信链 Hash 存证
生成 Popi 证书图片
上传证书图片到 COS
返回 evId、txId、区块高度、证书地址等结果
```

示例：

```go
result, err := client.CreateSimpleHashAttestationCertificate(context.Background(), zxchainsdk.SimpleHashAttestationCertificateRequest{
    UserName:       "zzzzzq",
    UserID:         "56142321",
    WorkName:       "测试作品",
    TaskID:         "9999999",
    CompletedAt:    "2026.5.11 15:20:01",
    WorkPreviewURL: "https://your-cdn/path/work-preview.jpg",
    EvidenceHash:   "作品hash",        //可选参数，可以不传
    FontPath:       "C:/Windows/Fonts/msyh.ttc", // 可选；Windows 推荐微软雅黑，或配置 ZXCHAIN_CERTIFICATE_FONT_PATH

    CertificateStorage: &zxchainsdk.COSCertificateStorage{    //可选参数，可以不传
        BucketURL:     os.Getenv("COS_BUCKET_URL"),
        PublicBaseURL: os.Getenv("COS_PUBLIC_BASE_URL"),
        SecretID:      os.Getenv("COS_SECRET_ID"),
        SecretKey:     os.Getenv("COS_SECRET_KEY"),
    },
})
if err != nil {
    log.Fatalf("简化证书生成失败: %v", err)
}

fmt.Println("evId:", result.ReceiptID)
fmt.Println("txId:", result.RequestID)
fmt.Println("blockHeight:", result.BlockHeight)
fmt.Println("txTime:", result.TxTime)
fmt.Println("sm3Hash:", result.SM3Hash)
fmt.Println("certificateURL:", result.PopiCertificateCertificateImageURL)
fmt.Println("zxChainCertURL:", result.ZXChainCertURL)
```

请求参数：

- `UserName`：申请用户名称。
- `UserID`：申请用户 ID。
- `WorkName`：作品名称。
- `TaskID`：生成任务 ID。
- `CompletedAt`：作品完成时间。
- `WorkPreviewURL`：作品图片 URL。
- `EvidenceHash`：可选。作品文件哈希；不传时 SDK 会从 `WorkPreviewURL` 下载内容并自行计算hash值。
- `FontPath`：可选。中文字体路径；不传时 SDK 会自动查找 Windows/macOS/Linux 常见中文字体，也可以用 `ZXCHAIN_CERTIFICATE_FONT_PATH` 环境变量指定。Windows 常见可用路径：`C:/Windows/Fonts/msyh.ttc`、`C:/Windows/Fonts/simhei.ttf`、`C:/Windows/Fonts/simsun.ttc`。
- `CertificateStorage`：可选。COS 上传配置。

返回字段：

- `ReceiptID`：至信链 `evId`，后续给 `h3` 查询使用。
- `RequestID`：至信链 `txId`。
- `BlockHeight`：上链区块高度。
- `TxTime`：上链时间。
- `SM3Hash`：本次上链证据包的 SM3 Hash。
- `EvidenceHash`：作品预览图或业务传入证据的哈希。
- `PopiCertificateCertNo`：Popi 证书编号。
- `PopiCertificateVerifyURL`：Popi 证书二维码核验地址。
- `PopiCertificateCertificateImageURL`：Popi 证书图片公开地址。
- `ZXChainCertURL`：至信链官方证书地址。

## h3：查询 Hash 取证记录

`h3` 对应 SDK 方法：

```go
QueryHashAttestation(ctx, request)
```

Hash 存证成功后，可以用 `ReceiptID` 查询链上记录。

```go
result, err := client.QueryHashAttestation(context.Background(), zxchainsdk.HashAttestationQueryRequest{
    EvID: receiptID,
})
if err != nil {
    log.Fatalf("Hash 取证查询失败: %v", err)
}

fmt.Println("evId:", result.EvID)
fmt.Println("txId:", result.TxID)
fmt.Println("blockHeight:", result.BlockHeight)
fmt.Println("txTime:", result.TxTime)
fmt.Println("extendInfo:", result.ExtendInfo)
```

查询条件至少传一个：

- `EvID`：`h4` 返回的 `ReceiptID`。
- `Hash`：存证内容的 SM3 Hash。
- `TxID`：`h4` 返回的 `RequestID`。

返回字段：

- `EvID`：Hash 存证回执中的 `evId`。
- `TxID`：Hash 存证回执中的 `txId`。
- `BlockHeight`：上链区块高度。
- `TxTime`：官方返回的上链时间。
- `ExtendInfo`：存证时写入的业务场景信息。