# Profeto Admin 后台管理系统

## 概述

Profeto 后台管理界面,为足球 LLM 预测系统提供运维管理能力。
**与前台共用同一套「报刊风」设计语言**:纸色底(paper)、墨色字(ink)、印报红唯一强调(press),
宋体标题、方正边框、细线分隔,无圆角、无彩色药丸标签。
支持响应式布局(移动端 / 平板 / 桌面)。

## 文件结构

```
src/admin/
├── AdminApp.tsx          # Admin 应用入口(独立路由)
├── AdminLayout.tsx       # 布局(报头式侧栏 + 报眉顶栏,健康状态每 60s 复检)
├── api.ts                # 统一 API 客户端(超时、错误处理、X-API-Key 自动附带)
├── dal.ts                # 数据访问层(封装所有 API 端点调用)
├── types.ts              # TypeScript 类型定义(与 FastAPI Pydantic 模型对齐)
├── components.tsx        # 通用 UI 组件(报刊风 Card/Badge/DataTable/Alert...)
├── routes.tsx            # 路由定义(/admin/*)
└── pages/
    ├── Dashboard.tsx     # 仪表盘(系统概览)
    ├── Collection.tsx    # 数据采集(触发采集任务,结果结构化展示)
    ├── Predictions.tsx   # 预测管理(触发预测 + 结算 + 记录展开)
    ├── Backtest.tsx      # 回测管理(汇总指标 + 逐场明细 + 模型评估)
    ├── Monitoring.tsx    # 监控面板(存活 + 数据库就绪,30s 自动巡检)
    ├── DataSources.tsx   # 数据源管理(数据源配置与测试)
    ├── LLMConfig.tsx     # LLM 配置(模型连接与统计)
    └── Config.tsx        # 系统配置(登录鉴权说明 + .env 查看与修改指南)
```

## 页面说明

### 1. 仪表盘 (`/admin`)
- 系统健康状态、联赛 / 比赛 / 预测数量统计(报纸数字版式)
- 已入库联赛列表
- 快捷操作导航

### 2. 数据采集 (`/admin/collection`)
- 选择数据源: Bzzoiro / Understat / Injuries
- 选择联赛、日期范围(Understat 为赛季)
- 触发采集任务;结果结构化展示(新增 / 更新 / 跳过 / 未匹配 / 错误)

### 3. 预测管理 (`/admin/predictions`)
- 触发预测(选择比赛 + 模式:多专家 / 单次)
- **预测结算**: 录入实际比分,调用 /eval/settle,供准确率统计使用
- 预测记录列表: 点击展开终裁理由与五路专家摘要

### 4. 回测管理 (`/admin/backtest`)
- 回测配置: 联赛(下拉)、日期范围、场数、模式
- 结果汇总: 已评分 / 1X2 准确率 / 比分 RMSE / 平均置信度
- 逐场明细: 实际比分 vs 预测比分,正误标记
- 模型评估: 各模型历史准确率(/eval/summary)

### 5. 监控面板 (`/admin/monitoring`)
- /health 存活检查 + /health/ready 数据库就绪检查
- 每 30 秒自动巡检,可手动「立即巡检」
- 服务名 / 版本 / 运行时间 / 检查项

### 6. 数据源管理 (`/admin/data-sources`)
- 数据源状态: API Key 配置状态(脱敏)
- 测试连接: 调用采集 API 验证
- 数据源说明文档

### 7. LLM 配置 (`/admin/llm-config`)
- 当前配置: provider, model, base_url
- 连接测试(会真实调用一次预测,产生 LLM 费用)
- 使用统计: 预测次数、延迟、有效率(从预测记录聚合)
- 可用模型列表

### 8. 系统配置 (`/admin/config`)
- **登录与鉴权**: 后台由密码登录保护(服务器 .env 的 ADMIN_PASSWORD),
  会话以 HttpOnly Cookie 保存;脚本直连接口可使用 ADMIN_API_KEY(X-API-Key 请求头)
- 配置列表: 脱敏显示 .env 配置项
- 配置修改指南: SSH 修改 .env + 重启服务

## 鉴权说明

后端 `ADMIN_API_KEY` 的渐进式策略:
- 未配置 → 写入型接口无鉴权(本地开发)
- 已配置 → 采集 / 回测 / 结算接口必须带 `X-API-Key` 请求头

前端在 `api.ts` 统一注入该请求头;密钥在「系统配置」页设置,
仅存于本机浏览器 localStorage。401 错误会提示到该页填写密钥。

## 路由设计

| 路径 | 页面 | 描述 |
|------|------|------|
| `/` | 先知主站 | 报纸风格预测展示 |
| `/admin` | 仪表盘 | 系统概览 |
| `/admin/collection` | 数据采集 | 采集任务管理 |
| `/admin/predictions` | 预测管理 | 预测、结算与记录 |
| `/admin/backtest` | 回测管理 | 策略回测 |
| `/admin/monitoring` | 监控面板 | 系统监控 |
| `/admin/data-sources` | 数据源管理 | 数据源配置 |
| `/admin/llm-config` | LLM 配置 | 模型管理 |
| `/admin/config` | 系统配置 | 密钥与参数配置 |

## 响应式布局

### 移动端 (< 768px)
- 侧边栏折叠为汉堡菜单,点击展开
- 表格隐藏,显示卡片视图
- 表单单列布局;按钮最小 44px 触摸目标
- 统计卡片 1 列

### 桌面 (> 1024px)
- 侧边栏固定显示;完整表格视图;统计卡片 4 列

## 技术实现

- **路由**: `react-router-dom` v6 嵌套路由
- **样式**: Tailwind CSS,与前台共用 paper/ink/press 色板与组件类
  (.btn / .field / .tab / .section-head / .skeleton 见 `src/index.css`)
- **API**: 统一 fetch 客户端,30s 超时,类型安全,X-API-Key 自动附带
- **类型**: TypeScript strict mode,与后端 Pydantic 模型对齐
- **错误处理**: ApiError 类 + 页面级 Alert 展示
- **触摸友好**: 所有可点元素 min-h-[44px]

## 启动方式

```bash
cd frontend
npm run dev
# 访问 http://localhost:5173/admin
```

## 访问入口

主站页面顶部「管理后台」链接可跳转至 `/admin`。
Admin 后台侧栏底部「返回前台版面」链接可回到 `/`。