# excel_tools **Repository Path**: darksoulslee/excel_tools ## Basic Information - **Project Name**: excel_tools - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-29 - **Last Updated**: 2026-11-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 表格小助手 给体制内对表用的小工具。选两个 Excel 文件,点几下,把该填的列填进底稿,**原表格式原样保留**。 - 纯本地运行,文件不上传;正常使用时不联网(源码方式缺组件时才可能尝试从镜像补齐) - 界面用 Python 自带 `tkinter`,Excel 读写用 `openpyxl`;PDF/图片/盖章另需 `pypdf`、`pypdfium2`、`pillow`、`reportlab`(绿色版已内置,源码方式见 `requirements.txt`) --- ## 怎么运行 ### 方式一:绿色版(推荐,不需要装任何东西) 在一台**能跑的同系统机器**上执行一次打包,产出一个自带 Python 的文件夹: ```bash python3 build_dist.py # 默认一次打全部 3 个平台 python3 build_dist.py --target win # 只打 Windows x64(zip) python3 build_dist.py --target linux # 只打 Linux x86_64(tar.gz) python3 build_dist.py --target arm # 只打国产麒麟 aarch64(tar.gz) python3 build_dist.py --with-source # 保留明文 .py 源码(默认编译成 .pyc) python3 build_dist.py --clean # 打完清空下载缓存 ``` 打完会自动做一次**发布前自检**:本机平台直接用包内解释器真实导入全部模块, 逐个检查依赖和关键函数;跨平台包做静态检查。自检不通过会直接中止打包, 不会再把缺组件 / 少函数的包发出去。 产出 `dist/表格小助手-win-x64/`、`dist/表格小助手-linux-x64/`、 `dist/表格小助手-国产麒麟-aarch64/`。 把**整个文件夹**拷给任何人就能用:Windows 双击 `启动.bat`;Linux 双击 `表格小助手.desktop` (或终端执行 `./启动.sh`);macOS 双击 `启动.sh`。不用装 Python、不用联网、不用管理员权限。 包里是 [python-build-standalone](https://github.com/astral-sh/python-build-standalone) 的完整 **CPython 3.12**(与当前开发环境一致;旧版为了兼容 Win7 固定 3.9,现已不需要), **含 tkinter**,用官方已去符号的 `install_only_stripped` 版,再加全部依赖和你的代码。 打包时若主机也是 Python 3.12,直接用本机解释器编译 `.pyc`,不再额外下载一个编译器运行时。 包体积随运行时版本变化,以 `dist/` 里实际产出为准(Windows 约 60 MB、zip 约 20 MB 量级)。 Windows 上另有 `启动(调试模式).bat`,出错时保留黑窗口直接显示原因。 **Linux 中文字体**:python-build-standalone 自带的 Tk 没编译 Xft,中文字体家族会全部 退化成 X11 的 `fixed` 字体,界面上出现大量方框(豆腐块)。打包脚本会自动用 `vendor/` 里的 Xft 版 libtk + 配套 Tk 脚本替换(Ubuntu 20.04 的 `libtk8.6 8.6.10-1`, 只要求 glibc 2.29,兼容 Ubuntu 20.04 / Debian 11 及更新的系统),运行时使用系统自带的 `libXft` / `fontconfig` 和系统字体。所以 `vendor/` 目录要跟代码一起保留;目标机器 需要有常见中文字体(主流桌面发行版默认带 Noto CJK)和图形桌面。 Linux/macOS 优先发 **tar.gz**(天然保留执行权限和软链接)。发 zip 也行,打包时已强制写入 可执行权限;万一某些解压工具把权限丢了,报 `Permission denied`,在解压目录执行一次 `chmod +x 启动.sh 表格小助手.desktop` 即可。 **下载源**:Python 走阿里 npmmirror、依赖走清华 PyPI,都是国内源,实测几十秒下完; GitHub / 官方 PyPI 只做兜底。文件带官方 sha256 校验,换源不会降低安全性。 下完缓存在 `dist/.cache/` 里,重新打包不用再下。 **打包会自动瘦身**:用官方去符号的 Python,再删掉 C 头文件、Python 自带测试、 `pip`、静态库、Tk 示例等运行时用不到的东西(Linux 没瘦身时 250 MB → 45 MB), 删完立刻自检,确认解释器、tkinter、依赖和界面代码都能跑。 **跨平台的限制**:Python 解释器不能交叉运行,所以在本机打其它架构的包只能做静态检查、 跳过运行自检。国产麒麟 ARM 包最好在一台 ARM 机器上再跑一遍脚本做完整自检。 `reportlab` 在个别 ARM 镜像上可能没有对应 wheel,脚本会跳过并提示, 该平台「合并 PDF 加中文页码」功能会明确报缺少组件,而不是静默崩溃。 如果对方系统的 glibc 版本比打包机老(报 `GLIBC_x.x not found`),换台老一点的 Linux 打包,或用 `--target Linux` 指定。 ### 方式二:自己装环境跑 源码方式需要先装好依赖,再用命令行启动: ```bash pip install -r requirements.txt python3 app.py ``` Windows 需要 `python3-tk`(Linux 常见发行版是 `python3-tk` 包,macOS 用官方 Python 安装包自带)。 绿色版目录里另有 `启动.bat` / `启动.sh` / `表格小助手.desktop`,解压后双击即可,不需要装 Python。 --- ## 界面结构 ### 第一层:功能引导页 首页是 **5 个功能分区**:智能汇总与拆分、清洗与提取加工、自动匹配与比对、严苛数据校验、套打与文档归档;另有 4 个快捷入口:分组统计、统计看图、按位打码、两表比对。每个分区进去后还有方式选择页(如清洗分地址拆分 / 身份证提取 / 文本抠取 / 物理除脏 / 按位打码,套打分 PDF / Word / 合并 PDF)。以后加卡片在 `ui/home.py` 的 `HomePage` 里加,路由在 `main.py` 的 `ROUTES` 里注册。 ### 第二层:拆分与汇总 从首页点「批量拆分」或「数据汇总」进入同一个页面,顶部可以随时切换。 **批量拆分** - 选一张总表,自动识别表头 - 选一列作为拆分依据(默认优先推荐单位/部门/科室),值相同的行放进同一个文件 - 空白值单独生成「未填写」文件 - 输出目录、文件名后缀可改;文件名 = 字段值 + 后缀 - 复制原文件后删掉其他组的行,表头、合并单元格、列宽、字体原样保留 - 生成前显示分组数和文件名示例;超过 200 组会二次确认 - 重名自动加 `_2`,非法字符自动替换 **数据汇总** - 选一个文件夹,点「扫描」先看文件、工作表、行数 - 可勾选「包含子文件夹」 - 按表头字段自动对齐(同义字段也能对上,如 身份证 ↔ 身份证号、手机号 ↔ 联系电话),列取并集 - 输出一张总表,最后加一列「来源文件」 - 自动跳过 `~$` 临时文件、打不开的文件、没有数据的文件 - 输出文件不会把自己扫进去 ### 第三层:自动匹配(三步向导) **第 1 步 · 选择文件** - 左:**待匹配表**(底稿,结果以此表为基础,格式原样保留) - 右:**数据来源表**(从这里取要填的内容) - 自动识别表头,并在下方列出「列号 / 表头字段 / 前两行示例」 - 识别不准时,直接改「表头行」的两个数字,点「应用」,或点「自动识别」重来 - 可以切换工作表(默认自动挑带「姓名」的那张) **第 2 步 · 匹配字段(怎么把两个表的行对上)** - **默认什么都不选,全部由用户手点**:先点左表字段,再点右表字段 → 组成一对 - 点完不会丢:左边选中的字段保持高亮,底部「已选字段(配对一览)」框里实时列出每一对 - 每对都带**连接标识**:列表里是 `身份证号 → 身份证`,底部框里是独立的「连接」列(箭头从待匹配表字段指向数据来源表字段),一眼看出谁连谁 - 可以配多组,多组是「且」的关系(姓名 + 身份证更稳) - 拿不准可以手动点「智能推荐」,它会按同义字段推荐(姓名↔姓名、身份证号↔身份证、联系电话↔手机号),并**自动跳过底稿里整列为空的字段**(空列当不了匹配条件);不想要的再删掉 - 配错了可以「删除选中配对」「清空配对」;重新配对时原来的行不会跳位置 **第 3 步 · 回填与输出** 这一步是把来源表的值**写回原表已有的列**,不加新列、不改表头: - 左边点**原表里要回填的列**,右边点**数据来源表的字段**,组成一对——两边字段名不一样也没关系(原表叫「科室」、来源表叫「部门」),手动配就行 - 点完两边都带 ✓ 和箭头标识:左边显示 `部门 ← 科室`,右边显示 `科室 → 部门`,箭头方向就是数据流向 - 底部「已选回填字段」框里列出每一对,还带**来源第一行的示例值**,方便核对有没有配错 - 右边选输出目录、改文件名 - 可选:未匹配的行写「未匹配」(只填原本是空的格子,不覆盖原表已有内容)、填入内容去空格转大写 - 点右下角「生成表格」,下面有运行记录,完成后可直接打开输出文件夹 ### 第四层:数据校验 选一张表,自动识别字段类型,勾选检查项,生成两份文件: - `原文件名_校验报告_时间.xlsx`:概览 / 问题明细 / 字段分析 / 分布统计 - `原文件名_标注版.xlsx`:复制原表,把问题单元格按严重程度标色(严重红、警告黄、提示蓝),原值不改 **检查项** - 身份证:18 位、校验位、出生日期、性别一致、重复;15 位旧证会提示升位 - 手机号:11 位、`1[3-9]` 开头;带空格/横线会提示;座机放行 - 姓名:空格、数字字母、长度异常、重名 - 性别:只能男/女,并与身份证第 17 位比对 - 日期:非法日期、未来日期、与身份证出生日期不一致 - 数值:金额、年龄、人数等列不是数字 - 重复:身份证、手机号、姓名、整行重复 - 空白/全角:首尾空格、换行、零宽字符、全角数字字母 - 空值/必填:姓名、身份证为空 **字段识别** - 默认按表头和数据自动判断,支持多行合并表头(如「基本信息 / 姓名」) - 识别错了,在列表里选中一行,把「识别为」改成身份证/手机号/姓名/性别/出生日期/单位/日期/数值/文本/忽略,点「应用」 **报告里的统计** - 字段分析:每列非空数、空值数、空值率、唯一值数、示例 - 分布统计:性别、年龄段、单位/部门、学历、民族、政治面貌 --- ## 匹配规则(重点) | 项目 | 处理方式 | | --- | --- | | 空格 | 全部去掉(含全角空格、制表符、换行) | | 大小写 | 统一转大写,`x` 和 `X` 视为同一个 | | 全角 | 全角字母数字转半角 | | 多字段 | 按顺序拼成一个复合键,全部相同才算匹配 | | 重复行 | 数据来源表里同一个键出现多次,只取第一条,并在日志里提示 | | 空键 | 参与匹配的字段全为空,跳过该行并计数 | 所以「身份证号」和「身份证」标题不一样,只要在第 2 步手动配一次,值就能对上。 --- ## 表头识别规则(另一重点) 1. **锚点**:扫描前 60 行,找到写着「姓名 / 姓 名 / 人员姓名 / 职工姓名 / 员工姓名」的单元格,把它所在行当作表头末行。 2. **多层表头**:从锚点行往上找,只要上面一行有横向合并(分组表头)且不是数据、不是大标题,就并入表头区域。三层表头也能拼出 `联系方式 / 电话 / 手机`。 3. **合并单元格**:合并区域的左上角值会铺满整个区域,纵向合并的「姓名」不会变成空字段。 4. **标题行**:横跨大半张表的单格合并(如“XX局2026年在职干部职工信息表”)会被识别为大标题并跳过,不参与字段名。 5. **没有姓名列**:改用「第一行像数据的行」往上推一行作为表头,再往上合并分组表头。 识别结果在界面上是可见的(`表头:第 2-3 行`),不对就手动改,不用改代码。 --- ## 输出格式怎么保住的 不是新建工作簿,而是**复制原表,只把值写进它已有的列**: - 原有内容、表头、合并单元格、字体、边框、底色、行高列宽、冻结窗格全部保留 - **不新增列、不改表头**:回填目标一定来自原表自己的列,结构一动不动 - 匹配上的行直接覆盖写入;没匹配上的行只有勾了「未匹配」才会写标记,而且**只填原本是空的格子**,不会覆盖原表已有的内容 - 目标格落在合并单元格里时,值写进该合并区域左上角的格子,并在运行记录里提示(openpyxl 不允许往合并区的其他位置写值) ### 第五层:分组统计 选一张名单表,按乡镇、年龄、性别、学历、就业状态统计人数: - 自动识别这五个字段;识别不到或不想统计的维度选「不统计」 - 年龄优先用「年龄」列;没有年龄列时自动用「出生日期」或「身份证号」计算 - 年龄分组:25 岁以下 / 25-34 / 35-44 / 45-54 / 55-59 / 60 岁及以上 / 未知 - 生成统计表:总览 + 每个维度一张明细(人数、占比)+「乡镇×性别」「乡镇×就业状态」交叉表 - 空白值单独统计为「未填写」,不会悄悄丢掉 ### 第六层:两表比对 左边选上月名单(基准),右边选本月名单(对比): - 默认按身份证号比对;没有身份证号时按姓名 - 可再加一组次键(如姓名 + 出生日期),只有主键和次键都相同才算同一个人 - 结果列出:新增人员、退出人员、信息变化(逐项列出上月值 / 本月值)、重复人员 - 「本月名单标注」把本月每一行标成新增、信息变化、无变化、重复 - 主键为空的行不参与匹配,会单独提示;信息变化只比较两表都有的同名字段,序号、编号、来源文件不参与比较 ### 第七层:统计看图(透视表与图表) 按指定字段统计人数,自动生成统计表、透视表和透视图: - 支持按乡镇、年龄、性别、学历、就业状态等多个维度统计 - 自动生成每个维度的统计表和分布图表(饼图、柱状图) - 支持两个维度的交叉统计和堆叠柱状图 - 可选择是否生成透视表和透视图,灵活控制输出内容 - 自动检测重复数据并生成重复数据工作表 ### 第八层:数据打码 对敏感数据进行打码处理,保护隐私: - 选择要打码的列,设置从第几个字符开始,打码几个字符 - 可以设置多条规则,对多列进行打码,用 * 号表示 - 例如:身份证号从第7位开始打码4位,手机号从第4位开始打码4位 - 打码后的数据保持原有格式,适合在需要隐藏敏感信息的场景使用 --- ## 目录结构 ``` main.py 启动入口与页面路由表(ROUTES / CLI) app.py / engine.py 兼容入口:保留原来的 import 与双击用法,实际代码在 core/ 与 ui/ core/ 业务算法:base(表头识别/归一化/写值)、match、tools、check、 clean、pivot、stamp ui/ 界面:app、common、home、help、pages/(每个功能一个页面) build_dist.py 打免安装绿色版(自带 Python + 全部依赖 + 发布前自检) requirements.txt 源码方式运行所需依赖 samples/ make_samples.py 生成两份刁钻样例(多行表头 + 标题行 + 名字带空格 + 小写 x + 待回填的空列) test_engine.py 引擎自测 tests/ test_edge.py 边界场景:无姓名列 / 三层表头 / 回填不破坏原合并 / .xls 拦截 test_ui.py 无人工干预跑完整个界面流程 test_layout.py 控件有无溢出、挤压 test_split_merge.py 拆分 / 汇总:分组、保留格式、同义表头对齐 test_validate.py 数据校验:身份证校验位、性别/日期一致、重复、报告与标注版 test_bugfix.py Bug 修复回归:精度、表边界、安全写值、公式保护、校验口径等 14 组 test_entrypoints.py 界面→引擎签名全量核对、未定义调用扫描、合并 PDF 端到端、 Linux/LibreOffice 转换、坏文件降级、中文页码字体(10 组) selftest_all_features.py 全功能跨平台冒烟:17 项业务入口逐项真跑,输出 OK/SKIP/FAIL ``` 跑测试: ```bash python3 samples/test_engine.py python3 tests/test_edge.py python3 tests/test_ui.py python3 tests/test_layout.py python3 tests/test_split_merge.py python3 tests/test_validate.py python3 tests/test_bugfix.py python3 tests/test_entrypoints.py python3 tests/selftest_all_features.py # 全功能冒烟,Windows 上也跑这一份 ``` ### 跨平台验证说明 `selftest_all_features.py` 用真实数据逐项调用业务入口并输出结果清单, **在 Windows 和 Linux 上跑的是同一份脚本**:Windows 会自动走 Office COM、 `C:\Windows\Fonts` 字体等专有分支,补齐 Linux 无法验证的部分。当前开发机为 Linux,脚本在该环境的 17 项全部实测通过;**Windows 实机尚未验证过**, 交付 Windows 绿色版前请在那台机器上跑一次这个脚本,并人工双击确认启动脚本、 中文用户名路径、文件被 Excel 占用时的提示。macOS 不在验证范围内。 --- ## 出问题了怎么看 程序会自己留两个日志。优先写在程序目录(本文件夹);如果绿色版被解压到只读目录, 会自动改写到用户主目录或系统临时目录。 | 文件 | 内容 | | --- | --- | | `debug.log` | 启动信息、打开了哪个页面 | | `error.log` | 界面报错与**后台任务异常**的完整堆栈(同时会弹窗提示) | “点了没反应”时,先看 `debug.log`: - 只有「打开首页」、后面没有任何「打开 XXX」记录 → 点击事件根本没到控件上(窗口没激活 / 被别的窗口挡住 / 鼠标没点中) - 有打开记录但没有对应页面记录 → 切换页面时报错了,看 `error.log` 如果首页按钮实在点不动,可以绕过引导页直接进功能页: ```bash python3 app.py --match # 自动匹配 python3 app.py --split # 批量拆分 python3 app.py --merge # 数据汇总 python3 app.py --check # 数据校验 python3 app.py --stats # 分组统计 python3 app.py --compare # 两表比对 python3 app.py --mask # 按位打码 python3 app.py --pivot # 统计看图 python3 app.py --clean # 清洗工具选择页 python3 app.py --clean-address # 直达地址拆分 python3 app.py --clean-idcard # 直达身份证提取 python3 app.py --clean-text # 直达文本抠取 python3 app.py --clean-clean # 直达物理除脏 python3 app.py --stamp # 直达 PDF 套打 python3 app.py --stamp-word # 直达 Word 占位套打 python3 app.py --mergepdf # 直达合并 PDF ``` 多个启动参数同时出现时只生效第一个,并在终端给出提示。 --- ## 已知限制 - 原生支持 `.xlsx` / `.xlsm`;`.xls` 会先做有损转换(公式、部分格式、数字格式可能丢失),重要底稿请先在 Excel 里另存为 `.xlsx` - **15 位以上的编号(身份证、社保号等)如果被 Excel 存成「数值」,精度在存盘时就已经丢失**,程序读回时无法还原,会弹窗提醒。请在 Excel 里把该列设为「文本」并重新录入后再做匹配,否则不同编号可能被判成同一个人 - 匹配是“精确匹配”(归一化后完全相等),没有做模糊匹配(如“张 三”能对上“张三”,但“张叁”不行) - 数据来源表同一个键重复时取第一条,不合并 - 如果底稿里有图表、图片、数据透视表,openpyxl 保存后可能丢失(普通表格不受影响) - 单表特别大(十万行以上)时,读取和写回会有几秒等待,生成过程有日志但界面会短暂无响应 - 拆分会复制原文件后删行:行高、筛选区、打印区域、合并单元格会自动平移,但**公式引用、条件格式、数据验证、图表系列不随删行调整**,含这些对象的表请先另存副本核对 - 汇总按字段名 + 同义字段对齐,同名字段含义不同时可能被并到一列,生成后请抽查 - 汇总只读取每个文件自动识别的那一张工作表 - 身份证地区码只校验前两位省份,不校验完整 6 位行政区划 - 姓名、单位等重复按归一化后完全相同判断,不做模糊匹配 - 标注版只改单元格底色,不修改原值,也不自动修正数据 - 问题特别多时,报告「问题明细」会很长,建议先按严重程度筛选;超过 1,048,575 条会截断并在运行记录里提示,避免生成 Excel 打不开的文件 - 同一个单元格命中多条问题时,标注版只保留最严重的颜色 - 合并 PDF 加中文页码需要 `reportlab` 与系统中文字体;找不到中文字体时自动改用纯数字页码,不会画出方块 - 合并文件夹里的 Word / Excel 需要本机转换程序:**Windows** 用本机 Office + `pywin32`;**Linux / 国产麒麟 / macOS** 用系统安装的 `libreoffice`(命令行 headless,不需要 pywin32,绿色版也不内置)。两类转换程序都没有时,这些文件会被跳过并写进「未合并」清单,其余 PDF / 图片照常合并,不会整批失败 - 源码方式若缺少 PDF/图片相关组件,程序会尝试从国内镜像下载(带官方 sha256 校验、路径越界检查);完全离线的机器请按 `requirements.txt` 提前 `pip install` --- ## 下一步想加什么 - 校验规则可配置:必填字段、年龄范围、手机号段 - 匹配方式增加“包含 / 模糊匹配” - 底稿列顺序、列名映射 - 方案模板/配置记忆、批量任务队列、生成前差异预览与操作台账 调试时优先改 `core/base.py`(表头识别 `_detect_header()`、写值 `set_cell_value()` / `save_workbook()`) 与 `core/match.py`(匹配与回填 `generate()`)。`app.py` / `engine.py` 只是兼容入口。