用途
podium-multi-location-router 用于在多个物理门店之间路由 Podium API 调用,并在生产环境中运行这层路由。它面向的场景包括:多个门店共用一个 OAuth 应用、代理机构一次性批量接入多个新门店、以及需要回答“某个联系写入究竟进入了哪个门店”的合规审计场景。
主要能力
- 按门店隔离凭据:路由内部为每个 location_uid 持有独立的 PodiumAuth 实例,而不是按 org 共享,从而在审计上把每次调用归属到具体门店和具体凭据。
- 调用前门店校验:写操作前通过 GET /v4/locations 确认 location_uid 在当前凭据可见范围内,默认缓存 1 小时,超出范围时抛出 LocationNotInScopeError。
- 结构化审计日志:每次调用写入一行固定字段的 JSON,字段为 ts、location_uid、org_slug、endpoint、method、status、request_id、latency_ms,不记录 token、请求体或 PII。
- 幂等批量开通:逐个门店处理,先原子写入凭据记录,再实例化 auth 并校验;失败时回滚半成品记录,可安全重跑,已开通的门店会被跳过。
- 按门店速率预算:每个门店一个令牌桶,一个门店的突发流量不会耗尽其它门店的配额。
- 未知门店拒绝:查询未注册的 location_uid 时立即报错,不存在默认凭据或猜测式降级路由。
使用方式
需要 Python 3.10+,并已安装 podium-auth(消费其 PodiumAuth、PodiumOrgRouter、PodiumAuthError)和 podium-rate-limit-survival(消费其令牌桶预算原语)。此外需要具备 locations.read 权限的 Podium OAuth 应用、可写的审计日志目录(默认 ./audit-log/podium-router.jsonl),以及持久化的门店凭据映射(文件、AWS Secrets Manager、GCP Secret Manager 或 SOPS 加密 YAML)。
包含的命令示例:
- 写前校验:python3 scripts/verify_location.py --location-uid {your-location-uid} --credentials-file ./config/locations.json,退出码 0 表示在范围内,1 表示不在范围内,2 表示配置或网络错误。
- 幂等开通:python3 scripts/onboard_location.py 并传入 location-uid、org-slug、客户端凭据环境变量、refresh token 文件和凭据文件,重跑安全。
- 审计查询:python3 scripts/audit_log_query.py --audit-log ./audit-log/podium-router.jsonl --location-uid {your-location-uid} --since 2026-05-01 --until 2026-05-12 --output json。
- 编程调用:router = LocationRouter.from_credentials_file(...),client = router.get_client(location_uid=...),再通过 client.call 发起请求并 raise_for_status。
适用场景
适合多门店共享一个 Podium OAuth 应用、需要按门店审计数据去向、需要批量接入新门店且要求可恢复、需要隔离各门店速率配额的集成方。
限制
需要 Python 3.10+,并依赖 podium-auth 与 podium-rate-limit-survival;需要 locations.read 权限。凭据映射的存储方式、审计日志轮转、每门店速率桶的具体配置均需由使用方自行提供与调优。资料中未提供具体收费、价格、性能指标或平台兼容范围。