# 运维管理平台模块化开发规范

依据：

- [液态玻璃后台 UI 设计规范](./liquid-glass-admin-ui-guideline.md)
- [运维管理平台第一版开发内容](./v1-development-scope.md)

目标：建立一套可长期维护的开发规范，让第一版能快速落地，同时避免后续接入真实 Kubernetes、日志、监控、数据库资源、审批流时推倒重来。

## 1. 技术方向

第一版默认按前后端分离设计，前端先使用 Mock 数据完成完整业务闭环，后端接口后续按相同契约接入。

推荐前端技术栈：

| 类型 | 推荐 |
| --- | --- |
| 语言 | TypeScript |
| UI 框架 | React |
| 构建工具 | Vite |
| 路由 | React Router |
| 服务端状态 | TanStack Query |
| 客户端状态 | Zustand 或 React Context |
| 表单 | React Hook Form |
| 校验 | Zod |
| Mock | MSW |
| 单元测试 | Vitest |
| 组件测试 | Testing Library |
| E2E | Playwright |
| 样式 | CSS Variables + CSS Modules |
| 图标 | lucide-react |
| 图表 | Recharts 或 ECharts |

技术选择原则：

- 服务端数据用 Query 管理，不放进全局 Store。
- 项目、环境、集群这类 UI 上下文可以放全局 Store。
- UI Token 必须通过 CSS 变量统一管理。
- Mock 层必须和真实 API 共用类型定义。
- 业务模块优先纵向切分，不按文件类型横向堆叠。

## 2. 模块化架构

推荐使用“业务垂直切片 + 分层依赖”的结构。

目录结构：

```text
src/
  app/
    App.tsx
    router.tsx
    providers/
      QueryProvider.tsx
      AppStateProvider.tsx
    styles/
      tokens.css
      glass.css
      layout.css
      components.css

  pages/
    overview/
    services/
    service-detail/
    releases/
    resources/
    logs-events/
    audit/

  widgets/
    app-shell/
    top-context-bar/
    service-table/
    release-drawer/
    restart-dialog/
    metric-dashboard/
    event-timeline/

  features/
    switch-project-context/
    filter-services/
    release-service/
    restart-service/
    search-logs/
    filter-audits/

  entities/
    project/
    cluster/
    service/
    release/
    resource/
    event/
    audit/
    user/

  shared/
    api/
    config/
    constants/
    lib/
    types/
    ui/
    hooks/
    mocks/
    assets/
```

分层职责：

| 层级 | 职责 | 示例 |
| --- | --- | --- |
| `app` | 应用启动、路由、全局 Provider、全局样式 | `router.tsx`、`QueryProvider` |
| `pages` | 页面编排，只组合 widgets/features/entities | `OverviewPage` |
| `widgets` | 页面级业务区块，可包含多个 feature | `ServiceTable`、`ReleaseDrawer` |
| `features` | 用户可执行的业务动作 | 发布服务、重启服务、筛选服务 |
| `entities` | 业务实体模型、实体 API、实体展示组件 | `service`、`release` |
| `shared` | 无业务含义的通用能力 | Button、Table、fetcher、formatDate |

依赖方向：

```text
app -> pages -> widgets -> features -> entities -> shared
```

规则：

- 下层不能 import 上层。
- `shared` 不能 import 任何业务模块。
- `entities` 之间尽量不直接互相 import，跨实体组合放在 `features` 或 `widgets`。
- 页面不能直接写复杂业务逻辑，页面只做布局和组合。
- 同一业务动作只允许有一个入口模块，例如发布服务统一放在 `features/release-service`。

## 3. 模块目录规范

每个业务模块使用相同结构，便于查找。

```text
features/release-service/
  api/
    createRelease.ts
  model/
    schema.ts
    types.ts
    useReleaseService.ts
  ui/
    ReleaseForm.tsx
    ReleaseSteps.tsx
  lib/
    buildReleasePayload.ts
  index.ts
```

`index.ts` 只导出模块的公开 API。

允许导出：

- 页面或组件需要使用的 UI。
- Hook。
- 类型。
- 纯工具函数。

禁止导出：

- 内部私有组件。
- 临时常量。
- Mock 实现细节。
- 只为绕过依赖规则而暴露的对象。

## 4. 命名规范

文件命名：

