feat: add wechat miniprogram webview login

docs/technical/WECHAT_LOGIN_REAL_INTEGRATION_RUNBOOK_2026-04-21.md

@@ -100,6 +100,9 @@ real 模式行为固定为：
 | `WECHAT_AUTHORIZE_ENDPOINT` | 否 | 默认桌面二维码授权地址 |
 | `WECHAT_ACCESS_TOKEN_ENDPOINT` | 否 | 默认 access_token 接口 |
 | `WECHAT_USER_INFO_ENDPOINT` | 否 | 默认用户信息接口 |
+| `WECHAT_JS_CODE_SESSION_ENDPOINT` | 否 | 默认小程序 `jscode2session` 接口 |
+| `WECHAT_MINI_PROGRAM_APP_ID` | 小程序 `real` 模式必填 | 微信小程序 AppID；不填时回退 `WECHAT_APP_ID` |
+| `WECHAT_MINI_PROGRAM_APP_SECRET` | 小程序 `real` 模式必填 | 微信小程序 AppSecret；不填时回退 `WECHAT_APP_SECRET` |
 | `WECHAT_STATE_TTL_MINUTES` | 否 | state 有效期，默认 `15` 分钟 |
 
 补充说明：
@@ -225,7 +228,46 @@ https://game.example.com
    - `wechatBound = true`
    - `bindingStatus` 已更新为目标状态
 
-## 8. 账号命中规则
+## 8. 小程序 web-view 登录联调步骤
+
+小程序壳走原生 `wx.login`，不走网页 OAuth callback。联调前需要额外确认：
+
+```bash
+WECHAT_AUTH_ENABLED=true
+WECHAT_AUTH_PROVIDER=real
+WECHAT_MINI_PROGRAM_APP_ID="你的微信小程序 AppID"
+WECHAT_MINI_PROGRAM_APP_SECRET="你的微信小程序 AppSecret"
+```
+
+在 `miniprogram/config.js` 中确认：
+
+```js
+const WEB_VIEW_ENTRY_URL = 'https://你的H5业务域名/';
+const API_BASE_URL = 'https://你的服务器域名/';
+const MINI_PROGRAM_APP_ID = '你的微信小程序 AppID';
+```
+
+联调流程：
+
+1. 微信开发者工具打开项目根目录。
+2. 小程序启动后调用 `wx.login`。
+3. 小程序壳请求：
+
+```http
+POST /api/auth/wechat/miniprogram-login
+```
+
+4. 后端通过 `jscode2session` 兑换 `openid/unionid`。
+5. 后端返回系统 `token`、`bindingStatus` 与 `user`。
+6. 小程序壳打开 H5，并在 hash 中附加：
+   - `auth_provider=wechat`
+   - `auth_token=...`
+   - `auth_binding_status=active|pending_bind_phone`
+7. H5 消费 hash 后通过 `/api/auth/me` 恢复登录态。
+
+这里不能把裸 `openid` 作为 web-view query 登录凭证；`openid` 只能留在后端身份绑定层，H5 只消费本系统 JWT。
+
+## 9. 账号命中规则
 
 当前实现固定按以下顺序命中已有账号：
 
@@ -238,7 +280,7 @@ https://game.example.com
 1. 若按 `unionid` 命中了已有微信身份，但本次微信回调带来了新的 `openid`，后端会把新的 `openid -> user_id` 映射补齐
 2. 若后续绑定手机号时发现该手机号已经属于正式账号，则会把微信身份并入这个正式账号
 
-## 9. 前端验收点
+## 10. 前端验收点
 
 前端联调时至少检查以下行为：