shaguabijia-app-server/docs/待办与技术债.md

待办与技术债账本

用途：记"现在先简化、以后要补"的事，和暂不处理的技术债，免得忘。每条标优先级 + 触发背景。做掉的移到末尾「已解决」。 范围：跨栈账本——本仓 shaguabijia-app-server(转发层) + shaguabijia-app-android(无障碍引擎移植) + pricebot-backend(agent 上游，不改)。 大背景：把"后端当大脑、无障碍服务遥控前端操作其它 App"的比价/领券引擎，从 demo app pricebot 移植进正式版傻瓜比价。引擎移植采用「代码全搬、独立子包 …shaguabijia.agent.*、验证分步(先领券后比价)」。 最后更新：2026-05-27

---

P1 · 鉴权与用户绑定(最该补)

• 现状：agent 系列接口 MVP 阶段全部不鉴权。领券 coupon/step 已落地不鉴权(✅ 已去掉 CurrentUser 依赖);比价 4 个(intent/recognize、price/step、ecom/intent/recognize、ecom/step)端点尚未建(见 P2),建时同样先不加鉴权。
• 代价(为什么记这笔账)：不验 JWT → 转发时 server 拿不到 user_id → agent 行为只能绑到 device_id(设备级)，采集不到"哪个用户领了/买了什么"的用户级画像。而精准人群画像、私域分群运营是商业模式的核心资产，靠的就是这份用户级行为数据。device_id 仍照传(后端按设备串领券队列够用)。
• 待补：① agent 接口加 JWT 鉴权；② 建立 device_id ↔ user_id 绑定(登录后上报一次即可)；③ 领券/比价记录按 user 维度落库。
• 连带：补鉴权后，客户端引擎 ApiClient 要接回 JWT(复用 app 现有 AuthInterceptor 思路：注入带鉴权头的 OkHttpClient)。

---

P2 · 引擎移植 · 后端转发层(本仓)

• 比价透传端点：仿 coupon_step 纯 body 透传、不加 Pydantic schema(协议归 pricebot 校验，否则它一改字段本仓就得跟着改，白白耦合)。client /api/v1/xxx → 转发 backend /api/xxx(去掉 v1，同 coupon_step)。
  • ✅ 外卖 2 个已落地(food MVP，2026-05-27)：intent/recognize + price/step，在 app/api/v1/compare.py(不鉴权、超时 60s)，测试 tests/test_compare_proxy.py，文档 docs/api/compare-*.md。
  • 电商 2 个待接：ecom/intent/recognize + ecom/step——放开电商 scene 时在 compare.py 加两行即可。
• ✅ 转发超时已分离(2026-05-27)：比价用新增的 PRICEBOT_COMPARE_TIMEOUT_SEC=60(意图识别大上下文 LLM、price/step 每帧 LLM)，与领券的 PRICEBOT_REQUEST_TIMEOUT_SEC=30 区分；真实耗时待真机实测再定终值。
• 生产 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 仓)

领券链路相关已完成(详见文末「已解决」):无障碍身份改名、BuildConfig 包名、领券入口、SettingsScreen 权限卡、ApiClient 改址。剩余:

• ✅ 比价悬浮球(外卖)已接(2026-05-27)：SUPPORTED_BIZ_PACKAGES 收窄到 3 个外卖源(美团/淘宝闪购/京东外卖)；scene 写死 food(getSceneMode 默认改「外卖比价」)。点球 → startTask → Phase1/2 → 比价结果悬浮窗,这条链客户端本就齐(随引擎移植搬入),本次只收窄入口 + 写死场景 + 接通 server。电商放开时再加回 PDD/抖音 + scene 选择。
• 仿腾讯权限引导：搬来的 AccessibilityGuideActivity/PermissionGuide*/GuideOverlayService 尚未接入口;当前是"跳系统设置页"最简版(SettingsScreen 权限卡 + 领券前检查已用)。体验后续可升级成仿腾讯浮层。
• 类名可选改名：PriceBotService 等用户不可见，保留无妨；想整洁可改 ShaguaAccessibilityService(牵动引用，不急)。

