# DataGuard - 数据库变更审核平台 开发文档

> 版本: v2.0  
> 更新日期: 2026-05-20  
> 技术栈: React 19 + TypeScript + Vite + Tailwind CSS + shadcn/ui

---

## 一、项目概述

DataGuard 是一款企业级数据库变更审核平台，对标 Bytebase / Yearning / Archery，支持多数据库实例管理、SQL 变更工单审批、查询审计、自动任务、权限控制等核心功能。

### 核心设计理念

- **安全优先**: 所有数据变更通过工单审批流程，SQL 自动审核 + 人工审批双重保障
- **多数据库支持**: MySQL、PostgreSQL、Redis、MongoDB、ClickHouse
- **审计可追溯**: 完整的查询审计日志，敏感数据自动脱敏
- **回滚可控**: 基于 Binlog ROW 格式的自动回滚 SQL 生成
- **角色分级**: admin / dba / developer / guest 四级权限控制

---

## 二、技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| 框架 | React | 19 |
| 语言 | TypeScript | 5.x |
| 构建 | Vite | 7.x |
| 样式 | Tailwind CSS | 3.4 |
| UI 库 | shadcn/ui + Radix UI | latest |
| 路由 | react-router-dom | 7.x |
| 图标 | lucide-react | latest |
| 图表 | recharts | 2.x |

### 目录结构

```
src/
├── components/           # 全局组件
│   ├── ui/              # shadcn/ui 组件（Button, Card, Dialog, Tabs, Switch, Select 等）
│   ├── Layout.tsx       # 主布局（侧边栏 + 顶部栏 + 内容区）
│   ├── PageHeader.tsx   # 统一页面头部（标题 + 描述 + 操作按钮）
│   ├── EmptyState.tsx   # 空状态组件
│   └── SkeletonCard.tsx # Loading 骨架屏
├── pages/               # 页面组件（按路由划分）
│   ├── Dashboard.tsx           # 仪表盘
│   ├── InstancePage.tsx        # 数据库实例管理
│   ├── TicketsPage.tsx         # 数据变更工单
│   ├── QueriesPage.tsx         # 查询审计
│   ├── RolesPage.tsx           # 角色管理
│   ├── UsersPage.tsx           # 用户管理
│   ├── DataPermissionPage.tsx  # 数据权限
│   ├── AuditRulesPage.tsx      # 审核规则
│   ├── WorkflowPage.tsx        # 审批流程配置
│   ├── AutoTaskPage.tsx        # 自动任务
│   ├── AnnouncementPage.tsx    # 公告管理
│   └── LoginPage.tsx           # 登录
├── hooks/               # 自定义 Hooks
│   └── useAuth.tsx      # 权限上下文 + useAuth + useActionPermission
├── lib/                 # 工具库
│   ├── utils.ts         # 工具函数
│   ├── constants.ts     # 常量
│   ├── queryTemplates.ts# 查询模板
│   └── storage.ts       # localStorage 命名空间与迁移
├── types/               # TypeScript 类型定义
│   └── index.ts         # 全局类型
├── App.tsx              # 根组件（路由 + 路由守卫）
├── index.css            # 全局样式 + 深色主题变量
└── main.tsx             # 入口文件
```

---

## 三、核心功能模块

### 3.1 仪表盘 (Dashboard)

**路由**: `/dashboard`  
**权限**: 全部角色

**功能说明**:
- 工单统计卡片（总工单 / 待审批 / 本月 / 进行中）
- 审核规则统计卡片
- 查询统计卡片
- 工单趋势折线图（30天）
- 状态分布饼图
- 工单表格列表（含详情弹窗）

**关键代码**:
```tsx
// pages/Dashboard.tsx
// 使用 recharts 绘制图表，数据来自 /dashboard/stats 接口
```

---

### 3.2 数据库实例管理 (InstancePage)

**路由**: `/mysql`, `/postgres`, `/redis`, `/mongo`, `/clickhouse`  
**权限**: admin, dba

**功能说明**:
- 卡片网格展示实例（连接状态、版本、环境、主机、端口）
- 实时性能指标（QPS、连接数、磁盘、CPU、内存）
- 实例详情页（监控图表、连接信息、慢查询 TOP5、基本信息）
- 支持批量添加实例

