[control-plane → 主仓] control-plane-v1 补组织成员管理面（block 子项 #19）：端点形态 + 邀请语义请拍板

[uniquehole]

背景

• 提问方：control-plane（HashMatrixData/hashmatrix-control-plane）
• 目标方：主仓 hashmatrix（HashMatrixData/hashmatrix，contracts 单一事实源）
• 触及：契约 openapi/control-plane-v1（producer=control-plane）的组织成员管理面

缘由

M2 总纲 §2/§4 已列「control-plane 契约补成员管理面（org membership 邀请/移除，注明成员 SoT=Keycloak、control-plane 仅编排）」。本仓已按 split-task 拆出子任务 #17 → #18/#19/#20，其中 #19（成员 REST 端点 + 租户自管理鉴权）blocked-by 此契约面。当前 contracts/openapi/control-plane-v1.yaml 里 member 相关仅有既有 /v1/me/tenants（租户切换器 MembershipView），尚无成员管理端点。按「先改契约、再改实现」铁律，#19 待此面定形再动工。

讨论点（请主仓拍板，2 项不可返工）

1. 端点形态：成员管理走 /v1/tenants/{tenantId}/members（沿用契约现有单租户 {tenantId} 寻址范式）还是 /me-风格的租户自管理根？D9 定义为「带 X-Tenant-Id 的租户自管理」。本仓倾向前者（与现有单租户端点一致）。
2. 「邀请」语义：M2 是否只做「把已存在的 Keycloak user 按 email/username 加入当前 org」，把完整邮件 invite 流后置？本仓倾向先做前者。

一并请契约固化（加法）

• 方法：GET / POST / DELETE .../members（list / 加入 / 移除）
• DTO：成员视图不含任何凭据字段；与既有 MembershipView（切换器）命名区分（本仓拟用 OrgMemberView）
• 门控语义：租户管理员（tenant-admin）自管理，非 SUPERADMIN 跨租户运营
• 注明：成员 SoT=Keycloak Org，control-plane 仅编排，PG 不另存成员凭据（守 D1/R3）

期望与引用（引用胜于粘贴）

• 期望：主仓在 control-plane-v1 内加法补上述成员面 + 更新 registry.yaml，给定端点形态/DTO 结论。
• 引用：契约 contracts/openapi/control-plane-v1.yaml；总纲 docs/milestones/M2-页面真实操作-可写纵切链.md §2(D9)/§4；本仓 HashMatrixData/hashmatrix-control-plane#17（拆解）与 #19（被 block 子项）。

可能的落点

• 澄清端点形态/邀请语义即可，本仓据此对齐
• 落成主仓 Issue：在 control-plane-v1 落地成员契约面（结论清晰后 convert / /issue-report）
• 其它

[uniquehole]

✅ 主仓拍板：契约已立（#57），两项不可返工决策定案

成员面契约 task 已开立并通知 control-plane 起草：➡️ #57（producer=control-plane;M2 milestone、#50 sub-issue;gateway#18 已 Blocked by #57）。背景见已闭环讨论 #52。

1. 端点形态 → header 寻址 /v1/org/members（不采纳 path {tenantId}）
你倾向 /v1/tenants/{tenantId}/members,但主仓按已锁 D2（X-Tenant-Id 唯一） 定为 header 寻址:活动租户只来自 X-Tenant-Id,path 再带 {tenantId} 会造双源、违反 D2。现有 /v1/tenants/{tenantId}/* 是 SUPERADMIN 跨租户运营面,与"租户自管理"不同平面,不可复用其寻址。
→ GET / POST /v1/org/members、DELETE /v1/org/members/{userId},require_tenant=true。

2. 邀请语义 → 同意你的倾向:M2 只做"按 email/username 把已存在 KC user 加入当前 org",完整邮件 invite 流后置。

一并固化:DTO=OrgMemberView（与 MembershipView 区分、无凭据字段）;门控=tenant-admin 自管理;🔴 成员 SoT=Keycloak、control-plane 仅编排、PG 不另存成员凭据（D1/R3）。

已折入 #57,后续在该 issue 跟踪,本讨论无需继续。