opsxsql/docs/AUDIT_REPORT.md

SQL-Platform-Pro 全面架构审计报告

生成时间: 2026-05-24
项目路径: ~/devops/sql-platform
Git 总提交数: 56

---

1. 项目结构概览

1.1 技术栈

层级	技术
前端框架	React 19 + TypeScript 5.9 + Vite 7
UI 组件库	Radix UI + Tailwind CSS (shadcn/ui 风格)
后端框架	FastAPI + SQLAlchemy 2 (异步)
数据库	SQLite (开发) / 可切换 MySQL/PostgreSQL
多数据库支持	MySQL (aiomysql), PostgreSQL (asyncpg), MongoDB (motor), Redis (redis)
容器化	Docker Compose + Dockerfile (前后端)
数据库迁移	Alembic

1.2 目录结构

sql-platform/
├── backend/                    # Python FastAPI 后端
│   ├── app/
│   │   ├── api/v1/endpoints/   # 29 个 API 端点文件
│   │   ├── core/               # 配置/安全/数据库/权限
│   │   ├── dependencies/       # 依赖注入
│   │   ├── models/             # 16 个 ORM 模型
│   │   ├── schemas/            # 17 个 Pydantic Schema
│   │   ├── services/           # 31 个业务服务
│   │   └── utils/              # 工具函数
│   ├── alembic/                # 数据库迁移
│   ├── tests/                  # 46 个测试文件
│   ├── venv/                   # Python 虚拟环境
│   └── requirements.txt
├── frontend/                   # React 前端
│   ├── src/
│   │   ├── api/               # 15 个 API 模块
│   │   ├── components/        # 9 个自定义组件 + 50 个 UI 组件
│   │   ├── hooks/             # 5 个自定义 Hooks
│   │   ├── pages/             # 26 个页面
│   │   ├── lib/               # 工具函数/常量
│   │   ├── constants/         # 菜单常量
│   │   └── types/             # TypeScript 类型定义
│   ├── dist/                   # 构建产物
│   ├── public/                 # 静态资源 (DB logos)
│   └── package.json
├── docker-compose.yml
├── run.sh / run.bat
└── 文档: ROADMAP.md, RELEASE_NOTES.md, TDD_PLAN.md 等

1.3 源代码规模

指标	数值
源文件总数 (排除 dist/venv/node_modules/git)	326
后端 Python 总行数	47,003
前端 TS/TSX 总行数	23,486
项目总代码行数	~70,489

---

2. 后端模型统计 (16 个模型)

模型文件	类名	主要字段数	说明
user.py	User	10	id, username, display_name, email, phone, hashed_password, role, is_active, last_login, timestamps
instance.py	Instance	17	id, name, db_type, host, port, username, password, database, env, description, status, version, access_mode, workflow_id, excluded_databases, mask_fields, group_id
instance_group.py	InstanceGroup	9	id, name, description, db_type, permissions, access_type, allowed_databases, is_active, timestamps
ticket.py	Ticket	17	id, ticket_no, title, db_type, instance_id, target_database, sql_content, rollback_sql, status, priority, applicant_id, approver_id, reason, audit_result, execute_result, timestamps
workflow.py	WorkflowDefinition	6	id, name, description, category, is_default, is_active, timestamps
workflow.py	WorkflowVersion	8	id, workflow_id, version_number, version_name, is_active, steps_snapshot, flow_config_snapshot, change_summary
workflow.py	WorkflowStep	13	id, workflow_id, step_number, name, step_type, approver_role, approver_ids, is_required, timeout_hours, auto_approve_on_timeout, conditions
workflow.py	TicketApproval	15	id, ticket_id, workflow_id, step_number, step_type, approver_id, actual_approver_id, action, comment, transfer, timestamps
workflow.py	WorkflowExecutionLog	9	id, workflow_id, ticket_id, step_id, event_type, actor_id, context_data, timestamp
audit_log.py	AuditLog	17	id, user_id, username, action, target_type, target_id, detail, db_type, database_name, execution_time_ms, rows_affected, result_status, query_content, ip_address
audit_rule.py	AuditRule	10	id, name, description, rule_type, severity, db_type, pattern, value, is_enabled, message
query_history.py	QueryHistory	14	id, user_id, username, instance_id, db_type, database_name, query_content, query_type, execution_time_ms, result_rows, is_success, is_favorite
query_history.py	QuickQueryModel	12	id, name, description, query_content, db_type, database_pattern, is_shared, created_by, usage_count
scheduled_task.py	ScheduledTask	15	id, name, task_sql_type, instance_id, target_db, sql_content, cron_expression, is_enabled, run_count, next_run_at
scheduled_task.py	ScheduledTaskLog	8	id, task_id, status, affected_rows, duration_ms, error_message, timestamps
announcement.py	Announcement	6	id, title, content, is_published, published_at, timestamps
backup.py	Backup	9	id, instance_id, title, database, filename, size_bytes, status, created_by
masking_rule.py	MaskingRule	9	id, instance_id, database, table_name, column_name, mask_type, mask_config
notification.py	NotificationChannel	6	id, name, channel_type, config, is_enabled
notification_template.py	NotificationTemplate	7	id, name, event_type, channel_type, title_template, body_template
ldap_config.py	LdapConfig	9	id, ldap_host, ldap_port, use_ldaps, admin_dn, admin_password, search_filter, base_dn
schema_revision.py	SchemaRevision	8	id, instance_id, database, revision, ddl_content, checksum, applied_by, status
system_setting.py	SystemSetting	8	id, key, value, value_type, group, label, description, default_value, sort_order

