add: qData 数据中台技术报告（架构/ETL/部署/简历要点）

docs/project/qdata/architecture.md

@@ -0,0 +1,412 @@
+# QDATA 前后端架构报告
+
+> 生成日期：2026-08-27 | 基于源码深度分析
+
+---
+
+## 一、后端架构（Java / Spring Boot）
+
+### 1.1 项目概况
+
+qData 是一个企业级**数据中台**（Data Governance Platform），由江苏千统科技有限公司开发，版本 **1.6.1**，采用 Apache License 2.0 授权。后端基于 **Java 8** + **Spring Boot 2.5.15** 构建，Maven 多模块单体架构，共 **16 个业务模块** + **12 个框架子模块** + **2 个独立微服务**。
+
+| 维度 | 数量 |
+|------|------|
+| Controller 总数 | **146** |
+| REST 端点总数 | **1,242** |
+| Service 接口 | **~130** |
+| ServiceImpl 实现类 | **~125** |
+| DO（实体）类 | **118** |
+| VO 类 | **403** |
+| DTO 类 | **223** |
+| MyBatis Mapper 接口 | **143** |
+| Mapper XML 文件 | **109** |
+| 数据库表（latest） | **2,095** |
+
+### 1.2 分层架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     qdata-server（入口）                      │
+│                  QDataApplication.java :8080                 │
+├─────────────────────────────────────────────────────────────┤
+│                 qdata-framework（框架层，12 个子模块）          │
+│  auth │ common │ config │ file │ generator │ mybatis         │
+│  neo4j│ pay    │ quartz │ redis│ security  │ websocket       │
+├─────────────────────────────────────────────────────────────┤
+│               业务模块层（10 个模块，api + biz 拆分）           │
+│  system │ att │ da │ dg │ dm │ dp │ dpp │ ds │ mc │ ai      │
+├─────────────────────────────────────────────────────────────┤
+│            qdata-api-ds（DolphinScheduler 集成接口）           │
+├─────────────────────────────────────────────────────────────┤
+│          独立微服务：service-ai :8087 │ service-quality :8083  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 1.3 模块清单与职责
+
+| 模块 | Controller | 端点 | 职责 |
+|------|-----------|------|------|
+| `qdata-module-system` | 31 | 209 | 用户、角色、菜单、部门、字典、日志、消息、CA 证书 |
+| `qdata-module-da` | 23 | 237 | 数据资产编目、数据源管理、数据发现、资产审计、GIS/视频资产 |
+| `qdata-module-att` | 20 | 196 | 分类管理（10 类）、项目管理、标签、规则、客户端 |
+| `qdata-module-dpp` | 16 | 158 | ETL 数据集成、数据开发、任务调度、质量任务 |
+| `qdata-module-mc` | 13 | 113 | 元数据采集、变更检测、版本管理、方言适配 |
+| `qdata-module-dg` | 11 | 87 | 数据分类分级、脱敏规则、敏感数据管理 |
+| `qdata-module-dp` | 9 | 85 | 数据标准、数据元、码表映射、逻辑模型、文档管理 |
+| `qdata-module-dm` | 6 | 50 | 数据域、数据层、主题域、业务分类 |
+| `qdata-module-ds` | 4 | 27 | 数据服务 API 发布、客户端认证、调用日志 |
+| `qdata-module-ai` | 3 | 21 | AI 对话、模型管理（内嵌模式） |
+| `qdata-framework` | 4 | 33 | 文件上传、代码生成器、Quartz 任务管理 |
+| `qdata-service-ai` | 3 | 15 | 独立 AI 服务（JDK 17，Text2SQL） |
+| `qdata-service-quality` | 2 | 10 | 独立数据质量服务（MongoDB） |
+| `qdata-server` | 1 | 1 | 默认入口 |
+
+### 1.4 路由设计
+
+所有业务 Controller 使用统一的 RESTful 前缀约定：
+
+| 模块前缀 | 示例路径 | 说明 |
+|---------|---------|------|
+| `/system/` | `/system/user/list`, `/system/role` | 系统管理 |
+| `/da/` | `/da/asset/list`, `/da/datasource` | 数据资产 |
+| `/att/` | `/att/project/list`, `/att/tag` | 分类管理 |
+| `/dpp/` | `/dpp/etl/task/list`, `/dpp/quality/task` | 数据开发 |
+| `/mc/` | `/mc/task/list`, `/mc/db` | 元数据采集 |
+| `/dg/` | `/dg/dataCategory/list`, `/dg/desensitize/rule` | 数据治理 |
+| `/dp/` | `/dp/model/list`, `/dp/dataElem` | 数据标准 |
+| `/dm/` | `/dm/dataDomain/list`, `/dm/dataLayer` | 数据建模 |
+| `/ds/` | `/ds/api/list`, `/ds/apiLog` | 数据服务 |
+| `/ai/` | `/ai/chatConversation`, `/ai/model` | AI 模块 |
+| `/services/v1.0.0/` | 动态注册的 API 端点 | 数据服务运行时 |
+
+### 1.5 Service 层
+
+每个业务模块遵循 **api + biz** 拆分模式：
+- `*-api` —— 接口定义、DTO、枚举、领域对象
+- `*-biz` —— 业务逻辑、Controller、ServiceImpl、MyBatis Mapper
+
+关键 Service 职责：
+
+| Service | 模块 | 核心职责 |
+|---------|------|---------|
+| `IDppEtlTaskService` | dpp | ETL 任务 CRUD、发布/下线、调度器集成 |
+| `McTaskServiceImpl` | mc | 元数据采集执行、增量/全量、变更检测 |
+| `DaAssetServiceImpl` | da | 资产编目、血缘追踪（Neo4j）、发现任务 |
+| `DsApiServiceImpl` | ds | API 发布/注销、SQL 解析、在线测试 |
+| `QualityTaskExecutorServiceImpl` | quality | 质量规则执行、错误数据存储（MongoDB） |
+| `DpModelServiceImpl` | dp | 逻辑模型管理、数据元关联、物化视图 |
+| `TokenService` | security | JWT 签发/验证/刷新、Redis 存储 |
+
+### 1.6 数据模型
+
+共 **748** 个模型类（118 DO + 403 VO + 223 DTO + 4 Entity），按模块分布：
+
+| 模块 | DO | 说明 |
+|------|-----|------|
+| `da` | 25 | `DaAssetDO`, `DaDatasourceDO`, `DaDiscoveryTaskDO` 等 |
+| `att` | 20 | `AttProjectDO`, `AttTagDO`, `AttClientDO` 等 |
+| `dpp` | 18 | `DppEtlTaskDO`, `DppEtlNodeDO`, `DppEtlSchedulerDO` 等 |
+| `mc` | 12 | `McDbDO`, `McTableDO`, `McColumnDO`, `McTaskDO` 等 |
+| `dg` | 11 | `DgDataCategoryDO`, `DgDesensitizeRuleDO` 等 |
+| `dp` | 9 | `DpModelDO`, `DpModelColumnDO`, `DpDataElemDO` 等 |
+| `quality` | 7 | `QualityRuleEntity`, `CheckErrorData` 等 |
+| `dm` | 6 | `DmDataDomainDO`, `DmDataLayerDO` 等 |
+| `system` | 5 | `SysConfig`, `SysNotice`, `SysOperLog` 等 |
+| `ai` | 3 | `AiModelDO`, `AiChatConversationDO`, `AiChatMessageDO` |
+| `ds` | 2 | `DsApiDO`, `DsApiLogDO` |
+
+### 1.7 认证机制
+
+**主认证**：Spring Security 5.7.12 + JWT（HS512）
+
+```
+┌──────────┐    POST /login     ┌──────────────┐
+│  Client  │ ──────────────────► │ AuthController│
+└──────────┘                     └──────┬───────┘
+                                        │
+                                        ▼
+                              ┌──────────────────┐
+                              │  SysLoginService   │
+                              │  · BCrypt 密码校验  │
+                              │  · 验证码校验       │
+                              │  · IP 黑名单检查    │
+                              └────────┬─────────┘
+                                       │
+                                       ▼
+                              ┌──────────────────┐
+                              │   TokenService     │
+                              │  · HS512 签发 JWT  │
+                              │  · Redis 存储      │
+                              │  · 自动续期（20min）│
+                              └──────────────────┘
+```
+
+- Token 通过 `Authorization: Bearer {token}` 传递
+- Redis Key：`login_tokens:{uuid}`，默认 TTL **600 分钟**（10 小时）
+- Token 在剩余 **20 分钟**时自动续期
+- 密码加密：**BCrypt**
+- CSRF 已禁用（无状态策略）
+
+**OAuth2 支持**：基于 **SA-Token** 框架，支持全部 4 种授权模式（Authorization Code、Implicit、Password、Client Credentials），路径 `/oauth2/**`。
+
+**数据服务客户端认证**：独立的 `DsCheckClientToken` 注解 + `ApiJwtUtil`，7 天 Token + 30 天 Refresh Token。
+
+### 1.8 配置管理
+
+| 配置项 | 值 |
+|--------|-----|
+| 服务端口 | 8080 |
+| Tomcat 最大线程 | 800 |
+| Tomcat 最小空闲线程 | 100 |
+| 文件上传上限 | 3,000 MB |
+| XSS 过滤路径 | `/system/*`, `/monitor/*`, `/tool/*` |
+| i18n 资源包 | 13 个（跨模块） |
+| 分页插件 | PageHelper（MySQL 方言） |
+| ID 策略 | 自增 + 雪花 ID |
+
+**数据源支持**：MySQL（主）、DM8、KingbaseES、Oracle、PostgreSQL、SQL Server，通过 `application-dev.yml` 切换。连接池使用 **Alibaba Druid 1.2.23**（初始 5，最大 20）。
+
+---
+
+## 二、前端架构（Vue 3 / TypeScript）
+
+### 2.1 技术栈
+
+| 类别 | 技术 | 版本 |
+|------|------|------|
+| 框架 | Vue 3 | ^3.5.21 |
+| UI 库 | Element Plus | 2.7.6 |
+| 构建工具 | Vite | 5.3.2 |
+| 状态管理 | Pinia | 2.1.7 |
+| 路由 | Vue Router | 4.4.0 |
+| 国际化 | vue-i18n | ^11.4.5 |
+| HTTP 客户端 | Axios | 0.28.1 |
+| 图表 | ECharts | 5.5.1 |
+| 流程图 | AntV X6 | ^2.18.1 |
+| 代码编辑器 | Monaco Editor | ^0.52.2 |
+| 富文本 | Vue Quill | 1.2.0 |
+| Markdown | markdown-it | ^14.1.0 |
+| 网络图 | vis-network | ^9.1.13 |
+| 表单设计器 | @form-create/designer | ^3.2.11 |
+| 文档预览 | @vue-office/docx/excel/pdf | ^1.6.3 / ^1.7.14 / ^2.0.10 |
+| 模糊搜索 | Fuse.js | 6.6.2 |
+| 拖拽 | vuedraggable | ^4.1.0 |
+| 加密 | crypto-js + jsencrypt | ^4.2.0 / 3.3.2 |
+
+### 2.2 目录结构
+
+```
+qdata-ui/src/
+├── api/            # 14 个模块目录，151 个 API 文件
+├── assets/         # 静态资源（197 个 SVG 图标）
+├── components/     # 38 个组件目录，83 个文件
+├── composables/    # 5 个组合式函数
+├── directive/      # 4 个自定义指令（copyText, hasPermi, hasRole）
+├── layout/         # 12 个布局组件
+├── locales/        # 3 语言 × 18 命名空间 = 54 个翻译文件
+├── plugins/        # 8 个插件（auth, cache, download, modal, tab, i18n）
+├── router/         # 27 个路由文件
+├── store/          # 8 个 Pinia Store
+├── utils/          # 30 个工具文件
+└── views/          # 13 个模块目录，322 个页面组件
+```
+
+### 2.3 路由设计
+
+共 **91 个路由声明**，分为两层：
+
+- **constantRoutes**（公开路由）：来自 18 个路由模块文件，无需权限
+- **dynamicRoutes**（动态路由）：来自 4 个模块文件，由后端菜单接口动态注入
+
+路由组件解析使用 `import.meta.glob('./../../views/**/*.vue')` 实现懒加载。`beforeEach` 守卫在路由切换时取消未完成的 HTTP 请求。
+
+路由 Top 5：
+
+| 路由文件 | 路由数 |
+|---------|--------|
+| `system/public/index.js` | 19 |
+| `system/dynamic/index.js` | 10 |
+| `dp/document/index.js` | 10 |
+| `da/quality/index.js` | 8 |
+| `meta/dynamic/index.js` | 8 |
+
+### 2.4 状态管理
+
+**8 个 Pinia Store**：
+
+| Store | 职责 |
+|-------|------|
+| `app` | 侧边栏状态、设备类型、UI 尺寸 |
+| `user` | 认证信息（Token、用户、角色、权限） |
+| `dict` | 字典缓存（内存 KV） |
+| `permission` | 动态路由管理、菜单树解析 |
+| `settings` | 布局配置（主题色、顶栏、标签页等） |
+| `tags-view` | 标签页导航管理 |
+| `locale` | 国际化语言切换 |
+| `project` | 项目上下文、资产/模型分类树 |
+
+### 2.5 组件体系
+
+**19 个全局注册组件**：
+
+| 组件 | 说明 |
+|------|------|
+| `SvgIcon` | SVG 图标渲染器（197 个图标） |
+| `Pagination` | 分页封装 |
+| `ImageUpload` | 图片上传预览 |
+| `FileUpload` | 文件上传 |
+| `FileUploadbtn` | 文件上传按钮 |
+| `Editor` | 富文本编辑器（Quill） |
+| `DictTag` | 字典值标签 |
+| `DetailInfo` | 通用详情页头 |
+| `DescriptionsInfo` | 描述信息封装 |
+| `RightToolbar` | 表格工具栏（列切换、搜索、刷新） |
+| `TreeSelect` | 树形下拉选择 |
+| `QtTable` / `QtSearchBar` / `QtFormItem` / `QtTabPane` / `QtTagGroup` / `QtWrap` | qData 定制组件 |
+| `ImagePreview` | 图片预览灯箱 |
+| `GuideTip` | 引导提示 |
+
+**专用组件**（非全局）：
+
+| 组件 | 说明 |
+|------|------|
+| `SqlEditor` | SQL 编辑器（Monaco/CodeMirror，支持 FlinkSQL） |
+| `ShellEditor` | Shell 脚本编辑器 |
+| `ProTable` | 专业表格组件 |
+| `Crontab` | Cron 表达式编辑器（8 个子组件） |
+| `MarkdownView` | Markdown 渲染器 |
+| `DeptTree` | 部门树选择器 |
+| `HeaderSearch` | 头部搜索（Fuse.js 模糊匹配） |
+
+### 2.6 国际化
+
+| 语言 | 命名空间 | 翻译键值对 | 行数 |
+|------|---------|-----------|------|
+| zh-CN（主） | 18 | ~6,320 | 7,420 |
+| en-US | 18 | ~6,200 | 7,130 |
+| ja-JP | 18 | ~6,200 | 7,175 |
+
+最大的命名空间：`dpp`（数据开发）1,636 行，`sys`（系统管理）1,017 行，`da`（数据资产）810 行。
+
+### 2.7 构建配置
+
+**开发服务器**：端口 81，4 个代理规则：
+
+| 代理路径 | 目标 | 说明 |
+|---------|------|------|
+| `/dev-api` | `http://localhost:8080` | 主后端 |
+| `/dev-ai` | `http://localhost:8087` | AI 服务 |
+| `/jmreport` | `http://localhost:8080` | 报表服务 |
+| `/v3/api-docs` | `http://localhost:8080` | Swagger 文档 |
+
+**构建优化**：
+- 手动 chunk 拆分（每个 `node_modules` 包独立分包）
+- Gzip/Brotli 压缩（通过 `VITE_BUILD_COMPRESS` 环境变量控制）
+- SVG 图标精灵（`vite-plugin-svg-icons`，197 个图标）
+- 自动导入（`unplugin-auto-import` + `unplugin-vue-components`）
+
+### 2.8 文件统计
+
+| 类别 | 数量 |
+|------|------|
+| Vue 文件总数 | **405** |
+| JS 文件总数 | **310** |
+| TS 文件总数 | **8** |
+| 源文件总数 | **730** |
+| views/ 下 Vue 文件 | 322 |
+| components/ 下 Vue 文件 | 71 |
+| API 文件 | 151 |
+| 路由文件 | 27 |
+| Store 文件 | 8 |
+| 翻译文件 | 54 |
+| SVG 图标 | 197 |
+
+---
+
+## 三、前后端交互模型
+
+### 3.1 通信架构
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                        qdata-ui (Vue 3)                         │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
+│  │  views/   │  │  store/  │  │  router/  │  │   api/        │  │
+│  │  322 页面 │  │  8 Store │  │  91 路由  │  │  151 API 文件 │  │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └──────┬────────┘  │
+│       │              │              │               │           │
+│       └──────────────┴──────────────┴───────┬───────┘           │
+│                                             │ Axios             │
+└─────────────────────────────────────────────┼───────────────────┘
+                                              │
+                    ┌─────────────────────────┼────────────────────┐
+                    │   Nginx :80（生产）      │                    │
+                    │   /prod-api → :8080      │                    │
+                    │   /prod-ai  → :8087      │                    │
+                    └─────────────────────────┼────────────────────┘
+                                              │
+              ┌───────────────────────────────┼────────────────────────┐
+              │                               │                        │
+              ▼                               ▼                        ▼
+    ┌──────────────────┐          ┌──────────────────┐      ┌──────────────────┐
+    │   qdata-api       │          │  qdata-service-ai │      │  qdata-service-   │
+    │   :8080           │          │  :8087            │      │  quality :8083    │
+    │   146 Controller  │          │  3 Controller     │      │  2 Controller     │
+    │   1,242 端点       │          │  15 端点           │      │  10 端点           │
+    └────────┬─────────┘          └──────────────────┘      └──────────────────┘
+             │
+    ┌────────┼────────┬──────────┬──────────┐
+    ▼        ▼        ▼          ▼          ▼
+  MySQL    Redis   RabbitMQ    Neo4j    MongoDB
+  /DM8     :6379   :5672      :7687    :27017
+```
+
+### 3.2 认证流程
+
+1. 前端调用 `POST /login`（用户名 + 密码 + 验证码）
+2. 后端 `AuthController` → `SysLoginService` 校验（BCrypt + 验证码 + IP 黑名单）
+3. `TokenService` 签发 JWT（HS512），存入 Redis（`login_tokens:{uuid}`，TTL 600min）
+4. 前端存储 Token 到 Cookie，后续请求通过 `Authorization: Bearer {token}` 携带
+5. `JwtAuthenticationTokenFilter` 拦截请求，从 Redis 验证 Token 有效性
+6. Token 剩余 20 分钟时自动续期
+
+### 3.3 动态菜单与路由
+
+1. 前端登录后调用 `getRouters()` 获取后端菜单树
+2. `permission` Store 将菜单树转换为 Vue Router 路由配置
+3. 组件字符串通过 `import.meta.glob` 解析为懒加载组件
+4. `addRoutes()` 动态注入路由，`router.addRoute()` 添加 404 兜底
+5. 侧边栏、顶栏、面包屑均从路由元数据（`meta.title`, `meta.icon`）渲染
+
+### 3.4 API 文档
+
+- **SpringDoc OpenAPI 3** + **Knife4j** 增强 UI
+- 分组：`system`、`example`、`ai`、`dm`
+- Swagger UI 路径：`/swagger-ui.html`
+- API 文档路径：`/v3/api-docs`
+- i18n 支持：`SwaggerI18nCustomizer` 运行时翻译 `@Tag` 和 `@Operation`
+- Knife4j 基础认证：`test` / `12313`
+
+---
+
+## 四、文件统计汇总
+
+| 维度 | 数量 |
+|------|------|
+| 后端 Controller | 146 |
+| 后端 REST 端点 | 1,242 |
+| 后端 Service 接口 | ~130 |
+| 后端 DO 类 | 118 |
+| 后端 Mapper 接口 | 143 |
+| 后端 Mapper XML | 109 |
+| 数据库表 | 2,095 |
+| 前端 Vue 文件 | 405 |
+| 前端 JS/TS 文件 | 318 |
+| 前端 API 文件 | 151 |
+| 前端路由 | 91 |
+| 前端 Pinia Store | 8 |
+| 前端组件 | 83 |
+| 前端翻译键值对 | ~6,320 |
+| SVG 图标 | 197 |
+| Docker 服务 | 22 |

docs/project/qdata/data-governance-etl.md

@@ -0,0 +1,429 @@
+# QDATA 数据治理与 ETL 报告
+
+> 生成日期：2026-08-27 | 基于源码深度分析
+
+---
+
+## 一、ETL 数据集成
+
+### 1.1 双引擎架构
+
+qData 采用 **DataX + Spark** 双引擎架构：
+
+| 引擎 | 适用场景 | 数据源支持 |
+|------|---------|-----------|
+| DataX | RDBMS 间数据库同步（轻量级） | rdbmsreader / rdbmswriter |
+| Spark | 复杂转换、CSV/Excel 导入、分布式处理 | DB / CSV / Excel Reader |
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    qdata-module-dpp                        │
+│            （ETL 任务管理、调度、监控）                      │
+├──────────────────────────────────────────────────────────┤
+│                                                          │
+│  ┌─────────────────────┐    ┌─────────────────────────┐  │
+│  │    DataX 引擎        │    │    Spark 引擎            │  │
+│  │  DataXExecutor       │    │  EtlApplication          │  │
+│  │  DataXJsonBuilder     │    │  ReaderFactory           │  │
+│  │  Python subprocess   │    │  TransitionFactory       │  │
+│  │                      │    │  WriterFactory           │  │
+│  │  · rdbmsreader       │    │                          │  │
+│  │  · rdbmswriter       │    │  · DBReader (3 模式)     │  │
+│  │  · VALUE_MAP         │    │  · CsvReader             │  │
+│  │  · ADD_CONSTANT      │    │  · ExcelReader           │  │
+│  │  · SELECT_FIELDS     │    │  · DBWriter (3 模式)     │  │
+│  │  · FIELD_DERIVATION  │    │  · 7 种 Transition       │  │
+│  └──────────┬──────────┘    └────────────┬────────────┘  │
+│             │                            │                │
+│             └─────────┬──────────────────┘                │
+│                       ▼                                   │
+│              ┌──────────────────┐                         │
+│              │  DolphinScheduler │                         │
+│              │  / Quartz 调度     │                         │
+│              └──────────────────┘                         │
+└──────────────────────────────────────────────────────────┘
+```
+
+### 1.2 DataX 引擎
+
+**核心类**：
+
+| 类 | 职责 |
+|----|------|
+| `DataXExecutor` | 通过 Python 子进程执行 DataX 任务（`python3 datax.py job.json`） |
+| `DataXJsonBuilder` | 生成 DataX job.json 配置，支持 Reader/Writer/Processor 节点 |
+| `DataXProperties` | 配置项：`datax.home`、`datax.python-command`、`datax.datax-py-path`、`datax.job-dir` |
+
+**支持的 Processor**：`VALUE_MAP`（值映射）、`ADD_CONSTANT`（添加常量列）、`SELECT_FIELDS`（列选择）、`FIELD_DERIVATION`（字段派生）。
+
+### 1.3 Spark 引擎
+
+**入口**：`tech.qiantong.qdata.spark.etl.EtlApplication.main()`
+
+**执行流程**：
+1. 接收 DolphinScheduler 传递的 Base64 编码 JSON 参数（`reader` + `transition[]` + `writer` + `config`）
+2. 通过 RabbitMQ 发布 RUNNING 状态
+3. 初始化 Redis（增量游标存储）
+4. 创建 `SparkSession`
+5. 执行管线：`ReaderFactory` → `TransitionFactory`（N 个转换）→ `WriterFactory`
+6. 通过 RabbitMQ 上报 SUCCESS/FAILURE 状态
+7. 成功写入后将增量游标存入 Redis
+
+**Reader 注册表**：
+
+| 类型码 | 类 | 说明 |
+|--------|-----|------|
+| `DB_READER` | `DBReader` | Spark JDBC 读取 |
+| `EXCEL_READER` | `ExcelReader` | Excel 文件读取 |
+| `CSV_READER` | `CsvReader` | CSV 文件读取 |
+
+**DBReader 读取模式**：
+
+| 模式 | 说明 |
+|------|------|
+| 1 = 全量 | 读取全表 |
+| 2 = ID 增量 | 基于 Redis 缓存的 ID 游标 |
+| 3 = 时间范围增量 | 支持固定值、时间范围、SQL 表达式 |
+
+**Transition 注册表**：
+
+| 类型码 | 类 | 说明 |
+|--------|-----|------|
+| `SPARK_CLEAN` | `CleanTransition` | 数据清洗（31KB，最复杂的转换） |
+| `SORT_RECORD` | `SortTransition` | 排序 |
+| `FIELD_DERIVATION` | `FieldDerivationTransition` | 字段派生 |
+| `DATA_DEDUPLICATION` | `DataDeduplicationTransition` | 数据去重 |
+| `VALUE_MAP` | `ValueMapTransition` | 值映射 |
+| `ADD_CONSTANT` | `AddConstantTransition` | 添加常量列 |
+| `SELECT_FIELDS` | `SelectFieldsTransition` | 列选择 |
+
+**Writer 注册表**：
+
+| 类型码 | 类 | 说明 |
+|--------|-----|------|
+| `DB_WRITER` | `DBWriter` | Spark JDBC 写入 |
+
+**DBWriter 写入模式**：
+
+| 模式 | 说明 |
+|------|------|
+| 1 = 全量 | 临时表 + 重命名交换 |
+| 2 = 追加 | 直接追加写入 |
+| 3 = 增量更新 | Upsert（PreparedStatement 批处理） |
+
+支持 `preSql` / `postSql` 执行，方言适配 Kingbase8、SQL Server、Doris 的表重命名操作。
+
+**JDBC 驱动内置**：MySQL 8、DM8、Oracle、KingBase、SQLServer、jtds。
+
+### 1.4 调度集成
+
+| 调度器 | 模式 | 说明 |
+|--------|------|------|
+| Quartz | 进程内 | 轻量级，适合单机部署 |
+| DolphinScheduler | 分布式 | 通过 HTTP API 集成，31 个端点 |
+
+**DolphinScheduler API 端点**（定义于 `QianTongDCApiType`）：
+
+| 类别 | 端点数 | 示例 |
+|------|--------|------|
+| 项目管理 | 4 | `POST /v2/projects`, `GET /v2/projects/{code}` |
+| 流程定义 | 11 | 创建、更新、删除、发布、批量操作、版本管理 |
+| 调度管理 | 6 | 创建、更新、上线、下线、预览 |
+| 执行管理 | 2 | 启动流程实例、执行流程 |
+| 监控查询 | 5 | 流程实例、任务实例、日志 |
+| 任务编码 | 1 | 生成任务定义编码 |
+
+**回调机制**：ETL Spark 任务不直接调用 DolphinScheduler REST API，而是通过 **RabbitMQ** 发布状态更新：
+- 交换机：`ds.exchange.processInstance`、`ds.exchange.taskInstance`
+- 路由键：`ds.queue.processInstance`、`ds.queue.taskInstance.insert`、`ds.queue.taskInstance.update`
+
+---
+
+## 二、数据开发
+
+### 2.1 任务类型
+
+| 类型码 | 说明 |
+|--------|------|
+| 1 | 离线任务 |
+| 2 | 实时任务 |
+| 3 | 数据开发任务（SQL 脚本） |
+| 4 | 作业任务 |
+
+### 2.2 任务状态
+
+| 状态码 | 说明 |
+|--------|------|
+| -3 | 部分上线 |
+| -2 | 草稿 |
+| 0 | 下线 |
+| 1 | 上线 |
+
+### 2.3 核心功能
+
+- **可视化 ETL 编排**：基于 AntV X6 的拖拽式流程编辑器
+- **SQL 脚本开发**：Monaco Editor 支持的 SQL 编辑与执行
+- **任务版本管理**：节点版本化，支持历史回溯
+- **统计面板**：运行中数量、今日错误数、今日执行数、成功率
+
+---
+
+## 三、数据质量
+
+### 3.1 独立微服务
+
+`qdata-service-quality`（端口 8083）独立部署，使用 **MongoDB** 存储错误数据。
+
+### 3.2 质量规则引擎
+
+**工厂模式**：`QualitySqlGenerateFactory` 根据规则类型分发到对应的 SQL 生成器。
+
+**9 种质量规则生成器**：
+
+| 生成器 | 维度 | 说明 |
+|--------|------|------|
+| `CharacterValidationGenerator` | 有效性 | 字符格式验证 |
+| `CompositeUniquenessGenerator` | 唯一性 | 组合字段唯一性 |
+| `DecimalPrecisionGenerator` | 有效性 | 小数精度验证 |
+| `EnumValidationGenerator` | 有效性 | 枚举值验证 |
+| `GroupFieldCompletenessGenerator` | 完整性 | 分组字段完整性 |
+| `LengthValidationGenerator` | 有效性 | 长度验证 |
+| `NumericRangeValidationGenerator` | 有效性 | 数值范围验证 |
+| `TimeOrderValidationGenerator` | 有效性 | 时间顺序验证 |
+| `CommonGenerator` | 通用 | 通用规则 |
+
+### 3.3 数据库方言注册
+
+`ComponentRegistry` 注册了 **6 种数据库方言**：
+
+| 数据库 | 方言类 |
+|--------|--------|
+| MySQL | `MySqlQuality` |
+| Oracle 12c | `Oracle12cQuality` |
+| Oracle | `OracleQuality` |
+| SQL Server | `SQLServerQuality` |
+| DM8 | `DM8Quality` |
+| 默认 | `DefaultQuality` |
+
+### 3.4 执行流程
+
+1. `QualityTaskExecutorServiceImpl.executeTask(taskId)` 提交异步执行（`ThreadPoolTaskExecutor` + Redis 去重锁）
+2. 查询任务 → 生成批次号 → 获取数据源对象 → 按数据源 ID 分组
+3. 对每个数据源：连接 → 加载规则 → 通过 `RuleTaskExecutor` 逐条执行规则
+4. 错误数据存入 MongoDB（`CheckErrorData` 文档）
+5. 支持 3 种错误数据修改方式：
+   - `updateType=1`：修改数据 + 更新物理表
+   - `updateType=2`：修改备注
+   - `updateType=3`：修改修复状态
+
+---
+
+## 四、元数据管理
+
+### 4.1 采集架构
+
+`qdata-module-mc` 提供自动化的元数据采集，支持增量/全量两种模式，使用 **Neo4j** 图数据库存储元数据关系。
+
+### 4.2 采集流程
+
+```
+McTaskServiceImpl.runDaDiscoveryTask(taskId)
+    │
+    ├── Redis 分布式锁（防重复执行）
+    ├── 创建采集实例
+    │
+    └── executeTaskSafely(task, instance)
+        │
+        ├── 准备数据源连接
+        ├── 加载数据库范围（自定义 / 全部）
+        ├── 对比数据库列表（新增/删除/变更）
+        │
+        └── 对每个数据库：
+            ├── 加载表列表 → 对比表列表
+            ├── 加载列信息 → 对比列信息
+            └── 记录变更日志
+```
+
+### 4.3 变更检测
+
+| 变更类型 | 说明 |
+|---------|------|
+| "1" | 表注释变更 |
+| "2" | 列新增/删除/修改 |
+| "3" | 索引字段变更 |
+| "4" | 存储大小变更 |
+| "1"-"9"（列级） | 注释、类型、长度、精度、小数位、默认值、主键、外键、可空 |
+
+### 4.4 数据库方言
+
+`DatabaseDialectFactory` 注册的方言：
+
+| 数据库 | 方言类 | 状态 |
+|--------|--------|------|
+| MySQL | `MySqlDialect` | 完整实现 |
+| Hive | `HiveDialect` | 完整实现 |
+| DM8 | `DamengDialect` | 完整实现 |
+| Oracle | `OracleDialect` | 占位实现 |
+| PostgreSQL | `PostgreSqlDialect` | 占位实现 |
+| SQL Server | `AbstractDialect` | 占位实现 |
+
+方言接口方法：`getStorageEngine()`, `getTableRowCount()`, `getTableIndexes()`, `getTablePartitionFields()`, `isColumnAutoIncrement()`, `getDbMetadata()`, `getTableMetadata()`, `getColumnMetadata()`。
+
+---
+
+## 五、数据资产
+
+### 5.1 资产编目
+
+`DaAssetServiceImpl` 是核心服务，集成 **11 个子服务**：
+
+| 子服务 | 职责 |
+|--------|------|
+| `IDaAssetColumnService` | 资产字段编目 |
+| `IDaAssetApiService` | 资产 API 定义 |
+| `IDaAssetApiParamService` | API 参数管理 |
+| `IDaAssetGeoService` | 地理空间资产 |
+| `IDaAssetGisService` | GIS 资产 |
+| `IDaAssetVideoService` | 视频资产 |
+| `IDaAssetFilesService` | 文件资产 |
+| `IDaAssetThemeRelService` | 资产-主题关联 |
+| `IDaAssetProjectRelService` | 资产-项目关联 |
+| `IDaDiscoveryTableService` | 发现表管理 |
+| `IDaDiscoveryTaskService` | 发现任务管理 |
+
+### 5.2 数据血缘
+
+通过 **Neo4j** 图数据库追踪 ETL 管线的数据血缘：
+
+| 节点类型 | 标签 | 说明 |
+|---------|------|------|
+| `TableNode` | `@Node("Table")` | 数据表节点 |
+| `TaskNode` | `@Node("Task")` | ETL 任务节点 |
+
+| 关系类型 | 方向 | 说明 |
+|---------|------|------|
+| `TABLE_TO_TASK` | Table → Task | 表作为任务输入 |
+| `TASK_TO_TABLE` | Task → Table | 任务输出到表 |
+
+关系属性：`taskId`, `taskCode`, `datasourceHostPort`, `tableName`。
+
+`LineageDataService` 支持 Cypher 查询遍历上下游 Table → Task → Table 链路。
+
+---
+
+## 六、数据服务（API 发布）
+
+### 6.1 动态 API 注册
+
+`MappingHandlerMapping` 使用 Spring 的 `RequestMappingHandlerMapping` 在运行时动态注册/注销 REST API：
+
+- **URL 模式**：`/services/{version}/{path}`（如 `/services/v1.0.0/user/1`）
+- **内部存储**：`ConcurrentHashMap<String, DsApiDO> mappings`
+- **认证**：`@DsCheckClientToken` 注解 + `ApiJwtUtil` JWT 验证
+
+### 6.2 API 服务类型
+
+| 类型码 | 说明 |
+|--------|------|
+| 1 | 数据服务（数据表/SQL 查询） |
+| 2 | 模型数据服务 |
+| 3 | 第三方 API 代理 |
+| 4 | 文件服务 |
+
+### 6.3 响应类型
+
+| 类型码 | 说明 |
+|--------|------|
+| 1 | 详情（单条记录） |
+| 2 | 列表 |
+| 3 | 分页 |
+
+### 6.4 核心功能
+
+- **SQL 解析**：`DsApiServiceImpl.sqlParse()` 使用 JSqlParser 解析 SQL，提取请求参数和响应字段
+- **SQL 生成**：`sqlJdbcNamedParameterBuild()` 从表单配置生成带命名参数的 SQL
+- **多数据库 SQL 生成**：支持 Kingbase8、PostgreSQL、SQL Server、MySQL、Oracle
+- **在线测试**：`serviceTesting()` 支持分页/列表/详情响应测试
+- **异步日志**：`AsyncTask.doTask(DsApiLogDO)` 异步记录 API 调用日志
+
+---
+
+## 七、数据建模
+
+### 7.1 模型类型
+
+| 类型码 | 说明 |
+|--------|------|
+| 1 | 逻辑模型 |
+| 2 | 物理模型（从数据源导入） |
+
+### 7.2 模型分层
+
+| 层 | 目标用户 | 说明 |
+|----|---------|------|
+| 公共层（Public Layer） | 数据开发者 | 明细模型 |
+| 应用层（Application Layer） | 业务/分析师 | 聚合模型 |
+
+### 7.3 核心功能
+
+- **逻辑模型管理**：`DpModelServiceImpl` 提供 CRUD、发布状态管理、版本控制
+- **数据元管理**：数据元标准定义、码表映射、数据元-资产关联
+- **物化视图**：`DpModelMaterializedController` 管理物化视图
+- **树形结构**：公共层（业务分类）+ 应用层（主题域）
+
+---
+
+## 八、数据治理
+
+### 8.1 数据分类分级
+
+`qdata-module-dg` 提供完整的数据分类分级体系：
+
+| 功能 | Controller | 说明 |
+|------|-----------|------|
+| 数据分类 | `DgDataCategoryController` | 数据分类目录 |
+| 分类子类 | `DgDataCategoryCatController` | 分类细分 |
+| 数据级别 | `DgDataLevelController` | 数据分级 |
+| 敏感级别 | `DgSensitiveLevelController` | 敏感数据分级 |
+
+### 8.2 数据脱敏
+
+| 功能 | Controller | 说明 |
+|------|-----------|------|
+| 脱敏规则 | `DgDesensitizeRuleController` | 脱敏规则定义 |
+| 脱敏区间 | `DgDesensitizeIntervalController` | 脱敏区间配置 |
+| 脱敏字段 | `DgDesensitizeAssetcolumnController` | 资产字段脱敏关联 |
+| 白名单 | `DgDesensitizeWhitelistController` | 脱敏白名单 |
+| 用户关联 | `DgDesensitizeUserRelController` | 用户-脱敏规则关联 |
+
+---
+
+## 九、AI 智能能力
+
+### 9.1 AI 平台支持
+
+`AiPlatformEnum` 支持 **19 个 AI 平台**：
+
+**国内（11 个）**：通义千问（DashScope）、文心一言（百度）、DeepSeek、智谱、星火（讯飞）、豆包（字节）、混元（腾讯）、SiliconFlow、MiniMax、Moonshot（Kimi）、百川。
+
+**海外（8 个）**：OpenAI、Azure OpenAI、Anthropic（Claude）、Gemini（Google）、Ollama、StableDiffusion、Midjourney、Suno、Grok。
+
+### 9.2 Text2SQL
+
+`StatisticsPromptBuilder` 实现自然语言到 SQL 的转换：
+
+- **星型模型支持**：事实表 + 维度表 + 事实-维度关联
+- **数据库方言感知**：MySQL、DM8/Oracle、Kingbase8、PostgreSQL、SQL Server、Doris
+- **双回复模式**：
+  - `CHART` 模式：返回 SQL + 维度 + 度量 + 时间粒度（用于图表渲染）
+  - `QA` 模式：返回文本或 SQL（用于问答）
+
+### 9.3 事实-维度表匹配
+
+`MatchPromptBuilder` 使用 AI 自动匹配事实表与维度表的关联关系：
+- 输入：事实表（表名、别名、描述、列、主键）+ 维度表列表
+- 输出：JSON 格式的关联关系（维度表、事实列名、维度列名、匹配原因）
+
+### 9.4 独立部署
+
+`qdata-service-ai`（端口 8087）独立部署，要求 **JDK 17**，通过 `DualServiceImpl` 实现 12 个空桩接口，使其可脱离其他微服务独立运行。

