Neo-ZQYY/docs/_overview/02b-adminweb-page-matrix.md

# admin-web 19 路由业务指纹矩阵

> 生成日期：2026-05-04 ／ 视角：系统运维（开发 + 运维操作 ETL 库 + AI 监控） ／ 用户：Neo + 运维成员
> 来源：`apps/admin-web/src/App.tsx`、`apps/admin-web/src/pages/*.tsx`、`apps/admin-web/src/api/*.ts`
> 后端 baseURL：`/api`（见 `apps/admin-web/src/api/client.ts`），路由挂载见 `apps/backend/app/main.py` L203-L246

---

## 一、菜单结构（7 一级 + 子菜单）

```
Sider（侧边栏）
├─ /dashboard            运行状态（首页）
├─ /etl-tasks            ETL 任务管理（5 子 Tab：config/queue/schedule/history/status）
├─ task-engine-group     小程序任务管理 ▼
│   ├─ /task-engine/trigger-jobs    定时任务
│   ├─ /task-engine/transfer-log    转移日志
│   ├─ /task-engine/pending-review  待审核任务
│   └─ /task-engine/config          参数管理
├─ /triggers             触发器管理（4 子 Tab：all/biz/ai/etl）
├─ ai-group              AI 管理 ▼
│   ├─ /ai/dashboard            总览
│   ├─ /ai/operations           手动操作
│   ├─ /ai/prewarm              预热进度
│   ├─ /triggers?tab=ai         触发器设置（跳到 TriggerManager AI Tab）
│   └─ /ai/trigger-jobs         调度历史
├─ /tenant-admins        租户管理员
├─ settings-group        系统设置 ▼
│   ├─ /settings/env-config         环境配置
│   ├─ /settings/runtime-context    业务运行上下文 / 沙箱
│   └─ /triggers?tab=biz            触发器配置（跳到 TriggerManager 业务 Tab）
└─ logs-group            日志调试 ▼
    ├─ /logs/dev-trace          DevTrace（全链路日志）
    ├─ /logs/ai-run-logs        AI 调用明细
    └─ /logs/db-viewer          数据库查看器
```

设计意图：

- 一级菜单按业务域聚合（运行状态 / ETL / 小程序任务引擎 / 触发器 / AI / 租户 / 设置 / 日志）。
- `?tab=` 参数使 AI 与系统设置共用 `/triggers` 一个页面，不同入口落到不同 Tab。
- 历史上是 11 个一级项（CHANGE 2026-07-14 Task 7.1 重组为 7 个），合并的页面（`TaskConfig`、`TaskManager`、`ETLStatus`、`AITriggers`）以子组件形式被新页面 import，未直接挂载路由。

---

## 二、菜单 → 路由 → 页面 → 后端 API 映射

