技术债文档

docs/README.md

@@ -6,6 +6,7 @@
 |---|---|
 | [后端技术实现.md](./后端技术实现.md) | **后端技术方案**:业务概览、分层架构与目录、登录链路、美团 CPS、领券透传、数据模型、配置与部署、已知问题。想了解"整个后端怎么回事"看这份。 |
 | [api/](./api/) | **API 接口文档**(目录),采用"索引 + 一接口一文件",结构见下。想查"某个接口的协议"看这里。 |
+| [待办与技术债.md](./待办与技术债.md) | **待办与技术债账本**:记"现在先简化、以后要补"的事 + 跨前后端技术债(P1 鉴权/用户绑定、引擎移植待办等),免遗忘。想知道"还欠什么、以后要补什么"看这份。 |
 
 ## api/ 目录是怎么组织的(传送门式)
 

docs/待办与技术债.md

@@ -0,0 +1,48 @@
+# 待办与技术债账本
+
+> 用途：记"现在先简化、以后要补"的事，和暂不处理的技术债，免得忘。每条标优先级 + 触发背景。做掉的移到末尾「已解决」。
+> 范围：跨栈账本——本仓 `shaguabijia-app-server`(转发层) + `shaguabijia-app-android`(无障碍引擎移植) + `pricebot-backend`(agent 上游，不改)。
+> 大背景：把"后端当大脑、无障碍服务遥控前端操作其它 App"的比价/领券引擎，从 demo app `pricebot` 移植进正式版傻瓜比价。引擎移植采用「代码全搬、独立子包 `…shaguabijia.agent.*`、验证分步(先领券后比价)」。
+> 最后更新：2026-05-27
+
+---
+
+## P1 · 鉴权与用户绑定(最该补)
+
+- **现状**：agent 系列接口 MVP 阶段**全部不鉴权**——领券 `coupon/step` + 比价 4 个(`intent/recognize`、`price/step`、`ecom/intent/recognize`、`ecom/step`)。落地时现有 `coupon-step` 路由的 `CurrentUser` 依赖要先去掉。
+- **代价(为什么记这笔账)**：不验 JWT → 转发时 server 拿不到 `user_id` → agent 行为只能绑到 `device_id`(设备级)，**采集不到"哪个用户领了/买了什么"的用户级画像**。而精准人群画像、私域分群运营是商业模式的核心资产，靠的就是这份用户级行为数据。`device_id` 仍照传(后端按设备串领券队列够用)。
+- **待补**：① agent 接口加 JWT 鉴权；② 建立 `device_id ↔ user_id` 绑定(登录后上报一次即可)；③ 领券/比价记录按 user 维度落库。
+- **连带**：补鉴权后，客户端引擎 `ApiClient` 要接回 JWT(复用 app 现有 `AuthInterceptor` 思路：注入带鉴权头的 OkHttpClient)。
+
+---
+
+## P2 · 引擎移植 · 后端转发层(本仓)
+
+- **加 4 个比价透传端点**：`intent/recognize`、`price/step`、`ecom/intent/recognize`、`ecom/step`。仿 `coupon_step` **纯 body 透传、不加 Pydantic schema**(协议归 pricebot 校验，否则它一改字段本仓就得跟着改，白白耦合)。client `/api/v1/xxx` → 转发 backend `/api/xxx`(去掉 v1，同 `coupon_step`)。
+- **转发超时要调大**：`coupon_step` 现 `PRICEBOT_REQUEST_TIMEOUT_SEC=30`(领券单帧 wait 6s)。但意图识别是一次大上下文 LLM、`price/step` 每帧也是 LLM，可能 >30s；客户端 `ApiClient` 读超时是 60s。→ 转发超时对齐 60s，**待测 pricebot 各接口真实耗时**再定终值。
+- **生产 server 与 backend 同内网**：`PRICEBOT_BASE_URL` 部署时设内网地址。比价是 30~80 步循环，每步多一跳，走公网延迟会累积。
+- **nginx body 上限**：比价 debug 包带 `screenshot`(webp base64，几百 KB)。若 debug 联调走线上域名经 nginx，注意 `client_max_body_size`(release 不带截图、debug 直连本地都无此问题，仅"debug 走域名"才撞)。
+
+---
+
+## P2 · 引擎移植 · 客户端(android 仓，在此备忘)
+
+- **无障碍身份统一为傻瓜比价**：服务名/图标自动继承 application(`<service>` 不单独设 label/icon)；需显式改的 3 处文案——`accessibility_service_description`、前台常驻通知文案("PriceBot 正在待命"等)、`GuideCopy` 里引导高亮的系统列表条目名("PriceBot"→"傻瓜比价")。
+- **BuildConfig 包名**：代码里 `com.pricebot.app.BuildConfig` 的 import 必须改成本 app 包名，否则编译不过。
+- **领券入口**：首页"一键领券"从 `ComparingScreen` 假动画 → 真 `startCouponClaim()`。
+- **比价悬浮球**：`SUPPORTED_BIZ_PACKAGES`(购物 App 前台才显示悬浮球)逻辑照搬。
+- **权限引导融入 Compose**：把 pricebot `MainActivity` 里申请无障碍/悬浮窗/电池优化的逻辑抽出，接到傻瓜比价的 Compose 页(权限引导 Activity 那几个可照搬，改包名+文案)。
+- **类名可选改名**：`PriceBotService` 等用户不可见，保留无妨；想整洁可改 `ShaguaAccessibilityService`(牵动引用，不急)。
+
+---
+
+## 技术债(暂不处理，知情即可)
+
+- **agent 接口公网裸奔**：不鉴权 = 任何人可调，烧 pricebot 的 LLM 算力。与美团 3 接口现状同级，记账后随 P1 一起补。
+- **既有债(已记录在别处)**：美团 `referral-link` 的 `sid` 客户端可覆盖刷分佣；`logout` 占位不吊销 token；`SMS_MOCK=true` 全站免密登录；`JWT_SECRET_KEY` 默认值可伪造 token。详见 [后端技术实现.md](./后端技术实现.md) 与 [api/](./api/)。
+
+---
+
+## 已解决
+
+（暂无）