Initial commit: SQL audit platform v0.1.0

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>
2026-05-22 11:11:57 +08:00
commit 439155c92e
@@ -0,0 +1,547 @@
+# 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*