Metadata-Version: 2.4
Name: excelpilot
Version: 0.1.1
Summary: ExcelPilot 本地离线表格效率工具箱（27 个工具）
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: chardet>=5.0.0
Requires-Dist: flask>=3.0.0
Requires-Dist: openpyxl>=3.1.0

# ⚡ ExcelPilot 表格效率工具箱

本地离线运行的 Excel 效率工具箱，**27 个工具**，浏览器图形界面操作。
数据全程在本机内存和本地磁盘处理，**不联网、不上传、不依赖任何在线服务**。

每个工具都自带**图文说明**：一句话定位、适用场景、以及一段「处理前 → 处理后」的
**循环动画演示**（用真实样例数据渲染，无需任何外部图片/动图文件，鼠标悬停可暂停）。

每个工具还有**操作引导**：点标题右侧的「🎓 操作引导」，界面会依次高亮真正的控件、
说明这一步该填什么；你真的做完该步（传完文件 / 点了运行 / 出了结果）后会自动跳到
下一步，也可以手动点上一步、下一步或结束引导。

---

## 一、启动方式

### 方式 A：一键启动（推荐）
双击 **`启动工具箱.bat`**
- 首次运行时会自动安装依赖库（**这一次需要联网**）
- 之后每次双击即开即用，**完全离线**

### 方式 B：命令行
```bash
python -m excelpilot
```
然后浏览器访问终端里打印的地址（默认 `http://127.0.0.1:8765`）。
端口被占用时会自动顺延到下一个可用端口。

> 关闭那个黑色终端窗口即可停止服务。

---

## 二、27 个工具

### 🧹 整理清洗（8）
| 工具 | 说明 |
|---|---|
| 多表合并 | 一堆结构相近的表拼成一张，自动对齐表头 |
| 多 Sheet 合并 | 一个工作簿里十几个 Sheet 合并成一张总表 |
| **批量新建 Sheet** | ① 按列拆成多 Sheet ② 按名称清单批量建空表 ③ 复制模板 Sheet |
| 一键拆分 | 按列拆成多个独立文件，或按行数切成小文件 |
| 智能去重 | 可忽略大小写/空格，支持只导出重复行核查 |
| 数据清洗 | 去空格、全角转半角、日期统一、删空行空列 |
| 智能向下填充 | 专治合并单元格留下的空格，自动填上方最近值 |
| 表头标准化 | 批量重命名列名，统一「客户名称/客户名」这类别名 |

### ✏️ 文本处理（4）
| 工具 | 说明 |
|---|---|
| 文本分列/合并 | 按分隔符或固定宽度拆分；多列按连接符合并 |
| 批量查找替换 | 跨多列替换，支持正则表达式 |
| 智能提取 | 从文本里抠出手机号/邮箱/身份证/网址/金额/日期 |
| 金额转大写 | 1234.56 → 壹仟贰佰叁拾肆元伍角陆分 |

### ✅ 校验转换（3）
| 工具 | 说明 |
|---|---|
| 数据校验 | 必填/唯一/正则/数值区间/枚举，输出问题清单并标红 |
| 格式转换 | xlsx / csv / json 互转（csv 带 BOM，中文不乱码） |
| 一键美化 | 冻结首行、自动筛选、自动列宽、隔行底色 |

### 📊 分析洞察（7）
| 工具 | 说明 |
|---|---|
| 数据透视 | 选行列维度+聚合方式，直接出交叉汇总表 |
| 统计画像 | 每列的类型/空值率/唯一值/均值中位数，类 pandas describe |
| 模糊查重 | 编辑距离相似度，错别字也能归为一组近似重复 |
| 智能采样 | 随机抽 N 行、按比例、分层抽样，随机种子可复现 |
| 表格差异对比 | 两表按主键对比，标出新增/删除/修改了什么 |
| 长宽表转换 | 宽表转长表、长表转宽表 |
| 表格转置 | 行列互换 |

### 🚀 效率工具（5）
| 工具 | 说明 |
|---|---|
| 关联匹配 | 比 VLOOKUP 更强，支持左/内/外连接 |
| 数据脱敏 | 手机/身份证/姓名/邮箱/银行卡自动打码 |
| 造测试数据 | 一键生成逼真的中文测试数据 |
| 生成图表 | 在 Excel 里插入可编辑的真图表（柱/折线/饼） |
| 公式助手 | 20 条高频公式速查 |

---

## 三、离线是怎么保证的

| 关注点 | 做法 |
|---|---|
| Excel 读写 | `openpyxl`（成熟库，纯 Python），不调用任何在线接口 |
| Web 服务 | Flask 只监听 `127.0.0.1`，外部机器访问不到 |
| 编码识别 | `chardet` 本地探测，兼容 GBK 老文件 |
| 运行期联网 | **完全没有**，可拔网线使用 |
| 唯一需要联网的时刻 | 首次安装依赖库那一次 |

