zizi-al/oh-my-muse

Fork 0

zizi b0b4b2c557 test(p1r): 收口 Content Admin Read completed approval 门禁

2026-06-13 16:55:58 +08:00

16 KiB

Raw Blame History

P1R Content Admin Read Completed Approval 审阅版

日期：2026-06-13

结论

推荐 Content 下一批只推进管理后台只读模型 3 个 operation 的 operation-level completed approval：

content:adminListWorks
content:adminGetWork
content:adminListChapters

不推荐把 Content 剩余 41 个 operation 一次性推进 completed，也不推荐把 content 加入 domain-level completed allowlist。

这 3 个 operation 是 admin 侧读模型，只读取作品摘要、章节摘要和治理摘要，不写 command / audit / outbox，不依赖 FileService、AI candidate、Meta projection 或导入导出产物。它们的 completed approval 应独立成一个小切片，用真实 PostgreSQL _test、MockMvc HTTP 入口、admin RBAC、tenant 隔离、治理摘要聚合和正文不泄露证据闭合。

本审阅版只冻结候选范围、证据标准、风险边界和后续执行版要求。不修改 OpenAPI，不修改 scanner，不修改 coverage report，不修改业务实现，不推进任何 operation completed。

flowchart TB
    Current["当前 Content<br/>10 completed / 41 needs_verification"] --> Choose["选择下一批 evidence slice"]
    Choose --> AdminRead["推荐：admin read<br/>adminListWorks + adminGetWork + adminListChapters"]
    Choose --> Wider["不推荐：Content 剩余 41 全量推进"]
    AdminRead --> Boundary{"是否写入业务事实?"}
    Boundary -->|否| Evidence["只读 evidence<br/>RBAC + tenant + no body leak + no-write"]
    Boundary -->|是| Defer["保持 needs_verification"]
    Evidence --> Review["fresh spec/scope review<br/>fresh quality/feasibility review"]
    Review --> Exec["双 PASS 后写执行版"]
    Exec --> Approval{"用户明确批准后才实现"}
    Approval -->|否| Stay["保持 233/141/92"]
    Approval -->|是| Target["目标 233/144/89<br/>Content 13 completed / 38 needs_verification"]

当前事实状态

工作区：

/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0

当前 HEAD：

2692af3 test(p1r): 收口 Content Planning completed approval 门禁

当前分支状态：

dev/1.0.0...origin/dev/1.0.0

当前 coverage summary：

total=233
completed=141
needsVerification=92
incomplete=0
genericPersistence=0
ssePlaceholder=0

当前 domain 状态：

account  completed=10  needsVerification=23
content  completed=10  needsVerification=41
market   completed=4   needsVerification=28
meta     completed=16  needsVerification=0

本审阅版推荐的下一批目标值只是后续获批后的执行目标：

total=233
completed=144
needsVerification=89
incomplete=0
genericPersistence=0
ssePlaceholder=0

content total=51
completed=13
needsVerification=38

operation key	Method	Path	推荐原因	必补 completed-grade evidence
`content:adminListWorks`	`GET`	`/admin-api/muse/content/works`	admin 作品列表读模型，支持 status / keyword / riskFlag，返回治理摘要，不返回正文	MockMvc HTTP + 真实 PostgreSQL `_test`，覆盖 API version、admin RBAC、分页过滤、riskFlag true/false、治理摘要、tenant 隔离、正文不泄露、纯读 no-write
`content:adminGetWork`	`GET`	`/admin-api/muse/content/works/{workId}`	admin 作品详情读模型，返回作品元信息、章节摘要、异常摘要和治理历史，不返回正文全文	MockMvc HTTP + 真实 PostgreSQL `_test`，覆盖存在、missing、cross tenant、治理历史、章节摘要聚合、正文不泄露、纯读 no-write
`content:adminListChapters`	`GET`	`/admin-api/muse/content/works/{workId}/chapters`	admin 章节摘要列表读模型，按章节顺序返回 blockCount / wordCount / riskFlags，不返回 block 正文	MockMvc HTTP + 真实 PostgreSQL `_test`，覆盖章节排序、blockCount、wordCount 聚合、治理 risk flags、missing、cross tenant、正文不泄露、纯读 no-write

不纳入本批的 operation

以下 38 个 Content operation 必须继续 dedicated / needs_verification：

content:adminListExportTasks
content:adminListImportTasks
content:adminRiskAction
content:confirmChapterParseResult
content:rejectChapterParseResult
content:downloadExportPackage
content:getExportTask
content:getImportTask
content:getParseJob
content:listParseJobChapters
content:batchConfirmChapters
content:retryParseJob
content:createWork
content:deleteWork
content:updateWork
content:deleteBlock
content:mergeBlocks
content:splitBlock
content:mergeBlockSuggestion
content:createChapter
content:deleteChapter
content:updateChapter
content:createBlock
content:reorderChapters
content:validateDynamicFields
content:exportWork
content:createExportTask
content:createImportTask
content:listMetaProjections
content:getMetaProjection
content:createParseJob
content:listPlanningCandidates
content:createPlanningCandidate
content:getPlanningCandidate
content:confirmPlanningCandidate
content:discardPlanningCandidate
content:createStyleCheck
content:getStyleCheckResult

