patbond-doc/docs/development/iterations/iteration-3/04-reality-check.md

04 · M3 开工前现实核查（Reality Check）

• 核查人：Reality Checker（TestingRealityChecker）
• 日期：2026-09-08
• 方法：延续 iteration-2/04 的标准——不采信任何书面转述。所有结论分档标注：【亲验】命令自己跑、输出自己看；【UNVERIFIED】本地无法复现、明确不采信
• 约束遵守：只读核查 + 运行测试/构建/API 查询/E2E 脚本；零代码改动、零 commit/push、未改 mkdocs.yml；compose 用后已 down

---

0. 裁定（先说结论）

M3 开工 readiness：CERTIFIED（无条件放行）。

这是本核查人首次给出 CERTIFIED，理由是证据构成与 M2 开工时有质的不同：M2 收官声称的每一个关键数字都由本人在 2026-09-08 当天重新实跑并逐一命中——后端 191/191、前端 272/272 + analyze 零问题、mkdocs strict 通过、契约快照 sha256 字节级一致、三仓 HEAD CI 经 Gitea API 亲查全 success、E2E 烟囱 11/11 本人从冷启动完整复跑一遍通过（这同时证明 M3 开工时后端 compose 通道是活的，不是「2026-09-08 时点的历史记录」）。七项核查零实质偏差；上一轮（iteration-2/04）的 5 条放行条件全部消解。

M2 的已知挂起项（真机两项、auth 域契约测试缺口等）均已在文档中诚实标注为 🟡/另立工单，不构成对 M3（社区域）开工的阻塞，列为第 §5 节「随行观察项」而非放行条件。

---

1. 三仓 Git 状态与远端同步 —【亲验，全部通过】

git status --short --branch + git fetch + git rev-parse HEAD origin/<branch> 逐仓实测（2026-09-08）：

仓库	分支	工作树	本地 HEAD	远端 HEAD	一致
patbond-api	dev	干净	64c9b72	64c9b72	✓
patbond-flutter	dev	干净	720865b	720865b	✓
patbond-doc	main	干净	e68b655	e68b655	✓

与收官声称的 api dev@64c9b72、flutter dev@720865b 完全一致。上一轮放行条件 1（doc 仓不干净、报告长期不 commit）已消解：本次 doc 仓干净且与远端同步，iteration-2 全部 30 份报告 + 索引已入库。

环境事实：工作区存在 patbond-doc 的两个克隆（patbond-doc 主克隆与本核查所在的 referral 克隆，origin 均指向 zhaoyuxi/patbond-doc.git），两者均干净、HEAD 同为 e68b655，不构成风险，但建议后续收敛为单一工作副本以免改错目录。

核查结束时复查：四个工作树（含 referral）git status --porcelain 均为 0 处未提交——本核查自身未污染任何仓库（mvn target/、site/ 均被 gitignore 覆盖）。

2. 双端测试基线实跑 —【亲验，数字逐一命中】

2.1 后端 191/191

命令：JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./mvnw clean test（patbond-api，本人实跑，BUILD SUCCESS，1 分 37 秒）。

surefire 报告逐文件解析汇总（不抄 Maven 控制台，直接数 XML）：

模块	tests	failures	errors	skipped
patbond-common	3	0	0	0
patbond-user	68	0	0	0
patbond-auth	31	0	0	0
patbond-pet	89	0	0	0
合计	191	0	0	0

与声称的 191 精确一致。Testcontainers 正常（postgres:18 容器起落、4 个 Flyway 迁移在干净实例全量执行成功）。

小观察（非缺陷）：Flyway 提示 PostgreSQL 18.6 is newer than this version of Flyway... latest supported is 17——当前仅为警告且全部迁移执行成功，M3 若升级 Flyway 版本可顺手消除。

2.2 前端 272/272 + analyze 零问题

命令：flutter test（patbond-flutter，本人实跑）：00:32 +272: All tests passed!。 命令：flutter analyze：No issues found! (ran in 1.9s)。均与声称一致。

3. 文档门禁与契约快照 —【亲验，字节级一致】

• mkdocs build --strict：通过（3.51s，EXIT=0）。
• 契约快照 sha256 比对：

243fe6487bfa19018bddbfdb2cece16d9f81bc9718d3404501574677a4cd689d  patbond-api/patbond-pet/src/test/resources/contract/openapi-v1.2.0.yaml
243fe6487bfa19018bddbfdb2cece16d9f81bc9718d3404501574677a4cd689d  patbond-doc/docs/api/openapi.yaml

字节级一致属实。正典 info.version: 1.2.0、路径数 grep 实数 18，与声称一致。上一轮的 D-1 缺口（events 端点游离于契约外）已不复存在——v1.2.0 含 /api/v1/events。

4. 三仓 HEAD 的 CI 状态 —【亲验，Gitea API 亲查】

curl https://git.patbond.cn/api/v1/repos/zhaoyuxi/<repo>/commits/<sha>/status（2026-09-08）：

