docs: 重写 README 并新增开发文档（功能↔代码对照，以实际代码为准）

README 精简为系统简介/技术栈/模块说明/初次运行/运行编译命令/开发文档锚点；
新增 docs/dev_guide.md：技术栈与主要库、目录结构、导航栏 6 功能对应代码文件与职责。

README.md

@@ -1,230 +1,99 @@
-# CapacityReport - 容量报表处理系统
+# CapacityReport · 容量报表处理系统
 
-CapacityReport 用于导入每周容量报表数据，按 `Configure.json` 的字段映射和 `ReportScript.sql` 的业务脚本完成数据清洗、入库、计算和结果表生成。系统支持本地上传处理，也支持从 FTP/SFTP 远程目录递归下载数据后自动处理。
+CapacityReport 用于处理每周的网络容量报表数据：从本地上传或 FTP/SFTP 远程目录获取 Excel/CSV/ZIP 数据，按字段映射清洗、入库到 MySQL，再执行业务 SQL 生成 4G/5G 容量结果表，并通过容量看板做高负荷小区分析。
-
-## 双模式后端（自带 FTP/MySQL，或接入 Metrix 平台）
-
-CapacityReport 是自包含应用，源与仓库各自可在「直连」与「Metrix 平台」之间独立选择，二者可任意组合，互不依赖——Metrix 在不在、CapacityReport 怎么跑都不影响：
-
-- **数据源**（系统设置 → 数据源/仓库）：`SFTP` / `FTP`（直连，填服务器与账号密码）或 `Metrix 存储平台`（填平台地址 + Token + storage_id）。
-- **数据仓库**：`MySQL`（直连，填主机/账号密码）或 `Metrix 数据库平台`（填平台地址 + Token + database_conn_id + 目标库）。
-- **Metrix 连接**作为一种连接类型在「数据源/仓库」标签页配置：`base_url` + `API Token`（存配置，非环境变量）+ `storage_id`（存储平台）+ `database_conn_id`/`target_database`（数据库平台），存储/数据库平台共用同一地址与 Token。
-- 直连模式走原生路径（自带 LOAD DATA 入库、单会话跑报表 SQL、本地查看/导出）；Metrix 模式下源走平台储存 API、仓库走平台导入 + `run-script(single_session)`，「数据管理」查看/导出自动**代理到 Metrix** 的 table-data/导出接口。
-- 切换后端不改业务：字段映射、报表 SQL、自动调度、处理历史在两种模式下一致。
-
-## 功能概览
-
-- Excel/CSV/ZIP 数据导入与自动解压、转换、入库。
-- FTP/SFTP 远程数据源配置、连接测试、远程下载并处理。
-- 远程自动调度：按远程 ZIP 文件名日期检查目标自然周 7 天数据，就绪后自动下载并处理。
-- MySQL 数据表查看、清空、删除、CSV/XLSX 导出。
-- SQL 脚本在线查看、保存和执行。
-- 处理历史、日志查看、历史原始数据打包下载。
-- 按 ZIP 文件名数据日期校验本地授权期限，过期后可输入激活码顺延。
-- 系统设置：数据库、远程数据源、Sheet 过滤、字段映射、历史保留、密码修改。
-- 发行形态：Server Portable、Tauri 桌面版、Docker 服务端版。
 
 ## 技术栈
 
-- 后端：FastAPI + Uvicorn
+- 后端：Python + FastAPI + Uvicorn
 - 前端：Vue 3 + TypeScript + Vite + Naive UI
-- 桌面端：Tauri 2 + Python sidecar
+- 桌面端：Tauri 2（Rust）+ Python sidecar
 - 数据库：MySQL 8.0+
-- 数据处理：Pandas + OpenPyXL
+- 数据处理：Pandas + OpenPyXL；图表：ECharts；SQL 编辑器：Monaco Editor
-- 打包：PyInstaller、Docker、Docker Compose
 
-## 目录结构
+## 功能模块
 
