contracts: 补 control-plane 成员管理面（org membership 邀请/移除 · 解 gateway#18 阻塞）

[uniquehole]

源起：讨论 #52。WP1 / 总纲 §64/§82 拆分项之一。父：#50。

背景

M2 组织管理·成员链（链③）需要 control-plane 的成员管理面。现 contracts/openapi/control-plane-v1.yaml 仅有只读 GET /v1/me/tenants（当前用户 membership 视图），无成员邀请/移除写面。gateway #18 被阻塞。

要达成

• 扩 contracts/openapi/control-plane-v1.yaml 成员管理面（加法 MINOR）
• 明确 成员 SoT 在 Keycloak Org、control-plane 仅经 KC Admin API 编排（严禁 control-plane PG 另建成员凭据实体 — D1/R3 不变量）
• registry 版本递增（producer=hashmatrix-control-plane）

路径形状 / 前缀（最终以契约为准，回应讨论 #52 第 4 点）

• 成员面 = 租户自管理（apps/console 按角色门控，带 X-Tenant-Id，require_tenant=true），非 admin 跨租户运营。
• 对外契约路径走 control-plane 既定 /v1/... 约定（应用内 /api/v1/...，网关 strip /api）；建议 GET/POST /v1/orgs/members、DELETE /v1/orgs/members/{userId}。
• 前缀不混淆澄清：管理面无租户前缀权威为 /admin/*（ICD §3.6 require_tenant=false，gateway#6），非 /api/v1/*。gateway M1 贯通主线 · 端到端集成（主仓 owner） #15 简报「M1 fix(gateway): control-plane 路由 require_tenant=false（共享控制平面跨租户管理） #45 设 /api/v1/* require_tenant=false」有误，应更正为 /admin/*。成员面是 require_tenant=true 的 /v1/* 租户隔离路由，与 /admin/* 天然不冲突。

责任 / 对接

• 起草：control-plane 工程师（producer）→ PR 到主仓 contracts/
• 评审：主仓 contracts 治理 + webui + gateway
• 解阻塞：hashmatrix-gateway#18（Blocked by 本 issue）

验收

oasdiff 加法兼容；registry 版本对齐；成员写真打 Keycloak（control-plane PG 不存成员凭据）。

[uniquehole]

主仓拍板：成员面端点形态 / 邀请语义 / DTO（源 讨论 #54）

两项不可返工决策定如下（control-plane #19 据此实现，覆盖 #57 正文中 /v1/orgs/members 的临时措辞）：

1. 端点形态——header 寻址，非 path {tenantId}：成员面是租户自管理,活动租户由 X-Tenant-Id 给定（require_tenant=true）。路径用 /v1/org/members（"当前 org"），不采用 /v1/tenants/{tenantId}/members。
   • 理由（守已锁 D2）：path 再放 {tenantId} 会与 X-Tenant-Id 构成"双租户源",违反「X-Tenant-Id 唯一」不变量、并需额外校验 path==header。现有 /v1/tenants/{tenantId}/* 语义是 SUPERADMIN 跨租户运营（admin 面）,与租户自管理不同平面,不可混用。
   • 端点：GET /v1/org/members、POST /v1/org/members、DELETE /v1/org/members/{userId}。
2. 邀请语义——M2 只做"加已存在 KC user"：按 email/username 把已存在的 Keycloak user 加入当前 org;完整邮件 invite 流后置（接受功能不完整）。
3. DTO：OrgMemberView（与切换器 MembershipView 命名区分,不含任何凭据字段）。
4. 门控：tenant-admin 自管理,非 SUPERADMIN 跨租户。
5. 🔴 D1/R3：成员 SoT=Keycloak Org,control-plane 仅经 KC Admin API 编排,PG 不另存成员凭据实体。