| 一级菜单 | 子菜单 | 路由 | 页面文件 | 主要后端 API（前缀 `/api`） | 设计目的 |
|---|---|---|---|---|---|
| —（登录） | — | `/login` | `Login.tsx` | `POST /auth/login`（authStore） | JWT 登录，成功跳 `/dashboard` |
| 运行状态 | — | `/dashboard` | `Dashboard.tsx` | `GET /ops/system`、`GET /ops/services`、`GET /ops/git`、`GET /admin/db-health`、`GET /admin/ai/trigger-jobs` | 登录后默认首页：服务器资源 + 服务/Git 状态 + DB 健康 + AI 总览 + AI 调度摘要 |
| ETL 任务管理 | — | `/etl-tasks` | `ETLTasks.tsx`（包 5 Tab） | （见各 Tab） | 合并 ETL 五大场景为 Tab：发起 / 队列 / 调度 / 历史 / 状态 |
| ↳ config | — | `/etl-tasks?tab=config` | `TaskConfig.tsx`（被 ETLTasks 引用） | `GET /tasks`、`POST /tasks/validate`、`POST /execution/queue`、`POST /execution/run`、`POST /schedules`、`GET /tasks/flows` | Flow 选择 + 处理模式 + 时间窗口 + 提交 / 直跑 / 创建调度 |
| ↳ queue | — | `/etl-tasks?tab=queue` | `TaskManager.tsx::QueueTab` | `GET /execution/queue`、`DELETE /execution/queue/:id`、`POST /execution/:id/cancel`、WS `/ws/logs/:id` | 当前队列 + WebSocket 实时日志 |
| ↳ schedule | — | `/etl-tasks?tab=schedule` | `components/ScheduleTab.tsx` | `GET/POST/PUT/DELETE /schedules`、`PATCH /schedules/:id/toggle`、`POST /schedules/:id/run` | 调度任务 CRUD + 启停 + 立即执行 |
| ↳ history | — | `/etl-tasks?tab=history` | `TaskManager.tsx::HistoryTab` | `GET /execution/history`、`POST /execution/:id/rerun`、`POST /execution/cleanup-output` | 执行历史 + 重跑 + 清理输出 |
| ↳ status | — | `/etl-tasks?tab=status` | `ETLStatus.tsx`（被 ETLTasks 引用） | `GET /etl-status/cursors`、`GET /etl-status/recent-runs` | 任务游标 + 最近执行（success/failed/running 统计） |
| 小程序任务管理 | 定时任务 | `/task-engine/trigger-jobs` | `TriggerJobs.tsx` | `GET /trigger-jobs`、`POST /trigger-jobs/:id/run`、`DELETE /admin/task-engine/clear-all-tasks` | `biz.trigger_jobs` 列表 + 手动执行 + 清空助教任务（高危） |
| ↳ | 转移日志 | `/task-engine/transfer-log` | `TransferLog.tsx` | `GET /admin/task-engine/transfer-log` | P18 客户转移日志（门店/时间/助教筛选 + guard_checks 标签） |
| ↳ | 待审核任务 | `/task-engine/pending-review` | `PendingReview.tsx` | `GET /admin/task-engine/pending-review`、`POST .../:id/reassign`、`POST .../:id/close`、`GET .../transfer-log/:memberId/history` | 待审核任务列表 + 重新分配 + 关闭 + 客户历史抽屉 |
| ↳ | 参数管理 | `/task-engine/config` | `TaskEngineConfig.tsx` | `GET /admin/task-engine/config`、`PUT /admin/task-engine/config/:id`、`POST /admin/task-engine/config`、`DELETE /admin/task-engine/config/:id` | `biz.cfg_task_generator_params` 全局/门店覆盖参数 + 权重卡片编辑 |
| 触发器管理 | — | `/triggers` | `TriggerManager.tsx`（包 4 Tab） | （见各 Tab） | 聚合 biz / ai / etl 三类触发器为统一管理入口 |
| ↳ all | — | `/triggers?tab=all` | `TriggerManager.tsx::AllTriggersTab` | `GET /admin/triggers/unified` | 跨源只读统一视图 |
| ↳ biz | — | `/triggers?tab=biz` | `TriggerManager.tsx::BizTriggersTab` | `GET /trigger-jobs`、`PATCH /trigger-jobs/:id/config` | 业务触发器列表 + 编辑 cron / 间隔秒数 |
| ↳ ai | — | `/triggers?tab=ai` | `TriggerManager.tsx::AITriggersTab`（包 `AITriggers` + `AIOperations` + `AITriggerJobs`） | `GET /admin/ai/triggers`、`PATCH /admin/ai/triggers/:id`、`POST /admin/ai/trigger-event`、`POST /admin/ai/trigger-jobs/:id/retry`、`POST /admin/ai/cache/invalidate`、`POST /admin/ai/run/:appType`、`POST /admin/ai/batch-run`、`POST /admin/ai/batch-run/confirm`、`GET/POST /admin/ai/alerts/:id/(ack\|ignore)` | AI 触发器启停 + 编辑 cron + AI 手动操作 + 调度历史 |
| ↳ etl | — | `/triggers?tab=etl` | `TriggerManager.tsx::ETLTriggersTab` | `GET /schedules` | `meta.scheduled_tasks` 调度任务只读列表 |
| AI 管理 | 总览 | `/ai/dashboard` | `AIDashboard.tsx` | `GET /admin/ai/dashboard` | 4 卡 + 7 天趋势 + App 占比 + 预算进度 + App 健康 + 最近告警 |
| ↳ | 手动操作 | `/ai/operations` | `AIOperations.tsx` | `POST /admin/ai/trigger-jobs/:id/retry`、`POST /admin/ai/cache/invalidate`、`POST /admin/ai/batch-run(/confirm)`、`POST /admin/ai/run/:appType`、`POST /admin/ai/trigger-event`、`GET /admin/ai/alerts`、`POST /admin/ai/alerts/:id/(ack\|ignore)` | 重跑 / 缓存失效 / 按需重跑 / 批量执行 / 告警管理 / 越过去重 |
| ↳ | 预热进度 | `/ai/prewarm` | `AIPrewarm.tsx` | `GET /admin/ai/prewarm/progress`、`POST /admin/ai/run/:appType`（app2_finance / app2a_finance_area）、`POST /admin/ai/trigger-event` | app2_finance 72 组合（8 时间 × 9 区域）覆盖率 + 一键补缺 + 单组合重跑 |
| ↳ | 触发器设置 | `/triggers?tab=ai` | （跳转 TriggerManager） | （同 ai Tab） | 入口跳转，不渲染独立页面 |
| ↳ | 调度历史 | `/ai/trigger-jobs` | `AITriggerJobs.tsx` | `GET /admin/ai/trigger-jobs`、`GET /admin/ai/trigger-jobs/:id`、`POST /admin/ai/trigger-jobs/:id/retry` | 事件链调度记录 + 详情 + 重跑（含今日去重统计） |
| 租户管理员 | — | `/tenant-admins` | `TenantAdmins/index.tsx` | `GET/POST/PATCH/DELETE /admin/tenant-admins`、`POST /admin/tenant-admins/:id/reset-password`、`GET /admin/registry/tenants`、`GET .../sites`、`PATCH .../sites/:id/code`、`GET .../sites/:id/code-history`、`POST/DELETE .../sites` | 租户管理员 CRUD + 简写 ID 管理 + 门店建删 |
| 系统设置 | 环境配置 | `/settings/env-config` | `EnvConfig.tsx` | `GET /env-config`、`PUT /env-config`、`GET /env-config/export` | `.env` 键值对编辑 + 导出（敏感值脱敏） |
| ↳ | 业务运行上下文 / 沙箱 | `/settings/runtime-context` | `RuntimeContext.tsx` | `GET /admin/runtime-context/sites`、`PATCH /admin/runtime-context` | 多门店 live/sandbox 切换 + 历史日期固定 + 触发器自动暂停 |
| ↳ | 触发器配置 | `/triggers?tab=biz` | （跳转 TriggerManager） | （同 biz Tab） | 入口跳转 |
| 日志调试 | DevTrace | `/logs/dev-trace` | `DevTrace.tsx` | `GET /admin/dev-trace/(dates\|requests\|coverage\|settings)`、`GET /admin/dev-trace/request/:id`、`POST /admin/dev-trace/cleanup`、`POST /admin/dev-trace/coverage/scan`、`PUT /admin/dev-trace/settings` | 全链路 trace 请求列表 + span 树 + 覆盖率扫描 + 清理 |
| ↳ | AI 调用明细 | `/logs/ai-run-logs` | `AIRunLogs.tsx` | `GET /admin/ai/run-logs`、`GET /admin/ai/run-logs/:id` | AI 单次调用 prompt / response / error 详情 |
| ↳ | 数据库查看器 | `/logs/db-viewer` | `DBViewer.tsx` | `GET /db/schemas`、`GET /db/schemas/:s/tables`、`GET /db/tables/:s/:t/columns`、`POST /db/query` | Schema/Table 树 + 只读 SQL 执行 |

