171 lines
8.9 KiB
Markdown
171 lines
8.9 KiB
Markdown
# CapacityReport 开发文档
|
||
|
||
面向二次开发者，介绍项目实际用到的技术栈、目录结构，以及导航栏每个功能对应的代码文件，方便快速定位要修改的位置。
|
||
|
||
## 技术栈与主要库
|
||
|
||
### 后端（Python）
|
||
|
||
| 库 | 用途 |
|
||
| --- | --- |
|
||
| fastapi / uvicorn | Web 框架与 ASGI 服务器 |
|
||
| python-multipart | 文件上传表单解析 |
|
||
| pandas / openpyxl | Excel/CSV 数据读取与处理 |
|
||
| chardet | CSV 编码探测 |
|
||
| pymysql | 直连 MySQL 读写 |
|
||
| cryptography | 本地授权文件加密 |
|
||
| paramiko | SFTP 远程下载 |
|
||
|
||
### 前端（Vue 3）
|
||
|
||
| 库 | 用途 |
|
||
| --- | --- |
|
||
| vue / vue-router | 框架与路由 |
|
||
| naive-ui | UI 组件库 |
|
||
| @vicons/ionicons5 | 图标 |
|
||
| echarts | 容量看板图表 |
|
||
| monaco-editor | 脚本编辑页的 SQL 编辑器 |
|
||
| @tauri-apps/api | 桌面端与原生能力交互 |
|
||
| vite / vue-tsc / typescript | 构建与类型检查 |
|
||
| unplugin-auto-import / unplugin-vue-components | Naive UI 组件按需自动导入 |
|
||
|
||
### 桌面端（Tauri 2 / Rust）
|
||
|
||
| 库 | 用途 |
|
||
| --- | --- |
|
||
| tauri | 桌面应用框架 |
|
||
| tauri-plugin-shell | 启动并管理后端 sidecar 进程 |
|
||
| tauri-plugin-dialog | 文件保存对话框 |
|
||
| reqwest | 下载文件到本地 |
|
||
| sysinfo | 跨平台进程检测与清理 |
|
||
| open | 调用系统文件管理器打开目录 |
|
||
| serde | 序列化 |
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
CapacityReport/
|
||
├─ app/ # 后端（FastAPI）
|
||
│ ├─ main.py # 入口：创建应用、鉴权中间件、注册路由、托管前端
|
||
│ ├─ state.py # 运行时共享状态（配置、历史、任务锁、上传会话）
|
||
│ ├─ config.py # 配置读写（AppConfig 与各配置块）
|
||
│ ├─ auth.py # 登录账号（auth.ini）、JWT、密码修改
|
||
│ ├─ db_init.py # 启动时确保必要数据表存在
|
||
│ ├─ database.py # DatabaseManager：直连 MySQL 表操作
|
||
│ ├─ warehouse.py # 数据库访问的统一封装
|
||
│ ├─ processor.py # DataProcessor：解压/转换/入库/执行报表 SQL；ProcessLogger
|
||
│ ├─ history.py # HistoryManager：处理历史记录与日志
|
||
│ ├─ api/routers/ # 各业务接口（按模块拆分，见下表）
|
||
│ ├─ services/ # 业务服务（远程下载、调度、CellData、授权等）
|
||
│ └─ utils/ # 通用工具（文件、文件名日期解析）
|
||
├─ frontend/ # 前端（Vue 3 + Vite）
|
||
│ └─ src/
|
||
│ ├─ AppShell.vue # 整体框架：登录、侧边导航、顶栏、主题切换
|
||
│ ├─ App.vue / main.ts # 应用根与入口
|
||
│ ├─ router.ts # 路由表（6 个功能页）
|
||
│ ├─ types.ts # 前端类型定义
|
||
│ ├─ api/client.ts # 请求封装（token、错误处理、下载）
|
||
│ ├─ components/ # 各功能页面与公共组件
|
||
│ └─ composables/ # 可复用逻辑（页头、主题、剪贴板、日志等）
|
||
├─ src-tauri/ # Tauri 桌面壳（Rust）
|
||
│ ├─ src/main.rs # 启动/停止 Python sidecar、下载、打开目录
|
||
│ └─ tauri.conf.json # 桌面打包配置（WebView2、NSIS 等）
|
||
├─ scripts/ # 运行/编译 Python 脚本
|
||
├─ packaging/ # docker-compose、PyInstaller 配置、MySQL 初始化
|
||
├─ docker/entrypoint.sh # 容器启动脚本
|
||
├─ docs/ # 项目维护记录（project_context.md）
|
||
├─ README.md # 使用说明
|
||
├─ DEVELOPMENT.md # 开发文档（本文件）
|
||
├─ Configure.json # 应用配置
|
||
├─ ReportScript.sql # 容量报表处理 SQL
|
||
├─ CellData.sql # CellData 处理 SQL
|
||
├─ Dockerfile # 服务端镜像
|
||
└─ requirements.txt # Python 依赖
|
||
```
|
||
|
||
运行时数据（不进版本库）：`cache/`（任务工作目录、历史记录 `history.json`）、`logs/`、`auth.ini`（账号）、`license.dat`（授权）。
|
||
|
||
## 功能与代码对照
|
||
|
||
后端接口按模块拆分在 `app/api/routers/`，前端页面在 `frontend/src/components/`。下面按导航栏 6 个功能逐一说明涉及的代码文件。
|
||
|
||
公共代码（多数功能都会用到）：
|
||
|
||
- 前端框架与导航：`frontend/src/AppShell.vue`、`router.ts`、`api/client.ts`、`composables/`
|
||
- 后端入口与共享：`app/main.py`、`app/state.py`、`app/config.py`、`app/api/routers/task_runtime.py`（任务阶段、授权日志、历史保留清理）
|
||
|
||
### 数据处理
|
||
|
||
页面路由 `/upload`。负责本地上传或远程下载数据，清洗入库并执行报表 SQL；若启用 CellData 数据源，会在容量处理前先更新 CellData。
|
||
|
||
| 类型 | 文件 | 职责 |
|
||
| --- | --- | --- |
|
||
| 前端 | `frontend/src/components/FileWorkflow.vue` | 上传/远程下载入口、处理进度与日志、CellData 卡片 |
|
||
| 接口 | `app/api/routers/upload.py` | 创建上传会话、接收文件 |
|
||
| 接口 | `app/api/routers/tasks.py` | 任务锁、启动容量处理、查询状态 |
|
||
| 接口 | `app/api/routers/remote.py` | 远程下载并处理、连接测试、自动调度状态/触发 |
|
||
| 接口 | `app/api/routers/cell_data.py` | CellData 单独处理（远程刷新 / 本地上传） |
|
||
| 服务 | `app/processor.py` | 直连 MySQL：解压、Excel/CSV 转换、入库、执行 `ReportScript.sql` |
|
||
| 服务 | `app/services/remote_download.py` | FTP/SFTP 远程下载 |
|
||
| 服务 | `app/services/auto_scheduler.py` | 后台自动调度（按目标周检查远程数据就绪） |
|
||
| 服务 | `app/services/cell_data.py` | CellData 解析入库、执行 `CellData.sql`、跨库复制 |
|
||
| 服务 | `app/services/license.py` | 按数据日期校验授权期限 |
|
||
| 工具 | `app/utils/file_dates.py` | 文件名日期解析、按目录筛选最近 7 天文件 |
|
||
|
||
### 容量看板
|
||
|
||
页面路由 `/dashboard`。基于主仓库的 4G/5G 结果表做高负荷分析。
|
||
|
||
| 类型 | 文件 | 职责 |
|
||
| --- | --- | --- |
|
||
| 前端 | `frontend/src/components/CapacityDashboard.vue` | 看板大屏：汇总卡片、图表、问题小区清单、详情抽屉 |
|
||
| 前端 | `frontend/src/components/EChart.vue` | ECharts 封装组件 |
|
||
| 接口 | `app/api/routers/dashboard.py` | 状态、汇总概览、问题小区清单、单小区详情、清单导出 |
|
||
| 依赖 | `app/warehouse.py` | 读取数据库中的结果表 |
|
||
|
||
### 处理历史
|
||
|
||
页面路由 `/history`。查看历史任务、日志，浏览/下载历史原始数据。
|
||
|
||
| 类型 | 文件 | 职责 |
|
||
| --- | --- | --- |
|
||
| 前端 | `frontend/src/components/HistoryPanel.vue` | 历史列表、详情、日志、文件浏览与下载 |
|
||
| 接口 | `app/api/routers/history.py` | 历史记录、日志、占用计算、文件浏览/下载、删除 |
|
||
| 服务 | `app/history.py` | HistoryManager：记录存于 `cache/history.json` 与 `cache/<task_id>` |
|
||
|
||
### 数据管理
|
||
|
||
页面路由 `/database`。浏览、编辑、导入导出数据库表，可切换主数据库与 CellData 数据库。
|
||
|
||
| 类型 | 文件 | 职责 |
|
||
| --- | --- | --- |
|
||
| 前端 | `frontend/src/components/DatabasePanel.vue` | 表列表、表数据分页、行编辑/删除、导入导出、执行 SQL |
|
||
| 接口 | `app/api/routers/database.py` | 表列表/结构/分页、清空/删除、行增改删、CSV/XLSX 导出、模板/导入、执行 SQL（`database_source` 选主库或 CellData 库） |
|
||
| 服务 | `app/database.py` | DatabaseManager：直连 MySQL 表操作 |
|
||
| 服务 | `app/warehouse.py` | 数据库访问的统一封装 |
|
||
|
||
### 脚本编辑
|
||
|
||
页面路由 `/script`。在线编辑并执行报表 SQL 与 CellData SQL。
|
||
|
||
| 类型 | 文件 | 职责 |
|
||
| --- | --- | --- |
|
||
| 前端 | `frontend/src/components/ScriptPanel.vue` | Monaco SQL 编辑器、保存、运行、切换脚本类型 |
|
||
| 接口 | `app/api/routers/script.py` | 读取/保存/执行（`report` → `ReportScript.sql`，`celldata` → `CellData.sql`） |
|
||
| 服务 | `app/processor.py`、`app/services/cell_data.py` | 在对应数据库上下文执行脚本 |
|
||
|
||
### 系统设置
|
||
|
||
页面路由 `/settings`。配置数据库、远程数据源、字段映射、自动调度等，并提供修改密码。
|
||
|
||
| 类型 | 文件 | 职责 |
|
||
| --- | --- | --- |
|
||
| 前端 | `frontend/src/components/SettingsPanel.vue` | 各类配置表单、连接测试、配置导入导出 |
|
||
| 前端 | `frontend/src/components/LicenseActivationModal.vue` | 授权延期窗口（连点品牌图标 8 次打开） |
|
||
| 接口 | `app/api/routers/config.py` | 各配置块读写、配置上传/下载、MySQL/远程/CellData 连接测试、CellData 规则校验 |
|
||
| 接口 | `app/api/routers/auth.py` | 登录、修改密码 |
|
||
| 接口 | `app/api/routers/license.py` | 授权状态查询与激活 |
|
||
| 服务 | `app/config.py` | AppConfig 及各配置块的解析与保存 |
|
||
| 服务 | `app/auth.py` | 账号（`auth.ini`）、JWT |
|
||
| 服务 | `app/services/license.py` | 授权加密文件读写、激活码校验 |
|