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

analytics_event — 客户端埋点事件流

模型 app/models/analytics_event.py · 仓库 app/repositories/analytics.py · 接口 C 端 POST /api/v1/analytics/events(analytics-events,批量,不强制登录);admin GET /admin/api/event-logs(app/admin/routers/event_logs.py) · ← 索引 · 总览

客户端行为埋点的落地表,一事件一行(append-only)。客户端攒批上报(每批 ≤200 条),服务端展开逐条插入;props 装事件自带的任意维度。当前主要供 admin「埋点日志」检索与手工分析,无自动聚合任务。#83 新增(2026-06-27)。

用在哪 / 增删改查

• C(插入):POST /api/v1/analytics/events(不强制登录:带 JWT 则记 user_id,匿名只记 device_id)。服务端补 client_ip。
• U / D:无。只追加。
• R:admin GET /admin/api/event-logs(游标分页,可按 event/device_id/user_id 筛)。

字段

列	类型	约束 / 默认	说明
id	Integer	PK, autoincrement
event	String(64)	index, NOT NULL	事件名(客户端约定,如页面曝光/点击类事件名)
props	JSON	nullable	事件属性(任意维度,客户端原样传)
device_id	String(64)	index, NOT NULL	客户端 per-install id(匿名也有)
user_id	Integer	index, nullable	登录态才有。无硬 FK
session_id	String(64)	index, nullable	客户端会话 id(一次冷启动一个)
client_ts	BigInteger	NOT NULL	事件发生时间(客户端 epoch ms)
sent_at	BigInteger	nullable	客户端上报时间(epoch ms);与 client_ts 差 = 攒批延迟
page	String(64)	nullable	事件所在页面
client_ip	String(64)	nullable	服务端从请求头取
oem / os / model	String	nullable	厂商 / 系统版本 / 机型
app_ver	String(32)	nullable	App versionName
network	String(16)	nullable	网络类型(wifi/cellular)
channel	String(32)	nullable	分发渠道
created_at	DateTime(tz)	server_default now()	入库时间

关系 / Join Key

• user_id 软指 user.id、device_id 与其他表的 per-install id 同源——均无硬 FK(埋点不鉴权、匿名也收,不能被外键约束卡住)。

索引与约束

• PK id;index event、device_id、user_id、session_id。

注意

• 每批最多 200 条,超出整批 422;单条字段超长按模型截断口径处理。
• 时间轴分析用 client_ts(事件真实发生时刻),created_at 只是入库时刻(受攒批影响)。