From a188c43bf79cf7cb92273d7eb3b1023d1af8431b Mon Sep 17 00:00:00 2001 From: marco Date: Wed, 27 May 2026 12:26:58 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8A=80=E6=9C=AF=E5=80=BA=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/README.md | 1 + docs/待办与技术债.md | 48 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 docs/待办与技术债.md diff --git a/docs/README.md b/docs/README.md index 928ca30..9f40fc7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ |---|---| | [后端技术实现.md](./后端技术实现.md) | **后端技术方案**:业务概览、分层架构与目录、登录链路、美团 CPS、领券透传、数据模型、配置与部署、已知问题。想了解"整个后端怎么回事"看这份。 | | [api/](./api/) | **API 接口文档**(目录),采用"索引 + 一接口一文件",结构见下。想查"某个接口的协议"看这里。 | +| [待办与技术债.md](./待办与技术债.md) | **待办与技术债账本**:记"现在先简化、以后要补"的事 + 跨前后端技术债(P1 鉴权/用户绑定、引擎移植待办等),免遗忘。想知道"还欠什么、以后要补什么"看这份。 | ## api/ 目录是怎么组织的(传送门式) diff --git a/docs/待办与技术债.md b/docs/待办与技术债.md new file mode 100644 index 0000000..4438abf --- /dev/null +++ b/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(`` 不单独设 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/)。 + +--- + +## 已解决 + +（暂无）