zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
oh-my-muse/docs/agent-specs/2026-06-06-P1R7SourceOwnerPropagation全局执行版.md

15 KiB
Raw Blame History

P1R7 Source Owner Propagation 全局执行版

结论

本执行版只定义 P1R-7 Source Owner Propagation 的全局落地顺序、子阶段拆分、review gate、验证门槛和当前 AI 草稿处理规则；不实现代码，不提交，不推送，不推进 completed。

总执行主线：

flowchart TB
    GlobalReview["全局审阅版<br/>已双 review PASS"] --> GlobalPlan["全局执行版<br/>本文件，待双 review"]
    GlobalPlan --> Freeze["冻结全局合同<br/>用户可见 Events 不替代内部 Source/Authorization"]
    Freeze --> P7bPlan["P1R-7b 子计划<br/>AI terminal event"]
    P7bPlan --> P7bImpl["P1R-7b 实现<br/>AI outbox + worker + Events evidence"]
    P7bImpl --> NextDecision{"下一 owner 选择"}
    NextDecision --> P7c["P1R-7c Knowledge<br/>source status / projection notification"]
    NextDecision --> P7e["P1R-7e Account<br/>security / quota notification 备选"]
    P7c --> P7d["P1R-7d Market<br/>lifecycle / governance notification"]
    P7e --> P7d
    P7d --> P7f["P1R-7f Content<br/>用户可见 content/task notification"]
    P7f --> Approval["P1R-7 completed approval<br/>用户单独批准"]

硬边界：

  1. 当前 AI outbox / V17 / docs 草稿在 P1R-7b 子计划修订并双 review PASS 前不得继续测试、提交、推送或作为完成证据。
  2. 全局方案只定义“用户可见 Events 发布链路”，不替代正式 Source / Authorization 内部传播链路。
  3. 每个 owner 的实现都必须 fresh implementer + fresh spec review + fresh quality / feasibility review。
  4. completed approval 必须另起任务，不能由任何 dedicated gate 或 owner evidence 自动推出。

范围

本执行版负责：

  • 固化 P1R-7 全局 source owner propagation 合同。
  • 定义后续 P1R-7b/c/d/e/f 子计划顺序和拆分条件。
  • 定义每个子计划必须继承的通用验证门槛。
  • 定义当前 dirty AI 草稿如何进入 P1R-7b 子计划复审。

本执行版不负责：

  • 不改业务代码、迁移、OpenAPI、scanner、coverage JSON/Markdown。
  • 不运行 Maven / pnpm / Flyway / coverage scanner full verification。
  • 不清理或回退当前 dirty/untracked baseline。
  • 不把 streamEvents、P1R-7、Market 或任何 owner 标为 completed。

已验证事实

工作区与 review gate

  1. 正确工作区为 /Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0。
  2. 当前分支为 dev/1.0.0，远端 origin/dev/1.0.0 已 ff-only 对齐。
  3. 当前 HEAD 为 fa29753 test(p1r): 收口 Events SSE 门禁。
  4. 当前 git status --short --branch 显示未提交 AI P1R-7b 草稿、V17 migration 草稿和 docs/agent-specs/ 文档草稿。
  5. 受保护文件定向 git status --short 无输出。
  6. docs/agent-specs/2026-06-06-P1R7SourceOwnerPropagation全局审阅版.md 已通过 fresh spec review：
    • Kant / 019e9987-ca59-7370-bc49-9938eb93c70f / PASS。
  7. 同一全局审阅版已通过 fresh quality / feasibility review：
    • Hubble / 019e998b-2d82-7200-9289-c6c8dd37f744 / PASS。

Coverage 与状态边界

  1. 当前 coverage summary：
    • totalOperations = 233
    • completedOperations = 100
    • needsVerificationOperations = 133
    • incompleteOperations = 0
    • genericPersistenceOperations = 0
    • ssePlaceholderOperations = 0
  2. Events 当前唯一 operation 为 streamEvents GET /app-api/muse/events = dedicated / needs_verification。
  3. Market 当前 32 operations 均为 dedicated / needs_verification。
  4. P1R-7a 收口文档明确：P1R-7a 未接入 source owner propagation，未运行 source owner publish tests。

