products 离群端点裁决包 v1（T4 产物 · 波波性能基线遗留 · 2026-09-15）

背景接令：波波 D2 §7 真机位性能基线（staging-baseline-2026-09-14.json）中 GET /api/miniapp/products 为全站唯一离群点——P95 26.6ms / MAX 66.6ms（抖动 2.5 倍）/ 响应 26,057B，三项均为全站最高，约为次高端（guides 5.0KB）5 倍、其余端点（1-4ms）10-20 倍。

本包只裁决，不动代码；不含 a 端 /api/admin/products（admin_backend.py:667，鉴权控制台路径+offset 分页，非 C 端热路径，明确排除在离群修复范围外）。

一、现状（读码结论，非估算处均标注来源）

1.1 端点实现（backend/app/routers/miniapp_products.py）

list_products（:79-89，默认 limit=50、上限 200）每次请求的查询构成：

#	查询	位置	说明
1	`packages` 全行（含 description TEXT）	:81-84	一次取 50 行
2	`site_config.default_leader`（领队）	:34-35	每请求 1 次
3..N	`package_components`（含 description TEXT）	:96-102 循环内 `await _components_of(p["id"])`	每产品 1 次 → N+1

_map_product（:43-70）返回字段：id/title/cover/description/leader/includes[]（每项含 description）/price/duration/difficulty(硬编码 medium)/dailySchedule(恒空)/tags/status(恒 published)/addons(恒空)/originalPrice(恒 null)。

1.2 延迟离群的根因＝N+1（证据：线性拟合精确吻合）

featured（limit=6）→ 8 次往返 → P50 4.5ms；list（staging 约 40 个在售套餐）→ ~42 次往返 → P50 23.2ms
两者比值 5.2，与往返数比 42/8=5.25 精确一致 → 延迟由往返次数线性主导，不是序列化/包体主导
对照组：guides/recommendations/site-texts 均单查询 → 1.7-2.2ms，与本模型自洽
MAX 66.6ms 的 2.5 倍抖动与连接池等待特征相符（N+1 放大任何一次池等待）

1.3 25.4KB 包体构成（推算+定性，字段级精确占比待 staging 复测标定）

包体推算：featured 3,843B ÷ 6 ≈ 640B/产品；list ≈ 40 产品 × 640B ≈ 25.6KB ✓（与实测 26,057B 吻合）
唯二无界字段（schema 证据 backend/sql/005_packages.sql：两处 description TEXT NOT NULL DEFAULT ''）：
packages.description（产品级富文本，管理端自由录入，理论无上限）
package_components.description（每个 includes 项一份）
结构性冗余：leader 对象每产品重复一份（含 avatar URL）；恒空/恒定字段（dailySchedule[]/addons[]/originalPrice/difficulty/status）≈ 每产品 ~100B 纯协议噪音
结论（定性，高置信）：包体大头＝两级 description TEXT；精确占比（如 description:includes:leader = 5:3:2 之类）须 staging 拉一次真实响应做字节分账后回填，裁决不依赖该精确值

1.4 消费方现状（改动面评估依据）