-```text
+系统左侧导航分为 6 个模块：
-CapaReport/
-├─ app/                         # FastAPI 后端源码
-│  ├─ api/routers/              # API 路由
-│  ├─ services/                 # 授权、远程下载等业务服务
-│  ├─ utils/                    # 通用工具
-│  ├─ main.py                   # 后端入口和前端托管
-│  ├─ processor.py              # 数据处理主流程
-│  ├─ database.py               # MySQL 访问
-│  ├─ history.py                # 处理历史
-│  └─ config.py                 # 配置读写
-├─ frontend/                    # Vue 前端
-├─ src-tauri/                   # Tauri 桌面壳
-├─ scripts/                     # 运行 / 编译 Python 脚本（dev、run、tauri、docker、clean...）
-├─ packaging/                   # Dockerfile、Compose、PyInstaller 配置
-├─ dist/                        # 编译后的最终产物
-├─ docs/project_context.md      # 项目维护记录
-├─ Configure.json               # 应用配置
-├─ ReportScript.sql             # SQL 处理脚本
-├─ requirements.txt             # Python 依赖
-└─ Dockerfile                   # 服务端容器镜像
-```
 
-## 运行与编译脚本
+| 模块 | 作用 |
-
-所有运行 / 编译都统一为 `scripts/` 下的 Python 脚本，直接用系统 Python 运行即可（`python scripts/xxx.py`）。脚本会**自动创建 `.venv` 并安装依赖**（使用标准库 `venv`，不依赖 uv），自动安装前端依赖；缺少 Node.js / Rust / Docker 时会给出安装引导。
-
-前置要求：
-
-- Python 3.10+（加入 PATH，作为创建 `.venv` 的基础解释器）
-- Node.js 18+（前端构建）
-- MySQL 8.0+（直连仓库模式）
-- Rust 工具链（仅编译 Tauri 桌面版需要）
-- Docker（仅编译 Docker 镜像需要）
-
-| 脚本 | 用途 |
 | --- | --- |
-| `python scripts/dev.py` | 开发测试：后端自动重载 + 前端 Vite 热更新 |
+| 数据处理 | 本地上传或远程下载数据，清洗后入库并执行报表 SQL |
+| 容量看板 | 4G/5G 高负荷小区分析大屏（汇总、图表、问题清单、单小区详情） |
+| 处理历史 | 查看历史任务、处理日志，浏览/下载历史原始数据 |
+| 数据管理 | 浏览、编辑、导入导出数据库表，在线执行 SQL |
+| 脚本编辑 | 在线编辑并执行容量报表 SQL / CellData SQL |
+| 系统设置 | 数据库、远程数据源、字段映射、自动调度等配置 |
+
+## 初次运行
+
+- 默认登录账号：用户名 `root`，密码 `Capacity`（登录后可在「系统设置 → 修改密码」中修改）。
+- 系统需要配套使用：
+  - **一个 FTP/SFTP 数据源**：存放每周容量报表数据，在「系统设置 → 远程数据源」中配置，可手动下载或开启自动调度。
+  - **一个 MySQL 8.0+ 数据库**：作为数据仓库，在「系统设置 → 数据库」中配置连接信息。
+- 启动后访问 `http://localhost:9081`。
+- 也可以直接在「数据处理」页拖拽上传数据文件，无需远程数据源。
+
+## 运行与编译
+
+所有运行 / 编译都统一为 `scripts/` 下的 Python 脚本，直接用系统 Python 运行即可。脚本会自动创建 `.venv` 并安装依赖、自动安装前端依赖；缺少 Node.js / Rust / Docker 时会给出安装引导。
+
+环境要求：
+
+- Python 3.10+（加入 PATH）
+- Node.js 18+
+- MySQL 8.0+
+- Rust 工具链（仅编译 Tauri 桌面版时需要）
+- Docker（仅编译镜像时需要）
+
+| 命令 | 用途 |
+| --- | --- |
+| `python scripts/dev.py` | 开发模式：后端自动重载 + 前端热更新 |
 | `python scripts/run.py` | 本地运行：构建前端（如缺失）并启动服务 |
 | `python scripts/tauri_dev.py` | Tauri 桌面端测试运行 |
 | `python scripts/build_server.py` | 编译 Server 便携版 |
 | `python scripts/build_tauri.py` | 编译 Tauri 桌面版 |
 | `python scripts/build_docker.py` | 编译 / 更新 Docker 镜像 |
-| `python scripts/clean.py` | 清理缓存、`__pycache__`、编译产物、运行时临时数据 |
+| `python scripts/clean.py` | 清理缓存与编译产物 |
-| `python scripts/gen_license_code.py` | 根据授权 key 生成激活码 |
-
-### 开发测试
-
-```powershell
-python scripts/dev.py
-```
-
-启动后端（`http://127.0.0.1:9081`，自动重载）和前端（`http://127.0.0.1:5174`，Vite 热更新，`/api` 与 `/health` 代理到后端）。按 `Ctrl+C` 停止。
 
 ### 本地运行
 
