# SentAI 后台交互审计与重构规范

## 1. 当前接口梳理

### 通用
- `GET /health`

### 认证
- `POST /api/auth/login`

### 巡检平台
- `GET /api/dashboard/summary`
- `GET /api/tasks`
- `POST /api/tasks`
- `PUT /api/tasks/:id`
- `PATCH /api/tasks/:id/status`
- `GET /api/runs/report`
- `GET /api/runs`
- `GET /api/runs/:runId`
- `POST /api/runs/execute/:taskId`

### Agent-S
- `GET /api/agent/health`
- `POST /api/agent/run`

### 环境监测
- `GET /api/monitoring/summary`
- `GET /api/monitoring/agents`
- `POST /api/monitoring/agents`
- `PUT /api/monitoring/agents/:id`
- `PATCH /api/monitoring/agents/:id/status`
- `PATCH /api/monitoring/agents/:id/features`
- `POST /api/monitoring/agents/:id/verify`
- `POST /api/monitoring/agents/:id/package`
- `GET /api/monitoring/targets`
- `POST /api/monitoring/targets`
- `PUT /api/monitoring/targets/:id`
- `PATCH /api/monitoring/targets/:id/status`
- `DELETE /api/monitoring/targets/:id`
- `GET /api/monitoring/runs`
- `GET /api/monitoring/runs/:runId`
- `DELETE /api/monitoring/runs/:runId`
- `POST /api/monitoring/runs/actions/delete`
- `POST /api/monitoring/runs/:runId/requeue`
- `POST /api/monitoring/runs/actions/clear-queued`
- `POST /api/monitoring/runs/actions/requeue-stale`
- `POST /api/monitoring/runs/execute/:targetId`
- `GET /api/monitoring/logs/recent`
- `POST /api/monitoring/agent/heartbeat`
- `POST /api/monitoring/agent/jobs/claim`
- `POST /api/monitoring/agent/jobs/:runId/result`
- `POST /api/monitoring/logs/ingest`

## 2. 当前页面问题清单

### 导航与页面结构
- 多个页面各自维护导航文案和页面头，结构重复，状态不一致。
- 首页、环境监测、Agent 节点存在多套“工作区导航”实现，用户切换成本高。
- 列表页、详情页、表单页没有稳定的信息层级，容易在同一页堆叠过多内容。

### 列表页
- 列表工具栏不统一：有的页面只有搜索，有的页面有筛选但没有排序/批量操作。
- 执行记录与监测记录早期偏“卡片流”，长周期使用时不利于检索、对比、批量处理。
- 目标列表、记录列表、Agent 列表都缺少统一的“主操作区 + 批量操作区 + 视图控制”节奏。

### 详情页
- 详情区域字段排列依赖当前页面作者习惯，没有统一的“摘要 / 核心信息 / 附属信息 / 历史”结构。
- 执行结果与证据入口分散，用户不容易快速判断“先看哪里”。

### 表单页
- 相同概念在不同页面命名不一致，例如“接入地址”在不同模式下含义完全不同。
- 高级 JSON 仍承担了部分主流程字段，降低可配置性和可维护性。
- 表单缺少“推荐填写顺序”和“默认执行路径”的稳定提示。

### 全局反馈
- loading / empty / error / success / confirm 的样式和触发方式不统一。
- 批量删除、执行、重新入队等危险操作仍然缺少标准化二次确认摘要。

## 3. 新的后台交互规范

### 3.1 顶层信息架构
- 一级导航固定为：`概览`、`巡检任务`、`巡检报告`、`执行记录`、`环境监测`、`Agent 节点`
- 每个一级资源只保留一个主目标：
  - 列表页：筛选、浏览、批量操作
  - 详情页：判断状态、查看证据、执行操作
  - 表单页：新增或编辑，不与大列表强耦合

### 3.2 列表页规范
- 统一工具栏顺序：
  - 搜索
  - 筛选
  - 排序
  - 批量操作
  - 导出
  - 新建
- 列表行以“低噪音高密度”为主，状态用小标签，不用整块背景色表达。
- 列表默认支持：
  - 多选
  - 批量删除/批量重试/批量启停
  - 分页
  - 分组或折叠

### 3.3 详情页规范
- 统一为 5 个区块：
  - 摘要区
  - 核心信息区
  - 附属信息区
  - 操作区
  - 历史区
- 危险操作集中放在操作区，不散落在多个卡片内部。

### 3.4 表单页规范
- 表单按“基础信息 > 执行/接入方式 > 认证信息 > 证据采集 > 高级配置”分组。
- 可视化字段优先，高级 JSON 仅作为扩展入口。
- 同一个字段名在不同资源中尽量保持语义一致。

### 3.5 全局反馈规范
- loading：顶部状态条 + 局部按钮忙碌态
- empty：资源型空状态，不显示“孤零零一句话”
- error：显示人类可理解错误，不直接暴露底层异常
- success：顶部通知，带影响条数
- danger confirm：明确展示影响范围、资源名称和数量

## 4. 重构优先级

### P1 导航框架
- 抽离共享导航配置
- 抽离共享后台框架组件
- 页面头和主操作区统一

### P2 列表页
- 统一工具栏
- 统一多选/批量操作
- 统一分页和分组

### P3 详情页
- 统一摘要结构
- 统一证据入口
- 统一历史区

### P4 表单页
- 统一分段结构
- 把主流程字段从 JSON 中提取出来

### P5 全局反馈
- 统一反馈组件
- 统一确认弹窗策略

## 5. 第一轮实施范围
- 抽离共享导航配置和后台框架
- 先重构 `环境监测` 与 `Agent 节点`
- 后续将 `巡检任务 / 报告 / 执行记录` 接入同一框架