root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
6f8f12314fde7aa0370c2cd0ae3ffd2b6e38705c
Neo-ZQYY/apps/admin-web/README.md
Neo 6f8f12314f feat: 累积功能变更 — 聊天集成、租户管理、小程序更新、ETL 增强、迁移脚本 
包含多个会话的累积代码变更：
- backend: AI 聊天服务、触发器调度、认证增强、WebSocket、调度器最小间隔
- admin-web: ETL 状态页、任务管理、调度配置、登录优化
- miniprogram: 看板页面、聊天集成、UI 组件、导航更新
- etl: DWS 新任务（finance_area_daily/board_cache）、连接器增强
- tenant-admin: 项目初始化
- db: 19 个迁移脚本（etl_feiqiu 11 + zqyy_app 8）
- packages/shared: 枚举和工具函数更新
- tools: 数据库工具、报表生成、健康检查
- docs: PRD/架构/部署/合约文档更新

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-06 00:03:48 +08:00

265 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 # 依赖声明
```
## 启动
```bash
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` 配置跨域
## 依赖
```json
{
"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）
- [x] 租户管理员 CRUD + 2 步创建 + 软删除（NS4.1）
- [x] 注册体系管理 — 简写ID 管理 + 店铺同步（NS4.1）
- [x] 调度任务最小运行间隔 + 强制执行（P16）
- [x] AI 监控后台 — Dashboard + 调度状态 + 调用明细 + 手动操作（P15）
- [x] 开发调试全链路日志 — DevTrace 页面 + 覆盖率扫描 + Span 树展示
- [x] P18 任务引擎运营看板 — 转移日志 + 待审核任务 + 参数管理（3 页面 + 9 API）
Reference in New Issue View Git Blame Copy Permalink