From da18d9685e31e85d8e90146e7ac0b3dd89cdc142 Mon Sep 17 00:00:00 2001 From: Karlcarlo Date: Tue, 22 Sep 2026 11:49:06 +0800 Subject: [PATCH] =?UTF-8?q?docs(AGENTS):=20=E8=A1=A5=20=C2=A74.2=20?= =?UTF-8?q?=E2=80=94=E2=80=94=20=E6=98=BE=E5=BC=8F=E8=90=BD=E5=9C=B0?= =?UTF-8?q?=E5=90=8E=E7=82=B9=E3=80=8C=E5=B0=8F=E6=88=BF=E5=AD=90=E3=80=8D?= =?UTF-8?q?=E5=9B=9E=E9=A6=96=E9=A1=B5=E4=B8=8D=E8=83=BD=E8=A2=AB=E6=81=A2?= =?UTF-8?q?=E5=A4=8D=E9=80=BB=E8=BE=91=E5=86=8D=E9=80=81=E5=9B=9E=E5=8E=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 记录用户实测现象：扫码进应用 → 点小房子 → 被 last_app 恢复送回应用 → 左上角变成返回箭头 - 修法两层缺一不可：① App.onLaunch 按 option.path 置 restoreArmed（首页壳一次性消费）； ② 判定「不恢复」的那一轮加载（含显式落地落点、onShow 重载、retryLoad）都要带 #norestore=1 - §6 自测补「扫码入口」用例，并说明 Console 过滤 [enter-app] 可看完整判定链 --- AGENTS.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7034a0e..4fe8b39 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,7 +43,9 @@ CRMEB 商城小程序（uniapp，manifest `name=DoubaShop`），同时是**整 7. **恢复/落地统一 `navigateTo` 容器页**，并保留首页壳作为返回落点；不要直接把首页壳的 web-view src 指向第三方应用（首页壳的 `buildWebUrl` 是 **hash** 注入，会破坏自带 hash 路由的应用）。 8. **只用 `options.url` 当显式落地判据**：`options.scene` **每次冷启动都有值**（1001 最近使用 / 1007 分享 / 1011 扫码…），拿它判落地会导致恢复永远不执行。 -## 4. 踩坑：热启动 vs 冷启动（2026-09-22，付过线上代价） +## 4. 踩坑：宿主生命周期（2026-09-22，都付过线上代价） + +### 4.1 热启动 vs 冷启动 - 用户点右上角胶囊圆点「关闭」**不是销毁**，只是切后台。马上再进是**热启动**：页面栈与 web-view 都在， **只触发 `onShow`，不触发 `onLoad`**；被回收后才是冷启动。 @@ -54,6 +56,20 @@ CRMEB 商城小程序（uniapp，manifest `name=DoubaShop`），同时是**整 页面 `onShow` 里 `Date.now() - appShowAt < 2000` 视为热启动恢复 → **跳过重载**。 - 改任何 `onShow` 逻辑前，先想清楚触发来源（App 前后台切换 / 页内跳转 / 切 tab）。 +### 4.2 显式落地后点「小房子」回首页，不能被恢复逻辑再送回去 + +- 扫码（太阳码）/ 分享落地时，用户直接落在**容器页**，页面栈只有它 → 左上角是**「小房子」**，点它回小程序首页。 +- 如果这时「上次应用恢复」还生效，就会把用户又送回刚扫码的那个应用：表现为**点了小房子回不了家**， + 而且因为多push了一层容器页，左上角变成**返回箭头**，得再点一次返回才真回首页（用户实测）。 +- **修法两层，缺一不可**： + 1. **入口判定**：`App.vue onLaunch` 用 `option.path` 置 `globalData.restoreArmed` —— + 只有 `pages/index/index` / `pages/guide/index` 且无 `query.url` 才为 true；首页壳 `onLoad` 一次性消费。 + （用 path 不用时间窗：引导页可能停很久看开屏广告。） + 2. **抑制 H5 兜底**：这类「明确不恢复」的首页加载，以及显式落地/恢复后的返回落点， + `loadMamaBox(true)` / `_loadWithCachedIdentity` / `onShow` 重载 / `retryLoad` **都要带 `#norestore=1`**， + 否则 mama-box 的兜底恢复会绕开小程序判定又把用户送走。 +- 反向：小程序**尝试恢复但取数失败/超时**时**不带** `norestore`，让 mama-box 兜底重试一次。 + ## 5. 本仓库状态提醒 - ⚠️ `mixins/shareCard.js` **未被 git 跟踪**（untracked），但两个宿主页都 import 它 —— 提交时别漏，否则一旦丢工作区这份文件就没了。 @@ -62,9 +78,12 @@ CRMEB 商城小程序（uniapp，manifest `name=DoubaShop`），同时是**整 ## 6. 自测 -微信开发者工具（HBuilderX 运行到小程序）： +微信开发者工具（HBuilderX 运行到小程序）。**Console 过滤 `[enter-app]`** 可看到完整判定链 +（入口路径 / restoreArmed / last-app 请求与响应 / 是否命中 / 热启动判定 / 容器页加载与上报）： 1. **冷启动**：点「编译」→ 有 last_app 记录时应直接进上次的 H5 应用（不经过首页）。 2. **热启动**：点工具栏「切后台」再「切前台」→ 应停在原 H5，**不应重载回首页**。 -3. 无记录 / 断网冷启动 → 最多约 1.5s 后照常进首页。 -4. 授权页返回、分享卡片、商城宫格进应用各走一遍。 +3. **扫码入口**：编译模式选「通过二维码编译」（或扫太阳码）→ 进应用后点左上角「小房子」→ **应停在首页**， + 不应被送回应用、也不应出现返回箭头。 +4. 无记录 / 断网冷启动 → 最多约 1.5s 后照常进首页。 +5. 授权页返回、分享卡片、商城宫格进应用各走一遍。 接口契约与后端验证清单见 `box_app/AGENTS.md` §5、§6。