017 - Apple / Google / LINE 三方登录

背景

C 端 app 现仅支持「手机号 + 短信验证码」登录（/infouser/user/lodeing，登录即注册）。本特性新增 Apple / Google / LINE 三方登录，降低台湾市场获客与登录摩擦。鉴权沿用现有自写 JwtUtil（HS256 JWT + Redis 会话），不引入新鉴权体系。

锁定的关键决策（业务确认）

手机号始终是主键：三方账号只是绑在「某个手机号账号」上的快捷入口，不在 InfoUser 上落三方 ID（独立表 info_user_oauth 记录绑定关系）。
首次使用任一三方登录强制手机验证：拿到手机号后查 info_user——已注册则关联到该老账号（写一条 oauth 绑定），未注册则新建账号后再绑定。不以邮箱做关联。
不使用 Apple 邮箱信息：Apple 只取 identityToken 的 sub（稳定用户ID），忽略 email。
记录登录渠道 loginType：因一个用户可绑多家三方，loginType 不落用户表，而写入本次会话的 JWT claim（provider）。

User Story

US1 - 三方登录入口 (P0)

客户在登录页选 Apple/Google/LINE，客户端拿到 provider 凭证后调后端校验。

US2 - 首次登录手机验证 + 绑定 (P0)

首次用某三方账号登录时，强制输手机号 + 短信验证码：手机号已注册→关联该账号；未注册→新建账号；随后建立 oauth 绑定。

US3 - 已绑定快捷登录 (P0)

已绑过该三方的账号再次登录，校验凭证通过即直接签发 token，免手机验证。

Functional Requirements

FR-001: 提供 POST /infouser/user/oauthLogin {provider, credential, ...}，后端校验 provider 凭证换取稳定 providerUid。用户 provider 为 apple、google、line（旧版）、line_user；骑手为 apple_rider、google_rider、line_rider；商家为 apple_merchant、google_merchant、line_merchant。
FR-002: 凭证校验三选一：Apple=验 ES256 identityToken 取 sub；Google=tokeninfo HTTP 验真取 sub 并校 audience；LINE=前端传授权 code，后端用 code+clientSecret+clientId 向 oauth2/v2.1/token 换 access_token，再调 v2/profile 取 userId（Authorization Code 流程，不直接收前端 accessToken）。
FR-003: 按 (provider, providerUid) 查 info_user_oauth：命中→校验用户 status/del_flag 正常后直接签发 token（claim provider）返回；未命中→缓存 {provider,providerUid} 到 Redis(短TTL)，返回 needPhone + tempKey。
FR-004: 提供 POST /infouser/user/oauthBindPhone {tempKey, phone, code, ...}：取回缓存的 providerUid + 验短信码（复用 lodeing 逻辑，含万能码 8888）→ getuser(phone)：已注册→关联；未注册→createUser 新建；随后 insert info_user_oauth(user_id, provider, provider_uid)。
FR-005: 新建用户的 info_user.nick_name 统一用手机号（与现有 createUser 一致），avatar 留空；三方资料不得覆盖用户主昵称/头像。第三方名称的独立展示见下方 2026-09-24 后续增量。
FR-006: token claim 增加 provider 字段（apple/google/line_user/line_rider/line_merchant；手机号登录为 phone），供登录渠道统计或「未绑手机限制」类约束使用。
FR-007: 登录端点 @Anonymous 放行；受保护接口继续走 @Auth，零额外接入。
FR-008: 凭证校验失败 / tempKey 过期 / 短信码错误 → 明确错误提示，不签发 token、不建账号。
FR-009（2026-08-05 增量，2026-09-04 扩展）: LINE「唤起 LINE App / 系统浏览器」流程下前端拿不到 code，使用服务端回调 GET /auth/line/callback（@Anonymous，LineCallbackController）：接收 provider 与 LINE 重定向的 code → 复用 verify(provider, code) 换 token 取 userId → 已绑定签 token / 未绑定生成 tempKey → 302 跳回 provider 对应 App scheme（?token= / ?needPhone=1&tempKey= / ?error=，未绑定时 App 再调 /infouser/user/oauthBindPhone）。原 /oauthLogin 保留，覆盖前端自取 code 场景（H5/webview/SDK）。
FR-010（2026-09-04 增量）: LINE 登录按客户端区分 line_user、line_rider、line_merchant。三个客户端继续自行构造 LINE 授权地址，共用 GET /auth/line/callback，通过回调 URL 的 provider 查询参数选择对应 Channel 配置；provider 只能取上述三个白名单值。
FR-011: 三个 LINE Channel 使用各自的 Channel ID、Channel Secret、redirect URI 和 App 回跳地址。换取 access token 时提交的 redirect URI MUST 与发起授权时完全一致，包括 provider 查询参数。
FR-012: line_user 沿用普通用户首次登录的手机号关联/新建逻辑；line_rider 只允许绑定已有且有效的 userType=2 账号；line_merchant 只允许绑定已有且有效的 userType=1/3/4/5 账号，不自动创建骑手或商家。
FR-013: 普通用户手机号继续使用 info_user.phone；骑手和全部商家账号（userType=1/2/3/4/5）统一使用 info_user.tel_phone。有效商家/骑手的 tel_phone 不得重复，软删除账号（del_flag!='0'）不占用手机号；手机号按存储字符串精确比较，0912... 与 +886... 视为不同号码。普通用户的 phone 可与商家/骑手的 tel_phone 相同。
FR-014: 商家/骑手手机号唯一性通过业务层校验实现，不新增数据库唯一索引。新增与修改时均校验，修改时排除当前 user_id。
FR-015: LINE 登录成功后，line_user、line_rider、line_merchant 分别签发普通用户、骑手、商家 App 会话 token，并跳回对应 App scheme。