---

技术债(暂不处理，知情即可)

• agent 接口公网裸奔：不鉴权 = 任何人可调，烧 pricebot 的 LLM 算力。与美团 3 接口现状同级，记账后随 P1 一起补。
• 既有债(已记录在别处)：美团 referral-link 的 sid 客户端可覆盖刷分佣；logout 占位不吊销 token；SMS_MOCK=true 全站免密登录；JWT_SECRET_KEY 默认值可伪造 token。详见 后端技术实现.md 与 api/。

---

阶段 1 领券落地后的遗留(待清理,不阻塞跑通)

• FloatingButton 死代码:Running 面板已换成 ComposeView 承载 CouponProgressPanel(=复用 AgentFloat)。旧原生面板字段(line1~4View/elapsedView/progressBarView/historyContainerView 等)+ updateStatus(StepStatus) 里保留的那段更新逻辑 + appendActionLine/markCurrentActionDone/markPlatformDone/addCancelButton 全部 no-op,待删。
• ComparingScreen / CompResultScreen 弃用:领券改走悬浮窗,不再走全屏假动画。Routes.COMPARING / COMP_RESULT 成死路由,连同两个 Screen 文件待删(CouponPromptDialog 已抽到 ui/coupon/,删 ComparingScreen 不影响它)。
• ApiClient 常量 unused:getBackendUrl() 改用 BuildConfig.BASE_URL 后,DEFAULT_BACKEND_URL/KEY_BACKEND_URL 常量 unused,待清。
• 领券大数字语义:悬浮窗左侧"已领券"大数字目前接 progress.current(正在领第几张),非"已成功数"。中间帧后端不回传已领明细,要精确需后端在 status.progress 加 completed[](协议文档第四节已留扩展点)。
• 正式版 versionCode 必须 > 占坑版线上最高:占坑版(shaguabijia-android)与正式版同包名 com.jishisongfu.shaguabijia 原地覆盖。正式版当前 versionCode=1,真机占坑版是 5 → 同签名降级被 Android 拒装,正式版无法覆盖更新线上占坑版用户。上线前 versionCode 要提到 > 线上占坑版最高值。

已解决

• ✅ 领券链路接通(阶段 1):首页「去领取」→ CouponPromptDialog → 权限检查 → startCouponClaim → 循环 /api/v1/coupon/step;Running 悬浮窗换皮(ComposeView 承载 CouponProgressPanel/AgentFloat,OverlayLifecycleOwner 撑 Compose)。
• ✅ coupon/step 去鉴权:去掉 CurrentUser,MVP 不鉴权(device_id 透传)。
• ✅ ApiClient 改址:BuildConfig.BASE_URL + /api/v1/ 前缀。
• ✅ SettingsScreen 权限卡:5 项(无障碍/悬浮窗/录屏<API30/电池/自启动)真实检测 + 点击跳转 + 自启动无法检测态 + onResume 自动刷新 + 刷新按钮;逻辑抽到 PermissionHelper(HomeScreen 领券前检查复用)。
• ✅ 无障碍身份统一傻瓜比价:服务名/图标继承 app;accessibility_service_description/前台通知/GuideCopy/引导 Activity 里的 "PriceBot" 全改「傻瓜比价」;app 图标换成完整 logo1(adaptive 居中+黄边,不裁切)。
• ✅ GuideOverlayService 组件名 bug:批量 sed 改包名误把无障碍服务 ComponentName 的 packageName 改成 …shaguabijia.agent(应是 applicationId …shaguabijia)→ 无障碍开启检测永远 false;改用 PermissionHelper.isAccessibilityEnabled 动态构造。
• ✅ BuildConfig 包名:com.pricebot.app.BuildConfig import 改本 app 包名。