[gateway → 主项目] M2 三套路径形状契约（datasources/metadata-write/members）何时落地，gateway 路由被阻塞

[uniquehole]

背景

• 提问方：gateway（HashMatrixData/hashmatrix-gateway）
• 目标方：主项目（HashMatrixData/hashmatrix，contracts/ 单一事实源）
• 触及：M2 三条可写纵切链的路径形状契约（datasources / metadata-write / members）

gateway 已按主仓 M2 总纲（docs/milestones/M2-页面真实操作-可写纵切链.md §"① 契约先行"）将 #15 自拆为 4 个 sub-issue（#16 数据源 / #17 元数据含写 / #18 成员 / #19 端到端集成）。三条路由是契约路径形状的下游消费方，但核对 contracts/ 后发现三套契约尚不完整，gateway 按「先改契约再改实现」铁律暂不能动 apisix.yaml 主体。特此前置讨论确认节奏与归属。

疑问 / 讨论点

1. datasources 契约缺失：contracts/registry.yaml 与 contracts/openapi/ 下未见 data-foundation-datasources（producer 应为 data-foundation）。M2 总纲 §62/§82 要求新增此 OpenAPI+ICD——当前路径形状（如 /api/datasources、/{id}/tables、/{id}/preview）gateway 无契约可依。何时落、由谁 PR？
2. governance 写入面未扩展：contracts/openapi/governance-metadata-v1.yaml 当前仅有 GET /api/meta/search 与 POST /api/open/query，无 POST /api/meta/assets（资产登记/编辑写入面）。总纲 §82 要求"扩 governance-metadata 写入面"——写端点路径形状待定。
3. control-plane 成员管理面缺失：contracts/openapi/control-plane-v1.yaml 仅有只读 GET /v1/me/tenants，无成员邀请/移除面（org membership 写）。总纲 §64/§82 要求"补 control-plane 成员管理面，明确成员 SoT 在 Keycloak、control-plane 仅编排"——成员端点路径/前缀待定。
4. 次要·fix(gateway): control-plane 路由 require_tenant=false（共享控制平面跨租户管理） #45 引用校正：gateway M1 贯通主线 · 端到端集成（主仓 owner） #15 简报称"M1 fix(gateway): control-plane 路由 require_tenant=false（共享控制平面跨租户管理） #45 已立 control-plane /api/v1/* 设 require_tenant=false"，但 gateway 本仓 apisix/apisix.yaml 现状是 /admin/* 路由 require_tenant=false，无 /api/v1/* 路由。请确认 admin 无租户面对外前缀，以便 contracts: control-plane-v1 新增 GET /v1/me/tenants（当前用户 membership 数组） #18 成员面（租户自管理·带租户头）与之前缀不混淆。

期望与引用

• 期望：①②③ 三套契约的落地计划与责任方（哪个 PR、预计顺序），以便 gateway [ICD] tenant-context-headers §3.4 修订：多 org→403 ⇒ 单活动租户 + 预留多 membership #16/[deploy] gateway 子 chart 落地：启用 APISIX 官方 chart 依赖 + config/插件 ConfigMap 注入 + 装进单 ns #17/contracts: control-plane-v1 新增 GET /v1/me/tenants（当前用户 membership 数组） #18 解阻塞；④ 给出 admin 无租户面的权威前缀。
• 引用（胜于粘贴）：
  • 总纲：docs/milestones/M2-页面真实操作-可写纵切链.md §62/§64/§82
  • 现有契约：contracts/registry.yaml、contracts/openapi/governance-metadata-v1.yaml、contracts/openapi/control-plane-v1.yaml
  • gateway 子任务：hashmatrix-gateway#16 / #17 / #18 / #19（父 #15）

可能的落点

• 澄清即可（契约其实已在某 PR/分支，gateway 取最新即可）
• 落成 Issue（若契约确未落，建议在主仓 contracts/ 各开一条 task 追踪，gateway 子任务 Blocked by 之）
• 其它：按主仓回复决定

[uniquehole]

主仓裁决：讨论成立，三套契约确缺，已落 Issue

核对 contracts/ 后确认 ①②③ 三点均成立——契约 SoT 在主仓 contracts/，当前确无对应路径形状，gateway 按「先改契约再改实现」铁律暂停 apisix.yaml 主体改动是正确的。归属与节奏如下：

①②③ 落地计划与责任方（各开一条 task，gateway 子任务 Blocked by 之）

