aiops/docs/project-structure.md

# 项目结构

## 整体结构

```
aiops/
├── frontend/                    # 前端 (React 19 + TypeScript + Vite)
│   ├── src/
│   │   ├── api/                 # API 封装（按菜单域拆分，http.ts 自动解包 .data）
│   │   │   ├── server/          # 服务器 / 区域 / 资源模型
│   │   │   ├── kubernetes/      # K8s 集群 / Pod / Workload
│   │   │   ├── monitor/         # 告警 / 指标 / 数据源 / Grafana
│   │   │   ├── log/             # 日志中心（Loki / ES 代理查询）
│   │   │   ├── deploy/          # 流水线 / 发布 / 凭证
│   │   │   ├── task/            # 定时任务 / 脚本库 / 远程执行
│   │   │   ├── approval/        # 审批流程
│   │   │   ├── audit/           # 操作审计 / 终端审计
│   │   │   ├── aiops/           # AI 助手 / Agent CLI
│   │   │   ├── cloud/           # 云账号 / 域名 / 账单
│   │   │   ├── system/          # 用户 / 角色
│   │   │   └── agent/           # Agent 监控
│   │   ├── pages/               # 复杂域级页面（从 components 迁入）
│   │   │   ├── monitor/         # 监控中心 / 主机监控 / 中间件 / SNMP / 站点
│   │   │   ├── approval/        # 审批分类 / 流程 / 权限
│   │   │   └── audit/           # 操作审计 / 登录日志 / 终端审计回放
│   │   ├── components/          # 业务组件 + 布局
│   │   │   ├── layout/          # PageShell / Sidebar / Header / ThemePicker
│   │   │   ├── dashboard/       # 仪表盘
│   │   │   ├── server/          # 服务器管理
│   │   │   ├── k8s/             # K8s 集群管理
│   │   │   ├── monitor/         # 告警中心 / 日志中心 / 数据源
│   │   │   ├── deploy/          # CI/CD 流水线
│   │   │   ├── task/            # 定时任务 / 脚本库 / 远程执行
│   │   │   ├── aiops/           # AI 助手 / Agent CLI / 大模型设置
│   │   │   ├── cloud/           # 云资源
│   │   │   ├── approval/        # 审批组件（对话框 / 流程图）
│   │   │   ├── system/          # 系统管理
│   │   │   └── ui/              # shadcn/ui 基础组件
│   │   ├── locales/             # i18n 翻译 (zh-CN.json / en-US.json)
│   │   ├── i18n/                # i18next 初始化
│   │   ├── hooks/               # useTheme / useConfirm / usePermission 等
│   │   ├── store/               # Zustand 状态管理
│   │   ├── types/               # TypeScript 类型（按域拆分）
│   │   ├── utils/               # 主题 / 权限 / 导出 / 校验工具
│   │   └── lib/                 # 通用工具（cn 等）
│   ├── package.json
│   ├── vite.config.ts           # 代理 /api、/ws、/health、/version 到 :8080
│   └── Dockerfile               # [legacy] 独立 Nginx 镜像
│
├── backend/                     # 后端 (Go 1.24 + Gin + GORM)
│   ├── main.go                  # 应用入口（CLI + HTTP 服务）
│   ├── embed.go                 # go:embed 前端静态资源
│   ├── static/                  # 前端构建产物（embed 目录）
│   ├── config/                  # Viper 配置加载
│   ├── controller/              # HTTP 处理器（60+ 文件按领域拆分）
│   ├── middleware/              # JWT / Admin / PipelineAccess / CORS / 日志
│   ├── router/                  # 路由注册（~1000 行）
│   ├── model/                   # GORM 数据模型（86+ 表）
│   ├── dto/                     # 请求/响应 DTO
│   ├── service/                 # 业务逻辑层
│   ├── repository/              # 数据访问层
│   ├── seed/                    # 种子数据
│   ├── pkg/                     # 公共包
│   │   ├── database/            # DB 连接 + AutoMigrate
│   │   ├── kubernetesclient/    # 轻量 K8s 客户端
│   │   ├── remoteexec/          # Go-native SSH 远程执行
│   │   ├── agentcli/            # AI 运维 Agent 引擎（ReAct + Evolver）
│   │   ├── toolinstaller/       # 工具懒加载（kubectl/maven/helm 等）
│   │   ├── redis/               # Redis 连接
│   │   ├── logger/              # Zap 日志
│   │   └── wshub/               # WebSocket Hub
│   ├── config.yaml              # 默认配置
│   └── Dockerfile               # [legacy] 分离式后端镜像
│
├── agent/                       # 监控 Agent（独立 Go module）
│   ├── main.go                  # CLI 入口
│   ├── collector/               # /proc 指标采集
│   ├── task/                    # 远程任务执行
│   ├── reporter/                # HTTP 上报
│   └── deploy/                  # install.sh + systemd
│
├── docs/                        # 开发文档
│   └── agent/                   # Agent CLI 设计文档集（10 篇）
├── deploy/kubernetes/           # K8s 清单 (devops 命名空间)
├── docker-compose.yml           # MySQL + Redis + AIOps embed
├── docker-compose.k8s.yml       # 单应用 + 外部 DB
├── Dockerfile.embed             # embed 单容器镜像（推荐）
├── run.sh                       # 统一入口脚本
├── aiops                        # 独立二进制产物（gitignore）
└── README.md
```

