Standalone consumer

受控独立非 AI 业务 Consumer

文件来源、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/webman-business-app/standalone" || exit 1

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

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

这是一个轻量 PHP consumer，用真实 PostgreSQL 业务对象调用 SandIAM PHP SDK 的 authorizeEntity。它不是 SandAdmin 插件、不会创建数据库或表，也没有默认账号、token 或可直接运行的业务数据。

配置与启动

1. 在已创建的非生产 PostgreSQL 数据库中，经环境负责人授权后执行 schema.pgsql；它只创建 standalone_* consumer 表，绝不创建 sand_iam_* 或 sa_* 表。
2. 复制 .env.example 到受控环境变量注入方式，填写现有 PostgreSQL DSN、数据库账号、SandIAM 地址及已登记的 组织/应用代码及两个已登记的 API code。DSN 不是 pgsql:，缺少配置，API code 重复，或任一 consumer 表不存在时， 应用会拒绝请求；不会自动建库、建表或补数据。验收环境可为 API code 使用受控验收前缀，业务路由不因此变化。
3. 在本目录执行 composer install。该命令会生成本地 vendor/；它是可再生依赖目录，已被 .gitignore 排除，不能纳入源码或发布包。composer.json 使用本仓 PHP SDK 的本地 path repository；这不表示 Composer Registry 已发布该 SDK。
4. 仅在隔离环境由操作者选择 HTTP 启动方式，例如 php -S 127.0.0.1:8088 -t public public/router.php。 示例不包含服务启动或数据库连接验收；发布前须在隔离真实环境完成该验收。

路由与受控验证

• GET /health：检查现有数据库连接和两张 consumer 表。
• GET /items/{id}：要求 Bearer token 与 request ID，从 PostgreSQL 读取业务对象后按真实组织/所有者范围授权；不接受客户端提供的组织、所有者或范围。
• POST /items/{id}/close：要求 Authorization: Bearer <应用用户 token> 与 8–96 位 X-Request-Id。 请求体只能为空对象，若含 organization_id、owner_identity_id、scope 或 attributes 会被拒绝。

关闭操作在一个事务中对真实对象 SELECT … FOR UPDATE，用 SDK authorizeEntity 根据该对象的数据库组织/所有者字段授权； 实体属性与路由属性分字段提交，SandIAM 用同一 request ID 记录粗粒度 authorize.* 和实体级 scope.* 审计，SDK 还会本地复核返回 scope。 再用 state='open' AND version=:version 完成 open → closed。deny、网络故障、协议无效、并发变化和审计写入失败均回滚并拒绝； 业务审计只存 SHA-256 截断引用，不存 access token、组织/所有者原值或秘密。read allow/deny、close deny、认证/撤销拒绝和 授权异常均由独立 audit connection 写入，不会随 close 事务回滚；close allow 审计仍在业务事务中。

接入登记契约

在调用本 consumer 前，应用管理员须通过既有 SandIAM 管理流程登记下列稳定契约；本目录不调用管理 API：

API code	resource_code	action	operation	api_version	route	数据范围
standalone_work_item.read	standalone_work_item	work_item.read	read	v1	GET /items/{id}	仅服务端加载的 organization_id、owner_identity_id
standalone_work_item.close	standalone_work_item	work_item.close	update	v1	POST /items/{id}/close	同上；状态和版本仅来自 PostgreSQL

登记时分别绑定 API code、resource_code、策略 action、operation、api_version、HTTP 方法/路由和 scope resolver；这些字段按上表契约对应，不要求使用同一个字符串。请求 body 不能提供或覆盖范围字段。

隔离验收时，应分别记录 allow（关闭一次）、deny（403 且状态仍为 open）、撤销后再试（拒绝且无副作用）和审计 request ID；结束后按隔离环境授权流程删除测试数据。真实 HTTP、SandIAM、数据库、撤销和清理路径须由部署方在隔离真实环境验收； 离线检查不构成真实环境验收。

离线测试

php tests/offline_test.php 使用内存 fake repository/authorizer 验证 deny、授权网络/协议失败和 body 范围篡改均不产生 关闭副作用。它不启动服务、不访问 PostgreSQL、不调用 SandIAM HTTP，不能计入真实验收。

---

文档首页 · 排障