Key Entities

info_user_oauth（新增）：id、user_id、provider（apple/google/line_user/line_rider/line_merchant）、provider_uid、create_time。UNIQUE(provider, provider_uid) 用于按三方ID反查用户；user_id 普通索引。
InfoUser（已有，不改）：仍是手机号为主键，无三方 ID 列。

安全要点

Apple/Google 必须校验 audience（= 我方 client_id/bundleId），防其他 App 的 token 被冒用。
Apple 校验 iss=https://appleid.apple.com + exp。
tempKey 一次性、短 TTL（5 分钟），防重放。

2026-09-08 增量：骑手、商家 Apple / Google 与用户端兼容

新增 apple_rider、apple_merchant、google_rider、google_merchant，各端独立校验 audience，不回退到用户端 client ID。
骑手仅允许已有有效 userType=2，商家仅允许已有有效 userType=1/3/4/5；通过 tel_phone 验证绑定，不自动创建业务账号。子账号继续校验启用状态与归属权限。
业务账号首次绑定要求真实短信验证码，不使用原用户分支的固定验证码兼容逻辑；用户原校验行为不变。
按端签发 QS_TOKEN_KEY / SH_APP_TOKEN_KEY，用户原有 apple、google 配置、绑定和 token 类型保持兼容。
兼容用户 App 仍在使用的 provider=line 和不带 provider 的 /auth/line/callback，旧授权地址换 token 时使用原 redirect URI。line / line_user 均可读取旧、新绑定；不直接执行数据迁移。
用户旧版不强制升级 state 协议；客户端升级与真实凭证验证须单独记录实际完成情况，不以单元测试代替上线验收。
业务 LINE 新增 POST /auth/line/authorize 签发五分钟有效的 provider 绑定 state；回调和直接提交 code 均要求单次消费，App 比较回跳 state。用户旧 LINE 协议保持不变。

不在本期范围（原记录）

后台管理端解绑/查看三方绑定（后续增量）。
第三家以上三方（微信/Facebook）——表结构已可扩展，但本期只接 Apple/Google/LINE。
Apple 隐藏邮箱中转、refresh_token 续期等高级场景。

2026-09-24 后续增量：登录渠道与第三方名称展示（后端已于 2026-09-28 实施）

用户端分别展示原有 info_user.nick_name、本次登录渠道（Apple / LINE）及该渠道的第三方名称。用户修改昵称仍走原有资料修改流程；切换登录渠道不得覆盖 info_user.nick_name，也不得把不同 user_id 的三方身份视为同一账号。
info_user_oauth.user_id 只表示账号绑定关系，不表示“最近一次登录”。当前 provider 记录在本次登录的 JWT 会话中，info_user 不保存最近登录渠道；本增量展示的是本次会话的登录方式，不是跨设备共享的历史“最后一次登录方式”。
第三方名称按绑定身份独立保存于 info_user_oauth.provider_display_name（新增可空字段）；本次登录为 LINE 时显示 LINE 名称，为 Apple 时显示 Apple 名称，不使用其他渠道的名称。字段已于 2026-09-28 增加（SQL 待手动执行，历史行保持空值）。
LINE：每次成功登录且取得带 profile 权限的资料时，读取 displayName 并刷新对应绑定记录；获取失败时保留已保存的名称，不影响登录。
Apple：首次授权取得用户共享的 fullName 时保存到对应绑定记录；后续登录不要求再次取得名称。历史账号未保存过 Apple 名称或用户未共享名称时，该名称允许为空，用户端仅展示“Apple 登录”及原有昵称，不伪造 Apple 名称。
2026-09-28 后端实施完成（实施记录见 tasks.md）：App 端展示联调与真机验证待 App 源码接入，数据库 SQL 待手动执行。

2026-10-08 增量：业务端（骑手/商家/子账号）改用账号密码绑定

背景：子账号等业务账号不强制登记 tel_phone，而短信绑定流程按 tel_phone 查账号——无手机号的账号永远查不到，LINE/Apple 登录对其实际不可用。业务账号的 user_name + 密码是其唯一且 100% 覆盖的日常登录因子（shanglodeing/syslodeing 均为账号密码登录），以密码作为绑定凭证与业务账号既有安全等级一致。

FR-016: 业务渠道（apple_rider/google_rider/line_rider/apple_merchant/google_merchant/line_merchant）首次绑定改为账号 + 密码：oauthBindPhone 业务分支不再要求手机号/短信码，改为提交 userName + RSA 加密 password；后端按 user_name + user_type IN (渠道角色) + del_flag=0 查账号，RSA 解密比对密码（复用 shanglodeing 比对逻辑），通过后走 canOauthLogin（含停用拦截、子账号启用状态与归属校验）再写绑定并按端签发 token。
FR-017: 用户端绑定完全不变：仍为手机号 + 短信验证码（含万能码 8888 兼容）；apple/google/line/line_user 行为不变。本增量同时移除业务端的短信绑定路径——所有业务账号必有 user_name+密码，密码绑定即全覆盖，不保留双路径。
FR-018: 业务端绑定失败（缺账号/缺密码/账号不存在/密码错误/账号停用）不写绑定、不签 token；提示复用现有 key（no.user.password.not.null / no.user.not.exist / no.user.password.error / no.user.stop），仅新增 no.oauth.username.blank。
FR-019: LINE 回调契约不变：业务线未绑定仍 302 needPhone=1&tempKey=，业务 App 将该页面渲染为账号密码表单（App 端外部待办，后端不改回跳参数）。
oauthLogin、oauthDeviceConfirm、已绑定快捷登录、绑定竞态容错分支均不受本增量影响；设备信任免短信确认继续仅限用户端。

spec.md 11 KB History Raw