diff --git a/docs/development/device-verification.md b/docs/development/device-verification.md new file mode 100644 index 0000000..4cac8c4 --- /dev/null +++ b/docs/development/device-verification.md @@ -0,0 +1,121 @@ +# 真机验证清单(常设) + +> **定位**:跨迭代常设文档——凡「只能在真机/模拟器上验证」的事项都登记在此,按迭代分节;每项含操作步骤、通过标准与执行记录。真机到位或发版前照单执行。 +> **维护约定**:各迭代收官时把真机专属验证项登记进来;完成后填执行记录并同步 [功能完成清单](feature-checklist.md) 对应条目状态。 +> 原位置为 iteration-2/30 号报告,2026-09-08 提升为常设文档(M3 起亦有真机项)。 + +## 通用前置准备 + +**设备**: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(指向手机自身)。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 /home/lx/workspace/patbond/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) + +_(待补)_ diff --git a/docs/development/iterations/iteration-2/30-device-verification-checklist.md b/docs/development/iterations/iteration-2/30-device-verification-checklist.md index 6dc1b2b..b397ed6 100644 --- a/docs/development/iterations/iteration-2/30-device-verification-checklist.md +++ b/docs/development/iterations/iteration-2/30-device-verification-checklist.md @@ -1,101 +1,7 @@ -# 真机补验清单(M2 挂起项) +# 30 真机补验清单(已迁移) -> **背景**: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 手测」由 🟡 改 ✅。 +本清单已于 2026-09-08 提升为**跨迭代常设文档**(M3 起也有真机验证项): -## 前置准备 +👉 **[开发文档 → 真机验证清单](../../device-verification.md)** -**设备**: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 输出摘录(脱敏)、执行人)_ +M2 挂起的两项验证(Android 事件落库、SessionTracker 30 分钟手测)的完整操作步骤、通过标准与执行记录均在新位置维护。本页仅保留编号占位,保证 iteration-2 报告序列(01~30)完整可审计。 diff --git a/mkdocs.yml b/mkdocs.yml index eeba9c0..87d892e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,6 +7,7 @@ nav: - 开发实施计划: development/development-plan.md - Git 工作流规范: development/git-workflow.md - 功能完成清单: development/feature-checklist.md + - 真机验证清单: development/device-verification.md - CI Runner 部署手册: development/ci-runner-setup.md - 第一迭代: - 进展看板: development/iterations/iteration-1/index.md