docs/project/qdata/deployment.md

@@ -0,0 +1,409 @@
+# QDATA 部署与基础设施报告
+
+> 生成日期：2026-08-27 | 基于源码深度分析
+
+---
+
+## 一、服务架构总览
+
+qData 采用**三后端 + 一前端**的微服务架构，通过 Docker Compose 编排，支持 **light**（轻量）和 **all**（全量）两种部署模式。
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                         Nginx :80                                   │
+│              /prod-api → qdata-api:8080                             │
+│              /prod-ai  → qdata-service-ai:8087                      │
+│              /         → 前端静态文件                                │
+├────────────────────────────────────────────────────────────────────┤
+│                                                                    │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐ │
+│  │   qdata-api       │  │  qdata-service-ai │  │  qdata-service-  │ │
+│  │   :8080           │  │  :8087            │  │  quality :8083   │ │
+│  │   JDK 8           │  │  JDK 17           │  │  JDK 8           │ │
+│  │   146 Controller  │  │  Text2SQL         │  │  质量规则引擎     │ │
+│  └────────┬─────────┘  └──────────────────┘  └────────┬─────────┘ │
+│           │                                            │           │
+│  ┌────────┼────────────────────────────────────────────┼────────┐  │
+│  │        ▼                                            ▼        │  │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │  │
+│  │  │ MySQL/DM8│ │  Redis   │ │ RabbitMQ │ │ MongoDB  │        │  │
+│  │  │  :3306   │ │  :6379   │ │  :5672   │ │ :27017   │        │  │
+│  │  │  主数据库 │ │  缓存/会话│ │  消息队列 │ │ 错误数据  │        │  │
+│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │  │
+│  │                                                              │  │
+│  │  ┌──────────┐ ┌──────────────────┐ ┌──────────────────────┐ │  │
+│  │  │  Neo4j   │ │ DolphinScheduler │ │   Spark + Hadoop     │ │  │
+│  │  │  :7687   │ │  :12345          │ │   :7077 / :8020      │ │  │
+│  │  │  血缘图谱 │ │  分布式调度       │ │   分布式 ETL          │ │  │
+│  │  └──────────┘ └──────────────────┘ └──────────────────────┘ │  │
+│  └─────────────────────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 二、Docker Compose 编排
+
+### 2.1 文件结构
+
+| 文件 | 说明 |
+|------|------|
+| `docker-compose.yml` | 主入口（DM8 数据库） |
+| `docker-compose-mysql.yml` | MySQL 数据库入口 |
+| `docker-compose-base.yml` | 基础服务（Redis、RabbitMQ、Nginx、数据库、MongoDB、Neo4j） |
+| `docker-compose-dolphinscheduler.yml` | DolphinScheduler 全家桶 |
+| `docker-compose-spark.yml` | Spark Master + Worker |
+| `docker-compose-hadoop.yml` | Hadoop HDFS（NameNode、DataNode、ResourceManager、NodeManager） |
+| `docker-compose-qdata.yml` | 三个 qData 后端服务 |
+| `docker-compose-demo.yml` | 演示数据库（MySQL、Oracle、DM8） |
+| `.env` / `.env.example` | 环境变量配置 |
+
+使用 `include` 指令组合（需要 Compose v2.20.2+）。
+
+### 2.2 部署模式
+
+| Profile | 服务数 | 说明 |
+|---------|--------|------|
+| `light` | ~10 | 核心服务：数据库 + Redis + RabbitMQ + MongoDB + Neo4j + Nginx + 3 个 qData 服务 |
+| `all` | ~22 | 全量：light + DolphinScheduler + Spark + Hadoop |
+| `local` | ~18 | 本地开发：all 但不含 Nginx |
+
+### 2.3 完整服务清单（22 个服务）
+
+**基础服务**：
+
+| 服务 | 镜像 | 端口 | Profile |
+|------|------|------|---------|
+| `redis` | redis:6-alpine | 6379 | all, light, local |
+| `rabbitmq` | rabbitmq:3.12-management | 5672, 15672 | all, light, local |
+| `nginx` | nginx:1.24.0 | 80 | all, light |
+| `dm8` | dm8:mixed | 5236 | all, light, schema |
+| `mysql` | mysql:8.0 | 3306 | all, light, schema |
+| `mongodb` | mongo:4.4 | 27017 | all, light, schema |
+| `neo4j` | neo4j:4.4.40 | 7474, 7687 | all, light, neo4j |
+
+**DolphinScheduler**：
+
+| 服务 | 端口 | 依赖 |
+|------|------|------|
+| `dolphinscheduler-postgresql` | 5432 | — |
+| `dolphinscheduler-zookeeper` | — | — |
+| `dolphinscheduler-api` | 12345, 25333 | zookeeper, rabbitmq |
+| `dolphinscheduler-alert` | — | zookeeper, rabbitmq |
+| `dolphinscheduler-master` | — | zookeeper, rabbitmq |
+| `dolphinscheduler-worker` | — | zookeeper, rabbitmq |
+
+**Spark + Hadoop**：
+
+| 服务 | 说明 |
+|------|------|
+| `spark` | Spark Master |
+| `spark-worker-1` | Spark Worker |
+| `namenode` | HDFS NameNode |
+| `datanode` | HDFS DataNode |
+| `resourcemanager` | YARN ResourceManager |
+| `nodemanager` | YARN NodeManager |
+
+**qData 服务**：
+
+| 服务 | 端口 | 依赖 |
+|------|------|------|
+| `qdata-api` | 8080 | redis, rabbitmq, dm8/mysql |
+| `qdata-service-quality` | 8083 | redis, rabbitmq, dm8/mysql, mongodb |
+| `qdata-service-ai` | 8087 | redis, rabbitmq, dm8/mysql |
+
+### 2.4 网络配置
+
+- 网络名称：`qdatanet`
+- 子网：`172.28.0.0/16`
+- 所有服务通过服务名互相访问（如 `redis`、`rabbitmq`、`dm8`）
+
+### 2.5 命名卷
+
+| 卷 | 用途 |
+|----|------|
+| `dolphinscheduler-postgresql` | DS PostgreSQL 数据 |
+| `dolphinscheduler-zookeeper` | ZooKeeper 数据 |
+| `dolphinscheduler-worker-data` | DS Worker 数据 |
+
+---
+
+## 三、部署管理脚本
+
+### 3.1 qdata.sh 命令
+
+| 命令 | 说明 |
+|------|------|
+| `start light` | 轻量模式启动 |
+| `start all` | 全量模式启动 |
+| `start local` | 本地开发模式 |
+| `stop` | 停止所有服务 |
+| `restart` | 重启 |
+| `status` | 查看服务状态 |
+| `logs` | 查看日志 |
+| `doctor` | 环境诊断 |
+| `uninstall` | 卸载 |
+
+### 3.2 启动选项
+
+| 选项 | 说明 |
+|------|------|
+| `--db dm8\|mysql` | 选择数据库类型 |
+| `--demo` | 启动演示数据库 |
+| `--offline` | 离线模式 |
+| `--force` | 强制重建 |
+
+### 3.3 预检检查
+
+| 检查项 | light 要求 | all/local 要求 |
+|--------|-----------|---------------|
+| Docker 版本 | ≥ 20.10.0 | ≥ 20.10.0 |
+| Compose 版本 | ≥ 2.20.2 | ≥ 2.20.2 |
+| CPU | ≥ 4 核 | ≥ 8 核 |
+| 内存 | ≥ 8 GB | ≥ 14 GB |
+| Linux 容器模式 | 是 | 是 |
+| Rootless Docker | 拒绝 | 拒绝 |
+| 端口可用性 | 检查 | 检查 |
+| 网络子网冲突 | 检查 | 检查 |
+| 包完整性 | 检查 | 检查 |
+
+---
+
+## 四、Nginx 配置
+
+### 4.1 主配置
+
+| 配置项 | 值 |
+|--------|-----|
+| Worker 进程 | 8 |
+| 最大连接数 | 3000 |
+| Gzip | 启用 |
+| 代理缓冲 | 启用 |
+| Keepalive | 300s |
+
+### 4.2 站点配置
+
+| 路径 | 目标 | 说明 |
+|------|------|------|
+| `/` | `/usr/share/nginx` | Vue SPA（`try_files $uri $uri/ /index.html`） |
+| `/prod-api` | `http://qdata-api:8080` | 主后端代理（剥离 `/prod-api/` 前缀） |
+| `/prod-ai` | `http://qdata-service-ai:8087` | AI 服务代理（剥离 `/prod-ai/` 前缀） |
+
+| 配置项 | 值 |
+|--------|-----|
+| `client_max_body_size` | 500M |
+| 代理超时 | 600s（connect/send/read） |
+| Keepalive | 600s |
+
+---
+
+## 五、环境变量
+
+### 5.1 qData 核心
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `QDATA_HUB` | 容器镜像仓库 | Aliyun ACR |
+| `QDATA_TAG` | 镜像标签 | `1.6.1` |
+| `DB_TYPE` | 数据库类型 | `dm8` |
+
+### 5.2 数据库
+
+**DM8**：
+
+| 变量 | 说明 |
+|------|------|
+| `CASE_SENSITIVE` | 大小写敏感（0） |
+| `INSTANCE_NAME` | 实例名（QDATA） |
+| `SYSDBA_PWD` | SYSDBA 密码 |
+| `QDATA_USER` / `QDATA_PWD` | 应用用户 |
+
+**MySQL**：
+
+| 变量 | 说明 |
+|------|------|
+| `MYSQL_ROOT_PASSWORD` | Root 密码 |
+| `MYSQL_DATABASE` | 数据库名（qdata） |
+| `MYSQL_USER` / `MYSQL_PASSWORD` | 应用用户 |
+
+### 5.3 中间件
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `REDIS_PASSWORD` | Redis 密码 | — |
+| `EXPOSE_REDIS_PORT` | Redis 端口 | 6379 |
+| `RABBITMQ_DEFAULT_USER` | RabbitMQ 用户 | admin |
+| `RABBITMQ_DEFAULT_PASS` | RabbitMQ 密码 | — |
+| `MONGO_INITDB_ROOT_USERNAME` | MongoDB 用户 | — |
+| `MONGO_INITDB_ROOT_PASSWORD` | MongoDB 密码 | — |
+
+### 5.4 DolphinScheduler
+
+| 变量 | 说明 |
+|------|------|
+| `DS_HUB` | DS 镜像仓库 |
+| `DS_TAG` | DS 镜像标签 |
+| `SPRING_DATASOURCE_URL` | DS 数据库 URL |
+| `REGISTRY_ZOOKEEPER_CONNECT_STRING` | ZooKeeper 地址 |
+| `SPRING_RABBITMQ_HOST/PORT/USERNAME/PASSWORD` | RabbitMQ 连接 |
+
+### 5.5 Spark + Hadoop
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `SPARK_MASTER_URL` | Spark Master | `spark://spark:7077` |
+| `SPARK_WORKER_MEMORY` | Worker 内存 | 5G |
+| `SPARK_WORKER_CORES` | Worker 核数 | 4 |
+| Hadoop 变量 | 30+ 个 | core-site.xml, hdfs-site.xml 等 |
+
+### 5.6 前端环境变量
+
+| 变量 | 开发 | 生产 |
+|------|------|------|
+| `VITE_APP_BASE_API` | `/dev-api` | `/prod-api/` |
+| `VITE_APP_BASE_AI` | `/dev-ai/` | `/prod-ai/` |
+| `VITE_APP_AUTH_TYPE` | `client` | `client` |
+| `VITE_APP_AES_KEY` | `AD42F6697B035B75` | `AD42F6697B035B75` |
+| `VITE_BUILD_COMPRESS` | — | `gzip` |
+
+---
+
+## 六、数据库版本管理
+
+### 6.1 SQL 脚本结构
+
+```
+sql/
+├── mysql/
+│   ├── initialization/    # 全量初始化脚本（V1.0.6 ~ V1.6.1 + latest）
+│   └── upgrade/           # 增量升级脚本
+├── dm/
+│   ├── initialization/    # DM8 初始化脚本
+│   └── upgrade/           # DM8 增量升级
+└── dolphinscheduler/
+    └── upgrade/           # DS 数据更新
+```
+
+### 6.2 版本升级路径（13 步）
+
+| 步骤 | 升级路径 | 变更规模 |
+|------|---------|---------|
+| 1 | V1.0.6 → V1.0.7 | 极小（76B 数据） |
+| 2 | V1.0.7 → V1.0.8 | 小（3.6KB） |
+| 3 | V1.0.8 → V1.1.0 | 极小（483B） |
+| 4 | V1.1.0 → V1.1.1 | 小（816B） |
+| 5 | V1.1.1 → V1.1.2 | 极小（314B） |
+| 6 | V1.1.2 → V1.2.0 | 中（5.6KB schema + 26.8KB data） |
+| 7 | V1.2.0 → V1.3.0 | 中（4.7KB schema + 5.8KB data） |
+| 8 | V1.3.0 → V1.4.0 | **大**（38.5KB schema + 19.8KB data） |
+| 9 | V1.4.0 → V1.5.2 | 中（8.2KB schema + 9.6KB data） |
+| 10 | V1.5.2 → V1.5.3 | 无变更 |
+| 11 | V1.5.3 → V1.5.4 | 小（1KB data only） |
+| 12 | V1.5.4 → V1.6.0 | 小（2.4KB schema only） |
+| 13 | V1.6.0 → V1.6.1 | 中（947B schema + 5.8KB data） |
+
+### 6.3 表数量增长
+
+| 版本 | 表数量 |
+|------|--------|
+| V1.0.6 ~ V1.1.2 | 746 |
+| V1.2.0 | 756 |
+| V1.3.0 | 761 |
+| V1.4.0 | 770 |
+| V1.5.4 | 770 |
+| V1.6.0 | 2,094 |
+| V1.6.1 | **2,095** |
+
+V1.6.0 发生了**重大 Schema 扩展**（+1,324 表），表数量从 770 激增至 2,094。
+
+---
+
+## 七、CI/CD
+
+### 7.1 GitHub Actions
+
+`.github/workflows/release.yml` 实现 **Release 自动化**：
+
+- **触发条件**：推送 `v*` 标签
+- **功能**：从注解标签提取 Release Notes，通过 `gh release create` 创建/更新 GitHub Release
+- **不包含**：构建产物、运行测试、推送 Docker 镜像
+
+### 7.2 Docker 镜像
+
+Dockerfile 位于：
+
+| 服务 | Dockerfile 路径 |
+|------|----------------|
+| qdata-server | `qdata-server/docker/Dockerfile` |
+| qdata-service-quality | `qdata-service-quality/docker/Dockerfile` |
+| qdata-service-ai | `qdata-ai-server/docker/Dockerfile` |
+
+镜像推送到 Aliyun ACR（`crpi-kf13onfj0v8f6jax.cn-shanghai.personal.cr.aliyuncs.com/qiantongkeji`）。
+
+---
+
+## 八、API 文档配置
+
+| 配置项 | 值 |
+|--------|-----|
+| 框架 | SpringDoc OpenAPI 3 + Knife4j |
+| 分组 | `system`, `example`, `ai`, `dm` |
+| Swagger UI | `/swagger-ui.html` |
+| API Docs | `/v3/api-docs` |
+| Knife4j | 启用（zh-CN，基础认证 test/12313） |
+| i18n | `SwaggerI18nCustomizer` 运行时翻译 `@Tag` 和 `@Operation` |
+
+---
+
+## 九、部署前置条件
+
+| 组件 | 版本要求 |
+|------|---------|
+| JDK | 1.8（AI 服务需 17） |
+| Node.js | 18+ |
+| yarn | v1.22.22+ |
+| Maven | 3.6+ |
+| Docker | 20.10.0+ |
+| Docker Compose | 2.20.2+ |
+| DM8 | 大小写不敏感，GB18030 编码 |
+| Redis | 5.0+ |
+| RabbitMQ | 任意版本 |
+
+---
+
+## 十、前端构建配置
+
+### 10.1 开发服务器
+
+| 配置 | 值 |
+|------|-----|
+| 端口 | 81 |
+| host | true |
+| 自动打开浏览器 | 是 |
+
+### 10.2 代理规则
+
+| 路径 | 目标 | 重写 |
+|------|------|------|
+| `/dev-api` | `http://localhost:8080` | 剥离前缀 |
+| `/dev-ai` | `http://localhost:8087` | 剥离前缀 |
+| `/jmreport` | `http://localhost:8080` | 无 |
+| `/v3/api-docs` | `http://localhost:8080` | 无 |
+
+### 10.3 Vite 插件
+
+| 插件 | 说明 |
+|------|------|
+| `@vitejs/plugin-vue` | Vue 3 SFC 支持 |
+| `unplugin-auto-import` | Vue/Router/Pinia API 自动导入 |
+| `unplugin-vue-setup-extend-plus` | `<script setup>` 命名扩展 |
+| `vite-plugin-svg-icons` | SVG 图标精灵（197 个） |
+| `vite-plugin-compression` | Gzip/Brotli 压缩（构建时） |
+| `vite-plugin-monaco-editor-esm` | Monaco Editor ESM 支持 |
+
+### 10.4 构建优化
+
+- **手动 chunk 拆分**：每个 `node_modules` 包独立分包
+- **路径别名**：`~` → 项目根，`@` → `src/`
+- **支持扩展名**：`.mjs`, `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.vue`
+- **PostCSS**：移除 SCSS `@charset` 警告

