guke
a86688ccfb
背景 / 目标 连续 15 天(北京自然日)没有「首页可见 / 发起比价 / 发起领券」行为的用户判定为流失,每日自动清零其金币 + 折算现金;清零前按可配置节奏预警;全程留审计。纯登录不算活跃;邀请奖励金物理隔离、不清(产品红线)。 改了什么 活跃口径共享模块 app/repositories/activity.py:worker(清零/预警)与 admin(最近活跃)单一真源,防漂移。 清零业务逻辑 inactivity.py:选取 / 逐用户清零(行锁 + 幂等)/ 预警分档 + streak 去重 / run_once 组合,预警故障逐用户隔离、绝不阻塞清零。 每日 worker inactivity_reset_worker.py(仿 daily_exchange:文件锁 + 北京日守卫 + RUN_HOUR 门槛 + 总闸)+ main.py lifespan 接线。 可插拔通知器 notifier.py(v1 LogNotifier 日志占位,预留 JPush/短信)。 配置 INACTIVITY_*(阈值 / 预警档 / 执行点 / 通道 / 开关)。 admin 最近活跃口径改用共享模块(移除 last_login_at、纳入 show/home、以 created_at 为基线)。 审计:inactivity_reset_log + inactivity_notification_log 两表 + 钱包流水双写(biz_type=inactivity_reset,ref_id 交叉)。 文档:设计 spec / 实现 plan / docs/database/ 两表字典。 关键产品决策 邀请金不清:只清金币 + 折算现金,invite_cash_balance_cents 原封(仅快照入审计)。 活跃口径 = max(created_at, 首页可见, 比价, 领券),不含 last_login_at;首页可见 = event=show + page=home。 时间边界:北京自然日 0 点对齐(见 activity.reset_cutoff)。 总闸默认关,灰度验证后再开。 数据库变更 新表:inactivity_reset_log、inactivity_notification_log。 analytics_event 新增复合覆盖索引 ix_analytics_event_active (event, page, user_id, created_at)(活跃口径聚合热点)。 修复了 base 上的迁移多头(135e79414fd0 与 phone_rebind_log 同从 comparison_llm_cost 分叉)→ 加空 merge 修订,alembic upgrade head 恢复单头正常。 ⚠️ 上线注意(合并后 / 开总闸前) INACTIVITY_RESET_ENABLED 默认 false;开启前提 = show/home 埋点全量铺满——否则"只登录不操作"且注册满 15 天的老用户会落到 created_at 基线被误清。 前端依赖:Android 端需在首页可见上报 event=show + page=home(携带登录后的 user_id)。 admin「最近活跃」口径变化(去登录、纳入 home_view、created_at 基线):属预期变化,需产品/运营知会;与 DAU(_period_active_user_ids,仍含登录)是两套指标。 清零对 C 端「金币流水」可见(biz_type=inactivity_reset,备注「15天不活跃清零」)。 灰度:先只看预警/清零名单对不对,再开总闸。 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #143
傻瓜比价 App 后端 — 数据库表文档(索引)
数据库:SQLite 起步(
data/app.db),生产可切 PostgreSQL(改DATABASE_URL)。 ORM:SQLAlchemy 2.0(app/models/),迁移:Alembic(alembic/versions/,render_as_batch兼容 SQLite)。 金额字段一律存整数:金币=个数,现金=分(*_cents)。时间列DateTime(timezone=True)。 最后更新:2026-07-09(补 5 张新表文档并入索引:coupon_session(#99 领券任务流水)、analytics_event(#83 埋点)、invite_cash_transaction(#82 邀请奖励金账本)、admin_role(#117/#126 RBAC 角色)、ad_pangle_daily_revenue(#92,文档已有、补进索引);同步改动列:comparison_record.product_names、withdraw_order.source、coin_account.invite_cash_balance_cents、feedback审核/环境列、cps_order京东列、device_liveness.first_protected_at、ad_feed_reward_record.ad_type/feed_scene、admin_user.plain_password/pages_override。上一次 2026-06-23)
🧭 先看 OVERVIEW.md — 表 × 功能 × 关系:跨表的「每块功能用哪些表 / 什么操作写哪张表 / 表间 join key」都在那;本页只做单表索引,点进每张表的详情看字段级说明。
表总览(45 张业务表 + alembic_version 框架表)
账号 / 反馈
| 表 | 用途 | 模型 | 文档 |
|---|---|---|---|
user |
用户(登录主体);几乎所有表的外键宿主 | models/user.py |
详情 |
onboarding_completion |
新手引导完成标记(按 设备+账号 去重,登录时据此跳过引导) | models/onboarding.py |
详情 |
feedback |
用户帮助与反馈(含截图) | models/feedback.py |
详情 |
device_liveness |
无障碍存活监控(心跳超时检出 + 掉线召回;(user_id, device_id) 唯一) |
models/device.py |
详情 |
好友邀请(注册增长)
| 表 | 用途 | 模型 | 文档 |
|---|---|---|---|
invite_relation |
邀请绑定关系(注册即生效但绑定不发奖 #113;好友比价并下单后发邀请奖励金,compare_reward_granted 幂等闸;invitee_user_id 唯一) |
models/invite.py |
详情 |
invite_fingerprint |
剪贴板归因失败时的指纹兜底(落地页记 ip+屏幕+机型,登录后反查邀请人) | models/invite_fingerprint.py |
详情 |
钱包 / 福利(看广告赚钱闭环)
| 表 | 用途 | 模型 | 文档 |
|---|---|---|---|
coin_account |
金币+现金余额快照(一用户一行) | models/wallet.py |
详情 |
coin_transaction |
金币流水账本 | models/wallet.py |
详情 |
cash_transaction |
现金流水账本(分,金币兑换账) | models/wallet.py |
详情 |
invite_cash_transaction |
邀请奖励金流水账本(分,与现金物理隔离;好友比价并下单发奖 + source=invite_cash 提现) |
models/wallet.py |
详情 |
withdraw_order |
提现单(现金→微信零钱,含人工审核态;source 分账 coin_cash/invite_cash) |
models/wallet.py |
详情 |
wechat_transfer_authorization |
微信免确认转账授权(一用户一行) | models/wallet.py |
详情 |
signin_record |
签到记录(7 天循环) | models/signin.py |
详情 |
signin_boost_record |
签到后看广告膨胀记录 | models/signin.py |
详情 |
user_task |
一次性任务领取去重 | models/task.py |
详情 |
ad_reward_record |
看激励视频发奖记录(S2S 回调,trans_id 幂等) | models/ad_reward.py |
详情 |
ad_watch_log |
看广告观看时长(旧版兼容字段) | models/ad_watch_log.py |
详情 |
ad_ecpm_record |
广告展示 eCPM 上报(收益对账) | models/ad_ecpm.py |
详情 |
ad_feed_reward_record |
信息流/Draw 广告结算记录(10 秒一份,client_event_id 幂等;ad_type+feed_scene 分形态/场景) |
models/ad_feed_reward.py |
详情 |
ad_pangle_daily_revenue |
穿山甲 GroMore 后台收益日表(定时拉取,收益报表/大盘真实收益源,#92) | models/ad_pangle_revenue.py |
详情 |
inactivity_reset_log |
15 天不活跃清零审计(每次清零一行;清零前三桶余额快照+原因+不活跃天数;只清金币+现金,邀请金仅快照) | models/inactivity.py |
详情 |
inactivity_notification_log |
不活跃清零前预警记录(余额快照+档位+通道+状态;streak 去重依据 + 占位 outbox) | models/inactivity.py |
详情 |
比价 / 省钱
| 表 | 用途 | 模型 | 文档 |
|---|---|---|---|
comparison_record |
比价记录(每次比价完整明细) | models/comparison.py |
详情 |
comparison_milestone_claim |
比价战绩里程碑领取记录 | models/comparison_milestone.py |
详情 |
savings_record |
省钱记录(profile 省钱战绩源;真实下单归因 + demo) | models/savings.py |
详情 |
price_report |
上报更低价(众包纠偏,人工审核发奖) | models/price_report.py |
详情 |
比价数据沉淀(pricebot server→server 内部上报,不走用户鉴权)
| 表 | 用途 | 模型 | 文档 |
|---|---|---|---|
price_observation |
价格观测(平台/门店视角的到手价事实,匿名也记;comparison_record 的客观对照) |
models/price_observation.py |
详情 |
store_mapping |
跨平台「同一家店」id/名/deeplink 身份映射(淘宝/美团/京东,供 lookup 反查省现场搜店) | models/store_mapping.py |
详情 |
launch_confirm_sample |
启动确认窗 agent 兜底样本(pricebot LLM 放行跨 App 启动窗后回写,供研发人工沉淀规则) | models/launch_confirm_sample.py |
详情 |
领券(每日领券联动 · 今日状态)
| 表 | 用途 | 模型 | 文档 |
|---|---|---|---|
coupon_prompt_engagement |
领券引导窗频控源(今日是否已 engage,按 device+package+日) | models/coupon_state.py |
详情 |
coupon_daily_completion |
首页「去领取」置灰源(今日是否已跑完整轮) | models/coupon_state.py |
详情 |
coupon_claim_record |
每张券领取结果沉淀(资产/画像/排查,不参与判断) | models/coupon_state.py |
详情 |
coupon_session |
一次领券任务一行的全程流水(发起/终态/耗时/机型,admin 领券看板数据源,#99) | models/coupon_state.py |
详情 |
美团 CPS 券缓存
| 表 | 用途 | 模型 | 文档 |
|---|---|---|---|
meituan_coupon |
美团 CPS 券本地缓存(智能推荐/销量榜从库出,定时 ETL 灌入) | models/meituan_coupon.py |
详情 |
美团 CPS 群发联盟(私域社群比价 · 群发选品→点击→对账漏斗)
| 表 | 用途 | 模型 | 文档 |
|---|---|---|---|
cps_activity |
可推广活动池(运营预存的券/物料:美团 actId / 淘宝淘口令 / 京东链接) | models/cps_activity.py |
详情 |
cps_group |
推广微信群(sid=美团二级渠道追踪位,订单按 sid 归群对账) |
models/cps_group.py |
详情 |
cps_link |
群发短链 /c/{code}(群×活动生成,302 跳/淘宝落地页) |
models/cps_link.py |
详情 |
cps_click |
短链点击事件流(visit/copy,PV/UV 漏斗源) | models/cps_link.py |
详情 |
cps_wx_user |
CPS 落地页微信用户身份(openid 维度;网页授权拿 openid/昵称/unionid,记首次来源群) | models/cps_wx_user.py |
详情 |
cps_order |
美团联盟 query_order 拉回的对账订单(按 sid 归群算佣金) | models/cps_order.py |
详情 |
首页门面数据
| 表 | 用途 | 模型 | 文档 |
|---|---|---|---|
ops_stat_config |
首页三统计展示配置(real/manual/random) | models/ops_stat_config.py |
详情 |
ops_marquee_seed |
首页轮播种子(真实不足时兜底混播) | models/ops_marquee_seed.py |
详情 |
埋点
| 表 | 用途 | 模型 | 文档 |
|---|---|---|---|
analytics_event |
客户端埋点事件流(批量上报,一事件一行;admin 埋点日志检索,#83) | models/analytics_event.py |
详情 |
运营后台 admin(独立子应用 app/admin/,独立鉴权)
| 表 | 用途 | 模型 | 文档 |
|---|---|---|---|
admin_user |
管理员账号(独立 JWT + RBAC;pages_override 个人可见页覆盖) |
models/admin.py |
详情 |
admin_role |
后台角色→可见页配置(内建三角色 + 自定义角色,#117/#126) | models/admin_role.py |
详情 |
admin_audit_log |
操作审计日志(只追加) | models/admin.py |
详情 |
app_config |
运营可配置项(覆盖 rewards 常量) | models/app_config.py |
详情 |
通用约定
- 主键:
idInteger autoincrement;例外:coin_account/wechat_transfer_authorization的user_id既是主键也是外键(一用户一行),app_config用key作主键。 - 外键:所有用户维度表
user_id→user.id且建 index(含device_liveness);admin_audit_log.admin_id→admin_user.id;price_report.comparison_record_id→comparison_record.id。 - 金额:整数;金币计数,现金/价格存「分」(
*_cents)。汇率10000 金币 = 1 元 = 100 分。 - 时间:
created_at等用DateTime(timezone=True)+server_default=func.now();业务"今天"按北京时间(core/rewards.cn_today),跨天计数用「日期串」列(reward_date/watch_date/report_date,String(10)存YYYY-MM-DD)等值查,不在 SQL 里做跨时区 date 比较(SQLite 不可靠)。 - JSON 列:
JSON().with_variant(JSONB(), "postgresql")—— PG 上 JSONB(可建 GIN 索引),SQLite 退化为通用 JSON(否则create_all编译报错);feedback.images例外,用通用JSON。 - 分页:列表接口统一游标式(
id倒序,cursor=上页最后一条 id,返回next_cursor)。 - 迁移:改表必写 alembic 迁移并保持单 head;改表/建表同时更新本目录对应文档(一表一文件)+ OVERVIEW.md。