一、立项背景与目标
中小企业的行政、财务、HR 每天在做大量"打开表格→复制→粘贴→另存为"的机械动作:月末汇总各部门报销单、按部门拆分工资表、把系统导出的乱码 CSV 转成 Excel、批量重命名几百张扫描件。这类活单次十分钟,但每月重复几十次,且极易出错——漏行、串行、甚至覆盖掉原始文件。市面上的同类工具要么功能单一,要么要求把数据上传到云端处理,企业出于数据安全顾虑不敢用。
因此目标是做一个纯本地运行、零配置、覆盖高频办公场景的命令行工具箱,一次安装解决 11 类重复劳动。
二、核心功能模块
1. 表格处理:多表合并(按表头并集自动对齐,支持来源标记与整体去重)、按列拆分(按部门/客户拆表)、Excel 与 CSV 互转(自动识别 GBK 编码与分隔符)、数据清洗(去重、删空行空列、清理空格)。
2. 文件处理:批量重命名(替换/正则/前后缀/序号,带冲突检测)、文件自动归档(按用途/扩展名/日期/月份分类)、文件清单生成(含 MD5 校验,用于交付验收)。
3. Word 批处理:批量文本替换(正文、表格、页眉页脚全覆盖)、模板加 Excel 数据批量生成通知/合同。
4. PDF 处理:多文件合并、按页或按页码范围拆分。
三、业务流程与功能路径
命令行路径:omate <功能> <路径> [参数] --dry-run 先预演确认 → 去掉 --dry-run 正式执行 → 自动生成 Markdown/CSV 处理报告。
面向不熟悉命令行的使用者,另提供交互式中文菜单:不带参数运行 omate 即进入菜单,按数字选功能、按提示逐项填参数,执行前回显等价命令行,兼顾易用性与后续学习迁移。
所有写文件的操作都遵循"绝不静默覆盖"原则,目标同名时自动追加 _1、_2。
一、整体架构与设计思路
采用"注册表 + 任务类"的插件式架构:每个功能继承 Task,实现 configure()(声明参数)与 execute()(返回处理报告),CLI 与交互式菜单从同一张注册表生成,新增功能无需改动任何入口代码。
分层:core/task.py 任务协议与注册表;core/report.py 处理报告(终端/Markdown/CSV);core/excel.py Excel 读写(列宽自适应、表头冻结、自动筛选);core/fsutil.py 文件工具(不覆盖策略、自然排序);console.py 终端输出层(颜色降级、中英文混排对齐);cli.py / menu.py / runner.py 负责入口、菜单与执行汇总,后两者共用 runner 保证行为一致。
技术栈:Python 3.9+、openpyxl(唯一必需依赖)、python-docx 与 pypdf(可选扩展)、pytest、ruff、GitHub Actions。
二、我负责的模块与量化结果
独立完成需求拆解、架构设计、全部编码与测试:
1. 11 个功能任务,22 个源码文件共 2700 行,核心框架仅 521 行;
2. 104 个 pytest 用例(775 行),覆盖各任务的成功与异常路径;
3. GitHub Actions 在 Ubuntu + Windows 双平台 × Python 3.9/3.11/3.12/3.13 共 8 个环境矩阵上验证,加静态检查共 9 个 CI 任务,全部通过;
4. 端到端演示脚本 8 个步骤全部成功。
三、难点与解决方案
1. 批量重命名不毁数据:逐个改名时 A↔B 互换会互相覆盖,撞名时更会静默丢文件。改为"全局冲突检测 + 两阶段重命名(先全改临时名再改最终名)+ 失败回滚",真实数据上成功拦截 4 处冲突。
2. Word 占位符跨 run:手工输入的占位符会被 Word 拆成多个 run 存储,按 run 遍历替换必然失败,改为合并整段文本后替换、再写回首个 run。
3. CSV 编码混乱:国产系统导出常见 GBK,也有带 BOM 的 UTF-8,实现多编码依次试探加分隔符嗅探,转出统一用 utf-8-sig 保证 Excel 不乱码。
4. 中英文混排错位:len() 计算宽度会让含中文的表格错位,改用 unicodedata.east_asian_width 按东亚宽字符(占 2 列)计算。
5. 打包踩坑:PEP 639 下 license 表达式与 License classifier 不能共存,会导致 pip install 直接失败,构建 wheel 时才暴露。