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

coupon_session — 领券任务全程流水(admin「领券数据」看板数据源)

模型 app/models/coupon_state.py(CouponSession) · 仓库 app/repositories/coupon_state.py(upsert_session) · 接口 C 端 POST /api/v1/coupon/session(coupon-session);admin GET /admin/api/coupon-data/*(聚合看板 + 明细,app/admin/routers/coupon_data.py) · ← 索引 · 总览

一次领券任务一行(trace_id 唯一),记从发起(started)到收尾(completed/failed/abandoned)的全程:总耗时、各平台耗时、领到张数、机型/ROM、发起来源。与同文件的三张「今日状态」表(coupon_state)分工不同:那三张按「设备×日」管频控/置灰,本表按「一次任务」管漏斗与体验指标——admin「领券数据」看板的发起数、完成率、中途流失(started 无终态)、平均耗时都从这算。#99 新增(2026-06-30)。

用在哪 / 增删改查

• C / U(upsert,按 trace_id):客户端 POST /api/v1/coupon/session 两段上报——发起时建行(status='started',带 platforms/origin_package/机型),收尾时按同 trace_id 更新同一行(终态 + elapsed_ms + platform_elapsed + claimed_count)。发起即落库 → 收尾丢失(App 被杀/断网)的行永远停在 started = 中途流失,可量化。
• D:无。
• R:admin GET /admin/api/coupon-data(按 started_date × app_env 聚合趋势/漏斗 + 逐条明细,join user 出手机号)+ GET /admin/api/coupon-data/user-records(用户抽屉:某用户全部领券记录)。

字段

列	类型	约束 / 默认	说明(取值 / join)
id	Integer	PK, autoincrement
trace_id	String(64)	NOT NULL, UNIQUE(uq_coupon_session_trace)	一次领券唯一 id(客户端 UUID,全程贯穿),upsert 幂等键;与 pricebot work_logs / coupon_claim_record.trace_id 同源
device_id	String(64)	NOT NULL	客户端 per-install id
user_id	Integer	index, nullable	登录态才带(admin join user 出手机号/昵称);匿名领券为空。无硬 FK
status	String(16)	NOT NULL	started(发起)/ completed / failed / abandoned(用户中止)。started 无终态 = 中途流失
app_env	String(16)	index, nullable	prod / dev(客户端 BuildConfig.DEBUG)。admin 报表默认只看 prod,防测试数据串台
platforms	JSON(PG: JSONB)	nullable	发起勾选平台 ["meituan-waimai", ...];空=全领
origin_package	String(64)	nullable	发起来源外卖 App 包名;null=App 内(傻瓜比价首页)发起,非空=切到美团/淘宝/京东被弹券引导发起。admin「发起平台」列据此区分
device_model	String(128)	nullable	机型(Build.MANUFACTURER + MODEL)
rom	String(64)	nullable	ROM(OemDetector,如 ColorOS 14)
started_at	DateTime(tz)	NOT NULL	发起时刻(客户端墙钟)
started_date	Date	NOT NULL	发起的 Asia/Shanghai 自然日;admin 按天聚合/筛选(复合索引)
finished_at	DateTime(tz)	nullable	收尾时刻(服务端 now);未收尾(流失)为空
elapsed_ms	Integer	nullable	全程耗时(客户端点发起→收尾计时,权威);平均/分位只统计 completed
platform_elapsed	JSON(PG: JSONB)	nullable	各平台领券耗时 {"meituan-waimai": 3200, ...}(ms)
claimed_count	Integer	nullable	本次领到张数(收尾上报)
trace_url	String(512)	nullable	pricebot 公网调试链接(admin 明细可点开复盘)
created_at / updated_at	DateTime(tz)	server_default now() / +onupdate

关系 / Join Key

• user_id 软指 user.id(无硬 FK,可空;admin 明细 LEFT JOIN 出手机号)。
• trace_id 与 pricebot work_logs、coupon_claim_record.trace_id 同源(一次任务),无 id 级 join。
• device_id 与领券三表同源(per-install id)。

索引与约束

• PK id;UNIQUE trace_id;index user_id、app_env;复合 index ix_coupon_session_date_env(started_date, app_env)= admin 看板主查询路径。

注意

• 写库 best-effort 口径与领券三表一致:上报失败不影响领券本身(且本表数据源是客户端独立上报,不是 /coupon/step 透传顺手写)。
• elapsed_ms 以客户端计时为准(墙钟差不影响);finished_at - started_at 只做时刻留痕,不用来算时长。