Startseite Erkunden Hilfe
Anmelden
TRS
/
wenlanai
7
0
Fork 0
Dateien Issues 0 Pull-Requests 0 Wiki
Struktur: d82ac17cb4
Branches Tags
wenlanai
/
docs
/
admin-interaction-audit-phase1.md

admin-interaction-audit-phase1.md 5.0 KB
Verlauf Originalformat

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 节点
  • 后续将 巡检任务 / 报告 / 执行记录 接入同一框架