BFF 已有缓存：server/src/bff/bff.service.ts:13 CACHE_TTL_MS=60_000，bff-map.ts:68 products 路由已标 cache:'public' → 选项 C 的代码已存在
注意：波波基线实测打的是 FastAPI 直连（base :8089 + /api/miniapp/*），未经过 BFF（perf_probe.py docstring 明示不测 BFF 转发层）→ BFF 缓存对基线数字无贡献，对 C 端 v2 流量是否实际生效待 staging 验证
前端契约本就不含列表 description：miniprogram/miniprogram/typings/api.d.ts Package（列表项）无 description 字段，PackageDetail extends Package 才有 → 后端列表超量返回是实现偏离契约，不是契约要求
唯一实际消费：miniprogram-v2/pages/category-package/category-package.ts:146（limit=20），:170 descText = r.description 渲染在列表卡（wxml:17 有 wx:if 守卫，description 缺失时块隐藏不报错）

二、优化选项 A / B / C

选项 A：响应裁剪（列表瘦身）

内容：list_products（连带 featured/curated/search 三个同源端点，均走 _map_product）增加列表态映射：

A1 硬裁剪：列表删 description 与 includes[].description（详情页 GET /products/{id} 本就返回全量 description+images，契约不动）
A2 截断变体：SUBSTRING(description,1,120) 作摘要保留在列表（前端零改动，descText 仍显示 teaser）
顺带 rider（强烈建议随 A 同单）：组件查询批量化——一条 SELECT ... FROM package_components WHERE package_id = ANY($1) ORDER BY package_id, sort_order 内存分组，N+1 → 3 次往返（packages+leader+components 各 1）。改动就在同一函数、同一测试面

预估收益：

包体：−40~60%（两级 description 是唯二无界项；精确值待 staging 分账复测）
延迟：A 本体几乎不动 P95（往返数不变）；rider 落地后 P95 预估 26.6 → 2-4ms（3 次往返 × ~0.55ms/次，与 featured 单位往返耗时一致）
A1 前端影响：category-package 列表卡 descText 块隐藏（wx:if 守卫，无报错）；A2 零前端改动

改动面：后端 1 个文件（miniapp_products.py，列表态开关+rider）；前端 0-1 个页面（A1 需 category-package 视觉确认）；契约零变更（Package 列表本无 description）。

选项 B：分页收紧 + 字段白名单

内容：默认 limit 50→20、cap 200→50；白名单化响应字段（剔除 originalPrice/difficulty/status/dailySchedule/addons 等恒定恒空字段）。

预估收益：

包体：小幅（恒定字段仅 ~100B/产品 ≈ 全包体 15%；不触碰 description 大头）
延迟：零收益（往返数不变）
代价：字段白名单动的是所有消费方都在读的响应形状——typings 同步、category-package/home 等页面逐字段核对、跨端契约评审，改动面与风险均大于 A，收益反而小于 A

改动面：后端 1 文件 + typings 1 文件 + 前端多页面核对（category-package/category-hotel/home 等全部消费 products 列表的页面）。

选项 C：缓存（BFF 层 TTL≤60s）

内容：代码已存在（见 1.4）。剩余工作是验证+登记，不是开发：

staging 确认 BFF 部署态且 /api/v2/products 二次请求返回 cached:true
观测冷 miss（每 TTL 窗口 1 次）仍为 ~26ms —— 该成本被 60s 摊薄，可接受
结果登记进 bff-map.md / 性能预算文档

预估收益：

服务端延迟：BFF 路由的 C 端流量平均延迟 → ~1-2ms（缓存命中路径）
明确不解决：① 客户端带宽——每个客户端每个 TTL 窗口的冷拉取仍要下载 25.4KB 全量包体；② 直连 FastAPI 的消费方（含波波基线口径）延迟照旧；③ N+1 的 42 次往返在每次冷 miss 时照样发生

改动面：零代码（除非 staging 验证发现 BFF 缓存失效 → 另计 0.5-1 人日修复）。缓存口径完全符合既有政策：docs/contracts/backend-info-pack-v2.md:152「缓存只许 site-texts/产品公开只读数据（TTL≤60s）」。

三、裁决建议（R1 倾向 A+C）

裁决：A1（或 A2，待 staging 字节分账后定）+ rider 批查 + C 验证登记

裁决理由：

互补而非重叠——A 管字节（客户端带宽+冷 miss 传输量，C 管不了），C 管服务端延迟屏蔽（A 的裁剪对往返数无贡献）。两者各覆盖对方盲区
C 近乎零成本——代码已存在且政策早已背书（TTL≤60s 白名单明文覆盖产品公开只读），只剩验证登记；放弃 C 等于丢掉已付费资产
rider 随 A 顺带——P95 离群的真根因是 N+1（1.2 的线性证据），只做 A+C 而不带 rider，直连 FastAPI 路径的 26.6ms 原样保留；rider 与 A 改同一函数、同一测试面，边际成本最低
契约风险最小——A 不动响应形状契约（Package 列表本就无 description），B 动；B 的白名单收益/风险比最差，否决 B（其分页收紧部分可在 A 落地后按需另议，不在本包强推）

反对意见（如实记录，均不推翻裁决）：

A2 截断是语义变更——列表 description 从全文变摘要，未来若有消费方按全文使用会踩静默截断坑 → 缓解：优先 A1（删字段，契约干净）；A2 仅在前端坚持要 teaser 时选用
60s 缓存意味着价格最长延迟 60s 可见——公开只读政策的既有接受项；缓解：下单/详情链路不走列表缓存，价格敏感操作不经过该路径
BFF 内存缓存是单实例 Map、无集中失效——当前流量规模可接受，登记为已知限制；多实例扩容时需重审
A 的包体收益比例（−40~60%）是推算——若 staging 字节分账显示大头另有其人（如 cover_url 巨长、leader avatar 重复占比超预期），A 的刀法须按分账结果重切 → 开工前先拉一次真实响应做字节分账（半小时级），再锁 A1/A2
C 的「已实现」未经 staging 实证——若验证发现 BFF 未部署或缓存不生效，C 从 0.5 人日涨到 1-1.5 人日，届时可评估是否降级为「仅登记待办」

四、工程量估算（人日）

选项	内容	后端	前端	验证/回归	合计
前置	staging 字节分账（拉真实响应逐字段计量）	—	—	0.5	0.5
A1+rider	列表裁剪两级 description + 组件批查（N+1→3 查询）	1.0	0.5（category-package 视觉适配）	0.5（perf_probe 复测）	2.0
A2 变体	截断 120 字替代硬裁剪（前端零改动）	0.5	0	0.5	1.5（替代 A1 时）
B	分页收紧+字段白名单+契约同步	1.0	1.0（多页面核对）	0.5	2.5（收益最低，已否决）
C	BFF 缓存 staging 验证+登记	0（已实现）	0	0.5	0.5（验证失败另计 0.5-1）
R1=A+C	A1+rider + C 验证（含前置分账）	1.0	0.5	1.5	≈2.5-3.0 人日

复测判据（验收口径，沿用波波 perf_probe.py 同脚本同机位）

products P95：26.6ms → ≤5ms（rider 后 3 次往返口径）
products 包体：26,057B → A1 ≤12KB / A2 ≤14KB（以分账实测校准）
featured：4.5ms / 3.8KB 不劣化（同函数改动，回归护栏）
BFF /api/v2/products：二次请求 cached:true 命中，命中延迟 ≤2ms
功能回归：category-package 列表三态正常、详情页 description/images 全量不变、search 关键词仍可命中 description（rider 保留搜索用全文列）

产物：本文件（裁决包，不含代码改动）。执行待刘总/派工岗按 R1 放行后另开工单。

依据链：staging-baseline-2026-09-14.json（波波实测）→ miniapp_products.py / bff.service.ts / bff-map.ts / api.d.ts / 005_packages.sql（读码）→ backend-info-pack-v2.md:152（缓存政策）。