| 类型 | 规范 | 示例 |
| --- | --- | --- |
| React 组件 | PascalCase | `ServiceTable.tsx` |
| Hook | camelCase，以 `use` 开头 | `useServicesQuery.ts` |
| 工具函数 | camelCase | `formatDuration.ts` |
| 类型文件 | `types.ts` | `entities/service/model/types.ts` |
| Schema | `schema.ts` | `release/model/schema.ts` |
| 常量 | `constants.ts` | `shared/constants/status.ts` |
| 样式模块 | 同组件名 | `ServiceTable.module.css` |
| 测试 | 同文件名 + `.test` | `formatDuration.test.ts` |

类型命名：

- 业务实体：`Service`、`ReleaseRecord`、`DataResource`。
- API 请求：`CreateReleaseRequest`。
- API 响应：`ServiceListResponse`。
- 表单值：`ReleaseFormValues`。
- 组件 Props：`ServiceTableProps`。

状态枚举：

- TypeScript 使用字符串联合类型优先。
- 后端返回值必须稳定，不使用中文作为状态码。

示例：

```ts
export type ServiceStatus = "healthy" | "warning" | "critical" | "unknown" | "running";
```

## 5. TypeScript 规范

必须开启：

```json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}
```

规则：

- 禁止使用 `any`，确实无法确定时使用 `unknown` 并收窄。
- API 返回值必须有类型。
- 表单提交值必须有 Zod Schema 校验。
- 组件 Props 必须显式定义。
- 复杂类型放在 `model/types.ts`。
- 跨模块共享类型只能从模块 `index.ts` 导入。
- 不在组件里直接拼接后端数据结构，使用 mapper 转成前端 ViewModel。

推荐：

```ts
type ServiceTableRow = {
  id: string;
  name: string;
  status: ServiceStatus;
  version: string;
  instanceText: string;
  cpuUsage: number;
  memoryUsage: number;
  owner: string;
};
```

## 6. API 层规范

统一入口：

```text
shared/api/
  httpClient.ts
  queryKeys.ts
  errors.ts
```

实体 API：

```text
entities/service/api/
  getServices.ts
  getServiceDetail.ts
  getServiceInstances.ts
  getServiceMetrics.ts
```

规则：

- 所有请求必须经过 `shared/api/httpClient.ts`。
- API 函数只负责请求和数据转换，不处理 UI Toast。
- 请求参数统一使用对象，不使用多个位置参数。
- 列表接口必须支持 `projectId`、`environment`、`clusterId`。
- 写操作必须返回可用于刷新缓存的业务 ID。
- API 错误统一转成标准错误对象。

标准错误：

```ts
type ApiError = {
  code: string;
  message: string;
  requestId?: string;
  details?: unknown;
};
```

Query Key 规范：

```ts
export const queryKeys = {
  services: (params: ServiceListParams) => ["services", params] as const,
  serviceDetail: (id: string) => ["service", id] as const,
  releases: (params: ReleaseListParams) => ["releases", params] as const,
};
```

## 7. 状态管理规范

状态分三类：

| 类型 | 管理方式 | 示例 |
| --- | --- | --- |
| 服务端状态 | TanStack Query | 服务列表、发布记录、数据资源 |
| 全局 UI 上下文 | Zustand / Context | 项目、环境、集群、当前用户 |
| 局部 UI 状态 | React `useState` | 抽屉开关、当前 Tab、表单中间态 |

全局 Store 只放：

- 当前项目。
- 当前环境。
- 当前集群。
- 当前用户和角色。
- 全局布局状态。

禁止放入全局 Store：

- 服务列表。
- 发布记录。
- 日志列表。
- 监控图表数据。
- 临时表单值。

原因：这些数据属于服务端状态，应该由 Query 缓存、刷新和失效控制。

## 8. UI 组件规范

组件分三类：

| 类型 | 目录 | 说明 |
| --- | --- | --- |
| 通用 UI | `shared/ui` | Button、Table、Badge、Drawer |
| 实体组件 | `entities/*/ui` | ServiceStatusBadge、ResourceTypeIcon |
| 业务组件 | `features` / `widgets` | ReleaseDrawer、ServiceTable |

通用 UI 规则：

- 不包含业务字段。
- 不直接请求接口。
- 不读取全局业务 Store。
- 通过 Props 接收数据。
- 支持 `className`。
- 支持键盘焦点。
- 支持 disabled、loading、error 状态。