**关键数据结构**:
```typescript
interface DBInstance {
  id: number;
  name: string;
  host: string;
  port: number;
  type: 'mysql' | 'postgres' | 'redis' | 'mongo' | 'clickhouse';
  env: 'production' | 'staging' | 'development';
  status: 'connected' | 'disconnected' | 'error';
  version: string;
  databases: number;
  tables: number;
  size: string;
  connections: number;
  maxConnections: number;
  qps: number;
  latency: number;
  cpu: number;
  memory: number;
  disk: number;
  uptime: string;
  lastBackup: string;
}
```

---

### 3.3 数据变更工单 (TicketsPage)

**路由**: `/tickets`  
**权限**: admin, dba, developer（developer 仅可查看自己工单）

**功能说明**:
- 工单列表（状态快捷筛选、搜索、多维度过滤）
- 新建工单（SQL 编辑器、审核预览、回滚 SQL）
- 工单详情（审批流程可视化、SQL 内容、回滚 SQL、审批记录）
- 操作权限：审批/拒绝（dba+admin）、执行（dba+admin）

**工单状态流转**:
```
pending(待审批) -> reviewing(审批中) -> approved(已通过) -> executing(执行中) -> success(成功)
                                          -> rejected(已拒绝)
                                          -> failed(失败)
```

**回滚机制**:
- 基于 MySQL Binlog ROW 格式解析
- AST 语法分析提取变更前后的数据
- 执行前自动备份受影响数据
- 72 小时内可一键回滚

**关键数据结构**:
```typescript
interface Ticket {
  id: string;
  title: string;
  dbType: string;
  instance: string;
  database: string;
  sql: string;
  rollbackSql?: string;
  status: 'pending' | 'reviewing' | 'approved' | 'rejected' | 'executing' | 'success' | 'failed';
  priority: 'high' | 'medium' | 'low';
  applicant: string;
  approver: string;
  createTime: string;
  executeTime: string;
  reason: string;
  workflowSteps?: { name: string; status: string; time?: string }[];
  approvalRecords?: { approver: string; action: string; comment: string; time: string }[];
}
```

---

### 3.4 查询审计 (QueriesPage)

**路由**: `/queries`  
**权限**: 全部角色（guest 不可新建查询）

**功能说明**:
- 查询审计日志列表（SQL 语句、执行时长、返回行数、敏感数据标记）
- 查询结果集展示（敏感字段自动脱敏）
- 新建查询（SQL 编辑器 + 数据库选择）
- 查询结果导出

**敏感数据脱敏规则**:
| 字段类型 | 脱敏方式 | 示例 |
|---------|---------|------|
| 邮箱 | 前缀掩码 | `abc***@gmail.com` |
| 手机号 | 中间掩码 | `138****8888` |
| 身份证号 | 中间掩码 | `110**********0011` |
| 银行卡 | 后四位保留 | `**** **** **** 1234` |

---

### 3.5 角色管理 (RolesPage)

**路由**: `/roles`  
**权限**: admin

**功能说明**:
- 角色列表展示
- 权限矩阵（页面权限 + 操作权限 + 数据权限）
- 角色创建/编辑/删除

**系统内置角色**:

| 角色 | 权限范围 |
|------|---------|
| 超级管理员(admin) | 全部功能 |
| 数据库管理员(dba) | 数据源 + 工单审批 + 查询 + 权限 + 规则 + 流程 |
| 开发人员(developer) | 工单提交 + 查询 |
| 访客(guest) | 仅查询审计查看 |

---

### 3.6 用户管理 (UsersPage)

**路由**: `/users`  
**权限**: admin

**功能说明**:
- 用户列表（用户名、角色、状态、最近登录）
- 新建/编辑/禁用用户
- 角色分配

---

### 3.7 审批流程配置 (WorkflowPage)

**路由**: `/workflow`  
**权限**: admin, dba

**功能说明**:
- 审批流程模板管理
- 流程步骤配置：提交阶段 -> 审核阶段 -> 执行阶段
- 支持多级审批（一级审批、二级审批）
- 审批模式：或签（任一人通过）/ 会签（全部人通过）
- 流程可视化展示
- 适用数据库类型配置

**典型流程示例**:
```
提交阶段(提交人) -> 一级审批(部门负责人, 或签) -> 二级审批(DBA团队, 或签) -> 执行阶段(DBA执行人)
```

---

### 3.8 自动任务 (AutoTaskPage)

**路由**: `/auto-task`  
**权限**: admin