---

## 三、19 页指纹卡

> 实际可路由页面共 19 个：`Login` + 18 个登录后页面（其中 `/triggers?tab=biz`、`/triggers?tab=ai` 是 `/triggers` 的查询参数入口，菜单暴露但共用 1 个 `TriggerManager.tsx`）。

### 3.1 `/login`

- **设计目的**：JWT 用户名+密码登录，仅渐变色卡片。
- **关键操作**：填写用户名 / 密码 → 「登录」按钮。
- **后端 API**：`POST /api/auth/login`（通过 `useAuthStore.login`）；JWT aud=`admin`。
- **数据来源**：`auth.admin_users`（admin/super_admin/site_admin 共表，aud 区分）。
- **必现字段**：渐变色背景、`NeoZQYY` 标题、用户名输入、密码输入、登录按钮。
- **典型用例**：进入后台首屏。
- **测试校核重点**：错误返回应展示 `detail` 文案；成功后 `navigate("/dashboard")`。

---

### 3.2 `/dashboard`（运行状态，首页）

- **设计目的**：登录后默认首页，聚合服务器、服务、Git、DB、AI 状态在一屏。
- **关键操作**：刷新（轮询 15s）、跳转「ETL 状态详情」、「触发器详情」、「AI 调度详情」、启停服务、`git pull`、同步依赖。
- **后端 API**：`GET /api/ops/system`、`/services`、`/git`；`POST /api/ops/services/:env/(start|stop|restart)`、`POST /api/ops/git/:env/(pull|sync-deps)`；`GET /api/admin/db-health`；`GET /api/admin/ai/trigger-jobs`；内嵌 `AIDashboard` 调 `GET /api/admin/ai/dashboard`。
- **数据来源**：服务器实时（`psutil`）+ Git CLI + 业务库 `biz.ai_run_logs` / `biz.trigger_jobs` + 测试库连接探活。
- **必现字段**：CPU/内存/磁盘三组进度条、4 个环境（prod/test/etl/dev）状态、Git branch + last_commit、DB 健康行、AI 调用量/成功率/Token/延迟、AI 调度摘要（今日触发数/成功率/最近错误）。
- **典型用例**：每天进入后台第一眼看的总览；判断「服务是否在线」「ETL 是否卡住」「AI 是否预算耗尽」。
- **最近变更**：CHANGE 2026-07-25（Task 8.1）OpsPanel 拆出 3 个 Section 组件被本页复用；Task 8.x 增加 AI 调度摘要。
- **测试校核重点**：`AIDashboard` 在本页是嵌入子组件，不应有独立顶部 Title；DB 健康超时 10s 回落 timeout 状态；AI 调度摘要的「今日」基于 `created_at.startsWith(YYYY-MM-DD)`，跨时区注意。

---

### 3.3 `/etl-tasks`（ETL 任务管理，5 Tab）

- **设计目的**：把 ETL 全生命周期（发起 → 队列 → 调度 → 历史 → 状态）合并为单页 5 Tab，URL 参数 `?tab=` 同步。
- **关键操作**：切换 Tab、Tab 内复用各原页面操作。
- **后端 API**：见 §二映射表（`/tasks/*`、`/execution/*`、`/schedules*`、`/etl-status/*`，WS `/ws/logs/:id`）。
- **数据来源**：ETL 库（`meta.scheduled_tasks`、`meta.execution_log`）+ 任务调度后端内存队列。
- **必现字段**：5 Tab 标题图标（发起 / 队列 / 调度 / 历史 / 状态），`destroyInactiveTabPane={false}` 切回不刷新。
- **典型用例**：运维新发起一次 ETL（config）→ 看队列 → 历史回看 → 状态确认游标推进。
- **最近变更**：CHANGE 2026-07-14 Task 9.1 合并 4 页为 Tab；CHANGE 2026-03-25 拆出原 TaskManager 内部子 Tab。
- **测试校核重点**：`?tab=xxx` 非法值回落 `config`；切 Tab 不丢失子 Tab 状态。

---

### 3.4 `/task-engine/trigger-jobs`（小程序定时任务）

- **设计目的**：管理 `biz.trigger_jobs` 中所有定时任务（cron / interval / event），支持手动执行。
- **关键操作**：刷新、手动执行（Popconfirm）、清空所有助教任务（高危 danger 按钮）。
- **后端 API**：`GET /api/trigger-jobs`、`POST /api/trigger-jobs/:id/run`、`DELETE /api/admin/task-engine/clear-all-tasks`。
- **数据来源**：`biz.trigger_jobs` + `biz.coach_tasks`（清空目标）。
- **必现字段**：任务名称（描述+job_name）、触发方式 Tag、触发配置 code、状态、上次/下次执行、最近错误、操作列。
- **典型用例**：测试重置任务表 + 强制运行某 cron。
- **测试校核重点**：清空所有任务的 `Popconfirm` 含 description，danger 按钮置 loading；status≠enabled 的执行按钮 disabled。

---

### 3.5 `/task-engine/transfer-log`（客户转移日志）

- **设计目的**：P18 助教任务引擎产生的 `biz.coach_task_transfer_log` 分页只读视图。
- **关键操作**：刷新、按门店/日期范围/助教 ID 筛选、翻页。
- **后端 API**：`GET /api/admin/task-engine/transfer-log`（分页 + 筛选）。
- **数据来源**：`biz.coach_task_transfer_log`（含 `guard_checks` JSON 三项检查）。
- **必现字段**：转移时间、门店、客户、原助教、新助教、转移原因（中文映射）、转移得分、保护检查 Tag（success/error 图标）。
- **典型用例**：审计某客户为何被转走、检查 guard 是否触发。

---

### 3.6 `/task-engine/pending-review`（待审核任务）

