Python人事档案管理系统：Excel批量导入导出、脱敏与幂等

简介：这是一套面向人事行政人员、中小企业管理者及需要整理员工档案的办公用户的人事档案管理系统破解版，主打易用、可定制与多场景数据处理，可用于员工信息登记、查询打印、统计分析和日常通讯录维护。系统支持CSV、XLS等格式导入导出与摄像头数据采集，能按学历、性别、年龄及年龄段、籍贯、婚姻状况、毕业院校等维度生成统计图表，并提供当天、本周、下周、下月生日提示；录入身份证信息后可辅助判断真伪并提取出生日期、性别、年龄和籍贯，树型分组便于透视管理。包体约3.16MB，文件总数与类型明细暂未提供，采用免安装的绿色软件形态，支持单机与网络环境，报表和界面也预留二次开发空间。已有1438人学习或下载，适合希望低成本搭建人事信息台账、快速上手统计与查询的读者参考使用。

1. 人事档案管理系统这类工具，我不建议你去下“破解版”

上个月有人甩给我一个压缩包，说找到一份人事档案管理系统破解版，功能强大还支持导入导出，让我帮忙看看能不能用。我解开目录扫了一眼就退回去了：里面塞了三个来路不明的 dll，外加一个开机自启的更新服务，导入导出模块本身倒确实是真货，可它导出的时候会顺手把整张员工表写进一个明文日志文件。这类包我碰得不少，功能是真的，代价是你全公司的身份证号、银行卡号、家庭住址全都躺在别人的回传通道里。

真正要解决的问题其实很朴素：把散在几十个 Excel 里的员工信息收进一个能查、能改、能批量导入导出的库，字段自己定，脱敏规则自己写。用 Python 加一个轻量 Web 框架，两三天能搭出可用版本，导入导出是重点，坑也恰好集中在这两块。下面这套是我给几个小团队落地过的版本，从表结构到流式导出一条线走通，照着抄能跑。

2. 数据模型先立住：18 个字段和一份导入契约

动手写接口之前，先把表结构和 Excel 模板定死。这两件事定错了，后面每加一个功能都要返工。我见过最常见的翻车方式，是把入职登记表原样搬进数据库——六七十列，一半常年空着，改个字段名要动前端、后端、导出模板三处。

2.1 拆成三张表，主表只留 18 个字段

我的切法是主表 + 任职记录表 + 附件表。主表只放“不随调岗变化”的稳定信息，工号、姓名、证件、联系方式、入职日期这些；调岗调薪、部门变更全部进任职记录表，一条变更一条记录，带生效日期；劳动合同扫描件、学历证明这类走附件表存路径和哈希，不塞进数据库 BLOB。

这样切的好处很直接：员工主表宽度可控，导出时字段枚举简单；任职历史天然是时间序列，算司龄、算在岗人数不用做复杂的状态回溯；附件单独存，备份和迁移时可以分开处理。

id_card上必须建唯一索引，这是后面做幂等导入的地基。dept_code不要存部门中文名，中文名一改，历史数据全对不上，用编码关联部门表最稳。

2.2 导入模板的六条硬约束

模板这一层不做约束，代码里就要用十倍的量去兜底。我一般把规矩写在模板首页的说明 sheet 里，同时代码里也校验一遍：

1. 第一个 sheet 必须是数据页，名字固定为employees，说明页放第二个 sheet，读取时忽略。
2. 第一行是表头，列名与字段映射表一一对应，不允许合并单元格，不允许空列插在中间。
3. 日期列统一YYYY-MM-DD，不接受2024/1/5、20240105这种变体。
4. 证件号、手机号、银行卡号三列，列格式必须设成“文本”，否则 Excel 会把 18 位身份证按浮点数截断成科学计数法。
5. 枚举列（性别、员工状态、学历）在模板里做数据有效性下拉，减少脏值。
6. 单次导入上限 5000 行，超过就拆文件。这个限制不是为了省内存，是为了让失败回执可读。

2.3 建表与模型定义

用 SQLAlchemy 2.x 的声明式写法，SQLite 起步够用，团队大了换 MySQL 只改连接串。

