ErrorDetecting/BACKEND_INTEGRATION.md

后端联调指南

环境与代理

• 前端目录：frontend-vue
• 开发代理：frontend-vue/vite.config.ts:25-30 将前端的 /api 代理到后端 VITE_API_TARGET
• 环境变量：
  • frontend-vue/.env.development 示例：VITE_API_TARGET=https://your-backend.example.com
  • 可选：VITE_DEV_HOST、VITE_ALLOWED_HOSTS 控制本地开发主机与允许的外网访问
• 启动与构建：
  • 开发：cd frontend-vue && npm i && npm run dev
  • 预览：npm run preview

鉴权与凭证

• 认证头：Authorization: Bearer <token>
• 前端存储：
  • localStorage 键名：cm_user、cm_token
  • 应用启动恢复：frontend-vue/src/app/main.ts:10-12
• 路由守卫：frontend-vue/src/app/router/index.ts:23-30 未登录重定向到登录页；基于 meta.roles 进行角色校验

关键接口规范

• 健康检查：GET /v1/health
• 登录：POST /v1/user/login
  • 请求体：{ username, password }
  • 响应体：{ token, user: { username, role, email? } }
• 注册：POST /v1/user/register
  • 请求体：{ username, email, password, fullName }
  • 响应体：{ token?, user: { username, role, email? } }
• 用户列表：GET /api/v1/users
  • 响应体：{ users: Array<{ username, role, email }> } 或 Array<{ username, role, email }>
  • 前端选择逻辑：仅匹配当前登录用户名；未匹配则显示错误提示
  • 权限不足（例如操作员 403）：页面显示权限提示
  • 角色值规范化：后端返回的 role 会统一转为小写并支持常见别名（如 administrator→admin、ops→operator）
• 集群与节点：
  • GET /v1/clusters → [{ uuid, host, ip, count, health }]
  • POST /v1/clusters、DELETE /v1/clusters/:id、POST /v1/clusters/:id/start|stop
  • GET /v1/nodes?cluster=<uuid> → [{ name, ip, status, cpu, mem, updated }]
  • POST /v1/nodes/:name/start|stop、DELETE /v1/nodes/:name
• 指标：
  • CPU 趋势：GET /v1/metrics/cpu_trend?cluster=<uuid> → { times: string[], values: number[] }
  • 内存使用：GET /v1/metrics/memory_usage?cluster=<uuid> → { used: number, free: number }
• 诊断：
  • 故障摘要：GET /v1/faults/summary?node=<name>|cluster=<host> → { code, time, scope }
  • AI 对话历史：GET /v1/ai/history?sessionId=<id> → { messages: Array<{ role, content, reasoning? }> }
  • AI 对话：POST /v1/ai/chat → { reply, reasoning? }

前端数据绑定要点

• 个人主页：frontend-vue/src/app/views/Profile.vue
  • 仅使用后端数据；加载中与错误态可视化
  • 角色标签映射：frontend-vue/src/app/constants/roles.ts
• 角色来源：
  • 登录/注册优先采用后端返回的 user.role 或 role（frontend-vue/src/app/stores/auth.ts:55-72,74-91）
• 诊断页与导航：
  • 路由授权：diagnosis 允许 admin/operator（frontend-vue/src/app/router/index.ts:12）
  • 侧边栏入口基于角色显示（frontend-vue/src/app/components/Sidebar.vue:7）

联调步骤

• 设置 VITE_API_TARGET 指向后端地址，确保后端允许来自前端的 CORS 与 Host
• 启动前端后检查 GET /v1/health 返回正常
• 使用真实账号登录，确认：
  • GET /v1/user/me 返回用户信息，个人主页字段显示为后端数据
  • 侧边栏与页面访问受角色控制
  • 仪表板与诊断页数据来自后端接口
• 常见问题：
  • Token 无效或过期 → 返回 401，需要重新登录
  • 代理失败 → 检查 VITE_API_TARGET 与后端协议/端口
  • 外网访问本地开发 → 配置 VITE_ALLOWED_HOSTS，参考 Cloudflare-Tunnel-Guide.md

参考文件

• frontend-vue/vite.config.ts
• frontend-vue/src/app/main.ts
• frontend-vue/src/app/router/index.ts
• frontend-vue/src/app/stores/auth.ts
• frontend-vue/src/app/views/Profile.vue
• frontend-vue/src/app/components/Sidebar.vue
• frontend-vue/src/app/constants/roles.ts