291 lines
10 KiB
Markdown
291 lines
10 KiB
Markdown
# P1R6 Market 真实 API 收口
|
||
|
||
日期：2026-06-05
|
||
|
||
## 结论
|
||
|
||
P1R-6 Market Task 13 已完成最终验证、coverage 报告对账、真实 PostgreSQL / Flyway `_test` 迁移验收与 memory 留痕。
|
||
|
||
本次只把 Market 32 个 operation 收口到 `dedicated / needs_verification`，没有把 Market 标记为 `completed`。
|
||
|
||
P1R coverage 当前关键数字为：
|
||
|
||
```text
|
||
completedOperations 100
|
||
needsVerificationOperations 132
|
||
incompleteOperations 1
|
||
genericPersistenceOperations 0
|
||
ssePlaceholderOperations 1
|
||
```
|
||
|
||
统一 Events SSE 仍只有 P1R-7 `streamEvents`，状态为 `sse_placeholder / incomplete`；本次没有进入 P1R-7。
|
||
|
||
## 已验证事实
|
||
|
||
### 工作区与边界
|
||
|
||
本次验证在指定 worktree 执行：
|
||
|
||
```text
|
||
/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0
|
||
```
|
||
|
||
当前分支：
|
||
|
||
```text
|
||
dev/1.0.0
|
||
```
|
||
|
||
当前远端：
|
||
|
||
```text
|
||
origin ssh://git@100.64.0.8:2222/admin/oh-my-muse.git
|
||
```
|
||
|
||
本次没有在 `/Users/qingse/Sync/local-git/oh-my-muse` 写文件。
|
||
|
||
本次没有清理、回退当前 dirty / untracked baseline。
|
||
|
||
### coverage 重新生成
|
||
|
||
执行命令：
|
||
|
||
```bash
|
||
tmpvenv=$(mktemp -d /tmp/p1r6-py.XXXXXX)
|
||
/opt/homebrew/bin/python3.12 -m venv "$tmpvenv"
|
||
"$tmpvenv/bin/python" -m pip install --quiet PyYAML
|
||
"$tmpvenv/bin/python" muse-cloud/scripts/p1r-audit-api-coverage.py --check
|
||
code=$?
|
||
rm -rf "$tmpvenv"
|
||
echo scanner_exit=$code
|
||
exit $code
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
Generated docs/superpowers/reports/p1r-api-coverage.json
|
||
Generated docs/superpowers/reports/p1r-api-coverage.md
|
||
scanner_exit=0
|
||
```
|
||
|
||
补充事实：本轮默认 `python3` 指向的 Framework Python 3.12 在导入标准库 `dataclasses -> inspect -> dis -> opcode` 阶段卡住，`timeout 60 python3 -u muse-cloud/scripts/p1r-audit-api-coverage.py --check` 返回 `scanner_exit=124`。使用 Homebrew Python 3.12 临时 venv 安装 PyYAML 后，同一 scanner 脚本通过；这不是 coverage 逻辑失败。
|
||
|
||
### coverage 对账
|
||
|
||
执行命令：
|
||
|
||
```bash
|
||
jq -r '.operations | group_by(.domain)[] | [.[0].domain, (length|tostring), ([group_by(.implementationStatus + "/" + .completionStatus)[] | (.[0].implementationStatus + "/" + .[0].completionStatus + ":" + (length|tostring))] | join(", "))] | @tsv' docs/superpowers/reports/p1r-api-coverage.json
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
account 33 dedicated/needs_verification:33
|
||
ai 41 dedicated/completed:41
|
||
content 51 dedicated/needs_verification:51
|
||
events 1 sse_placeholder/incomplete:1
|
||
knowledge 59 dedicated/completed:59
|
||
market 32 dedicated/needs_verification:32
|
||
meta 16 dedicated/needs_verification:16
|
||
```
|
||
|
||
执行命令：
|
||
|
||
```bash
|
||
jq -r '.summary | [.completedOperations,.needsVerificationOperations,.incompleteOperations,.genericPersistenceOperations,.ssePlaceholderOperations] | @tsv' docs/superpowers/reports/p1r-api-coverage.json
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
100 132 1 0 1
|
||
```
|
||
|
||
执行命令：
|
||
|
||
```bash
|
||
jq -r '.operations[] | select(.domain == "market") | [.operationId,.implementationStatus,.completionStatus] | @tsv' docs/superpowers/reports/p1r-api-coverage.json | sort
|
||
```
|
||
|
||
结果：Market 32 个 operation 全部为 `dedicated / needs_verification`。
|
||
|
||
额外核验：
|
||
|
||
```bash
|
||
jq -r '[.operations[] | select(.domain=="market" and (.completionStatus=="completed" or .implementationStatus!="dedicated" or .completionStatus!="needs_verification"))] | length' docs/superpowers/reports/p1r-api-coverage.json
|
||
jq -r '[.operations[] | select(.domain=="market")] | length' docs/superpowers/reports/p1r-api-coverage.json
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
0
|
||
32
|
||
```
|
||
|
||
### Maven gate
|
||
|
||
执行命令：
|
||
|
||
```bash
|
||
cd muse-cloud
|
||
JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn -pl muse-server -Dtest=P1rApiCoverageReportTest,P1rMarketRealApiGateTest,P1rMarketRouteOwnershipTest,P1rMarketMigrationSqlTest test
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
Tests run: 24, Failures: 0, Errors: 0, Skipped: 0
|
||
BUILD SUCCESS
|
||
```
|
||
|
||
本次计划指定的 `-pl muse-server` 命令没有触发 reactor 依赖或无匹配测试模块失败，因此没有执行 fallback 复跑。
|
||
|
||
### Market focused tests
|
||
|
||
先发现 Market 测试类：
|
||
|
||
```bash
|
||
rg --files muse-cloud/muse-module-market/muse-module-market-server/src/test muse-cloud/muse-server/src/test/java/cn/iocoder/muse/server/framework/api | sort
|
||
```
|
||
|
||
发现 `muse-module-market-server/src/test` 下 21 个 Market 测试类，覆盖 service、controller 和 mapper。
|
||
|
||
执行聚合测试：
|
||
|
||
```bash
|
||
cd muse-cloud
|
||
JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn -pl muse-module-market/muse-module-market-server -am -Dtest='*Market*Test' -Dsurefire.failIfNoSpecifiedTests=false test
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
Tests run: 191, Failures: 0, Errors: 0, Skipped: 0
|
||
BUILD SUCCESS
|
||
```
|
||
|
||
Surefire XML 交叉汇总结果：
|
||
|
||
```text
|
||
market_server_xml_classes 21
|
||
market_server_xml_totals 191 0 0 0
|
||
```
|
||
|
||
### Task 12 Flyway IT
|
||
|
||
执行命令：
|
||
|
||
```bash
|
||
cd muse-cloud
|
||
set -a
|
||
. ~/.config/muse-repo/infra.env
|
||
set +a
|
||
export P1R_FLYWAY_PASSWORD="$MUSE_POSTGRES_PASSWORD"
|
||
P1R6_TEST_DB="${P1R6_TEST_DB:-muse_local_p1r6_test}"
|
||
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \
|
||
timeout 180 mvn -o test -pl muse-server \
|
||
-Dtest=P1rMarketFlywayMigrationIT \
|
||
-Dflyway.postgresql.transactional.lock=false \
|
||
-Dp1r.flyway.url="jdbc:postgresql://${MUSE_POSTGRES_HOST}:${MUSE_POSTGRES_PORT}/${P1R6_TEST_DB}" \
|
||
-Dp1r.flyway.user="$MUSE_POSTGRES_USERNAME" \
|
||
-Dp1r.flyway.locations="filesystem:sql/muse"
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
flyway_success=true
|
||
flyway_url=jdbc:postgresql://<host>:5433/muse_local_p1r6_test
|
||
flyway_locations_requested=filesystem:sql/muse
|
||
flyway_locations_effective=filesystem:/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0/muse-cloud/sql/muse
|
||
migrations_executed=15
|
||
successful_migration_count=15
|
||
target_schema_version=15
|
||
flyway_latest=15:extend market real api schema
|
||
schema_version=15
|
||
Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
|
||
BUILD SUCCESS
|
||
```
|
||
|
||
Task 12 真实 Flyway IT 当前保持通过：`P1rMarketFlywayMigrationIT` 3 tests，验收到 V15，且 V1-V15 共 15 条 SQL migration 成功。
|
||
|
||
补充事实：不带 `-Dflyway.postgresql.transactional.lock=false` 的同一 Flyway IT 两次在 `PostgreSQLAdvisoryLockTemplate` / `flyway.migrate()` 路径卡住，必须终止 Maven/Surefire 进程；独立 `psql` 在临时 `_test` 探针库按 V1-V15 顺序执行全部 SQL 成功，证明 V15 SQL 本身可执行。加上 Flyway PostgreSQL 非事务 advisory lock 参数后，独立探针库和计划默认 `muse_local_p1r6_test` 均通过；探针库已清理。
|
||
|
||
### diff hygiene
|
||
|
||
执行命令：
|
||
|
||
```bash
|
||
git diff --check
|
||
```
|
||
|
||
结果：无输出。
|
||
|
||
执行命令：
|
||
|
||
```bash
|
||
git status --short -- docs/api-contracts/market/openapi.yaml docs/api-contracts/ai/openapi.yaml docs/api-contracts/knowledge/openapi.yaml muse-cloud/scripts/p1r-audit-api-coverage.py
|
||
```
|
||
|
||
结果：无输出。
|
||
|
||
因此，本次没有修改 Market / AI / Knowledge OpenAPI。
|
||
|
||
本次也没有修改 `muse-cloud/scripts/p1r-audit-api-coverage.py` 来掩盖缺口。
|
||
|
||
### review gate 记录
|
||
|
||
P1R-6 Market 实现阶段本轮 fresh review gate 结论为：
|
||
|
||
```text
|
||
Spec compliance review: PASS_WITH_WARNINGS
|
||
Quality / feasibility review: PASS_WITH_WARNINGS
|
||
```
|
||
|
||
reviewer：
|
||
|
||
```text
|
||
spec compliance reviewer: 019e9576-b387-7671-8e4b-06573003b705
|
||
quality / feasibility reviewer: 019e957c-b7d3-7170-bdbd-64e99176970e
|
||
```
|
||
|
||
这些 review 结论只证明 P1R-6 实现边界与质量可行性通过带警告评审，不能替代真实运行态 / 端到端验收，也不能作为把 Market coverage 推进到 `completed` 的依据。
|
||
|
||
## 推断
|
||
|
||
基于 coverage scanner、route ownership gate、Market focused tests、muse-server gate 与真实 Flyway IT 的组合证据，可以判断 P1R-6 Market 已具备 dedicated 入口、Market owner 路由归属、核心服务/controller/mapper 测试覆盖和 V15 数据库迁移验收基础。
|
||
|
||
由于本次没有做真实运行态 / 端到端用户流验收，不能推断 Market 已达到业务完成态。
|
||
|
||
## 假设
|
||
|
||
本次假设 `~/.config/muse-repo/infra.env` 中的 PostgreSQL 连接配置仍是项目允许用于 P1R `_test` Flyway 验收的本地/内网测试配置。
|
||
|
||
本次假设当前 dirty / untracked baseline 来自 Tasks 3-12 或用户已有工作，因此只在 Task 13 指定范围内新增 memory、重新生成 coverage 报告，不做清理或回退。
|
||
|
||
## 剩余 warnings
|
||
|
||
- `recordFailed` 仍未被业务写路径使用，失败命令审计和重放语义仍弱；本轮 quality review 判定为 P2 warning，不阻塞 `dedicated / needs_verification`。
|
||
- 并发首购覆盖是 Mockito 分支测试，不是真实 PostgreSQL 双事务竞争测试；若后续申请 Market `completed`，应补真实 DB 并发 / HTTP 幂等验收。
|
||
- `P1rMarketRouteOwnershipTest` 仍是源码扫描 gate，只能证明当前源码静态匹配结果，不能替代运行态路由注册和真实 HTTP 调用验收。
|
||
- `P1rApiCoverageReportTest` / coverage gate 读取生成后的 JSON 报告，能防止报告状态回退，但不能单独证明运行态 API 行为。
|
||
- 当前环境默认 `python3` 导入标准库会卡住；后续复跑 scanner 建议显式使用可工作的 Homebrew Python 3.12 临时 venv，或先修复默认 Python 运行时。
|
||
- 当前环境 Flyway PostgreSQL transactional advisory lock 会卡住；后续复跑 `P1rMarketFlywayMigrationIT` 建议带 `-Dflyway.postgresql.transactional.lock=false`。
|
||
- `P1rMarketFlywayMigrationIT` 会通过 `System.setProperty` 把 `p1r.flyway.url` 和 `p1r.flyway.user` 改成脱敏值；这是为了减少 Surefire XML 泄露，但仍属于 JVM 全局属性副作用。
|
||
- Surefire XML 可能包含本地绝对路径，例如 worktree 路径和 Flyway effective locations；外发测试报告前应清洗本地路径。
|
||
|
||
## 后续建议
|
||
|
||
如要把 Market 从 `needs_verification` 推进到 `completed`，需要用户单独批准，并补充真实运行态 / 端到端验收：HTTP 层真实请求、权限边界、幂等重放、失败路径、数据库落库、投影/outbox、审计日志和跨 owner 传播证据。
|
||
|
||
P1R-7 Events SSE 应另起任务，不应混入 P1R-6 Market Task 13。
|
||
|
||
## 本次改动文件
|
||
|
||
- `docs/superpowers/reports/p1r-api-coverage.json`
|
||
- `docs/superpowers/reports/p1r-api-coverage.md`
|
||
- `docs/memorys/2026-06-04-P1R6Market真实API收口.md`
|