排除原因：

adminRiskAction 是治理写命令，当前 requiresCommandId=true，服务实现包含 command reserve、expectedVersion 校验、行锁、治理事实 insert、audit 和幂等 replay，必须单独做写路径切片。
adminListImportTasks / adminListExportTasks 虽是 admin read，但读的是任务域，证据应覆盖导入导出任务状态、产物和 work 关联，不应夹入本轮作品/章节读模型。
创建、更新、删除、重排、拆分、合并等 Content 写命令仍有独立 OpenAPI / commandId / revision / no-write 负路径闭合风险。
导入、导出、解析、下载仍缺 FileService、任务产物和真实下载字节闭环 evidence。
Meta projection、AI planning candidate、style check、suggestion 等能力依赖 Meta / AI / Knowledge 外部 owner closure 和运行时证据。

已有实现证据

Controller 入口

AdminContentController 当前提供 3 个 admin read route：

GET /muse/content/works
GET /muse/content/works/{workId}
GET /muse/content/works/{workId}/chapters

以上是 controller-local mapping；对外 OpenAPI 路径仍以 /admin-api/muse/... 为准。执行版必须通过当前项目既有 admin MockMvc / Web 测试上下文证明最终 admin API 路径可访问。

三者均调用 requireApiVersion()，并使用：

@PreAuthorize("@ss.hasPermission('muse:content:query')")

这能作为后续执行版的入口证据来源，但不能替代 HTTP + real DB completed evidence。

Service 读模型

ContentAdminServiceImpl.listWorks：

riskFlag=true 时先按当前 tenant 查询 governance action 的 distinct work ids。
通过 WorkMapper.selectAdminPage 按 status、keyword、riskWorkIds 分页。
查询当前页作品的 governance actions，转换为 risk flags 和最后治理时间。

ContentAdminServiceImpl.getWork：

通过 requireWork(workId) 读取作品。
复用 listChapters(workId) 返回章节摘要。
查询治理动作，返回 exception summary 和 governance history。
返回作品元信息、ownerId、wordCount、chapterCount、createdAt、updatedAt，不返回 block 正文。

ContentAdminServiceImpl.listChapters：

通过 requireWork(workId) 确认作品存在。
查询 governance actions。
按 ChapterMapper.selectListByWorkId 顺序返回章节摘要。
通过 BlockMapper.selectCountByChapterId 和 selectWordCountSumByChapterId 聚合 block 数和字数，不返回正文。

OpenAPI 合同

OpenAPI 当前 operationId：

adminListWorks
adminGetWork
adminListChapters

OpenAPI 对 admin read 的核心约束是：

管理员查询作品列表和治理摘要。
管理员查看作品元信息、章节摘要、异常摘要。
管理员查看作品章节列表，不含正文全文。
默认不返回用户私有正文全文，确需查看必须另有合规访问设计。

本切片不需要修改 docs/api-contracts/content/openapi.yaml。

当前单元测试证据

现有 focused tests 可作为执行版辅助证据：

AdminContentControllerTest.should_requireRbacAnnotationsForAdminContentApis
AdminContentControllerTest.should_rejectMissingApiVersion_when_listWorks
AdminContentControllerTest.should_exposeAdminReadRoutesWithoutPrivateBody
ContentAdminServiceTest.should_listWorksWithGovernanceSummary
ContentAdminServiceTest.should_getWorkDetailWithoutPrivateBody
ContentAdminServiceTest.should_listChaptersWithoutBody
ContentAdminServiceTest.should_listChaptersWithAggregatedWordCountAndKeepBlockCount

这些测试不能直接等同 completed。completed approval 仍需要新增或扩展 HTTP + real PostgreSQL _test 证据，证明 route、mapper、tenant 拦截、真实 schema 和 no-write 一起成立。

必补证据标准

后续执行版必须至少覆盖以下矩阵。

Admin List Works

有 X-API-Version 的成功请求。
缺 X-API-Version 的统一错误响应。
admin 权限 muse:content:query 存在，并有缺权限拒绝证据。
status 过滤。
keyword 过滤。
riskFlag=false 返回普通作品分页。
riskFlag=true 只返回存在治理动作的作品。
riskFlag=true 且当前 tenant 无治理动作时返回空页。
risk flags、lastGovernanceActionAt、ownerId、wordCount、chapterCount 等摘要字段正确。
cross tenant 数据不可见。
JSON 响应不含 block 正文、contentText、content、body 等私有正文字段。
请求前后 command、audit、outbox、governance action、work/chapter/block 行数不发生写入变化。

Admin Get Work