-```powershell
+```bash
 python scripts/run.py            # 默认 0.0.0.0:9081
 python scripts/run.py --port 8080
-python scripts/run.py --rebuild  # 强制重新构建前端
 ```
 
-访问 `http://localhost:9081`。
+### 开发模式
 
-### Server 便携版
+```bash
-
+python scripts/dev.py
-```powershell
-python scripts/build_server.py
-python scripts/build_server.py --no-archive
 ```
 
-输出：
+后端 `http://127.0.0.1:9081`（自动重载），前端 `http://127.0.0.1:5174`（Vite 热更新）。
 
-```text
+### 编译发布版
-dist\server\CapacityReport-Server-windows-x64\
+
-dist\server\CapacityReport-Server-windows-x64.zip
+```bash
+python scripts/build_server.py            # Server 便携版（dist/server/）
+python scripts/build_tauri.py             # Tauri 桌面版（dist/desktop/）
+python scripts/build_docker.py            # Docker 镜像 + 离线包（dist/docker/）
 ```
 
-便携版内包含后端可执行文件、前端构建产物、`Configure.json`、`ReportScript.sql`、`CellData.sql`、`cache/`、`logs/` 和启动脚本（Windows 为 `run.bat`，Linux/macOS 为 `start.sh`）。默认监听端口 `9081`。便携版需在目标系统原生构建。
+桌面版需在目标系统本机构建（Windows 包在 Windows、Linux 包在 Linux、macOS 包在 macOS）；Windows 安装包内置 WebView2 离线安装器。Docker 离线包部署：
-
-### Tauri 桌面版
-
-```powershell
-python scripts/build_tauri.py                   # 编译当前系统的桌面版
-python scripts/build_tauri.py --platform windows
-```
-
-输出：`dist\desktop\` 下的安装包（Windows: `.msi` / `.exe`；Linux: `.deb` / `.AppImage`；macOS: `.dmg`）。
-
-- 桌面版使用 Tauri 启动 Python sidecar，sidecar 监听 `127.0.0.1:9081`，运行数据写入系统 app data 目录。
-- Windows 安装包内置 WebView2 离线安装器，适合无外网、未预装 WebView2 Runtime 的机器。
-- Windows 默认安装到 `D:\Program Files\CapacityReport`，无 D 盘时回落系统盘。
-- 首次安装运行 Rust/Tauri 时，脚本会在缺少 Tauri CLI 时自动 `cargo install tauri-cli --locked`。
-- Tauri 无法可靠跨系统交叉编译：`--platform` 必须与当前系统一致，否则脚本会提示需在目标系统本机构建。
-
-### Docker 镜像
-
-```powershell
-python scripts/build_docker.py            # 编译镜像并生成 dist/docker/ 离线部署包
-python scripts/build_docker.py update     # 重新编译镜像并就地更新本机容器
-python scripts/build_docker.py --no-save  # 编译但不导出 tar
-```
-
-离线部署包输出到 `dist\docker\`（`capacity-report-app-latest.tar`、`docker-compose.yml`、`Configure.json`、`ReportScript.sql`、`CellData.sql`、`mysql/`）。运行态数据落在 `/data` 数据卷，首次启动由 `docker/entrypoint.sh` 播种默认配置。
-
-部署：
 
 ```bash
 docker load -i dist/docker/capacity-report-app-latest.tar
 docker compose -f dist/docker/docker-compose.yml up -d
 ```
 
-访问 `http://localhost:9081`；停止：`docker compose -f dist/docker/docker-compose.yml down`。
+## 开发文档
 
-### 清理
+更详细的技术栈、目录结构和「功能 ↔ 代码」对照见 [开发文档](docs/dev_guide.md)：
 
