Initial commit

2026-05-13 10:30:19 +08:00
commit a2a693885b
38 changed files with 5757 additions and 0 deletions
@@ -0,0 +1,142 @@
+# ZXChain SDK 使用文档
+
+## 初始化客户端
+
+SDK 不主动读取 `.env`，需要自己管理配置，并把凭据传给 SDK。
+
+```go
+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 访问密钥。
+
+## 存证和生成证书并一起返回
+
+`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",        //可选参数，可以不传
+
+    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值。
+- `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`：存证时写入的业务场景信息。
+