loganandClaude Opus 4.7
439155c92e
FastAPI backend with auth, user, instance, ticket, query, dashboard APIs. React + TypeScript frontend with mock data UI (10 pages). SQLite + async SQLAlchemy, JWT auth, role-based access control. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
548 lines
15 KiB
Markdown
548 lines
15 KiB
Markdown
# 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 # 公告管理
|
||
│ ├── ConfigPlatformPage.tsx # 配置平台
|
||
│ └── LoginPage.tsx # 登录
|
||
├── hooks/ # 自定义 Hooks
|
||
│ └── useAuth.tsx # 权限上下文 + useAuth + useActionPermission
|
||
├── lib/ # 工具库
|
||
│ ├── mock.ts # 全量 Mock 数据
|
||
│ └── utils.ts # 工具函数
|
||
├── types/ # TypeScript 类型定义
|
||
│ └── index.ts # 全局类型
|
||
├── App.tsx # 根组件（路由 + 路由守卫）
|
||
├── index.css # 全局样式 + 深色主题变量
|
||
└── main.tsx # 入口文件
|
||
```
|
||
|
||
---
|
||
|
||
## 三、核心功能模块
|
||
|
||
### 3.1 仪表盘 (Dashboard)
|
||
|
||
**路由**: `/dashboard`
|
||
**权限**: 全部角色
|
||
|
||
**功能说明**:
|
||
- 工单统计卡片（总工单 / 待审批 / 本月 / 进行中）
|
||
- 审核规则统计卡片
|
||
- 查询统计卡片
|
||
- 工单趋势折线图（30天）
|
||
- 状态分布饼图
|
||
- 工单表格列表（含详情弹窗）
|
||
|
||
**关键代码**:
|
||
```tsx
|
||
// pages/Dashboard.tsx
|
||
// 使用 recharts 绘制图表，工单表格复用 tickets mock 数据
|
||
```
|
||
|
||
---
|
||
|
||
### 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 权限配置表
|
||
|
||
路由权限：`useAuth.tsx` 中 `routePermissionMap`
|
||
操作权限：`useAuth.tsx` 中 `actionPermissionMap`
|
||
菜单权限：`lib/mock.ts` 中 `menuItems[*].roles`
|
||
|
||
### 4.4 角色切换演示
|
||
|
||
侧边栏底部提供角色切换按钮（仅演示用途），切换后：
|
||
1. 自动过滤菜单项
|
||
2. 检查当前页面是否有权限，无权限则跳转到仪表盘
|
||
3. 页面内按钮按新角色重新渲染
|
||
|
||
---
|
||
|
||
## 五、Mock 数据层
|
||
|
||
所有数据存储在 `src/lib/mock.ts`，后端接口就绪后替换为 API 调用即可。
|
||
|
||
**主要数据集合**:
|
||
|
||
| 数据 | 变量名 | 用途 |
|
||
|------|--------|------|
|
||
| 数据库实例 | `dbInstances` | 实例管理 |
|
||
| 工单 | `tickets` | 工单管理 |
|
||
| 查询审计 | `queryAudits` | 查询审计 |
|
||
| 审核规则 | `auditRules` | 审核规则 |
|
||
| 用户 | `users` | 用户管理 |
|
||
| 角色 | `roles` | 角色管理 |
|
||
| 审批流程 | `workflows` | 流程配置 |
|
||
| 菜单 | `menuItems` | 侧边栏菜单 |
|
||
| 当前用户 | `currentUser` | 登录用户 |
|
||
|
||
---
|
||
|
||
## 六、开发规范
|
||
|
||
### 6.1 新增页面步骤
|
||
|
||
1. 在 `src/pages/` 创建页面组件
|
||
2. 在 `src/App.tsx` 添加路由（配置 `routePermissionMap` 权限）
|
||
3. 在 `src/hooks/useAuth.tsx` 的 `routePermissionMap` 中添加路由权限
|
||
4. 在 `src/lib/mock.ts` 的 `menuItems` 中添加菜单项
|
||
5. （如需要）在 `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*
|