Machine service provider

机器服务 Provider B 与调用方示例

文件来源、Shell 与工作目录

从独立 sand-iam 源码仓 取得选定的 0.8.3 候选 revision，保留 sdk/ 与 examples/ 的相对目录关系。源码中已包含本页文件；源码候选不等于可下载的正式发行包，也不能混用历史 preview 的服务端与当前 SDK。下列命令使用 POSIX shell（Linux/macOS）；Windows 使用受控 POSIX shell，或按目标环境转换为 PowerShell 后另行验证。

把 SAND_IAM_ROOT 设置为包含 info.ini、sdk/ 与 examples/ 的 SandIAM 包根；独立源码仓中它是 sand-iam/，完整包解压后可能直接是解压目录。先检查该根，再进入本页目录：

: "${SAND_IAM_ROOT:?set the matching SandIAM package root}"
test -f "$SAND_IAM_ROOT/info.ini" && test -d "$SAND_IAM_ROOT/sdk/php" || exit 1
cd "$SAND_IAM_ROOT/examples/machine-service-client/provider" || exit 1

本页“本目录”及未注明的相对路径都以 examples/machine-service-client/provider/ 为基准。依赖安装、服务启动、schema执行和真实联调须具备相应环境授权；这里只明确落点，不代表本轮已运行。

源码入口对应独立 SandIAM 0.8.3 候选；SDK 与示例随该源码提供，0.8.3 已公开发布，具体资产与验收范围见版本与兼容性页面。正文操作说明沿用既有指南，本轮未重新执行依赖安装或真实业务联调；使用前核对服务端版本和隔离环境。公开历史 v0.7.6-preview 与当前源码候选的边界见版本与兼容性。

这是独立的轻量 PHP 业务服务及调用方示例。服务提供 GET /health 和 POST /provider/v1/documents/{id}/process。调用方使用本仓 PHP SDK 签发短期上下文， 仅通过 X-Sand-Iam-Context 请求头交接；服务端每次请求都调用 SDK 的 verifyContext()，包括幂等重放。

服务、受众和动作由部署环境固定，默认分别为 provider-b-document、provider-b、 document.process，调用请求不能覆盖。调用方和 Provider 必须注入相同值，真实验收可使用 隔离前缀而不占用生产协议名。验证成功后，服务锁定 PostgreSQL 中已有的 provider_b_document， 确认其 organization_id 与验证结果一致，再保存文档的 SHA-256 和字节数。 业务处理记录与成功审计在同一事务中提交；失败则回滚。

配置与运行

1. 经数据库负责人明确授权后，将 schema.pgsql 应用到已存在的隔离 PostgreSQL 业务数据库，并准备业务文档。示例不创建数据库、账号、sand_iam_* 或 sa_* 表。
2. 在本目录执行 composer install；锁文件固定本次可安装依赖，sand/iam-sdk 来自本仓 ../../../sdk/php。生成的 vendor/ 是可再生目录，不进入源码或候选包。
3. 按 .env.example 的配置项，通过部署环境和密钥管理系统注入配置，不提交真实 .env。 缺少必填配置或 DSN 不是 pgsql: 时，服务拒绝运行。
4. 使用内部 PHP 进程管理器部署 public/index.php。调用方执行 php caller/invoke.php <document-id>，并提供稳定的 PROVIDER_B_IDEMPOTENCY_KEY。

以上是接入步骤，不表示本仓已经执行数据库初始化、服务启动或真实联调。

需要在真实环境验证的行为

• 允许处理： 授予固定服务、受众和动作，处理调用方所属客户主体的文档，保留脱敏的请求与上下文编号用于关联审计。
• 拒绝处理： 未授权动作、错误受众、无效上下文、网络或协议错误、文档不存在、跨客户主体文档均应拒绝，且不产生处理记录。
• 撤销生效： 撤销凭证或服务授权后，使用此前签发的上下文及幂等键重试。服务先验权再查询重放记录，旧上下文不能绕过撤销。
• 幂等与冲突： (workload_client_id,idempotency_key) 唯一。同一文档及内容重复请求返回原处理结果；同一键改用其他文档或内容时返回 409，不新增处理记录。
• 审计与清理： provider_b_audit_log 保存请求编号、上下文编号、业务对象编号、结果及重放标记；幂等键仅保存 SHA-256，不保存上下文令牌、凭证、文档正文或密码。验收后清理隔离夹具与测试数据。

命中业务路由的 400/401/403/409/503 失败会尝试独立写入脱敏失败审计， 上下文令牌及幂等键仅保存摘要。审计写入失败不会允许业务处理，也不会改变原始拒绝结果。 通过请求编号、上下文编号及摘要证据关联 SandIAM 签发/验证审计与业务服务审计；运行器日志不能代替审计记录。

离线检查

在本目录执行 composer test，检查 PostgreSQL 配置限制、幂等重放与冲突，以及拒绝请求不调用持久化。 这些测试不连接 SandIAM、HTTP 或 PostgreSQL，不能证明真实撤销、并发或双侧审计已通过。 发布前仍需完成真实服务、数据库与调用方联调。

---

文档首页 · 排障