模型总计: 22 个类 (16 个文件), ~110+ 字段定义

---

3. API 端点统计 (29 个文件, 146 条路由)

端点文件	路由数	行数	功能说明
ticket.py	11	1,073	SQL 工单全生命周期管理
redis.py	11	275	Redis 连接/查询/Key 管理
instance.py	10	295	数据库实例 CRUD
instance_detail.py	10	348	实例详情 (表/字段/索引)
instance_group.py	10	437	权限组管理
audit_rule.py	9	206	审核规则管理
scheduled_task.py	8	287	定时任务调度
workflow.py	7	273	审批流定义/版本/步骤
mongo.py	6	256	MongoDB 查询/集合浏览
query_history.py	6	111	查询历史/快速查询
sql_assistant.py	6	182	AI SQL 助手
masking_rule.py	5	337	数据脱敏规则
notification.py	5	153	通知渠道/模板
user.py	5	116	用户管理
db_types.py	4	266	多数据库类型支持
dictionary.py	4	70	数据字典
settings.py	4	162	系统设置
announcement.py	4	93	公告管理
auth.py	3	58	认证 (登录/LDAP)
backup.py	3	62	数据库备份
ldap_config.py	3	138	LDAP 配置
pool.py	3	64	连接池管理
schema_drift.py	3	85	Schema 漂移检测
query.py	2	251	SQL 查询执行
rollback.py	2	176	回滚 SQL 生成
audit.py	1	27	审计日志查询
dashboard.py	1	62	仪表盘数据
impact.py	1	33	影响分析
合计	146	5,896

---

4. 前端页面统计 (26 个页面, 14,008 行)

页面文件	行数	功能说明
InstancePage.tsx	1,452	数据库实例管理 (最大页面)
TicketCreatePage.tsx	1,192	创建 SQL 工单
QueriesPage.tsx	896	SQL 查询编辑器
UsersPage.tsx	877	用户管理
Dashboard.tsx	825	仪表盘
WorkflowPage.tsx	808	审批流程管理
TicketDetailPage.tsx	808	工单详情
TicketsPage.tsx	742	工单列表
ConfigPlatformPage.tsx	700	平台配置
DataDictionaryPage.tsx	688	数据字典
AuditRulesPage.tsx	596	审核规则
AuditLogsPage.tsx	555	审计日志
InstanceGroupPage.tsx	465	权限组管理
NotificationPage.tsx	456	通知管理
RolesPage.tsx	417	角色权限
MongoDBDetailPage.tsx	386	MongoDB 浏览
AnnouncementPage.tsx	349	公告管理
LdapConfigPage.tsx	335	LDAP 配置
RedisDetailPage.tsx	309	Redis 浏览
AutoTaskPage.tsx	293	定时任务
InstanceDetailPage.tsx	260	实例详情
PlatformConfigPage.tsx	209	平台配置页
NotificationsPage.tsx	180	通知列表
LoginPage.tsx	134	登录页
SettingsPage.tsx	56	设置页
Home.tsx	20	首页占位