**功能说明**:
- 定时 SQL 任务管理（Cron 表达式）
- 支持频率：一次性 / 每小时 / 每天 / 每周 / 每月
- 任务启停控制
- 执行日志和通知

**典型场景**:
- 每日数据归档
- 周/月度统计报表生成
- 索引健康检查
- 过期数据清理

---

### 3.9 配置平台 (ConfigPlatformPage)

**路由**: `/config-platform`  
**权限**: admin

**包含 5 个配置模块**:

#### 3.9.1 消息推送
- 渠道：飞书、钉钉、企业微信、Telegram、邮件
- 每个渠道独立开关 + Webhook 配置
- 通知事件：工单创建、审批通过、审批拒绝、执行完成、执行失败
- 连接测试功能

#### 3.9.2 LDAP 设置
- LDAP/AD 域账号登录集成
- 服务器地址、Bind DN、Base DN、字段映射
- 自动同步用户（可配置同步间隔）

#### 3.9.3 查询限制
- 查询审核审批开关（不开启时允许查询授权资源）
- 最大 Limit 限制（滑块控制 100-100,000）
- 查询超时时间
- 结果导出行数限制
- 写入操作开关
- 禁止的关键词列表

#### 3.9.4 工单提交规则
| 规则 | 说明 |
|------|------|
| SQL 语法检查 | 提交前自动语法校验 |
| 影响行数限制 | 单次操作最大影响行数 |
| 工单标题必填 | 最小 5 字符 |
| 变更原因必填 | 最小 10 字符 |
| 回滚 SQL 必填 | UPDATE/DELETE 必须提供回滚 |
| 禁止提交时段 | 配置高峰时段禁止提交 |
| 同一表并发限制 | 同一表只能有一个进行中的变更 |
| 敏感操作二次确认 | 影响行数超阈值需二次确认 |

#### 3.9.5 DDL 拦截规则
| 规则 | 动作 |
|------|------|
| DROP TABLE / DATABASE | 拦截 |
| TRUNCATE TABLE | 拦截 |
| ALTER TABLE DROP/MODIFY/CHANGE COLUMN | 需审批 |
| RENAME TABLE | 需审批 |
| CREATE TABLE / ADD COLUMN / CREATE INDEX | 警告 |

---

## 四、权限系统

### 4.1 权限架构

```
路由守卫 (RouteGuard)
  -> 菜单过滤 (visibleMenuItems)
    -> 页面级权限 (PageHeader action/secondaryAction)
      -> 操作级权限 (useActionPermission)
        -> 数据级权限 (列表过滤)
```

### 4.2 权限 Hook

```typescript
// 获取用户信息和权限方法
const { user, isAdmin, isDBA, isDeveloper, isGuest, hasPermission } = useAuth();

// 检查操作权限
const canApprove = useActionPermission('ticket.approve');  // true/false
```

### 4.3 权限配置表

菜单/路由权限（唯一源）：`constants/menu.ts` 中 `menuItems[*].roles`
操作权限：`hooks/useAuth.tsx` 中 `actionPermissionMap`

### 4.4 角色切换演示

侧边栏底部提供角色切换按钮（仅演示用途），切换后：
1. 自动过滤菜单项
2. 检查当前页面是否有权限，无权限则跳转到仪表盘
3. 页面内按钮按新角色重新渲染

---

## 五、数据层

后端 API 已全面就绪，无 Mock 层。所有请求走 `src/api/request.ts` 统一实例：

- 响应拦截器已解包一层（拿到的是响应体本身），API 函数用 `request.get<unknown, T>()` 标注返回类型
- 401 自动走 refresh token 单飞刷新（并发只刷一次），失败才跳登录并携带 redirect 回跳
- 单请求逃生口：`{ skipErrorHandler: true }` 关闭全局错误提示
- 列表数据获取用 `hooks/useFetchList.ts`（取消 + 版本号防错序 + error 三态）

---
## 六、开发规范

### 6.1 新增页面步骤

1. 在 `src/pages/` 创建页面组件
2. 在 `src/App.tsx` 添加路由
3. 在 `src/constants/menu.ts` 的 `menuItems` 中添加菜单项（roles 即路由权限，单源维护）
4. （如需要）在 `actionPermissionMap` 中添加页面操作权限

### 6.2 新增操作权限

1. 在 `useAuth.tsx` 的 `actionPermissionMap` 中定义权限
2. 在页面中使用 `useActionPermission('action.key')` 获取权限
3. 使用条件渲染控制按钮/操作的显示

