Add WeChat miniprogram web-view shell

docs/technical/WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md

@@ -0,0 +1,74 @@
+# 微信小程序 web-view 壳接入记录
+
+日期：`2026-05-03`
+
+## 1. 目标
+
+本次先用微信小程序 `web-view` 承载现有 H5，不重写 React/Vite 主前端，也不把 SpacetimeDB SDK 或业务规则搬进小程序端。
+
+当前小程序壳只承担三件事：
+
+1. 提供微信开发者工具可识别的 `miniprogram/` 工程根目录。
+2. 用一个全屏 `web-view` 打开现有 H5 入口。
+3. 给 H5 URL 附加来源标记，便于后续识别 `wechat_mini_program` 宿主。
+
+## 2. 文件入口
+
+| 文件 | 说明 |
+| --- | --- |
+| `project.config.json` | 指定 `miniprogramRoot: "miniprogram/"`。 |
+| `miniprogram/app.json` | 小程序全局配置，注册 `pages/web-view/index`。 |
+| `miniprogram/config.js` | 业务域名入口配置，需要部署时填写。 |
+| `miniprogram/pages/web-view/index.*` | 最小 web-view 页面。 |
+
+## 3. 需要手工填写的配置
+
+在 `miniprogram/config.js` 中填写：
+
+```js
+const WEB_VIEW_ENTRY_URL = 'https://你的H5业务域名/';
+```
+
+约束：
+
+1. 必须是 `https`。
+2. 不能是 `localhost` 或 IP。
+3. 域名需要在微信小程序后台配置为业务域名。
+4. H5 页面里的 API、图片、音视频、iframe 等外链也要满足微信侧域名与证书要求。
+
+`WEB_VIEW_SOURCE_QUERY` 默认附加：
+
+```text
+clientType=mini_program
+clientRuntime=wechat_mini_program
+```
+
+后续如果 H5 或 `api-server` 需要更严格地区分来源，应优先使用请求头或登录态中的客户端身份字段，不要只信任 URL query。
+
+## 4. 微信后台配置
+
+至少需要在小程序后台配置：
+
+1. `业务域名`：承载 H5 的域名。
+2. `request 合法域名`：H5 里如果仍有小程序原生层直接请求 API，才需要配置；当前 web-view 壳本身不直接请求业务 API。
+3. `socket 合法域名`：若后续小程序原生层直连 WebSocket 才需要；当前不启用。
+
+当前仓库的 H5 仍建议通过同域 `/api/*` 访问 Rust `api-server`，避免在小程序和 H5 中分别维护跨域白名单。
+
+## 5. 当前不做的事
+
+本次不做原生小程序页面迁移，原因是当前主前端依赖：
+
+1. React DOM 挂载、浏览器 history 和 `window.location`。
+2. `localStorage` / `sessionStorage`。
+3. 浏览器 `fetch` 与 `ReadableStream` SSE。
+4. DOM、Canvas、Three.js 等浏览器渲染能力。
+
+这些能力不能稳定原样运行在原生小程序宿主中。后续如要原生化，应新建小程序端宿主，复用 `packages/shared` 契约和 `api-server` BFF，而不是把 `src/` 整体搬过去。
+
+## 6. 验收口径
+
+1. 微信开发者工具打开项目根目录后，识别 `miniprogram/` 为小程序源码目录。
+2. 未填写 `WEB_VIEW_ENTRY_URL` 时，页面显示配置提示，不出现空白页。
+3. 填写已配置业务域名后，首页全屏打开 H5。
+4. H5 内登录、SSE、图片资源等能力按 H5 自身部署域名和 `/api/*` 代理链路验证。