222 lines
7.2 KiB
Markdown
222 lines
7.2 KiB
Markdown
# P1R6 Market 规格计划
|
||
|
||
日期：2026-06-03
|
||
|
||
## 背景
|
||
|
||
本次进入 P1R-6 Market Real API 的规格、计划和 review gate 阶段，只完成事实盘点、规格、执行计划、review 修订和阶段留痕，不进入代码实现。
|
||
|
||
真实工作面：
|
||
|
||
```text
|
||
/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0
|
||
```
|
||
|
||
分支：
|
||
|
||
```text
|
||
dev/1.0.0
|
||
```
|
||
|
||
开始前已执行：
|
||
|
||
```bash
|
||
git status --short --branch
|
||
git log --oneline -5
|
||
git pull --ff-only origin dev/1.0.0
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
## dev/1.0.0...origin/dev/1.0.0
|
||
48c750b test(p1r): 补齐 AI 与 Knowledge 外部端到端验收
|
||
Already up to date.
|
||
```
|
||
|
||
## 已验证事实
|
||
|
||
当前 coverage summary：
|
||
|
||
```text
|
||
completedOperations 100
|
||
needsVerificationOperations 100
|
||
incompleteOperations 33
|
||
genericPersistenceOperations 32
|
||
ssePlaceholderOperations 1
|
||
```
|
||
|
||
当前按域状态：
|
||
|
||
```text
|
||
account 33 dedicated / needs_verification
|
||
ai 41 dedicated / completed
|
||
content 51 dedicated / needs_verification
|
||
events 1 sse_placeholder / incomplete
|
||
knowledge 59 dedicated / completed
|
||
market 32 generic_persistence / incomplete
|
||
meta 16 dedicated / needs_verification
|
||
```
|
||
|
||
Market 32 个 operation 当前全部为：
|
||
|
||
```text
|
||
generic_persistence / incomplete
|
||
```
|
||
|
||
当前 Market 实现事实：
|
||
|
||
- `docs/api-contracts/market/openapi.yaml` 声明 32 个 Market operation。
|
||
- `muse-module-market-server` 当前合同入口仍是 `AdminMuseMarketContractController` 和 `AppMuseMarketContractController`。
|
||
- 当前 Market 合同入口统一委托 `MuseContractPersistenceService`，不能作为真实 API 完成证据。
|
||
- `muse-module-market-server` 当前只依赖 `muse-module-market-api`、security、mybatis。
|
||
- `muse-server` 当前同时装配 `muse-module-market-server` 和 `muse-module-member-server`。
|
||
- `muse-module-member-server` 已有 `MarketAccountProjectionFacade`、默认 fail-closed `UnavailableMarketAccountProjectionFacade`、`muse_account_record_projection` DO/Mapper 和 V11 DDL。
|
||
|
||
当前 DDL 事实：
|
||
|
||
- V6 已有 Market 初始资产、版本、安装、发布申请、申诉和 handoff 表。
|
||
- V8 已有 workflow task、favorite、purchase 表。
|
||
- V11 已有 Account 查询读模型 `muse_account_record_projection`。
|
||
- P1R-5 已使用 V14；P1R-6 如新增迁移，推荐使用 `V15__extend_market_real_api_schema.sql`。
|
||
|
||
## 本阶段产物
|
||
|
||
- 规格：`docs/superpowers/specs/2026-06-03-P1R-6-market-real-api-design.md`
|
||
- 计划：`docs/superpowers/plans/2026-06-03-P1R-6-market-real-api.md`
|
||
- 留痕：`docs/memorys/2026-06-03-P1R6Market规格计划.md`
|
||
|
||
## Review 结果
|
||
|
||
本阶段按要求执行 fresh review gate。
|
||
|
||
Spec compliance review：
|
||
|
||
```text
|
||
PASS_WITH_WARNINGS
|
||
```
|
||
|
||
已修复首轮阻塞点：
|
||
|
||
- 计划开头错误写成只允许执行 `Task 1-12`，但正文实际包含 Task 13。已修为 `Task 1-13`。
|
||
|
||
Spec review 非阻塞提醒：
|
||
|
||
- handoff token 业务状态里的 `completed` 不能和 coverage `completionStatus=completed` 混淆。计划已补充消歧说明。
|
||
|
||
Quality / feasibility review：
|
||
|
||
```text
|
||
PASS_WITH_WARNINGS
|
||
```
|
||
|
||
已修复阻塞点：
|
||
|
||
- Task 5 不再要求 Market 模块另建同名 `MarketAccountProjectionFacade` / `UnavailableMarketAccountProjectionFacade`。
|
||
- 已明确 P1R-6 Account 投影采用最小可执行接线方案：`muse-module-market-server` 显式依赖 `muse-module-member-server`，复用 member 侧既有 `MarketAccountProjectionFacade`、`AccountRecordProjectionDO`、`AccountRecordProjectionMapper`。
|
||
- 已明确 `muse_market_account_projection` 只表达 Market 侧 projection sync / outbox 状态，不是 Account 查询读模型。
|
||
- 已明确 Account 查询读模型只能是 V11 已有 `muse_account_record_projection`。
|
||
- 已要求实现阶段用 Maven reactor 或 dependency-tree 验证不形成 Maven 循环，并用 Spring context 测试证明真实 provider 替换默认 unavailable bean。
|
||
|
||
Quality review 非阻塞提醒：
|
||
|
||
- 当前 worktree 仍有 P1R-4 / P1R-5 coverage/test/script 未提交 diff，P1R-6 spec/plan/memory 也是未跟踪文件。进入 P1R-6 实现前必须先提交或明确保留这些 diff，避免阶段混账。
|
||
|
||
## 关键设计结论
|
||
|
||
- P1R-6 目标状态只能是 `dedicated / needs_verification`，不能写成 `completed`。
|
||
- Market owner 是 `muse-module-market`，负责市场来源侧事实、授权、安装、handoff、发布、治理和申诉。
|
||
- Market 不直接写 AI / Knowledge / Content canonical facts。
|
||
- 购买只产生授权，不等于安装；安装只进入账户可用列表，不等于绑定目标 owner。
|
||
- Account 只消费 Market 写入的投影；Account 查询读模型为 `muse_account_record_projection`。
|
||
- `needs_recheck` 不能作为 Market `SourceStatus` 值，只能表达为 action policy / recheck reasons。
|
||
- P1R-7 统一 Events SSE 不属于 P1R-6。
|
||
- 不修改 `docs/api-contracts/market/openapi.yaml`，不修改 scanner 掩盖缺口。
|
||
|
||
## 验证命令与结果
|
||
|
||
coverage audit：
|
||
|
||
```bash
|
||
python3 muse-cloud/scripts/p1r-audit-api-coverage.py --check
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
Generated docs/superpowers/reports/p1r-api-coverage.json
|
||
Generated docs/superpowers/reports/p1r-api-coverage.md
|
||
```
|
||
|
||
coverage 对账：
|
||
|
||
```bash
|
||
jq -r '.summary | [.completedOperations,.needsVerificationOperations,.incompleteOperations,.genericPersistenceOperations,.ssePlaceholderOperations] | @tsv' docs/superpowers/reports/p1r-api-coverage.json
|
||
jq -r '.operations[] | select(.domain == "market") | [.implementationStatus,.completionStatus] | @tsv' docs/superpowers/reports/p1r-api-coverage.json | sort | uniq -c
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
100 100 33 32 1
|
||
32 generic_persistence incomplete
|
||
```
|
||
|
||
文档结构检查：
|
||
|
||
```bash
|
||
python3 - <<'PY'
|
||
import re, pathlib
|
||
plan=pathlib.Path('docs/superpowers/plans/2026-06-03-P1R-6-market-real-api.md').read_text()
|
||
spec=pathlib.Path('docs/superpowers/specs/2026-06-03-P1R-6-market-real-api-design.md').read_text()
|
||
print('plan_tasks', re.findall(r'^## Task (\d+):', plan, re.M))
|
||
print('spec_operation_rows', len(re.findall(r'^\| `[^`]+` \| (GET|POST|DELETE|PUT|PATCH) \| `/', spec, re.M)))
|
||
print('plan_operation_lines', len(re.findall(r'^[A-Za-z].+ (GET|POST|DELETE|PUT|PATCH) /', plan, re.M)))
|
||
PY
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
plan_tasks ['1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11', '12', '13']
|
||
spec_operation_rows 32
|
||
plan_operation_lines 32
|
||
```
|
||
|
||
diff hygiene：
|
||
|
||
```bash
|
||
git diff --check
|
||
```
|
||
|
||
结果：无输出。
|
||
|
||
OpenAPI diff 检查：
|
||
|
||
```bash
|
||
git status --short -- docs/api-contracts/market/openapi.yaml docs/api-contracts/ai/openapi.yaml docs/api-contracts/knowledge/openapi.yaml
|
||
```
|
||
|
||
结果：无输出。
|
||
|
||
## 当前阶段边界
|
||
|
||
本阶段只完成 P1R-6 规格、计划、review 修订和 memory 留痕，没有实现代码。
|
||
|
||
当前不应把任何 Market operation 标为 `completed`。
|
||
|
||
## 下一步
|
||
|
||
进入 P1R-6 实现前必须先处理工作面：
|
||
|
||
1. 提交或明确保留 P1R-4 / P1R-5 coverage completed 推进 diff。
|
||
2. 提交或明确保留 P1R-6 spec / plan / memory 文档 diff。
|
||
3. 再按 `docs/superpowers/plans/2026-06-03-P1R-6-market-real-api.md` Task 1-13 执行。
|
||
|
||
实现阶段执行规则：
|
||
|
||
- 同一实现 Task 内复用最近 implementer。
|
||
- 新 Task 才 fresh implementer。
|
||
- 每个 Task 完成后仍必须 fresh spec review 和 fresh quality / feasibility review。
|
||
- review 结论不能替代真实运行态验收或 coverage `completed` 批准。
|