全局设计事实

  1. CLAUDE.md 将 Source 传播定为“事件驱动 + 各模块自治”。
  2. design-docs/架构-02-核心数据结构与双轨模型.md 明确不需要独立 source 模块。
  3. design-docs/后端-03-关键流程实现与接口契约.md 明确异步失败不得回滚已提交 Canonical。
  4. P1R-7a 执行版已固定 source owner 本域 outbox + worker 调用 Events API；Events server 不反向依赖 source owner server。
  5. Events owner 当前已有 EventsPublishApi、EventsPublishReqDTO、commandId/source tuple 幂等、payload sanitizer、accepted-only 可见查询和 SSE stream。

推断

  1. 全局执行顺序应先冻结通用合同，再修订 P1R-7b AI 子计划；否则当前 AI 草稿可能继续携带单点设计里的事务和 dirty baseline 风险。
  2. AI 仍是第一实现切片，因为它已有 terminal fact、ownerUserId、runtime job 和 focused test 基础。
  3. Knowledge 适合作为第二个 source status propagation owner，但如果后续目标更偏用户通知而非来源状态传播，Account security event 可以作为更低风险 second slice 备选。
  4. Market 应排在 AI/Knowledge 之后，因为 Market Account projection outbox 与 Events publish outbox 职责不同，直接复用风险较高。
  5. Content 需要先界定内部领域事件与用户可见事件，否则容易把 BlockSavedEvent 等内部 trigger 过度推送到 SSE。

假设

  1. 后续 owner 允许在本域新增 publish outbox 或等价状态表。
  2. 后续 owner server 允许新增 muse-module-events-api 依赖。
  3. 现有 Events OpenAPI 事件类型足够覆盖第一轮用户可见摘要；如果不够，应另起合同变更审批。
  4. 当前 AI 草稿可以作为 P1R-7b 子计划的候选素材，但必须经过执行版修订、双 review 和本地验证后才能继续。

全局合同

依赖合同

  1. Source owner server 可以依赖 muse-module-events-api。
  2. Source owner server 不得依赖 muse-module-events-server。
  3. muse-module-events-server 不得依赖 AI / Knowledge / Market / Member / Content server。
  4. muse-server 可以装配 Events server 与各 source owner server。
  5. 每个 owner 子计划必须包含 Maven dependency tree 验证命令。

发布 envelope 合同

每个 owner 子计划必须固定：

字段 要求
commandId 稳定短幂等键，长度 <= 128，推荐 <owner>_evt:<sha256-32>
tenantId 必填，worker 必须恢复租户上下文
ownerUserId 必填，决定 SSE 可见性
sourceOwner 固定 owner 枚举
sourceType 固定业务事实类型
sourceId 本域事实稳定 id 或业务 id
sourceRevision 本域事实版本；缺失时必须在子计划解释占位语义
eventType 只能使用 Events OpenAPI 已声明类型
resourceType/resourceId UI 定位对象，不参与替代 source tuple 幂等
payloadSummary OpenAPI allowlist 安全摘要
emittedAt 本域事实发生时间

用户可见事件判定

每个候选事件进入 SSE 前必须满足：

  1. 用户需要实时感知。
  2. 用户可据此采取动作或理解当前工作状态。
  3. payload 能压缩为 OpenAPI 已声明 schema 的安全摘要。
  4. 不需要暴露内部 source propagation、授权快照、worker、风控或 provider raw 细节。
  5. 能提供稳定 source tuple、commandId、ownerUserId 和 emittedAt。

默认不进入 SSE：

  1. 内部 followup trigger。
  2. projection rebuild / worker heartbeat / retry job 状态。
  3. 需要完整正文、知识资料、provider raw、授权详情或安全原始证据才能解释的事件。

Outbox 合同

每个 owner 子计划必须包含：

  1. queued/running/retryable/published/dead_letter 或等价状态。
  2. attempt_count 或等价 claim 次数字段。
  3. max_attempt 配置。
  4. next_retry_at。
  5. claimed_at。
  6. claim_expires_at。
  7. 固定退避策略。
  8. claim 索引。
  9. FOR UPDATE SKIP LOCKED 或等价原子领取机制。
  10. ON CONFLICT DO NOTHING / insertIgnore + 回查，禁止把唯一约束异常作为正常幂等路径。
  11. published_event_id / published_sequence_no 或等价回写字段。
  12. last_error_code / last_error_message 安全错误摘要。
  13. 中文日志，包含 owner、tenantId、ownerUserId、source tuple、outboxId、attempt、状态转换和错误摘要。

Payload 合同

每个 owner 子计划必须列出：

  1. 允许的 eventType。
  2. 每个 eventType 的 payload allowlist。
  3. 需要丢弃或归一化的敏感字段。
  4. payload invalid 时的 fail-closed 状态和错误码。
  5. rejected/blocked 后不得进入 SSE 可见查询的验证方式。

子阶段执行顺序

Task 0：冻结总执行版

目标：

  • 本文件完成 fresh spec review + fresh quality / feasibility review 双 PASS。
  • 双 PASS 前不修订 P1R-7b 子计划，不继续 AI 草稿测试或实现。

验收：

  • Reviewer 明确 PASS。
  • 如有 FAIL，先修订本文件并重审。
  • protected files 仍无改动。

Task 1：P1R-7b 子计划修订

目标：

  • 修订 docs/agent-specs/2026-06-06-P1R7bSourceOwnerPropagation执行版.md。
  • 将它从“AI 单点执行版”改为“全局执行版下的 AI 第一切片子计划”。
  • 明确当前 AI 草稿的处理策略：修订沿用、拆分提交或用户批准后清理。

必须补充：

  1. 继承本执行版的依赖合同、envelope 合同、outbox 合同和 payload 合同。
  2. 明确 AI 只发布用户可见 terminal done/error 摘要。
  3. 明确 AI outbox 创建不得依赖捕获 DuplicateKeyException 作为正常幂等路径。
  4. 明确 P1R-7b 只处理 AI，不处理 Knowledge / Market / Account / Content。
  5. 明确 P1R-7b 不推进 completed。

Review gate：

  • Fresh spec compliance review。
  • Fresh quality / feasibility review。
  • 双 PASS 前不得继续当前 AI 草稿实现。

Task 2：P1R-7b AI 实现收口

目标：

  • 在 P1R-7b 子计划双 PASS 后，处理当前 AI 草稿或由 fresh implementer 重做。
  • 实现 AI terminal event -> AI publish outbox -> AI worker -> EventsPublishApi -> muse_unified_event -> SSE 可见证据。

必须验证：

  1. AI focused tests。
  2. Outbox mapper/service/worker tests。
  3. Events publish accepted/rejected/blocked/duplicate tests。
  4. SSE visible query tests。
  5. Dependency tree：AI 只依赖 events-api，不依赖 events-server；Events server 不依赖 source owner server。
  6. Migration SQL test 和 Flyway _test。
  7. protected files 无改动。

Review gate：

  • 每个实现 Task fresh implementer。
  • 每个实现 Task fresh spec review。
  • 每个实现 Task fresh quality / feasibility review。

Task 3：第二 owner 选择决策

目标：

  • 在 AI 第一切片通过后，只读评估第二 owner 是 Knowledge source status 还是 Account security notification。

选择规则：

  1. 如果目标是 source status propagation 证据优先，选择 Knowledge。
  2. 如果目标是用户可见通知链路低风险扩展优先，选择 Account security event。
  3. 不因 Market 有 outbox 命名而优先选择 Market。
  4. Content 进入前必须先冻结内部事件与用户可见事件判定。
  5. 如果 Account security event 先于 Market 落地，阶段编号仍保留 P1R-7e，不重命名 P1R-7d，避免阶段编号反向改写历史计划。

输出：

  • docs/agent-specs/YYYY-MM-DD-P1R7c...审阅版.md。
  • fresh spec review + fresh quality review。

Task 4：P1R-7c / P1R-7e 子计划与实现