---

## 四、项目结构

```
excel-toolkit/
├── 启动工具箱.bat      # 双击启动（Windows）
├── excelpilot/         # 包：Flask 服务端 + 27 个工具 + templates/
│   ├── app.py          #   Flask 服务端（路由）
│   ├── core.py         #   表格读写引擎（openpyxl 封装）+ 通用工具
│   ├── tools.py        #   工具集第一批（整理清洗 / 文本处理）
│   ├── tools_advanced.py#  工具集第二批（校验 / 分析 / 效率）
│   └── templates/index.html  # Web 界面
├── requirements.txt    # 依赖清单
├── test_all.py         # 工具逻辑测试（37 项）
├── test_web.py         # Web 路由测试（49 项）
├── test_http_real.py   # 真实 HTTP 端到端测试（21 项）
└── workspace/          # 运行时产生的上传与结果文件
```

**加新工具只需两步**：在 `excelpilot/tools.py` 里用 `@register(...)` 写一个函数，
前端表单会自动根据参数定义渲染，无需改动 HTML。

---

## 五、测试

```bash
python test_all.py        # 全部 27 个工具的逻辑与产出文件
python test_web.py        # Flask 路由：上传/运行/下载/错误处理
python test_http_real.py 8766   # 对运行中的服务做真实 HTTP 全流程
```

当前状态：**37 + 49 + 21 = 107 项全部通过**。

---

## 六、常见问题

**Q：双击 bat 后闪退？**
把 bat 拖到已打开的 cmd 窗口里回车运行，能看到报错信息。多数是 Python 没装或没勾选 Add to PATH。

**Q：提示「不是有效的 xlsx 文件」？**
老版 `.xls` 不是 `xlsx`（xlsx 本质是 zip 包）。请先用 Excel 另存为 `.xlsx`，或另存为 CSV。

**Q：CSV 打开中文乱码？**
本工具写出 CSV 默认带 BOM（utf-8-sig），Excel 双击打开正常。若你要给老系统用，可在「格式转换」里选 GBK 编码。

**Q：处理大文件会卡吗？**
预览只取前 200 行，实际处理全量。十万行级别的单表各工具一般几秒内完成。

**Q：端口被占用？**
程序会自动顺延到下一个可用端口，看终端里打印的实际地址即可。也可设置环境变量 `EXCELPILOT_PORT` 指定。

---

## 七、完全离线分发（含依赖 wheel）

若目标机器不能联网，本仓库已附带 `whls/` 目录，内含全部依赖的离线 wheel 包
（openpyxl / flask / chardet 及其传递依赖，共 16 个：Windows + Linux，Python 3.12/3.13）。

在目标机解压后，运行：

```bash
python -m pip install --no-index --find-links=whls -r requirements.txt
```

即可不联网装好全部依赖，随后双击 `启动工具箱.bat` 即可使用。

> 说明：`whls/` 已内置 **Windows(x86_64) 与 Linux(manylinux x86_64)** 下 **Python 3.12 / 3.13** 的 wheel，pip 会根据目标机自动选用匹配的版本。
> 若目标机是 macOS 或非 x86_64 架构（如 ARM），请在有网的同环境下用以下命令重新拉取对应平台的 wheel：
> ```bash
> python -m pip download -r requirements.txt -d whls -i https://pypi.tuna.tsinghua.edu.cn/simple/
> ```

---

## 八、使用 uv 启动

如果你习惯用 uv 管理环境，本仓库已附带 uv.lock，
可直接用 uv 一键创建虚拟环境并启动，无需手动 pip install：

```bash
uv sync          # 按 uv.lock 创建 .venv 并安装依赖（首次需联网）
uv run -m excelpilot    # 启动服务
```

或双击 启动工具箱-uv.bat（Windows）/ 运行 启动工具箱-uv.sh（Linux、macOS）：
脚本会先尝试 uv sync --offline（离线），失败再回退到联网 uv sync，然后自动 uv run -m excelpilot。
在 Linux/macOS 上首次运行前请先赋予执行权限：`chmod +x 启动工具箱-uv.sh`。

> uv 自带 Python 版本管理；pyproject.toml 已声明 requires-python = ">=3.12"，
> 在 3.12 / 3.13 上均可运行。离线分发用的 whls/ 也已同时包含这两个版本、双平台的 wheel。
>
> **whls/ 是如何被「自动关联」的**：`pyproject.toml` 里已配置
> `[tool.uv] find-links = ["whls"]`，uv 会优先从 `whls/` 目录匹配轮子；
> 因此 `uv sync --offline` 全程不联网、只用本地 `uv.lock` + `whls/` 即可装好全部依赖。
> （pip 路径则靠 `启动工具箱.bat` 里的 `--find-links=whls` 显式指定，效果相同。）
