M2 自拆解简报 · 页面真实操作（可写纵切链）

[uniquehole]

M2 自拆解简报 · hashmatrix（主仓 · 协调/契约/部署/验收）

粗粒度里程碑简报。只读本简报 + 本仓代码即可自拆子任务并自验收，无需问人。
上位总纲：本仓 docs/milestones/M2-页面真实操作-可写纵切链.md

0. 一句话目标

作为治理方，为 M2 三条可写链提供契约先行、demo MySQL 部署、D7 密钥注入与端到端集成验收，并把 D7–D9 决策落档。

1. 起点 · 代码现状

• docs/milestones/M2-*.md —— 总纲已落 [真实]
• contracts/ —— 有 icd/governance-metadata 等；无 datasources / metadata-write / members 契约 [缺失]
• deploy/ —— M1 单 ns demo（infra-dev: Keycloak+PG）已真实；无 demo MySQL [缺失]
• docs/architecture/05-多租户与控制平面.md —— 待补 D7–D9

2. 范围边界

• ✅ M2 做：三套契约 + registry、demo MySQL 子依赖 + 种子、D7 主密钥 Secret 注入、三条链集成自检、决策落档
• ⛔ 不做：ESO/Vault 真集成（仅占位）、生产级 MySQL HA

3. 工作项 & 拆分指引

WP1 · 契约先行（解三条链阻塞）

• 要达成：contracts/openapi/data-foundation-datasources（producer=data-foundation）+ ICD；扩 governance-metadata 写入面；补 control-plane 成员管理面；更新 registry.yaml。
• 入手点：contracts/ 现有 openapi/icd 结构 + CONVENTIONS.md；先改契约再让子仓实现（铁律）。
• 验收：registry 索引到三套；webui SDK 可据此生成；oasdiff 加法兼容。

进度（经讨论 #52/#53/#54/#58 触发，主仓已拍板设计要点）：三套契约缺口已核实，拆为可追踪子 task（本 issue sub-issues）、各 producer 已通知起草、关键不可返工设计点已定案，gateway#16/#17/#18 已 Blocked by：

• contracts: 新增 openapi/data-foundation-datasources + ICD（M2 数据源接入链 · 解 gateway#16 阻塞） #55 datasources OpenAPI+ICD（producer=data-foundation）→ 解 gateway#16 · [通知 data-foundation#9] · 守 D7/D8
• contracts: 扩 governance-metadata 写入面（资产登记/编辑 · 解 gateway#17 阻塞） #56 governance-metadata 写入面（producer=governance）→ 解 gateway#17 · [通知 governance#26] · 拍板([governance → hashmatrix] governance-metadata 写入面契约何时落地（阻塞 #29 资产登记写端点） #53)：读写 DTO 分离 AssetUpsertRequest+JSONB、id 服务端生成、PUT/{id} 幂等、require_tenant=true
• contracts: 补 control-plane 成员管理面（org membership 邀请/移除 · 解 gateway#18 阻塞） #57 control-plane 成员管理面（producer=control-plane）→ 解 gateway#18 · [通知 control-plane#17] · 拍板([control-plane → 主仓] control-plane-v1 补组织成员管理面（block 子项 #19）：端点形态 + 邀请语义请拍板 #54)：header 寻址 /v1/org/members（守 D2）、加已存在 KC user、DTO OrgMemberView、tenant-admin 门控

状态：设计定案 · 起草中（producer 子仓 PR 契约到主仓 contracts/）；三者无相互依赖、可并行，data-foundation（锚点链）优先。三套合入 registry 前 gateway 路由主体按铁律暂停。
关联：业务表隔离档位歧义已裁决并落档——metadata_asset 走行级 tenant_id 先行级（#58，arch 05「D9 落地档位说明」已合入 PR #59）；动态 schema 建表归 control-plane provisioning（升档后置）。详见 WP4。

WP2 · demo MySQL 部署 + 种子

• 要达成：demo namespace 增 dev 级 MySQL（端口 3306）+ 种子一张虚构脱敏表（如 acme.orders_demo），供 data-foundation 测试连接/预览。
• 入手点：deploy/ infra-dev 加子依赖（dev 级、非 HA）；values-localdev 接线。
• 验收：单 ns helm install 后 MySQL Pod 绿、种子表可被连接预览。

WP3 · D7 主密钥注入

• 要达成：data-foundation AES 主密钥经 K8s Secret 注入（DS_SECRET_KEY），values 占位不入库明文。
• 入手点：deploy/ data-foundation chart env + Secret 模板；红线守卫。
• 验收：密钥来自集群 Secret、git 无明文。

WP4 · 集成验收 + 决策落档