docs/project/qdata/index.md

@@ -0,0 +1,33 @@
+# qData 技术报告
+
+> 基于源码深度分析，非文档推测 | 生成日期：2026-08-27
+
+---
+
+## 报告索引
+
+| 序号 | 报告 | 内容概述 |
+|------|------|---------|
+| 01 | [前后端架构报告](architecture.md) | 后端分层架构（146 Controller / 1,242 端点）、前端 Vue 3 架构（405 Vue 文件）、认证机制、前后端交互模型 |
+| 02 | [数据治理与 ETL 报告](data-governance-etl.md) | DataX + Spark 双引擎 ETL、数据开发（4 种任务类型）、数据质量（9 种规则）、元数据管理、数据资产、数据服务 API、数据建模、数据治理、AI Text2SQL |
+| 03 | [部署与基础设施报告](deployment.md) | Docker Compose 编排（22 个服务）、Nginx 配置、环境变量、数据库版本管理（V1.0.6→V1.6.1）、CI/CD、API 文档 |
+| 04 | [简历技术要点](resume.md) | 8 个技术要点提炼：双引擎 ETL、动态 API 发布、元数据采集、质量规则引擎、DolphinScheduler 集成、AI Text2SQL、Docker 全栈编排 |
+
+---
+
+## 快速参考
+
+| 项目 | 值 |
+|------|-----|
+| qData 主服务端口 | 8080 |
+| AI 服务端口 | 8087 |
+| 质量服务端口 | 8083 |
+| 前端开发端口 | 81 |
+| 前端生产端口 | 80（Nginx） |
+| 主入口 | `QDataApplication.java` |
+| 前端入口 | `qdata-ui/src/main.js` |
+| 版本 | 1.6.1 |
+| 后端框架 | Spring Boot 2.5.15 / Java 8 |
+| 前端框架 | Vue 3.5.21 / Vite 5.3.2 |
+| 数据库表 | 2,095 |
+| REST 端点 | 1,242 |

