From 05e05961111018f43aeb00e9989c650642b9d7e3 Mon Sep 17 00:00:00 2001 From: Nixevol Date: Fri, 26 Jun 2026 12:03:04 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20Web=20=E7=AB=AF?= =?UTF-8?q?=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E=20USAGE.md=EF=BC=88?= =?UTF-8?q?=E8=A1=A8=E6=A0=BC=20+=20Mermaid=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 涵盖登录、整体流程、准备配置、各功能页操作与注意事项；README 增加链接。 --- README.md | 2 + USAGE.md | 153 ++++++++++++++++++++++++++++++++++++++++ docs/project_context.md | 6 ++ 3 files changed, 161 insertions(+) create mode 100644 USAGE.md diff --git a/README.md b/README.md index 40bf0c3..17daf38 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,8 @@ CapacityReport 用于处理每周的网络容量报表数据：从本地上传 - 启动后访问 `http://localhost:9081`。 - 也可以直接在「数据处理」页拖拽上传数据文件，无需远程数据源。 +详细的 Web 端操作方法与注意事项见 [使用说明 USAGE.md](USAGE.md)。 + ## 运行与编译 所有运行 / 编译都统一为 `scripts/` 下的 Python 脚本，直接用系统 Python 运行即可。脚本会自动创建 `.venv` 并安装依赖、自动安装前端依赖；缺少 Node.js / Rust / Docker 时会给出安装引导。 diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 0000000..ee1f0d8 --- /dev/null +++ b/USAGE.md @@ -0,0 +1,153 @@ +# CapacityReport 使用说明 + +本文面向使用者，介绍 Web 端各功能的操作方法与注意事项。系统的安装、运行与编译请见 [README](README.md)。 + +## 登录 + +- 启动服务后在浏览器访问 `http://localhost:9081`（桌面版直接打开应用窗口）。 +- 默认账号：用户名 `root`，密码 `Capacity`。 +- 登录后可在「系统设置 → 修改密码」修改密码。建议使用 Chrome / Edge 等现代浏览器。 + +## 整体使用流程 + +```mermaid +flowchart LR + A[登录] --> B[系统设置
配置数据库 + 远程数据源] + B --> C[数据处理
上传或远程下载数据] + C --> D[处理入库
执行报表 SQL] + D --> E[容量看板
查看高负荷分析] + D --> F[数据管理
查看/导出结果表] + C --> G[处理历史
查看日志/下载原始数据] +``` + +首次使用建议顺序：先在「系统设置」配好 MySQL 数据库，再在「数据处理」上传或下载数据，处理完成后到「容量看板」「数据管理」查看结果。 + +## 准备工作（系统设置） + +正式处理数据前，至少要配置好数据库；使用远程自动下载时再配置远程数据源。 + +| 配置项 | 位置 | 说明 | +| --- | --- | --- | +| 数据库（数据仓库） | 系统设置 → 数据库 | 填写 MySQL 8.0+ 的主机、端口、库名、账号密码，保存后点「测试连接」确认可用 | +| CellData 数据库 | 系统设置 → 数据库 | 可选。若使用 CellData 小区信息，配置其数据库（可与主库相同或独立） | +| 远程数据源 | 系统设置 → 远程数据源 | 可选。配置 FTP/SFTP 服务器与目录，用于「远程下载并处理」 | +| 自动调度 | 系统设置 → 自动调度 | 可选。开启后系统按目标自然周自动检查远程数据并处理 | +| 字段映射 / Sheet 过滤 / 目录映射 | 系统设置 → 规则映射 | 配置源数据字段到目标字段的映射、Sheet 过滤规则、目录到暂存表的映射 | +| 处理历史保留 | 系统设置 → 数据库 | 可选。设置自动清理已结束历史、保留最近次数 | + +> 提示：连接 FTP/SFTP 和 MySQL 的测试按钮会真实发起连接，若服务器较慢可能需要等待几秒。 + +## 功能页使用说明 + +### 数据处理 + +数据处理页提供「容量数据」和「CellData」两个区域，每个区域都支持本地上传与远程下载两种方式。每个卡片右上角有说明按钮，可查看所需文件格式。 + +| 操作 | 说明 | +| --- | --- | +| 本地上传（容量数据） | 拖拽或点击选择文件，支持 `.zip / .xlsx / .xls / .csv`，也可整文件夹上传 | +| 远程下载并处理（容量数据） | 从「系统设置」中配置的 FTP/SFTP 目录下载数据后自动处理 | +| CellData 上传 | 拖拽或选择**文件夹**（需包含 `700M`、`2.6G` 等频段子目录），不支持单个 ZIP 直接拖入 | +| CellData 远程下载并处理 | 按 CellData 数据源配置拉取并处理 | + +处理过程的阶段会在进度区实时显示： + +```mermaid +flowchart LR + S0[远程下载中] --> S1[更新 CellData] + S1 --> S2[授权校验] + S2 --> S3[解压数据] + S3 --> S4[转换 Excel] + S4 --> S5[导入数据] + S5 --> S6[运行脚本] + S6 --> S7[完成] +``` + +| 阶段 | 含义 | +| --- | --- | +| 远程下载中 | 从 FTP/SFTP 下载数据（仅远程方式） | +| 更新 CellData | 启用 CellData 数据源时，容量处理前先刷新小区信息 | +| 授权校验中 | 按数据日期校验授权期限 | +| 解压数据中 | 解压上传/下载的 ZIP | +| 转换 Excel 中 | 将 Excel 转换为 CSV | +| 导入数据中 | 数据写入 MySQL 暂存表 | +| 运行脚本中 | 执行 `ReportScript.sql` 生成结果表 | + +> 注意：同一时间只能运行一个处理任务。任务运行时上传区会隐藏，只显示进度与日志，请等当前任务结束后再发起新任务。 + +### 容量看板 + +展示主数据库中 4G/5G 结果表的高负荷分析大屏，需先完成数据处理生成结果表。 + +| 区域 | 说明 | +| --- | --- | +| 制式切换 / 刷新 | 顶部切换 4G / 5G，点击刷新重新加载 | +| 汇总卡片 | 小区总数、高负荷数、各类预警、平均利用率、总流量等 | +| 图表 | 负荷问题分布、上下行利用率分布、制式 / 站型 / 频段统计等 | +| 问题小区清单 | 按高负荷优先排序，支持筛选、关键字搜索、分页与导出 CSV | +| 小区详情 | 点击清单某行打开右侧抽屉，查看关键指标、优化建议、同扇区小区 | + +> 说明：未生成结果表时，看板显示「请先进行数据处理」。 + +### 处理历史 + +记录每次处理任务，便于回溯与排查。 + +| 操作 | 说明 | +| --- | --- | +| 查看详情 | 打开任务详情与分级处理日志 | +| 文件浏览 | 在详情中浏览该任务工作目录下的文件 | +| 下载 | 将历史原始数据打包为 ZIP 下载（任务完成后可用） | +| 删除 | 删除历史记录及其相关文件 | + +### 数据管理 + +直接查看与维护数据库中的表，可在主数据库与 CellData 数据库之间切换。 + +| 操作 | 说明 | +| --- | --- | +| 选择数据库 / 表 | 表标题旁图标按钮切换数据库；左侧列表选择表 | +| 浏览数据 | 分页查看表数据，列宽可拖拽，可展开字段结构 | +| 编辑 / 删除行 | 每行可编辑或删除；编辑时清空某字段表示写入 NULL | +| 导出 | 导出当前表为 CSV，或选择多张表导出为同一个 XLSX | +| 模板 / 导入 | 下载当前表字段的 CSV 模板；导入要求表头与表字段完全一致 | +| 清空 / 删除表 | 清空表数据或删除整张表 | + +> 注意：清空、删除表、删除行为不可恢复操作，请谨慎确认。 + +### 脚本编辑 + +在线编辑并执行业务 SQL，使用 Monaco 编辑器（带 SQL 高亮）。 + +| 操作 | 说明 | +| --- | --- | +| 切换脚本 | 顶部切换「容量报表脚本」（`ReportScript.sql`）和「CellData 脚本」（`CellData.sql`） | +| 保存 | 保存脚本，保存前会自动备份为 `.sql.bak` | +| 运行 | 在对应数据库上执行当前脚本，下方显示运行日志 | + +> 说明：脚本运行也占用同一个任务锁，运行期间不能同时发起数据处理。 + +### 系统设置 + +| 标签页 | 内容 | +| --- | --- | +| 数据库 | 主仓库 MySQL、CellData 数据库、处理历史保留 | +| 远程数据源 | 容量数据 FTP/SFTP、CellData 数据源（含扫描路径、规则设置） | +| 自动调度 | 开关、检查间隔、目标周期、预期目录、调度状态 | +| 规则映射 | Sheet 过滤规则、字段映射、数据目录映射 | +| 修改密码 | 修改登录密码 | + +页面顶部可下载 / 上传配置文件（`Configure.json`），方便备份与迁移。 + +## 注意事项 + +| 事项 | 说明 | +| --- | --- | +| 任务串行 | 数据处理、CellData 处理、脚本执行共用一个任务锁，同一时间只能运行一个，请勿并发触发 | +| 文件命名日期 | 容量数据 ZIP 文件名需含时间戳（`XXX_YYYYMMDDHHMM` 或 `XXX_YYYYMMDDHHMM_YYYYMMDDHHMM`），系统以**第一个**时间戳作为数据日期 | +| 每目录 7 天窗口 | 每个目录只保留并处理最近 7 个自然日的文件 | +| CellData 文件 | 来源为 `Result_300_*.zip`，时间取文件名末尾时间戳；本地上传必须按频段目录组织 | +| 授权期限 | 处理时按数据日期校验授权，超期会失败；可在弹出的激活框输入激活码延长 30 天 | +| 自动调度前提 | 开启自动调度会强制开启远程自动化与处理后删除源文件，请确认远程目录配置正确 | +| 数据安全 | 清空表、删除表、删除行、删除历史均不可恢复，操作前请确认 | +| 端口占用 | 服务默认使用 `9081` 端口，若被占用可在运行时指定其他端口 | diff --git a/docs/project_context.md b/docs/project_context.md index dec45f9..c0fa6f1 100644 --- a/docs/project_context.md +++ b/docs/project_context.md @@ -1,5 +1,11 @@ # 项目上下文记录 +## 2026-06-26：新增使用说明 USAGE.md + 文档去 Metrix + +- 新增根目录 `USAGE.md`（Web 端使用说明）：登录（`root`/`Capacity`）、整体流程与数据处理管线 Mermaid 图、准备工作/各功能页/系统设置标签页/注意事项均用表格。内容以实际代码为准：处理阶段取 `FileWorkflow.vue` 的 `stageLabels`（远程下载/更新 CellData/授权校验/解压/转换 Excel/导入/运行脚本）；系统设置 6 个标签（数据库、远程数据源、自动调度、规则映射、修改密码，及仅 Metrix 启用时的「数据源/仓库」）；数据处理含容量数据 + CellData 两区、本地上传 vs 远程下载；任务锁串行、文件名时间戳、每目录 7 天、授权按数据日期等注意事项。`README.md` 增加指向 USAGE.md 的链接。 +- 开发文档/README 去掉 Metrix 描述（暂未使用）：移除 requests/csv_processor/pipeline/platform 等仅服务 Metrix 的条目与字样。 +- 文档命名：开发文档由 `docs/dev_guide.md` 移到根目录 `DEVELOPMENT.md`；README/USAGE/DEVELOPMENT 三篇均在根目录，`docs/` 仅保留 `project_context.md`。 + ## 2026-06-26：重写 README 与新增开发文档（以实际代码为准） - `README.md` 精简重写：系统简介、技术栈、6 个导航模块作用表、初次运行（默认账号 `root`/`Capacity`，需配套 FTP/SFTP 数据源 + MySQL 仓库）、运行与编译命令（复用 `scripts/` 下 py 脚本，可复制即用）、以及跳转开发文档的锚点链接。去掉了原 README 中偏底层的「常用接口」「维护注意事项」等内容。