更新文档0709 (#128)

Reviewed-on: #128
2026-07-09 14:24:46 +08:00
parent 0cf5b3816f
commit fa4127b9e5
43 changed files with 756 additions and 279 deletions
@@ -3,7 +3,7 @@
 > 域名:`app-api.shaguabijia.com`(HTTPS,nginx 反代)
 > 仓库:`shaguabijia-app-server`
 > 接口协议详见 [`docs/api/`](./api/)(索引 + 一接口一文件)
-> 最后更新:2026-06-23(§7 数据模型改为指向 OVERVIEW、§5 美团 CPS 对齐多 tab feed/4 接口、§6 厘清 coupon/step 有写库副作用 ≠ 纯透传壳、§6.5 补 `/internal/app-version`、Alembic 迁移数更新)
+> 最后更新:2026-07-09(§1/§6.2 比价透传改「软鉴权 + trace_id 签发 + harvest 落库」不再是纯透传;§3 目录树补全到当前 22 个 v1 路由 + core 三 worker + utils/geo;§1 补 邀请奖励金/埋点/领券看板/设备存活;§5 美团 feed/top-sales 按城市过滤 #116;§7 45 张表、98 迁移;§8 部署对齐 ecs1 git-clone + systemd 定时器;§10 刷新。上一次 2026-06-23)

 ---

@@ -13,17 +13,23 @@

 | 能力 | 说明 |
 |---|---|
-| **账号与登录** | 极光一键登录 + 短信验证码登录(mock)→ 签发 JWT |
+| **账号与登录** | 极光一键登录 + 短信验证码登录(SMS_MOCK 切换)→ 签发 JWT;新手引导标记(设备+账号,含用户自助重置 #114) |
 | **用户资料** | 昵称 / 头像(上传图片含魔数嗅探) / 注销账号(软删除+匿名化) |
-| **美团 CPS 选品** | 透传美团联盟优惠券(外卖/到店)、点击换取推广链接(分佣)、未配凭证时降级返空 |
-| **领券透传** | `/coupon/step` 透传到 pricebot-backend(一键领券核心,MVP 不鉴权,前端已接通) |
-| **外卖比价透传** | `/intent/recognize` + `/price/step` 透传到 pricebot-backend(food MVP,MVP 不鉴权) |
-| **金币 / 现金钱包** | 金币账户/流水/兑换/微信绑定/提现单 11 端点 |
+| **美团 CPS 选品** | feed 多 tab(rec 离线库 / distance 实时)+ 销量榜,**按设备坐标离线反查城市、只出同城券**(#116);点击换推广链接(分佣);未配凭证降级返空 |
+| **领券透传** | `/coupon/step` 透传到 pricebot-backend(一键领券核心,不鉴权,前端已接通)+ best-effort 写领券三表;`/coupon/session` 领券任务流水(admin 看板,#99) |
+| **外卖比价透传 + 落库** | `/intent/*` + `/price/step` + `/trace/finalize`、`/trace/epilogue` 透传 pricebot,**软鉴权 + 首帧签发 trace_id + harvest 三段式落 `comparison_record`**(2026-07 起,见 §6.2) |
+| **金币 / 现金钱包** | 金币账户/流水/兑换/微信绑定/提现单;**邀请奖励金独立账本**(#82,与现金物理隔离,`source` 分账提现 #121) |
+| **好友邀请** | 邀请码/落地页指纹归因;发奖口径=好友**比价并下单**(#113,发邀请奖励金) |
 | **签到 + 任务 + 省钱战绩** | 福利模块 |
-| **看广告发奖** | 穿山甲 GroMore 激励视频 S2S 回调(SHA256 验签)+ 4 态 CTA 冷却 |
-| **帮助与反馈** | 用户提交反馈(含截图)+ 静态 `/media` 服务 |
+| **看广告发奖** | 穿山甲 GroMore 激励视频 S2S 回调(SHA256 验签)+ 信息流/Draw 结算(ad_type/feed_scene 分场景)+ 穿山甲后台收益日表拉取(#92) |
+| **帮助与反馈** | 反馈工单(来源/场景/端环境采集 + admin 采纳发币/拒绝/运营回复,#94/#105)+ 静态 `/media` 服务 |
+| **埋点** | `/analytics/events` 批量上报落 `analytics_event`(#83) |
+| **设备存活监控** | 无障碍心跳 + 掉线检出(worker,超时 1h #107)+ 召回 ack;admin 存活看板(#80) |
+| **平台配置 / OTA** | `/platform/*`:门面统计、feature flags、广告配置下发、App 版本检查更新(全不鉴权) |
+| **CPS 群发联盟** | `/c/{code}` 短链落地 + 微信授权 + 联盟对账(美团+京东 #90),运营台在 admin |
+| **运营后台 admin** | 独立子应用(8771,独立 JWT):用户/钱包/提现审核/反馈/大盘/收益报表/领券看板/RBAC 自定义角色(#117/#126)等,全量端点见 [api/README](./api/README.md) Admin 段 |

-**本服务自身没有"比价"实现**——比价/领券业务的核心都在 pricebot-backend(另一个 repo),本服务对 step 类接口做"透传壳"。无爬虫、无 LLM,但**有钱包/福利等业务模型**(数据模型从早期 1 张 `user` 表已扩展到 **40 张业务表**,见 §7 / [database/OVERVIEW.md](./database/OVERVIEW.md))。
+**"比价/领券"的执行核心在 pricebot-backend**(另一个 repo),本服务对 step 类接口做透传;但 2026-07 起比价透传**不再是纯壳**——app-server 直接负责比价记录落库(§6.2)。无爬虫、无 LLM,业务模型已扩展到 **45 张业务表**(见 §7 / [database/OVERVIEW.md](./database/OVERVIEW.md))。仓库根另有 `h5/`(mine 我的页 + shared bridge/api,#89,H5 化的我的页静态资源)。

 ---

@@ -52,81 +58,56 @@

 ```
 app/
-├── main.py                  # FastAPI 入口:注册全部 router、CORS、/health、lifespan
+├── main.py                  # FastAPI 入口:注册 21 个 v1 router + 4 个 internal router、CORS、
+│                            #   lifespan(预热 pricebot client + 离线地理库,启 3 个后台 worker)、
+│                            #   /media 静态服务 + /media/shaguabijia.apk 官网直链(强制下载头)
 ├── api/
-│   ├── deps.py              # 共享依赖:get_current_user(鉴权)、get_db(注入 session)
-│   └── v1/                  # 接口层(薄):解析请求 → 调 repositories/integration → 组装响应 + HTTP 错误码
-│       ├── auth.py          # 登录 6 端点(极光一键登录 / 短信 send+login / refresh / me / logout)
-│       ├── user.py          # 用户资料 3 端点(改昵称 / 上传头像 / 注销账号)
-│       ├── feedback.py      # 帮助与反馈 1 端点(提交反馈含截图)
-│       ├── coupon.py        # 领券透传 /coupon/step(转发 pricebot,MVP 不鉴权)
-│       ├── compare.py       # 外卖比价透传 /intent/recognize + /price/step(转发 pricebot,MVP 不鉴权)
-│       ├── compare_record.py# 比价记录 3 端点(上报 /compare/record + 列表 /compare/records + 详情;鉴权,区别于上面透传)
-│       ├── meituan.py       # 美团 3 端点 + feed 拼接(_interleave / _TOPIC_ROUNDS),未配 MT_CPS 凭证降级返空
-│       ├── wallet.py        # 钱包/提现 11 端点(余额/流水/兑换/绑微信/提现/查单)
-│       ├── signin.py        # 签到 2 端点(状态 / 执行签到)
-│       ├── tasks.py         # 一次性任务 2 端点(列表 / 领取)
-│       ├── savings.py       # 省钱 3 端点(汇总 / 战绩 / 明细)
-│       └── ad.py            # 看广告发奖 3 端点(穿山甲 S2S 回调 / 进度+本轮冷却 / 联调发奖)
-├── schemas/                 # Pydantic:API 收发的数据契约(与客户端对齐字段看这里)
-│   ├── auth.py
-│   ├── user.py              # 改昵称请求 + OkResponse
-│   ├── feedback.py          # 反馈出参(请求是 multipart,在 router 直接校验)
-│   ├── meituan.py
-│   ├── welfare.py           # 钱包/签到/任务/省钱 收发模型
-│   ├── compare_record.py    # 比价记录上报/列表/详情 收发模型(字段对齐 pricebot calibration + done.params)
-│   └── ad.py                # 看广告发奖收发模型
-├── integrations/            # 外部服务/SDK 客户端(重逻辑:签名/加解密/外部 HTTP)
-│   ├── jiguang.py           # 极光 REST 验 token + RSA 解密(多 padding 试错)
-│   ├── meituan.py           # 美团 CPS 网关签名 + query_coupon / get_referral_link
-│   ├── sms.py               # 短信验证码(mock,进程内存冷却表)
-│   ├── pangle.py            # 穿山甲激励视频发奖回调验签(SHA256,2026-05 从 core 移入)
-│   └── wxpay.py             # 微信支付 V3 商家转账(提现)+ code 换 openid(2026-05 从 core 移入)
-├── core/                    # 基础设施(无外部业务集成)
-│   ├── config.py            # pydantic-settings
-│   ├── security.py          # JWT 签发/校验
-│   ├── ratelimit.py         # 同 IP 滑动窗口限流依赖
-│   ├── rewards.py           # 发奖/兑换/提现额度等业务常量与换算(2026-05 加 VIDEO_ROUND_REQUIRED_COUNT / VIDEO_ROUND_COOLDOWN_SECONDS)
-│   ├── media.py             # 用户上传文件(头像/反馈截图)落盘 + 魔数嗅探 + 随机文件名
-│   └── logging.py
-├── repositories/            # 数据访问 + 事务(早期叫 crud,2026-05 统一并入此目录)
-│   ├── user.py              # get_user_by_id / by_phone / upsert_for_login / update_nickname / set_avatar_url / soft_delete_account
-│   ├── feedback.py          # 提交反馈写库
-│   ├── wallet.py            # 账户/流水/兑换/提现单(调 integrations/wxpay)
-│   ├── signin.py            # 签到记录 / 连续天数 / 档位
-│   ├── task.py              # 一次性任务领取
-│   ├── savings.py           # 省钱汇总 / 战绩 / 明细
-│   ├── comparison.py        # 比价记录 upsert(user_id+trace_id 幂等)+ best/saved/status 派生 + 分页
-│   └── ad_reward.py         # 看广告发奖(按 trans_id 幂等 + 每日上限 + 本轮冷却派生)
-├── models/                  # ORM 表结构
-│   ├── user.py              # user(含微信 openid/nickname/avatar)
-│   ├── feedback.py          # 用户反馈(content/contact/images JSON 列/status)
-│   ├── wallet.py            # 金币账户 / 金币流水 / 现金流水 / 提现单
-│   ├── signin.py            # 签到记录
-│   ├── task.py              # 任务领取记录
-│   ├── savings.py           # 省钱明细 / 店铺菜品 / dishes(PG 上 JSONB)
-│   ├── comparison.py        # 比价记录(完整明细;含 4 个 JSON(B) 列 + raw_payload;独立于 savings)
-│   └── ad_reward.py         # 看广告发奖记录
-└── db/
-    ├── base.py              # DeclarativeBase
-    └── session.py           # engine + get_db(非 SQLite 时启 pool: size=10/overflow=20/recycle=3600)
+│   ├── deps.py              # 共享依赖:get_current_user / OptionalUser(软鉴权) / get_db
+│   ├── internal/            # server→server 内部端点(X-Internal-Secret):app_version / launch_confirm / price / store
+│   └── v1/                  # 接口层(薄),21 个路由文件:
+│       ├── auth.py user.py feedback.py            # 登录 / 资料+引导(含 reset #114) / 反馈工单
+│       ├── coupon.py                              # 领券透传 step + session 流水 + prompt/completed 频控族
+│       ├── compare.py                             # 比价透传 + trace_id 签发 + harvest 落库(§6.2)
+│       ├── compare_record.py compare_milestone.py # 比价记录(鉴权兜底上报/列表/详情/stats)+ 里程碑
+│       ├── meituan.py                             # CPS 选品 4 端点(feed 多 tab / top-sales 按城市 #116)
+│       ├── wallet.py wxpay.py                     # 钱包/提现(source 分账 #121)/transfer-auth 族 + 微信回调 stub
+│       ├── signin.py tasks.py savings.py          # 福利
+│       ├── ad.py                                  # 激励视频 S2S + 信息流/Draw 结算 + eCPM/noshow/watch
+│       ├── invite.py order.py report.py           # 邀请 / 支付归因(触发邀请发奖 #113) / 上报更低价
+│       ├── analytics.py device.py platform.py     # 埋点 #83 / 无障碍存活 #65 / 门面+flags+ad-config+OTA
+│       └── cps_redirect.py                        # /c/{code} 短链落地 + 微信 OAuth(挂域名根)
+├── admin/                   # 运营后台独立子应用(8771,独立 JWT;app.main 不 import 它)
+│   ├── main.py deps.py security.py permissions.py # 入口 / 鉴权链 / RBAC 页面目录(#117)
+│   └── routers/             # 23 个路由:users wallet withdraw feedback(+qr) dashboard comparison
+│                            #   coupon_data device_liveness event_logs price_report onboarding
+│                            #   ops_marquee_seed ops_stat_config ad_audit ad_revenue ad_config
+│                            #   config admins roles(#126) audit auth cps
+├── schemas/                 # Pydantic 契约(17 个文件,与客户端对齐字段看这里)
+├── integrations/            # 外部 SDK(重逻辑):jiguang / meituan(S-Ca 签名) / sms / pangle / wxpay
+├── core/                    # 基础设施:config(+config_schema 运营可配项定义) / security / ratelimit /
+│   │                        #   rewards / media / logging / ad_cooldown / test_account(测试号免验证码 #69)
+│   ├── pricebot_router.py   # pricebot 多实例一致性 hash(ketama 1000 虚节点,按 trace_id 亲和)
+│   ├── pricebot_client.py   # 共享 httpx AsyncClient 单例(#87:免每请求重建 SSL 上下文、绕进程代理)
+│   ├── withdraw_reconcile_worker.py  # 提现对账 worker(lifespan 启动)
+│   ├── heartbeat_monitor_worker.py   # 无障碍心跳掉线检出 worker(#65,超时 1h #107)
+│   └── daily_exchange_worker.py      # 金币自动兑换 worker
+├── utils/                   # geo.py(离线经纬度→城市反查,~2.5M 行 CSV+KDTree,启动预热)
+│                            #   + meituan_city.py(城市→美团 city_id,#116)
+├── repositories/            # 数据访问 + 事务(28 个文件;comparison.py 含 harvest_running/done/abort 三段)
+├── models/                  # ORM 表结构(34 个文件,45 张业务表,见 database/OVERVIEW.md)
+└── db/                      # DeclarativeBase + engine/get_db(非 SQLite 启 pool 10+20)

-alembic/                     # 数据库迁移(versions/ 11+ 个迁移含 feedback_table / convert_dishes_jsonb / merge 等)
-deploy/                      # systemd(.service) + nginx(.conf)
-secrets/                     # 极光 RSA 私钥 / 微信支付证书(不入 git,仅 .gitkeep 占位)
-scripts/
-  ├── init_postgres.py       # 一键 PG 初始化:建用户 + 建库 + 写 .env + 跑迁移(2026-05 新增,见已知 bug §10)
-  ├── migrate.sh             # 单独跑 alembic upgrade head(部署/CI 用)
-  ├── reset_signin.py        # 重置今日签到
-  ├── reset_welfare.py       # 重置福利数据
-  ├── reconcile_withdraws.py # 提现对账
-  └── sim_pangle_callback.py # 模拟穿山甲回调
-tests/                       # pytest(auth / health / welfare / withdraw / ad_reward / coupon_proxy / compare_proxy)
-run.sh                       # 本地启动脚本(自动先跑迁移再起服务)
-docs/api/                    # API 接口文档(索引 README + 一接口一文件)
-docs/integrations/           # 集成层实现文档(SDK 签名/加解密/协议细节)
-docs/database/数据库迁移.md           # Alembic 迁移指南(如何建表/升级/新增迁移)
-docs/database/postgres-migration.md   # SQLite → PostgreSQL 切换指南(配套 scripts/init_postgres.py)
+h5/                          # H5 静态页(#89):mine 我的页 + shared bridge/api
+alembic/                     # 数据库迁移(98 个,含 14+ merge;单 head,见 §7)
+deploy/                      # systemd:app-server + admin 两服务;定时器 meituan-etl(选品 ETL)/
+│                            #   pangle-revenue(穿山甲收益,每天 10:30 #100)/daily-exchange;nginx 配置
+secrets/                     # 极光 RSA 私钥 / 微信支付证书(不入 git)
+scripts/                     # init_postgres / migrate.sh / create_admin / 美团券 ETL(pull_meituan_coupons +
+│                            #   load_meituan_coupon_tsv) / sync_pangle_revenue(#92) / publish_apk /
+│                            #   reconcile_withdraws / reset_* / sim_pangle_callback / seed_mock_*(造数)
+tests/                       # pytest(外部集成全 monkeypatch,不打真 HTTP)
+run.sh                       # 本地启动(钉定 .venv 解释器 #75,先迁移再起服务)
+docs/api/ docs/database/ docs/integrations/ docs/guides/   # 文档(各自带索引)
 ```

 > **命名说明**:`api/v1/` 的 `v1` 用于 URL 版本化(移动端无法强制即时升级,需新旧版本并存能力);`integrations` 装外部 SDK 集成、`repositories` 装数据访问、`core` 装基础设施,三者分离。**数据访问层统一在 `repositories/`**(早期叫 `crud/`,2026-05 已整体并入,`crud/` 不再存在)。`coupon.py` 是领券透传,勿与 `meituan.py` 里的 `coupons`(券列表)混淆。
@@ -190,15 +171,15 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert

 ### 5.2 对外四个接口

-> 接口级入参/出参/各 tab 行为详见 [api/meituan-feed.md](./api/meituan-feed.md) 等,本节只讲后端形态。
+> 接口级入参/出参/各 tab 行为详见 [api/meituan/meituan-feed.md](./api/meituan/meituan-feed.md) 等,本节只讲后端形态。

 - `coupons`:对外的搜索/榜单接口(底层 `query_coupon`),**客户端暂未接入**。
 - `feed`:首页推荐流,**已是多 tab**(入参 `tab`):
-  - `rec` 智能推荐:走**离线库 `meituan_coupon`**(筛佣金率≥3%、`DISTINCT ON` 去重、按销量降序分页),**纯库查询、不打美团、不依赖 MT 凭证**(实测同城热销中位佣金 ~0.8%,实时筛≥3% 每页剩 0–1 条又撞 402,故从库出)。不显示距离。
+  - `rec` 智能推荐:走**离线库 `meituan_coupon`**(筛佣金率≥3%、`DISTINCT ON` 去重、按销量降序分页),**纯库查询、不打美团、不依赖 MT 凭证**(实测同城热销中位佣金 ~0.8%,实时筛≥3% 每页剩 0–1 条又撞 402,故从库出)。不显示距离。**#116 起按城市过滤**:设备经纬度经 `utils/geo`(离线反查,启动预热)+ `meituan_city` 映射成美团 `city_id`,只出同城券;拿不到坐标/城市 → 返空 + `status=degraded`。
  - `distance` 距离最近:实时拉外卖+到店两路,按用户坐标由近及远。
  - 默认(空 tab):旧的逐轮分页混合 feed(2 外卖 + 1 到店交叉,写死 3 页爆款/今日必推/精选+限时,第 4 页返空),**仅老客户端兼容**。
  - 任何失败场景返 `200` + 空 `items` + `status=degraded`(不抛 5xx)。
- `top-sales`:独立的销量榜接口,离线库 `meituan_coupon` 按销量降序 + 跨源去重,**不实时打美团**。
+- `top-sales`:独立的销量榜接口,离线库 `meituan_coupon` 按销量降序 + 跨源去重 + **同城过滤**(#116,同 rec 的城市反查),**不实时打美团**。
 - `referral-link`:换推广链接,客户端取 `link_map["3"]`(deeplink)优先跳美团 App。
 - `query_coupon`:底层取数(被 `coupons`/`distance` feed 共用),不直接对外。

@@ -212,7 +193,7 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert

 ## 6. 领券透传(coupon/step)

-产品"一键领券"的核心接入点,**真正的领券逻辑不在本服务**——在另一个 repo `pricebot-backend`(GoalEngine + 事件驱动)。但 `coupon/step` **不是纯透传壳**:它在转发 pricebot 之余,还**best-effort 写库**(纯透传壳是 `compare.py` 的 `intent/recognize`、`price/step`,它们只转发不写库)。
+产品"一键领券"的核心接入点,**真正的领券逻辑不在本服务**——在另一个 repo `pricebot-backend`(GoalEngine + 事件驱动)。但 `coupon/step` **不是纯透传壳**:它在转发 pricebot 之余,还**best-effort 写库**。(比价透传 `compare.py` 2026-07 起同样带落库副作用,见 §6.2——现在全站已没有"只转发不写库"的透传端点,只有 `trace/epilogue` 例外。)

 ```
 客户端 → POST /api/v1/coupon/step  (任意 JSON body,含 device_id/trace_id/step)
@@ -231,6 +212,29 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert
 - **错误**:body 非合法 JSON → 400;pricebot 不可达或返回 5xx → 502。
 - **配置**:`PRICEBOT_BASE_URL`(默认 `http://localhost:8000`)、`PRICEBOT_REQUEST_TIMEOUT_SEC`(默认 30s,因领券单帧最多 wait 6s)。
 - **现状**:**前端已接通**——首页「去领取」→ `CouponPromptDialog` → 权限检查 → 无障碍引擎 `startCouponClaim` → 循环调本接口,逐张券下发 launch/wait/done。pricebot-backend 不在本目录。
+- **配套**:`POST /coupon/session`(#99)由客户端**独立两段上报**(发起建行/收尾更新)落 `coupon_session` 流水,供 admin「领券数据」看板算发起数/完成率/中途流失/耗时——与 step 透传链路解耦。
+
+---
+
+## 6.2 外卖比价透传:软鉴权 + trace_id 签发 + harvest 落库(2026-07)
+
+`compare.py` 的 `/intent/recognize`、`/intent/step`、`/intent/precoupon/step`、`/price/step`、`/trace/finalize`、`/trace/epilogue` 透传 pricebot 之余,**由 app-server 直接落库比价记录**(不再依赖客户端 POST /compare/record):
+
+```
+客户端首帧(可不带 trace_id)
+  → compare._forward:app-server 用 uuid 签发 trace_id、注入转发 body、回填响应顶层
+  → [harvest_running] 仅 mint 那帧:按 trace_id 建 comparison_record 的 running 行
+  → 后续帧原样透传(原始 bytes 快路,不再写库)
+  → done 帧(price/step)→ [harvest_done] 写 success/failed + 派生 best_*/saved_amount_cents
+  → 用户终止/未识别 → 客户端打 /trace/finalize → [harvest_abort] 写 cancelled/failed(不降级已 success)
+  → /trace/epilogue(#112):App 结果页截图透传入 trace,纯透传、不落库
+```
+
+- **软鉴权(OptionalUser)**:新客户端带 JWT → 记录绑 `user_id`;老客户端不带 → `user_id` 暂空,由其后续带 JWT 的 `POST /compare/record` 上报补齐(灰度期两条写路径按 `trace_id` reconcile)。
+- **写库全 best-effort**:`run_in_threadpool` + 独立 SessionLocal,失败只 warning、绝不连累比价返回(同 coupon.py 口径)。
+- **trace_url** 从 pricebot 响应顶层取(pricebot 每帧都带);查看权限按 `user.debug_trace_enabled` 控制。
+- **邀请发奖不在 harvest**:#113 口径 = 好友「比价并下单」,发放在 `POST /order/report`(`invite.try_reward_on_compare`,`compare_reward_granted` 幂等闸,发**邀请奖励金**入独立账本)。
+- 透传基建:`core/pricebot_router.pick_pricebot`(按 trace_id 一致性 hash 选实例)+ `core/pricebot_client`(共享 httpx 单例,#87)。

 ---

@@ -240,13 +244,13 @@ 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 侧跳过上报、不影响比价/领券)。

-> 同类内部回写端点(同走 `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)。
+> 同类内部回写端点(同走 `X-Internal-Secret`)还有:`/internal/price-observation`(价格观测)、`/internal/store-mapping` + `/store-mapping/lookup` + `/store-mapping/invalidate`(跨平台店铺映射沉淀/反查/失效)等 pricebot 比价资产沉淀;`GET /internal/launch-confirm-samples`(#91,样本列表供 pricebot `distill_launch_confirm.py` 聚合沉淀回静态规则);以及 **`/internal/app-version`(OTA)**——**发布流程**(非 pricebot)出 APK 后写最新版本号/下载链接/sha256 落 `app_config`,客户端再 `GET /api/v1/platform/app-version` 读做检查更新。完整 7 个内部端点见 [api/internal/internal.md](./api/internal/internal.md)。

 ---

 ## 7. 数据模型

-**完整表清单不在本文维护**(避免双份漂移)——共 **40 张业务表** + `alembic_version` 框架表,逐表字段级说明 + 跨表关系/写入路径见 **[database/OVERVIEW.md](./database/OVERVIEW.md)**(总览)与 [database/README.md](./database/README.md)(一表一文件索引)。生产 PG / 开发可回退 SQLite。
+**完整表清单不在本文维护**(避免双份漂移)——共 **45 张业务表** + `alembic_version` 框架表,逐表字段级说明 + 跨表关系/写入路径见 **[database/OVERVIEW.md](./database/OVERVIEW.md)**(总览)与 [database/README.md](./database/README.md)(一表一文件索引)。生产 PG / 开发可回退 SQLite。2026-06 下旬以来新增:`coupon_session`(#99)、`analytics_event`(#83)、`invite_cash_transaction`(#82)、`admin_role`(#117)、`ad_pangle_daily_revenue`(#92)。

 本文只保留分层与高频维度的速查:数据访问统一在 `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` 表字段。

@@ -265,15 +269,15 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert

 `upsert_user_for_login`:phone 存在则更新 `last_login_at`,不存在则注册(注册即登录)。

-**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)。
+**Alembic 迁移**:`alembic/versions/` 当前 **98 个迁移文件**(含 14+ 个合并迁移),当前单一 head `admin_user_pages_override`(2026-07-08,#126)。多人/多分支并行改表频繁产生多 head,靠 `alembic merge` 收敛回单 head。规模随改表增长,**别背具体链**,以 `alembic history`/`alembic heads` 实时输出为准。⚠️ revision id 长度 ≤32 字符(`alembic_version` 列宽,超长部署时截断报错——0.2.1 实踩)。详见 [数据库迁移.md](./database/数据库迁移.md)。

 ---

 ## 8. 配置与部署

-配置见 `core/config.py`(pydantic-settings 读 `.env`)。分组:环境、`DATABASE_URL`(默认 SQLite,生产应切 PG)、JWT、极光(`JG_*`)、短信(`SMS_MOCK` 默认 true)、美团(`MT_CPS_*`)、**pricebot 上游(`PRICEBOT_BASE_URL` / `PRICEBOT_REQUEST_TIMEOUT_SEC=30` / `PRICEBOT_COMPARE_TIMEOUT_SEC=60`)**、**媒体存储(`MEDIA_ROOT=./data/media` / `MEDIA_URL_PREFIX=/media`)**、CORS。
+配置见 `core/config.py`(pydantic-settings 读 `.env`)。分组:环境、`DATABASE_URL`(默认 SQLite,生产应切 PG)、JWT(+独立 `ADMIN_JWT_SECRET`)、极光(`JG_*`)、短信(`SMS_MOCK` 默认 true)、美团(`MT_CPS_*`)、**pricebot 上游(`PRICEBOT_BASE_URL` / 多实例 `PRICEBOT_INSTANCES` / `PRICEBOT_REQUEST_TIMEOUT_SEC=30` / `PRICEBOT_COMPARE_TIMEOUT_SEC=60`)**、**内部密钥(`INTERNAL_API_SECRET`,internal 族)**、穿山甲(`PANGLE_*`,含收益 API)、微信支付(`WXPAY_*`)、**媒体存储(`MEDIA_ROOT=./data/media` / `MEDIA_URL_PREFIX=/media`)**、CORS;运营可覆盖的业务常量在 `core/config_schema.py` 定义、`app_config` 表落值(admin `GET/PATCH /config`)。

-**生产部署**:systemd `shaguabijia-app-server.service`(WorkingDirectory `/opt/shaguabijia-app-server`,`EnvironmentFile=.env`,uvicorn 监听 `127.0.0.1:8770`,`--workers 1`)+ nginx 443 反代 → 8770。**无 Docker**。**PostgreSQL 16** 同机部署。
+**生产部署(2026-06-06 起在 ecs1)**:双 systemd 服务 `shaguabijia-app-server.service`(uvicorn `127.0.0.1:8770`,`--workers 1`)+ `shaguabijia-admin.service`(8771),WorkingDirectory `/opt/shaguabijia-app-server`,`EnvironmentFile=.env`,nginx 443 反代 `app-api.shaguabijia.com` → 8770。**无 Docker**。**PostgreSQL 16** 同机部署。代码走 **git clone(main 分支)+ Gitea 只读部署密钥**,日常发布用服务器上的 `deploy` 一键命令 / `release.sh` 发车 / deploy.shaguabijia.com 发车台(不再 rsync 整目录;`secrets/` 私钥证书单独放置、不入 git)。

 ```bash
 # 首次 PG 初始化(新机器或新环境):
@@ -281,12 +285,13 @@ ssh server "sudo apt install -y postgresql-16 && sudo systemctl enable --now pos
 ssh server "cd /opt/shaguabijia-app-server && .venv/bin/python scripts/init_postgres.py"
 # 该脚本会建业务用户 + 建库 + 写 .env 的 DATABASE_URL + 跑 alembic upgrade head

-# 后续日常部署:
-rsync -avz --exclude='.venv' --exclude='__pycache__' --exclude='data' --exclude='secrets/*.pem' ./ server:/opt/shaguabijia-app-server/
-scp secrets/jverify_rsa_private.pem server:/opt/shaguabijia-app-server/secrets/   # 私钥单独传,不入 git
-ssh server "cd /opt/shaguabijia-app-server && .venv/bin/alembic upgrade head && systemctl restart shaguabijia-app-server"
+# 日常部署(deploy 一键命令等价动作):
+ssh server "cd /opt/shaguabijia-app-server && git pull && .venv/bin/alembic upgrade head \
+  && systemctl restart shaguabijia-app-server shaguabijia-admin"
 ```

+**systemd 定时器**(`deploy/`,各带 .md 运维手册):`meituan-etl`(美团 CPS 选品 ETL → `meituan_coupon`,rec/top-sales 数据源)、`pangle-revenue`(穿山甲 GroMore 后台收益拉取,每天 10:30,#100)、`daily-exchange`(金币自动兑换;lifespan 里另有 in-process worker,两套并存以部署材料为准)。
+
 完整 PG 切换流程见 [docs/database/postgres-migration.md](./database/postgres-migration.md)。

 **生产 checklist(均为上线必查)**:
@@ -325,8 +330,8 @@ conda activate price          # 首次:pip install -e .
 | logout 无服务端失效 | 靠客户端清 token;后续加 jti 黑名单表(注销账号也是同问题——软删后旧 token 仍能用到自然过期) |
 | 美团接口无鉴权 + sid 可覆盖 | 评估加鉴权/锁定 sid(注意首页要求未登录可见) |
 | 美团接口未配凭证降级 | 未配 `MT_CPS_APP_KEY` 时 3 端点返空(不报 502),`/feed` 跟"已配但调用失败"路径无法区分——见 [integrations/meituan](./integrations/meituan.md) |
-| 领券/比价依赖 pricebot | `coupon/step` / `intent/recognize` / `price/step` 仅透传,真正逻辑在 pricebot-backend;前端已接通领券链路,比价 food MVP 也已接通 |
-| agent 系列接口 MVP 不鉴权 | 拿不到 user_id → 无法采集"哪个用户领了/买了什么"用户级画像(商业模式核心资产)。见 [待办与技术债.md](./guides/待办与技术债.md) P1 |
+| 领券/比价依赖 pricebot | 执行核心在 pricebot-backend;比价透传 2026-07 起带 harvest 落库(§6.2),领券 `coupon/step` 带三表副作用,均非纯壳 |
+| 领券 step 仍不鉴权;比价已软鉴权 | 比价透传族改 OptionalUser:带 JWT 即绑 `user_id`(用户级画像已能落到比价记录);`coupon/step` 仍拿不到 user_id(device 维度),老客户端比价记录靠 `/compare/record` 兜底补绑。见 [待办与技术债.md](./guides/待办与技术债.md) |
 | SMS 已接极光(2026-06-03) | real 模式自定义验证码,上线只需 `SMS_MOCK=false`(复用极光凭证)。详见 [integrations/sms](./integrations/sms.md) |
 | 短信冷却存内存 | 扩 worker 前需迁移到 Redis |
 | `MEDIA_ROOT` 进程内 serve | 头像/反馈截图当前用 FastAPI StaticFiles,生产建议 nginx 直 serve 该目录 |