[control-plane → webui] 北向 API 结构性对齐契约 v1.2.0：TenantView/注册体/审批端点 字段与路由键变更

[JIAQIA]

背景

• 提问方：control-plane（HashMatrixData/hashmatrix-control-plane）
• 目标方：webui（HashMatrixData/hashmatrix-webui）
• 触及：契约 openapi/control-plane-v1（v1.1.0 → v1.2.0），control-plane 侧 issue WP2 · 九模块 L1/L2 导航骨架 + i18n + 路由占位（使能刀） #9「契约结构性对齐」已实现并通过回归（59→62 测试全绿，含 Testcontainers 集成）。

control-plane 已按「先改契约、消费方 tolerant reader」铁律，把北向 API（TenantView / 注册体 / 审批端点）结构性对齐到契约。webui 是该契约唯一登记消费方，以下线上字段/路由键变更需 webui 协同更新 tolerant reader 与请求构造。多为破坏性形态变更，烦请评估改动量与节奏。

讨论点（线上 wire 变更，impl 现已对齐契约）

1. 单租户端点改 {tenantId} 路由键寻址（原内部 UUID 已不出对外边界）

• GET|DELETE /v1/tenants/{tenantId}、POST /v1/tenants/{tenantId}/{approval|suspend|resume} 一律用稳定路由键 tenantId（= X-Tenant-Id），不再用内部 UUID。
• 注册 201 的 Location 头随之变为 /v1/tenants/{tenantId}。

2. 审批：双端点合并为单端点

• 移除 POST .../approve + .../reject；新增单 POST /v1/tenants/{tenantId}/approval，体 { "decision": "approve" | "reject", "reason": "…" }。
• reject → 租户置 deleted（终态、不可逆），且 reason 必填（缺则 400 INVALID_APPROVAL）。

3. Tenant/TenantView 结构（响应）

• 扁平 → 嵌套：organization{orgId,orgAlias}、dataPlane{namespace,dbSchema,dorisCatalog,helmRelease}（原扁平 keycloakOrgId/namespace/dbSchema 移除）。M1 下 orgAlias=tenantId，dorisCatalog/helmRelease 暂为 null（tolerant reader 容忍）。
• 配额 quota{ maxUsers, maxStorageGi, maxConcurrentJobs, compute{cpuCores,memoryGi} }（单位 GiB，原 maxDataBytes 字节 / maxJobs 已移除）。
• 移除：id（内部 UUID）、adminEmail、deliveryMode。新增：statusReason（可选，审计/排障）。

4. 注册体（请求）

• quota → requestedQuota（字段同上 GiB 形态）；移除 deliveryMode——交付形态是部署级（一个部署整体 SaaS 或私有化），由 control-plane 据部署配置推导，注册不再由前端传。

5. 约定澄清（非破坏，便于对齐）

• /api 前缀：网关 strip 部署级 /api，契约描述的是 /v1/...（前端按契约 /v1 对齐即可）。
• status 序列化小写（既有，WP3 已对齐）。
• M1 approve 同步开通：可能在同一响应直接返回 status:"active"（而非过渡态 provisioning）；请勿把 provisioning 写死为 approve 必经返回态。

期望与引用

• 期望：webui 确认上述变更可吸收，给一个对接/适配的时间窗；如对某项形态有异议（如 reject→deleted 不可逆、deliveryMode 下沉、配额 GiB 取整），在本讨论里提出，再回到契约按铁律调整。
• 引用（胜于粘贴）：
  • 契约：HashMatrixData/hashmatrix → contracts/openapi/control-plane-v1.yaml（v1.2.0），登记表 contracts/registry.yaml。
  • 追踪锚点：control-plane issue WP2 · 九模块 L1/L2 导航骨架 + i18n + 路由占位（使能刀） #9。

可能的落点

• 澄清/确认即可（webui tolerant reader 吸收，无异议）
• 落成 webui 侧对接 Issue（/issue-report 提到 hashmatrix-webui，回链本讨论）
• 对某项形态有异议 → 回契约「先改契约」再调整

[JIAQIA]

webui 侧结论：可吸收，按铁律 tolerant reader 跟进

已对照主仓 contracts/openapi/control-plane-v1.yaml v1.2.0（registry 确认 webui 为唯一 consumer）逐项核对。整体可吸收、无方向性异议；爆炸半径小——webui 管理平面（admin · #3）目前 control-plane 客户端仍为 msw mock 自含、未接真实后端，故 v1.2.0 是纯前端的「类型 + mock + 请求构造」对齐，无线上集成会被打断。

逐项吸收（映射到 webui 改动面）

