Cloudsign 服务端 SDK 源码预览

先完成一次只读调用，再接入具体业务。首次阅读按“一至四”执行；需要文件助手时，
再查看后面的专题。安装成功、HTTP 请求成功和业务任务完成分别判断。

一、选择语言与下载方式

本源码包可在自己的服务端直接使用，不表示已经发布到 Composer、npm、Maven
或其他公共包仓库。包内包含所选 SDK、项目配置、使用说明与 SHA256SUMS。
接入前核对文件摘要，并保存所用版本和源码包的独立摘要。

基本概念与接入路线：自己网站的 /index/api_docs?guide=concepts
完整中文指南：自己网站的 /index/api_docs?guide=resources
各语言入口：guide=sdk-php / sdk-node / sdk-go / sdk-java / sdk-rust / sdk-c
Python 客户端通过 Python SDK 与企业签名示例源码包提供，见 guide=sdk-python。
运行环境与升级回退：guide=sdk-support。
上传、等待与下载助手：guide=sdk-helpers，提供多语言可复用业务函数。

二、准备项目

将接口页复制的示例保存到以下位置，并保留包内的相对目录。
PHP：example.php 与 cloudsign-sdk/php/ 同级。PHP 8.3+，启用 ext-curl。
Node.js：example.mjs 与 cloudsign-sdk/node/ 同级。Node.js 20+，使用相对路径导入。
Go：example.go 与根 go.mod 同级。Go 1.22+，保留 require / replace 及 SDK 自身的 go.mod。
Java：Example.java 与 java-sources.txt 同级。JDK 17+，保留 cloudsign-sdk/java/src/。
Rust：保存到 cloudsign-sdk/rust/examples/example.rs。Rust 1.88+，保留原 Cargo.lock。
C：example.c、根 CMakeLists.txt 与 cloudsign-sdk/c/ 同级，使用 C11 和 CMake 3.20+。

C 依赖 libcurl 7.85+、OpenSSL 3+、cJSON 1.7.18+、PCRE2 10.42+ 与 pkg-config。
Rust 首次构建可能需要取得 Cargo.lock 中固定的依赖。原生文件助手已在 Linux
环境验证，其他系统需核对包内 README 与支持范围，不能由 HTTP 首调成功推断全部文件能力。

三、配置服务端凭据

CLOUDSIGN_BASE_URL：完整 HTTPS 网站来源，不带 API 路径、查询或分发短链。
CLOUDSIGN_ACCESS_KEY_ID：自己的 AccessKey ID。
CLOUDSIGN_ACCESS_KEY_SECRET：对应 Secret，通过受保护的运行配置注入。
CLOUDSIGN_SECURITY_TOKEN：临时凭据必须传同一组令牌，长期凭据不填写。
CLOUDSIGN_IDEMPOTENCY_KEY：仅写入需要。首次请求前保存，同一操作重试保持原值。

长期 Secret 不得放入浏览器、Vue、iOS 或安卓客户端。终端接入使用自己的后端，
或者已经登记并批准的 OAuth。沙箱使用独立凭据与入口，不与生产混用。

四、完成第一次调用

接口页和各语言指南均提供完整的身份查询示例。先保存并运行只读代码，核对账号与权限：

PHP：
  php example.php
Node.js：
  node example.mjs
Go：
  go run example.go
Java：
  javac --release 17 -encoding UTF-8 -d classes "@java-sources.txt"
  java -cp classes Example
Rust：
  cargo run --locked --manifest-path cloudsign-sdk/rust/Cargo.toml --example example
C：
  cmake -S . -B build
  cmake --build build -j2
  ./build/cloudsign_api_example

退出码 0 并输出 RequestId 表示本次身份查询成功。需要核对身份时，读取响应 data 中
的 owner_id、actions 和 resources；示例只输出 RequestId，不打印完整数据。
错误输出状态、错误码与 RequestId。不要记录整个响应、Secret、
临时授权 URL 或设备数据。读取正常后，再按业务需要授权写入；付款、退款、核销、
删除和签名均为真实操作，需按对应指南明确确认。

若命令使用 APP_ID、VERSION_ID 等 Shell 变量，先设置为已保存的完整业务 ID，
或直接替换命令中的占位值；SDK 不会自动为调用方赋值。

五、C SDK 任务助手

分页与已有任务等待：
  ./build/cloudsign_helpers_example pages
  ./build/cloudsign_helpers_example waitJob "<应用ID>" "<签名任务ID>"
  ./build/cloudsign_helpers_example waitUpload "<应用ID>" "<上传任务ID>"

分页和等待都有页数、次数及总时长上限。任务结束仍需检查是否成功；达到等待上限
不会取消服务端任务。继续原记录，不因客户端超时而创建另一项上传或签名。

下载：cloudsign_download_package 消费已经取得的凭证，并核对预期大小和可信 SHA-256。
准备 CLOUDSIGN_STORAGE_ORIGIN 与 CLOUDSIGN_EXPECTED_SHA256，按需配置
CLOUDSIGN_API_CA_FILE / CLOUDSIGN_STORAGE_CA_FILE，再运行包内 download-example.c。
API 当前提供大小和短期 URL，不提供可信安装包摘要；没有独立可信摘要时，不跳过校验。
目标已存在不覆盖，存储地址不从不可信凭证自动加入白名单。

单分片传输：cloudsign_upload_part 用于已申报的一个分片。先确认是否已完成，缺片时
再取凭证传输，之后由 API 再次确认。保存任务、序号、大小、摘要和原确认键。
存储 2xx 或对象已存在不代表平台确认成功。

完整恢复上传：cloudsign_upload_begin / cloudsign_upload_transfer 组织整次分片上传，
调用方负责先保存创建键和检查点。包内 upload-example.c 使用私有状态文件、排他锁、
fsync 与原子替换；中断后继续同一个任务。不要把另一份文件接到旧任务。

Webhook：使用原始正文和四个签名头验证 CSWH1，再核对可信订阅及应用归属。
普通事件在持久事务中去重并保存结果后才生成回执；挑战验签后可直接回显 challenge
和 proof。webhook-example.c 是验证与挑战演示，不会替接收端实现 HTTP 服务或数据库事务。

六、C 强类型请求和响应

接口成功响应可使用 models.h 的解码器和 getter。解码成功后，由独立快照拥有字段；
通过 cloudsign_decoded_free 释放。借用的子指针不能单独 free、修改或与释放并发使用。
presence_* 区分未返回、null 与真实值，不能把 false、零或空集合当作字段不存在。
整数使用 int64_t，金额保持十进制字符串。示例见 models-example.c。

requests.h 提供 cloudsign_input_* 与 cloudsign_build_*。输入清零后，为已填写字段
设置 CLOUDSIGN_FIELD_VALUE，使用命名枚举和明确的联合标签。构建是本地操作，
成功后持有 cloudsign_built_request，在使用只读视图期间保留所属请求对象，最后按接口释放。
cloudsign_send_built_request 才会显式发送请求；幂等键和业务确认不能省略。

请求正文限制为 16 KiB / 32 层；响应原文最多 2 MiB，模型缓冲最多 16 MiB，另有 JSON 内存。
错误响应不解码为成功模型，失败不返回半个有效对象。ABI 属于预览，请固定版本并重建。
完整参数、生命周期、错误处理与各 CLI 用法见网站 guide=sdk-c 和包内 C README。
