Merge pull request #83 from qinshihu/refactor/module-architecture

Refactor/module architecture

Author: qinshihu

.trae/documents/NAVIGATION_AUDIT.md

@@ -0,0 +1,74 @@
+# 导航菜单体检记录（NAV-AUDIT）
+
+> 按 `frontend/src/config/navigation.ts` 顺序**逐组、逐页、逐功能**深体检。
+> 每组体检完毕即修复问题 → tsc/test → commit → push → 等用户确认 → 下一组。
+> 实时状态写在本总账；过程性记录写在「过程记录」段。
+>
+> 最后更新：2026-07-23（v6 — 逐页逐功能重检开始）
+
+## 总账
+
+| # | 分组 | 菜单项 | 状态 | 备注 |
+|---|------|--------|------|------|
+| 1 | nav.home | dashboard, bigScreen | ✅ | v6 体检+修复：useBigScreenData setTimeout cleanup + 2 空 catch → logger.warn + Dashboard 6 useQuery queryFn 内 try/catch logger.error + dashboardRoutes parseInt NaN 防 + dashboardStats/operationalAnalytics 8 处 parseFloat Number.isFinite + useBigScreenData 6 处 data as Array.isArray 兜底 + callZabbix typeof === 'object' 校验 + BigScreenRecentTasksList/RightColumn Invalid Date → '--' |
+| 2 | nav.serverMgmt | servers, networkDevices, networks, snmp, networkDiscovery, dbConnections, sshKeys, terminal, remoteDesktop | ⏳ | 待重检 |
+| 3 | nav.containersVirtualization | containers, containerMonitor, containerLogs, images, volumes, virtualMachines, compose, snapshotPolicies, vmMigrations, imageRegistry, kubernetes, costAnalysis, autoScale | ⏳ | 待重检 |
+| 4 | nav.dataCenter | dcManage, dataRoom | ⏳ | 待重检 |
+| 5 | nav.autoExecution | agents, agents/tools, workflows, workflows/providers, tasks, approvals, scripts, scheduledTasks, configTemplates | ⏳ | 待重检 |
+| 6 | nav.alertsAI | alerts, alertMappings, alertNoise, alertCorrelation, rootCauseAnalysis, aiRootCause, topology, aiInsights, alertAutoAnalysis, inspectionCenter, alerts/providers, zabbix, prometheus | ⏳ | 待重检 |
+| 7 | nav.mcp | mcpOverview, mcpTools, mcpExternalServers, mcpTester | ⏳ | 待重检 |
+| 8 | nav.autoRemediation | remediationPolicies, remediationDashboard, remediationExecutions, remediationWorkbench, aiRemediations | ⏳ | 待重检 |
+| 9 | nav.knowledgeReports | knowledge, audit, notifications, reports | ⏳ | 待重检 |
+| 10 | nav.systemUsers | users, frontendTests, toolLinks, settings | ⏳ | 待重检 |
+
+> 图例：⏳ 待体检 / 🔄 体检中 / ✅ 体检+修复完成
+
+## 已修复 bug 总账（c01c217 commit 范围）
+
+### P0 后端缺失端点（5 处）
+- `tool-links`: GET /categories + DELETE /:id/icon
+- `alert-provider-configs`: 完整 CRUD（JSON 持久化）
+- `notifications`: POST /:id/retry
+- `tasks`: POST /:id/retry（创建新 task 并异步执行）
+- `ai-remediations`: POST /:id/approve + /reject
+
+### P0 后端结构（3 处）
+- `audit JOIN users`: list 改 LEFT JOIN 取 username
+- `configTemplates total`: 嵌入 data.items
+- `dc slots/batch`: 新增聚合端点（顺序：/batch 必须在 /:rackId 之前）
+
+### P1 前端 axios 解包统一修复（10+ 处）
+批量改 `const { data } = await api.get(...)` 模式，涉及 servers/queries.ts(4)+handlers(2)、alerts/*(7)、monitor/TrendCharts/ZabbixQuery/api.ts/cost-analysis、network/*(8)、notification/api.ts(3)、settings/SecuritySettings
+
+### P1 前端硬编码 fetch 漏 /v1（3 处）
+- RemoteDesktop.tsx
+- BackupSettings.tsx
+
+### P1 kubernetes 双重 /api 前缀
+- useKubernetes.ts scale/restart 4 处
+
+### P1 业务修复
+- scripts runScript: 前端 setTimeout mock → 真实 POST /scripts/:id/execute
+- Topology handleDiscoverDependencies: catch 吞错 → logger.warn + 失败计数
+
+## 待修复（非阻塞 / 体验问题）
+
+| 优先级 | 项 | 位置 | 描述 |
+|--------|----|------|------|
+| P2 | RemediationExecutions 分页无封顶 | `frontend/src/modules/auto/pages/RemediationExecutions.tsx:309-321` | 下一页按钮无 disabled + 限上界 |
+| P2 | Reports type 写死 'inspection' | `backend/src/modules/monitor/services/reportService.ts:227,243` | getTemplates/getTemplate 丢失真实 type |
+| P3 | lint-staged Windows 路径 bug | `scripts/lint-staged.cjs:31-39` | Windows 上 path.join 把绝对路径当相对路径处理 → ENOENT |
+| P3 | ComposeEditor 归属错配 | `frontend/src/modules/containers/...` | compose 实际属 config-management，不影响功能 |
+
+### 2026-07-23 v5+ 完结：遗留 P2/P3 全部解决
+- ✅ ssh-keys consumer 5 处 `?? 0/?? ''` fallback
+- ✅ useNetworkDevices `_deviceName` 改用 `SnmpInspectionData` 显式断言（消除污染）
+- ✅ ComposeEditor PaginatedResult 类型统一为 `{items, total}`（5 个 list 方法对齐）
+- ✅ containerRoutes `/containers` / volumeRoutes `/volvolumes` 改为 `{items, total}` 嵌套格式
+- ✅ Approvals 评论 modal（已在 v5 完成）
+- ✅ 3 个真死路由删除：agents/:id/test-input、agents/:id/executions、scheduled-tasks/:id/run
+- ✅ presetTestInputs.ts 删除（只被 test-input 引用）
+
+## 体检方法
+
+每组并行启动 1 个 `general-purpose-task` 子代理，做"路由可达 → 后端模块健康 → 已知 bug 信号"快速体检。子代理只回报高置信度问题。问题修复后 commit + push，再进入下一组。

backend/src/modules/ai/README.md

@@ -2,12 +2,14 @@
 
 > **DDD 限界上下文**：AI 能力编排（LLM、Agent、RCA、知识库、自动修复）
 > **聚合根**：`Agent`、`LLM Provider`、`Knowledge`
-> **最后刷新**：2026-07-22（基于 12,943 行实测）
+> **最后刷新**：2026-07-23（nav.autoExecution 第 5 轮 RBAC + logger 补全）
 
 ## 职责
+
 AI 能力编排：大语言模型调用、Agent 管理、根因分析、知识库、自动修复建议。
 
 ## 内部结构（2026-07-22 核对代码现状）
+
 ```
 ai/
 ├── routes.ts               # 模块路由聚合入口（挂 9 个 mount，含 /mcp 代理）
@@ -44,25 +46,27 @@ ai/
 
 ## 路由端点（受保护，路径前缀 `/api/v1/*`）
 
-| 前缀 | 来源 routes 文件 | 说明 |
-|------|------------------|------|
-| `/agents/*` | `agentRoutes.ts` → `agent/` 子目录 | Agent CRUD + 执行 + 工具 + 导入导出（详见子目录 README） |
-| `/knowledge/*` | `knowledgeRoutes.ts` | 知识库 CRUD |
-| `/knowledge/qanything/*` | `knowledgeQAnythingRoutes.ts` | QAnything 知识库集成 |
-| `/copilot/*` | `copilotRoutes.ts` | AI Copilot 对话 |
-| `/root-cause-analysis/*` | `rootCauseAnalysisRoutes.ts` | 根因分析 |
-| `/multi-agent/*` | `multiAgentRoutes.ts` | 多 Agent 协作 |
-| `/ai-models/*` | `aiModelRoutes.ts` | AI 模型 CRUD |
-| `/ai-remediations/*` | `aiRemediationRoutes.ts` | AI 修复建议 |
-| `/mcp/*` | `routes.ts` 第 22 行 `router.use('/mcp', mcpGateway)` | **AI 内部使用的 MCP 网关代理**（与 `mcp/` 模块的 `/api/v1/mcp/*` 是不同路径） |
+| 前缀                     | 来源 routes 文件                                      | 说明                                                                          |
+| ------------------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `/agents/*`              | `agentRoutes.ts` → `agent/` 子目录                    | Agent CRUD + 执行 + 工具 + 导入导出（详见子目录 README）                      |
+| `/knowledge/*`           | `knowledgeRoutes.ts`                                  | 知识库 CRUD                                                                   |
+| `/knowledge/qanything/*` | `knowledgeQAnythingRoutes.ts`                         | QAnything 知识库集成                                                          |
+| `/copilot/*`             | `copilotRoutes.ts`                                    | AI Copilot 对话                                                               |
+| `/root-cause-analysis/*` | `rootCauseAnalysisRoutes.ts`                          | 根因分析                                                                      |
+| `/multi-agent/*`         | `multiAgentRoutes.ts`                                 | 多 Agent 协作                                                                 |
+| `/ai-models/*`           | `aiModelRoutes.ts`                                    | AI 模型 CRUD                                                                  |
+| `/ai-remediations/*`     | `aiRemediationRoutes.ts`                              | AI 修复建议                                                                   |
+| `/mcp/*`                 | `routes.ts` 第 22 行 `router.use('/mcp', mcpGateway)` | **AI 内部使用的 MCP 网关代理**（与 `mcp/` 模块的 `/api/v1/mcp/*` 是不同路径） |
 
 > **路径前缀说明**：`ai/routes.ts` 第 22 行的 `router.use('/mcp', mcpGateway)` 与 `_registry.ts` 的 `/api/v1` 组合后实际是 `/api/v1/mcp/*`，**与 `mcp/` 模块独立路由 `/api/v1/mcp/*` 形成两条等价路径**（均指向同一 `services/mcp/gateway.ts`）。前端 mcp 模块通过 `/api/v1/mcp/*` 调用，AI 模块内部 agent 通过 `agentMcpAdapter` 调用相同服务。
 
 ## 依赖关系
+
 - 依赖 `auth/`（鉴权）、`alerts/`（告警数据源）、`mcp/`（AI 内部 tool 调用）
 - 被 `workflow/`、`auto/` 调用
 
 ## 关键说明
+
 - `ai/` 是 **全项目最大模块**（12,943 行 / 83 个 .ts，其中非测试 66 个 .ts / 11,220 行），是所有 AI 能力的聚合点
 - `llm/llmService/` 集成了多模型（Doubao/OpenAI/LocalAI 三个内置 providerAdapters）、熔断器、重试逻辑
 - 单一入口：`llm/llmService/index.ts` 是 barrel，统一导出 `generateCompletion` / `executeAgentWithLLM` 等

backend/src/modules/ai/routes/agent/crudRoutes.ts

@@ -64,48 +64,7 @@ router.get('/:id', validateParams(agentSchemas.agentId), (req: Request, res: Res
   }
 });
 
-// GET /:id/executions - 执行历史列表
-router.get(
-  '/:id/executions',
-  validateParams(agentSchemas.agentId),
-  validateQuery(agentSchemas.listExecutions),
-  (req: Request, res: Response) => {
-    try {
-      const { limit = 20, offset = 0, status } = req.query;
-      const limitNum = parseInt(limit as string);
-      const offsetNum = parseInt(offset as string);
-
-      const executions = agentCrudService.listExecutionsByAgent(req.params.id, {
-        status: status as string | undefined,
-        limit: limitNum,
-        offset: offsetNum,
-      });
-
-      const totalCount = agentCrudService.countExecutionsByAgent(
-        req.params.id,
-        status as string | undefined,
-      );
-
-      res.json({
-        success: true,
-        data: {
-          executions,
-          pagination: {
-            total: totalCount,
-            limit: limitNum,
-            offset: offsetNum,
-          },
-        },
-      });
-    } catch (error) {
-      logger.error('Failed to fetch agent executions:', error);
-      res.status(500).json({
-        success: false,
-        error: (error as Error).message || 'Failed to fetch agent executions',
-      });
-    }
-  },
-);
+// 注：2026-07-23 删除 GET /:id/executions（前端无消费者）
 
 // POST / - 创建
 router.post(

backend/src/modules/ai/routes/agent/executionRoutes.ts

@@ -12,6 +12,7 @@ import type { Request, Response } from 'express';
 import { Router } from 'express';
 import { randomUUID } from 'crypto';
 import { logger } from '../../../../utils/logger';
+import { requireRole } from '../../../../middleware/auth';
 import { validateBody, validateParams } from '../../../../middleware/validation';
 import { agentSchemas } from '../../../../shared/schemas/apiValidation';
 import { agentCrudService } from '../../services/agentCrudService';
@@ -20,9 +21,10 @@ import { executeAgentNode } from '../../services/agents/agentExecutor';
 
 const router = Router();
 
-// POST /:id/test - 测试 Agent 执行
+// POST /:id/test - 测试 Agent 执行（高风险：实际执行 LLM/工具链）
 router.post(
   '/:id/test',
+  requireRole('admin', 'operator'),
   validateParams(agentSchemas.agentId),
   validateBody(agentSchemas.testAgent),
   async (req: Request, res: Response) => {
@@ -62,10 +64,11 @@ router.post(
           // 其他Agent用LLM执行
           output = await executeAgentWithLLM(agent.id, input);
         }
-      } catch (error) {
+      } catch (error: unknown) {
         status = 'error';
-        errorMessage = (error as Error).message;
+        errorMessage = error instanceof Error ? error.message : String(error);
         output = `Agent "${agentName}" 执行失败: ${errorMessage}`;
+        logger.error(`Agent execution failed for ${agentName}:`, error);
       }
 
       const executionTime = Date.now() - startTime;

backend/src/modules/ai/routes/agent/importExportRoutes.ts

@@ -10,13 +10,14 @@ import type { Request, Response } from 'express';
 import { Router } from 'express';
 import { randomUUID } from 'crypto';
 import { logger } from '../../../../utils/logger';
+import { requireRole } from '../../../../middleware/auth';
 import { validateBody, validateParams } from '../../../../middleware/validation';
 import { agentSchemas } from '../../../../shared/schemas/apiValidation';
 import { agentCrudService } from '../../services/agentCrudService';
 
 const router = Router();
 
-router.post('/import', validateBody(agentSchemas.importAgents), (req: Request, res: Response) => {
+router.post('/import', requireRole('admin'), validateBody(agentSchemas.importAgents), (req: Request, res: Response) => {
   try {
     const agents = req.body.agents;
     if (!Array.isArray(agents)) {

backend/src/modules/ai/routes/agent/index.ts

@@ -1,15 +1,16 @@
 /**
  * =============================================================================
- * Agent 路由聚合入口（2026-07-21 拆分）
+ * Agent 路由聚合入口（2026-07-21 拆分，2026-07-23 清理死路由）
  * =============================================================================
  *
- * 从原 agentRoutes.ts 单文件拆分为 6 个子路由文件：
+ * 从原 agentRoutes.ts 单文件拆分为 5 个子路由文件：
  * - crudRoutes          (list / get / create / update / delete + executions list)
- * - statsRoutes         (stats summary + test-input)
+ *   注：2026-07-23 删除 GET /:id/executions（前端无消费者），executions list 路径已废
+ * - statsRoutes         (stats summary)
+ *   注：2026-07-23 删除 GET /:id/test-input（前端无消费者）+ 删除 presetTestInputs.ts
  * - executionRoutes     (POST /:id/test - 测试执行)
  * - importExportRoutes  (import + export)
  * - toolRoutes          (tools/list + tools/test + tools/descriptions)
- * - presetTestInputs    (共享常量)
  *
  * 全部通过 router.use() 聚合到主 router：
  * - routes.ts 调用方：import agentRoutes from './agent' 仍兼容（agentRoutes.ts 是 re-export）

backend/src/modules/ai/routes/agent/presetTestInputs.ts

@@ -1,18 +1,14 @@
 /**
- * Agent 统计 / 测试输入 routes（2026-07-21 拆分）
+ * Agent 统计 routes（2026-07-21 拆分，2026-07-23 清理死路由）
  *
- * 从原 agentRoutes.ts L40-65 + L279-312 抽出：
- * - GET /stats/summary        (汇总统计)
- * - GET /:id/test-input       (推荐测试输入)
+ * 仅保留 GET /stats/summary（前端 Agents.tsx 调用）；
+ * GET /:id/test-input 已删除（前端无消费者）。
  */
 
 import type { Request, Response } from 'express';
 import { Router } from 'express';
 import { logger } from '../../../../utils/logger';
