easy-data-check · 数据对账平台

企业级数据对账平台:把"来源端"与"目标端"数据按业务主键对齐、逐字段比对,产出差异明细并闭环(调账 / 预警 / 回调 / 已修复)。取数端支持 JDBC(SQL) / HTTP API / Groovy 脚本 三种运行时可配置数据源;

文档导航

文档	面向	内容
docs/项目介绍指南.md	产品 / 业务 / 实施	带真实界面截图的介绍指南：登录→数据源→6 步任务→执行→差异分诊→预警/回调（支付流水 vs 订单演示）
docs/功能介绍与操作指南.md	运维 / 业务 / 集成方	完整使用手册:核心概念、操作指南(数据源→任务→执行→差异分诊→预警/回调→用户/日志)、引擎原理、数据模型、REST API、排错、路由速查
docs/skills/easydata-operator-SKILL.md	AI / 集成方	AI 操作 skill:仅凭平台地址 + JWT token,AI 即可通过 REST API 自动配置、编辑、执行对账
`docs/superpowers/specs/` / `plans/`	设计者 / 贡献者	历史设计 spec 与实施计划(数据源分表重构、引擎内联、预警/回调/重试、分页统一等)

下文仅给出最精简的技术栈 / 工程结构 / 功能总览 / 快速开始 / 验证清单 —— 详细操作与 API 见上方手册。

技术栈

后端:JDK 11 + Spring Boot 2.7.18 + MyBatis-Plus + Spring Security + JWT + MySQL 8
前端:Vue 3 + Element Plus + Vite + Pinia + Vue Router + Axios + ECharts
引擎:data-check 源码内联至 com.openquartz.easydatacheck.engine(中度清理:去 Redis/Excel-File-loader/Database/Incremental 处理器及孤儿适配器 + jedis+easyexcel+poi 依赖;Lombok 1.18.30 兼容 JDK11)
取数:JDBC JdbcFetcher / OkHttp HttpFetcher / Groovy JSR-223 GroovyFetcher(含辅助 JDBC)
其他:Hutool、EasyExcel(结果导出)、AES 密码加密

工程结构

easy-data-check/
├── pom.xml                                # 父 POM (JDK11, Spring Boot BOM)
├── README.md                               # 本文件
├── docs/
│   ├── skills/easydata-operator-SKILL.md   # AI 操作 skill
│   ├── 功能介绍与操作指南.md                # 完整操作指南
│   └── superpowers/                        # 设计 spec 与实施计划
├── easy-data-check-backend/                # 后端(Spring Boot,:8080/api)
│   └── src/main/java/com/openquartz/easydatacheck/
│       ├── common/       统一响应(Result/PageResult)/异常/枚举/模型(DataSourceConfig/DataSetConfig/FieldMapping/PageConfig)
│       ├── config/       Security / MybatisPlus / WebMvc / Jackson / PlatformProperties
│       ├── security/     JWT(JwtUtil + JwtAuthFilter + 无状态鉴权)
│       ├── user/         用户 / 角色 / 认证(RBAC)
│       ├── datasource/   数据源按类型分表(JDBC/HTTP/Groovy) + 三类取数器 + AES 加密
│       ├── task/         对账任务(携带源/目标数据源 id+type)
│       ├── execute/      执行编排核心(Orchestrator / Loader / Paging / Aggregator / Persister)
│       │                  + PostExecutionHandler(预警/回调/重试-已修复)
│       ├── result/       结果查询 / 调账 / 标记已修复 / 导出 / 仪表盘
│       ├── alert/        预警配置运行时(模板/类型/地址/配置 + 触发/渲染/Sender)
│       ├── callback/     差异回调运行时(SQL/Groovy/HTTP 执行器 + 日志)
│       ├── log/          操作日志(@OperationLog AOP,SpEL)
│       └── engine/       对账引擎(源码内联自 data-check)
└── easy-data-check-ui/                     # 前端(Vue 3,:5173,代理 /api → :8080)

数据源存储(按类型分表)

公共列:id / name / remark / creator / create_time / update_time / deleted。类型特定列:

表	特定列
`edc_ds_jdbc`	`driver / url / username / password(AES)`
`edc_ds_http`	`base_url / auth_type(NONE/BASIC/BEARER) / username / password / token / connect_timeout_ms / read_timeout_ms / headers_json`
`edc_ds_groovy`	`script / helper_jdbc_data_source_id / timeout_ms`

edc_check_task 携带 source_data_source_type / target_data_source_type,运行时按 id+type 定位表、解析为统一 DataSourceConfig 交给 fetcher(fetcher 零改动)。前端数据源页 JDBC/HTTP/GROOVY 三 Tab 分页。