• 要达成：三条链各一个集成自检（脚本/e2e，并入 M1 冒烟不回归）；复核并按实现补全 docs/architecture/05 的 D7–D9（决策已落档，随实装回填细节）。
• 验收：两租户隔离自检通过；M1 既有链路不回归。

4. 关键参考

• 契约规范：contracts/CONVENTIONS.md、docs/architecture/06-契约治理.md
• M1 部署范式：deploy/ infra-dev + values-localdev、tools/local-infra/
• 本地起法：tools/local-infra make up → helm install（见 local-deploy skill）

5. 依赖 & 约束

• 主仓 owns charts（D5）；契约 SoT 在本仓 contracts/
• 被全部子仓依赖（契约/部署/验收）；依赖各子仓交付 image
• 受决策约束：D5（charts 归属）、D7（密钥不入库）、红线

6. 完成判据

• 三套契约入 registry、子仓可消费（拆解：contracts: 新增 openapi/data-foundation-datasources + ICD（M2 数据源接入链 · 解 gateway#16 阻塞） #55 / contracts: 扩 governance-metadata 写入面（资产登记/编辑 · 解 gateway#17 阻塞） #56 / contracts: 补 control-plane 成员管理面（org membership 邀请/移除 · 解 gateway#18 阻塞） #57，起草中 — 见 WP1 进度）
• 单 ns helm install 起 demo MySQL + 种子、data-foundation 可连
• D7 主密钥经 Secret 注入、git 无明文
• 三条链集成自检 + 两租户隔离通过、M1 不回归
• 红线自检：种子/示例全虚构脱敏

---

🧩 deploy / 契约 子任务拆分（本简报 WP1+WP2+WP3 落地）

精确到路径的子 issue。锚点链（数据源接入）的契约+部署优先；目录链契约并列。

契约（WP1）

• contracts: 新增 openapi/data-foundation-datasources + ICD（M2 数据源接入链 · 解 gateway#16 阻塞） #55 · data-foundation-datasources OpenAPI + ICD + registry（锚点链 · 解 gateway#16）— 草案 PR contracts: data-foundation-datasources OpenAPI + ICD（M2 数据源接入链 · #55） #66 待评审（据子仓 PR M1 自拆解简报 · 入口级交付 #14–[deploy] gateway 子 chart 落地：启用 APISIX 官方 chart 依赖 + config/插件 ConfigMap 注入 + 装进单 ns #17 实现回填，Spectral 通过）
• governance-metadata 写入面 — 已完成（governance-metadata-v1 1.1.0 + ICD 0.2.0，contracts: 扩 governance-metadata 写入面（资产登记/编辑 · 解 gateway#17 阻塞） #56 / PR feat(contracts): governance-metadata v1.1.0 — 资产登记/编辑写入面 /api/meta/assets (#56) #61）；我先前误建的 contracts: 扩 governance-metadata 写入面（资产登记/编辑 · M2 目录链②） #64 已关闭去重
• control-plane 成员管理面 — 已完成（control-plane-v1 1.3.0 含 /v1/org/members，contracts: 补 control-plane 成员管理面（org membership 邀请/移除 · 解 gateway#18 阻塞） #57）

部署（WP2/WP3）

• deploy(infra-dev): demo MySQL 子依赖 + 种子表（M2 数据源接入链·被连接样例源） #62 · infra-dev demo MySQL 子依赖 + 种子表（被连接样例源，3306 / acme.orders_demo）
• deploy(data-foundation): datasource env 接线 + D7 主密钥 Secret 注入 #63 · data-foundation chart：datasource env 接线 + D7 主密钥 Secret 注入（含平台 PG 增建 df 库）

推进顺序：#55 契约先行 → #62/#63 部署（解 demo MySQL + D7）→ 锚点链单 ns 端到端可演示；#56 契约已就绪，目录链 governance 实现据此并行。

[uniquehole]

📥 webui 消费方追踪 · M2 三链契约缺口（WP1「契约先行」）

来自 hashmatrix-webui 消费侧。webui 的 M2 已按总纲拆成 6 个 sub-issue（父 hashmatrix-webui#24），其中三条写链的「接真实 API」判据被本仓 #50-WP1 契约先行阻塞。下面把缺口与消费方对契约的精确诉求列清，便于按铁律「先改契约、再让子仓实现」推进。webui 侧已采用 msw 顶契约形状先行，契约发布后切真实，不阻塞前端骨架。

阻塞映射（webui sub-issue → 所需契约）

