feat(auth): 微信登录与手机号绑定 / 占用冲突处理(M2 + M3 §10) #139

2026-07-16T15:31:03+08:00

guke commented

2026-07-16 15:31:03 +08:00

背景 / 需求

新增「微信登录」链路:用户用微信授权登录 App。openid 已绑账号即直接登入;
未绑则走「绑手机号」建号,并处理「手机号已被别的账号占用」的冲突(M2),
以及绑微信后展示昵称/头像的替换策略(M3 §10)。

关键取舍:微信登录不套用钱包提现里 bind-wechat 的「撞号即 409」逻辑
——登录场景 openid 命中就应登入,不能因撞号把用户挡在门外。

改动概览:新增 5 个端点(前缀 `/api/v1/auth`)

方法	路径	作用
POST	`/wechat-login`	code→openid。命中已绑用户→直接登入;未命中→签发 `bind_ticket`,返回 `need_bind_phone`(此刻不建号);未配 APP_ID/SECRET→503
POST	`/wechat/bind-phone/sms`	持 `bind_ticket` + 手机号 + 短信码绑号
POST	`/wechat/bind-phone/jverify`	持 `bind_ticket` + 极光本机号一键取号绑号
POST	`/wechat/conflict/continue`	占用冲突·继续绑定=登录老账号(老号没绑微信则把 openid 绑上;已绑别的微信则只登入、丢弃本次 openid)
POST	`/wechat/conflict/rebind`	占用冲突·换绑=单事务注销老账号 X(腾号)+ 用该号重建新账号 Y + 写换绑台账;受 30 天限制

绑号两条取号路径(sms / jverify)尾段共用 _finish_wechat_bind:
手机号未注册→建微信账号(channel=wechat,昵称头像取微信)登入;
已被占用→返回 phone_occupied(带占用账号昵称/头像/注册时间/has_wechat、
conflict_ticket、rebind_available、rebind_blocked_days),交前端冲突页。
冲突页三选一,后端提供 continue / rebind 两个动作(「取消」为前端本地行为)。

关键设计

两种短时令牌(core/security.py,复用 JWT_SECRET_KEY,靠 typ 区分):

bind_ticket(typ=wechat_bind,sub=openid,附微信昵称/头像,TTL 10min):
openid 未命中时下发,覆盖「授权→输手机号→收码→验码」整个绑定流程。
conflict_ticket(typ=wechat_conflict):比 bind_ticket 多编码已验证的手机号;
换绑 / 继续绑定只认票里的 phone,堵住「拿别人手机号去夺号」的接管漏洞。

30 天换绑限制: 新增台账表 phone_rebind_log(手机号级、渠道无关),
记录「腾号重建」这一破坏性事件,靠 rebound_at 算窗口;
阈值走配置 PHONE_REBIND_LIMIT_DAYS。命中限制的换绑请求返回 409。

M3 §10 昵称/头像替换: 绑微信默认用微信昵称/头像替换展示,
抽成共享 helper,登录绑号路径与钱包绑微信路径两处共用
(故 wallet.py、tests/test_withdraw.py 一并有改动)。