- **设计目的**：展示 `status='pending_review'` 的助教任务，超管可重分配 / 关闭。
- **关键操作**：刷新、按门店筛选、重新分配（输入新助教 ID）、关闭（输入原因）、查看转移历史抽屉。
- **后端 API**：`GET /api/admin/task-engine/pending-review`、`POST .../:id/reassign`、`POST .../:id/close`、`GET .../transfer-log/:memberId/history`。
- **数据来源**：`biz.coach_tasks`（status=pending_review） + `coach_task_transfer_log`。
- **必现字段**：任务类型 Tag、转移次数、优先级得分、操作列（仅 super_admin 可见）。
- **测试校核重点**：`super_admin` 角色才显示重新分配/关闭按钮。

---

### 3.7 `/task-engine/config`（任务引擎参数管理）

- **设计目的**：`biz.cfg_task_generator_params` 全局默认 + 门店覆盖参数；权重 `w_rs/w_ms/w_ml` 卡片整体编辑（联合校验）。
- **关键操作**：行内编辑、新增（弹窗）、删除、权重卡片提交。
- **后端 API**：`GET /api/admin/task-engine/config`、`PUT .../:id`、`POST .../`、`DELETE .../:id`。
- **数据来源**：`biz.cfg_task_generator_params`。
- **必现字段**：参数中文标签（13 个映射）、当前值、归属（全局 / 门店#xxx）、更新时间。
- **测试校核重点**：3 个权重必须同步提交；非超管只读。

---

### 3.8 `/triggers`（触发器统一管理，4 Tab）

- **设计目的**：聚合 biz / ai / etl 三类触发器为单页 4 Tab，统一只读视图 + 编辑能力。
- **关键操作**：切 Tab、`all` 只读统一表、`biz` 编辑 cron/interval、`ai` 复用 AITriggers + AIOperations + AITriggerJobs、`etl` 只读 scheduled_tasks。
- **后端 API**：`GET /api/admin/triggers/unified`、`GET /api/trigger-jobs`、`PATCH /api/trigger-jobs/:id/config`、`GET /api/schedules`、（AI Tab 详见 3.12）。
- **数据来源**：`biz.trigger_jobs` + `meta.scheduled_tasks` + `biz.ai_run_logs`（健康）。
- **必现字段**：4 Tab 图标（全部 / 业务 / AI / ETL），「最近错误」单独一列。
- **最近变更**：CHANGE 2026-07-15 Task 10.1 创建。
- **测试校核重点**：`?tab=biz` / `?tab=ai` 直达正确 Tab；biz Tab 编辑校验 `cron_expression` 或 `interval_seconds` 至少一个；ai Tab 内三个组件按 `Space direction="vertical" size="large"` 纵向排列。
- **功能交集**：`AITriggers.tsx`（孤儿）功能已被 `BizTriggersTab` 编辑能力 + `AITriggersTab` 嵌入完整覆盖。

---

### 3.9 `/ai/dashboard`（AI 总览）

- **设计目的**：AI 8 个 App 的整体健康监控。
- **关键操作**：选门店、切日期范围（今日 / 近 3/7/10 天 / 自定义 RangePicker）、刷新。
- **后端 API**：`GET /api/admin/ai/dashboard`（参数 `site_id`、`range_days` 或 `date_from/date_to`）。
- **数据来源**：`biz.ai_run_logs` + `biz.ai_alerts` + `biz.ai_token_budget`。
- **必现字段**：4 统计卡（调用 / 成功率 / Token / 平均延迟）、7 天趋势、App 占比、预算进度（日/月）、App 健康、最近告警表。
- **测试校核重点**：`/dashboard` 嵌入本页时不应渲染重复顶部；range_days=0 时启用 RangePicker。

---

### 3.10 `/ai/operations`（AI 手动操作）

- **设计目的**：5 卡操作面板：重跑 / 缓存失效 / 按需重跑 / 批量执行 / 告警管理 / 越过去重事件。
- **关键操作**：输入 trigger_job_id 重跑；按 app_type+member 失效缓存；按 app+member+site 重跑某 App；批量执行（预估→确认两步）；ack/ignore 告警；触发事件链。
- **后端 API**：`POST /api/admin/ai/trigger-jobs/:id/retry`、`POST .../cache/invalidate`、`POST .../run/:appType`、`POST .../batch-run`、`POST .../batch-run/confirm`、`POST .../trigger-event`、`GET .../alerts`、`POST .../alerts/:id/(ack|ignore)`。
- **数据来源**：`biz.ai_run_logs` + `biz.trigger_jobs` + `biz.ai_chat_cache` + `biz.ai_alerts`。
- **必现字段**：site_id 默认 `2790685415443269`（朗朗台球）、6 个 App 类型选项（不含 app2 系列，预热单独走 `/ai/prewarm`）。
- **测试校核重点**：批量执行需先 estimate 拿 `batch_id` 再 confirm；缓存失效返回 `affected_count`。

