CapacityReport/docs/platform_architecture_plan.md

数据处理平台架构设计

目标

建设一个通用的数据处理平台，用于接入 FTP/SFTP 等远程数据源，处理压缩包、CSV、XLSX 等报表文件，完成入库、清洗、合并、脚本执行、定时任务和结果查询。平台后续不绑定单一报表类型，容量报表只是一个业务应用或任务模板。

当前 CapaReport 项目只作为参考和代码借鉴来源。新平台前期放在当前项目根目录的 platform/ 目录下开发，该目录已加入 CapaReport 的 .gitignore，避免影响当前项目提交。

隔离边界

platform/ 是完全独立的新平台工作区，只是临时放在当前项目根目录下，方便开发时查看和参考 CapaReport 的现有实现。该目录下的所有内容都不属于 CapaReport 项目。

必须遵守以下边界：

• 不使用 CapaReport 的 Python 虚拟环境，例如 .venv/、venv/。
• 不使用 CapaReport 的 Python 依赖文件，例如 requirements.txt。
• 不使用 CapaReport 的启动脚本、构建脚本或运行配置。
• 不使用 CapaReport 的前端依赖目录，例如 frontend/node_modules/。
• 不使用 CapaReport 的前端构建配置或包管理文件，例如 frontend/package.json、frontend/package-lock.json、frontend/vite.config.ts。
• 不从 CapaReport 的 app/、frontend/、src-tauri/ 等目录直接导入代码。
• 不读取或依赖 CapaReport 的 Configure.json、ReportScript.sql、缓存、日志、授权文件或本地运行数据。
• 不把 platform/ 的代码、依赖、配置或生成物提交到 CapaReport 仓库。
• 如需复用思路，只能按模块职责重新实现或后续抽取为独立仓库，不能形成对当前项目目录的运行时依赖。

设计原则

• 只做 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 入库、任务日志。第一版不要急着覆盖所有报表，先跑通“远程目录到数据库结果表”的稳定链路。