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

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

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` 运行：