-```powershell
+- [技术栈与主要库](docs/dev_guide.md#技术栈与主要库)
-python scripts/clean.py          # 清理缓存 / 编译产物 / 运行时临时数据
+- [目录结构](docs/dev_guide.md#目录结构)
-python scripts/clean.py --deep   # 额外清理 .venv 与 frontend/node_modules
+- [功能与代码对照](docs/dev_guide.md#功能与代码对照)
-```
+  - [数据处理](docs/dev_guide.md#数据处理)
-
+  - [容量看板](docs/dev_guide.md#容量看板)
-## Linux / macOS
+  - [处理历史](docs/dev_guide.md#处理历史)
-
+  - [数据管理](docs/dev_guide.md#数据管理)
-脚本跨平台通用，在对应系统原生环境执行相同命令即可：
+  - [脚本编辑](docs/dev_guide.md#脚本编辑)
-
+  - [系统设置](docs/dev_guide.md#系统设置)
-```bash
-python3 scripts/build_server.py
-python3 scripts/build_tauri.py
-python3 scripts/build_docker.py
-```
-
-Server 便携版与桌面版需在目标系统原生构建（Windows 包在 Windows、Linux 包在 Linux、macOS 包在 macOS）；Docker 镜像可在任意装有 Docker 的开发机构建。
-
-## 配置说明
-
-`Configure.json` 主要包含：
-
-- `MySQL_DBInfo`：MySQL 连接配置。
-- `RemoteData`：FTP/SFTP 远程数据源配置。
-- `HistoryRetention`：处理历史保留配置。
-- `SheetFilter`：Excel Sheet 过滤规则。
-- `ExtractField`：字段映射配置。
-
-`RemoteData.auto_scheduler` 用于远程自动调度：
-
-```json
-{
-  "enabled": false,
-  "check_interval_hours": 1,
-  "expected_directories": ["4G/FDD", "4G/900", "5G/2.6", "5G/700"],
-  "week_offset": 0
-}
-```
-
-- `enabled`：是否启用自动调度。
-- `check_interval_hours`：检查间隔，最小 1 小时。
-- `expected_directories`：相对 `remote_dir` 的预期数据目录；为空时按远程 ZIP 实际所在目录检测。
-- `week_offset`：`0` 表示上周自然周，`-1` 表示上上周。
-
-自动调度开启后，系统会强制开启 `RemoteData.enabled` 和 `auto_delete_source`。调度器每轮先检查 `cache/auto_scheduler/ready.flag`；如果标识存在则直接触发远程下载并处理。没有标识时，会按 ZIP 文件名中的第一个时间戳判断每个目录是否覆盖目标自然周 7 天；全部就绪后写入标识，下一个检查周期再启动处理。处理成功并完成远程源文件清理后会删除标识；处理失败或源文件清理失败会保留标识，后续自动重试。
-
-如果配置了 `expected_directories`，其中某个目录可访问但完全没有 ZIP 文件，会视为该目录已停推并跳过，不再阻塞其他目录；但所有目录都为空时不会触发自动处理。
-
-无论手动上传还是远程下载，处理流程都会按文件名日期对每个目录只保留最近 7 天文件。文件名支持 `XXX_YYYYMMDDHHMM_YYYYMMDDHHMM` 和 `XXX_YYYYMMDDHHMM` 两类格式，数据日期始终取第一个时间戳。
-
-登录密码保存在本地 `auth.ini`，该文件不应提交到版本库。
-
-## 授权
-
-授权到期日期保存在本地加密文件 `license.dat`，默认到期日由 `app/services/license.py` 中的 `DEFAULT_EXPIRES_ON` 控制，当前为 `2026-12-30`。处理任务不会读取系统日期，而是从任务目录 ZIP 文件名中的 `YYYYMMDDHHMM` 或 `YYYYMMDDHHMMSS` 时间戳取最大日期进行比对。登录后连续点击左上角品牌图标 8 次，可主动打开授权延期窗口。
-
-## 常用接口
-
-- `POST /api/login`：登录
-- `POST /api/change-password`：修改密码
-- `POST /api/upload`：上传文件
-- `POST /api/remote/test`：测试 FTP/SFTP 连接
-- `POST /api/remote/start`：远程下载并处理
-- `GET /api/remote/scheduler/status`：查询远程自动调度状态
-- `POST /api/remote/scheduler/trigger`：手动触发一次自动调度检查
-- `POST /api/process/start`：启动本地处理
-- `POST /api/process/status`：查询处理状态
-- `GET /api/license/status`：查询授权状态
-- `POST /api/license/activate`：提交激活码并顺延授权期限
-- `GET /api/history`：处理历史
-- `POST /api/history/download`：下载历史原始数据
-- `GET /health`：健康检查
-
-## 维护注意事项
-
-- 不要提交 `auth.ini`、`license.dat`、`cache/`、`logs/`、`dist/`、`frontend/dist/`、`src-tauri/target/`、`src-tauri/binaries/`。
-- `src-tauri/gen/schemas/` 需要保留并提交，`src-tauri/capabilities/default.json` 的 JSON schema 会引用它。
-- `ReportScript.sql` 是业务处理链路的一部分，修改前需要确认 SQL 语义和字段映射兼容。

docs/dev_guide.md

@@ -0,0 +1,170 @@
+# CapacityReport 开发文档
+
+面向二次开发者，介绍项目实际用到的技术栈、目录结构，以及导航栏每个功能对应的代码文件，方便快速定位要修改的位置。
+
+## 技术栈与主要库
+
+### 后端（Python）
+
+| 库 | 用途 |
+| --- | --- |
+| fastapi / uvicorn | Web 框架与 ASGI 服务器 |
+| python-multipart | 文件上传表单解析 |
+| pandas / openpyxl | Excel/CSV 数据读取与处理 |
+| chardet | CSV 编码探测 |
+| pymysql | 直连 MySQL 读写 |
+| cryptography | 本地授权文件加密 |
+| paramiko | SFTP 远程下载 |
+| requests | Metrix 平台 API 客户端（可选模式） |
+
+### 前端（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          # make_warehouse：按仓库类型返回直连或 Metrix 仓库
+│  ├─ processor.py          # DataProcessor：解压/转换/入库/执行报表 SQL；ProcessLogger
+│  ├─ history.py            # HistoryManager：处理历史记录与日志
+│  ├─ api/routers/          # 各业务接口（按模块拆分，见下表）
+│  ├─ services/             # 业务服务（远程下载、调度、CellData、授权、Metrix 等）
+│  └─ 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/                    # 文档（本文件、项目维护记录）
+├─ 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/services/csv_processor.py`、`pipeline.py`、`platform.py` | Metrix 平台模式下的预处理与平台导入（可选） |
+| 工具 | `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` | 直连或 Metrix 仓库的统一访问 |
+
+### 脚本编辑
+
+页面路由 `/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`、`app/services/pipeline.py` | 在对应数据库上下文执行脚本 |
+
+### 系统设置
+
+页面路由 `/settings`。配置数据库、远程数据源、字段映射、自动调度等，并提供修改密码。
+
+| 类型 | 文件 | 职责 |
+| --- | --- | --- |
+| 前端 | `frontend/src/components/SettingsPanel.vue` | 各类配置表单、连接测试、配置导入导出 |
+| 前端 | `frontend/src/components/LicenseActivationModal.vue` | 授权延期窗口、Metrix 平台开关（连点品牌图标 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` | 授权加密文件读写、激活码校验 |

docs/project_context.md

@@ -1,5 +1,11 @@
 # 项目上下文记录
 
+## 2026-06-26：重写 README 与新增开发文档（以实际代码为准）
+
+- `README.md` 精简重写：系统简介、技术栈、6 个导航模块作用表、初次运行（默认账号 `root`/`Capacity`，需配套 FTP/SFTP 数据源 + MySQL 仓库）、运行与编译命令（复用 `scripts/` 下 py 脚本，可复制即用）、以及跳转开发文档的锚点链接。去掉了原 README 中偏底层的「常用接口」「维护注意事项」等内容。
+- 新增 `docs/dev_guide.md` 开发文档：①技术栈与主要库（仅列实际用到的：后端 fastapi/uvicorn/pandas/openpyxl/chardet/pymysql/cryptography/paramiko/requests；前端 vue/vue-router/naive-ui/@vicons/echarts/monaco-editor/@tauri-apps/api + vite 构建链；Tauri tauri/shell/dialog/reqwest/sysinfo/open/serde）；②目录结构及各目录/文件职责；③导航栏 6 功能（数据处理/容量看板/处理历史/数据管理/脚本编辑/系统设置）逐一用表格列出前端组件、后端路由、相关服务文件与职责，方便定位修改点。
+- 文档事实核对要点（以代码为准）：默认账号在 `app/auth.py`（`root`/`Capacity`，存 `auth.ini`）；运行时 SQL 为 `ReportScript.sql` 与 `CellData.sql`（`app/config.py`）；历史记录存 `cache/history.json`（`app/history.py`）；6 个路由页对应 `frontend/src/router.ts`；端口 9081。
+
 ## 2026-06-26：统一运行/编译脚本为 scripts/ 下纯 Python（傻瓜式，自动 venv）
 
 把分散的运行/编译入口（根 `run.bat`/`debug.bat`/`start.sh`/`dev.py`、`scripts/build.{sh,ps1,bat}`、`supervisord.conf`、`packaging/Dockerfile`）清理掉，统一改为 `scripts/` 下只依赖标准库的 Python 脚本，可直接 `python scripts/xxx.py` 运行：