318 lines
13 KiB
Markdown
318 lines
13 KiB
Markdown
# 数据处理平台架构设计
|
|
|
|
## 目标
|
|
|
|
建设一个通用的数据处理平台，用于接入 FTP/SFTP 等远程数据源，处理压缩包、CSV、XLSX 等报表文件，完成入库、清洗、合并、脚本执行、定时任务和结果查询。平台后续不绑定单一报表类型，容量报表只是一个业务应用或任务模板。
|
|
|
|
当前 CapaReport 项目只作为参考和代码借鉴来源。新平台前期放在当前项目根目录的 `platform/` 目录下开发，该目录已加入 CapaReport 的 `.gitignore`，避免影响当前项目提交。
|
|
|
|
## 设计原则
|
|
|
|
- 只做 Web 平台，不再引入桌面端打包形态。
|
|
- 后端使用 Python，前端使用 Web 技术栈。
|
|
- 模块之间通过明确接口协作，避免一个模块同时承担下载、解析、入库、SQL 执行等多种职责。
|
|
- 每个核心模块独立 Git 仓库维护，平台主仓库通过 submodule 组合。
|
|
- 先保证文件接入、数据入库、任务执行、结果查询这条主链路稳定，再扩展更多报表和自动化能力。
|
|
- 当前阶段避免过度抽象，模块边界清晰即可，插件化能力按真实需求逐步增强。
|
|
|
|
## 仓库与目录组织
|
|
|
|
平台根目录建议为独立 Git 仓库，放在当前项目的 `platform/` 下。本目录不进入 CapaReport 仓库。
|
|
|
|
建议平台主仓库负责：
|
|
|
|
- 应用启动与服务编排。
|
|
- 全局配置、认证、权限、审计、任务调度。
|
|
- 前后端集成。
|
|
- submodule 版本锁定。
|
|
- 平台级文档和部署脚本。
|
|
|
|
建议 submodule 放在平台主仓库的 `modules/` 下：
|
|
|
|
| 模块仓库 | 职责 |
|
|
| --- | --- |
|
|
| `platform-core` | 应用核心模型、配置、任务状态、事件、日志、通用接口约定 |
|
|
| `source-remote` | FTP/SFTP 连接、目录扫描、文件下载、远端删除、连接测试 |
|
|
| `file-processing` | 解压缩、文件识别、CSV/XLSX 读取、字段映射、数据标准化、临时文件管理 |
|
|
| `database-service` | 数据库连接、库表管理、数据入库策略、SQL 执行、结果查询、导出 |
|
|
| `job-runner` | 手动任务、定时任务、脚本任务、任务依赖、失败重试、运行历史 |
|
|
| `web-ui` | Web 界面、配置管理、任务监控、数据管理、脚本管理、API 文档 |
|
|
| `api-client-contracts` | 前后端共享的 API 契约、类型约定、错误码和响应结构 |
|
|
|
|
早期可以减少仓库数量，例如先保留 `platform-core`、`source-remote`、`file-processing`、`database-service`、`web-ui` 五个模块。等脚本和调度复杂度上来后，再把 `job-runner` 独立出去。
|
|
|
|
## 模块职责
|
|
|
|
### 平台核心模块
|
|
|
|
平台核心模块只负责平台级能力，不处理具体业务数据。
|
|
|
|
核心职责：
|
|
|
|
- 任务、运行记录、数据源、数据集、文件、脚本、调度计划等基础模型。
|
|
- 统一日志、错误码、状态流转和事件通知。
|
|
- 配置读取、配置校验、敏感信息存储策略。
|
|
- 模块注册和服务发现。
|
|
- 认证、Token、权限、审计的基础接口。
|
|
|
|
不应承担：
|
|
|
|
- FTP/SFTP 协议细节。
|
|
- CSV/XLSX 解析细节。
|
|
- 具体数据库 SQL 方言。
|
|
- 具体业务报表规则。
|
|
|
|
### FTP/SFTP 模块
|
|
|
|
远程数据源模块只负责“远程文件发现和传输”。
|
|
|
|
核心职责：
|
|
|
|
- FTP/SFTP 连接配置、测试、目录递归扫描。
|
|
- 远程文件列表、文件大小、修改时间、文件名时间范围识别辅助信息。
|
|
- 按规则下载文件和目录。
|
|
- 下载完成后的远端源文件删除，只删除文件不删除目录。
|
|
- 网络异常、断连、重试、超时控制。
|
|
|
|
不应承担：
|
|
|
|
- 解压缩。
|
|
- CSV/XLSX 字段解析。
|
|
- 数据入库。
|
|
- SQL 脚本执行。
|
|
|
|
### 文件处理模块
|
|
|
|
文件处理模块负责把原始文件转成“可入库的数据批次”。
|
|
|
|
核心职责：
|
|
|
|
- ZIP 等压缩包解压，保留原始数据和清理临时展开文件。
|
|
- CSV/XLSX 文件识别、编码识别、Sheet 过滤、表头识别。
|
|
- 字段映射、类型转换、空值和异常值标准化。
|
|
- 文件名日期解析、按目录选择最近 N 天或目标周期数据。
|
|
- 生成数据批次元信息，例如来源文件、字段列表、行数、日期范围、目标逻辑表。
|
|
- 为数据库模块提供流式或分块数据输入。
|
|
|
|
不应承担：
|
|
|
|
- 真实数据库连接管理。
|
|
- 建表、删表、查表。
|
|
- SQL 脚本执行。
|
|
- 结果表查询。
|
|
|
|
### 数据库模块
|
|
|
|
数据库模块负责“数据库侧”的所有能力。
|
|
|
|
核心职责：
|
|
|
|
- 数据库连接配置、连接池、连接测试。
|
|
- 数据库、表、字段、索引管理。
|
|
- 数据入库策略：批量插入、数据库原生加载、临时表、落地中间文件。
|
|
- SQL 脚本执行、SQL 查询、结果分页、结果导出。
|
|
- 表结构查看、表数据管理、权限控制下的数据修改。
|
|
- 多数据库适配的接口预留，早期以 MySQL 为主。
|
|
|
|
数据入库边界建议：
|
|
|
|
- 文件处理模块负责解析、清洗、标准化和分批输出。
|
|
- 数据库模块负责选择入库方式并执行入库。
|
|
- 业务任务模块只编排“先处理文件，再入库，再执行脚本”，不直接操作底层文件或数据库细节。
|
|
|
|
性能取舍：
|
|
|
|
- 大 CSV 优先走数据库原生批量加载能力。
|
|
- 原生加载不可用时使用分块批量插入。
|
|
- XLSX 不应整文件无脑载入内存，优先采用流式读取或按 Sheet 分块处理。
|
|
- 大任务必须有进度、行数、速度、当前阶段和失败定位。
|
|
|
|
### 任务与脚本模块
|
|
|
|
任务模块负责“什么时候做、做什么、做到哪一步”。
|
|
|
|
核心职责：
|
|
|
|
- 手动上传处理、远程下载处理、定时扫描处理。
|
|
- SQL 脚本、Python 脚本和后续其他脚本类型的执行入口。
|
|
- 任务状态、阶段、日志、运行历史、失败重试。
|
|
- 调度策略：按小时扫描、按文件日期判断就绪、就绪后延迟触发。
|
|
- 任务互斥、取消、超时、异常恢复。
|
|
|
|
任务模块不直接解析文件，也不直接写数据库底层逻辑，只调用文件处理模块和数据库模块。
|
|
|
|
### Web 界面模块
|
|
|
|
Web 界面模块负责平台交互，不包含业务处理逻辑。
|
|
|
|
核心页面建议：
|
|
|
|
- 数据源配置：FTP/SFTP、连接测试、远端目录、删除源文件策略。
|
|
- 文件处理配置：Sheet 过滤、字段映射、文件日期规则、目标表规则。
|
|
- 数据库配置：连接、库表管理、数据查询、导出、SQL 执行。
|
|
- 任务中心：手动运行、远程运行、定时任务、运行历史、日志。
|
|
- 脚本中心：SQL/Python 脚本编辑、版本、执行记录。
|
|
- API Token 与 API 文档。
|
|
- 系统设置：用户、权限、历史保留、平台运行参数。
|
|
|
|
界面模块只调用 API，不直接耦合后端模块内部实现。
|
|
|
|
## 核心数据流
|
|
|
|
平台主链路建议分为以下阶段：
|
|
|
|
1. 数据源扫描：远程模块返回文件清单和基础元信息。
|
|
2. 数据选择：任务模块根据调度规则和文件日期规则选择待处理文件。
|
|
3. 数据获取：远程模块下载文件，形成原始数据目录。
|
|
4. 文件展开：文件处理模块解压压缩包并识别 CSV/XLSX。
|
|
5. 数据标准化：文件处理模块完成编码、字段、类型、空值、异常值处理。
|
|
6. 数据入库：数据库模块按入库策略写入目标库表。
|
|
7. 脚本处理：任务模块调用数据库模块执行 SQL 或调用脚本执行器。
|
|
8. 结果输出：数据库模块提供结果表查询、导出和 API 查询。
|
|
9. 历史归档：任务模块记录原始数据、日志、结果、运行耗时和错误信息。
|
|
10. 清理策略：按配置清理临时文件、历史记录和远端源文件。
|
|
|
|
## 关键模型
|
|
|
|
建议平台统一维护以下概念：
|
|
|
|
| 模型 | 含义 |
|
|
| --- | --- |
|
|
| 数据源 | FTP/SFTP、本地目录或未来其他来源 |
|
|
| 文件清单 | 一次扫描得到的远程或本地文件列表 |
|
|
| 数据集 | 一批准备处理的数据，可以来自上传或远程下载 |
|
|
| 处理配置 | 字段映射、Sheet 过滤、文件日期规则、目标表规则 |
|
|
| 任务 | 一次手动或自动触发的处理动作 |
|
|
| 运行记录 | 任务的一次实际运行，包含状态、阶段、日志、耗时 |
|
|
| 数据批次 | 文件处理模块输出给数据库模块的标准化数据 |
|
|
| 脚本 | SQL、Python 或其他脚本类型 |
|
|
| 结果资源 | 结果表、导出文件、日志、原始数据归档 |
|
|
|
|
## 配置设计
|
|
|
|
配置应分层：
|
|
|
|
- 平台配置：端口、认证、历史保留、日志、存储目录。
|
|
- 数据源配置：协议、地址、端口、账号、目录、超时、删除源文件策略。
|
|
- 文件处理配置：文件类型、压缩包规则、字段映射、日期解析、异常值策略。
|
|
- 数据库配置：连接、目标库、入库策略、表名前缀、大小写兼容。
|
|
- 任务配置：调度周期、目标日期规则、失败重试、并发限制。
|
|
- 脚本配置：脚本类型、执行环境、参数、权限。
|
|
|
|
敏感配置可以先支持明文内网部署，后续再增加加密存储或密钥管理。
|
|
|
|
## API 设计方向
|
|
|
|
API 应按资源分组，而不是按页面分组。
|
|
|
|
建议资源：
|
|
|
|
- 数据源 API。
|
|
- 文件与数据集 API。
|
|
- 数据库 API。
|
|
- 任务 API。
|
|
- 脚本 API。
|
|
- 历史 API。
|
|
- Token 与用户 API。
|
|
- 系统配置 API。
|
|
|
|
外部系统接入时优先通过 Token 调用任务和查询 API。API 文档应自动生成，并为常用接口提供中文说明、参数示例和错误说明。
|
|
|
|
## 调度设计
|
|
|
|
调度不应依赖服务器系统时间判断数据是否已经推送完成，应优先依据文件名中的数据日期或文件清单中的业务日期。
|
|
|
|
建议支持：
|
|
|
|
- 每隔固定时间扫描远程目录。
|
|
- 按目录判断目标日期是否齐全。
|
|
- 空目录可配置为停推目录并跳过。
|
|
- 日粒度和周粒度文件按文件名自动识别。
|
|
- 就绪后先写入就绪标识，下一轮扫描再触发处理，避免刚推送完成时立即下载半成品。
|
|
- 处理成功后按配置删除远端源文件，并清除就绪标识。
|
|
|
|
日粒度与周粒度规则必须配置化，避免不同目录、不同厂家、不同报表命名习惯互相影响。
|
|
|
|
## 存储与历史
|
|
|
|
建议保留以下目录概念：
|
|
|
|
- 原始数据目录：保存下载或上传的原始文件。
|
|
- 临时处理目录：保存解压后的 CSV/XLSX、中间转换文件。
|
|
- 归档目录：保存可追溯的任务原始数据和日志。
|
|
- 导出目录：保存临时导出文件，下载完成后自动清理。
|
|
- 脚本目录：保存 SQL、Python 等脚本。
|
|
|
|
处理历史应支持：
|
|
|
|
- 查看任务详情、阶段、日志。
|
|
- 下载完整原始数据包。
|
|
- 单文件或单目录下载。
|
|
- 按保留次数或保留天数清理。
|
|
- 清理临时文件但不误删原始归档。
|
|
|
|
## 当前项目可复用经验
|
|
|
|
当前 CapaReport 可作为参考的能力：
|
|
|
|
- FTP/SFTP 下载、远程删除、连接测试。
|
|
- 文件名日期解析和最近 N 天筛选。
|
|
- ZIP 解压、CSV/XLSX 处理、字段映射。
|
|
- MySQL 表管理、数据查询、CSV/XLSX 导出。
|
|
- SQL 脚本执行和日志展示。
|
|
- 处理历史、原始数据下载、临时文件清理。
|
|
- API Token、OpenAPI 文档、Web 管理界面。
|
|
- 自动调度的就绪标识和二次触发机制。
|
|
|
|
迁移时应避免直接复制成一个巨型模块，应先按职责拆分，再逐步搬运可复用逻辑。
|
|
|
|
## 开发路线
|
|
|
|
### 阶段一：平台骨架
|
|
|
|
- 建立 `platform/` 独立仓库。
|
|
- 明确模块 submodule 目录。
|
|
- 建立后端 Web 服务、前端壳、基础认证、配置读写。
|
|
- 接入一个最小远程数据源配置和连接测试。
|
|
|
|
### 阶段二：文件到数据库主链路
|
|
|
|
- 完成远程下载、本地上传、解压、CSV/XLSX 识别。
|
|
- 完成字段映射和基础类型转换。
|
|
- 完成 MySQL 入库、表管理、数据查询。
|
|
- 建立任务状态、日志和历史记录。
|
|
|
|
### 阶段三：脚本与调度
|
|
|
|
- 支持 SQL 脚本执行。
|
|
- 支持定时扫描远程目录。
|
|
- 支持按目录和日期判断数据就绪。
|
|
- 支持处理成功后删除远端源文件。
|
|
|
|
### 阶段四：业务模板化
|
|
|
|
- 将容量报表作为一个业务模板接入平台。
|
|
- 增加更多报表模板和处理脚本。
|
|
- 支持任务参数、脚本参数、结果表配置。
|
|
|
|
### 阶段五：平台增强
|
|
|
|
- 增加权限细分、审计、任务重试、告警。
|
|
- 增加更多数据库适配。
|
|
- 增加模块版本管理和升级策略。
|
|
|
|
## 风险与决策点
|
|
|
|
| 风险 | 建议 |
|
|
| --- | --- |
|
|
| 模块拆得太细导致开发慢 | 早期只拆核心边界，复杂后再独立仓库 |
|
|
| 文件处理和数据库入库职责混乱 | 坚持文件模块输出标准数据批次，数据库模块负责落库 |
|
|
| 大文件处理性能不足 | 优先流式、分块、数据库原生批量加载 |
|
|
| 不同报表命名规则不一致 | 日期解析和周期规则配置化 |
|
|
| 脚本权限风险 | 脚本执行入口必须有权限控制和审计记录 |
|
|
| submodule 管理复杂 | 主仓库锁版本，模块仓库保持独立发布说明 |
|
|
|
|
## 近期建议
|
|
|
|
先在 `platform/` 下建立独立平台主仓库，再从 CapaReport 中抽取最小可用能力：远程连接测试、文件日期解析、CSV 入库、任务日志。第一版不要急着覆盖所有报表，先跑通“远程目录到数据库结果表”的稳定链路。
|