```tsx
const canDelete = useActionPermission('ticket.delete');

{canDelete && (
  <button onClick={handleDelete}>删除</button>
)}
```

### 6.3 使用 PageHeader 组件

```tsx
import PageHeader from '@/components/PageHeader';

<PageHeader
  title="页面标题"
  description="页面描述"
  action={{ label: '新建', icon: Plus, onClick: () => {}, permission: 'action.key' }}
  secondaryAction={{ label: '导出', icon: Download, onClick: () => {} }}
/>
```

---

## 七、主题与样式

### 7.1 CSS 变量

深色主题变量定义在 `src/index.css`:

```css
:root {
  --dg-bg-primary: #0d1117;      /* 主背景 */
  --dg-bg-secondary: #161b22;     /* 卡片背景 */
  --dg-bg-tertiary: #21262d;      /* 输入框/标签背景 */
  --dg-bg-hover: #1c2128;         /* hover 状态 */
  --dg-border: #30363d;           /* 边框 */
  --dg-border-light: #21262d;     /* 浅色边框 */
  --dg-text-primary: #e6edf3;     /* 主要文字 */
  --dg-text-secondary: #8b949e;   /* 次要文字 */
  --dg-text-muted: #484f58;       /* 弱化文字 */
}
```

### 7.2 公共样式类

```css
.dg-card       /* 统一卡片样式 */
.dg-btn-primary   /* 主按钮 */
.dg-btn-secondary /* 次要按钮 */
.dg-input      /* 输入框样式 */
.dg-label      /* 标签样式 */
```

---

## 八、后续优化建议

### 8.1 后端集成（高优先级）

| 模块 | 接口需求 |
|------|----------|
| 用户认证 | `/api/auth/login`, `/api/auth/logout` |
| 仪表盘 | `/api/dashboard/stats`, `/api/dashboard/trends` |
| 实例管理 | `/api/instances/*` CRUD |
| 工单 | `/api/tickets/*` CRUD + 审批/执行/回滚 |
| 查询审计 | `/api/queries/*` 执行 + 日志 |
| 用户管理 | `/api/users/*` CRUD |
| 角色管理 | `/api/roles/*` CRUD |
| 配置平台 | `/api/config/*` 读写 |

### 8.2 功能优化

- [ ] **SQL 编辑器升级**: 集成 Monaco Editor 替代 textarea，支持语法高亮、自动补全、错误提示
- [ ] **实时通知**: WebSocket 推送工单状态变更、审批提醒
- [ ] **数据同步**: LDAP 用户自动同步定时任务
- [ ] **报表导出**: PDF/Excel 格式的审计报告生成
- [ ] **SQL 变更影响分析**: 自动计算影响行数、预估执行时间
- [ ] **数据库对比**: 结构对比、数据对比功能
- [ ] **备份管理**: 定时备份、备份恢复、备份策略配置
- [ ] **操作审计**: 管理员操作日志，防止越权

### 8.3 性能优化

- [ ] **虚拟滚动**: 大数据量表格使用虚拟滚动
- [ ] **懒加载**: 路由级 Code Splitting
- [ ] **数据缓存**: React Query / SWR 管理服务端状态
- [ ] **图表优化**: 大数据量图表采样渲染

### 8.4 安全加固

- [ ] **前端加密**: 敏感配置字段前端加密传输
- [ ] **防 XSS**: 所有用户输入转义输出
- [ ] **防 CSRF**: 请求头携带 Token
- [ ] **会话管理**: JWT Token 自动刷新、过期提醒

---

## 九、API 接口规范（建议）

### 9.1 统一响应格式

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": 1705315200000
}
```

### 9.2 分页参数

```
GET /api/tickets?page=1&size=10&status=pending&sort=-createTime
```

### 9.3 权限相关 Header

```
Authorization: Bearer <JWT_TOKEN>
X-User-Role: admin
```

---

## 十、部署说明

### 10.1 构建

```bash
cd /mnt/agents/output/app
npm run build
```

输出目录: `dist/`

### 10.2 环境变量

```env
# .env.production
VITE_API_BASE_URL=https://api.dataguard.company.com
VITE_APP_TITLE=DataGuard
VITE_VERSION=2.0.0
```

---

*文档维护: 开发团队*  
*如有问题请联系 DBA 团队或提交 Issue*