docs: 真机补验独立操作清单（30 号，M2 挂起项）

两项验证（Android 事件落库 + SessionTracker 30min 换会话）的完整操作步骤：
compose 起后端、三 base URL dart-define、逐步通过标准、psql 查证 SQL
（列名按 V2 实际 schema 核对为 client_ts）、巡检兜底、收尾清卷；
末尾留执行记录节，完成后同步 feature-checklist 第 9 节状态。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/development/iterations/iteration-2/30-device-verification-checklist.md

@@ -0,0 +1,101 @@
+# 真机补验清单（M2 挂起项）
+
+> **背景**：M2 收官时无 Android 真机/模拟器，按方案 A 挂起两项真机专属验证（不阻塞迭代，见报告 29 §4）。本页是独立操作清单——真机到位后照此执行，预计 **0.5 天内完成**。
+> **来源**：验证项定义在报告 10 §2.1（验收 6）与报告 12 §3.2；埋点验收标准与巡检 SQL 在报告 06 §5.1。
+> 完成后：把执行记录追加到本页末尾「执行记录」节，两项都过即可在 [功能完成清单](../../feature-checklist.md) 第 9 节将「Android 真机落库验证 + SessionTracker 30min 手测」由 🟡 改 ✅。
+
+## 前置准备
+
+**设备**：Android 真机（推荐）或 Android 模拟器。桌面/Web 不可用——没有真实的移动端后台生命周期（`paused` 不触发），且 platform 值不在契约枚举内会被服务端整批拒绝。
+
+**后端**（工作机上执行）：
+
+```bash
+cd /home/lx/workspace/patbond/patbond-api
+JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./mvnw -DskipTests package
+docker compose up -d --build
+docker compose ps   # 四容器 Up，postgres healthy
+```
+
+**装机运行**（patbond-flutter 目录）：
+
+```bash
+# 模拟器：宿主机地址用 10.0.2.2
+flutter run -d <设备ID> \
+  --dart-define=PATBOND_API_BASE_URL=http://10.0.2.2:8081 \
+  --dart-define=PATBOND_USER_API_BASE_URL=http://10.0.2.2:8082 \
+  --dart-define=PATBOND_PET_API_BASE_URL=http://10.0.2.2:8083
+
+# 真机：换成工作机局域网 IP（真机与工作机须同一网络）
+#   --dart-define=PATBOND_API_BASE_URL=http://<局域网IP>:8081  （其余两个同理）
+```
+
+> 注意：三个 base URL 都要传，漏传的会落到默认 127.0.0.1（指向手机自身）。
+
+## 验证一：Android 事件真实落库（~10 分钟）
+
+**目的**：确认埋点链路在真实移动端（platform=android）端到端落库——桌面端已验证全链路仅差 platform 枚举这一步。
+
+**步骤**：
+1. app 内注册新账号（用户名任意、手机号 11 位、密码 ≥8 位含字母数字），登录进入主页
+2. 操作产生事件：切几个 Tab、建一只宠物档案、记一条体重
+3. **把 app 退到后台**（Home 键，触发离开前台冲刷）,等 5 秒
+4. 工作机查库：
+
+```bash
+docker exec patbond-postgres-1 psql -U patbond -d patbond -c \
+  "SELECT event_name, platform, session_id, client_ts
+   FROM platform.product_events ORDER BY client_ts DESC LIMIT 20;"
+```
+
+**通过标准**：
+- [ ] 有行返回，`platform` 列为 `android`
+- [ ] 事件覆盖 ≥3 类（如 page_viewed、pet_create_started/succeeded、health_record_create_succeeded）
+- [ ] 本轮所有事件共享同一个 `session_id`（UUIDv7 格式）
+
+## 验证二：SessionTracker 30 分钟后台换会话（~45 分钟，含等待）
+
+**目的**：验证 10 号报告 §2.1 验收 6——退后台超 30 分钟回前台应更换 sessionId，不超过则沿用。
+
+**步骤**（接验证一，同一次登录、不杀进程）：
+1. 回前台随便操作一下（记一条体重）
+2. **退后台等 5 分钟** → 回前台操作（再记一条体重或切 Tab）
+3. **退后台等 35 分钟** → 回前台操作一次
+4. 再退一次后台（触发冲刷），等 5 秒后查库：
+
+```bash
+docker exec patbond-postgres-1 psql -U patbond -d patbond -c \
+  "SELECT DISTINCT session_id, min(client_ts) AS first_seen
+   FROM platform.product_events
+   WHERE user_id = (SELECT id FROM identity.users WHERE username = '<你的测试用户名>')
+   GROUP BY session_id ORDER BY first_seen;"
+```
+
+**通过标准**：
+- [ ] 恰好 **2 个** session_id（第 2 步的 5 分钟不换会话、第 3 步的 35 分钟换新）
+- [ ] 两个会话的 first_seen 时间差 ≈ 40 分钟（与操作节奏吻合）
+
+**巡检 SQL 兜底**（06 号 §5.1 口径，防「每事件一个 sessionId」缺陷复发）：
+
+```bash
+docker exec patbond-postgres-1 psql -U patbond -d patbond -c \
+  "SELECT count(DISTINCT session_id)::float / count(*) AS ratio
+   FROM platform.product_events;"
+# ratio 应远小于 0.9；> 0.9 说明 sessionId 生成有问题，告警
+```
+
+## 收尾
+
+```bash
+cd /home/lx/workspace/patbond/patbond-api && docker compose down
+# 测试数据不入库（协作规则 3）：本清单产生的数据都在 compose 卷里，
+# 需要干净环境时 docker compose down -v 清卷即可
+```
+
+两项都过后：更新本页执行记录 + feature-checklist 第 9 节状态，M2 挂起项即全部闭环。若有任何一项不过，按第一迭代惯例开缺陷单修复后复测。
+
+---
+
+## 执行记录
+
+_（待真机到位后填写：日期、设备型号/Android 版本、两项结果、psql 输出摘录（脱敏）、执行人）_

mkdocs.yml

@@ -61,6 +61,7 @@ nav:
           - 27 第三波收口: development/iterations/iteration-2/27-wave3-closure.md
           - 28 E2E 烟囱收官: development/iterations/iteration-2/28-e2e-smoke-report.md
           - 29 M2 收官总结: development/iterations/iteration-2/29-m2-summary.md
+          - 30 真机补验清单: development/iterations/iteration-2/30-device-verification-checklist.md
   - API:
       - 契约说明: api/index.md
   - 架构: