@@ -1,176 +0,0 @@
# admin 比价记录「技术成功/失败」口径与缺失提示设计
- **日期**：
- **范围**：后端 `shaguabijia-app-server` （ #209 落库与 C 端）+ 前端 `shaguabijia-admin-web`
- **涉及文件**：
- 后端：`app/admin/repositories/comparison_outcome.py` （ `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` **（ `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（ ）
|---|---|---|
| success | success | （无） |
| below_minimum | success | 未满起送 |
| store_closed | success | 门店打烊 |
| store_not_found | success | 未找到店 |
| items_not_found | success | 未找到菜 |
| no_delivery | success | 单点不配送 |
| unsupported | success | 平台·场景不支持 |
| failed / 其他未知 | failed | （无，这才是要排查的技术故障） |
| （
| （
**派生规则 ** ：
- 记录 `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（
outcome_hint : str | None = None # 缺失提示文案；None = 无缺失
```
原 `status` 字段**保留原样下发**（排查时可看后端落库原值）。前端只认 `admin_status` + `outcome_hint` ，不自己算口径。
## 后端实现（方案 A）
### 1. 新模块 `app/admin/repositories/comparison_outcome.py`（供 `queries.py` 与 `stats.py` 共用，避免循环 import）
``` python
from sqlalchemy import func
from app . models . comparison import ComparisonRecord
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 ] :
""" Python 层派生（列表用；raw_payload 已随 ORM 加载，零额外查询）。 """
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
def _original_expr ( ) :
return func . coalesce (
ComparisonRecord . raw_payload [ " record_status " ] . as_string ( ) ,
ComparisonRecord . raw_payload [ " status " ] . as_string ( ) ,
)
def admin_success_sql ( ) :
""" SQL 层 admin 成功判定（概览/大盘的 case/where 共用）。 """
original = _original_expr ( )
return original . in_ ( tuple ( ADMIN_SUCCESS_OUTCOMES ) ) | (
original . is_ ( None ) & ( ComparisonRecord . status == " success " )
)
```
### 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 成功 / (started - cancelled) # 分母不变，见 queries.py:532
```
**耗时分位 ** （ ， `_comparison_duration_aggregate*` ）：统计集从「`status == "success"` 」改为「admin 成功集」——用户已确认**统一口径纳入**这 6 类。改动点：`_comparison_status_condition` 系的耗时过滤条件改用 `_original_expr ∈ S` （或复用一个 `_admin_success_condition()` 表达式，列表/概览/大盘共用）。
### 4. 大盘 `stats.py` `dashboard_overview`
`period_comparison_stats` 的 success 分子（[stats.py:278-281 ](../../../shaguabijia-app-server/app/admin/repositories/stats.py ) 的 `case(status=='success')` ）现在**不含 below_minimum**（ #209 只改了概览、没同步大盘）。改用 `admin_success_sql()` （ `original ∈ S` ）口径，与概览一致。
**范围界定 ** ：两页成功率**分母都是 `total - cancelled` **（概览 [queries.py:532 ](../../src/../../../shaguabijia-app-server/app/admin/repositories/queries.py )、大盘 [stats.py:290 ](../../../shaguabijia-app-server/app/admin/repositories/stats.py )），口径一致、本次不动。真正的既有差异在**分子**：概览 success 含 `below_minimum` 、大盘不含。本次把两处分子都统一为 `original ∈ S` ，改完两页口径**完全一致**。副作用：大盘成功率因补上 `below_minimum` + 5 类而上升，概览因补上 5 类上升——均属口径调整、非数据异常。
## 前端实现
### 1. 状态列（[page.tsx:416](../../src/app/(main)/comparison-records/page.tsx)）
`render` 改用 `admin_status` 出标签（`STATUS_LABEL/COLOR` ： `outcome_hint` 非空 → 标签后跟 `<Tooltip title={outcome_hint}>` 包一个 ⚠（antd `WarningOutlined` ）。
### 2. 详情页状态（[page.tsx:627](../../src/app/(main)/comparison-records/page.tsx)）
同步用 `admin_status` + `outcome_hint` 。
### 3. `STATUS_LABEL` / `STATUS_COLOR`（ ）
精简：移除把 `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 端 / 大盘之外的成功率不受影响。
guke
guke