# models.py from datetime import date, datetime from sqlalchemy import String, Date, DateTime, UniqueConstraint, Index from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column class Base(DeclarativeBase): pass class Employee(Base): __tablename__ = "employee" id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True) emp_no: Mapped[str] = mapped_column(String(32), nullable=False) name: Mapped[str] = mapped_column(String(64), nullable=False) # 唯一索引，幂等导入靠它兜底 id_card: Mapped[str] = mapped_column(String(32), nullable=False, unique=True) gender: Mapped[str] = mapped_column(String(8), default="未填") birth_date: Mapped[date | None] = mapped_column(Date, nullable=True) mobile: Mapped[str | None] = mapped_column(String(20)) email: Mapped[str | None] = mapped_column(String(128)) dept_code: Mapped[str] = mapped_column(String(32), nullable=False) job_title: Mapped[str | None] = mapped_column(String(64)) hire_date: Mapped[date] = mapped_column(Date, nullable=False) leave_date: Mapped[date | None] = mapped_column(Date) emp_status: Mapped[str] = mapped_column(String(16), default="在职") edu_level: Mapped[str | None] = mapped_column(String(16)) contract_end: Mapped[date | None] = mapped_column(Date) bank_account: Mapped[str | None] = mapped_column(String(64)) emergency_contact: Mapped[str | None] = mapped_column(String(64)) remark: Mapped[str | None] = mapped_column(String(512)) updated_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow) __table_args__ = ( # 工号也做唯一，防止同一个人两条工号记录 UniqueConstraint("emp_no", name="uq_emp_no"), Index("ix_dept_status", "dept_code", "emp_status"), )

上面的模型里，unique=True加在id_card上是整套方案里最关键的一行。导入重复文件时，数据库这一层会直接拒绝写入重复证件号，不需要业务代码里做全表扫描比对。ix_dept_status这个联合索引是给「按部门统计在职人数」这类查询准备的，导出全量数据时用不上，但日常列表页离不开它。

updated_at用onupdate自动维护，比在每个 service 里手写now()省心。日期字段一律可空，除了hire_date——没有入职日期的记录没法算司龄，也没法进统计口径，宁可导入时拒掉。

建库脚本用Base.metadata.create_all()，正式环境再引入 Alembic 做迁移版本控制。

3. Excel 批量导入：三层校验流水线

导入是整个系统里最容易出事故的地方。用户手里的 Excel 什么样都有：表头多个空格、日期写成“2024年3月”、身份证后面偷偷跟了一个回车、同一个文件导两遍。把校验拆成三层，出问题的时候能精确定位到是文件坏了、行坏了还是某个字段坏了。

3.1 文件级、行级、字段级各管一段

文件级校验在读数据之前完成：后缀必须是.xlsx（.xls直接拒，老格式解析库行为不一致）、文件大小不超过 10MB、sheet 名存在、表头集合与预期完全一致（多一列少一列都拒，宁可让用户改模板，也别做模糊匹配）。

行级校验看跨字段关系：hire_date不能晚于leave_date；状态是「离职」时leave_date必须有值；birth_date与hire_date间隔不能小于 16 年，小于这个数基本是日期填错了。

字段级校验最细：必填非空、长度上限、枚举白名单、证件号校验码、手机号号段、邮箱正则。三层各自返回一个错误列表，最后合并成一份错误回执。

# validators.py import re from datetime import date ID_WEIGHTS = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2] ID_CHECK = "10X98765432" def check_id_card(id_no: str) -> bool: """18 位身份证校验：长度 + 出生日期合法性 + 加权校验码""" if not id_no or len(id_no) != 18: return False if not id_no[:17].isdigit(): return False try: year, month, day = int(id_no[6:10]), int(id_no[10:12]), int(id_no[12:14]) date(year, month, day) # 日期不合法会抛异常 except ValueError: return False total = sum(int(id_no[i]) * ID_WEIGHTS[i] for i in range(17)) return id_no[17].upper() == ID_CHECK[total % 11] def check_mobile(mobile: str) -> bool: """只做宽松校验：11 位数字且以 1 开头，号段变化太快不适合写死""" return bool(re.fullmatch(r"1\d{10}", mobile or "")) def check_date_range(birth: date | None, hire: date | None) -> bool: """出生日期与入职日期至少间隔 16 年""" if not birth or not hire: return True return (hire - birth).days >= 16 * 365