docs/project/qdata/resume.md

@@ -0,0 +1,51 @@
+# QDATA 简历技术要点
+
+> 基于项目源码实际实现提炼，每个要点均可深入到函数级别展开
+
+---
+
+## 1. 设计并落地企业级数据中台架构（16 模块 / 1,242 端点 / 2,095 表）
+
+基于 Spring Boot 2.5.15 构建 Maven 多模块单体架构，采用 **api + biz** 拆分模式实现 10 个业务模块（system/att/da/dg/dm/dp/dp/ds/mc/ai）+ 12 个框架子模块（auth/common/config/file/generator/mybatis/neo4j/pay/quartz/redis/security/websocket）的分层治理。后端共 **146 个 Controller** 暴露 **1,242 个 REST 端点**，**143 个 MyBatis Mapper** 操作 **2,095 张数据库表**，模型层包含 118 个 DO + 403 个 VO + 223 个 DTO。通过 Spring Security 5.7.12 + JWT（HS512）实现无状态认证，Token 存入 Redis（`login_tokens:{uuid}`，TTL 600min），剩余 20 分钟自动续期；同时基于 SA-Token 实现 OAuth 2.0 全四种授权模式（Authorization Code / Implicit / Password / Client Credentials）。前端 Vue 3.5.21 + Element Plus 2.7.6 构建 405 个 Vue 组件，8 个 Pinia Store 管理全局状态，91 个路由（18 个公开 + 4 个动态模块）通过后端菜单接口动态注入，`import.meta.glob` 实现组件懒加载。
+
+---
+
+## 2. 实现 DataX + Spark 双引擎 ETL 管线（7 种 Reader/Transition + 3 种写入模式）
+
+DataX 引擎通过 `DataXExecutor` 以 Python 子进程方式执行 `python3 datax.py job.json`，`DataXJsonBuilder` 动态生成 Reader/Writer/Processor 配置，支持 VALUE_MAP、ADD_CONSTANT、SELECT_FIELDS、FIELD_DERIVATION 四种处理器。Spark 引擎（`EtlApplication.main()`）接收 DolphinScheduler 传递的 Base64 编码 JSON 参数，执行 ReaderFactory → TransitionFactory（CleanTransition 31KB 最复杂 / SortTransition / FieldDerivationTransition / DataDeduplicationTransition / ValueMapTransition / AddConstantTransition / SelectFieldsTransition）→ WriterFactory 管线。DBReader 支持全量、ID 增量（Redis 游标 `ETL_READER_ID_KEY + nodeCode + ":" + incrementColumn`）、时间范围增量三种模式；DBWriter 支持全量（临时表+重命名交换）、追加、增量更新（PreparedStatement 批处理 Upsert）三种写入策略，方言适配 Kingbase8/SQL Server/Doris 的表重命名操作。任务状态通过 RabbitMQ 异步上报（交换机 `ds.exchange.processInstance` / `ds.exchange.taskInstance`），避免 Spark 任务直接调用 DolphinScheduler REST API。
+
+---
+
+## 3. 构建运行时动态 API 发布引擎（数据表/SQL → REST 端点）
+
+基于 Spring `RequestMappingHandlerMapping` 实现运行时 API 动态注册/注销，`MappingHandlerMapping` 维护 `ConcurrentHashMap<String, DsApiDO>` 映射表，URL 模式 `/services/{version}/{path}`。`RequestHandler` 通过 `@DsCheckClientToken` 注解拦截请求，支持 4 种服务类型（数据服务/模型数据服务/第三方 API 代理/文件服务）和 3 种响应类型（详情/列表/分页）。`DsApiServiceImpl.sqlParse()` 使用 JSqlParser 解析 SQL 提取请求参数和响应字段，`sqlJdbcNamedParameterBuild()` 从表单配置生成带命名参数的多数据库方言 SQL（Kingbase8/PostgreSQL/SQL Server/MySQL/Oracle）。`ApiMappingEngine` 执行 SQL 查询并按响应类型格式化结果，异步 `AsyncTask.doTask(DsApiLogDO)` 记录调用日志，客户端认证通过独立的 JWT 机制（7 天 Token + 30 天 Refresh Token）实现。
+
+---
+
+## 4. 实现自动化元数据采集与变更检测系统（6 种方言 + 9 类变更追踪）
+
+`McTaskServiceImpl.runDaDiscoveryTask()` 通过 Redis 分布式锁防重执行，按"加载数据库范围 → 对比数据库列表 → 对比表列表 → 对比列信息"四层递进采集元数据。变更检测覆盖 9 类列级变更（注释/类型/长度/精度/小数位/默认值/主键/外键/可空）和 4 类表级变更（注释/字段增删改/索引变更/存储大小）。`DatabaseDialectFactory` 注册 6 种数据库方言（MySQL/Hive/DM8 完整实现，Oracle/PostgreSQL/SQL Server 占位），每种方言实现 `getStorageEngine()`、`getTableRowCount()`、`getTableIndexes()`、`getTablePartitionFields()`、`isColumnAutoIncrement()` 等方法。Neo4j 图数据库通过 `TableNode`（`@Node("Table")`）和 `TaskNode`（`@Node("Task")`）两种节点类型、`TABLE_TO_TASK` 和 `TASK_TO_TABLE` 两种关系类型构建数据血缘图谱，`LineageDataService` 支持 Cypher 查询遍历上下游 Table → Task → Table 链路。
+
+---
+
+## 5. 设计数据质量规则引擎（9 种规则生成器 + 6 种数据库方言 + MongoDB 错误存储）
+
+`qdata-service-quality` 独立微服务（端口 8083）采用工厂模式，`QualitySqlGenerateFactory` 通过 Spring `Map<String, QualitySqlGenerator>` 按 bean 名称自动注入 9 种规则生成器（CharacterValidation / CompositeUniqueness / DecimalPrecision / EnumValidation / GroupFieldCompleteness / LengthValidation / NumericRangeValidation / TimeOrderValidation / Common），每种生成器实现 `generateSql()`、`generateErrorSql()`、`generateValidDataSql()` 三个方法。`ComponentRegistry` 注册 6 种数据库方言（MySQL/Oracle12c/Oracle/SQL Server/DM8/Default），将规则 SQL 翻译为目标数据库方言。`QualityTaskExecutorServiceImpl.executeTask()` 通过 `ThreadPoolTaskExecutor` 异步执行 + Redis 去重锁，按数据源分组后逐条执行规则，错误数据存入 MongoDB（`CheckErrorData` 文档），支持 3 种修改方式（修改数据+更新物理表 / 修改备注 / 修改修复状态）。
+
+---
+
+## 6. 集成 DolphinScheduler 分布式调度（31 个 API 端点 + RabbitMQ 回调）
+
+`qdata-api-ds` 模块通过 `DsRequestUtils` 封装 HTTP 调用（`ds.base_url` + `ds.token` header），定义 `QianTongDCApiType` 枚举覆盖 DolphinScheduler 31 个 API 端点（项目管理 4 个 / 流程定义 11 个 / 调度管理 6 个 / 执行管理 2 个 / 监控查询 5 个 / 任务编码 1 个）。5 个 Service 实现类（`DsProjectServiceImpl` / `DsEtlTaskServiceImpl` / `DsEtlNodeServiceImpl` / `DsEtlSchedulerServiceImpl` / `DsEtlExecutorServiceImpl`）封装项目创建、流程定义发布/下线、调度上线/下线、流程实例执行等操作。ETL Spark 任务通过 RabbitMQ 回调（而非直接 HTTP 调用），交换机 `ds.exchange.processInstance` / `ds.exchange.taskInstance` 配合路由键实现异步状态上报，后端 `TaskLogListener` / `ProcessListener` / `TaskListener` 消费消息并更新 DolphinScheduler 状态。同时支持 Quartz 进程内调度作为轻量级替代方案，通过 `ScheduleConstants.QUARTZ` / `ScheduleConstants.DOLPHINSCHEDULER` 动态切换。
+
+---
+
+## 7. 构建 AI 智能问数平台（19 个 AI 平台 + Text2SQL + 事实-维度表自动匹配）
+
+基于 Spring AI 框架集成 19 个 AI 平台（国内 11 个：通义千问/文心一言/DeepSeek/智谱/星火/豆包/混元/SiliconFlow/MiniMax/Moonshot/百川；海外 8 个：OpenAI/Azure OpenAI/Anthropic/Gemini/Ollama/StableDiffusion/Midjourney/Suno/Grok），通过 `AiPlatformEnum` 统一管理。`StatisticsPromptBuilder` 实现 Text2SQL 生成，支持星型模型（事实表 + 维度表 + 事实-维度关联），数据库方言感知（MySQL/DM8/Oracle/Kingbase8/PostgreSQL/SQL Server/Doris），双回复模式（CHART 模式返回 SQL+维度+度量+时间粒度用于图表渲染，QA 模式返回文本或 SQL 用于问答）。`MatchPromptBuilder` 使用 AI 自动匹配事实表与维度表的关联关系，输入事实表元数据和维度表列表，输出 JSON 格式的关联关系（维度表/事实列名/维度列名/匹配原因）。`qdata-service-ai` 独立部署（JDK 17，端口 8087），通过 `DualServiceImpl` 实现 12 个空桩接口使其可脱离其他微服务独立运行。
+
+---
+
+## 8. 实现 Docker Compose 全栈编排（22 个服务 / light + all 双模式 / 预检体系）
+
+通过 10 个 docker-compose 文件（base/dolphinscheduler/spark/hadoop/qdata/demo）模块化编排 **22 个服务**，使用 `include` 指令组合（需 Compose v2.20.2+）。支持 `light`（~10 服务，4CPU/8GB）和 `all`（~22 服务，8CPU/14GB）两种部署模式。`qdata.sh` 管理脚本提供 start/stop/restart/status/logs/doctor/uninstall 命令，内置 comprehensive 预检体系：Docker 版本（≥20.10.0）、Compose 版本（≥2.20.2）、Linux 容器模式检测、Rootless Docker 拒绝、CPU/内存校验、端口可用性检查、网络子网冲突检测（`172.28.0.0/16`）、包完整性验证。Nginx 反向代理配置 `/prod-api` → `qdata-api:8080`、`/prod-ai` → `qdata-service-ai:8087`，`client_max_body_size 500M`，代理超时 600s。数据库版本管理覆盖 V1.0.6 到 V1.6.1 共 13 步增量升级路径，V1.6.0 发生重大 Schema 扩展（表数量从 770 激增至 2,094）。

mkdocs.yml

@@ -89,6 +89,12 @@ nav:
     - Open-API 计费平台:
       - project/openapi-billing-architecture.md
       - 简历技术要点: project/openapi-billing-resume.md
+    - qData 数据中台:
+      - project/qdata/index.md
+      - 前后端架构: project/qdata/architecture.md
+      - 数据治理与ETL: project/qdata/data-governance-etl.md
+      - 部署与基础设施: project/qdata/deployment.md
+      - 简历技术要点: project/qdata/resume.md
   - 架构:
     - architecture/index.md
     - 缓存: