docs: 同步 README 与 docs 文档至当前代码状态

- README 补充 PageShell、i18n、Agent CLI、中间件监控等近期功能 - project-structure 重写 api/pages/locales 目录约定 - development-guide 新增 PageShell 与 i18n 开发规范 - PROJECT_SUMMARY 整体重写，移除过时 internal/ 结构 - docs/README 新增 Agent CLI 设计文档索引与近期变更摘要 - dev-log 追加 2026-07-01 变更记录
2026-07-01 12:50:58 +08:00
1 parent e363ded445
commit 4cb0e62857
@@ -6,25 +6,45 @@
 aiops/
 ├── frontend/                    # 前端 (React 19 + TypeScript + Vite)
 │   ├── src/
-│   │   ├── components/          # 业务组件（单文件 <700 行）
-│   │   │   ├── agent/           # Agent 监控
-│   │   │   ├── aiops/           # AI 智能运维
+│   │   ├── api/                 # API 封装（按菜单域拆分，http.ts 自动解包 .data）
+│   │   │   ├── server/          # 服务器 / 区域 / 资源模型
+│   │   │   ├── kubernetes/      # K8s 集群 / Pod / Workload
+│   │   │   ├── monitor/         # 告警 / 指标 / 数据源 / Grafana
+│   │   │   ├── log/             # 日志中心（Loki / ES 代理查询）
+│   │   │   ├── deploy/          # 流水线 / 发布 / 凭证
+│   │   │   ├── task/            # 定时任务 / 脚本库 / 远程执行
 │   │   │   ├── approval/        # 审批流程
-│   │   │   ├── automation/      # 自动化运维
-│   │   │   ├── cloud/           # 云平台管理
+│   │   │   ├── audit/           # 操作审计 / 终端审计
+│   │   │   ├── aiops/           # AI 助手 / Agent CLI
+│   │   │   ├── cloud/           # 云账号 / 域名 / 账单
+│   │   │   ├── system/          # 用户 / 角色
+│   │   │   └── agent/           # Agent 监控
+│   │   ├── pages/               # 复杂域级页面（从 components 迁入）
+│   │   │   ├── monitor/         # 监控中心 / 主机监控 / 中间件 / SNMP / 站点
+│   │   │   ├── approval/        # 审批分类 / 流程 / 权限
+│   │   │   └── audit/           # 操作审计 / 登录日志 / 终端审计回放
+│   │   ├── components/          # 业务组件 + 布局
+│   │   │   ├── layout/          # PageShell / Sidebar / Header / ThemePicker
 │   │   │   ├── dashboard/       # 仪表盘
-│   │   │   ├── deploy/          # CI/CD 部署
-│   │   │   ├── k8s/             # K8s 集群管理
-│   │   │   ├── monitor/         # 监控告警
 │   │   │   ├── server/          # 服务器管理
+│   │   │   ├── k8s/             # K8s 集群管理
+│   │   │   ├── monitor/         # 告警中心 / 日志中心 / 数据源
+│   │   │   ├── deploy/          # CI/CD 流水线
+│   │   │   ├── task/            # 定时任务 / 脚本库 / 远程执行
+│   │   │   ├── aiops/           # AI 助手 / Agent CLI / 大模型设置
+│   │   │   ├── cloud/           # 云资源
+│   │   │   ├── approval/        # 审批组件（对话框 / 流程图）
 │   │   │   ├── system/          # 系统管理
 │   │   │   └── ui/              # shadcn/ui 基础组件
-│   │   ├── hooks/               # 自定义 Hooks
-│   │   ├── services/            # API 封装 (api.ts / http.ts)
+│   │   ├── locales/             # i18n 翻译 (zh-CN.json / en-US.json)
+│   │   ├── i18n/                # i18next 初始化
+│   │   ├── hooks/               # useTheme / useConfirm / usePermission 等
 │   │   ├── store/               # Zustand 状态管理