check_id_card里三件事缺一不可：长度和纯数字是第一道闸；date(year, month, day)这一步能揪出20241301这种不存在的日期，很多人只写正则\d{18}就放过去了；加权求和取模是国标校验位，能挡掉绝大多数手输错误。check_mobile故意不做号段白名单，运营商号段一年变好几次，写死等于给自己埋雷，宽松校验加人工复核更实际。

3.2 读文件时避开 openpyxl 的默认行为

openpyxl有个默认行为要注意：单元格如果存的是数字，读出来就是int或float，不是str。身份证被 Excel 存成数字之后，第 18 位会直接丢失精度，变成1.10101e+17，这时候无论怎么校验都救不回来，只能报错让用户改列格式重新导出。

# importer.py from openpyxl import load_workbook from datetime import datetime, date HEADER_MAP = { "工号": "emp_no", "姓名": "name", "证件号": "id_card", "性别": "gender", "出生日期": "birth_date", "手机号": "mobile", "邮箱": "email", "部门编码": "dept_code", "岗位": "job_title", "入职日期": "hire_date", "离职日期": "leave_date", "员工状态": "emp_status", "学历": "edu_level", "合同到期日": "contract_end", "银行卡号": "bank_account", "紧急联系人": "emergency_contact", "备注": "remark", } def read_sheet(path: str) -> list[dict]: wb = load_workbook(path, read_only=True, data_only=True) ws = wb["employees"] rows = ws.iter_rows(values_only=True) header = [str(c).strip() if c is not None else "" for c in next(rows)] mapping = {i: HEADER_MAP[h] for i, h in enumerate(header) if h in HEADER_MAP} result = [] for line_no, row in enumerate(rows, start=2): # 2 = 数据首行行号 if all(c is None or str(c).strip() == "" for c in row): continue # 整行空白直接跳过 item = {"_line": line_no} for idx, field in mapping.items(): item[field] = normalize(row[idx] if idx < len(row) else None) result.append(item) return result def normalize(value): """统一成字符串并去空白；日期单元格单独转 ISO 格式""" if value is None: return None if isinstance(value, datetime): return value.date().isoformat() if isinstance(value, date): return value.isoformat() if isinstance(value, float) and value.is_integer(): return str(int(value)) # 手机号被读成 138.0 的情况 return str(value).strip()

read_only=True对大文件很重要，不加这个参数会把整个工作簿加载进内存。data_only=True让公式单元格返回计算结果而不是公式字符串，模板里如果有=TODAY()这种列，不加就会读到TODAY()五个字符。

normalize里那两个isinstance分支是血泪经验：Excel 里手机号存成数字，读出来是13800138000.0，不做转换直接入库，后面按手机号查人永远查不到。日期单元格读出来是datetime对象，直接str()会得到2024-03-05 00:00:00，跟数据库的DATE类型对不上。

3.3 事务策略：全量拒绝还是部分成功

两种策略要提前跟业务方对齐，别自己拍板。

全量拒绝的做法是整批数据在一个事务里，任何一行校验失败就rollback，返回错误回执让用户改完重传。适合首次初始化导入，数据量不大、要求干净。部分成功是把合法行写进去，非法行进错误列表返回，适合日常增量维护，用户不用为一个错别字重传三千行。

我默认用全量拒绝，理由是人事数据的完整性强于便利性，半截导入的状态最难排查。实现上用 SQLAlchemy 的会话上下文：

# service.py from sqlalchemy.orm import Session from sqlalchemy.exc import IntegrityError def import_employees(db: Session, rows: list[dict]) -> dict: errors = [] for item in rows: errs = validate_row(item) # 三层校验合并结果 if errs: errors.append({"line": item["_line"], "msg": "；".join(errs)}) if errors: return {"ok": 0, "failed": len(errors), "errors": errors[:100]} try: for item in rows: db.add(Employee(**strip_meta(item))) db.commit() # 任意一条违反唯一索引都会在这里炸 except IntegrityError as e: db.rollback() return {"ok": 0, "failed": len(rows), "errors": [{"line": 0, "msg": f"唯一键冲突：{e.orig}"}]} return {"ok": len(rows), "failed": 0, "errors": []}

errors[:100]这个截断别省，五千行的错误回执原样返回给前端，浏览器渲染都能卡住。错误信息里带上 Excel 行号，用户对着行号改，比给他一句“数据不合法”有用一百倍。

db.add循环之后统一commit，不要每行 commit 一次，五千行五千次事务，SQLite 上能跑出分钟级耗时。

4. 导出与脱敏：同一份数据，不同的人看到不同的列

导出比导入更容易出事，因为导入错了顶多数据脏，导出错了是数据泄露。人事系统里最敏感的三列是身份证、银行卡号、薪资（如果表里有），任何一次导出都要过一遍权限和脱敏两道闸。

4.1 导出接口的入参设计

接口不做成GET /export/all，而是显式接收字段清单和范围：

# 只导出本部门在职员工的基础字段 curl -G "http://127.0.0.1:8000/api/employees/export" \ --data-urlencode "fields=emp_no,name,dept_code,job_title,hire_date" \ --data-urlencode "dept_code=D001" \ --data-urlencode "emp_status=在职" \ -H "Authorization: Bearer <token>" \ -o staff.xlsx

fields参数必须跟后端维护的「可导出字段白名单」求交集，不在白名单里的字段直接丢弃，不报错也不透传。这一层写死之后，前端传什么参数都越不过去。dept_code这类过滤条件还要再过一层数据权限：普通 HR 只能导自己部门，管理员才能跨部门。

4.2 脱敏规则按角色分档

脱敏不要在导出时临时判断，做成规则表配置，改规则不改代码。

有一点要注意：脱敏在导出环节做，但查询列表页也要做同样的处理，两处的规则必须调用同一个函数。我见过列表页脱敏了、导出没脱敏的实现，等于白做。

# mask.py def mask_id_card(v: str) -> str: if not v or len(v) < 8: return v or "" return v[:3] + "*" * (len(v) - 7) + v[-4:] def mask_mobile(v: str) -> str: if not v or len(v) != 11: return v or "" return v[:3] + "****" + v[-4:] def mask_bank(v: str) -> str: digits = "".join(ch for ch in (v or "") if ch.isdigit()) return f"**** **** {digits[-4:]}" if len(digits) >= 4 else "" MASK_RULES = { "id_card": mask_id_card, "mobile": mask_mobile, "bank_account": mask_bank, }

mask_id_card里用len(v) - 7算星号个数，是为了兼容 15 位老身份证，写死 11 个星号在 15 位数据上会错位。mask_bank先把非数字字符剔掉再取后四位，用户填卡号时带空格或者横杠是常态。

4.3 十万行导出不撑爆内存的写法

openpyxl的普通模式会在内存里维护整棵单元格树，十万行二十列能吃掉一个多 G。用write_only=True模式，行是边生成边往临时文件写，内存占用跟行数基本无关。

# export.py import tempfile from openpyxl import Workbook from fastapi.responses import FileResponse def export_to_file(rows_iter, headers, path_map, raw_fields): wb = Workbook(write_only=True) ws = wb.create_sheet("员工档案") ws.append(headers) for row in rows_iter: # rows_iter 是生成器，逐条从库里取 line = [] for field in raw_fields: v = row.get(field) if field in MASK_RULES: # 敏感列走脱敏 v = MASK_RULES[field](v) line.append(v) ws.append(line) tmp = tempfile.NamedTemporaryFile(suffix=".xlsx", delete=False) wb.save(tmp.name) return tmp.name

rows_iter一定要是生成器，用yield_per分批从数据库里取，比如每批 2000 条，取完一批写一批。如果写成db.query(Employee).all()再循环，前面省下的内存又全还回去了。

ws.append()传的列表长度必须和表头一致，write_only模式下不检查这个，缺列会静默错位，导出的文件打开才发现整列偏移。加一句断言assert len(line) == len(headers)能省掉排查半天。

导出完成后用FileResponse返回，文件名放在Content-Disposition里，中文名要做 URL 编码，否则某些浏览器下载下来是乱码：

from urllib.parse import quote filename = quote("员工档案_20240305.xlsx") headers = {"Content-Disposition": f"attachment; filename*=UTF-8''{filename}"}

5. 避坑与排查：导入导出环节最常翻的 5 个车

下面这几条都是我在实际项目里被咬过的，现象、原因、解决办法按顺序摆出来，遇到同类问题直接对照。

现象一：导入后身份证全变成了科学计数法，18 位只剩 15 位有效数字。原因：Excel 把长数字串当浮点数处理，超过 15 位精度就丢了，代码侧拿到的已经是错数据。解决：模板里三列长数字预设为文本格式；读取时判断isinstance(value, float)就报错回执，明确告诉用户「证件号列请设置为文本格式后重新粘贴」，不要试图用代码还原，还原不出来。

现象二：同一个 Excel 传了两遍，库里多出一倍重复员工。原因：只做了应用层的「先查再插」，并发或者重复提交时，查和插之间有窗口期，两个请求都查不到就都插进去了。解决：数据库唯一索引是底线，id_card和emp_no都建唯一约束；应用层再用INSERT ... ON CONFLICT DO UPDATE或者捕获IntegrityError转成友好提示。光靠应用层判断，早晚出事。

现象三：日期列一半能导进去，一半报格式错误。原因：同一个 Excel 里，有的日期是真正的日期单元格，有的是用户手打的文本「2024.3.5」，normalize出来一个是2024-03-05，一个是2024.3.5。解决：normalize里对字符串日期做一次多格式尝试解析，用datetime.strptime依次试%Y-%m-%d、%Y/%m/%d、%Y.%m.%d，全失败才报错；同时在错误回执里带上原始值，让用户看到自己填的是什么。

现象四：导出十万行时接口超时，或者直接把容器 OOM 干掉。原因：一次性all()加载全表，加上普通模式openpyxl的单元格树，内存翻好几倍。解决：生成器分页取数（yield_per(2000)）、Workbook(write_only=True)、写临时文件后FileResponse返回，三件套一起上。另外记得在finally里删临时文件，不然跑几天磁盘就满了。

现象五：列表页脱敏了，导出接口忘了脱敏，银行卡号原样流出。原因：脱敏逻辑写在视图层而不是数据层，新增一个导出接口就漏一次。解决：把脱敏收敛到序列化层，所有出口（列表、详情、导出）统一走同一个to_dict(role)方法，字段级权限在方法内部判断。再加一条自动化测试：用普通 HR 角色调用所有导出接口，断言响应里不含完整身份证号。

6. 把导入做成幂等任务：任务号、指纹与上线自检表

导入功能做到能跑只是及格线，真正让人省心的是幂等。用户点两次提交、网络抖动重试、批量脚本重复调用，结果都应该是「数据不变」。我的做法是给每次导入生成一个任务号，同时算一个文件指纹。

import hashlib, uuid def make_task(path: str) -> dict: h = hashlib.sha256() with open(path, "rb") as f: for chunk in iter(lambda: f.read(8192), b""): h.update(chunk) return {"task_id": str(uuid.uuid4()), "fingerprint": h.hexdigest()}

指纹入库存一张import_task表，字段是fingerprint、task_id、status、row_count、created_at。同一个指纹第二次进来，直接返回上次的结果，不重复执行。这里有个细节：指纹要按「文件字节」算，不要按「解析后的数据」算，因为用户可能只是改了单元格格式，内容没变，按内容算会误判成新任务。

指纹方案有个坑要提前想清楚：用户改了文件里一个错别字重传，指纹变了，会当成新任务跑一遍。这时候唯一索引会挡住重复的id_card，但其他行的更新就丢了。所以我在import_task上加一个「覆盖模式」开关，开启时走ON CONFLICT DO UPDATE，只更新非空字段，避免把用户没填的列覆盖成空。

上线前我固定跑一遍这张自检表，五条全过才敢交付：

最后一条经验是踩出来的：有一次给某团队部署，导出五万行的时候容器被 OOM kill，日志里什么都没有，排查了半天才发现是某个同事在export里加了.all()。从那以后我每次上线导入导出，都强制先把这张自检表跑一遍，尤其是「重复导入」和「大文件内存」两项，宁可多花二十分钟，也不想半夜被电话叫醒。希望帮到你。

本文还有配套的精品资源，点击获取