-import { validateParams } from '../../../../middleware/validation';
-import { agentSchemas } from '../../../../shared/schemas/apiValidation';
 import { agentCrudService } from '../../services/agentCrudService';
-import { PRESET_TEST_INPUTS } from './presetTestInputs';
 
 const router = Router();
 
@@ -43,39 +39,4 @@ router.get('/stats/summary', (_req: Request, res: Response) => {
   }
 });
 
-router.get(
-  '/:id/test-input',
-  validateParams(agentSchemas.agentId),
-  (req: Request, res: Response) => {
-    try {
-      const agent = agentCrudService.getAgentNameRoleCategory(req.params.id);
-      if (!agent) {
-        return res.status(404).json({ success: false, error: 'Agent not found' });
-      }
-
-      const agentName = agent.name;
-      let testInput = PRESET_TEST_INPUTS[agentName];
-
-      // 如果没有预设的测试输入，生成一个通用的
-      if (!testInput) {
-        const role = agent.role || '运维助手';
-        testInput = `你好，我是${role}，请帮我处理一个运维相关的问题`;
-      }
-
-      res.json({
-        success: true,
-        data: {
-          testInput,
-          agentName,
-        },
-      });
-    } catch (error) {
-      logger.error('Failed to get test input:', error);
-      res
-        .status(500)
-        .json({ success: false, error: (error as Error).message || 'Failed to get test input' });
-    }
-  },
-);
-
 export default router;