Neo-ZQYY/apps/admin-web

apps/admin-web — 管理后台

基于 React + Vite + Ant Design 构建的 ETL 管理后台，提供任务管理、调度配置、数据查看、ETL 监控和运维控制功能。

技术栈

• React 19 + TypeScript
• Vite 6（构建工具）
• Ant Design 5（UI 组件库）
• Zustand 5（状态管理）
• React Router DOM 7（路由）
• Axios（HTTP 客户端）
• Day.js（日期处理）

目录结构

apps/admin-web/
├── src/
│   ├── App.tsx              # 主布局 + 路由配置 + 路由守卫
│   ├── main.tsx             # 应用入口
│   ├── pages/               # 18 个功能页面
│   │   ├── Login.tsx        # 登录页
│   │   ├── TaskConfig.tsx   # 任务配置（Flow 选择 + 任务勾选 + 参数设置）
│   │   ├── TaskManager.tsx  # 任务管理（队列 + 执行历史 + 实时日志）
│   │   ├── ETLStatus.tsx    # ETL 状态（游标监控 + 最近执行）
│   │   ├── DBViewer.tsx     # 数据库查看器（Schema/表/列浏览 + SQL 执行）
│   │   ├── LogViewer.tsx    # 日志查看器
│   │   ├── EnvConfig.tsx    # 环境配置管理
│   │   ├── OpsPanel.tsx     # 运维面板（服务启停 + Git + 系统监控）
│   │   ├── TenantAdmins/    # 租户管理员管理（2步创建 + 软删除 + 简写ID管理）
│   │   ├── AIDashboard.tsx  # AI 运行总览（统计卡片 + 趋势图 + 饼图 + 预算 + 告警）
│   │   ├── AITriggerJobs.tsx # AI 调度状态（分页表格 + 筛选 + 手动重跑）
│   │   ├── AIRunLogs.tsx    # AI 调用明细（分页表格 + 详情抽屉）
│   │   ├── AIOperations.tsx # AI 手动操作（重跑 + 缓存失效 + 批量执行 + 告警管理）
│   │   ├── DevTrace.tsx    # 开发调试全链路日志（覆盖率 + 筛选 + 请求列表 + Span 树 + 设置）
│   │   ├── TransferLog.tsx      # P18 客户转移日志（分页表格 + 门店/时间/助教筛选 + guard_checks 标签）
│   │   ├── PendingReview.tsx    # P18 待审核任务（分页表格 + 重新分配/关闭弹窗 + 转移历史抽屉）
│   │   ├── TaskEngineConfig.tsx # P18 参数管理（全局默认+门店覆盖 + 行内编辑 + 权重卡片编辑）
│   │   └── TriggerJobs.tsx      # 定时任务管理（biz.trigger_jobs 表展示 + 手动执行 + 清空任务）
│   ├── components/          # 可复用组件
│   │   ├── BusinessDayHint.tsx   # 营业日提示组件
│   │   ├── DwdTableSelector.tsx  # DWD 表选择器
│   │   ├── ErrorBoundary.tsx     # 错误边界
│   │   ├── LogStream.tsx         # 实时日志流组件
│   │   ├── ScheduleTab.tsx       # 调度配置标签页（含最小运行间隔、强制执行、上次成功时间）
│   │   └── TaskSelector.tsx      # 任务选择器
│   ├── api/                 # API 调用层
│   │   ├── client.ts        # Axios 实例（baseURL + JWT 拦截器）
│   │   ├── businessDay.ts   # 营业日配置 API
│   │   ├── tasks.ts         # 任务配置 API
│   │   ├── execution.ts     # 任务执行 API
│   │   ├── schedules.ts     # 调度管理 API
│   │   ├── etlStatus.ts     # ETL 状态 API
│   │   ├── dbViewer.ts      # 数据库查看器 API
│   │   ├── envConfig.ts     # 环境配置 API
│   │   ├── opsPanel.ts      # 运维面板 API
│   │   ├── registry.ts      # 注册体系 API（租户/店铺/简写ID/同步）
│   │   ├── tenantAdmins.ts  # 租户管理员 CRUD API
│   │   ├── adminAI.ts       # AI 监控后台 API（Dashboard/调度/调用/缓存/预算/批量/告警）
│   │   ├── devTrace.ts     # DevTrace 全链路日志 API（日期/请求/详情/清理/设置/覆盖率）
│   │   └── taskEngine.ts  # P18 任务引擎运营看板 API（转移日志/待审核/参数管理，9 个函数）
│   ├── store/
│   │   ├── authStore.ts     # Zustand 认证状态（JWT 持久化 + hydrate）
│   │   └── businessDayStore.ts  # 营业日状态管理
│   ├── types/               # TypeScript 类型定义
│   │   └── devTrace.ts     # DevTrace 类型（TraceSpan/TraceRequest/TraceDetail/TraceSettings/TraceCoverage）
├── index.html               # HTML 入口
├── vite.config.ts           # Vite 配置
├── tsconfig.json            # TypeScript 配置
└── package.json             # 依赖声明

