diff --git a/docs/api/coupon-step.md b/docs/api/coupon-step.md index aa21345..f72672b 100644 --- a/docs/api/coupon-step.md +++ b/docs/api/coupon-step.md @@ -1,9 +1,9 @@ # POST /api/v1/coupon/step — 一键领券任务步进(透传到 pricebot) -> 所属:Coupon 组(前缀 `/api/v1/coupon`) | 鉴权:Bearer access_token | [← 返回 API 索引](./README.md) +> 所属:Coupon 组(前缀 `/api/v1/coupon`) | 鉴权:**无(MVP 阶段不鉴权)** | [← 返回 API 索引](./README.md) ## 入参 -任意 JSON body,**不做 schema 校验**,原样透传给上游。后端仅从中读 `trace_id`、`step` 用于日志。 +任意 JSON body,**不做 schema 校验**,原样透传给上游。后端仅从中读 `device_id`、`trace_id`、`step` 用于日志。 ## 出参 pricebot-backend 的响应**原样返回**(JSON object)。 @@ -13,9 +13,11 @@ pricebot-backend 的响应**原样返回**(JSON object)。 - `502` pricebot 上游不可达(网络错误)或返回 5xx ## 说明 -本服务只加一层 JWT 鉴权,把请求体原样转发到 `PRICEBOT_BASE_URL` 的 `/api/coupon/step`(async httpx)。真正的领券逻辑在 **pricebot-backend(另一个 repo)**,本接口是"鉴权壳 + 透传"。是产品"一键领券"的接入点,前端目前尚未对接。 +把请求体原样转发到 `PRICEBOT_BASE_URL` 的 `/api/coupon/step`(async httpx)。真正的领券逻辑在 **pricebot-backend(另一个 repo,GoalEngine + 事件驱动)**,本接口只是"透传壳"。 -这是后端**唯一需要 JWT 鉴权的业务接口**。 +是产品"一键领券"的接入点,**前端已接通**:首页「去领取」→ `CouponPromptDialog` 确认 → 权限检查 → 无障碍引擎 `PriceBotService.startCouponClaim()` → 循环调本接口,后端逐张券下发 launch/wait/done。 + +⚠️ **MVP 阶段不鉴权**(已去掉 `CurrentUser` 依赖):`device_id` 透传给 pricebot 区分设备,但后端拿不到 `user_id` → 领券行为暂时绑不到登录用户(采集不到用户级画像)。待补 JWT 鉴权 + `device_id↔user_id` 绑定,详见 [待办与技术债.md](../待办与技术债.md) P1。 **相关配置**: - `PRICEBOT_BASE_URL`(默认 `http://localhost:8000`) diff --git a/docs/后端技术实现.md b/docs/后端技术实现.md index aef17ac..5a657fe 100644 --- a/docs/后端技术实现.md +++ b/docs/后端技术实现.md @@ -15,9 +15,9 @@ |---|---| | **账号与登录** | 极光一键登录 + 短信验证码登录(mock)→ 签发 JWT | | **美团 CPS 选品** | 透传美团联盟优惠券(外卖/到店)、点击换取推广链接(分佣) | -| **领券透传** | `/coupon/step` 加 JWT 鉴权后转发到 pricebot-backend(一键领券核心,前端待接入) | +| **领券透传** | `/coupon/step` 透传到 pricebot-backend(一键领券核心,MVP 不鉴权,前端已接通) | -**本服务自身没有"比价"实现**——名字叫比价,实质是:登录态 + 美团券聚合分佣 + 给真正的领券/比价核心(pricebot-backend,另一个 repo)做"鉴权 + 透传壳"。无爬虫、无 LLM、无积分/提现/钱包,数据模型仅一张 `user` 表(美团数据与领券请求均实时透传不落库)。 +**本服务自身没有"比价"实现**——名字叫比价,实质是:登录态 + 美团券聚合分佣 + 给真正的领券/比价核心(pricebot-backend,另一个 repo)做"透传壳"。无爬虫、无 LLM、无积分/提现/钱包,数据模型仅一张 `user` 表(美团数据与领券请求均实时透传不落库)。 --- @@ -50,7 +50,8 @@ app/ │ ├── deps.py # 共享依赖:get_current_user(鉴权)、get_db(注入 session) │ └── v1/ # 接口层(薄):解析请求 → 调 repositories/integration → 组装响应 + HTTP 错误码 │ ├── auth.py # 登录 6 端点(极光一键登录 / 短信 send+login / refresh / me / logout) -│ ├── coupon.py # 领券透传 /coupon/step(转发 pricebot) +│ ├── coupon.py # 领券透传 /coupon/step(转发 pricebot,MVP 不鉴权) +│ ├── compare.py # 外卖比价透传 /intent/recognize + /price/step(转发 pricebot,MVP 不鉴权) │ ├── meituan.py # 美团 3 端点 + feed 拼接(_interleave / _TOPIC_ROUNDS) │ ├── wallet.py # 钱包/提现 11 端点(余额/流水/兑换/绑微信/提现/查单) │ ├── signin.py # 签到 2 端点(状态 / 执行签到) @@ -177,19 +178,20 @@ POST /api/v1/auth/sms/login { phone, code } → 任意 6 位通过 → upsert ## 6. 领券透传(coupon/step) -产品"一键领券"的核心接入点,但**真正的领券逻辑不在本服务**——在另一个 repo `pricebot-backend`(GoalEngine + 事件驱动)。本服务只做"鉴权 + 透传壳"。 +产品"一键领券"的核心接入点,但**真正的领券逻辑不在本服务**——在另一个 repo `pricebot-backend`(GoalEngine + 事件驱动)。本服务只做"透传壳"。 ``` -客户端 → POST /api/v1/coupon/step (Bearer access_token + 任意 JSON body) - → coupon.py:get_current_user 校验 JWT(唯一需鉴权的业务接口) +客户端 → 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 → 把 pricebot 的响应原样返回 ``` -- **不做 schema 校验**:body 原样透传,pricebot 自己校验(后端仅读 `trace_id`/`step` 打日志)。 +- **MVP 不鉴权**:已去掉 `CurrentUser` 依赖。`device_id` 透传给 pricebot 区分设备,但后端拿不到 `user_id` → 领券行为暂时绑不到登录用户(采集不到用户级画像)。待补 JWT,见 `待办与技术债.md` P1。 +- **不做 schema 校验**:body 原样透传,pricebot 自己校验。 - **错误**:body 非合法 JSON → 400;pricebot 不可达或返回 5xx → 502。 - **配置**:`PRICEBOT_BASE_URL`(默认 `http://localhost:8000`)、`PRICEBOT_REQUEST_TIMEOUT_SEC`(默认 30s,因领券单帧最多 wait 6s)。 -- **现状**:接口已挂载可用,但**前端 ComparingScreen 仍是动画 demo、尚未对接此接口**;pricebot-backend 不在本目录。 +- **现状**:**前端已接通**——首页「去领取」→ `CouponPromptDialog` → 权限检查 → 无障碍引擎 `startCouponClaim` → 循环调本接口,逐张券下发 launch/wait/done。pricebot-backend 不在本目录。 --- @@ -256,7 +258,7 @@ conda activate price # 首次:pip install -e . | logout 无服务端失效 | 靠客户端清 token;后续加 jti 黑名单表 | | 美团接口无鉴权 + sid 可覆盖 | 评估加鉴权/锁定 sid(注意首页要求未登录可见) | | feed 静默吞异常 | 建议给 `_fetch_topic` 加日志,避免无声失败 | -| 领券依赖 pricebot | `coupon/step` 仅透传,真正逻辑在 pricebot-backend;前端尚未对接 | +| 领券依赖 pricebot | `coupon/step` 仅透传,真正逻辑在 pricebot-backend;前端已接通领券链路 | | SMS 为 mock | 上线接真实供应商 + `SMS_MOCK=false` | | 短信冷却存内存 | 扩 worker 前需迁移到 Redis | | SQLite | 流量上来切 PostgreSQL,只改 `DATABASE_URL` |