## 背景 / 需求新增「微信登录」链路:用户用微信授权登录 App。openid 已绑账号即直接登入; 未绑则走「绑手机号」建号,并处理「手机号已被别的账号占用」的冲突(M2), 以及绑微信后展示昵称/头像的替换策略(M3 §10)。关键取舍:微信登录**不套用**钱包提现里 bind-wechat 的「撞号即 409」逻辑 ——登录场景 openid 命中就应登入,不能因撞号把用户挡在门外。 ## 改动概览:新增 5 个端点(前缀 `/api/v1/auth`) | 方法 | 路径 | 作用 | |---|---|---| | POST | `/wechat-login` | code→openid。命中已绑用户→直接登入;未命中→签发 `bind_ticket`,返回 `need_bind_phone`(**此刻不建号**);未配 APP_ID/SECRET→503 | | POST | `/wechat/bind-phone/sms` | 持 `bind_ticket` + 手机号 + 短信码绑号 | | POST | `/wechat/bind-phone/jverify` | 持 `bind_ticket` + 极光本机号一键取号绑号 | | POST | `/wechat/conflict/continue` | 占用冲突·继续绑定=**登录老账号**(老号没绑微信则把 openid 绑上;已绑别的微信则只登入、丢弃本次 openid) | | POST | `/wechat/conflict/rebind` | 占用冲突·换绑=**单事务**注销老账号 X(腾号)+ 用该号重建新账号 Y + 写换绑台账;受 30 天限制 | 绑号两条取号路径(sms / jverify)尾段共用 `_finish_wechat_bind`: 手机号未注册→建微信账号(channel=wechat,昵称头像取微信)登入; 已被占用→返回 `phone_occupied`(带占用账号昵称/头像/注册时间/`has_wechat`、 `conflict_ticket`、`rebind_available`、`rebind_blocked_days`),交前端冲突页。冲突页三选一,后端提供 continue / rebind 两个动作(「取消」为前端本地行为)。 ## 关键设计 **两种短时令牌(`core/security.py`,复用 `JWT_SECRET_KEY`,靠 `typ` 区分):** - `bind_ticket`(typ=wechat_bind,sub=openid,附微信昵称/头像,TTL 10min): openid 未命中时下发,覆盖「授权→输手机号→收码→验码」整个绑定流程。 - `conflict_ticket`(typ=wechat_conflict):比 bind_ticket **多编码已验证的手机号**; 换绑 / 继续绑定只认票里的 phone,堵住「拿别人手机号去夺号」的接管漏洞。 **30 天换绑限制:** 新增台账表 `phone_rebind_log`(手机号级、渠道无关), 记录「腾号重建」这一破坏性事件,靠 `rebound_at` 算窗口; 阈值走配置 `PHONE_REBIND_LIMIT_DAYS`。命中限制的换绑请求返回 409。 **M3 §10 昵称/头像替换:** 绑微信默认用微信昵称/头像替换展示, 抽成共享 helper,登录绑号路径与钱包绑微信路径两处共用 (故 `wallet.py`、`tests/test_withdraw.py` 一并有改动)。

guke added 15 commits 2026-07-16 15:31:04 +08:00

feat(auth): 微信登录 bind_ticket 令牌 + 配置 2a82b20365

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(auth): POST /wechat-login(openid 命中即登入,否则发绑号令牌) 88313cefdf

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

style(auth): 微信登录 import 去前向未用 + isort 排序 fe9b749154

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(auth): POST /wechat/bind-phone/sms(短信绑号:建号/占用) a5fdcb53d8

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(auth): 补 phone_occupied 的 avatar_url 断言(锁定 M2 冲突页契约) c1b00eca0c

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(auth): POST /wechat/bind-phone/jverify(极光本机号绑号) 3621d606ad

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(auth): 补 jverify 绑号 401/502 错误分支测试 3146224944

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Merge branch 'main' of https://gitea.shaguabijia.com/WonderableAI/shaguabijia-app-server into feat/wechat-login 0177d467bf

feat(auth): M2 phone_rebind_log 换绑台账模型 + 配置 + 迁移 af615a9853

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(auth): M2 conflict_ticket 令牌(编码已验证 openid+phone) f8b5d31d2e

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(auth): M2 占用响应加 conflict_ticket/has_wechat/rebind_available f411e81b07

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(auth): M2 POST /wechat/conflict/continue(继续绑定=登录老账号) 80652ca78d

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(auth): M2 POST /wechat/conflict/rebind(换绑=注销X重建Y,单事务) 1567a9ac74

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(auth): M3 §10 绑微信按默认替换展示昵称头像(共享 helper 接两路径) 7a8bd59517

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Merge branch 'main' of https://gitea.shaguabijia.com/WonderableAI/shaguabijia-app-server into feat/wechat-login 1b729f7098

# Conflicts:
#	app/api/v1/auth.py

guke added 1 commit 2026-07-16 17:36:20 +08:00

chore(alembic): 合并 pages_override 与领券成功率两个迁移 head,修复 upgrade head(单数)多 head 报错 433555da3c

pull main 带入 #126 的 admin_user_pages_override,与本分支领券成功率的
coupon_session_platform_success → coupon_claim_app_env 都从 admin_user_plain_password
分叉,形成两个 alembic head。多 head 会让部署/run.sh 用的 `alembic upgrade head`(单数)
报 "Multiple head revisions are present" 而中断。

本迁移为纯 merge:upgrade/downgrade 均空,不含任何表结构或数据改动,仅把两个 head
收敛为单 head(merge_pages_override_coupon_slot),使 `alembic upgrade head` 恢复正常。

guke merged commit 061f6baaf1 into main

2026-07-17 21:49:14 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: WonderableAI/shaguabijia-app-server#139

feat(auth): 微信登录与手机号绑定 / 占用冲突处理(M2 + M3 §10) #139

背景 / 需求

改动概览:新增 5 个端点(前缀 /api/v1/auth)

关键设计

改动概览:新增 5 个端点(前缀 `/api/v1/auth`)