自定义组件 (9 个, 1,706 行)

组件文件	行数	功能说明
SchemaSidebar.tsx	614	数据库 Schema 树形浏览
SqlEditor.tsx	431	CodeMirror SQL 编辑器
EditInstanceDialog.tsx	276	实例编辑对话框
Layout.tsx	126	全局布局/侧边栏
SkeletonCard.tsx	65	骨架屏加载
ConfirmDialog.tsx	59	确认对话框
FormDialog.tsx	53	通用表单对话框
PageHeader.tsx	55	页面头部
EmptyState.tsx	27	空状态占位

另外有 50 个 shadcn/ui 基础组件 (components/ui/)。

前端 API 模块 (15 个)

auth.ts, dashboard.ts, dbTypes.ts, dictionary.ts, instance.ts, instanceDetail.ts, instanceGroup.ts, mongo.ts, notification.ts, query.ts, redis.ts, request.ts, ticket.ts, user.ts, workflow.ts

---

5. 后端服务统计 (31 个服务文件, 22,043 行)

服务文件	行数	功能说明
mysql_audit_rules.py	2,199	MySQL 审核规则库
redis_audit_rules.py	1,869	Redis 审核规则库
audit_engine_v2.py	1,699	审核引擎 V2
ticket_executor.py	1,688	工单执行器
mongodb_audit_rules.py	1,638	MongoDB 审核规则库
workflow_engine.py	1,319	工作流引擎
postgres_audit_rules.py	1,289	PostgreSQL 审核规则库
query_service.py	1,261	查询服务
audit_engine.py	790	审核引擎 V1
mongo_connector.py	780	MongoDB 连接器
explain_service.py	789	EXPLAIN 执行计划分析
audit_rule_seeds.py	637	审核规则种子数据
rollback_generator.py	836	回滚 SQL 生成
data_masker.py	401	数据脱敏
query_history_service.py	451	查询历史服务
backup_executor.py	351	备份执行器
db_connector.py	345	数据库连接器
sql_assistant.py	342	AI SQL 助手
impact_analyzer.py	315	影响分析
schema_drift_detector.py	314	Schema 漂移检测
redis_validator.py	280	Redis 命令验证
role_permissions.py	279	角色/权限服务
redis_connector.py	269	Redis 连接器
sql_analyzer.py	255	SQL 分析器
dictionary_service.py	240	数据字典服务
notification_sender.py	238	通知发送
connection_pool.py	228	连接池管理
audit_rule_seeds_v2.py	500	审核规则种子 V2
instance_service.py	134	实例服务
settings_seeds.py	136	设置种子数据
workflow_seeds.py	93	工作流种子数据
audit_log_service.py	78	审计日志服务

---

6. 测试统计 (46 个测试文件, 1,075 个测试)

测试总数: 1,075 个测试用例

Top 10 测试文件

测试文件	测试数	覆盖领域
test_query_service.py	75	查询服务
test_ticket_executor.py	67	工单执行器
test_audit_engine_v2.py	65	审核引擎 V2
test_query_history_service.py	47	查询历史服务
test_masking_rule.py	45	脱敏规则
test_explain.py	40	EXPLAIN 分析
test_sql_assistant.py	37	SQL 助手
test_notification.py	35	通知系统
test_user.py	34	用户管理
test_sql_analyzer.py	31	SQL 分析器

测试分布

测试数区间	文件数
50+	3
30-49	5
20-29	6
15-19	7
10-14	12
5-9	8
<5	5

---

7. Git 历史 (56 次提交)

最近 30 次提交

9813741 feat: SchemaSidebar 加宽 + Redis key 点击插入查询命令到编辑器
2f76482 refactor: Redis 树取长补短 — 单列内嵌详情 + 类型颜色图标 + 左竖线层级
327ab33 feat: Redis Keys 目录树结构浏览 — 按 : 分隔符构建层级树
ed13243 feat: 多数据库类型支持 — Redis/MongoDB/PostgreSQL 数据库+表浏览
fb16723 fix: TicketCreatePage 去掉优先级选择器+修复Redis实例切换后database残留触发MySQL tables请求
08f0f88 feat: 工单列表重设计+权限组实例过滤+通知修复
88d064e feat: 权限组重构为一组双Transfer(只读+写入) + 用户管理加权限组关联
39d9600 refactor: 权限组从一组一类型改为一组同时包含readonly+write实例
40868c6 feat: 权限组创建改为双Transfer同时配置只读+写入
128de64 feat: 数据源编辑加排除数据库+脱敏字段+审批流关联; 权限组Transfer改为选择实例
4111e1e refactor: 权限组简化为2组(readonly/write) + Transfer穿梭框选择数据库
8161bcf feat: 权限组简化 + 工单撤销按钮
b80d383 refactor: 重构权限组系统 — 新增 access_type/allowed_databases 字段 + 角色权限服务
35a014e feat: 查询页增强 + 权限体系优化
aa2e26c feat: 查询页目标数据库改为下拉选择
e6ab5bf feat: SchemaSidebar 三级树结构 — 库→表→字段 (类似 Navicat)
6a8c4d9 feat: Redis/MySQL 加载骨架屏 loading 效果
ca99f0e fix: 工单提交422错误处理 + SQL模板占位符校验
0aa4595 fix: 查询模板占位符替换 + _auto_add_limit 跳过非SELECT语句 + 默认用户密码修正
0fb947d feat: TicketCreatePage tab化 + SchemaSidebar + Redis快速搜索 + Dashboard导航修复
8471f36 init
c7fccf9 feat: 三大核心功能完成 — query_history持久化 + EXPLAIN真实解析 + Dashboard修复
1fcb984 fix: Dashboard 页面崩溃修复 + 真实 API 数据对接
8b921c6 refactor: mock清理+安全配置+通用组件+菜单优化
ec3a03c docs: 添加 v0.1.0 Release Notes
4ac2528 fix: 审核引擎优化 + 执行结果结构化展示
9f56e86 fix: 移除所有弹框遮罩层点击关闭 — 防止输入时误触关闭
47f077c test: instance端点扩展测试 (8→17) + 数据库列补齐修复
305bbb1 test: P2测试覆盖 — user/pool/schema_drift端点 43个新测试 (895→1017全通过)
b39c426 fix: merge后14个测试修复+前端TS编译修复 - 895/895通过+前端零错误

开发趋势

• 高频迭代: 近期大量 feat/refactor 提交，围绕权限体系、多数据库支持、UI 优化
• 质量关注: 测试修复、编译修复、错误处理等 fix 提交占比约 30%
• 最新方向: Schema 浏览增强 (Redis 目录树、多数据库类型支持)

---

8. 依赖统计

后端依赖 (requirements.txt: 20 个包)

包名	版本	用途
fastapi	>=0.104.0	Web 框架
uvicorn[standard]	>=0.24.0	ASGI 服务器
sqlalchemy[asyncio]	>=2.0.23	异步 ORM
aiosqlite	>=0.19.0	SQLite 异步驱动
pydantic	>=2.5.0	数据校验
pydantic-settings	>=2.1.0	配置管理
python-jose[cryptography]	>=3.3.0	JWT 令牌
passlib[bcrypt]	>=1.7.4	密码哈希
python-multipart	>=0.0.6	文件上传
cryptography	>=41.0.0	加密库
sqlparse	>=0.4.4	SQL 解析
alembic	>=1.13.0	数据库迁移
aiomysql	>=0.2.0	MySQL 异步驱动
asyncpg	>=0.29.0	PostgreSQL 异步驱动
motor	>=3.3.0	MongoDB 异步驱动
pymongo	>=4.6.0	MongoDB 驱动
httpx	>=0.25.0	HTTP 客户端
aiosmtplib	>=3.0.0	邮件发送
redis	>=5.0.0	Redis 客户端

前端依赖

dependencies: 53 个包 (含 Radix UI 全家桶 28 个, CodeMirror 9 个, ECharts/Recharts 等)
devDependencies: 17 个包 (Vite 7, TypeScript 5.9, ESLint, Tailwind CSS 等)

---