启动

cd apps/admin-web
pnpm install
pnpm dev          # 启动开发服务器（默认 http://localhost:5173）
pnpm build        # 生产构建
pnpm preview      # 预览生产构建

页面功能

登录页 (/login)

用户名密码登录，JWT 令牌存储在 localStorage，通过 Zustand authStore 管理。

任务配置 (/)

ETL 任务的核心配置界面：

• 选择执行流程（7 种 Flow）
• 勾选要执行的任务（按业务域分组）
• 设置处理模式（增量/校验/全窗口）
• 配置时间窗口参数（含营业日提示）
• 实时预览生成的 CLI 命令
• 一键执行或加入队列

任务管理 (/task-manager)

• 查看执行队列（拖拽排序、删除、取消）
• 执行历史列表（状态、耗时、退出码、终止操作）
• 实时日志流（WebSocket 推送）

ETL 状态 (/etl-status)

• 各 ODS 表的数据游标（最后抓取时间、记录数）
• 最近 50 条执行记录

数据库查看器 (/db-viewer)

• 浏览 ETL 数据库 Schema → 表 → 列结构
• 执行只读 SQL 查询（带安全限制）
• 结果表格展示

日志查看器 (/log-viewer)

查看历史执行的完整日志输出。

环境配置 (/env-config)

查看和编辑根 .env 文件中的配置项（敏感值脱敏显示）。

运维面板 (/ops-panel)

• 服务状态监控（test/prod 环境的 PID、内存、CPU）
• 服务启停控制（启动/停止/重启）
• Git 状态查看和 pull 操作
• 依赖同步（uv sync）
• 系统资源概况（CPU、内存、磁盘）

租户管理员管理 (/tenant-admins)

• 管理员列表（支持分页、关键词搜索、显示/隐藏已禁用记录）
• 2 步创建流程：第 1 步选择租户 + 输入账号信息 + 选择管辖门店；第 2 步可选设置简写ID
• 软删除管理员（二次确认 → is_active=false）
• 编辑管理员（用户名可修改，需校验唯一性；所属租户只读）
• 简写ID 管理弹窗：展示租户下所有店铺及当前 code，支持修改和查看变更历史
• 手动触发店铺同步（从 ETL 库同步最新店铺信息）

AI 运行总览 (/ai/dashboard)

AI 模块运行状况一览：

• 顶部统计卡片（今日调用次数、成功率、Token 消耗、平均延迟）
• 近 7 天趋势折线图（调用量 + 成功率）
• 各 App 调用占比饼图
• Token 预算使用进度条（日/月）
• 告警列表 + App 健康状态 + App 配置信息（只读）
• 支持门店筛选

AI 调度状态 (/ai/trigger-jobs)

调度任务执行状态监控：

• 分页表格（事件类型、会员、状态、执行链、耗时）
• 筛选器（event_type / status / site_id / 日期范围）
• 今日去重跳过数统计
• 操作列：查看详情、手动重跑（二次确认）

AI 调用明细 (/ai/run-logs)

AI 调用记录追踪：

• 分页表格（app_type、trigger_type、member_id、tokens、延迟、状态）
• 筛选器（app_type / status / trigger_type / site_id / 日期范围）
• 点击行展开详情抽屉（完整 prompt/response/error_message）

AI 手动操作 (/ai/operations)

AI 人工干预操作：

• 手动重跑（App 选择 + 会员 + 门店 → 单次执行）
• 缓存失效（按 App / 会员 / 门店批量失效）
• 批量执行（成本二次确认流程：预估 → 确认弹窗 → 执行）
• 告警管理（告警列表 + 确认/忽略操作）

开发调试全链路日志 (/dev-trace)

后端请求全链路追踪日志的可视化查看与管理：