业务组件规则：

- 可以组合实体组件和通用 UI。
- 可以调用 feature 内 Hook。
- 不直接写全局样式。
- 危险操作必须显式传入 `environment`。

组件文件结构：

```text
Button/
  Button.tsx
  Button.module.css
  Button.test.tsx
  index.ts
```

## 9. 样式规范

样式分层：

```text
app/styles/
  tokens.css
  glass.css
  layout.css
  components.css
```

规则：

- 颜色、圆角、阴影、字号、间距必须使用 Token。
- 组件局部样式使用 CSS Modules。
- 禁止在业务组件里硬编码主色和状态色。
- 禁止使用行内样式写核心布局。
- 不使用负字距。
- 不使用大面积单色主题覆盖液态玻璃风格。
- 图表颜色从 Token 或统一常量中读取。

CSS 命名：

```css
.root {}
.header {}
.body {}
.footer {}
.title {}
.meta {}
.actions {}
.isActive {}
.isDisabled {}
```

玻璃样式统一使用类：

- `.glass-surface`
- `.glass-surface-strong`
- `.glass-subtle`

不要在每个组件里重复实现玻璃效果。

## 10. 页面开发规范

页面只做三件事：

- 读取路由参数。
- 组合 widgets/features。
- 控制页面级布局。

页面不做：

- 直接调用底层 HTTP。
- 写复杂数据转换。
- 处理发布和重启流程细节。
- 写超过 80 行的业务逻辑。

页面示例：

```tsx
export function ServicesPage() {
  return (
    <PageLayout title="微服务">
      <ServiceFilters />
      <ServiceTable />
    </PageLayout>
  );
}
```

## 11. 业务模块规范

### 11.1 服务模块

目录：

```text
entities/service/
  api/
  model/
  ui/
  lib/
  index.ts
```

职责：

- 服务类型定义。
- 服务列表接口。
- 服务详情接口。
- 服务状态展示。
- 服务数据格式化。

不负责：

- 发布服务。
- 重启服务。
- 服务筛选表单。

### 11.2 发布模块

目录：

```text
features/release-service/
  api/
  model/
  ui/
  lib/
  index.ts
```

职责：

- 版本选择。
- 发布策略选择。
- 预检查展示。
- 发布提交。
- 发布状态反馈。

规则：

- `prod` 必须要求二次确认。
- 发布完成后必须刷新服务详情和发布记录。
- 发布成功或失败都必须生成事件和审计记录。

### 11.3 重启模块

职责：

- 单实例重启。
- 全部实例重启。
- 滚动重启和立即重启。
- 影响范围展示。

规则：

- `prod` 默认滚动重启。
- 立即重启必须二次确认。
- 操作完成后必须生成事件和审计记录。

### 11.4 数据资源模块

职责：

- 展示 MySQL、MongoDB、Redis、Kafka 状态。
- 展示容量、连接数、备份、关联服务。
- 展示异常事件。

规则：

- 第一版不开放查询入口。
- 第一版不开放恢复入口。
- 生产环境不显示任何直接执行数据库命令的能力。

## 12. 表单规范

所有表单必须：

- 使用 Schema 校验。
- 提交前做客户端校验。
- 提交中禁用提交按钮。
- 提交失败展示错误原因。
- 危险操作展示影响范围。

发布表单必须校验：

- 目标版本不能为空。
- 发布策略不能为空。
- `prod` 环境必须勾选确认。

重启表单必须校验：

- 重启范围不能为空。
- 立即重启必须二次确认。
- 单实例重启必须有实例 ID。

## 13. 权限规范

前端权限用于控制体验，后端权限用于保证安全。第一版即使没有真实后端，也要按这个结构设计。

权限点：

```ts
type Permission =
  | "service:read"
  | "service:release"
  | "service:restart"
  | "release:read"
  | "resource:read"
  | "logs:read"
  | "audit:read";
```

规则：

- 权限不足的危险操作显示禁用态，不直接隐藏。
- 禁用态必须说明原因。
- 生产环境操作必须额外判断角色和确认状态。
- 审计页面只对有 `audit:read` 权限的角色开放。

## 14. Mock 规范

Mock 使用 MSW 或等价方案。

目录：

```text
shared/mocks/
  browser.ts
  handlers.ts
  data/
    projects.ts
    services.ts
    releases.ts
    resources.ts
    events.ts
    audits.ts
```

规则：

- Mock 数据结构必须复用实体类型。
- Mock 行为要模拟真实写操作。
- 发布成功后更新服务版本。
- 重启成功后新增事件和审计。
- 支持模拟失败场景。
- 支持模拟空状态。

必须覆盖：

- Healthy、Warning、Critical 服务。
- 发布成功、失败、执行中。
- MySQL、MongoDB、Redis、Kafka 多种状态。
- `prod` 环境二次确认。
- 权限不足禁用操作。

## 15. 错误处理规范

错误分三层：

| 层级 | 处理 |
| --- | --- |
| API 层 | 转换为 `ApiError` |
| 业务层 | 判断是否可重试、是否需要刷新 |
| UI 层 | 展示错误状态、Toast、下一步操作 |

页面错误态必须提供：

- 错误原因。
- 重试按钮。
- 可选的查看事件入口。

写操作失败必须提供：

- 失败原因。
- requestId，如果有。
- 是否可以重试。
- 是否需要查看事件。

禁止：

- 只显示“操作失败”。
- 把原始异常对象直接渲染到页面。
- 静默吞掉接口错误。

## 16. 日志和审计规范

前端事件日志用于排查，审计记录用于追责。

发布、重启、回滚必须产生审计记录。

审计记录字段：

- 操作时间。
- 操作人。
- 角色。
- 操作对象。
- 操作类型。
- 环境。
- 集群。
- 执行结果。
- 关联记录 ID。

生产环境操作必须有明显标识。

## 17. 测试规范

测试分层：

| 类型 | 工具 | 覆盖内容 |
| --- | --- | --- |
| 单元测试 | Vitest | 工具函数、mapper、权限判断、表单校验 |
| 组件测试 | Testing Library | Button、Table、Badge、ReleaseDrawer |
| 集成测试 | Testing Library + MSW | 发布流程、重启流程、筛选流程 |
| E2E | Playwright | 核心用户路径 |

必须测试：

- 服务状态 Badge 文案和颜色类。
- 服务搜索和筛选。
- `prod` 发布确认。
- 发布成功后版本更新。
- 发布失败后错误反馈。
- 重启成功后事件和审计新增。
- 权限不足时按钮禁用。
- Secret 不显示明文。

E2E 核心路径：

1. 进入总览页。
2. 切换到 `prod`。
3. 打开 `user-service` 详情。
4. 打开发版抽屉。
5. 选择目标版本。
6. 勾选生产确认。
7. 执行发布。
8. 验证发布记录和审计记录。

## 18. 代码质量规范

必须配置：

- ESLint。
- Prettier。
- TypeScript strict。
- lint-staged。
- 单元测试命令。
- 构建命令。

建议脚本：

```json
{
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "preview": "vite preview",
    "lint": "eslint .",
    "format": "prettier --write .",
    "test": "vitest run",
    "test:watch": "vitest",
    "e2e": "playwright test",
    "check": "npm run lint && npm run test && npm run build"
  }
}
```

提交前最低要求：

- TypeScript 无错误。
- ESLint 无错误。
- 单元测试通过。
- 构建通过。

涉及 UI 的改动还要：

- 浏览器预览。
- 检查桌面宽度 1280px。
- 检查表格文字不重叠。
- 检查抽屉内容可滚动。
- 检查 `prod` 危险操作二次确认。

## 19. Git 和提交规范

分支命名：

```text
feature/overview-page
feature/release-drawer
fix/prod-release-confirm
chore/setup-eslint
```

提交信息：

```text
feat: add service release drawer
fix: require confirmation before prod restart
chore: setup testing pipeline
docs: add modular development guideline
```

提交类型：

| 类型 | 含义 |
| --- | --- |
| `feat` | 新功能 |
| `fix` | 修复 |
| `docs` | 文档 |
| `style` | 格式和样式调整 |
| `refactor` | 重构 |
| `test` | 测试 |
| `chore` | 工程配置 |

规则：

- 一个提交只做一类事情。
- 不把大范围格式化混进功能提交。
- 不提交本地环境文件。
- 不提交密钥、Token、数据库连接串。

