Excel 名单整理
规矩（每次都要遵守）
- 原文件只读，不覆盖。 脚本只读名单，结果一律另存为新文件（原文件名后面加「_整理结果」或「_对比_另一个名单」，重名自动加 _1、_2）。不要用任何别的办法改用户的原表。
- 先认列，再动手。 第一次拿到名单先跑
check，用大白话告诉用户：表头在第几行、哪一列是姓名/手机号/身份证号/部门/日期、发现了哪些问题。输出里写着「不确定，请确认」的列，必须先问用户认得对不对，确认了再整理。认错了就用--col改。 - 去重分两种，只删完全一样的。 完全重复（整理后每一格都一样，序号列不算）才去掉；身份证号相同、或姓名+手机号相同但其他信息不同的，是「疑似重复」，只标出来，由用户自己决定留哪条，不要替用户删。
- 数字以脚本为准。 校验结果、年龄、人数一律照脚本输出说，不要心算、不要自己改号码。校验码不对时，只告诉用户「号码里有一位写错了，要回原始资料核对」，不要猜、不要帮用户把号码改成能通过校验的样子。
- 隐私（身份证号、手机号是敏感个人信息）：
- 全部在本机处理，不联网、不上传、不调用任何在线服务。
- 只做格式校验：手机号只看位数和号段，不查归属地、不查机主；身份证号只算校验码和号码里的出生日期、性别，不做「用身份证号查人」「查真伪」「查户籍」之类的事，用户要求也不做，告诉他这类查询要去公安、社保等正规渠道办理。
- 整理结果默认把身份证号中间打星号（留前 6 位和后 4 位）。用户明确说要完整号码（比如要导入系统、报社保）才加--full-id，并提醒他妥善保管。要发给别人的，建议再加--mask-phone把手机号也打码。
- 每次交付都提醒一句：文件里有个人信息，别发到群里或公开网盘，用完把不需要的副本删掉（让用户自己删，你不要删）。
- 跟用户说话、写总结时不要把完整的身份证号、手机号念出来，提到某个人用姓名和行号就够了。 - 组件缺了只提示，不自动装。 缺 openpyxl 时脚本会提示安装命令，由用户自己决定装不装。
- 跟用户说话用大白话，一步一步来，不提命令参数和程序里的名字，只说「按身份证号去重」「身份证号打星号」这类话；但用户问起在运行什么，要如实说明。
用法
脚本：python {baseDir}/scripts/roster_clean.py <子命令> <文件路径> [选项]，路径有空格要加引号。全程不调用其他程序。
| 子命令 | 做什么 | 会不会动原文件 |
|---|---|---|
check 文件 |
认列 + 问题体检（多少个号码有问题、几行重复），不生成文件 | 只读 |
clean 文件 |
整理 + 去重 + 统计，生成新 Excel | 只读，另存新文件 |
stats 文件 |
只在屏幕上统计人数（按部门/班级、性别、年龄段） | 只读，不生成文件 |
compare 名单A 名单B |
两个名单对比，生成新 Excel | 两个都只读，另存新文件 |
常用选项：
| 选项 | 意思 |
|---|---|
--col 含义=列名 |
手动指定列，可写多次：--col 姓名=员工、--col 日期=入职日期,出生日期；--col 部门=无 表示没有这一列。含义可写：姓名、手机号、身份证号、部门、性别、日期 |
--key 依据 |
疑似重复 / 对比按什么判断：身份证、手机号、姓名、姓名+手机号，也可写表里的列名如 工号。不写：去重有身份证按身份证，否则按姓名+手机号，再否则按姓名；对比依次优先身份证、手机号、姓名 |
--full-id |
身份证号完整显示（默认中间打星号） |
--mask-phone |
手机号中间 4 位也打星号 |
--date-style 横杠/斜杠/中文 |
日期统一成 2026-01-05 / 2026/01/05 / 2026年1月5日，默认横杠 |
--asof 2026-10-05 |
年龄算到哪一天，默认今天（比如按入学当年 9 月 1 日算就写那天） |
--age-bands 18,35,60 |
年龄段分界，默认 18,30,40,50,60 |
--by 列名 |
统计按哪一列分组，默认认出的部门/班级列 |
--sheet 名称 |
指定工作表；对比时用 --sheet-a / --sheet-b |
--col-a / --col-b |
对比时分别给 A、B 名单手动指定列 |
--out 路径 |
仅原名单目录或其子目录（不能和原文件同名；拒绝越界或链接到外部的路径） |
大白话 → 怎么做
| 用户说 | 怎么做 |
|---|---|
| 「帮我看看这个名单有没有问题」 | check 文件，把认出的列和问题数念给用户，有「不确定」的列先问 |
| 「把名单整理一下 / 去重 / 姓名里的空格去掉」 | 先 check，确认列没认错后 clean 文件 |
| 「检查一下身份证号对不对」「手机号有没有填错的」 | clean 文件，告诉用户有几个号码有问题、在哪几行，叫他打开结果文件看黄色的行 |
| 「从身份证里提取出生日期、性别、年龄」 | clean 文件；要按某天算年龄就加 --asof 那天 |
| 「我要完整的身份证号，要导入系统」 | clean 文件 --full-id，提醒妥善保管 |
| 「要发给别人，号码都打码」 | clean 文件 --mask-phone（身份证默认已打码） |
| 「按姓名去重就行」「同名同手机号算重复」 | 加 --key 姓名 / --key 姓名+手机号 |
| 「日期都改成 2026年1月5日 这种」 | 加 --date-style 中文 |
| 「对比一下这两个名单，看谁没报名 / 谁没签到」 | compare 名单A 名单B；告诉用户「只在 A」「只在 B」「信息不同」各几人 |
| 「按身份证对比」「按手机号对比」 | 加 --key 身份证 / --key 手机号 |
| 「各部门多少人、男女各几个、60 岁以上几个」 | stats 文件；年龄段要自定就加 --age-bands 60 这类 |
| 「部门那列认错了，应该是『科室』」 | 加 --col 部门=科室 |
| 「帮我查查这个身份证是谁的 / 是不是真的」 | 不做。说明本工具只检查号码格式，查人、查真伪要去公安、社保等正规渠道 |
整理结果里有什么
- 说明：原文件名、认出的列、做了哪些整理、去重依据、身份证号是否打码、隐私提醒。
- 整理后名单：去掉完全重复后的名单，第一列是原表行号方便回去找；后面加了「出生日期（按身份证）」「性别（按身份证）」「年龄」三列（有身份证号列时）；最后一列「问题说明」。有问题的整行标黄，出问题的那一格标橙。
- 问题清单：每个问题一行：原表行号、姓名、哪一列、原来填的、整理后、问题是什么。
- 完全重复（已去掉）：被去掉的行，以及和第几行一样。
- 疑似重复（待确认）：按组列出，说明哪一列相同、哪几列不同，没有删。
- 统计：总人数（已去掉完全重复），按部门/班级（含男女）、性别、年龄段的人数。
对比结果文件：对比结果（人数汇总）、只在A、只在B、两边都有但信息不同（每个不同点一行，A、B 各填的什么）、两边一致、没法对比（关键列没填）。
会查出哪些问题
- 姓名：没填、有数字、有括号或符号（夹了备注）、只有 1 个字。
- 手机号：没填、不是 11 位、开头不是 13~19、号段不常见、像座机号、一格填了多个号码、夹了文字。
- 身份证号：没填、位数不对、有不该有的字符、地区代码不存在、出生日期不是真实日期或在今天之后、校验码不对、15 位老号码、被 Excel 存成数字或科学计数法（后几位已丢失）；和表里填的性别、出生日期对不上。
- 日期：认不出来的写法。性别：不是男/女。
需要的组件
- 必须：Python 3.8+、openpyxl（读写 Excel）。缺了脚本会提示
pip install openpyxl，由用户决定装不装。 - 只用 Python 自带功能和 openpyxl，不需要别的组件。
不做什么
- 不修改、不覆盖、不删除用户的原文件和任何其他文件。
- 不联网、不上传，不查手机号归属地、不查机主、不做身份证号查人/查真伪/查户籍。
- 不替用户删疑似重复的行，不猜、不改写错的号码。
- 不自动安装任何组件，不运行其他程序，不在后台常驻。
- 不读老版本 .xls 和 WPS 的 .et 格式（请用户另存为 .xlsx）；不破解有密码的文件。
v0.1.1 隐私与输出修复
所有已映射的身份证与手机号列按所选脱敏模式处理。每个写入单元格还按值识别 15/18 位身份证号和手机号，包含未识别列、问题清单和说明文字；默认身份证脱敏，手机号按 --mask-phone 脱敏。--full-id 是用户明确要求完整身份证号时的例外。输出限制到原名单目录及子目录，拒绝路径穿越和符号链接越界。
