# 真机验证清单（常设）

> **定位**：跨迭代常设文档——凡「只能在真机/模拟器上验证」的事项都登记在此，按迭代分节；每项含操作步骤、通过标准与执行记录。真机到位或发版前照单执行。
> **维护约定**：各迭代收官时把真机专属验证项登记进来；完成后填执行记录并同步 [功能完成清单](feature-checklist.md) 对应条目状态。
> 原位置为 iteration-2/30 号报告，2026-09-08 提升为常设文档（M3 起亦有真机项）。

## 通用前置准备

**设备**：Android 真机（推荐）或 Android 模拟器。桌面/Web 不可用——没有真实的移动端后台生命周期（`paused` 不触发），且 platform 值不在契约枚举内会被服务端整批拒绝。

**后端**（工作机上，进入你本地检出的 patbond-api 仓库目录执行）：

```bash
cd <你的工作区>/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（指向手机自身）。M3 起若新增服务端口（如 community :8084），相应补 `PATBOND_COMMUNITY_API_BASE_URL`。

---

# M2 挂起项（2026-09-08 登记，待执行）

> 来源：报告 iteration-2/10 §2.1（验收 6）与 iteration-2/12 §3.2；方案 A 挂起决议见 iteration-2/29 §4。
> **时限提醒**（iteration-3/06）：建议在 **2026-09-21（北极星首次出数日）前完成**，否则首批读数只能标「未验收」。

## 验证一：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 <你的工作区>/patbond-api && docker compose down
# 测试数据不入库（协作规则 3）：本清单产生的数据都在 compose 卷里，
# 需要干净环境时 docker compose down -v 清卷即可
```

两项都过后：填写下方执行记录 + [功能完成清单](feature-checklist.md) 第 9 节「Android 真机落库验证 + SessionTracker 30min 手测」由 🟡 改 ✅。若有任何一项不过，按惯例开缺陷单修复后复测。

### M2 项执行记录

_（待真机到位后填写：日期、设备型号/Android 版本、两项结果、psql 输出摘录（脱敏）、执行人）_

---

# M3 预登记（社区，随迭代交付补全）

以下为 M3 交付过程中预计产生的真机专属验证项，**各工单收口时在此补全具体步骤与通过标准**：

1. **媒体上传弱网表现**：真机蜂窝/弱 Wi-Fi 下选图→压缩→预签名直传→确认全链路；中断重试不产生孤儿 asset（对应 T3-13 验收的真机侧）。
2. **乐观更新真机手感**：点赞/收藏快速连点的防抖与回滚动画在真机帧率下的表现（对应 T3-15/16）。
3. **Feed 图片加载**：真机上滚动 Feed 的图片加载/缓存/占位表现；MinIO 经局域网/公网访问 URL 的可达性差异。
4. **社区事件落库**：community 域 v3 事件（platform=android）落库观察（沿 M2 验证一的方法，事件名换 v3 增量）。

## 执行记录（M3）

_（待补）_