核心设计:动态取数接入 data-check

平台在引擎的 ResourceLoader(@FunctionalInterface)处接入 — DataSetFetcher(Jdbc/Http/Groovy) → DataSetResourceLoader(把取数结果桥接成 CheckEntry,Map 行,无需编译期实体类) → CheckExecutor(按 processorType 选 Memory/Stream/Parallel) → CheckResultAggregator(多窗口汇总) → ResultPersister(独立事务落库)。

字段映射:fieldMapping.{sourceKeyField, targetKeyField, fields:[{name, sourceField, targetField, ignore}]}把源/目标不同列名对齐到同一"公共比较字段名"。
全量比对:一次 executor.process()。
分页比对(时间窗口 TIME_WINDOW):[start, end]按 pageConfig.windowUnit(DAY/HOUR)切成多子对账,逐窗口一次子对账后汇总。
分页比对(主键范围 KEY_RANGE):仅 源与目标均为 JDBC；配置 pageConfig.keyField + keyPageSize(默认 10000,最小 100)。用户 SQL 须用开区间上界:col >= ${keyStart} AND col < ${keyEnd}；末窗由引擎生成排他后继,保证末键被包含。
时间增量:取数 SQL 用 ${startTime} / ${endTime} 占位符过滤。
执行后置(不干扰执行状态):PostExecutionHandler 在落库后依次:评估预警规则 → 按通道(WEBHOOK/EMAIL)分发(写 edc_alert_log)→ 若 SUCCESS+有差异则执行差异回调(SQL/Groovy/HTTP,写 edc_callback_log)→ 若为 RETRY 且 SUCCESS 则 FixedMarker 自动把"消失的差异"标为 fixed_by=AUTO_RETRY。三段各自 try/catch,绝不向 run() 抛出。

功能模块总览

模块	菜单路径	说明
仪表盘	`仪表盘`	统计卡片 + 差异分布饼图 + 最近执行
数据源	`数据源`(JDBC/HTTP/GROOVY 三 Tab)	CRUD + 动态表单 + 密码 AES + 掩码 + 连通测试
对账任务	`对账任务`(6 步向导)	基本→源/目标数据集→字段映射→比对配置→预警与回调;启用/禁用
执行对账	`执行对账`	手动触发 + 时间范围 + 比对模式;重试 / 中止;状态轮询
对账结果	`对账结果`(/:executionId)	汇总头 + 差异并排(源多/目标多/不一致 + 修复 Tab);调账标记 + 标记已修复;Excel 导出
预警与回调	`预警/预警类型/预警地址/预警配置` + `回调配置`	4 模块 + 触发规则(失败/有差异/超阈值/一致率掉)+ WEBHOOK/EMAIL 通道;按 SQL/Groovy/HTTP 的差异回调
日志与系统	`操作日志` + `用户名/角色管理`	AOP 审计 + RBAC(改密/重置/分配角色)
REST API	base `/api`	整平台 CRUD 开放(`docs/skills/easydata-operator-SKILL.md` 含完整 Capability Map)

快速开始

1. 元数据库(MySQL)

docker run -d --name easy-data-check-mysql \
  -e MYSQL_ROOT_PASSWORD=root -e MYSQL_DATABASE=easy_data_check \
  -p 3306:3306 mysql:8
docker exec -i easy-data-check-mysql mysql -uroot -proot < \
  easy-data-check-backend/src/main/resources/db/schema.sql
# → 修改 application-dev.yml 的数据源连接信息以匹配环境

2. 后端(:8080/api)

mvn -pl easy-data-check-backend spring-boot:run

启动时自动 seed 默认账号 admin / admin123(ADMIN 角色)。

3. 前端(:5173)

cd easy-data-check-ui && npm install && npm run dev

浏览器打开 **http://localhost:5173**,用 admin / admin123 登录。(前端 baseURL/api代理到;5173→`8080。)

端到端使用最短路径

数据源 → 选 Tab(JDBC/HTTP/GROOVY)→ 新增 → 填连接 → 测试连通 → 保存。(密码明文提交,服务端 AES;回读掩码。)
对账任务 → 新建 → 6 步向导(选源/目标数据源 → 按类型配数据集(sql 或 http.{path,method,dataPath,pagination} 或 groovy.params)→ 配字段映射主键与字段 → compareMode=FULL|PAGED、processorType=AUTO|MEMORY|STREAM|PARALLEL + PAGED 时选 TIME_WINDOW 或 KEY_RANGE(后者需双 JDBC + keyField) → 可选挂预警/回调配置)→ 启用。
执行对账 → 选任务 → 填时间范围(TIME_WINDOW/增量必填;KEY_RANGE 按主键切窗)→ 提交 → 轮询(RUNNING → SUCCESS|FAILED|ABORTED)。中止为协作式:窗口循环检查 abort 标志,避免 SUCCESS 覆盖 ABORTED。
对账结果 → 看汇总 + 三类差异表 → 调账标记 / 标记已修复 / 导出 xlsx → 或触发重试对账(二次成功后自动把消失差异标 AUTO_RETRY)。

关键配置

项	来源	默认
后端 context-path	`application.yml`	`/api`
数据库连接	`application-dev.yml`	`localhost:3306/easy_data_check`,root/root
JWT 密钥/过期/头/前缀	`PlatformProperties.Jwt`	默认 secret(自动 pad 32B) / 86400s / `Authorization` / `Bearer`
AES 密码密钥	`easy-data-check.crypto.aes-key`	须与历史一致,否则存量密码失效
执行线程池	`execute.thread-pool-size`	8

验证记录

✅ 引擎 JDK11 编译(Lombok 1.18.30);内联清理后 + 现有单测(ExecuteComponentTest 字段映射/aggregator/processor 选择)全绿
✅ 登录 / JWT / 401 鉴权
✅ 数据源 CRUD + 连通测试 + 密码 AES / 掩码
✅ 全量比对 3 类差异(源多 / 目标多 / 不一致)正确检出
✅ 分页比对:2 天范围切为 2 子对账,聚合正确
✅ 时间增量:${startTime}/${endTime} 占账符过滤
✅ 调账标记(utf8mb4 中文备注)/ 已修复(AUTO_RETRY + MANUAL)
✅ 预警发送(edc_alert_log)、差异回调(edc_callback_log)
✅ EasyExcel 导出(有效 xlsx,含调账/修复字段)
✅ 操作日志 AOP + SpEL
✅ 前端端到端(登录→仪表盘→数据源→任务→执行→结果)
✅ 单元测试覆盖引擎 loader 字段映射 / aggregator / processor 选择 / 预警触发与渲染 / callback 执行器 / Webhook / 重试-FixedMarker

已知限制 / 后续演进

Platform hardening(2026-08) 后的现状快照:

类别	现状	后续
比对处理器	MEMORY/PARALLEL 全量装入；STREAM/PAGE 真流式（按页取数+边比边落库）；AUTO 小于 10 万用 MEMORY 否则 STREAM；REDIS/DATABASE 仍为 stub	Redis 分布式、有序归并
分页策略	`TIME_WINDOW` + JDBC↔JDBC `KEY_RANGE` 已交付(开区间 `${keyStart}`/`${keyEnd}`,末窗排他后继)	非 JDBC KEY_RANGE / keyset 发现优化
中止执行	协作式 abort:窗口循环检查标志,`updateSuccessIfRunning` 阻止 SUCCESS 覆盖 ABORTED;单窗内引擎线程仍可能跑完当前窗	更细粒度协作点
调度	仅手动触发;任务已预留字段	接入 Quartz / XXL-JOB
Groovy 沙箱	SecureAST deny-list + 超时 + 编译缓存,best-effort(非完整隔离)	建议生产独立容器 + SecurityManager
预警通道	WEBHOOK / EMAIL	SMS / 站内信(扩展 `edc_alert_type` 字典)
回调安全	不验证可写副作用(v1 文档已标风险)	dry-run / 审计
预警去重	无抑制窗口	后续加抑制

完整演进与设计推导见 docs/superpowers/specs/。

Name		Name	Last commit message	Last commit date
.codegraph		.codegraph
docs		docs
easy-data-check-backend		easy-data-check-backend
easy-data-check-ui		easy-data-check-ui
test-reports		test-reports
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile.backend		Dockerfile.backend
Dockerfile.frontend		Dockerfile.frontend
README.md		README.md
docker-compose.yml		docker-compose.yml
package.json		package.json
pom.xml		pom.xml

Navigation Menu

Uh oh!

Repository files navigation

easy-data-check · 数据对账平台

文档导航

技术栈

工程结构

数据源存储(按类型分表)

核心设计:动态取数接入 data-check

功能模块总览

快速开始

1. 元数据库(MySQL)

2. 后端(:8080/api)

3. 前端(:5173)

端到端使用最短路径

关键配置

验证记录

已知限制 / 后续演进

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

easy-data-check · 数据对账平台

文档导航

技术栈

工程结构

数据源存储(按类型分表)

核心设计:动态取数接入 data-check

功能模块总览

快速开始

1. 元数据库(MySQL)

2. 后端(:8080/api)

3. 前端(:5173)

端到端使用最短路径

关键配置

验证记录

已知限制 / 后续演进

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages