oh-my-muse/docs/agent-specs/2026-06-20-meta-schema用量投影-execution.md

Meta Schema 用量投影建模 —— 执行版

版本:v0.2(执行版,经 5-persona 评审修订) · 日期:2026-06-20 · 目标读者:实现 agent + 架构 review · 类型:执行版(可落地步骤,无代码实现) 上游:评审版 v0.2(方向已确认 §十)。 决策基线(人类 2026-06-20):Pull 按需查询 + 保留全 5 维度 + 字段级破坏分析 + 全维度真实才放行。 边界门:bc-boundaries——Meta 不直连他域 .dal/.application;BcBoundaryArchTest 须保持 0 违例。

⚠️ v0.2 评审修订摘要(2026-06-20,5-persona + 自验 grep)

v0.1 依赖的 grounding 在 4 处 over-claim,经 adversarial/feasibility/scope/security 多票 + 自验代码证伪。核心结论:真实化的"地基"在代码里不存在,必须先新建,故本特性比 v0.1 估计显著更大、风险更高。已证伪前提:

1. (P0)破坏字段集无生产者:MetaSchemaValidationServiceImpl.compatibility() 只算 type_changed,且 draftField != null 守卫使移除字段不产破坏,全无可见性比对(自验:该文件 L211/L214)。→ probe 的 removedFieldKeys/visibilityChangedFieldKeys 无来源,真能算的 type_changed 反而没通道(=类型变更假绿)。必须新建移除/可见性/类型变更三类破坏集计算。
2. (P0)schema_key 无来源:WorkDO.workSchemaId 是死代码(自验:全 content/meta 仅 WorkDO.java:30 声明、零读写),content 全模块无 schemaKey,ContentMetaFacade 无解析方法,planning 的 schemaVersion 来自 reqVO 默认 1。→ 回填源与写入点解析路径均虚构,须从零设计 schema_key 捕获。
3. (P1)可见性字段级不可直取:MetaFieldDO 无可见性列;muse_meta_visibility_policy 版本级;完整字段级可见性仅在 fieldContractSnapshot/policySnapshot JSON(MetaSchemaServiceImpl L575 实证)。→ visibilityChangedFieldKeys 须解析快照 JSON diff。
4. (P1)contentPayload key≠schema fieldKey:contentPayload 是 AI/用户内容 map,与 MetaField fieldKey 无强制对应(可能嵌套/改名)。→ 字段级 JSON-key 扫描需先验证结构,否则降级为"实例命中 schema_key"(非字段级)。 外加:preview 仅 draft 版(activate/rollback/deprecate 3 端点无法经本 preview 解阻);facade 装配应 @Primary @Service+去 @ConditionalOnMissingBean(@Service 上不可靠);preview 钉 schema hash 不钉消费数据(陈旧 0 放行);贡献者 DTO→既有 *ImpactSummaryVO 映射未定义;Export 贡献者置 content-server 无法真实计数(须 meta-server 或 VERIFIED_ZERO);VERIFIED_ZERO 须机械化断言防漂移。详见各节 + §九。

---

一、结论先行

1. 目标:让 Meta 治理 4 端点从"恒 fail-closed"变为"基于真实字段级 impact preview 后可放行",全 5 维度真实才放行(任一维度非真实→继续 fail-closed,绝不伪造/绝不 unknown 蒙混)。
2. 关键架构(订正):破坏判定(Meta 域)与实例计数(各消费域)干净分离——Meta 算出"破坏字段集",传给各 BC 贡献者,各 BC 只查本域、返回本维度计数。但破坏字段集的计算是净新增(见 §四.3,v0.1 误称"复用"):现有 compatibility() 只算 type_changed,须新建移除集(active−draft)+ 可见性集(快照 diff)+ 把 type_changed 纳入 probe。
3. 5 维度实证定性:仅 Planning 可作真实消费者(但前提:schema_key 须先有来源——当前无,见 §四.4);Work / KnowledgeProjection 实证零 schema 消费→「已验证真实 0」贡献者(须机械化断言);AIContext / Export 消费侧零持久化→P3 定性(Export 真实计数须置 meta-server,否则 VERIFIED_ZERO)。
4. 字段级破坏的真实成本:v0.1 称"contentPayload 已隐含字段用量、无需快照表"——此前提未验证。contentPayload 与 schema fieldKey 无强制对应,须先验证结构(§四.4);若非扁平 1:1,要么写结构化提取器,要么字段级降级。这与上游"字段级须存快照"决策的关系须显式厘清(见 §九.1)。
5. "全维度真实才放行"的硬阻塞(订正):不仅是"价值末期兑现",更有两处地基缺失会使 all-real 根本不可达:① schema_key 无来源→历史 planning 行无法归类;② 破坏集无生产者→字段级计数为空。必须先建地基(见新增 §四.0)。

---

二、范围与非目标

范围(本执行版)

• 地基层(净新增,P0 之前/之内):破坏字段集生产者(移除+可见性+类型变更)+ schema_key 捕获机制 + 可见性快照 diff。
• meta-api 贡献者端口契约 + meta-server 真实聚合器(替换 UnavailableMetaImpactFacade,all-real 门 + DTO→既有 VO 映射)。
• 5 维度各出真实贡献者:真实计数 或 已验证真实 0(均须机械化可证)。
• Planning 基础层:schema_key 写入捕获 + 历史口径 + 字段级计数(结构验证后)。
• 每阶段独立 Flyway(只增列/表)+ 真实 PG IT 验收。

非目标

• 不改 previewMetaSchemaDraftImpact(schemaKey, draftVersion, draftHash) 对外签名与 publish 端点 API 契约。
• (订正)本轮不解决 activate/rollback/deprecate 的非 draft preview 生成(见 §九.5);本轮 all-real 解阻先以 publish 为验收锚点。
• 不做运营用量大盘/报表;不引入独立 usage 模块;不做 admin 前端;不引入 @FeignClient。

---

三、5 维度实证定性

维度	BC / 载体	schema 持久化现状	定性	落地策略(订正)
Planning	content muse_content_planning_section(PlanningSectionDO)	schemaVersion INT;无 schema_key;字段值在 contentPayload JSONB	可作真实消费者,但 schema_key 须先有来源(当前无)	须先建 schema_key 捕获(§四.4);字段级须先验证 contentPayload↔fieldKey 结构
Work	content muse_content_work(WorkDO)	零 MetaSchema 引用(workSchemaId 死代码,仅声明)	已验证真实 0(P2 二次确认 affectedDynamicFieldWorkCount 是否别处有 work 级动态字段)	VERIFIED_ZERO 贡献者 + 机械化断言(测试断言本域无 schema 列/查询)
KnowledgeProjection	knowledge 投影表	零 schema 引用	已验证真实 0	同上,VERIFIED_ZERO + 机械化断言
AIContext	ai(无 schema 持久化 DAL)	消费侧零;schema 侧 MetaVisibilityPolicyDO.aiContext(版本级)	待定性(P3a spike)	真消费→建模;否→VERIFIED_ZERO。若 AI 运行时注入不持久化,Pull 模型可能不适用(见 §九.5)
Export	content ExportTaskDO(零 schema 引用)	schema 侧 MetaVisibilityPolicyDO.exportable(版本级,在 meta)	待定性(P3a spike)	真实计数须置 meta-server(content-server 读不到 meta 可见性,跨 BC 违例);否则 content-server 返 VERIFIED_ZERO

"已验证真实 0" ≠ unknown:须机械化可证(co-located 测试断言该域确无 schema 引用,后续漂移会令测试失败而非静默放行)。unknown(无数据可答)一律 fail-closed。

---

四、架构与数据契约

4.0 地基层(净新增,所有贡献者的前置)

v0.1 把这层误当"已存在/复用"。评审证伪,故独立成节。地基不就位,任何维度都无法真实计数。

• G1 破坏字段集生产者(meta-server):在现有 active/draft 字段比对之上新增:
  • removedFieldKeys = activeFieldKeys − draftFieldKeys(现 compatibility() 因 draftField != null 守卫完全不算)。
  • typeChangedFieldKeys = 现 compatibility() 已能算(type_changed),须纳入 probe(v0.1 漏了)。
  • visibilityChangedFieldKeys = 解析 active vs draft 的 fieldContractSnapshot/policySnapshot JSON,做字段级可见性 diff(字段级可见性不在列,只在快照 JSON;MetaSchemaServiceImpl L575)。
  • 验收:专项 IT——移除字段/类型变更/可见性收窄各产出非空集。
• G2 schema_key 捕获机制(content + meta-api):当前无任何 work→schema 绑定。须设计 schema_key 来源(见 §四.4 + §九.2 决策),否则 Planning 无法真实化。
• G3 可见性快照 diff 工具(meta-server):G1 的 visibility 子能力,解析 JSON 快照。

4.1 总览(订正:V 节为净新增)

flowchart TD
    A[AdminMetaSchemaController\npublish 先行;activate/rollback/deprecate 见§九.5] --> B[MetaSchemaServiceImpl.requireImpactPreview]
    B --> C[MetaSchemaImpactPreviewServiceImpl 对外语义不变]
    C --> D[RealMetaImpactFacade 聚合器\nmeta-server, @Primary @Service]
    D --> V[G1 破坏字段集生产者 净新增\nremoved + typeChanged + visibilityChanged]
    D -->|fan-out: probe 含破坏字段集| E1[Planning 贡献者\ncontent-server 查本域]
    D -->|fan-out| E2[Work 贡献者 VERIFIED_ZERO+断言]
    D -->|fan-out| E3[KnowledgeProjection 贡献者 VERIFIED_ZERO+断言]
    D -->|fan-out| E4[AIContext 贡献者 P3a 定性]
    D -->|fan-out| E5[Export 贡献者 P3a;真实计数须 meta-server]
    D -->|all-real 门 + 5维度齐全| F[MetaSchemaDimensionImpact x5\n→映射→ 既有 *ImpactSummaryVO]
    F --> G[(muse_meta_impact_preview 存快照)]
    subgraph meta-api 端口契约
      P[MetaSchemaUsageContributor\nMeta 定义、各 owner BC 实现 @Service Bean]
    end
    E1 & E2 & E3 & E4 & E5 -. implements .-> P
    D -. 依赖端口 .-> P

4.2 端口契约(meta-api,新增)

• MetaSchemaUsageContributor(进程内 @Service Bean 端口,参照 MuseAccountRecordProjectionApi 先例,非 @FeignClient):
  • MetaSchemaDimensionImpact previewDimensionImpact(MetaSchemaImpactProbe probe)
  • MetaImpactDimension dimension()(供聚合器校验 5 维度齐全)
• MetaSchemaImpactProbe(Meta→贡献者):schemaKey / draftVersion / draftHash / Set<String> removedFieldKeys / Set<String> typeChangedFieldKeys / Set<String> visibilityChangedFieldKeys。
  • 破坏字段集由 G1 算好传入,贡献者只在本域按 fieldKey 计数→守边界门。
• MetaSchemaDimensionImpact(贡献者→Meta):dimension / affectedInstanceCount / fieldRemovedInstanceCount / typeChangedInstanceCount / visibilityChangedInstanceCount / realityKind(REAL_COUNT | VERIFIED_ZERO)。无 unknown 态;无法真实作答→抛异常→聚合器 fail-closed。
• DTO→既有 VO 映射(订正,v0.1 缺):聚合出口仍是既有 MetaSchemaImpactSummary(WorkImpactSummaryVO, PlanningImpactSummaryVO, ...)。须在聚合器内定义映射,如 Planning:affectedInstanceCount→affectedPlanningSections、fieldRemoved+typeChanged+visibilityChanged→planningUsingDeprecatedFields(口径须明确);VERIFIED_ZERO 维度→对应 VO 全零。

4.3 聚合器(meta-server)

• RealMetaImpactFacade implements MetaImpactFacade,@Primary @Service(参照 RealContentFileFacade/RealAccountFileServiceFacade 实证先例);去掉 @ConditionalOnMissingBean(UnavailableMetaImpactFacade 注释明示其在 @Service 上不可靠、曾致单体启动不注册);并退役 Unavailable 的 @Service,保证单体内仅一个 MetaImpactFacade Bean。P0 IT 须断言"恰好一个 MetaImpactFacade 装配"。
  1. 调 G1 算 removedFieldKeys+typeChangedFieldKeys+visibilityChangedFieldKeys。
  2. 注入 List<MetaSchemaUsageContributor>,校验 5 维度齐全(缺任一→fail-closed)。
  3. fan-out 调各贡献者(本域只读);任一抛异常/超时→整体 fail-closed(all-real;不吞/不降级/不伪造)。须定义 per-贡献者超时预算(§九.6)。
  4. 全 5 维度均返→映射组装 MetaSchemaImpactSummary。
• 现 MetaSchemaImpactPreviewServiceImpl 与 publish 端点契约不变。

4.4 Planning 基础层 + schema_key 来源(content,P1)——⚠️ 当前无来源

• 前置决策(§九.2):schema_key 无任何现成来源(workSchemaId 死、ContentMetaFacade 无解析器、content 无 schemaKey)。须二选一:
  • (A 推荐)写入时捕获:新增 content→meta 的 schema_key 解析(如 ContentMetaFacade 增方法或调用方传入),ContentPlanningServiceImpl 写入点回填;历史行无可推断来源→显式排除口径(记录为 no-source cohort,不计入、不伪装 0;all-real 仅对新写入前向成立)。
  • (B) 若确有未发现的 work→schema 绑定:P1 起始 spike 证实后再用。
• Flyway 新增列 muse_content_planning_section.schema_key VARCHAR(只增)。
• 字段级前置:先只读验证一批 contentPayload 的 key 结构与 MetaField fieldKey 是否扁平 1:1。是→可扫描;否→写递归/限域提取器,或字段级降级为"实例命中 schema_key"并相应下调声明。
• 贡献者 ContentPlanningUsageContributor(只读本域):affectedInstanceCount=count(schema_key=probe.schemaKey & 未删);各破坏维度=该集合中 contentPayload key ∩ 对应破坏集 非空 的实例数;realityKind=REAL_COUNT。

---

五、分阶段(订正:增地基层 P0a;治理解阻锚定 publish)

阶段	内容	验收(真实 PG IT)
P0a 地基	G1 破坏字段集生产者(移除+类型变更+可见性快照 diff)+ §九.2 schema_key 来源决策落地	移除/类型变更/可见性各产非空集的专项 IT
P0b 端口/聚合器	meta-api 端口 + RealMetaImpactFacade(@Primary @Service、去 ConditionalOnMissingBean、退役 Unavailable @Service、fan-out、all-real 门、5 维度齐全、DTO→VO 映射)	贡献者未齐→fail-closed;齐全(测试包内联 5 个 stub 贡献者,非跨模块)→正确聚合;断言恰一个 Facade Bean
P1 Planning	schema_key 捕获(§四.4 A)+ 历史口径 + contentPayload 结构验证 + ContentPlanningUsageContributor 字段级计数	种带 schema_key+contentPayload 字段的实例→返真实各破坏计数;无消费→真实 0;无 source 历史行显式排除不伪造
P2 Work/Knowledge	两个 VERIFIED_ZERO 贡献者 + 机械化断言测试;二次确认 work 无别处动态字段	恒 VERIFIED_ZERO;断言本域无 schema 列/查询的测试(漂移即失败)
P3a 定性 spike	只读调查 AI/Export 是否真消费 schema(产出每维度"真实建模"or"已验证 0"结论)	spike 报告;无需人类批准即可执行
P3b 实现 + 解阻	按 P3a 分支:已验证 0→加 VERIFIED_ZERO 贡献者;真实→建模(Export 真实计数置 meta-server)。全 5 维度真实后,publish 端点 preview→publish 走通	全 5 维度真实 IT;publish 在全真实下走通;任一维度退化→fail-closed;preview 0→新增 using 实例→publish 不得放行(防陈旧,§九.4)

注:activate/rollback/deprecate 的解阻不在本轮(其 preview 须非 draft 版生成路径,见 §九.5),本轮 all-real 价值锚定 publish。

---

六、Blast Radius / 兼容性 / 回滚