目标：

  • 按 Task 3 决策进入 Knowledge 或 Account。
  • 每个 owner 都必须先产出单独审阅版，再产出单独执行版；审阅版和执行版各自 fresh spec review + fresh quality / feasibility review 双 PASS 后，才允许进入该 owner 实现。

必须继承：

  • 本执行版的全局合同。
  • P1R-7b 的复用经验，但不得复制 AI payload / 状态机细节到不匹配 owner。

Task 5：Market 与 Content 后续切片

目标：

  • Market 先拆清 Account projection outbox 与 Events publish outbox 职责。
  • Content 先拆清内部 followup trigger 与用户可见 Events notification。

进入条件：

  • 至少已有两个 owner 的 Events publish 链路通过验证，或者用户明确要求优先 Market / Content。

Task 6：P1R-7 completed approval 预检

目标：

  • 汇总 Events owner + 各 source owner evidence。
  • 只读判断是否具备 completed approval 申请条件。

必须包含：

  1. coverage 当前状态。
  2. 所有 owner 的测试证据。
  3. HTTP / SSE / DB / Flyway / dependency / protected file evidence。
  4. 未覆盖 owner 和未覆盖失败路径清单。

边界：

  • 该 task 只做预检，不自动标 completed。
  • completed approval 必须用户单独批准。

验证命令模板

每个 owner 子计划必须按实际模块填充以下模板：

cd /Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0
git status --short --branch
git status --short -- docs/api-contracts/market/openapi.yaml docs/api-contracts/ai/openapi.yaml docs/api-contracts/knowledge/openapi.yaml docs/api-contracts/events/openapi.yaml muse-cloud/scripts/p1r-audit-api-coverage.py docs/superpowers/reports/p1r-api-coverage.json docs/superpowers/reports/p1r-api-coverage.md

cd muse-cloud
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" mvn -o -pl <owner-module> -am -Dtest=<focused-tests> -Dsurefire.failIfNoSpecifiedTests=false test
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" mvn -o -pl muse-server -am -Dtest=<p1r-gate-tests> -Dsurefire.failIfNoSpecifiedTests=false test
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" mvn -o -pl <owner-module> -am dependency:tree

Flyway _test 必须使用独立测试库，且必须显式清空 JVM 代理参数或证明代理不会影响内网 PostgreSQL 连接。

当前 dirty baseline 处理规则

当前未提交 AI P1R-7b 草稿包括：

  • AI module POM、runtime projection service、job service 与相关测试改动。
  • AI publish outbox service / mapper / DO 新文件。
  • muse-cloud/sql/muse/V17__extend_ai_events_publish_outbox.sql。
  • P1R-7b migration SQL/Flyway test 草稿。
  • docs/agent-specs/ 文档草稿。

处理规则：

  1. 本执行版双 PASS 前，不继续测试或实现这些草稿。
  2. P1R-7b 子计划修订时必须显式决定这些草稿是“修订沿用”还是“废弃重做”。
  3. 如果选择修订沿用，必须补证据证明草稿已符合本执行版全局合同。
  4. 如果选择废弃重做，必须先征得用户明确批准后才能清理相关 dirty/untracked 文件。
  5. 任何情况下不得回退用户或其他代理的无关改动。

完成条件

本总执行版完成条件：

  1. 本文件存在且内容覆盖全局合同、子阶段顺序、验证模板、dirty baseline 处理规则。
  2. Fresh spec compliance review PASS。
  3. Fresh quality / feasibility review PASS。
  4. protected files 无改动。
  5. 输出下一步：修订 P1R-7b 子计划，而不是直接继续 AI 实现。
  6. 本轮 reviewer 只读审查文档，不运行 full verification；review PASS 不能解释为实现验证 PASS。

P1R-7 全链路完成条件不在本文件完成范围内；它必须在 P1R-7 completed approval 任务中单独判断。

回滚策略

本执行版只新增文档；若 review FAIL：

  1. 只修订本文件和必要的 .agent 说明。
  2. 不回退代码草稿。
  3. 不修改 protected files。
  4. 不运行 full verification。

若后续实现阶段发现全局合同错误：

  1. 停止对应 owner 实现。
  2. 回到全局审阅版 / 执行版修订。
  3. 重新 fresh spec review + fresh quality review。