• 覆盖率状态栏：路由/Service/Job/SSE/WS 五维度进度条 + 未覆盖项列表
• 筛选栏：日期、时间范围、trace_type、HTTP 方法、路径关键词、状态码、最小耗时、仅错误、Span 类型
• 请求列表：分页表格（时间/类型/方法/路径/状态/耗时/DB 查询数/错误标记）
• Span 链路树：选中请求后展示完整 span 树，支持缩进层级、SQL 详情、参数、错误信息
• 设置抽屉：日志开关、记录 SQL/参数、保留天数、日志目录、手动清理日期范围
• 覆盖率扫描：手动触发 AST 扫描，检测追踪覆盖情况

对应后端模块 apps/backend/app/trace/，通过 8 个 admin API 端点（/api/admin/dev-trace/*）通信，需 admin 角色鉴权。

客户转移日志 (/task-engine/transfer-log)

P18 任务引擎运营看板 — 转移日志页面：

• 分页表格展示 biz.coach_task_transfer_log 记录
• 筛选器：门店 ID、日期范围（RangePicker）、助教 ID
• guard_checks JSON 渲染为彩色标签（通过/未通过）
• transfer_reason 映射中文标签（连续召回失败/人工重新分配/归属变更）

待审核任务 (/task-engine/pending-review)

P18 任务引擎运营看板 — 待审核任务页面：

• 分页表格展示 status='pending_review' 的任务
• 超级管理员操作列：重新分配（输入目标助教 ID）、关闭（填写原因）
• 点击客户名打开转移历史抽屉
• 门店管理员只读（无操作列）

参数管理 (/task-engine/config)

P18 任务引擎运营看板 — 参数管理页面：

• 展示 biz.cfg_task_generator_params 全局默认 + 门店覆盖参数
• 行内编辑单个参数值
• 权重参数（w_rs/w_ms/w_ml）使用卡片编辑弹窗，前端预校验三者之和 = 1.0
• 新增门店覆盖（Select 选择参数名 + InputNumber 输入值）
• 删除门店覆盖（全局默认参数禁止删除）
• 超级管理员可编辑/新增/删除；门店管理员只读

定时任务管理 (/trigger-jobs)

biz.trigger_jobs 表中定时任务的管理页面：

• 表格展示所有定时任务（名称、触发条件、Cron/间隔配置、状态、上次执行时间）
• 手动执行单个任务（二次确认）
• 清空所有任务（Popconfirm 二次确认 + Modal 成功/失败反馈）
• 执行期间按钮 loading 状态防止重复操作

认证与路由守卫

• 所有功能页面通过 PrivateRoute 组件保护
• 未登录自动重定向到 /login
• JWT 令牌通过 Axios 拦截器自动附加到请求头
• 应用启动时通过 hydrate() 从 localStorage 恢复认证状态

API 层

src/api/client.ts 创建 Axios 实例，配置：

• baseURL：默认 http://localhost:8000
• 请求拦截器：自动附加 Authorization: Bearer <token>
• 响应拦截器：401 时自动清除认证状态并跳转登录

各 API 模块对应后端路由，提供类型安全的调用接口。

状态管理

使用 Zustand 管理全局状态：

认证状态 (authStore)：

• isAuthenticated：是否已登录
• token / refreshToken：JWT 令牌
• login() / logout() / hydrate()：状态操作

营业日状态 (businessDayStore)：

• businessDayStartHour：营业日分割点
• init() / refresh()：配置获取与刷新

与后端的关系

管理后台通过 REST API 与 apps/backend/ 通信：

• 开发环境：Vite 代理到 http://localhost:8000
• 生产环境：通过 CORS_ORIGINS 配置跨域

依赖

{
  "react": "^19.1.0",
  "react-dom": "^19.1.0",
  "react-router-dom": "^7.6.1",
  "antd": "^5.24.7",
  "axios": "^1.9.0",
  "zustand": "^5.0.5",
  "dayjs": "^1.11.19"
}

Roadmap

• 用户申请审批界面（对接 /api/xcx-auth 审批端点）
• 数据看板页面（助教业绩、财务日报、客户分析）
• 权限管理界面（角色/权限配置）
• 暗色主题支持
• 国际化（i18n）
• 租户管理员 CRUD + 2 步创建 + 软删除（NS4.1）
• 注册体系管理 — 简写ID 管理 + 店铺同步（NS4.1）
• 调度任务最小运行间隔 + 强制执行（P16）
• AI 监控后台 — Dashboard + 调度状态 + 调用明细 + 手动操作（P15）
• 开发调试全链路日志 — DevTrace 页面 + 覆盖率扫描 + Span 树展示
• P18 任务引擎运营看板 — 转移日志 + 待审核任务 + 参数管理（3 页面 + 9 API）