shaguabijia-app-server/docs/database/user.md

user — 用户(登录主体)

模型 app/models/user.py · 仓库 app/repositories/user.py · 接口 auth-jverify-login / auth-sms-login / user-profile / user-avatar / user-delete · ← 索引 · 总览

整个 App 的用户主体,也是几乎所有业务表的外键宿主。极光一键登录与短信登录都映射到同一行、以 phone 唯一索引;注册即登录(phone 不存在则 insert,存在则更新 last_login_at)。后续加微信/Apple 登录会新增 oauth_account 表,本表不动。

用在哪 / 增删改查

• C(插入=注册):首次登录 POST /auth/jverify-login(极光)或 /auth/sms/login(短信)→ upsert_user_for_login,phone 不存在则建行(register_channel='jverify'/'sms')。
• U(更新):① 每次登录刷 last_login_at;② 改昵称 PATCH /user/profile、传头像 POST /user/avatar;③ 绑/解绑微信 POST /wallet/bind-wechat / /unbind-wechat(写 wechat_openid/nickname/avatar_url);④ 注销 DELETE /user(软删,见下);⑤ admin 改状态(禁用/启用)。
• D(删除):无物理删除。注销是软删 = U:status='deleted' + phone='deleted_<id>'(释放唯一约束,可同号重注册)+ 清 PII。
• R(读取):每个鉴权请求经 api/deps.get_current_user 解 JWT 的 sub 查本表(并校验 status=='active');admin 用户管理列表/详情。

字段

列	类型	约束 / 默认	说明(取值 / join)
id	Integer	PK, autoincrement	用户主键;被多张业务表的 user_id 外键引用
phone	String(20)	UNIQUE, index, NOT NULL	手机号(登录主键)。注销后置 deleted_<id> 占位释放唯一约束
username	String(11)	UNIQUE, index, NOT NULL	对外展示账号 ID:11 位纯数字、首位非 1(与手机号天然区分)、全局唯一、创建时随机生成、不可变、不参与登录(登录仍走 phone)。生成见 repositories/user._gen_username
register_channel	String(20)	NOT NULL, default jverify	取值:jverify(极光一键)/ sms(短信);savings_record 的对比人群另有种子用户用 seed
nickname	String(64)	nullable	通用昵称(PATCH /user/profile 写)
avatar_url	String(512)	nullable	通用头像相对 URL /media/avatars/...(POST /user/avatar 写)
invite_code	String(16)	UNIQUE, index, nullable	邀请码:每用户一个稳定短码(懒生成,见 repositories/invite.ensure_code),分享链接/二维码里带它。UNIQUE 允许多个 NULL(未生成的用户)
wechat_openid	String(64)	UNIQUE, index, nullable	微信 openid(提现转账用);一微信一账号,多个 NULL 允许(多个未绑用户)
wechat_nickname	String(64)	nullable	微信昵称(绑定时拉,展示在提现绑定卡;与通用 nickname 分开存)
wechat_avatar_url	String(512)	nullable	微信头像 URL
status	String(20)	NOT NULL, default active	取值:active(可登录/鉴权)/ disabled(admin 禁用)/ deleted(已注销);仅 active 能通过鉴权
debug_trace_enabled	Boolean	NOT NULL, default false, server_default false	调试链接权限:开了的用户在比价完成弹窗 + 比价记录页能看到「复制调试链接」按钮(运营后台按用户配置);/me 与登录响应带出给前端做条件渲染
created_at	DateTime(tz)	server_default now()	注册时间
last_login_at	DateTime(tz)	应用层 default utcnow	最近登录时间(每次登录更新)

关系 / Join Key

• 被引用方(本表是 1,对方是 N/1):coin_account、coin_transaction、cash_transaction、withdraw_order、wechat_transfer_authorization、signin_record、signin_boost_record、user_task、comparison_record、comparison_milestone_claim、savings_record、ad_reward_record、ad_watch_log、ad_ecpm_record、ad_feed_reward_record、price_report、feedback 的 user_id 均 → user.id;invite_relation 的 inviter_user_id / invitee_user_id 均 → user.id。
• 与 admin_user 无任何关联(C 端用户 vs 后台管理员,两套体系)。

索引与约束

• PK id;UNIQUE+index phone、username、invite_code(允许多 NULL)、wechat_openid(允许多 NULL)。

注意

• nickname/avatar_url(通用)与 wechat_nickname/wechat_avatar_url(微信)分开存,不互相覆盖。
• 软删后旧 JWT 仍能用到自然过期(无 jti 黑名单,见 待办与技术债.md);鉴权查 status 拦得住绝大多数路径。