登录中转
整条链路只有两个接口：一个给浏览器、一个给站点服务端。
时序
用户（微信内） 站点 中台 微信
│ 点击"微信登录" ──────────▶│ │ │
│ │ 跳到 /oauth/entry ─────▶│ 302 authorize ──────▶│
│◀──────────── 授权确认页 ───────────────────────────────────────────────────│
│ 回调 /oauth/callback ◀─────────────────────────────│◀── code ──────────────│
│ │ code → openid │ │
│ │ 身份落库、发票据 │ │
│◀── 302 return?hub_ticket=xxx ─────────────────────│ │
│ │◀─ POST identity/exchange ─│ │
│ │ → openid/unionid/昵称 │ │
│ │ 建自己的会话（站点负责） │ │1. 浏览器入口 GET /oauth/entry
| 参数 | 必填 | 说明 |
|---|---|---|
| site | 是 | 站点短码 |
| scope | 否 | snsapi_base（默认，静默）| snsapi_userinfo（弹确认页，能拿昵称头像） |
| return | 否 | 相对路径或 https 绝对地址；绝对地址必须命中站点的允许回跳域名 |
| force | 否 | 1 = 即使在非微信浏览器也继续跳转（默认给提示页，避免微信的报错页吓到用户） |
2. 服务端兑换 POST /api/v1/identity/exchange
{ "ticket": "从 hub_ticket 参数拿到的值" }成功返回：
{
"ok": true,
"data": {
"identity_id": 1234,
"openid": "oXXXX…", // 属于本站点所用微信账号的 openid
"unionid": "uXXXX…" 或 "", // 账号绑定开放平台后才有；空值不是错误
"unionid_available": true,
"nickname": "张三", // 只有 snsapi_userinfo 才有
"avatar": "https://…",
"is_followed": true, // 是否已关注该服务号（轮询同步，有分钟级延迟）
"scope": "snsapi_userinfo",
"site_key": "vip",
"exchanged_at": 1760000000
}
}
票据只能用一次，60 秒过期，且绑定发起的站点。重复兑换返回
ticket_used，
超时返回 ticket_expired，跨站点使用返回 ticket_site。
3. 反查身份 POST /api/v1/identity/lookup
{ "openid": "oXXXX…" } // 或 { "unionid": "uXXXX…", "event_key": "remind" }返回同上的身份字段 + subscribe_quota（该事件在各订阅模板下的剩余额度）。
只能查本站点所用账号下的身份，跨账号查不到 —— 避免站点之间互相摸用户。
站点侧要怎么存
- 用户表的唯一键建议用 unionid（有则优先）或 openid；不要拿昵称当标识。
- 中台不存站点的业务账号，也不发会话 Cookie —— 登录态由站点自己建。
- 如果暂时拿不到 unionid（账号未绑开放平台），先按 openid 建账号；将来绑定后中台会开始返回 unionid， 届时用「同一 openid 补齐 unionid」的方式合并即可，不影响已建账号。
常见错误
| 现象 / code | 原因与处理 |
|---|---|
微信页面报 redirect_uri 域名与后台配置不一致 (10003) |
mp 后台的网页授权域名不是 wx.onzx.cn，或改了还没生效。名额只有 2 个、每月限改 5 次，先确认再动手 |
return_not_allowed | 回跳域名不在站点白名单里 —— 在「接入站点」里加上该 host，或改传相对路径 |
ticket_expired 频繁出现 | 站点页面里有慢逻辑（比如在回调页做了大查询）；兑换应作为跳转后的第一件事 |
| 昵称一直是空 | 用的是 snsapi_base。要昵称必须用 snsapi_userinfo（会弹确认页） |
profile_incomplete | 中台侧该微信账号没配 AppID/AppSecret，或 IP 白名单没加 |
PC 端与站外
网页授权只在微信内置浏览器里有效。PC 上的"微信扫码登录"是另一条链路：
需要在微信开放平台注册「网站应用」（需企业资质认证），中台已预留账号类型 website，
接入时只需在后台添加该应用并加一个扫码入口。当前版本未开放该接口 —— 需要时告诉我，加一个
/oauth/webqrcode 流程即可。
本页内容随代码一起版本化（V0.1.0）。发现文档与实际行为不一致，请当缺陷报告。