# 数据处理平台架构设计 ## 目标 建设一个通用的数据处理平台，用于接入 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 入库、任务日志。第一版不要急着覆盖所有报表，先跑通“远程目录到数据库结果表”的稳定链路。