---

### 3.11 `/ai/prewarm`（AI 预热进度）

- **设计目的**：监控 app2_finance / app2a_finance_area 的 8 时间 × 9 区域 = 72 组合覆盖率（注意：area=all 走 app2_finance 8 组合，其余 8 区域走 app2a_finance_area 64 组合）。
- **关键操作**：选门店、刷新、一键批量补缺（串行 POST）、触发全量预热（dws_completed 事件）、单组合重跑。
- **后端 API**：`GET /api/admin/ai/prewarm/progress`、`POST /api/admin/ai/run/(app2_finance|app2a_finance_area)`、`POST /api/admin/ai/trigger-event`。
- **数据来源**：`biz.ai_chat_cache`（统计已生成的 target_id × time_dimension × area 组合）。
- **必现字段**：环形进度条、缺失 missing 表（按区域分组）、单组合「重跑」按钮、批量补缺 Modal 进度。
- **最近变更**：CHANGE 2026-04-23 新增 app2a_finance_area 区域版（64 组合）。
- **测试校核重点**：`areaToAppType('all')` → `app2_finance`；其他 → `app2a_finance_area`。

---

### 3.12 `/ai/trigger-jobs`（AI 调度历史）

- **设计目的**：AI 事件链（consumption / dws_completed / note_created / task_assigned）的调度记录。
- **关键操作**：筛选 event_type / status / site_id / 日期范围、查看详情 Modal、Popconfirm 重跑、刷新。
- **后端 API**：`GET /api/admin/ai/trigger-jobs`、`GET .../:id`、`POST .../:id/retry`。
- **数据来源**：`biz.trigger_jobs`（job_type=ai_*）+ 关联 `biz.ai_run_logs`。
- **必现字段**：今日去重跳过数（`today_skipped_duplicates`）顶部统计、状态 Tag、事件类型、执行链 `app_chain`、耗时（finished_at - started_at）。

---

### 3.13 `/tenant-admins`（租户管理员）

- **设计目的**：管理员 CRUD（auth.tenant_admins，aud=tenant-admin），含 2 步创建（基本信息 → 简写 ID）。
- **关键操作**：搜索、切换显示已禁用、新增（2 步骤 Steps）、编辑、重置密码、软删除、简写 ID 管理弹窗。
- **后端 API**：`GET/POST/PATCH/DELETE /api/admin/tenant-admins`、`POST .../:id/reset-password`；`GET /api/admin/registry/tenants`、`GET .../sites`、`PATCH .../sites/:id/code`、`GET .../sites/:id/code-history`、`POST/DELETE .../sites`。
- **数据来源**：`auth.tenant_admins` + `core.tenants` + `core.sites`（FDW）。
- **必现字段**：用户名、显示名、租户名、管理类型 Tag、`managedSiteIds`、状态、最后登录、5 个操作按钮（编辑/重置密码/简写ID/启停/删除）。
- **后端响应**：CamelModel 已序列化为 camelCase（`displayName`、`managedSiteIds` 等）。
- **测试校核重点**：Step1 基本信息提交后才能进入 Step2；删除走软删除（`isActive=false`）；简写 ID 编辑同步写入 `core.site_codes_history`。

---

### 3.14 `/settings/env-config`（环境配置）

- **设计目的**：编辑根 `.env`（敏感值 `****` 脱敏，导出去敏感）。
- **关键操作**：行内编辑、批量保存（dirtyMap 暂存）、刷新、导出 `env-config.txt`。
- **后端 API**：`GET /api/env-config`、`PUT /api/env-config`、`GET /api/env-config/export`（blob 下载）。
- **数据来源**：根 `.env` 文件。
- **必现字段**：键 / 值（敏感为 ****）/ 是否敏感 Tag / 编辑按钮、顶部 dirty Badge 计数。
- **测试校核重点**：敏感值留空提交不修改；导出文件名从 `Content-Disposition` 提取，回退 `env-config.txt`。

---

### 3.15 `/settings/runtime-context`（业务运行上下文 / 沙箱）