webui sub-issue	依赖契约	当前状态（已核对 contracts/）
hashmatrix-webui#26 / #29（数据集成·数据源）	openapi/data-foundation-datasources	❌ 完全缺失（openapi/ 无文件、registry.yaml 无条目）
hashmatrix-webui#27（数据目录·资产登记）	governance-metadata 写入面	⚠️ 仅 GET /api/meta/search·detail·lineage，无 POST /api/meta/assets
hashmatrix-webui#28（组织管理·成员）	control-plane 成员管理面	⚠️ 有租户生命周期 + GET /v1/me/tenants，无 org membership 邀请/列表/移除

消费方诉求（SDK 由契约生成，字段形状需稳定）

1. data-foundation-datasources（锚点，最急 · 阻 #26/#29）

• POST /api/datasources/test — 入 {type,host,port,db,username,password} → 出 {ok:boolean, error?:string}
• POST /api/datasources — 同上入参 → 出 {id,...}，响应绝不回显 password（D7）
• GET /api/datasources — 本租户列表（X-Tenant-Id 过滤，D9），项含 name/type/host/db/status
• GET /api/datasources/{id}/tables — 库表树
• POST /api/datasources/{id}/preview — 入 {table,limit} → 出前 N 行
• D8：领域模型 type 驱动方言，不写死 MySQL（webui 表单/分支按 type 渲染）。
• 并请同步 registry.yaml 索引此契约，否则 SDK 生成取不到。

2. governance-metadata 写入面（阻 #27）

• 新增 POST /api/meta/assets（登记/编辑），本租户写（D9）；返回体对齐现有 AssetSummary。
• 属性建议 JSONB 可扩展（总纲 R2，避免 feat(contracts): 控制平面/租户开通 OpenAPI + governance 供数契约细化 (#3) #12 元模型引擎落地返工）——webui 表单不假设固定属性集。
• GET /api/meta/search 的租户过滤语义请在契约写明（webui 据此断言两租户隔离）。

3. control-plane 成员管理面（阻 #28）

• 成员列表 / 邀请(POST) / 移除(DELETE)，租户自管理：租户管理员角色门控、带 X-Tenant-Id，非 superadmin 跨租户（D9）。
• 列表项含 name/email/roles/groups/status。
• 成员 SoT 在 Keycloak Org，control-plane 仅编排读写，不另建成员凭据实体（守 D1/R3）。

请主仓明确

1. 三套契约的发布顺序与时点（webui 关键路径：privacy 子 chart 接线 ghcr + 端口/actuator 对齐 + 单 ns PSI mock helm 演示 #25 范式 → starter-security: 默认 permit-paths 未覆盖 /actuator/health/** —— K8s readiness/liveness 探针被 401 #26 锚点 → feat: M1 privacy 部署接线（chart 镜像/端口/探针 + gateway 路由 + 编排层契约） #29，锚点 datasources 最急）；
2. packages/sdk 的生成方式/触发（当前本仓仍手写 axios，无 codegen 产物）——契约 ready 后由谁/如何生成 SDK；
3. 契约入 registry 后请在此 @回链 或在对应 webui sub-issue 知会，webui 即从 msw 切真实。

红线自检：本评论无任何甲方可识别信息，示例占位均虚构（acme / example.com / tenant-demo）。

[uniquehole]

📌 WP1 契约进度记录：设计已定案 · producer 已绿灯起草

经讨论 #52/#53/#54/#58，三套契约的不可返工设计点全部拍板，三个 producer 子仓已收到绿灯起草通知。当前阶段：设计定案 · 起草中（契约尚未 PR/合入 registry，对应 checkbox 暂不勾选）。

契约 task	producer	设计定案	绿灯通知	解阻塞
#55 datasources OpenAPI+ICD	data-foundation	路径形状 + D8 中立 + D7 凭据 + 行级 tenant_id(#58)	data-foundation#9	gateway#16
#56 governance-metadata 写入面	governance	读写 DTO 分离 AssetUpsertRequest+JSONB、服务端 id、PUT/{id} 幂等、require_tenant=true（#53）	governance#26	gateway#17
#57 control-plane 成员面	control-plane	header 寻址 /v1/org/members（守 D2）、加已存在 KC user、OrgMemberView、D1/R3（#54）	control-plane#17	gateway#18

关联裁决：业务表隔离档位歧义已裁决——metadata_asset 走行级 tenant_id 先行级、schema-per-tenant 升档后置、动态建表归 control-plane provisioning；落档 arch 05「D9 落地档位说明」已合入 PR #59。

下一步（producer 手上）：起草契约 → PR 到主仓 contracts/ + 登记 registry.yaml/版本递增 → 合入后契约 task 关闭 → gateway #16/#17/#18 Blocked by 依赖自动解除。data-foundation（锚点链）优先。