## 前端目录约定

### api/ vs pages/ vs components/

| 目录 | 职责 | 示例 |
|------|------|------|
| `api/` | HTTP 请求封装，按菜单域分子目录 | `api/monitor/alert.ts`、`api/task/remote-exec.ts` |
| `pages/` | 复杂多 Tab / 多子面板页面，域级路由入口 | `pages/monitor/HostMonitor.tsx`、`pages/audit/TerminalAuditTab.tsx` |
| `components/` | 可复用业务组件、对话框、列表项 | `components/monitor/log-center/LogCenter.tsx` |

> 迁移原则：简单 CRUD 页面留在 `components/`，多 Tab + 子模块拆分的复杂页面迁入 `pages/`。

### 布局与设计系统

| 组件 / 类名 | 说明 |
|-------------|------|
| `PageShell` | 统一页面骨架：标题 / 指标条 / 工具栏 / Tab / 内容区 |
| `PageTabs` | Tab 切换栏（`dg-page-tab` 样式） |
| `ContentPanel` | 内容区面板容器 |
| `dg-page*` | CSS 设计令牌（定义于 `index.css`，主题变量驱动） |
| `ThemePicker` | 7 套主题切换（跟随系统 + 6 款配色） |

## 部署相关文件

| 文件 | 用途 |
|------|------|
| `run.sh` | build / docker / kubernetes / release 统一入口 |
| `Dockerfile.embed` | 生产推荐：前端嵌入后端单容器 |
| `docker-compose.yml` | 3 容器：MySQL + Redis + AIOps |
| `backend/static/` | `go:embed` 目标，由 `./run.sh build` 同步 |
| `./aiops` | 独立二进制输出路径（项目根目录） |

## 技术栈

### 前端

| 技术 | 版本 | 用途 |
|------|------|------|
| React | 19+ | 前端框架 |
| TypeScript | 5+ | 类型安全 |
| Vite | 7+ | 构建工具 |
| Tailwind CSS | 3+ | 样式框架 |
| shadcn/ui | - | UI 组件库 |
| Zustand | 5+ | 状态管理 |
| TanStack Query | 5+ | 数据请求 |
| i18next | - | 国际化（zh-CN / en-US） |

### 后端

| 技术 | 版本 | 用途 |
|------|------|------|
| Go | 1.24+ | 编程语言 |
| Gin | v1.9+ | Web 框架 |
| GORM | v1.30+ | ORM |
| JWT | v5 | 认证 |
| Viper | - | 配置管理 |
| Zap | - | 结构化日志 |
| SQLite / MySQL / Redis | - | 存储 |

## 端口分配

| 服务 | 端口 | 说明 |
|------|------|------|
| 前端 (Vite dev) | 5173 | 开发模式 |
| 后端 / embed 部署 | 8080 | API + WebSocket + SPA |
| Docker Compose MySQL | 3306 | 可选暴露 |
| K8s NodePort | 30080 | 集群外访问 |

## 版本信息注入

编译时通过 ldflags 注入 `main.Version` / `BuildTime` / `GitCommit`：

- `./run.sh build` / `./run.sh build tag v1.5.0`
- `Dockerfile.embed` 构建参数 `VERSION` / `BUILD_TIME` / `GIT_COMMIT`
- 运行时：`./aiops version`、`GET /version`