- **设计目的**：超管按门店切换 live ↔ sandbox（指定历史日期），切换会按 site_id 暂停/恢复 `biz.trigger_jobs`。
- **关键操作**：刷新列表、切到 sandbox（选历史日期 + reset_sandbox 开关 + 备注原因）、切回 live、查看切换步骤 Modal。
- **后端 API**：`GET /api/admin/runtime-context/sites`、`PATCH /api/admin/runtime-context`。
- **数据来源**：`meta.runtime_context` + `biz.trigger_jobs`（暂停/恢复影响）。
- **必现字段**：门店列表（site_id / site_code / mode Tag / sandbox_date / ai_mode）、切换 Drawer/Modal、步骤展示（success/skipped/warning/failed 颜色）。
- **测试校核重点**：仅 `super_admin` 可加载列表；sandbox_date 必填且 ≤ 今日；切换返回的 steps 全部展示。

---

### 3.16 `/logs/dev-trace`（DevTrace 全链路日志）

- **设计目的**：HTTP / SSE / WS / Job 全链路 span 树查看 + 覆盖率扫描 + 设置管理 + 手动清理。
- **关键操作**：选日期、按 trace_type / method / status_code / 关键字筛选、点行看 span 树、覆盖率扫描、设置 Drawer（开关 + 保留天数 + 清理）。
- **后端 API**：`GET /api/admin/dev-trace/(dates|requests|coverage|settings)`、`GET .../request/:id`、`PUT .../settings`、`POST .../cleanup`、`POST .../coverage/scan`。
- **数据来源**：本地 trace 日志文件（按日期分文件）。
- **必现字段**：覆盖率状态栏、25 种 span_type 颜色映射、左侧请求列表 + 右侧 span 树。
- **测试校核重点**：覆盖率 scan 是 POST，结果异步刷新；`cleanupLogs` 返回 `deleted_dates` + `deleted_files`。

---

### 3.17 `/logs/ai-run-logs`（AI 调用明细）

- **设计目的**：AI 单次调用的 prompt / response / error 详情查看。
- **关键操作**：筛选 app_type / status / trigger_type / site_id / 日期范围、点行打开 Drawer。
- **后端 API**：`GET /api/admin/ai/run-logs`、`GET .../:id`。
- **数据来源**：`biz.ai_run_logs`。
- **必现字段**：app_type、trigger_type、member_id、tokens_used、latency_ms、状态 Tag、Drawer 内 prompt/response/error 全文。

---

### 3.18 `/logs/db-viewer`（数据库查看器）

- **设计目的**：业务库只读 SQL 查询界面。
- **关键操作**：左侧 Tree 异步加载 schema → table、点表加载列定义、写 SQL → 执行（仅 SELECT）。
- **后端 API**：`GET /api/db/schemas`、`GET /api/db/schemas/:s/tables`、`GET /api/db/tables/:s/:t/columns`、`POST /api/db/query`。
- **数据来源**：业务库 `zqyy_app`（含 FDW 映射的 ETL `app.v_*`）。
- **必现字段**：左 Tree（schema 图标 + table 行数）、右上 SQL 编辑器、右下 列定义 / 查询结果切换。
- **测试校核重点**：后端只允许 `SELECT`；`encodeURIComponent` 处理 schema/table 名。

---

## 四、跨页共性约定

1. **认证守卫**：`PrivateRoute` 检查 `useAuthStore.isAuthenticated`，未登录跳 `/login`。Login 之外所有路由都包在 `AppLayout` 下。
2. **响应包装**：后端 `ResponseWrapperMiddleware` 把 2xx 响应包为 `{code:0, data:...}`，`apiClient` 拦截器统一解包，使页面代码直接拿 `data`。
3. **JWT 双认证**：admin-web 用 aud=`admin` token；本后台不应出现 miniapp / tenant-admin token（其它两个前端项目独立）。
4. **401 自动刷新**：`apiClient` 拦截器单飞刷新 + 队列重放，刷新失败清 token 跳 `/login`。
5. **重定向**：`/` → `/dashboard`；`/log-viewer`（已废弃）→ `/etl-tasks?tab=queue`。
6. **业务日**：`useBusinessDayStore.init()` 启动时拉营业日配置（用于 ETL 时间窗口）。
7. **底部状态栏**：每 5s 轮询 `/api/execution/queue`，展示 running 任务（flow + 前 3 个 task）。
8. **侧边栏**：`/triggers?tab=biz` 与 `/triggers?tab=ai` 是带 search 的特殊菜单 key，`getSelectedKeys` 根据 `pathname + search` 精确匹配。
9. **WebSocket**：仅 `TaskManager.QueueTab` 使用 `/ws/logs/:id` 实时日志（无独立 store）；后台 AI WS 由 `ai_ws_router` 提供，但 admin-web 暂未消费。
10. **响应格式**：多数 API 返回原始数组或对象；分页接口统一返回 `{ items, total, page, page_size }`（AI 系列再附加业务字段如 `today_skipped_duplicates`）。
11. **角色控制**：`super_admin` 才看到「业务运行上下文」「待审核任务的重分配/关闭」「参数管理的写入」按钮，前端通过 `useAuthStore.user.roles` 判断。