仓库	commit	state	检查项
patbond-api	64c9b72f…	success	CI / backend-test
patbond-flutter	720865bc…	success	CI / flutter-gates
patbond-doc	e68b6553…	success	CI / docs-build

29 号报告写 flutter 侧「待本提交 CI」——该悬置项现已落定为 success。

5. E2E 烟囱复跑 —【亲验，11/11 全过，通道确认存活】

完整冷启动复跑（非采信 2026-09-08 收官记录）：

1. ./mvnw -DskipTests package（EXIT=0）→ docker compose up -d --build → 四容器 Up、postgres healthy；
2. dart run test_e2e_m2_manual.dart（patbond-flutter 仓根）：=== M2 E2E 烟囱测试全部通过 ✓（11/11 场景）===，EXIT=0；
3. docker compose down 已执行，栈已清理。

11 场景全部真实走通，抽样摘录（本人输出）：场景 8 防枚举四路响应体完全一致（40401）；场景 9 第二设备新会话五类数据全量读回；场景 10 v2 事件 4/4 accepted（202，含 platform=android）；场景 11 乐观锁 409/40902 且先写者数据保留。

这条同时回答了 M3 开工的关键问题：后端 compose 通道今天是活的。 上一轮放行条件 3（E2E 通道 UNVERIFIED）消解。

6. 收官声称抽查（3+ 条高影响项）

6.1 契约测试确实会抓漂移 —【亲验（结构审读 + 实跑）】

审读 patbond-pet/src/test/java/.../contract/ContractConformanceTest.java（735 行），结构真实严格，不是摆设：

• 对 pets 域 18 操作真实起服务发请求（MockMvc + Testcontainers），响应体经 ContractValidator 对冻结快照严格校验（字段名/类型/必填/nullable/枚举/信封/错误码值）；
• Order(98) 快照守卫：断言版本=1.2.0、18 路径、24 操作、45 schema——doc 仓升版而忘同步快照会立即变红；
• Order(99) 全响应矩阵门禁：契约声明的每个 (操作, 状态码) 单元格都必须被真实响应覆盖，唯一豁免 care-reminders PATCH 409（并发守卫，单线程无法确定性触发，已注释说明）；
• 本次实跑中该测试类 11/11 通过（含在 191 内）。

诚实标注的已知边界：auth 域 6 个 M1 操作无契约测试（注释明言「另立工单」），见 §7 观察项。

6.2 pet_health schema 表数 —【亲验，8 表属实】

V3__pet_health_baseline.sql grep 实数 8 个 CREATE TABLE：breeds、pets、pet_owners、pet_weight_records、vaccine_catalog、pet_vaccinations、health_events、care_reminders——与 29 号报告「pet_health 8 表」一致（其「六表 psql 证据」指业务数据六表，不含 breeds/vaccine_catalog 字典表，无矛盾）。

6.3 feature-checklist 与实际相符 —【亲验】

docs/development/feature-checklist.md 实有 M2 三节（§7 宠物域后端 / §8 宠物域客户端 / §9 埋点体系）。关键的是它没有虚报：真机落库验证 + SessionTracker 手测标 🟡 挂起、integration_test 自动化标 🟡 留第四波、三项交互细节标 🟡 待拍板——与 30 号真机补验清单相互印证，状态标注诚实。

6.4 报告与 ADR 入档 —【亲验】

iteration-2/ 实有 01~30 共 30 份编号报告 + index.md + openapi-pets-draft.yaml，mkdocs strict 通过即导航无死链；docs/architecture/decisions.md 实有 ADR-001 至 ADR-015。与声称一致。

7. 随行观察项（非放行条件，不阻塞 M3 开工）

1. 真机两项挂起（Android 真机落库验证 + SessionTracker 30min 手测，30 号清单）——按方案 A 挂起属既定决策，设备到位后 0.5 天补验；M3 若涉及移动端埋点新事件，建议合并补验。
2. auth 域 6 操作无契约测试——M1 遗留、已声明另立工单；M3 新增社区域端点时应从第一天就纳入契约测试矩阵，勿再累积。
3. Flyway 对 PostgreSQL 18.6 的版本警告（§2.1）——顺手升级可消除。
4. doc 仓双克隆（§1）——建议收敛为单一工作副本。

8. 与上一轮（iteration-2/04）放行条件的对账

上轮放行条件	本次状态
1. doc 仓报告未提交/工作树不干净	✓ 消解：30 份报告入库，三仓干净同步
2. D-1 契约缺口（events 游离）	✓ 消解：v1.2.0 含 events，18 路径，字节级快照锁 CI
3. E2E 通道 UNVERIFIED	✓ 消解：本人冷启动复跑 11/11
4/5.（埋点空转与相关接线）	✓ 消解：E2E 场景 10 实证 4/4 accepted；v2 白名单已入 191 测试基线

---

结论：M2 收官声称经全量独立复验零实质偏差，M3（社区域）可以开工。 本报告全部数字均为核查人 2026-09-08 亲跑所得。