0 Fork 0

Files

T

Logan.Li a213d08e31 chore(frontend): purge dead code per guide red line

- delete 4 dead pages (~2300 lines): Home, ConfigPlatformPage,
  DataDictionaryPage, NotificationsPage (kept the live NotificationPage)
- delete 52 unused shadcn ui components (keep button/card/dialog in use;
  re-generate via shadcn CLI when needed)
- delete App.css, SkeletonCard, empty shared/ and features engine dirs
- remove dead theme blocks (midnight-purple / orange-vitality) from index.css
- uninstall ~40 dead deps (echarts, sonner, next-themes, zod,
  react-hook-form, unused radix packages, cmdk, vaul, ...)
- fix DEVELOPMENT.md drift: mock layer section rewritten to real API layer,
  permission docs now point to menu.ts single source

2026-10-26 17:23:24 +08:00

15 KiB

Raw Blame History

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 角色切换演示

侧边栏底部提供角色切换按钮（仅演示用途），切换后：

自动过滤菜单项
检查当前页面是否有权限，无权限则跳转到仪表盘
页面内按钮按新角色重新渲染

五、数据层

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

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

六、开发规范

6.1 新增页面步骤

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

6.2 新增操作权限

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

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

15 KiB Raw Blame History Unescape Escape

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

一、项目概述

核心设计理念

二、技术栈

目录结构

三、核心功能模块

3.1 仪表盘 (Dashboard)

3.2 数据库实例管理 (InstancePage)

3.3 数据变更工单 (TicketsPage)

3.4 查询审计 (QueriesPage)

3.5 角色管理 (RolesPage)

3.6 用户管理 (UsersPage)

3.7 审批流程配置 (WorkflowPage)

3.8 自动任务 (AutoTaskPage)

3.9 配置平台 (ConfigPlatformPage)

3.9.1 消息推送

3.9.2 LDAP 设置

3.9.3 查询限制

3.9.4 工单提交规则

3.9.5 DDL 拦截规则

四、权限系统

4.1 权限架构

4.2 权限 Hook

4.3 权限配置表

4.4 角色切换演示

五、数据层

六、开发规范

6.1 新增页面步骤

6.2 新增操作权限

6.3 使用 PageHeader 组件

七、主题与样式

7.1 CSS 变量

7.2 公共样式类

八、后续优化建议

8.1 后端集成（高优先级）

8.2 功能优化

8.3 性能优化

8.4 安全加固

九、API 接口规范（建议）

9.1 统一响应格式

9.2 分页参数

9.3 权限相关 Header

十、部署说明

10.1 构建

10.2 环境变量

15 KiB

Raw Blame History

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