# cps_wx_user — CPS 落地页微信用户身份(openid 维度)

> 模型 `app/models/cps_wx_user.py`(`CpsWxUser`) · 仓库 `app/repositories/cps_wx_user.py`(`get_by_openid` / `upsert`) · 接口 `GET /wx/oauth/cb`(微信网页授权回调,`app/api/v1/cps_redirect.py`) · [← 索引](./README.md) · [总览](./OVERVIEW.md)

用户在微信内打开群发短链落地页 [`/c/{code}`](./cps_link.md),经服务号网页授权拿到的微信身份,按 `openid` 唯一存一行。在 CPS 群发漏斗里,它给点击/领券补上**「是谁」**这一维度(此前 [`cps_click`](./cps_click.md) 只有 PV/UV 近似)。授权分两阶:`snsapi_base` 静默拿 `openid`(统计主力);用户点「领券」触发 `snsapi_userinfo` 才补 `nickname`/`headimgurl`/`unionid`。

> 注意:**下单归因到人**需 user-level sid(另一期),本表只承载身份 + 领券/点击侧,**不与 `cps_order` 关联**。

## 用在哪 / 增删改查
- **C / U(upsert)**:`upsert`(`get_by_openid` 查 → 无则建、有则补),由 `wx_oauth_cb`(`GET /wx/oauth/cb`)在微信授权回调里调。首次建行记来源 `first_code`/`first_group_id`;已存在则**仅在传入非 None 时**更新 `nickname`/`headimgurl`/`unionid`(`base` 阶段为 None,不覆盖已有画像),并显式刷新 `last_seen`(`onupdate` 仅字段有变更才触发,故 base-only 回访也要手动 set)。任何授权失败兜底回落地页,**绝不阻断领券**。
- **R**:`get_by_openid`(upsert 内部按 openid 查)。
- **D**:无。

## 字段
| 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
|---|---|---|---|
| `id` | Integer | PK, autoincrement | |
| `openid` | String(64) | **UNIQUE**, index, NOT NULL | 服务号下用户唯一标识(网页授权拿到);upsert 主键 |
| `unionid` | String(64) | index, nullable | 开放平台 unionid(服务号绑开放平台 + `scope=userinfo` 才有);跨 App/服务号统一用户 |
| `nickname` | String(128) | nullable | 昵称;`userinfo` 授权后才有(base 阶段为空) |
| `headimgurl` | String(512) | nullable | 头像 URL;同 `nickname`,userinfo 阶段才有 |
| `first_code` | String(16) | nullable | 首次进入来源短链 code(从哪个群的链接授权进来) |
| `first_group_id` | Integer | index, nullable | 首次来源群 = `cps_group.id`(语义关联,非 FK);群内用户级统计用 |
| `first_seen` | DateTime(tz) | server_default now() | 首次授权时间 |
| `last_seen` | DateTime(tz) | server_default now(), onupdate now() | 最近一次落地(upsert 时显式刷新) |

## 关系 / Join Key
- `first_group_id` → `cps_group.id`(**语义关联,无 ForeignKey**;记首次来源群)。
- 与 [`cps_click`](./cps_click.md) **无 id 级 join**:点击事件流目前不回写 openid 维度的用户统计,两者各按各的维度看(cps_click 看 PV/UV,本表看「谁」)。
- 与本 App `user` 表**无关**:微信落地页用户不是本 App 注册用户(同 CPS 其它表)。

## 索引与约束
- PK `id`;UNIQUE index `openid`;index `unionid`、`first_group_id`。

## 注意
- **两阶授权**:`base`(静默)只能拿 `openid`,不弹窗、不打扰,用作统计主力;`userinfo`(弹授权页)拿昵称头像 + unionid,只在用户点「领券」这种有交互的时刻触发(避免微信快照页),授权回流带 `?authed=1` 自动衔接复制口令。详见 `cps_redirect.py` 落地页逻辑。
- **`unionid` 不一定有**:需服务号已绑微信开放平台 + 走到 `userinfo` 授权;base 阶段、未绑开放平台时为 None。