9. 数据库状态 (SQLite)

表统计: 28 张表

表名	行数	说明
audit_rules	117	审核规则 (预置种子数据)
audit_logs	69	审计日志
system_settings	13	系统设置项
workflow_steps	28	工作流步骤
workflow_definitions	12	工作流定义
ticket_approvals	12	工单审批记录
query_histories	24	查询历史
tickets	6	SQL 工单
users	6	用户
instances	4	数据库实例
user_groups	3	用户组
instance_group_members	4	权限组成员
instance_groups	1	权限组
notification_channels	2	通知渠道
announcements	1	公告
alembic_version	1	迁移版本
backups	0	备份记录
masking_rules	0	脱敏规则
ldap_config	0	LDAP 配置
notification_templates	0	通知模板
query_templates	0	查询模板
quick_queries	0	快速查询
scheduled_tasks	0	定时任务
scheduled_task_logs	0	定时任务日志
schema_revisions	0	Schema 版本
slow_logs	0	慢查询日志
workflow_execution_logs	0	工作流执行日志
workflow_versions	0	工作流版本

数据总量: 28 张表, ~357 行数据

---

10. 功能模块完整度评估

功能模块	后端	前端	测试	状态
用户认证 (JWT/LDAP)	✅	✅	✅ (8+34)	🟢 完整
数据库实例管理	✅	✅	✅ (17+16+6)	🟢 完整
SQL 查询执行	✅	✅	✅ (75+22)	🟢 完整
工单管理	✅	✅	✅ (67+13)	🟢 完整
审批工作流	✅	✅	✅ (27)	🟢 完整
审核引擎 (V1+V2)	✅	✅	✅ (23+65)	🟢 完整
审核规则	✅	✅	✅ (22+12+13)	🟢 完整
数据脱敏	✅	✅	✅ (45)	🟢 完整
仪表盘	✅	✅	✅ (12)	🟢 完整
Redis 管理	✅	✅	✅ (14)	🟢 完整
MongoDB 管理	✅	✅	✅ (30)	🟢 完整
Schema 浏览	✅	✅	✅ (24+17+13+9)	🟢 完整
查询历史	✅	✅	✅ (47)	🟢 完整
备份恢复	✅	❌*	✅ (22)	🟡 后端完整，前端无独立页面
定时任务	✅	✅	-	🟡 无专项测试
公告管理	✅	✅	✅ (24)	🟢 完整
通知系统	✅	✅	✅ (35)	🟢 完整
数据字典	✅	✅	✅ (7)	🟢 完整
回滚 SQL	✅	✅	✅ (10)	🟢 完整
EXPLAIN 分析	✅	✅	✅ (40)	🟢 完整
SQL 助手 (AI)	✅	✅	✅ (37)	🟢 完整
权限组	✅	✅	✅ (20+21+14+16)	🟢 完整
系统设置	✅	✅	✅ (18+10)	🟢 完整
LDAP 配置	✅	✅	✅ (18)	🟢 完整
Schema 漂移	✅	✅	✅ (24+13+9)	🟢 完整
连接池	✅	-	✅ (21+12)	🟡 基础设施，无独立前端

---

11. 总结

项目规模

• ~70,500 行源代码 (后端 47K + 前端 23.5K)
• 146 条 API 路由，覆盖 29 个功能域
• 1,075 个测试用例，46 个测试文件
• 22 个 ORM 模型，28 张数据库表
• 26 个前端页面，9 个自定义组件

项目成熟度: ⭐⭐⭐⭐ (高)

优势:

1. 全栈 TDD 驱动开发，1,075 个测试确保质量
2. 多数据库完整支持 (MySQL/PostgreSQL/MongoDB/Redis)
3. 企业级功能完备 (审批流、审核引擎、权限组、数据脱敏)
4. 代码组织清晰，分层合理 (endpoint → service → model)

待改进:

1. 部分大文件需要拆分 (InstancePage 1,452行, ticket.py 1,073行)
2. 审核规则库占用大量代码 (MySQL 2,199行, Redis 1,869行)
3. 备份功能缺少独立前端页面
4. 14 张表数据为空 (部分功能尚未使用)
5. motor 在 requirements.txt 中重复出现