From a0cd4ff4e9a22ed720cec46ac35532e1d101bea4 Mon Sep 17 00:00:00 2001 From: guke Date: Tue, 4 Aug 2026 14:59:54 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20admin=20=E6=AF=94?= =?UTF-8?q?=E4=BB=B7=E8=AE=B0=E5=BD=95=E6=8A=80=E6=9C=AF=E6=88=90=E5=8A=9F?= =?UTF-8?q?/=E5=A4=B1=E8=B4=A5=E5=8F=A3=E5=BE=84=E8=AE=BE=E8=AE=A1=20spec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 比价记录页把「跑完流程、外部原因致结果缺失」的 6 类(未找到店/菜、 打烊、单点不配送、不支持、未满起送)从「失败」改判为「成功 ⚠」(hover 看缺失原因),让「失败」红标签只剩技术故障,便于管理员排查。 方案 A:纯 admin 层派生(读 raw_payload.record_status),不碰 DB 存储/ #209 落库/C 端;admin 后台统一口径(列表+概览成功率+大盘)。 Co-Authored-By: Claude Opus 4.8 (1M context) --- ...admin-comparison-outcome-display-design.md | 159 ++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-04-admin-comparison-outcome-display-design.md diff --git a/docs/superpowers/specs/2026-08-04-admin-comparison-outcome-display-design.md b/docs/superpowers/specs/2026-08-04-admin-comparison-outcome-display-design.md new file mode 100644 index 0000000..3de3930 --- /dev/null +++ b/docs/superpowers/specs/2026-08-04-admin-comparison-outcome-display-design.md @@ -0,0 +1,159 @@ +# admin 比价记录「技术成功/失败」口径与缺失提示设计 + +- **日期**：2026-08-04 +- **范围**：后端 `shaguabijia-app-server`（admin 层，**方案 A**：无 schema 变更、无迁移、不碰 #209 落库与 C 端）+ 前端 `shaguabijia-admin-web` +- **涉及文件**： + - 后端：`app/admin/repositories/queries.py`（列表派生 + 概览口径）、`app/admin/schemas/comparison.py`（新增两字段）、`app/admin/repositories/stats.py`（大盘成功率分子口径） + - 前端：`src/app/(main)/comparison-records/page.tsx`、`src/lib/types.ts` + - 文档：`shaguabijia-app-server/docs/guides/比价结果卡片-状态口径与交互参考.md`（补 admin 口径说明） + +## 目标 + +比价记录页（管理员排查工具）把「流程正常跑完、只是外部原因导致结果缺失」的记录——未找到店 / 未找到菜 / 门店打烊 / 单点不配送 / 平台·场景不支持 / 未满起送——从「失败」改判为 **🟢 成功 ⚠**（hover 看具体缺失原因）。让「失败」红标签**只剩真正的技术故障**，管理员一眼定位系统问题。改动范围：**admin 后台内部统一**（比价记录页状态列 + 概览成功率 + 数据大盘），不动 C 端。 + +## 背景与现状冲突 + +- **#209** 把 `store_closed / store_not_found / items_not_found / no_delivery / unsupported` 归一化成记录级 `failed` 落库，`below_minimum` 归 `success`；成功率按此算。 +- 前端 `STATUS_LABEL` 把这些细分值 + `failed` 全显示「失败」（[page.tsx:35](../../src/app/(main)/comparison-records/page.tsx)）。 +- 问题：这些是「跑完流程、外部结果缺失」，不是系统故障。全归「失败」粒度太粗，管理员无法区分「系统的锅」vs「目标平台本来就没有这家店 / 这些菜」。 +- **数据来源已坐实**：原始业务结局保存在 `raw_payload["record_status"]`（优先）或 `raw_payload["status"]`（兜底），**每条记录都有**（harvest 与 POST 两条写路径都落，见 `repositories/comparison.py:810` 注释）。admin 列表用裸 `select(ComparisonRecord)`、**本就全量加载 `raw_payload`**（C 端 `list_records` 才 `defer`），故列表派生**零额外查询**。概览/大盘用 `raw_payload["record_status"].as_string()` 在 SQL 里分类（跨方言写法，#209 迁移已验证可用）。 + +## admin 口径（核心） + +**原始结局** `original = raw_payload["record_status"] or raw_payload["status"]`。 + +| original | admin_status | outcome_hint（hover） | +|---|---|---| +| success | success | （无） | +| below_minimum | success | 未满起送 | +| store_closed | success | 门店打烊 | +| store_not_found | success | 未找到店 | +| items_not_found | success | 未找到菜 | +| no_delivery | success | 单点不配送 | +| unsupported | success | 平台·场景不支持 | +| failed / 其他未知 | failed | （无，这才是要排查的技术故障） | +| （cancelled 记录，status 列） | cancelled | （无） | +| （running 记录，status 列） | running | （无） | + +**派生规则**： +- 记录 `status == "cancelled"` → `admin_status=cancelled`；`status == "running"` → `admin_status=running`（生命周期状态直接取 `status`，不看 original）。 +- 否则看 original：∈ **admin 成功集** `S` → `admin_status=success`，`outcome_hint=_OUTCOME_HINTS.get(original)`（`success` 本身 → `None`）。 +- original 为 `failed` 或未知非 `S` → `admin_status=failed`，`outcome_hint=None`。 +- **兜底**：`raw_payload` 缺 original（极老记录）→ 用 `status` 列（`success→success` / `failed→failed`），`outcome_hint=None`。 + +其中 `S = {success, below_minimum, store_closed, store_not_found, items_not_found, no_delivery, unsupported}`。 + +## 数据契约（新增两字段） + +`AdminComparisonListItem`（`AdminComparisonDetail` 继承）新增： + +```python +admin_status: str # success / failed / cancelled / running（admin 口径） +outcome_hint: str | None = None # 缺失提示文案；None = 无缺失 +``` + +原 `status` 字段**保留原样下发**（排查时可看后端落库原值）。前端只认 `admin_status` + `outcome_hint`，不自己算口径。 + +## 后端实现（方案 A） + +### 1. 常量 + 派生（`queries.py`，紧邻既有 `_COMPARISON_STATUS_ALIASES`） + +```python +_ADMIN_SUCCESS_OUTCOMES = frozenset({ + "success", "below_minimum", "store_closed", + "store_not_found", "items_not_found", "no_delivery", "unsupported", +}) +_OUTCOME_HINTS = { + "below_minimum": "未满起送", "store_closed": "门店打烊", + "store_not_found": "未找到店", "items_not_found": "未找到菜", + "no_delivery": "单点不配送", "unsupported": "平台·场景不支持", +} + +def _derive_admin_outcome(raw_payload: dict | None, status: str) -> tuple[str, str | None]: + if status in ("cancelled", "running"): + return status, None + raw = raw_payload or {} + original = raw.get("record_status") or raw.get("status") + if original is None: # 极老记录兜底 + return ("success" if status == "success" else "failed"), None + if original in _ADMIN_SUCCESS_OUTCOMES: + return "success", _OUTCOME_HINTS.get(original) + return "failed", None +``` + +### 2. 列表 `list_comparison_records` + +在现有瞬态挂载段（`_attach_*` / `ad_revenue_yuan` 之后）对每条 `record`： + +```python +record.admin_status, record.outcome_hint = _derive_admin_outcome(record.raw_payload, record.status) +``` + +`raw_payload` 列表已加载，无 N+1。schema 加上述两字段（`from_attributes` 读出）。 + +### 3. 概览 `comparison_records_summary` + +把 `success` / `completed` 的 `case` 改用 original 口径： + +```python +_original_expr = func.coalesce( + ComparisonRecord.raw_payload["record_status"].as_string(), + ComparisonRecord.raw_payload["status"].as_string(), +) +# admin 成功 = original ∈ S OR (original IS NULL AND status == 'success') +# completed = admin 成功 + 纯 failed（admin 口径失败） +# success_rate = admin 成功 / completed +``` + +**耗时分位**（avg / p50 / p95，`_comparison_duration_aggregate*`）：统计集从「`status == "success"`」改为「admin 成功集」——用户已确认**统一口径纳入**这 6 类。改动点：`_comparison_status_condition` 系的耗时过滤条件改用 `_original_expr ∈ S`（或复用一个 `_admin_success_condition()` 表达式，列表/概览/大盘共用）。 + +### 4. 大盘 `stats.py` `dashboard_overview` + +`period_comparison_success`（分子，[stats.py:288](../../../shaguabijia-app-server/app/admin/repositories/stats.py) 的聚合 case）改用 `_original_expr ∈ S` 口径，与概览一致。 + +**范围界定（重要）**：大盘成功率分母是 `total - cancelled`（[stats.py:290](../../../shaguabijia-app-server/app/admin/repositories/stats.py)），与比价记录页概览的 `completed`（success+failed）分母**本就不同**（running 的处理差异）。**此既有差异不在本次范围**——本次只统一「6 类算成功」这个**分子**口径；两页分母口径保持现状，避免波及大盘既有数字。 + +## 前端实现 + +### 1. 状态列（[page.tsx:416](../../src/app/(main)/comparison-records/page.tsx)） + +`render` 改用 `admin_status` 出标签（`STATUS_LABEL/COLOR`：success→绿「成功」/ failed→红「失败」/ cancelled→「中途退出」/ running→「进行中」）；`outcome_hint` 非空 → 标签后跟 `` 包一个 ⚠（antd `WarningOutlined`）。 + +### 2. 详情页状态（[page.tsx:627](../../src/app/(main)/comparison-records/page.tsx)） + +同步用 `admin_status` + `outcome_hint`。 + +### 3. `STATUS_LABEL` / `STATUS_COLOR`（[page.tsx:35](../../src/app/(main)/comparison-records/page.tsx)） + +精简：移除把 `store_closed/store_not_found/items_not_found/no_delivery/unsupported` 直接映射「失败」的行（统一走 `admin_status`）；保留 `success/failed/cancelled/running`。`below_minimum` 同理不再单列。 + +### 4. `types.ts` + +`ComparisonRecordListItem` 加 `admin_status: string`、`outcome_hint: string | null`。 + +### 5. 概览成功率 + +前端只展示后端返回的数字，口径变化对前端透明；检查概览区有无「成功率」口径说明文案需同步。 + +## 不改 / 一致性 + +- `status` 列语义、#209 落库、完成奖励幂等、C 端「我的比价」/ 首页轮播 / 省钱战绩口径：**全不动**。 +- admin 口径（跑完即成功）**刻意宽于** C 端业务口径；因大盘也一并改，**admin 后台内部自洽**。 +- 在状态口径文档补一段「admin 记录页口径」：说明 admin 成功率是「技术完成率」，与 C 端业务口径不同，避免以后有人拿两者对不上而误判为 bug。 + +## 边界 + +- `raw_payload` 缺 `record_status/status`（极老记录）：`admin_status` 取 `status` 列，`outcome_hint=None`，不加 ⚠。 +- 多平台 `platform_results`：以记录级 `record_status` 为准（pricebot 已归纳），不逐平台判。 +- 迁移未覆盖、`status` 列仍是细分值的老记录：`original` 优先，仍正确归类（细分值本身 ∈ S）。 + +## 测试 + +- 后端新增 `_derive_admin_outcome` 单测：各 original + cancelled/running + raw_payload 缺失兜底，验 `(admin_status, outcome_hint)`。 +- `tests/test_comparison_admin_summary.py`：造含 6 类 + success + failed + cancelled 的记录，验 `success` / `completed` / `success_rate` / 耗时分位按新口径。 +- `tests/test_admin_read.py`：列表返回 `admin_status` / `outcome_hint`（成功·有缺失、纯失败、纯成功各一条）。 + +## 影响面 / 风险 + +- 概览/大盘 SQL 读 JSONB（`raw_payload['record_status'].as_string()`）：PG 上是 JSONB，跨方言 `.as_string()` #209 迁移已用；SQLite 测试走 JSON1。admin 低频、P0 量级，性能可忽略。 +- **admin 成功率数字会上升**（这 6 类从失败转成功）：需知会运营这是**口径调整、非数据异常**。C 端 / 大盘之外的成功率不受影响。