链	契约 task	producer 起草方	解阻塞
① datasources	#55 新增 openapi/data-foundation-datasources + ICD	data-foundation	gateway#16
② metadata-write	#56 扩 governance-metadata 写入面（POST /api/meta/assets）	governance	gateway#17
③ members	#57 补 control-plane 成员管理面（org membership 写）	control-plane	gateway#18

均挂 M2 milestone、area/contracts+priority/high，并已作为 #50 的 sub-issue。
顺序：三者无相互依赖，可并行起草；建议 ①（锚点链）优先。各 producer 子仓工程师 PR 到主仓 contracts/，主仓 contracts 治理 + webui（SDK）+ gateway（路由）联评。请 gateway 在 #16/#17/#18 分别标 Blocked by #55/#56/#57。

④ admin 无租户面权威前缀 —— gateway#15 简报有误，请更正

• 管理/无租户面权威前缀为 /admin/*（ICD tenant-context-headers §3.6，require_tenant=false，gateway#6 实装），不是 /api/v1/*。M1 贯通主线 · 端到端集成（主仓 owner） #15 简报「M1 fix(gateway): control-plane 路由 require_tenant=false（共享控制平面跨租户管理） #45 设 control-plane /api/v1/* require_tenant=false」两处不准：(a) 无租户前缀是 /admin/*；(b) control-plane 的 /v1/* 对外面是 require_tenant=true 的租户隔离路由（应用内 /api/v1/*，网关 proxy-rewrite strip /api，见 control-plane-v1 契约 §路径前缀约定），并非无租户。
• 因此 contracts: control-plane-v1 新增 GET /v1/me/tenants（当前用户 membership 数组） #18 成员面是租户自管理（带 X-Tenant-Id、require_tenant=true）的 /v1/orgs/members*，与 /admin/* 天然不在同一前缀空间，不会混淆。细节落在 contracts: 补 control-plane 成员管理面（org membership 邀请/移除 · 解 gateway#18 阻塞） #57 契约里。

红线 / 不可返工提醒（随 #57 实现守好）

成员 SoT 在 Keycloak Org，control-plane 仅经 KC Admin API 编排——严禁 control-plane PG 另建成员凭据实体（破坏 D1 单 User + 多 Org Membership 不变量，见总纲 R3）。

落点：勾选「落成 Issue」。三条契约 ready 前 gateway 路由主体保持暂停，符合铁律。

[uniquehole]

✅ 全部对接完成,关闭讨论

讨论结论已落地为可追踪闭环:

1. 三套契约 task（主仓 contracts/ · M2 milestone · #50 sub-issues）

• contracts: 新增 openapi/data-foundation-datasources + ICD（M2 数据源接入链 · 解 gateway#16 阻塞） #55 datasources OpenAPI+ICD（producer=data-foundation）
• contracts: 扩 governance-metadata 写入面（资产登记/编辑 · 解 gateway#17 阻塞） #56 governance-metadata 写入面（producer=governance）
• contracts: 补 control-plane 成员管理面（org membership 邀请/移除 · 解 gateway#18 阻塞） #57 control-plane 成员管理面（producer=control-plane）

2. producer 子仓工程师已通知起草（评论落在各仓 M2 自拆解简报）

• data-foundation#9 / governance#26 / control-plane#17 —— 起草后 PR 到主仓 contracts/

3. gateway 路由已标原生 Blocked by（依赖区可见,契约关闭即自动解除）

• gateway#16 ← contracts: 新增 openapi/data-foundation-datasources + ICD（M2 数据源接入链 · 解 gateway#16 阻塞） #55 · gateway#17 ← contracts: 扩 governance-metadata 写入面（资产登记/编辑 · 解 gateway#17 阻塞） #56 · gateway#18 ← contracts: 补 control-plane 成员管理面（org membership 邀请/移除 · 解 gateway#18 阻塞） #57

4. 主仓 tracking #50 WP1 进度已更新（起草中,data-foundation 锚点链优先）。

④ 前缀更正备忘:无租户管理面权威前缀为 /admin/*（ICD §3.6,require_tenant=false）,非 /api/v1/*;成员面是 require_tenant=true 的 /v1/* 租户隔离路由,两者不冲突。请同步修订 gateway#15 简报措辞。

后续进展在 #55/#56/#57 与 #50 跟踪,无需在本讨论继续。感谢 @uniquehole 前置澄清,避免了 gateway 在契约未定时返工。