存在作品时返回作品元信息、章节摘要、异常摘要、治理历史。
missing work 返回统一错误。
cross tenant work 返回不可见或 not found 语义，不泄露其它 tenant 数据。
章节摘要包含 order、blockCount、wordCount。
governance history 按时间或实现定义顺序返回，risk summary 与治理动作一致。
JSON 响应不含 block 正文、contentText、content、body 等私有正文字段。
纯读 no-write。

Admin List Chapters

存在作品时按 orderNo 升序返回章节摘要。
missing work 返回统一错误。
cross tenant work 返回不可见或 not found 语义。
blockCount 与真实 block 行数一致。
wordCount 聚合使用当前 tenant 数据，空章节或 NULL 字数时返回 0。
risk flags 与治理动作 target scope 语义一致。
JSON 响应不含章节/Block 正文。
纯读 no-write。

Flyway / schema

执行版不需要新增 migration，但必须证明当前 _test 库能从 V1 到当前目标版本 clean migrate，并且 admin read 依赖的表和索引真实存在：

muse_content_work
muse_content_chapter
muse_content_block
muse_content_governance_action

如果复用 Content 既有 Flyway IT，执行版必须明确说明复用关系、目标 schema version、XML 防空跑方式和本切片新增断言；不能把历史 XML 当 fresh evidence。

风险和取舍

admin read 不是 app owner read。

本切片不能要求 owner_user_id = loginUserId。正确边界是 admin RBAC、tenant SQL 拦截、API version 和不泄露正文。执行版如果把 app owner guard 套到 admin read 上，会改变产品语义。
requireWork(workId) 依赖 mapper 和 tenant 拦截器。

Service 内 requireWork 当前调用 workMapper.selectById(workId)，不是显式 owner 查询。completed evidence 必须在真实 MyBatis + tenant interceptor 环境里证明 cross tenant 不可见，而不是只用 mock service。
riskFlag 证据不能扩写成 risk action completed。

riskFlag 只证明 governance action 读聚合；不证明 adminRiskAction 的 commandId、expectedVersion、幂等、行锁、审计和写入路径。
正文字段泄露是本切片的硬风险。

admin read 合同明确默认不返回私有正文全文。执行版必须用 JSON path / JSON 字符串断言正文相关字段不存在，不能只检查 DTO 类名。
只读 no-write 必须跨表断言。

这 3 个 operation 是 read completed approval。执行版必须对 command、audit、outbox、governance action、work、chapter、block 的写入污染做基线计数或关键字段快照断言。

后续执行版要求

后续执行版必须包含：

精确目标 operation 清单：只包括 adminListWorks、adminGetWork、adminListChapters。
operation-level approval：不把 content 加入 domain allowlist。
实施前 RED：旧 report 下 P1R coverage gate 必须因目标 3 ops 尚未 completed 而失败。
HTTP + real PostgreSQL _test gate：新增或独立扩展 P1rContentAdminReadCompletedApprovalIT。
Web/MyBatis/DataSource 测试上下文：必须启用真实 tenant interceptor、真实 mapper、真实 service 和 controller。
RBAC / API version / CommonResult 错误响应证据。
adminListWorks、adminGetWork、adminListChapters 的 happy、missing、cross tenant、正文不泄露、no-write matrix。
focused tests：运行 ContentAdminServiceTest、AdminContentControllerTest 并做 XML 防空跑。
P1R mixed gates：同步所有读取全局 summary、Content 状态或非目标 domain 防回退的 gate。
scanner/report 更新策略：只在用户批准后追加 3 个 content:* operation-level allowlist。
protected diff：OpenAPI、Content main/java、SQL migration 默认不得修改。
.agent 和 docs/memorys 留痕。
rollback：撤回 scanner operation keys、coverage report、P1R gate 目标值和新增 _test，恢复 3 个 operation 为 needs_verification。

审批前置条件

进入执行版前需要 fresh review 双 PASS：

fresh spec/scope review：确认只覆盖 3 个 admin read operation，不夹带 adminRiskAction、import/export task、Content 写命令或 Content domain-level completed。
fresh quality/feasibility/testing review：确认 admin RBAC、tenant 拦截、正文不泄露、riskFlag 聚合、no-write、XML 防空跑和 mixed gate 同步可落地。

执行版双 PASS 后，仍必须由用户明确批准以下事项后才允许实现：

只审批 content:adminListWorks、content:adminGetWork、content:adminListChapters。
继续 operation-level approval，不把 content 加入 domain allowlist。
允许按执行版修改 scanner、coverage report、P1R gate tests、新增 HTTP+DB _test 和 memory。
允许同步 P1R mixed gate 的 summary / Content / 非目标域防回退断言。

本审阅版验收标准

候选 operation 和目标值可由当前 report 机械推导。
非目标 38 个 Content operation 明确保持 needs_verification。
admin read 与 app owner read、risk action 写命令、import/export task 读模型的边界清晰。
evidence 标准包含 admin RBAC、tenant 隔离、正文不泄露、riskFlag 聚合、no-write 和 XML 防空跑。
未修改 OpenAPI、scanner、coverage report、业务实现、SQL migration 或 P1R gate。

16 KiB Raw Blame History Unescape Escape