diff --git a/docs/development/iterations/iteration-2/30-device-verification-checklist.md b/docs/development/iterations/iteration-2/30-device-verification-checklist.md new file mode 100644 index 0000000..6dc1b2b --- /dev/null +++ b/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 输出摘录(脱敏)、执行人)_ diff --git a/mkdocs.yml b/mkdocs.yml index 4c5406c..26bdc44 100644 --- a/mkdocs.yml +++ b/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 - 架构: