WonderableAI/shaguabijia-app-server
11
0
Fork 0
Code Issues Pull Requests 8 Actions Packages Projects Releases Wiki Activity

docs: 补全 API 与数据库文档

Browse Source 
- 新增 device-liveness(无障碍存活监控)、internal(内部回写端点)、cps-redirect(CPS 短链落地)三族单文件文档
- API 总览补录此前缺失端点:coupon prompt 频控、report/invite、wxpay 回调、platform 客户端配置、feedback/user/ad 零散读端点
- database 新增 cps_wx_user / device_liveness / launch_confirm_sample 三表文档,更新 OVERVIEW/README/comparison_record/数据库迁移/后端技术实现

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
marco
2026-06-24 04:07:54 +08:00
parent 128db7fb86
commit 43f28d358b
12 changed files with 339 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/README.md
+45 -3
View File
@@ -3,7 +3,7 @@
> Base URL:生产 `https://app-api.shaguabijia.com`;本地联调 `http://<开发机>:8770`
> 协议:HTTP / JSON,请求与响应体均 `application/json`,字段统一 **snake_case**
> 鉴权:需鉴权的接口在请求头带 `Authorization: Bearer <access_token>`
> 最后更新:2026-06-18（补录比价透传端点 `intent/precoupon/step`、`intent/step`、`trace/finalize` 与 `meituan/top-sales` 到总览;上一次功能更新 2026-06-07 金币数值体系一期）
> 最后更新:2026-06-23（补全此前缺整族的端点:device 无障碍存活监控、internal 内部回写、CPS 短链落地、report/invite/wxpay,及 platform/coupon/feedback/user 的零散读端点;device/internal/cps-redirect 三族新建单文件文档。上一次 2026-06-18 补录比价透传端点与 `meituan/top-sales`）
> 架构:`app/api/v1/` 只放很轻的接口层;穿山甲/微信支付/极光/短信/美团等 SDK 集成的重逻辑在 `app/integrations/`,实现细节见 [docs/integrations/](../integrations/README.md)。
---
@@ -19,7 +19,14 @@
| 5 | `POST /api/v1/auth/refresh` | 无 | [详情](./auth-refresh.md) |
| 6 | `GET /api/v1/auth/me` | Bearer | [详情](./auth-me.md) |
| 7 | `POST /api/v1/auth/logout` | Bearer | [详情](./auth-logout.md) |
| 8 | `POST /api/v1/coupon/step` | 无 | [详情](./coupon-step.md) |
| 8 | `POST /api/v1/coupon/step` | 无 | [详情](./coupon-step.md)（透传 pricebot + best-effort 写 `coupon_*` 三表） |
| 8a | `POST /api/v1/coupon/prompt/shown` | 无 | 引导窗弹出即上报（按 device+package+日记 `shown`,今天这个 App 不再自动弹）(无单独文档) |
| 8b | `POST /api/v1/coupon/prompt/dismiss` | 无 | 用户拒绝/关闭引导窗（透传链路看不到拒绝,客户端通知）(无单独文档) |
| 8c | `GET /api/v1/coupon/prompt/should-show` | 无 | 切到外卖 App 时是否还应弹引导窗（`device_id`+`package`)(无单独文档) |
| 8d | `POST /api/v1/coupon/prompt/reset` | 无 | 重置今日引导窗 engagement（开发测频控用)(无单独文档) |
| 8e | `GET /api/v1/coupon/completed-today` | 无 | 这台设备今天是否已跑完整轮领券（首页「去领取」卡置灰源)(无单独文档) |
| 8f | `POST /api/v1/coupon/completed-today/reset` | 无 | 重置今日已完成（开发用)(无单独文档) |
| 8g | `GET /api/v1/coupon/stats` | Bearer | 累计领券数（「我的」页战绩卡;按 user_id 聚合,**鉴权**)(无单独文档) |
| 9 | `POST /api/v1/meituan/coupons` | 无 | [详情](./meituan-coupons.md) |
| 10 | `POST /api/v1/meituan/feed` | 无 | [详情](./meituan-feed.md) |
| 11 | `POST /api/v1/meituan/referral-link` | 无 | [详情](./meituan-referral-link.md) |
@@ -38,6 +45,19 @@
| **比价战绩里程碑**（前缀 `/api/v1/compare`；福利页「记录比价战绩」,按成功比价数解锁逐档发金币） |||
| 12d | `GET /api/v1/compare/milestones` | Bearer | [详情](./compare-milestones.md) |
| 12e | `POST /api/v1/compare/milestones/{milestone}/claim` | Bearer | [详情](./compare-milestone-claim.md) |
| **设备 / 无障碍存活监控**（前缀 `/api/v1/device`；心跳超时检出 + 掉线召回,#65） |||
| D1 | `POST /api/v1/device/register` | Bearer | [详情](./device-liveness.md)（注册设备/更新极光 push token） |
| D2 | `POST /api/v1/device/heartbeat` | Bearer | [详情](./device-liveness.md)（无障碍服务存活心跳,心跳也能自注册） |
| D3 | `GET /api/v1/device/liveness` | Bearer | [详情](./device-liveness.md)（进 App 查本机是否被判掉线过） |
| D4 | `POST /api/v1/device/liveness/ack` | Bearer | [详情](./device-liveness.md)（确认已弹引导,清掉线告警） |
| **上报更低价**（前缀 `/api/v1/report`；众包纠偏,人工审核发奖） |||
| R1 | `POST /api/v1/report` | Bearer | 提交上报（multipart:`comparison_record_id`/`reported_platform_id`/`reported_price`(元) + 1~4 张截图;原最低价反查 `comparison_record.best_*` 校验须更低）(无单独文档) |
| R2 | `GET /api/v1/report/records` | Bearer | 上报记录列表（`?status=` pending/approved/rejected 可选筛选）(无单独文档) |
| **好友邀请**（前缀 `/api/v1/invite`；注册即生效,双方各发 1 万金币） |||
| I1 | `GET /api/v1/invite/me` | Bearer | 我的邀请码 + 分享链接 + 已邀人数/已得金币(无单独文档) |
| I2 | `GET /api/v1/invite/invitees` | Bearer | 我邀请的人列表（`limit`/`offset` 分页）(无单独文档) |
| I3 | `POST /api/v1/invite/landing-track` | 无 | 落地页 `dl.html` 访问上报指纹(剪贴板归因兜底;浏览器无 token)(无单独文档) |
| I4 | `POST /api/v1/invite/bind` | Bearer | 绑定邀请人;支持 clipboard/manual 邀请码 + fingerprint 指纹反查三种归因(无单独文档) |
| **钱包 / 我的资产**（前缀 `/api/v1/wallet`） |||
| 14 | `GET /api/v1/wallet/account` | Bearer | [详情](./wallet-account.md) |
| 15 | `GET /api/v1/wallet/coin-transactions` | Bearer | [详情](./wallet-coin-transactions.md) |
@@ -68,15 +88,37 @@
| 35 | `POST /api/v1/ad/ecpm-report` | Bearer | [详情](./ad-ecpm-report.md) |
| 35a | `POST /api/v1/ad/feed-reward` | Bearer | [详情](./ad-feed-reward.md) |
| 35b | `POST /api/v1/ad/reward-noshow` | Bearer | [详情](./ad-reward-noshow.md)(激励视频提前关闭/未发奖留痕,只记原因不发币) |
| 35c | `GET /api/v1/ad/feed-reward/units` | Bearer | 信息流广告今日已发份数/上限(配合 `feed-reward` 看进度)(无单独文档) |
| **用户资料**（前缀 `/api/v1/user`） |||
| 35 | `PATCH /api/v1/user/profile` | Bearer | [详情](./user-profile.md) |
| 36 | `POST /api/v1/user/avatar` | Bearer | [详情](./user-avatar.md) |
| 36a | `POST /api/v1/user/onboarding/complete` | Bearer | 标记新手引导完成（按 账号+device_id 幂等,跨卸载重装持久）(无单独文档) |
| 36b | `GET /api/v1/user/onboarding/status` | Bearer | 查该 (账号,设备) 是否走过引导（运营在 admin 删记录即触发重走）(无单独文档) |
| 37 | `DELETE /api/v1/user` | Bearer | [详情](./user-delete.md) |
| **帮助与反馈**（前缀 `/api/v1/feedback`） |||
| 38 | `POST /api/v1/feedback` | Bearer | [详情](./feedback.md) |
| **首页门面数据**（前缀 `/api/v1/platform`；全平台展示数字,登录前可读） |||
| 38a | `GET /api/v1/feedback/config` | Bearer | 反馈页「加群二维码」卡配置（开关 + 二维码图 + 三行文案）(无单独文档) |
| 38b | `GET /api/v1/feedback/records` | Bearer | 我的反馈历史（pending/adopted/rejected）(无单独文档) |
| **首页门面数据 / 客户端配置**（前缀 `/api/v1/platform`；全平台展示数字 + 运营开关,**全部不鉴权**,登录前可读） |||
| 39 | `GET /api/v1/platform/stats` | 无 | [详情](./platform-stats.md) |
| 40 | `GET /api/v1/platform/savings-feed` | 无 | [详情](./platform-savings-feed.md) |
| 40a | `GET /api/v1/platform/flags` | 无 | 客户端运营 feature flag（比价/领券期广告开关等),拉取后缓存(无单独文档) |
| 40b | `GET /api/v1/platform/ad-config` | 无 | 客户端拉广告配置（穿山甲 app_id + 各位 ID + 各场景开关;不含验签密钥）(无单独文档) |
| 40c | `GET /api/v1/platform/app-version` | 无 | 最新 App 版本（OTA 检查更新;与本机 versionCode 比）(无单独文档) |
| **微信支付回调**（前缀 `/api/v1/wxpay`） |||
| W1 | `POST /api/v1/wxpay/transfer-auth-notify` | 无 | 免确认收款授权结果通知（一期 stub:仅应答 200 不验签不改账,授权状态靠主动查询兜底)(无单独文档) |
| **CPS 群发短链落地**（**无前缀**,挂域名根;公网不鉴权） |||
| C1 | `GET /c/{code}` | 无 | [详情](./cps-redirect.md)（短链落地:微信授权拿 openid + 记点击 + 302 跳/淘宝 H5 落地页） |
| C2 | `POST /c/{code}/copy` | 无 | [详情](./cps-redirect.md)（淘宝落地页点「复制口令」记 `copy`） |
| C3 | `GET /wx/oauth/cb` | 无 | [详情](./cps-redirect.md)（微信网页授权回调;upsert `cps_wx_user` + 种 cookie,`include_in_schema=False`） |
| C4 | `GET /MP_verify_*.txt` | 无 | [详情](./cps-redirect.md)（微信「网页授权域名」归属校验文件,`include_in_schema=False`） |
| **内部回写端点**（前缀 `/internal`;pricebot/发布流程→app-server,**`X-Internal-Secret` 头**,非客户端接口） |||
| N1 | `POST /internal/price-observation` | 内部密钥 | [详情](./internal.md)（比价价格事实批量落 `price_observation`） |
| N2 | `GET /internal/store-mapping/lookup` | 内部密钥 | [详情](./internal.md)（按源平台店名反查目标平台已沉淀店铺 id/deeplink） |
| N3 | `POST /internal/store-mapping` | 内部密钥 | [详情](./internal.md)（跨平台店铺身份映射落 `store_mapping`） |
| N4 | `POST /internal/store-mapping/invalidate` | 内部密钥 | [详情](./internal.md)（标记某平台 shopId 缓存 deeplink 失效） |
| N5 | `POST /internal/launch-confirm-sample` | 内部密钥 | [详情](./internal.md)（启动确认窗兜底样本落 `launch_confirm_sample`） |
| N6 | `POST /internal/app-version` | 内部密钥 | [详情](./internal.md)（发布流程写最新 App 版本,落 `app_config`） |
| **静态资源**（StaticFiles 挂载,见下方 `/media` 静态服务） |||
| - | `GET /media/avatars/<file>` | 无 | 用户头像;返回二进制图片 |
| - | `GET /media/feedback/<file>` | 无 | 反馈截图;返回二进制图片 |
docs/api/cps-redirect.md
+30
View File
@@ -0,0 +1,30 @@
# CPS 群发短链落地(cps-redirect 族)
> 所属:cps-redirect 组(**无前缀**,挂域名根;源 `app/api/v1/cps_redirect.py`) | 鉴权:**公网无鉴权**(群里任何人点都要能跳/能领) | [← 返回 API 索引](./README.md)
>
> 落库:点击落 [`cps_click`](../database/cps_click.md)、微信落地页用户落 [`cps_wx_user`](../database/cps_wx_user.md);短链由 [`cps_link`](../database/cps_link.md) 解析。
运营把 `/c/{code}` 短链发到微信群,用户点击 → 记点击 → 按平台 302 跳转(美团/京东)或返回 H5 淘宝落地页。**记点击/写用户失败绝不阻断用户跳转/领券**(try/except 吞掉)。
## GET /c/{code} — 短链落地
- 微信内 + 还没拿到 openid + 配了服务号 → 先 `snsapi_base` 静默授权拿 openid,再 302 回本页。
- 非微信 / 已有 openid cookie / 未配服务号 → 直接走原逻辑(openid 可能为 None,**绝不阻断**)。
- 记 `visit`(写 `cps_click`)后:**美团/京东** 302 跳 `target_url`;**淘宝** 返回 H5 落地页(主视觉图 + 「复制口令」按钮)。
- `code` 不存在/失效 → 302 跳兜底(`https://www.meituan.com/`)。
**入参**:路径 `code`(短链码)。**出参**:`302 Redirect` 或 `200 HTML`(淘宝)。
## POST /c/{code}/copy — 淘宝落地页点了「复制口令」
淘宝落地页是 H5,用户点「复制口令」才算转化 → 记一条 `copy` 事件(带 openid cookie)。
**入参**:路径 `code`;body 空。**出参**:`{ "ok": true }`。
## GET /wx/oauth/cb — 微信网页授权回调(`include_in_schema=False`)
`state='base:{code}'`(静默拿 openid)或 `'uinfo:{code}'`(补昵称头像)。换 openid(+userinfo)→ upsert [`cps_wx_user`](../database/cps_wx_user.md) → 种 cookie(`wx_openid` / `wx_uinfo`,30 天)→ 302 回落地页。**任何失败兜底回落地页,绝不阻断领券**。`uinfo` 回流带 `?authed=1`,落地页据此自动触发复制(把「点领券→授权→复制」衔接成一步)。
## GET /MP_verify_*.txt — 微信「网页授权域名」归属校验(`include_in_schema=False`)
微信请求 `coupon.shaguabijia.com/MP_verify_xxx.txt` 验证域名归属;端点放域名根、返回文件名核心串(纯文本)。为微信网页授权(拿 openid)接入做准备。
## 说明
- **两阶授权**:`base` 静默拿 openid(统计主力、不打扰);`userinfo` 在用户点「领券」时触发(交互触发避免微信快照页),拿昵称/头像/unionid。
- **`cps_click` 不阻断**:落地/跳转优先级高于统计——丢几条点击可接受,挡住用户领券不可接受。
docs/api/device-liveness.md
+52
View File
@@ -0,0 +1,52 @@
# 设备 / 无障碍存活监控(device 族)
> 所属:device 组(前缀 `/api/v1/device`,源 `app/api/v1/device.py`) | 鉴权:**全部 Bearer**(设备绑登录用户) | [← 返回 API 索引](./README.md)
>
> 落库:[`device_liveness`](../database/device_liveness.md) 表;后台 `heartbeat_monitor_worker` 据此检出心跳超时的设备并召回。设计见 spec `accessibility-liveness-push.md`(推送版)+ `accessibility-liveness-pull-prompt.md`(后置 pull 提醒版)。#65 新增。
无障碍服务存活监控链路:客户端无障碍服务存活时周期上报心跳,后端发现「曾保护过、现已超时」的设备 → 召回(推送 / 客户端进 App 弹「开启自启动」引导)。
## POST /register — 注册设备 / 更新推送 token
App 前台、拿到极光 push token 时调。按 `(user_id, device_id)` upsert。
**入参(JSON)**
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `device_id` | string | ✅ | 客户端 `DeviceId.get()` 生成的 per-install id |
| `registration_id` | string \| null | ❌ | 极光推送 registration id(`JCollectionAuth` 同意后才有) |
| `platform` | string | ❌ | 默认 `android` |
| `app_version` | string \| null | ❌ | App 版本 |
**出参**:`DeviceOut`(设备当前状态)。
## POST /heartbeat — 上报心跳
无障碍服务存活时周期调(**心跳也能自注册**)。`accessibility_enabled=true` 时刷新 `last_heartbeat_at`、状态机置 `alive`、清掉线告警。
**入参(JSON)**
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `device_id` | string | ✅ | 同上 |
| `accessibility_enabled` | bool | ✅ | 本机无障碍开关当前是否开 |
| `registration_id` | string \| null | ❌ | 顺带更新 push token |
**出参**:`{ "ok": true }`。
## GET /liveness — 查本机掉线告警(后置检测)
客户端进 App 时拉:本机是否被判定掉线过(`kill_alert_pending`)。命中 → 客户端弹「开启自启动」引导,之后调 `/liveness/ack` 清。设备从未注册过 → 返回默认(无告警)。
**入参(query)**:`device_id`(string,必填)。
**出参**:`LivenessOut`(含 `kill_alert_pending` 等)。
## POST /liveness/ack — 确认已提醒(清掉线告警)
客户端已弹过引导 → 清 `kill_alert_pending`(幂等;下次真掉线 worker 再置)。
**入参(JSON)**:`{ device_id }`。
**出参**:`{ "ok": true }`。
## 错误
- `401` 未鉴权 / token 失效。
- `422` 缺 `device_id` 或字段类型不符。
## 说明
- **`kill_alert_pending` 与 `liveness_state` 解耦**:worker 检出掉线置 True,心跳恢复(`/heartbeat`)只重置 state、不动此标记,只由 `/liveness/ack` 清 → 规避「服务随 App 重启先发心跳把 state 重置回 alive、客户端进 App 漏看这次掉线」竞态。
- 心跳超时阈值由 worker 配置决定,不在接口里。
docs/api/internal.md
+31
View File
@@ -0,0 +1,31 @@
# 内部回写端点(internal 族,pricebot / 发布流程 → app-server)
> 所属:internal 组(前缀 `/internal`,源 `app/api/internal/`) | 鉴权:**`X-Internal-Secret` 头**(== `settings.INTERNAL_API_SECRET`) | [← 返回 API 索引](./README.md)
**不是给客户端的接口**:不走用户 JWT。`§6` 是 app-server 透传给 pricebot,这里反过来——pricebot(及发布流程)把少量数据 server→server 回写 app-server 落库。
## 鉴权(所有 internal 端点共用)
请求头带 `X-Internal-Secret: <密钥>`,服务端常量时间比对 `settings.INTERNAL_API_SECRET`:
- 密钥**未配置**(默认空)→ `503`(挡裸奔写端点)。
- 不匹配 / 缺失 → `401`。
- 需 pricebot 与 app-server 两边 `.env` 配**同一** `INTERNAL_API_SECRET` 才生效(未配则 pricebot 侧跳过上报、不影响比价/领券)。
## 端点
| 方法 + 路径 | 落库 | 说明 |
|---|---|---|
| `POST /internal/price-observation` | [`price_observation`](../database/price_observation.md) | 比价 done 帧整批价格事实上报;`(trace_id, platform, scope)` 幂等,返回 `{inserted, skipped}` |
| `GET /internal/store-mapping/lookup` | (只读 [`store_mapping`](../database/store_mapping.md)) | 比价前按 `source_platform`+`name`(+`lat`/`lng`)反查各目标平台已沉淀的店铺 id/deeplink;命中→pricebot 直接 deeplink 省现场搜店 |
| `POST /internal/store-mapping` | `store_mapping` | 跨平台「同一家店」身份映射上报;`trace_id` 幂等、填空合并,返回 `{inserted, row_id}` |
| `POST /internal/store-mapping/invalidate` | `store_mapping` | 标记某平台 `shop_id` 的缓存 deeplink 失效(pricebot 撞错误页回退时报);当前支持 `taobao`/`jd`,其它平台 no-op,返回 `{ok, affected}` |
| `POST /internal/launch-confirm-sample` | [`launch_confirm_sample`](../database/launch_confirm_sample.md) | 启动确认窗 LLM 兜底放行后回写样本(host 包 + 弹窗树 + plan + locale);**都上报、不去重**,返回 `{id}` |
| `POST /internal/app-version` | [`app_config`](../database/app_config.md)(key=`latest_app_version`) | **发布流程**(非 pricebot)出 APK 后写最新版本号/下载链接/sha256;客户端再 `GET /api/v1/platform/app-version` 读做 OTA。也是应急改版本信息(紧急下线/改 `apk_url`)入口 |
## 错误
- `401` 密钥不匹配 / 缺失。
- `503` `INTERNAL_API_SECRET` 未配置。
- `422` 请求体字段校验失败。
## 说明
- 与不鉴权的比价透传(`compare.py` / `coupon.py`)无关:那两个是**客户端→server** 的透传壳,这里是 **server→server** 的内部写库。
- `launch-confirm-sample` 的样本供研发**人工**定期沉淀进 pricebot 的 `launch_confirm.PROFILES` 静态规则(让以后同款启动窗回到快路径,不必再调 LLM)。
docs/database/OVERVIEW.md
+19 -7
View File
@@ -2,7 +2,7 @@
> 跨表视角。单表字段级细节看同目录 `<表名>.md`(索引见 [README](./README.md))。
> 本文专门回答三件「跨表」的事:**① 每块 App 功能用到哪些表 ② 什么操作往哪张表写 ③ 表和表怎么连(join key,含没有外键约束、靠业务字段对齐的语义关联)**。
> **范围**:业务表全部在 `shaguabijia-app-server`(SQLAlchemy 2.0 + SQLite 开发 / PostgreSQL 生产)。`pricebot-backend`(比价/领券 Agent)是纯内存态、**无任何表**;Android 客户端只有 EncryptedSharedPreferences / SharedPreferences、**无关系库**。共 **37 张业务表** + `alembic_version`(框架的迁移版本指针)。注意「比价/领券**过程**」始终在 pricebot 内存态跑、**不落库**——只有**结果**回 app-server 才落库:领券结果落 `coupon_*` 三张今日状态表;比价结果分两路——客户端带 JWT 上报「我的记录」落 `comparison_record`,pricebot 另经 `app/api/internal/` server→server 把客观价格/门店事实落 `price_observation`/`store_mapping`(不鉴权、匿名也记)。此外好友邀请(`invite_*` 2 张)与美团 CPS 群发联盟(`cps_*` 5 张)是两个独立子系统。
> **范围**:业务表全部在 `shaguabijia-app-server`(SQLAlchemy 2.0 + SQLite 开发 / PostgreSQL 生产)。`pricebot-backend`(比价/领券 Agent)是纯内存态、**无任何表**;Android 客户端只有 EncryptedSharedPreferences / SharedPreferences、**无关系库**。共 **40 张业务表** + `alembic_version`(框架的迁移版本指针)。注意「比价/领券**过程**」始终在 pricebot 内存态跑、**不落库**——只有**结果**回 app-server 才落库:领券结果落 `coupon_*` 三张今日状态表;比价结果分两路——客户端带 JWT 上报「我的记录」落 `comparison_record`,pricebot 另经 `app/api/internal/` server→server 把客观价格/门店事实落 `price_observation`/`store_mapping`(不鉴权、匿名也记)+ 启动确认窗兜底样本落 `launch_confirm_sample`。此外好友邀请(`invite_*` 2 张)与美团 CPS 群发联盟(`cps_*` 6 张,含落地页微信身份 `cps_wx_user`)是两个独立子系统。无障碍存活监控 `device_liveness`(#65)按用户设备维度记心跳、检掉线召回。
---
@@ -18,6 +18,7 @@
| 「上报更低价」提交 / 列表 | [`price_report`](./price_report.md) | 众包纠偏:用户举证某平台更便宜,人工审核发奖 |
| (无 App UI)比价 done 后客观价格沉淀 | [`price_observation`](./price_observation.md) | **pricebot server→server 内部上报**;平台/门店视角的到手价事实,匿名也记,与 `comparison_record`(用户视角)互补 |
| (无 App UI)跨平台门店身份映射 | [`store_mapping`](./store_mapping.md) | **pricebot 内部上报**;同店在淘宝/美团/京东的 id/名/deeplink,供下次比价 `lookup` 反查省掉现场搜店 |
| (无 App UI)启动确认窗兜底样本 | [`launch_confirm_sample`](./launch_confirm_sample.md) | **pricebot 内部上报**;LLM 兜底放行「想要打开 XX」跨 App 启动窗后回写样本(host 包 + 弹窗树 + plan + locale),供研发人工沉淀进 pricebot 规则 |
### 领券(每日领券联动 · 今日状态)
| App 位置 / 动作 | 表 | 说明 |
@@ -47,6 +48,7 @@
| 登录(极光/短信)/ 改资料 / 注销 | [`user`](./user.md) | 登录主体,注册即登录 |
| 新手引导是否再展示 | [`onboarding_completion`](./onboarding_completion.md) | 按 设备+账号 去重;登录响应回 `onboarding_completed`,走完引导时标记,跨卸载重装 |
| 帮助与反馈 | [`feedback`](./feedback.md) | 含截图,后台人工处理 |
| 无障碍存活监控 / 掉线召回 | [`device_liveness`](./device_liveness.md) | 无障碍服务周期心跳;worker 检出心跳超时 → 推送/客户端进 App 弹「开启自启动」引导 |
### 好友邀请(注册增长)
| App 位置 / 动作 | 表 | 说明 |
@@ -61,6 +63,7 @@
| 运营建微信推广群 | [`cps_group`](./cps_group.md) | 一群一行,`sid`=美团二级渠道追踪位 |
| 后台批量生成群发短链 | [`cps_link`](./cps_link.md) | 群×活动 → `/c/{code}`,运营复制到微信群 |
| 用户点短链(落地/复制口令) | [`cps_click`](./cps_click.md) | 记 visit/copy 事件,统计 PV/UV |
| 微信内打开落地页授权 | [`cps_wx_user`](./cps_wx_user.md) | 服务号网页授权拿 openid(base 静默)/ 昵称头像 unionid(userinfo,点领券触发),记首次来源群 |
| 定时拉美团联盟订单对账 | [`cps_order`](./cps_order.md) | `query_order` 按 sid 归群,串成点击→下单→佣金漏斗 |
### 运营后台 admin(独立子应用 `app/admin/`,端口 8771,独立鉴权)
@@ -95,6 +98,9 @@
| 看广告时长上报 `POST /ad/watch-report` | `ad_watch_log`(C) | |
| 广告 eCPM 上报 `POST /ad/ecpm-report` | `ad_ecpm_record`(C) | |
| 信息流广告结算 `POST /ad/feed-reward` | `ad_feed_reward_record`(C)+ granted→`coin_account`(U)+`coin_transaction`(C `feed_ad_reward`) | `client_event_id` 幂等 |
| 注册设备 / 更新 push token `POST /device/register` | `device_liveness`(C/U upsert) | `(user_id, device_id)` 幂等;只在传入非空时更新 `registration_id`/版本 |
| 无障碍服务心跳 `POST /device/heartbeat` | `device_liveness`(C/U) | 心跳也能自注册;`accessibility_enabled=true` 时刷 `last_heartbeat_at`、置 `alive`、清 `notified_at` |
| 客户端 ack 掉线提醒 `POST /device/liveness/ack` | `device_liveness`(U) | 清 `kill_alert_pending`(幂等;下次真掉线 worker 再置) |
| 比价 done 上报 `POST /compare/record` | `comparison_record`(C 或 U) | `(user_id, trace_id)` 幂等覆盖 |
| 领里程碑 `POST /compare/milestone/claim` | `comparison_milestone_claim`(C) | **当前不发币**(coin_awarded=0) |
| 支付归因上报 `POST /order/report` | `savings_record`(C `source=compare`) | `(user_id, client_event_id)` 幂等 |
@@ -130,22 +136,25 @@
| 运营后台建活动 / 建群 | `cps_activity`(C/U) / `cps_group`(C/U) | `app/admin/routers/cps.py`;群含美团平台才分配 `sid` |
| 后台批量生成短链 `POST /admin/api/cps/referral-links` | `cps_link`(C) | 每 群×活动 一条;美团经 `sid` 转链拿 `target_url`(同群同活动重复生成产生多条) |
| 用户点群发短链 `GET /c/{code}` / `POST /c/{code}/copy` | `cps_click`(C `visit`/`copy`) | 公开端点不鉴权;`group_id`/`sid` 从 link 冗余进来免 join |
| 微信落地页授权回调 `GET /wx/oauth/cb` | `cps_wx_user`(C/U upsert) | 按 `openid` 幂等;base 拿 openid,userinfo 补昵称/unionid(非 None 才覆盖);任何失败兜底回落地页不阻断领券 |
| 定时拉美团联盟订单对账 | `cps_order`(C/U upsert) | `query_order` 按 `sid` 归群;`order_id` 幂等(状态会变,重复拉则更新) |
| pricebot 比价 done 内部上报 `POST /internal/price-observation` | `price_observation`(C 批量) | `(trace_id,platform,scope)` 幂等;**不走 JWT、靠 `X-Internal-Secret`**(未配→503) |
| pricebot 比价 done 内部上报 `POST /internal/store-mapping` | `store_mapping`(C/U 填空合并) | `trace_id` 幂等;另有 `lookup` 反查 + `invalidate` deeplink 失效标记(淘宝/京东) |
| pricebot LLM 兜底放行启动确认窗后上报 `POST /internal/launch-confirm-sample` | `launch_confirm_sample`(C) | **都上报、不去重**;靠 `X-Internal-Secret`(未配→503) |
| 后台 worker 检出心跳超时 `heartbeat_monitor_worker` | `device_liveness`(U `mark_notified`) | 置 `notified` + `notified_at` + `kill_alert_pending=True`;非 C 端、非 admin,定时扫 `list_overdue` |
> CPS 5 表与本 App `user` **无关**(被推广群的用户在美团下单,不是本 App 注册用户);`price_observation`/`store_mapping` 的 `source_user_id` 是可空旁路(链路不鉴权,匿名也记)。
> CPS 6 表与本 App `user` **无关**(被推广群的用户在美团下单 / 在微信落地页授权,不是本 App 注册用户;`cps_wx_user` 是微信 `openid` 维度的另一套用户身份);`price_observation`/`store_mapping`/`launch_confirm_sample` 的 `source_user_id`/`device_id` 是可空旁路(链路不鉴权,匿名也记)。
---
## 三、表间关系 & Join Key
### 硬外键(数据库 FK 约束)
- **17 张用户维度表 `.user_id` → `user.id`**:`coin_account`(同时是 PK)、`coin_transaction`、`cash_transaction`、`withdraw_order`、`wechat_transfer_authorization`(同时是 PK)、`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`。
- **18 张用户维度表 `.user_id` → `user.id`**:`coin_account`(同时是 PK)、`coin_transaction`、`cash_transaction`、`withdraw_order`、`wechat_transfer_authorization`(同时是 PK)、`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`、`device_liveness`。
- `admin_audit_log.admin_id` → `admin_user.id`。
- `price_report.comparison_record_id` → `comparison_record.id`(可空:关联记录被删后仍留上报历史)。
- **邀请两表** → `user.id`:`invite_relation.inviter_user_id`、`invite_relation.invitee_user_id`(唯一)、`invite_fingerprint.inviter_user_id`——注意 FK 列名是 `inviter`/`invitee_user_id`,不是 `user_id`。
- **CPS 5 表 + 比价沉淀 2 表均无硬 FK**(全靠 `sid`/`trace_id` 语义对齐,见下)。
- **CPS 6 表 + 比价沉淀 2 表 + `launch_confirm_sample` 均无硬 FK**(全靠 `sid`/`trace_id`/`openid` 语义对齐,见下)。
### 语义 join key(无 FK 约束,靠业务字段对齐 —— 排障/对账必看)
- **`coin_transaction.ref_id` 指向随 `biz_type` 变**:
@@ -172,7 +181,7 @@
- **里程碑解锁进度不存库**:`comparison_milestone_claim` 只记「哪几档已领」;进度 = `comparison_record` 里 `status='success'` 的 `count`。
- **领券三表无硬 FK,全靠软关联**:`coupon_prompt_engagement` / `coupon_daily_completion` / `coupon_claim_record` 的 `user_id` **软指** `user.id`(可空、有登录态才记、不进唯一键、不阻塞判断);`trace_id` **软指** pricebot work_logs(排查回指);唯一键都以 `device_id` + 北京自然日为主(详见 [`coupon_state.md`](./coupon_state.md))。
- **`onboarding_completion.(user_id, device_id)`**:`user_id` 语义关联 `user.id`(无硬 FK,同 `coupon_*` 设备表),`device_id` = 客户端硬件级 `ANDROID_ID`(≠ 领券 per-install `device_id`)。登录读、走完引导写,决定是否再展示新手引导。
- **CPS 群发 5 表全靠 `sid` / id 语义串联(无硬 FK)**:`cps_link.group_id`→`cps_group.id`、`cps_link.activity_id`→`cps_activity.id`、`cps_click.link_id`→`cps_link.id`;**点击与订单无法对到单笔**,只在群维度(`sid`)汇合——`cps_order.sid` ≈ `cps_group.sid` ≈ `cps_link.sid` ≈ `cps_click.sid`(仅美团有 sid,淘宝/京东无)。统计按群聚合,故 `group_id`/`sid` 冗余进 `cps_click` 免 join。
- **CPS 群发 6 表全靠 `sid` / id / `openid` 语义串联(无硬 FK)**:`cps_link.group_id`→`cps_group.id`、`cps_link.activity_id`→`cps_activity.id`、`cps_click.link_id`→`cps_link.id`、`cps_wx_user.first_group_id`→`cps_group.id`;**点击与订单无法对到单笔**,只在群维度(`sid`)汇合——`cps_order.sid` ≈ `cps_group.sid` ≈ `cps_link.sid` ≈ `cps_click.sid`(仅美团有 sid,淘宝/京东无)。统计按群聚合,故 `group_id`/`sid` 冗余进 `cps_click` 免 join。`cps_wx_user` 按 `openid` 自成用户身份维度,与 `cps_click`/`cps_order` 无 id 级 join。
- **比价沉淀两表(`price_observation` / `store_mapping`)**:`trace_id` 软指 pricebot work_logs(与 `comparison_record.trace_id` 同源但不互 join,各存各视角);`source_user_id` / `source_device_id` 软指用户/设备(可空,匿名也记)。`store_mapping.lookup` 靠**店名字符串精确相等** + geo 取最近,非 id 级 join。
### ER 关系(文字版)
@@ -182,7 +191,8 @@ user ─1:1─ wechat_transfer_authorization
user ─1:N─ { coin_transaction, cash_transaction, withdraw_order, 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 }
price_report, feedback, device_liveness }
(device_liveness 硬 FK; (user_id,device_id) 唯一)
user ─1:N─ onboarding_completion (user_id, 无硬 FK; (user_id,device_id) 去重)
comparison_record ─1:N─ price_report (comparison_record_id, 可空)
admin_user ─1:N─ admin_audit_log
@@ -192,8 +202,10 @@ coupon_prompt_engagement / coupon_daily_completion / coupon_claim_record
user ─1:N─ invite_relation (inviter_user_id 硬 FK); invitee_user_id ─1:1─ user (唯一硬 FK)
user ─1:N─ invite_fingerprint (inviter_user_id 硬 FK)
cps_activity / cps_group ──语义(无FK)──▶ cps_link ─1:N─ cps_click
(CPS 5 表自成子系统; cps_order 经 sid 归群对账, 与本 App user 无关)
(CPS 6 表自成子系统; cps_order 经 sid 归群对账, 与本 App user 无关)
cps_group ◀──语义(无FK)── cps_wx_user (first_group_id; openid 维度的微信落地页用户身份)
price_observation / store_mapping (独立, 无硬 FK; 维度=trace_id, source_user/device 仅软关联; pricebot 内部上报)
launch_confirm_sample (独立, 无硬 FK; 都上报不去重; pricebot 内部上报启动确认窗兜底样本)
```
---
docs/database/README.md
+6 -3
View File
@@ -3,13 +3,13 @@
> 数据库: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-06-17(补全 9 张此前缺文档的表:CPS 群发 5 张 `cps_*` + 好友邀请 2 张 `invite_*` + 比价沉淀 `price_observation`/`store_mapping`;并全表 review 对齐 model——`signin_record` 改 7 天循环、`coupon_prompt_engagement` 加 `package` 列按 App 频控、`user` 补 `username`/`invite_code`/`debug_trace_enabled` 等;含 [OVERVIEW 总览](./OVERVIEW.md))
> 最后更新:2026-06-23(补 3 张表文档:`device_liveness`(#65 无障碍存活监控)、`cps_wx_user`(CPS 落地页微信身份)、`launch_confirm_sample`(启动确认窗兜底样本);`comparison_record` 补 `input_tokens`/`output_tokens`。上一次 2026-06-17 补全 CPS 群发 5 张 `cps_*` + 好友邀请 2 张 `invite_*` + 比价沉淀 `price_observation`/`store_mapping` 并全表 review 对齐 model;含 [OVERVIEW 总览](./OVERVIEW.md))
> 🧭 **先看 [OVERVIEW.md — 表 × 功能 × 关系](./OVERVIEW.md)**:跨表的「每块功能用哪些表 / 什么操作写哪张表 / 表间 join key」都在那;本页只做**单表索引**,点进每张表的详情看字段级说明。
---
## 表总览(37 张业务表 + `alembic_version` 框架表)
## 表总览(40 张业务表 + `alembic_version` 框架表)
### 账号 / 反馈
| 表 | 用途 | 模型 | 文档 |
@@ -17,6 +17,7 @@
| `user` | 用户(登录主体);几乎所有表的外键宿主 | `models/user.py` | [详情](./user.md) |
| `onboarding_completion` | 新手引导完成标记(按 设备+账号 去重,登录时据此跳过引导) | `models/onboarding.py` | [详情](./onboarding_completion.md) |
| `feedback` | 用户帮助与反馈(含截图) | `models/feedback.py` | [详情](./feedback.md) |
| `device_liveness` | 无障碍存活监控(心跳超时检出 + 掉线召回;`(user_id, device_id)` 唯一) | `models/device.py` | [详情](./device_liveness.md) |
### 好友邀请(注册增长)
| 表 | 用途 | 模型 | 文档 |
@@ -53,6 +54,7 @@
|---|---|---|---|
| `price_observation` | 价格观测(平台/门店视角的到手价事实,匿名也记;`comparison_record` 的客观对照) | `models/price_observation.py` | [详情](./price_observation.md) |
| `store_mapping` | 跨平台「同一家店」id/名/deeplink 身份映射(淘宝/美团/京东,供 lookup 反查省现场搜店) | `models/store_mapping.py` | [详情](./store_mapping.md) |
| `launch_confirm_sample` | 启动确认窗 agent 兜底样本(pricebot LLM 放行跨 App 启动窗后回写,供研发人工沉淀规则) | `models/launch_confirm_sample.py` | [详情](./launch_confirm_sample.md) |
### 领券(每日领券联动 · 今日状态)
| 表 | 用途 | 模型 | 文档 |
@@ -73,6 +75,7 @@
| `cps_group` | 推广微信群(`sid`=美团二级渠道追踪位,订单按 sid 归群对账) | `models/cps_group.py` | [详情](./cps_group.md) |
| `cps_link` | 群发短链 `/c/{code}`(群×活动生成,302 跳/淘宝落地页) | `models/cps_link.py` | [详情](./cps_link.md) |
| `cps_click` | 短链点击事件流(visit/copy,PV/UV 漏斗源) | `models/cps_link.py` | [详情](./cps_click.md) |
| `cps_wx_user` | CPS 落地页微信用户身份(openid 维度;网页授权拿 openid/昵称/unionid,记首次来源群) | `models/cps_wx_user.py` | [详情](./cps_wx_user.md) |
| `cps_order` | 美团联盟 query_order 拉回的对账订单(按 sid 归群算佣金) | `models/cps_order.py` | [详情](./cps_order.md) |
### 首页门面数据
@@ -93,7 +96,7 @@
## 通用约定
- **主键**:`id` Integer autoincrement;例外:`coin_account` / `wechat_transfer_authorization` 的 `user_id` 既是主键也是外键(一用户一行),`app_config` 用 `key` 作主键。
- **外键**:所有用户维度表 `user_id` → `user.id` 且建 index;`admin_audit_log.admin_id` → `admin_user.id`;`price_report.comparison_record_id` → `comparison_record.id`。
- **外键**:所有用户维度表 `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`。
docs/database/comparison_record.md
+2
View File
@@ -37,6 +37,8 @@
| `comparison_results` | JSON(PG: JSONB) | NOT NULL, default [] | 逐平台对比 `[{platform_id,platform_name,package,price(元),is_source,rank,coupon_saved(元),coupon_name,applied_coupons}]`;`coupon_saved`=该平台主优惠额(美团红包/淘宝平台红包/京东百亿补贴,只取一笔),`coupon_name`=优惠来源名(展示用),`applied_coupons`=`[{name,amount}]` 多券明细 |
| `skipped_dish_names` | JSON(PG: JSONB) | NOT NULL, default [] | 被跳过的菜名 |
| `raw_payload` | JSON(PG: JSONB) | nullable | 客户端原始上报全量(calibration + done.params),取数兜底 |
| `input_tokens` | Integer | nullable | 本次 LLM 累计输入 token = Σ `llm_calls[].usage.prompt_tokens`(server 收上报后从 `llm_calls` 累加;旧记录/未采集为 null) |
| `output_tokens` | Integer | nullable | 本次 LLM 累计输出 token = Σ `llm_calls[].usage.completion_tokens`(同上) |
| `created_at` | DateTime(tz) | server_default now(), index | 时间 |
> `ordered`(已下单)是**瞬态字段**,不在表里:`list_records` 读取时按 `store_name ∈ 该用户 source='compare' 的 savings_record.shop_name 集合` 现挂到实例上供出参用。
docs/database/cps_wx_user.md
+37
View File
@@ -0,0 +1,37 @@
# cps_wx_user — CPS 落地页微信用户身份(openid 维度)
> 模型 `app/models/cps_wx_user.py`(`CpsWxUser`) · 仓库 `app/repositories/cps_wx_user.py`(`get_by_openid` / `upsert`) · 接口 `GET /wx/oauth/cb`(微信网页授权回调,`app/api/v1/cps_redirect.py`) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
用户在微信内打开群发短链落地页 [`/c/{code}`](./cps_link.md),经服务号网页授权拿到的微信身份,按 `openid` 唯一存一行。在 CPS 群发漏斗里,它给点击/领券补上**「是谁」**这一维度(此前 [`cps_click`](./cps_click.md) 只有 PV/UV 近似)。授权分两阶:`snsapi_base` 静默拿 `openid`(统计主力);用户点「领券」触发 `snsapi_userinfo` 才补 `nickname`/`headimgurl`/`unionid`。
> 注意:**下单归因到人**需 user-level sid(另一期),本表只承载身份 + 领券/点击侧,**不与 `cps_order` 关联**。
## 用在哪 / 增删改查
- **C / U(upsert)**:`upsert`(`get_by_openid` 查 → 无则建、有则补),由 `wx_oauth_cb`(`GET /wx/oauth/cb`)在微信授权回调里调。首次建行记来源 `first_code`/`first_group_id`;已存在则**仅在传入非 None 时**更新 `nickname`/`headimgurl`/`unionid`(`base` 阶段为 None,不覆盖已有画像),并显式刷新 `last_seen`(`onupdate` 仅字段有变更才触发,故 base-only 回访也要手动 set)。任何授权失败兜底回落地页,**绝不阻断领券**。
- **R**:`get_by_openid`(upsert 内部按 openid 查)。
- **D**:无。
## 字段
| 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
|---|---|---|---|
| `id` | Integer | PK, autoincrement | |
| `openid` | String(64) | **UNIQUE**, index, NOT NULL | 服务号下用户唯一标识(网页授权拿到);upsert 主键 |
| `unionid` | String(64) | index, nullable | 开放平台 unionid(服务号绑开放平台 + `scope=userinfo` 才有);跨 App/服务号统一用户 |
| `nickname` | String(128) | nullable | 昵称;`userinfo` 授权后才有(base 阶段为空) |
| `headimgurl` | String(512) | nullable | 头像 URL;同 `nickname`,userinfo 阶段才有 |
| `first_code` | String(16) | nullable | 首次进入来源短链 code(从哪个群的链接授权进来) |
| `first_group_id` | Integer | index, nullable | 首次来源群 = `cps_group.id`(语义关联,非 FK);群内用户级统计用 |
| `first_seen` | DateTime(tz) | server_default now() | 首次授权时间 |
| `last_seen` | DateTime(tz) | server_default now(), onupdate now() | 最近一次落地(upsert 时显式刷新) |
## 关系 / Join Key
- `first_group_id` → `cps_group.id`(**语义关联,无 ForeignKey**;记首次来源群)。
- 与 [`cps_click`](./cps_click.md) **无 id 级 join**:点击事件流目前不回写 openid 维度的用户统计,两者各按各的维度看(cps_click 看 PV/UV,本表看「谁」)。
- 与本 App `user` 表**无关**:微信落地页用户不是本 App 注册用户(同 CPS 其它表)。
## 索引与约束
- PK `id`;UNIQUE index `openid`;index `unionid`、`first_group_id`。
## 注意
- **两阶授权**:`base`(静默)只能拿 `openid`,不弹窗、不打扰,用作统计主力;`userinfo`(弹授权页)拿昵称头像 + unionid,只在用户点「领券」这种有交互的时刻触发(避免微信快照页),授权回流带 `?authed=1` 自动衔接复制口令。详见 `cps_redirect.py` 落地页逻辑。
- **`unionid` 不一定有**:需服务号已绑微信开放平台 + 走到 `userinfo` 授权;base 阶段、未绑开放平台时为 None。
docs/database/device_liveness.md
+43
View File
@@ -0,0 +1,43 @@
# device_liveness — 无障碍存活监控(心跳 + 掉线召回)
> 模型 `app/models/device.py`(`DeviceLiveness`) · 仓库 `app/repositories/device.py`(`register_or_update` / `touch_heartbeat` / `list_overdue` / `mark_notified` / `get_device` / `ack_kill_alert`) · 接口 用户 `POST /api/v1/device/register`、`POST /api/v1/device/heartbeat`、`GET /api/v1/device/liveness`、`POST /api/v1/device/liveness/ack`(`app/api/v1/device.py`);后台 worker `heartbeat_monitor_worker` · [← 索引](./README.md) · [总览](./OVERVIEW.md)
每行 = 一个用户的一台设备(per-install,`(user_id, device_id)` 唯一)。客户端无障碍服务存活时周期上报心跳刷新 `last_heartbeat_at`;App 前台/登录拿到极光 push token 时上报 `registration_id`。后端 `heartbeat_monitor_worker` 扫「曾保护过、现已心跳超时」的设备,推送(或本期仅终端打印)提醒用户重开无障碍。**表名不叫 `device`**:它存的不是设备信息(品牌/型号),而是**无障碍存活状态**。#65 新增。
> 设计见 spec `spec/accessibility-liveness-push.md`(推送版)+ `spec/accessibility-liveness-pull-prompt.md`(后置 pull 提醒版)。
## 用在哪 / 增删改查
- **C / U(upsert)**:`register_or_update`(`POST /device/register`,App 拿到 push token 时调)按 `(user_id, device_id)` upsert,只在传入非空时更新 `registration_id`/`platform`/`app_version`;`touch_heartbeat`(`POST /device/heartbeat`,无障碍服务存活时周期调,**心跳也能自注册**)在 `accessibility_enabled=true` 时刷 `last_heartbeat_at`、置 `ever_protected=true`、状态机重置回 `alive`、清 `notified_at`(掉线恢复→下次再断才再推一条)。
- **U(worker)**:`mark_notified`(`heartbeat_monitor_worker` 检出掉线后)置 `liveness_state='notified'` + `notified_at` + **`kill_alert_pending=True`**;`ack_kill_alert`(`POST /device/liveness/ack`,客户端弹过引导后)清 `kill_alert_pending`(幂等)。
- **R**:`list_overdue`(worker 扫描:`ever_protected=true` + `liveness_state='alive'` + `last_heartbeat_at` 早于 `now - timeout`)→ 掉线设备列表;`get_device`(`GET /device/liveness`,客户端进 App 拉本机是否被判掉线过)。
- **D**:无。
## 字段
| 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
|---|---|---|---|
| `id` | Integer | PK, autoincrement | |
| `user_id` | Integer | **FK→user.id**, index, NOT NULL | 归属用户 |
| `device_id` | String(128) | index, NOT NULL | 客户端 `DeviceId.get()` 生成的 per-install id(如 `device_Pixel_ab12cd34`) |
| `registration_id` | String(64) | nullable | 极光推送 registration id;`JCollectionAuth` 同意后才下发,拿到才填 |
| `platform` | String(16) | NOT NULL, default `android` | |
| `app_version` | String(32) | nullable | 上报时 App 版本 |
| `ever_protected` | Boolean | NOT NULL, default false | 收到过 service 心跳即 true(=该设备开过无障碍,功能对它有意义)。`list_overdue` 的过滤前提 |
| `last_heartbeat_at` | DateTime(tz) | index, nullable | 最近一次 service 心跳时间(存活证明);超时即视为保护掉线 |
| `last_report_protection_on` | Boolean | NOT NULL, default false | 最近一次上报的无障碍开关状态(观测用) |
| `liveness_state` | String(16) | NOT NULL, default `unknown` | 状态机:`unknown` → `alive`(收到 service 心跳)→ `silent`/`notified`(扫描发现超时并已推送);心跳恢复 handler 重置回 `alive` |
| `notified_at` | DateTime(tz) | nullable | 最近一次推送告警时间 |
| `kill_alert_pending` | Boolean | NOT NULL, default false | 掉线告警「待客户端提醒」标记(后置 pull 版)。**与 `liveness_state` 解耦**:worker 检出掉线即置 True;`touch_heartbeat`(心跳恢复)不动它;只由客户端 ack 清 |
| `created_at` | DateTime(tz) | server_default now() | |
| `updated_at` | DateTime(tz) | server_default now(), onupdate now() | |
## 关系 / Join Key
- `user_id` → `user.id`(多对一,**硬外键**)。
- 与 `comparison_record.device_id` 等表的 `device_id` **同源**(都来自客户端 per-install id),但本表无 id 级 join。
## 索引与约束
- PK `id`;index `user_id`、`device_id`、`last_heartbeat_at`;UNIQUE(`user_id`, `device_id`) = `uq_device_liveness_user_device`(一用户一设备一行,upsert 幂等键)。
## 注意
- **`kill_alert_pending` 为什么和 `liveness_state` 解耦**:服务随 App 重启会先发心跳把 `state` 重置回 `alive`,若复用 `state` 判「待提醒」,客户端进 App 这一刻可能恰好已被重置 → 漏看这次掉线。故另设一个只由 worker 置、只由客户端 ack 清的标记,规避竞态。
- **`list_overdue` 本期不要求有 `registration_id`**:本期只做终端打印检测、未真推送,没接极光 token 的设备也要检出。
- 心跳超时阈值由 worker 的 `timeout_minutes` 决定(不在表里)。
docs/database/launch_confirm_sample.md
+36
View File
@@ -0,0 +1,36 @@
# launch_confirm_sample — 启动确认窗 agent 兜底样本
> 模型 `app/models/launch_confirm_sample.py`(`LaunchConfirmSample`) · 仓库 `app/repositories/launch_confirm_sample.py`(`insert_sample`) · 接口 `POST /internal/launch-confirm-sample`(pricebot→app-server,`app/api/internal/launch_confirm.py`,`X-Internal-Secret` 校验) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
pricebot 的 `launch_confirm_agent` 每次「静态 PROFILES 没认出、靠 LLM 兜底放行」一个跨 App 启动确认窗(繁体 / 英文 / 小语种 / ROM 改版的「想要打开 XX」弹窗)时,把完整样本 server→server 落这里。研发定期**人工**把 `exec_success=true` 的样本沉淀进 pricebot 的 `launch_confirm.PROFILES`(静态快路径),让以后同款窗不必再调 LLM(回到快路径)。
> **不是给客户端的接口**:与登录无关、不鉴权,靠共享密钥头 `X-Internal-Secret`(== `settings.INTERNAL_API_SECRET`)校验,未配置则 503。
## 用在哪 / 增删改查
- **C(插入)**:`insert_sample`(`POST /internal/launch-confirm-sample`)。**都上报、不去重**(by design):同一种窗多台机器上报多条,研发按 `host_package`/`system_locale` 聚合后人工筛。大字段截断到列长上限(繁体长标题等),空串入库为 None。
- **R / U / D**:**无**(研发查库靠 SQL 直接看 + 人工沉淀,不经本服务接口)。
## 字段
| 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
|---|---|---|---|
| `id` | Integer | PK, autoincrement | |
| `created_at` | DateTime(tz) | server_default now(), index | 上报时间 |
| `trace_id` | String(64) | index, nullable | pricebot 侧 trace_id:回指原始 trace,可去 `price.shaguabijia.com` 查完整上下文 |
| `device_id` | String(64) | index, nullable | 上报设备 |
| `host_package` | String(128) | index, nullable | 弹窗宿主包(= 触发判据,也是研发沉淀进 `PROFILES.host_packages` 的键)。**按它聚合人工筛** |
| `target_app` | String(128) | nullable | 被打开的目标 App 包名(标题里「想要打开 X」的 X 是变量,据此把它从 sign 里挖空) |
| `system_locale` | String(32) | index, nullable | 系统语言地区(`zh-TW`/`en-US`…)—— 多语言问题的核心维度。⚠️ 前端 `AgentStepRequest` 暂未上报设备信息 → **现恒 None**,待前端加 `device_info` 字段后回填 |
| `exec_success` | Boolean | NOT NULL, default false | 这次兜底是否成功放行(弹窗消失=true;放弃 / LLM 没认出=false)。**研发只沉淀 true 的** |
| `dialog_title` | String(256) | nullable | 弹窗标题全文(研发据此提 `launch_sign`),如「『傻瓜比价』想要開啟『京東』」 |
| `payload` | JSON(PG: JSONB) | nullable | 完整样本大 JSON:`{is_launch_confirm, llm_model, llm_reason, plan, dialog_tree, device_info:{screen,locale,brand,model,android_version,rom_version}}`。加字段不必迁移 schema |
## 关系 / Join Key
- 无外键。`trace_id` 软指 pricebot trace(回指排查),`device_id` 软指设备;均不与本服务其它表 join。
## 索引与约束
- PK `id`;index `created_at`、`trace_id`、`device_id`、`host_package`、`system_locale`。
- **无唯一约束**(by design 不去重,见上)。
## 注意
- **PG 上 `payload` 用 JSONB**(可建 GIN 索引),SQLite(本地/测试)退化为通用 `JSON`(同 `price_observation`、`comparison_record`)。
- **为什么大字段塞 `payload` 而非拆列**:弹窗树快照 + LLM plan + 设备信息都是「研发偶尔人工看」的兜底数据,拆列会让每次扩样本字段都要迁移 schema;只把聚合/筛选要用的维度(`host_package`/`system_locale`/`exec_success`)提成结构化列建索引。
docs/database/数据库迁移.md
+10 -16
View File
@@ -92,23 +92,15 @@ alembic upgrade head
- 生成后**手动把文件名前缀去掉**（内部 id 别动）；或
- 在 `alembic.ini` 配 `file_template = %%(slug)s`（注意 ini 里 `%` 要写成 `%%`）让以后直接生成无前缀文件名（缺点：同名 slug 会冲突，描述写具体点）。
## 6. 当前迁移链(12 条,含合并迁移)
## 6. 当前迁移链(规模与当前 head)
- `alembic/versions/` 当前约 **78 个迁移文件**(含 14 个合并迁移),从 `init_user_table`(`down_revision=None`)起一路接到当前单一 head。**别背具体链**——它随每次改表增长,看实时输出:
```bash
ls alembic/versions/*.py | wc -l # 迁移文件数
alembic history # 完整链(按 down_revision,不是文件名字母序)
alembic heads # 当前 head(正常只 1 个)
```
init_user_table ← 起点(down_revision=None)
→ welfare_tables_coin_account_coin_txn 金币账户/金币流水/签到/任务表
→ cash_transaction_table 现金流水表
→ savings_record_table 省钱明细表
→ withdraw_order_and_user_openid 提现单表 + user.wechat_openid
→ user_wechat_nickname_avatar user 微信昵称/头像字段
→ unique_wechat_openid user.wechat_openid 唯一约束
→ savings_shop_dishes 省钱明细 shop_name + dishes
→ ad_reward_record 看广告发奖记录表
→ (此处分叉,两条并行 head)
├→ feedback_table 帮助与反馈表(PR #4)
└→ ef96beb47b1e_convert_savings_record_dishes_from_json dishes 列改 JSONB(PR #6)
→ f01db5d77dac_merge_pg_jsonb_and_feedback_heads (head,最新) 合并两条分叉
```
> 顺序以 `alembic history` 输出为准（按 `down_revision` 链，不是文件名字母序）。
- **当前 head**(2026-06-23):`4dc2af7ebe74`(文件 `4dc2af7ebe74_merge_device_65_and_comparison_token_.py`)——它合并了今日两条并行链:`comparison_token_cols`(#a584e1f,`comparison_record` 加 `input_tokens`/`output_tokens`)与 #65 device 链末端(`device_liveness` 表 + `ad_feed_reward_trace_id`)。即 `down_revision = ('comparison_token_cols', 'ad_feed_reward_trace_id')`。
- 频繁多 head 是常态(多人/多分支并行改表),靠合并迁移收敛回单 head,详见下面「踩坑 → 多 head 分叉」。
## 7. 踩坑
@@ -128,6 +120,8 @@ please specify a specific target revision, '<branchname>@head'...
- PR #6 (PG/JSONB) 加了 `ef96beb47b1e`,`down_revision='c8d9e0f1a2b3'`(也是 ad_reward) ← 跟 #4 同源,撞车
- 两个 PR 都合进 main 后,`alembic heads` 出现两个
> 此后这种合并是常态,每次都用 `alembic merge` 收敛。最近一次(2026-06-23):#65 device 链(`device_table` → `device_kill_alert_pending`,经 `ad_feed_reward_trace_id`)与 `comparison_token_cols`(`comparison_record` 加 token 列)并行,用 `4dc2af7ebe74_merge_device_65_and_comparison_token_.py` 合成单一 head。
**修复**:
```bash
alembic heads # 列出冲突的两个 head id
docs/后端技术实现.md
+27 -27
View File
@@ -3,7 +3,7 @@
> 域名:`app-api.shaguabijia.com`(HTTPS,nginx 反代)
> 仓库:`shaguabijia-app-server`
> 接口协议详见 [`docs/api/`](./api/)(索引 + 一接口一文件)
> 最后更新:2026-05-31
> 最后更新:2026-06-23(§7 数据模型改为指向 OVERVIEW、§5 美团 CPS 对齐多 tab feed/4 接口、§6 厘清 coupon/step 有写库副作用 ≠ 纯透传壳、§6.5 补 `/internal/app-version`、Alembic 迁移数更新)
---
@@ -23,7 +23,7 @@
| **看广告发奖** | 穿山甲 GroMore 激励视频 S2S 回调(SHA256 验签)+ 4 态 CTA 冷却 |
| **帮助与反馈** | 用户提交反馈(含截图)+ 静态 `/media` 服务 |
**本服务自身没有"比价"实现**——比价/领券业务的核心都在 pricebot-backend(另一个 repo),本服务对 step 类接口做"透传壳"。无爬虫、无 LLM,但**有钱包/福利等业务模型**(数据模型从早期 1 张 `user` 表已扩展到 10 张,见 §7)。
**本服务自身没有"比价"实现**——比价/领券业务的核心都在 pricebot-backend(另一个 repo),本服务对 step 类接口做"透传壳"。无爬虫、无 LLM,但**有钱包/福利等业务模型**(数据模型从早期 1 张 `user` 表已扩展到 **40 张业务表**,见 §7 / [database/OVERVIEW.md](./database/OVERVIEW.md))。
---
@@ -188,32 +188,44 @@ POST /api/v1/auth/sms/login { phone, code } → 任意 6 位通过 → upsert
> 美团请求字段 `listTopiId`(少个 c)是官方拼写,非笔误。经纬度 `*1_000_000` 取整。
### 5.2 三个接口
### 5.2 对外四个接口
- `query_coupon`:底层取数,被 `coupons` 路由和 `feed` 路由共用。
- `coupons` 路由:对外的搜索/榜单接口,**客户端暂未接入**。
- `feed` 路由:首页推荐流,每页并发拉外卖(platform=1)+ 到店(platform=2,到餐)各一次,按 **2 外卖 + 1 到店** 交叉去重(`_interleave`);榜单组合写死 3 页(`_TOPIC_ROUNDS`:爆款 / 今日必推 / 外卖精选+到店限时),第 3 页 `has_next=false`、第 4 页返空。
> 接口级入参/出参/各 tab 行为详见 [api/meituan-feed.md](./api/meituan-feed.md) 等,本节只讲后端形态。
- `coupons`:对外的搜索/榜单接口(底层 `query_coupon`),**客户端暂未接入**。
- `feed`:首页推荐流,**已是多 tab**(入参 `tab`):
- `rec` 智能推荐:走**离线库 `meituan_coupon`**(筛佣金率≥3%、`DISTINCT ON` 去重、按销量降序分页),**纯库查询、不打美团、不依赖 MT 凭证**(实测同城热销中位佣金 ~0.8%,实时筛≥3% 每页剩 0–1 条又撞 402,故从库出)。不显示距离。
- `distance` 距离最近:实时拉外卖+到店两路,按用户坐标由近及远。
- 默认(空 tab):旧的逐轮分页混合 feed(2 外卖 + 1 到店交叉,写死 3 页爆款/今日必推/精选+限时,第 4 页返空),**仅老客户端兼容**。
- 任何失败场景返 `200` + 空 `items` + `status=degraded`(不抛 5xx)。
- `top-sales`:独立的销量榜接口,离线库 `meituan_coupon` 按销量降序 + 跨源去重,**不实时打美团**。
- `referral-link`:换推广链接,客户端取 `link_map["3"]`(deeplink)优先跳美团 App。
- `query_coupon`:底层取数(被 `coupons`/`distance` feed 共用),不直接对外。
### 5.3 风险点
- **三接口无鉴权**:任何人可调,消耗你的美团 appkey 能力/配额。
- **对外接口无鉴权**:任何人可调,消耗你的美团 appkey 能力/配额。
- **`sid` 可被客户端覆盖**:他人可借接口刷自己渠道分佣,建议服务端锁定。
- **`feed` 静默吞异常**:`_fetch_topic` 对美团错误 `except 返回 []` 且不打日志,导致美团失败时 `feed` 返回"200 + 空 items"无声失败。排查时改用 `coupons`(它以 502 暴露错误)。
- **`feed` 失败返 `status=degraded`**:任何失败场景返 `200` + 空 `items` + `status=degraded`(不抛 5xx,避免前端弹报错 toast)。排查时看 `status` 字段区分 `empty`(真没数据)与 `degraded`(上游/库查询失败);或改用 `coupons`(它以 502 暴露错误)。`rec`/`top-sales` 走离线库,prod 刚部署 ETL 未灌则返 `empty`——开内测前先手动跑一次 ETL。
---
## 6. 领券透传(coupon/step)
产品"一键领券"的核心接入点,但**真正的领券逻辑不在本服务**——在另一个 repo `pricebot-backend`(GoalEngine + 事件驱动)。本服务只做"透传壳"。
产品"一键领券"的核心接入点,**真正的领券逻辑不在本服务**——在另一个 repo `pricebot-backend`(GoalEngine + 事件驱动)。但 `coupon/step` **不是纯透传壳**:它在转发 pricebot 之余,还**best-effort 写库**(纯透传壳是 `compare.py` 的 `intent/recognize`、`price/step`,它们只转发不写库)。
```
客户端 → POST /api/v1/coupon/step (任意 JSON body,含 device_id/trace_id/step)
→ coupon.py:不做 schema 校验,仅读 device_id/trace_id/step 打日志
→ async httpx 把 body 原样 POST 到 PRICEBOT_BASE_URL/api/coupon/step
→ coupon.py:不做 schema 校验,仅读 device_id/trace_id/step
→ [副作用1] step==0 → 写 coupon_prompt_engagement(claim_started)
→ async httpx 把 body 原样 POST 到 PRICEBOT_BASE_URL/api/coupon/step(按 trace_id 一致性 hash 选实例)
→ [副作用2] 从响应抽券结果(去重)→ 写 coupon_claim_record
→ [副作用3] action.command==done → 写 coupon_daily_completion(首页「去领取」卡置灰源)
→ 把 pricebot 的响应原样返回
```
> 三处写库(`_mark_engagement_blocking` / `_record_claims_blocking` / `_mark_completed_blocking`)全 **best-effort**:各自独立 session、经 `run_in_threadpool` 不阻塞事件循环,写失败只 `logger.warning`、绝不连累领券返回。判断维度是 `device_id`(`user_id` 可空旁路,仅资产留痕)。落库细节见 [database/coupon_state.md](./database/coupon_state.md)。
- **MVP 不鉴权**:已去掉 `CurrentUser` 依赖。`device_id` 透传给 pricebot 区分设备,但后端拿不到 `user_id` → 领券行为暂时绑不到登录用户(采集不到用户级画像)。待补 JWT,见 `待办与技术债.md` P1。
- **不做 schema 校验**:body 原样透传,pricebot 自己校验。
- **错误**:body 非合法 JSON → 400;pricebot 不可达或返回 5xx → 502。
@@ -228,27 +240,15 @@ POST /api/v1/auth/sms/login { phone, code } → 任意 6 位通过 → upsert
**启动确认窗兜底样本**(2026-06):国产 ROM 打开别的 App 时弹"想要打开 XX"确认窗,pricebot 对没见过文案(繁体/英文/ROM 改版)的窗用 LLM 兜底放行后,把样本 POST 到 [`/internal/launch-confirm-sample`](../app/api/internal/launch_confirm.py) 落 `launch_confirm_sample` 表(host 包 + 弹窗树 + LLM plan + 设备 locale/机型),供研发定期人工沉淀回 pricebot 的规则 yaml(回到快路径)。**需 pricebot 与 app-server 两边 `.env` 配同一 `INTERNAL_API_SECRET` 才生效**(未配则 pricebot 侧跳过上报、不影响比价/领券)。
> 同类内部回写端点还有 `/internal/price-observation`(价格观测)、`/internal/store-mapping`(跨平台店铺映射)等 pricebot 比价资产沉淀。
> 同类内部回写端点(同走 `X-Internal-Secret`)还有:`/internal/price-observation`(价格观测)、`/internal/store-mapping` + `/store-mapping/lookup` + `/store-mapping/invalidate`(跨平台店铺映射沉淀/反查/失效)等 pricebot 比价资产沉淀;以及 **`/internal/app-version`(OTA)**——**发布流程**(非 pricebot)出 APK 后写最新版本号/下载链接/sha256 落 `app_config`,客户端再 `GET /api/v1/platform/app-version` 读做检查更新。完整 6 个内部端点见 [api/internal.md](./api/internal.md)。
---
## 7. 数据模型
业务表(下表)+ `alembic_version` 框架表。生产 PG / 开发可回退 SQLite。
**完整表清单不在本文维护**(避免双份漂移)——共 **40 张业务表** + `alembic_version` 框架表,逐表字段级说明 + 跨表关系/写入路径见 **[database/OVERVIEW.md](./database/OVERVIEW.md)**(总览)与 [database/README.md](./database/README.md)(一表一文件索引)。生产 PG / 开发可回退 SQLite。
| 表 | models 文件 | 说明 |
|---|---|---|
| `user` | `models/user.py` | 用户(phone 唯一索引;注销时改成 `deleted_<id>` 释放约束) |
| `feedback` | `models/feedback.py` | 用户反馈(content/contact/images JSON 列/status) |
| `coin_account` | `models/wallet.py` | 用户的金币余额(`balance_cents` 单位:分) |
| `coin_transaction` | `models/wallet.py` | 金币流水(签到/任务/兑换/广告;`type` + `amount_cents`) |
| `cash_transaction` | `models/wallet.py` | 现金流水(兑换/提现) |
| `withdraw_order` | `models/wallet.py` | 提现单(`status` + `wxpay_batch_id`,微信支付商家转账) |
| `signin_record` | `models/signin.py` | 签到记录(每日一行,索引 `(user_id, signin_date)`) |
| `user_task` | `models/task.py` | 一次性任务领取记录 |
| `savings_record` | `models/savings.py` | 省钱明细(`dishes` 在 PG 上为 JSONB,SQLite 上是 TEXT) |
| `comparison_record` | `models/comparison.py` | 比价记录(每次比价完整明细;`(user_id, trace_id)` 唯一幂等;4 个 JSON(B) 列含 `raw_payload`;独立于 savings) |
| `ad_reward_record` | `models/ad_reward.py` | 看广告发奖(`trans_id` 唯一,幂等) |
本文只保留分层与高频维度的速查:数据访问统一在 `repositories/`,ORM 表结构在 `models/`(钱包/福利在 `wallet.py`/`signin.py`/`task.py`、比价在 `comparison.py`、领券今日状态在 `coupon_state.py`、CPS 群发在 `cps_*.py`、pricebot 内部沉淀在 `price_observation.py`/`store_mapping.py`/`launch_confirm_sample.py`、无障碍存活在 `device.py`)。下面单列最常用的 `user` 表字段。
**user 表字段速查**:
| 字段 | 类型 | 说明 |
@@ -265,7 +265,7 @@ POST /api/v1/auth/sms/login { phone, code } → 任意 6 位通过 → upsert
`upsert_user_for_login`:phone 存在则更新 `last_login_at`,不存在则注册(注册即登录)。
**Alembic 迁移**:`alembic/versions/` 当前 11 个迁移 + 1 个合并迁移(`f01db5d77dac_merge_pg_jsonb_and_feedback_heads.py`,2026-05-29 创建——实习生 PG 分支和 user-profile-feedback 分支并行开发时 down_revision 都挂在 `c8d9e0f1a2b3` 上,导致多 head,合并迁移把两条链合并)。详见 [数据库迁移.md](./database/数据库迁移.md)。
**Alembic 迁移**:`alembic/versions/` 当前约 **78 个迁移文件**(含 14 个合并迁移),当前单一 head `4dc2af7ebe74`(2026-06-23 合并 #65 device 链 + comparison token 列两条并行链)。多人/多分支并行改表频繁产生多 head,靠 `alembic merge` 收敛回单 head。规模随改表增长,**别背具体链**,以 `alembic history`/`alembic heads` 实时输出为准。详见 [数据库迁移.md](./database/数据库迁移.md)。
---