# AGENTS.md · mama-box（兜爸心选 H5）

> 在本仓库工作前先读。**跨仓库的权威约定在 `box_app/AGENTS.md`**（`/home/jone/workspace/box_app/AGENTS.md`）——
> 三仓布局、身份契约、接口命名、部署与踩坑总表都在那里；本文件只写本仓库特有的部分。

---

## 1. 这是什么

微信小程序里的**首页 H5**：小程序首页壳（`crmeb/pages/index/index.vue`）用 web-view 硬编码加载
`https://mp.yizhezhe.com/mama-box/`，用户看到的就是本站。它同时是 **H5 应用宫格**入口（30+ 第三方应用的门面）。

- 纯静态站点：**无框架、无构建、无测试**，`index.html` 一个页面用 `.screen` 切换多个屏。
- 仓库 `jone/mama-box`；本地 `/home/jone/workspace/mama-box`；生产 `/opt/app/mama-box`（nginx alias 托管，非 box_app 挂载）。
- 原型参考（只读，别当改动目标）：`/home/jone/workspace/dailiang-app-03`。

## 2. 文件地图

| 文件 | 作用 |
| --- | --- |
| `index.html` | 单页多屏的全部结构 + 样式引用/脚本引用（1550+ 行） |
| `js/app.js` | **全部业务逻辑**（3000+ 行）：屏切换、远程数据、宫格、授权、跳转、last_app |
| `js/wx-auth.js` | **共享助手，别的 H5 应用也引用它**：环境判定 / 读授权结果 / `requestProfile` / `goMall` / `reportLocation`。改动等于改所有接入方，务必保守 |
| `mama-box.css` | 样式 |
| `assets/` | 图片/资源 |
| `js/core.js` | ⚠️ **本仓库内已无任何引用**（MPA 原型带过来的遗留）。新代码不要基于它，改前先确认没有隐藏引用 |

## 3. 发布

```bash
git push origin main                      # 完成后在服务器：
cd /opt/app/mama-box && git fetch && git reset --hard origin/main    # 静态站，无需重启
```

nginx：`root /opt/app` + `Cache-Control: no-cache` + `etag on` —— 缓存靠 ETag，所以**改完必须 bump 版本号**。

**版本号规则（必做）**：改了 `js/*.js` 或 `mama-box.css` 时，两处同步 bump，且 commit message 带版本：
- `index.html` 顶部 `<!-- V:YYMMDDNN 缓存版本标记… -->`
- `js/app.js` 顶部 `var VER = 'YYMMDDNN';`

`YYMMDD` = 当天日期，`NN` = 当日两位序号（从 `01` 起）。例：`v26092202`。

## 4. 硬约定

1. **身份只从 URL 读**：宿主把 `#openid=…&unionid=…` 注入进来，用 `hashParam(name)` 读
   （它同时读 hash 与 query，并会剥掉历史 bug 粘上的 `?t=`）。`openid` 是唯一身份键。
2. **拿不到 openid 就显示提示条**（`showIdNotice`），**不要造假数据**：宿主拿不到身份时不会加载本页；
   真出现空身份要让人一眼看出来，而不是显示 `--`/演示值。
3. **跳其它 H5 应用一律走 `jumpApp(url, identifier)`**（或档案页的 `goArchiveH5()`）：它负责
   带身份（query）、上报分享地址、上报 last_app，再 `location.href`。**禁止裸 `location.href` 跳应用**。
4. **不要在本仓库写死应用名单**：能不能出现、叫什么、链接是什么，全部由 box_app 后台 App 表决定
   （`/api/mp/apps?isPublished=1`）。要下架某应用去后台下架，别在前端加过滤（历史教训：`wx-h5-demo` 过滤已按要求移除，别加回来）。
5. **授权走 `wxAuth.requestProfile()`**：它用 `wx.miniProgram.navigateTo` 跳小程序独立授权页并带 `backUrl`；
   结果由宿主写回 URL 的 **hash**。**不要用 postMessage 做授权请求**（延迟批量投递，点了没反应）。
6. **分享位置上报 `reportHostLocation()`**：postMessage 非实时（微信攒到后退/销毁/分享才派发），
   所以要在**换页/跳转前**主动上报目标地址，宿主的分享卡片才能在分享那一刻拿到正确地址。
7. **换应用前上报 last_app**（`reportLastApp()`，`navigator.sendBeacon`）：这是「退出小程序再进能回到上次应用」的
   数据来源，新增任何跳应用的入口都要走 `jumpApp()` 以继承这个行为。

## 5. 踩坑

- **不要给别的应用追加 `#openid`**：部分应用自带 hash 路由（如 `/baobao-yingji`），追加 hash 会被当非法路由 → 页面未找到。身份一律走 query（`withIdentity()` 已封装）。
- **`bustReload` 重载必须把 hash 拼回去**，否则丢身份、误报「未获取到微信身份」（v26092009 修过）。
- **首屏渲染与异步数据的竞态**：`init()` 负责渲染，远程档案在 `init()` **末尾**才拉（先拉会被 init 覆盖）。新增远程数据请照这个顺序。
- **`resumeLastApp()` 是兜底，不是主恢复**：主恢复在小程序首页壳（冷启动自己读 last-app 直接进容器页）。
  本页只在「首页壳取数失败回落加载」或「浏览器直访」时恢复；被宿主加了 `#norestore=1` 时必须**既不跳、也用
  sessionStorage 闸门占住**（否则宿主 `?t=` 重载会把返回落点也换成目标应用，back 回不到首页）。
- **改 `js/wx-auth.js` 等于改全生态**：它是所有接入 H5 应用共用的授权助手，先看 `docs/h5-auth-standard.md` 的协议再动。

## 6. 自测

无构建、无自动化测试。改完：
```bash
node --check js/app.js          # 语法
```
真机/微信开发者工具里走一遍：身份注入是否正常、宫格跳应用是否带身份、分享卡片地址、授权回填、
退出小程序再进是否能回到上次应用。相关接口契约与验证清单见 `box_app/AGENTS.md` §6。