变更记录

联系人邮箱只能设置一次

• PATCH /v1/club/contacts/{id} 新增可选字段 email，只能为还没有邮箱的联系人设置一次，设置后不能修改或清空。此前该接口完全不接受 email。
• 传入联系人当前已有的同一地址视为不修改，先读后写的客户端可以原样回传。
• 联系人已有邮箱而传入不同地址时返回 400 invalid_request，details: [{ field: "email", code: "already set" }]；地址已被平台上其他人使用时同样返回 400，code: "already in use"；显式传 null 视为请求格式错误。
• POST /v1/club/contacts 遇到重复邮箱时改为返回 400 invalid_request 并指出字段，不再返回 500 internal_error：邮箱已在本俱乐部名册中为 already in this club；家庭草稿成员的邮箱字段为 householdMembers[i].draft.email，同一次调用里重复使用同一地址时为 duplicate in request。
• PATCH /v1/federation/people/{contactId} 不变：联盟登记时邮箱必填，之后不可更正。

API 参考请求示例

• 示例请求改为如实展示签名请求头：X-Sx-Key-Id 为唯一的认证方案，X-Sx-Timestamp、X-Sx-Nonce、X-Sx-Signature 为每个操作的必填请求头，并附说明与示例值。此前四个请求头都显示为同一个占位密钥。
• OpenAPI 增加 servers（partner-api.sportsx.ai 与 partner-dev-api.sportsx.fun）；写操作的 Idempotency-Key 与联系人创建/更新的字段附示例值。
• 仅文档与契约检查变化，接口行为不变。

俱乐部 OWNER 专属 scope 授予

• 将 P0 对 club.compliance.read_files、club.safety.read_sensitive、club.coaches.read、club.coaches.write、club.federations.read 的“任何发放者均不支持”决定，改为仅允许精确当前俱乐部的 OWNER 授予。
• 权限 wildcard 与角色证据保持分离：ADMIN、自定义 wildcard 持有者和其他俱乐部的 OWNER 均不能授予这些 scope。
• scope 目录、凭据创建和 scope 更新统一使用服务端授予上限。既有 key 仍只有明确 scope；保留严格缩小能力，轮换不会扩大 scope。

P5 合同发布

• 发布仅签名认证，删除旧 Bearer 和运行时 mock demo 指南。
• 冻结当前清单：96 个显式 controller 操作，包括公开 GET /health，以及 85 个路径模板上的 95 个签名 /v1 操作。
• 增加中英文路由集合一致性、source-ledger 漂移、缺翻译和缺 spec 失败，以及双语文档构建 gate。
• 记录 workspace Redis 限流、失败关闭幂等、五种签署 webhook、权威对账和当前发放/worker 限制。

P6 独立 Partner worker

• 新增显式 PARTNER_ROLE=api|worker 启动；默认 api 保持向后兼容，未知 role 启动即失败。
• 将 webhook 队列消费与恢复从 Academy 所有模式移入仅健康检查的 worker；Partner API 与 Academy 保留共享 producer。
• 同一 bundle 新增相互独立的 API/worker Kubernetes Deployment；只有 API 拥有 Service/公开路由。
• 新增隔离 Postgres/Redis 运行时检查，覆盖 role 路由、queue registry identity、consumer ownership 与关闭清理。