• meta:新增 meta-api 端口 DTO + G1 地基 + 聚合器替换 Unavailable(@Primary @Service,平滑可退)。publish 端点 API 契约不变。
• content(P1):schema_key 列只增;新增写入捕获;贡献者只读本域。
• knowledge/ai(P2/P3):仅在确属消费方时改;否则 VERIFIED_ZERO(零数据面)。
• 迁移:每阶段独立 V<n>__*.sql(只增列/表);schema_key 仅前向捕获,历史按 no-source 口径(不强行回填虚构来源)。
• 回滚:聚合器未齐/任一退化即 fail-closed=回到现状;schema_key 列保留无害。
• 边界门:聚合器仅依赖 meta-api 端口 + 自域;各贡献者仅读本域;Export 真实计数置 meta-server→BcBoundaryArchTest 0 违例(验收硬条件)。

---

七、风险与缓解(订正)

风险	说明	缓解
地基不存在(已坐实)	破坏集生产者 + schema_key 来源 + 字段级可见性均须新建	P0a 独立先行 + 专项 IT;本特性真实工作量按"含地基"重估
schema_key 历史不可回填	无 work→schema 绑定	前向捕获 + 历史 no-source 显式排除口径(不伪造 0)
contentPayload≠fieldKey	字段级扫描可能多/少计	P1 先验证结构;不满足则结构化提取器或降级声明
preview 陈旧	preview 钉 schema hash 不钉消费数据	解阻锚定 publish + IT:preview 0→新增实例→不得放行;必要时 preview 有效期/写守卫
跨 BC 同步扇出超时	任一贡献者慢查询阻塞全治理	per-贡献者超时预算 + 本域索引;超时→fail-closed(不放行/不伪造)
VERIFIED_ZERO 漂移	域后续新增 schema 消费却仍返 0	co-located 机械化断言测试,漂移即失败

---

八、验收标准(达成定义)

• 地基:G1 三类破坏集专项 IT 通过;schema_key 来源决策落地且 P1 可用。
• 端口/边界:MetaSchemaUsageContributor 在 meta-api;聚合器替换后 BcBoundaryArchTest 0 违例;恰一个 MetaImpactFacade Bean。
• P1(Planning,真实 PG IT):真实各破坏计数;无消费→真实 0;无 source 历史行显式排除不伪造;contentPayload 结构经验证。
• P2:Work/Knowledge VERIFIED_ZERO + 机械化断言测试。
• P3:定性 spike 结论;全 5 维度真实后 publish preview→publish 走通,任一退化即 fail-closed;陈旧防护 IT 通过。
• 反假绿:无来源/不可归类数据不得伪装 0;VERIFIED_ZERO 须机械化可证;unknown 一律 fail-closed;type_changed 不得被漏算。

---

九、Open Items(供决断;⚠️ 标 P0 阻塞者须先定)

1. ⚠️ 字段级 vs contentPayload 与上游决策的关系:上游(评审版 §十)定"字段级须存每实例快照";执行版发现 contentPayload 或可替代但未验证结构。须定:验证 contentPayload 足够(则无需快照表)/补快照表/字段级降级。决策前 Planning 字段级不可落地。
2. ⚠️ schema_key 来源(P0 阻塞):无任何现成来源。选 §四.4 A(写入捕获+历史排除)还是另设绑定?这决定 Planning 能否真实化、all-real 能否达成。
3. AIContext/Export 是否真消费 schema(P3a spike 定):若确不消费→永久 VERIFIED_ZERO?Export 真实计数置 meta-server 是否可接受?
4. 超时/部分失败语义:确认"任一贡献者超时→整体 fail-closed"(正文 §4.3 已按此写)。
5. activate/rollback/deprecate 解阻:其 preview 须非 draft 版生成路径(现 previewMetaSchemaDraftImpact 拒非 draft)。本轮排除、仅解阻 publish——确认可接受,否则须扩 preview 生成。
6. per-贡献者超时预算 + 是否并行扇出:取值待定。
7. 端口粒度:单一 MetaSchemaUsageContributor(按 dimension 区分)——正文已按此设计;若 review 改每维度独立接口则 §四.2 重写。

下一步:鉴于评审证伪了地基存在性,本轮的真实成本与可达性较 v0.1 显著上升。建议人类就 §九.1/§九.2(P0 阻塞)与"是否仍坚持全 5 维度+字段级+全真实,或回退到 Content-only+计数优先"再决断,再进 P0a。