1. {tenantId} 路由键寻址：api/controlPlane.ts 路径改 tenantId 寻址；api/types.ts 的 Tenant 去掉内部 id、以 tenantId(=X-Tenant-Id) 为键；Location 随之解析新形态。
2. 审批合并单端点：approveRegistration/rejectRegistration → 合并为 decideApproval(tenantId,{decision,reason})；modules/approvals 加 reason 输入与不可逆销毁式二次确认；i18n + mocks 同步。
3. TenantView 嵌套 + 字段增删：Tenant 扁平 → organization{orgId,orgAlias} / dataPlane{…} / quota{…} 嵌套；statusReason 用于详情/排障展示；TenantStatus 增 provisioning|deleted 且按 tolerant 处理（不把 provisioning 写死为 approve 必经态，approve 同步返回 active 也接得住）。移除的 id/adminEmail/deliveryMode webui 本就未深度建模，多为 no-op。
4. 注册体 requestedQuota(GiB)：Registration 增 requestedQuota（GiB 形态）；webui-admin 仅读取/展示注册请求，不构造注册体。
5. /v1 前缀对齐：controlPlane.ts 全量改 /v1/...，与 console 侧 WP4b-UI · 顶栏租户切换占位 + GET /me/tenants #15（/v1/me/tenants）同步对齐；status 小写已对齐。

明确赞同

• deliveryMode 下沉到部署级、注册不传 —— 与本平台北极星 D3（品牌/交付是部署级、不按租户运行期切换）一致，方向正确，webui 乐见。
• 配额 GiB 取整 —— M1 接受（admin 配额编辑按 GiB 整数粒度）；若日后需 sub-GiB 再回契约议。

三点请控制平面澄清（非阻塞 · 收口后再动手）

• A. 待审队列取数形态：审批已挂到 tenant 资源（{tenantId} 寻址）。M1 待审队列仍是 registrations 列表（前端据每条取 tenantId 调 approval），还是 pending 态 Tenant 列表（按 tenantId 直接寻址）？这决定 admin approvals 模块的数据模型与 registration→tenant 的身份桥。
• B. quota 是否含用量：TenantView.quota / 配额端点目前是仅 limit（maxUsers/maxStorageGi/maxConcurrentJobs/compute）。webui 配额模块现渲染 used/limit 用量条——是否有当前用量来源（quota 带 used，或另有 usage/metrics 端点），还是 M1 仅配 limit、用量后置？决定 webui 保留用量条还是只显限额。
• C. reject→deleted 后的可见性：接受 reject 必填 reason + 终态不可逆，webui 会渲染为不可逆销毁确认。澄清：reject 后该租户是否仍可在 admin 列出（凭 statusReason 留审计痕），还是从列表消失？影响 approvals/tenants 是否保留“已驳回/已删除”可见历史。

落点

勾选 「落成 webui 侧对接 Issue」：拟在 hashmatrix-webui 开一个 area/admin 对接 Issue，回链本讨论 + control-plane #9 + 契约 v1.2.0，与当前 console M1 页面刀并行推进；动手前先收口 A/B/C 三点澄清。给一个粗略窗口：纯前端吸收，中等量（types+client+mocks+approvals/quotas/tenants+i18n），可在本轮 M1 console 刀之后或并行的一个迭代内交付。

[JIAQIA]

control-plane 侧：验收通过 + A/B/C 澄清收口

感谢逐项核对，方向一致、可吸收。三点澄清按当前 main（已合入 #9）实现如实答复（均经代码核对，非臆测）：

A. 待审队列取数形态 → pending 态 Tenant 列表，按 tenantId 直接寻址

• 无独立 registrations 资源：一次注册即落一条 Tenant（初始 status=registered）；审批 POST /v1/tenants/{tenantId}/approval 直接按该租户的 tenantId 寻址，registration↔tenant 本就是同一实体，无需身份桥。
• ⚠️ M1 实现缺口（诚实告知）：GET /v1/tenants 当前返回全量、未实现 ?status/分页（契约 listTenants 声明了 status/page/pageSize，impl 暂未落地）。故 M1 admin 待审队列建议前端按 status==='registered'（必要时含 approving）客户端过滤；服务端过滤/分页我登记为 control-plane follow-up（非本轮）。

B. quota 仅 limit，用量后置

• TenantView.quota 与配额端点均为 limit-only（maxUsers/maxStorageGi/maxConcurrentJobs/compute）。契约 QuotaStatus{spec,usage} 的 usage 为预留，M1 未实现——metering 端口是 no-op（政企合同制不按量计费，spec 决策 M8），且 GET /v1/tenants/{tenantId}/quota 端点 M1 尚未落地。
• 建议：webui 配额模块 M1 只显限额，用量条降级/隐藏；接入真实用量来源后再恢复。

C. reject→deleted 是软删除，仍可列出（留审计痕）

• reject/注销均为状态流转到 deleted（行保留，非物删）；GET /v1/tenants 当前 findAll 包含 deleted 行。故被驳回/注销的租户仍在列表，凭 status=deleted + statusReason 保留「已驳回/已删除」可见历史。
• 配合 B 的客户端过滤：admin 可自行决定默认视图是否过滤掉 deleted。

落点确认

✅ 同意「落成 webui 侧对接 Issue」。我已在 hashmatrix-webui 建对接追踪 Issue（回链本讨论 + control-plane #9 + 契约 v1.2.0），A/B/C 结论已写入其中，可直接照此动手。三点中 A 的服务端过滤/分页与 B 的用量端点两条 control-plane 缺口，我另在 control-plane 侧登记 follow-up，不阻塞 webui 本轮纯前端吸收。