opsxsql/frontend/DEVELOPMENT.md

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天）
• 状态分布饼图
• 工单表格列表（含详情弹窗）

关键代码:

// pages/Dashboard.tsx
// 使用 recharts 绘制图表，数据来自 /dashboard/stats 接口

---

3.2 数据库实例管理 (InstancePage)

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

功能说明:

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

关键数据结构:

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 小时内可一键回滚

关键数据结构:

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

// 获取用户信息和权限方法
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. 使用条件渲染控制按钮/操作的显示

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

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

6.3 使用 PageHeader 组件

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:

: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 公共样式类

.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 统一响应格式

{
  "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 构建

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

输出目录: dist/

10.2 环境变量

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

---

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