# 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` 批准。