docs: 添加 README.md 项目文档

2026-05-29 23:26:11 +08:00
1 parent 5212aaac54
commit d66ce3d5c9
@@ -0,0 +1,169 @@
+# OpsxSQL — SQL 审核与数据变更审批平台
+
+<p align="center">
+  <strong>安全、高效的企业级数据库自助查询 + 数据变更审批平台</strong>
+</p>
+
+---
+
+## 项目简介
+
+OpsxSQL 是一个面向 DBA 和开发人员的数据库管理平台，核心定位：
+
+- **自助查询** — 支持 MySQL / PostgreSQL / Redis / MongoDB 多类型数据库的在线查询
+- **数据变更审批流** — SQL 变更工单提交 → 审核 → 执行的完整审批流程
+- **SQL 审核** — 内置 26+ 条审核规则，覆盖语法、性能、安全、命名规范等维度
+- **实例管理** — 统一管理多种数据库实例，支持分组和标签
+
+## 技术栈
+
+| 层级 | 技术 |
+|------|------|
+| 后端 | Go 1.26 + Gin + GORM + SQLite |
+| 前端 | React 18 + TypeScript + Vite + Tailwind CSS + shadcn/ui |
+| 认证 | JWT + LDAP 集成 |
+| 数据库 | SQLite（零依赖，开箱即用） |
+
+## 功能模块
+
+### 🗄️ 实例管理
+- MySQL / PostgreSQL / Redis / MongoDB 实例注册与连接测试
+- 实例分组管理
+- 库表结构浏览（字段、索引详情）
+
+### 📝 自助查询
+- 在线 SQL 编辑器（CodeMirror）
+- 语法高亮 + 自动补全
+- 查询历史记录（上限 500 条/用户）
+- 慢查询日志分析
+
+### ✅ 工单审批
+- SQL 变更工单创建（支持 DDL / DML）
+- 多级审批流程（developer → dba → admin）
+- 工单状态追踪与通知
+- 执行结果确认
+
+### 🔍 SQL 审核
+- 26 条内置审核规则（MySQL 11 / PostgreSQL 7 / Redis 4 / MongoDB 4）
+- 规则类型：syntax / performance / safety / security / naming / DDL / DML / DQL / DCL
+- 规则启用/禁用 + 自定义配置
+
+### 👥 用户与权限
+- 四级角色：admin / dba / developer / auditor
+- LDAP 集成登录
+- 基于角色的数据隔离
+
+### 🔔 通知渠道
+- 飞书 Webhook 通知
+- 钉钉 Webhook 通知
+- 工单状态变更自动推送
+
+### 📊 其他
+- Dashboard 运营数据总览
+- 审计日志
+- 公告管理
+- 系统设置
+
+## 项目结构
+
+```
+sql-platform/
+├── backend/                  # Go 后端
+│   ├── cmd/server/           # 入口 + seed
+│   │   ├── main.go           # 启动入口
+│   │   └── seed.go           # 默认数据初始化
+│   ├── internal/
+│   │   ├── handler/          # 请求处理器
+│   │   ├── middleware/        # 中间件（认证/权限/日志）
+│   │   ├── model/            # 数据模型
+│   │   └── service/          # 业务逻辑
+│   ├── config/               # 配置管理
+│   └── router/               # 路由注册
+├── frontend/                 # React 前端
+│   └── src/
+│       ├── api/              # API 请求封装
+│       ├── components/       # 通用组件
+│       │   └── ui/           # shadcn/ui 组件
+│       ├── pages/            # 页面组件（27 个）
+│       └── lib/              # 工具函数
+├── tests/                    # 集成测试
+├── run.sh                    # 启动/停止脚本
+└── docker-compose.yml        # Docker 部署
+```
+
+## 快速开始
+
+### 前置要求
+
+- Go 1.26+
+- Node.js 18+
+- npm 或 yarn
+
+### 启动
+
+```bash
+# 克隆项目
+git clone https://gitee.com/opsx-tools/opsxsql.git
+cd opsxsql
+
+# 编译后端
+cd backend
+go build -o sql-platform ./cmd/server/
+
+# 启动（前后端一键启动）
+cd ..
+bash run.sh restart
+```
+
+后端运行在 **http://localhost:9000**，前端运行在 **http://localhost:5173**
+
+### 默认账号
+
+首次启动自动初始化以下账号（密码均为 `admin123`）：
+
+| 用户名 | 角色 | 说明 |
+|--------|------|------|
+| admin | admin | 超级管理员 |
+| dba | dba | 数据库管理员 |
+| auditor | auditor | 审计员（只读） |
+| developer | developer | 开发者 |
+
+### 测试
+
+```bash
+# 后端集成测试
+cd tests
+pip install pytest pytest-asyncio httpx
+pytest -v
+
+# 前端类型检查
+cd frontend
+npx tsc --noEmit
+```
+
+## 版本历史
+
+| 版本 | 说明 |
+|------|------|
+| v0.4.0 | 弹框架构重构 + 审核规则 API + LDAP 配置 + 全量 seed |
+| v0.3.2 | 通知渠道对接 + TicketCreatePage 重写 + 默认用户初始化 |
+| v0.3.1 | Go 后端迁移 + 工单审批流程 + 实例管理 |
+| v0.2.0 | 前端 UI 重构 + shadcn/ui 组件化 |
+| v0.1.0 | 项目初始化 + 基础 CRUD |
+
+## 代码统计
+
+- 后端 Go：29 文件，8,000+ 行
+- 前端 TypeScript：131 文件，27,000+ 行
+- 集成测试：21 文件，1,100+ 行
+- **总计 36,000+ 行**
+
+## 许可证
+
+MIT License
+
+---
+
+<p align="center">
+  <a href="https://gitee.com/opsx-tools/opsxsql">Gitee 仓库</a>
+</p>