## 20. 环境变量规范

命名：

```text
VITE_API_BASE_URL=
VITE_ENABLE_MOCK=
VITE_APP_ENV=
```

规则：

- 前端环境变量必须以 `VITE_` 开头。
- `.env.example` 必须维护。
- `.env.local` 不提交。
- 不在前端存储真实密钥。
- 生产环境配置由部署平台注入。

## 21. 性能规范

第一版性能目标：

- 首屏可交互时间控制在合理范围。
- 表格 100 条数据内交互不卡顿。
- 路由页面按需加载。
- 图表组件按页面懒加载。
- 日志列表避免一次渲染过多行。

规则：

- 路由级代码分割。
- 大图表库懒加载。
- 表格筛选优先使用 memoized selector。
- 不在 render 中做重型计算。
- 日志列表超过 500 行时考虑虚拟列表。

## 22. 安全规范

第一版必须遵守：

- 不展示 Secret 明文。
- 不在 localStorage 存储敏感 Token。
- 所有危险操作必须检查权限。
- 所有生产环境操作必须二次确认。
- 后端接入后必须校验权限，不能只依赖前端。
- 日志内容渲染要避免 XSS。
- 用户输入不能直接拼接到 URL path，必须 encode。

数据库资源限制：

- 第一版不做 SQL 查询。
- 第一版不做 Mongo 查询。
- 第一版不做备份恢复。
- 生产环境不显示直接执行命令入口。

## 23. 可访问性规范

最低要求：

- 所有按钮可键盘访问。
- 抽屉和弹窗可按 Esc 关闭。
- 菜单可键盘导航。
- 状态 Badge 必须有文字。
- 表单错误信息和字段绑定。
- 点击目标不小于 32px x 32px。
- 颜色不能作为唯一状态表达。

## 24. 开发顺序

推荐顺序：

1. 初始化项目和质量工具。
2. 建立 Token、玻璃样式、App Shell。
3. 建立 Mock 数据和 API 适配层。
4. 开发通用 UI 组件。
5. 开发实体模块：service、release、resource、event、audit。
6. 开发首页和微服务列表。
7. 开发服务详情页。
8. 开发发布抽屉和重启流程。
9. 开发发布记录、数据资源、日志事件、审计页。
10. 补齐测试、空状态、错误状态。
11. 浏览器视觉验收。
12. 构建验收。

## 25. Definition of Done

一个功能完成必须满足：

- 代码按模块边界放置。
- 类型完整，无 `any`。
- 样式使用全局 Token。
- Loading、Empty、Error 状态完整。
- 权限不足有禁用态和原因。
- `prod` 危险操作有二次确认。
- 写操作成功和失败都有反馈。
- 相关事件和审计记录更新。
- 单元测试或集成测试覆盖关键逻辑。
- `lint`、`test`、`build` 通过。
- 浏览器中验证 UI 不重叠、不溢出、抽屉可滚动。

## 26. 禁止项

- 禁止页面直接调用 `fetch`。
- 禁止在页面里堆业务逻辑。
- 禁止业务模块跨层反向依赖。
- 禁止在组件里硬编码设计 Token。
- 禁止把服务端状态放进全局 Store。
- 禁止生产环境危险操作绕过确认。
- 禁止展示 Secret 明文。
- 禁止生产数据库直接查询入口。
- 禁止只做成功态，不做失败态和空状态。
- 禁止没有审计记录的发布、重启、回滚。

## 27. 第一版推荐任务拆分

### 基础工程

- 初始化 Vite + React + TypeScript。
- 配置 ESLint、Prettier、Vitest。
- 配置路由和 Query Provider。
- 建立 `src` 分层目录。
- 建立全局样式 Token。

### UI 基础

- Button。
- IconButton。
- StatusBadge。
- GlassSurface。
- Table。
- Select。
- Tabs。
- Drawer。
- Dialog。
- Toast。
- EmptyState。

### 业务闭环

- Mock 数据。
- 总览页。
- 微服务页。
- 服务详情页。
- 发布抽屉。
- 重启确认。
- 发布记录页。
- 数据资源页。
- 日志与事件页。
- 权限与审计页。

### 验收

- 单元测试。
- 发布流程集成测试。
- 重启流程集成测试。
- Playwright 核心路径。
- 构建验证。
- 视觉检查。