-│   │   └── types/               # TypeScript 类型
+│   │   ├── types/               # TypeScript 类型（按域拆分）
+│   │   ├── utils/               # 主题 / 权限 / 导出 / 校验工具
+│   │   └── lib/                 # 通用工具（cn 等）
 │   ├── package.json
-│   ├── vite.config.ts
+│   ├── vite.config.ts           # 代理 /api、/ws、/health、/version 到 :8080
 │   └── Dockerfile               # [legacy] 独立 Nginx 镜像
 │
 ├── backend/                     # 后端 (Go 1.24 + Gin + GORM)
@@ -32,10 +52,10 @@ aiops/
 │   ├── embed.go                 # go:embed 前端静态资源
 │   ├── static/                  # 前端构建产物（embed 目录）
 │   ├── config/                  # Viper 配置加载
-│   ├── controller/              # HTTP 处理器
-│   ├── middleware/              # JWT / 日志 / CORS
-│   ├── router/                  # 路由注册
-│   ├── model/                   # GORM 数据模型
+│   ├── controller/              # HTTP 处理器（60+ 文件按领域拆分）
+│   ├── middleware/              # JWT / Admin / PipelineAccess / CORS / 日志
+│   ├── router/                  # 路由注册（~1000 行）
+│   ├── model/                   # GORM 数据模型（86+ 表）
 │   ├── dto/                     # 请求/响应 DTO
 │   ├── service/                 # 业务逻辑层
 │   ├── repository/              # 数据访问层
@@ -43,8 +63,12 @@ aiops/
 │   ├── pkg/                     # 公共包
 │   │   ├── database/            # DB 连接 + AutoMigrate
 │   │   ├── kubernetesclient/    # 轻量 K8s 客户端
-│   │   ├── remoteexec/          # Go-native SSH
-│   │   └── toolinstaller/       # 工具懒加载
+│   │   ├── remoteexec/          # Go-native SSH 远程执行
+│   │   ├── agentcli/            # AI 运维 Agent 引擎（ReAct + Evolver）
+│   │   ├── toolinstaller/       # 工具懒加载（kubectl/maven/helm 等）
+│   │   ├── redis/               # Redis 连接
+│   │   ├── logger/              # Zap 日志
+│   │   └── wshub/               # WebSocket Hub
 │   ├── config.yaml              # 默认配置
 │   └── Dockerfile               # [legacy] 分离式后端镜像
 │
@@ -55,13 +79,9 @@ aiops/
 │   ├── reporter/                # HTTP 上报
 │   └── deploy/                  # install.sh + systemd
 │
+├── docs/                        # 开发文档
+│   └── agent/                   # Agent CLI 设计文档集（10 篇）
 ├── deploy/kubernetes/           # K8s 清单 (devops 命名空间)
-│   ├── namespace.yaml
-│   ├── deployment.yaml          # embed 单容器, lghost/aiops:<tag>
-│   ├── mysql.yaml / redis.yaml
-│   └── ...
-│
-├── docs/                        # 开发文档（本目录）
 ├── docker-compose.yml           # MySQL + Redis + AIOps embed
 ├── docker-compose.k8s.yml       # 单应用 + 外部 DB
 ├── Dockerfile.embed             # embed 单容器镜像（推荐）
@@ -70,6 +90,28 @@ aiops/
 └── 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 款配色） |
+
 ## 部署相关文件

 | 文件 | 用途 |
@@ -91,16 +133,17 @@ aiops/
 | Vite | 7+ | 构建工具 |
 | Tailwind CSS | 3+ | 样式框架 |
 | shadcn/ui | - | UI 组件库 |
-| Zustand | - | 状态管理 |
-| TanStack Query | - | 数据请求 |
+| Zustand | 5+ | 状态管理 |
+| TanStack Query | 5+ | 数据请求 |
+| i18next | - | 国际化（zh-CN / en-US） |

 ### 后端

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