Cloudsign 企业签名命令行接入

本包帮助您从本地 IPA 开始，上传原包、恢复中断、提交签名并取得本次任务的准确产物。
先完成上传，再核对或开通签名权益，最后明确提交签名。上传、开通和签名分别确认结果。

一、开始前准备

1. 准备 Python 3.10+、自己的原始 IPA 和受保护工作目录。解压后保留 cloudsign/、
   enterprise_upload.py 与 enterprise_signing.py 的相对位置，不需要额外安装第三方包。
2. 核对包内 SHA256SUMS，保存所用源码版本和独立摘要。不要只复制命令行脚本而遗漏 SDK。
3. 在开发者中心授权业务应用与所需动作。新建上传需要 enterprise:CreateApps 和
   enterprise:UploadVersions；更新还需 enterprise:ReadApps。账号能力、可用空间、
   余额和实际上传大小限制仍然生效。
4. 通过自己的服务端安全配置注入下列变量。Secret 不写入脚本或状态文件。

CLOUDSIGN_HOST：网站主机名，不带 https:// 和路径；两个命令行工具使用此变量。
CLOUDSIGN_BASE_URL：直接使用 SDK Client 时可读取的完整 HTTPS 网站来源。
CLOUDSIGN_ACCESS_KEY_ID：已授权的长期 AccessKey ID。
CLOUDSIGN_ACCESS_KEY_SECRET：同一组凭据的 Secret。

先运行 python enterprise_upload.py --help 和 python enterprise_signing.py --help，
确认运行环境与源码目录。以下命令中的应用、版本占位值须替换为接口返回的完整 ID。

二、上传新应用或更新已有应用

首次上传：
  python enterprise_upload.py new app.ipa --state new-upload.json

更新已有应用：
  python enterprise_upload.py update app-v2.ipa --app "<应用ID>" --state update-upload.json

每次独立上传使用新的状态文件。状态文件保存应用 ID、上传任务 ID、幂等键和原始摘要，
不保存 Secret 或文件传输 URL。平台选择传输服务，SDK 自动处理，业务端无需选择存储厂商。

工具读取普通 IPA 内 XML 或二进制 Info.plist。需要手动填写名称或处理 ZIP64 元数据时，
同时提供 --name 和 --bundle-id，并与真实 IPA 一致；平台仍会校验安装包内容。
上传采用分片方式，每片最多 32 MiB，已确认分片可以恢复。

三、确认原包已经保存

读取输出中的 app_id、upload_id、version_id 和 state。只有 state=succeeded 且取得
非空 version_id，才表示原包校验并保存完成。这个版本 ID 后续作为签名输入。

文件传输完成或进度达到 100% 仍不是安装包校验完成。使用 --no-wait 时，工具在提交
校验后返回；继续通过 resume 或 getUpload 查询原上传任务，不能直接进入签名成功分支。
工具不会自动购买套餐、核销开通密钥或提交签名。

四、中断后继续同一次上传

保留原始 IPA、原状态文件和原幂等键，再执行：
  python enterprise_upload.py resume app.ipa --state new-upload.json

命令行恢复使用同一网站、账号与 AccessKey ID，不用修改后的文件覆盖原始文件。
轮换 AccessKey 后，可在同一 API 应用下查询原上传列表，再通过 SDK 接管原任务；
不要通过删除状态文件或重新生成幂等键来绕过恢复检查。

五、开通权益并提交签名

先通过网站或 API 核对有效签名权益。余额开通先展示报价并确认付款；开通密钥核销
先明确确认不支持退款。操作见 /index/api_docs?guide=enterprise-activation。

使用上传得到的业务应用 ID 和原包版本 ID：
  python enterprise_signing.py start --app "<应用ID>" --source "<原包版本ID>" --state signing.json

恢复同一次签名任务：
  python enterprise_signing.py resume --state signing.json

工具需要 enterprise:ReadApps、enterprise:ReadVersions、enterprise:CreateJobs、
enterprise:ReadJobs 及相应签名写入许可。--certificate 使用平台返回的完整证书 ID，
还需独立选择证书权限。每次独立重签使用新的状态文件，不让多个进程共用同一文件。

工具在提交前保存幂等键，收到任务 ID 后先保存再等待。已有任务 ID 时恢复不会重复提交。
响应丢失且尚无任务 ID 时，仅在 24 小时内按原幂等键恢复；超过此限先用 listJobs 找回任务。

六、确认本次签名产物

status=succeeded 且 result_state=available 时，才读取本任务准确的签名包 version_id。
任务失败、被替代、旧任务无可靠关联或产物被清理时，都不能改取版本列表第一项代替。
客户端等待超时不会取消服务端任务，保留原任务 ID，稍后继续查询。

通常保存准确版本 ID 后，再由自己的后端申请该版本的短期下载凭证。下载另需授权。
可选 --download 还要求独立可信来源的 --sha256，以及明确的 --storage-origin 白名单；
它限制客户端可访问的文件传输来源，不是选择平台存储厂商。不要从凭证 URL 自动建立信任。

API 当前提供文件大小和短期地址，不提供可信安装包摘要。没有独立摘要时省略 --download。
下载不覆盖已有目标；凭证 URL 和 Secret 不打印到日志。

七、失败处理和继续阅读

配置或权限错误：检查网站、整组凭据、动作和资源范围，保存安全错误码与 request_id。
上传中断：保留原文件与状态文件，继续原上传任务。
签名响应丢失：先读取原状态和任务，不换键重复提交。
任务结束但失败：读取业务状态，不把受理、传输完成或通知接收当成成功。

完整教程：/index/api_docs?guide=enterprise-start
上传与更新：/index/api_docs?guide=enterprise-upload
签名与产物：/index/api_docs?guide=enterprise-signing
下载与完整性：/index/api_docs?guide=enterprise-versions
业务代码助手：/index/api_docs?guide=sdk-helpers
升级和支持范围：/index/api_docs?guide=sdk-support