---

## 五、文档冲突待确认清单

> 以下与 NS1 / NS4 PRD、API-REFERENCE 或代码现状发现不一致或需澄清的点，待 Neo 确认。

1. **NS1 vs 代码**：NS1 主要描述 `/api/xcx/*` 小程序接口，未覆盖 `/api/admin/*`；admin-web 的全部 API 当前以 `apps/backend/app/routers/admin_*.py` 与 `app/routers/*.py` 实际实现为准，缺少独立 PRD。`待 Neo 确认`：是否需要补一份 `NS-admin-web-backend-api.md`？
2. **NS4 / NS4.1 vs admin-web**：NS4 / NS4.1 是 tenant-admin 重设计，与 admin-web 视角无直接冲突。但 `auth.tenant_admins` 表与 `/admin/tenant-admins` 路由都在 admin-web 出现（管理租户管理员），两者职责边界文档化建议明确：admin-web 操作租户管理员账号本身，tenant-admin 管理「门店运营」。`待 Neo 确认`。
3. **AI 触发器双 API**：`/api/admin/ai/triggers`（adminAI.ts）与 `/api/trigger-jobs`（triggerJobs.ts）操作的是同一张 `biz.trigger_jobs` 表，前者带 job_type 过滤、后者全量。`AITriggers.tsx` 用前者编辑 cron/desc，`BizTriggersTab` 用后者编辑 cron_expression/interval_seconds。`待 Neo 确认`：两套 API 是否合并？或明文区分使用边界。
4. **预热进度 vs API 文档**：`AIPrewarm` 注释写「app2_finance 72 组合」，实际是 `area=all` 走 8 组合 + 8 区域走 64 组合 = 72；NS3 / API-REFERENCE 是否同步说明这个二分？`待 Neo 确认`。
5. **事件类型枚举**：`AIOperations.EVENT_TYPE_OPTIONS`（4 项）、`AIPrewarm` triggerEvent (`dws_completed`)、`AITriggerJobs` 不限制；NS3 是否有完整 event_type 枚举表？`待 Neo 确认`。
6. **DBViewer 的安全边界**：`POST /db/query` 后端是否仅允许 SELECT？前端无校验，依赖后端 sqlparse 或类似拦截。`待 Neo 确认`。
7. **`clearAllTasks`（清空 coach_tasks）危险操作**：`TriggerJobs` 顶部的 danger 按钮调 `DELETE /api/admin/task-engine/clear-all-tasks`，注释写「测试用」。`待 Neo 确认`：是否仅在 `mode=sandbox` 才允许？现状无运行模式守卫。
8. **侧边栏 `?tab=` 入口**：「AI 管理 → 触发器设置」与「系统设置 → 触发器配置」都跳到 `/triggers?tab=ai|biz`，菜单上是两个 entry 但页面只有一个 TriggerManager；UX 是否符合预期？`待 Neo 确认`。
9. **Login 接口路径**：前端 `useAuthStore.login` 调 `/api/auth/login`（main.py 通过 `auth.router` 注册），未在本调研中读取 `auth.py` 路径常量，但 401 刷新拦截器引用了 `/auth/refresh`。`待 Neo 确认`：路径前缀是否含 `/admin`？
10. **`ai-group` 「触发器设置」展开问题**：`getDefaultOpenKeys` 注释里写 「无法判断 tab，交由路由侧 searchParams 处理默认展开」，当前从 ai 子菜单跳到 `/triggers?tab=ai` 时不会自动展开 ai-group。`待 Neo 确认`：是否需要修正 selectedKeys 逻辑使两个 group 都高亮？

---

> 文档篇幅控制：约 280 行（不含本提示）。本文为快速核对参考，详细业务规则以各页面 `.tsx` 顶部注释 + 后端 router 实现为准。