04
数据准备 · 来源归一

考勤来源归一

attendance-source-normalizer
🧲
数据准备 skills/attendance/
把散落在源目录、.msg 附件、邮件正文、视觉记录里的多来源考勤资料，归一为一份可复核的统一审核入口。只回答三件事：资料是什么、属于谁、是什么证据类型。异常交给 exception-review，备注交给 remarks。
◧

FLOW TYPES

适用客户B 型 / 邮件凭证型
珠海基石
客户系统导出原始记录（非钉钉直接导出）+ 中台 .msg 补卡 / 加班 / 出差 / 年假凭证。
奥托立夫
钉钉考勤报表 + 补卡 / 加班 / 出差 / 请假 / 外出子表（5 类从 OA 假勤管理导出）。
复宏汉霖
公司名 + 员工名 + 考勤 / 审批 .msg，夹杂图片 / PDF / Excel 附件。
英伟达
公司名 + 员工名 + 考勤 / 审批 .msg，夹杂图片 / PDF / Excel 附件。
⚡

TRIGGERS

触发场景
▸大量 .msg 补卡 / 加班 / 出差凭证要归集
▸来源散落于邮件 / 附件 / 图片 / PDF，先认清「谁的、什么证据」
▸钉钉凭证整理、msg 凭证归集
▸B 型客户进异常审核前要一份可审计的来源清单
⊢

PREREQUISITE

前置条件先跑 data-prep
←
运行本 skill 前，先用 data-prep 的 extract_msg_attachments.py 抽出 .msg 附件。
←
再用 preprocess_pdfs_for_vision.py 对 PDF 做预渲染，供后续视觉记录使用。
PREP · 前置命令
uv run python skills/attendance/attendance-data-prep/scripts/extract_msg_attachments.py \
  data/raw/<目录名> outputs/<目录名>/attachments

uv run python skills/attendance/attendance-data-prep/scripts/preprocess_pdfs_for_vision.py \
  outputs/<目录名> \
  --source-dir data/raw/<目录名> \
  --source-dir outputs/<目录名>/attachments
↹

INPUT & OUTPUT

输入 / 产出
↘ INPUT · 输入
  • data/raw/<目录名>（源目录）
  • attachments/（data-prep 已抽附件）
  • reference_roster.xlsx（可缺省 · 缺则未定位来源进待追问）
  • _email_texts.jsonl（邮件正文）
  • vision_extracted_records.jsonl（可缺省 · 缺则不阻塞）
↗ OUTPUT · 产出
  • normalized_sources.xlsx
  • 三 sheet：来源归一 · 归属覆盖 · 待追问
  • 交付 HR 时引用 xlsx，不只给 JSON / JSONL
▤

SHEETS

产物清单normalized_sources.xlsx
来源归一
来源文件、来源类型、归属员工、证据类型、邮件主题、状态、说明。
归属覆盖
每个员工已归属来源数和证据类型，归属缺口一目了然。
待追问
无法归属或证据类型无法分类的来源。
🪜

STEPS

处理流程
  1. 1
    汇集所有来源
    .msg、Excel、PDF、图片全部进「来源归一」；.msg 已抽附件，原始邮件也不能漏。
  2. 2
    归属员工
    从 reference_roster.xlsx、邮件主题、文件名、视觉记录多路匹配员工名；匹配不到进「待追问」。
  3. 3
    分证据类型
    至少区分补卡、加班、出差 / 公出、外出、请假 / 休假、考勤汇总、审批。
  4. 4
    算归属覆盖
    汇总每个员工已归属来源数与证据类型，写入「归属覆盖」sheet。
⌘

RUN

运行命令
RUN · 运行命令
uv run python skills/attendance/attendance-source-normalizer/scripts/normalize_attendance_sources.py \
  data/raw/<目录名> \
  outputs/<目录名>/normalized_sources.xlsx \
  --attachments-dir outputs/<目录名>/attachments \
  --reference-roster outputs/<目录名>/reference_roster.xlsx \
  --email-texts outputs/<目录名>/_email_texts.jsonl \
  --vision-records outputs/<目录名>/vision_extracted_records.jsonl
⇄

PIPELINE

与其他 skill 衔接
←
上游 data-prep：抽 .msg 附件、PDF 预渲染、产出 reference_roster.xlsx 与视觉记录。
→
下游 exception-review：拿来源清单判异常。
→
下游 remarks：算考勤备注。
✓

ACCEPTANCE

闭环验收
⊘

ANTI-PATTERNS

反例检查
✗
.msg 已抽附件，但原始邮件没有进入来源清单。
✗
只按文件名归属员工，忽略了 roster、邮件主题或视觉记录中的员工名。
✗
把客户名、公司名、部门名当成员工名。
✗
图片 / PDF 仍待识别，却被标成已解析考勤结论。
↺

FALLBACK

失败重试
✗
缺 reference_roster.xlsx：先生成来源清单，但所有无法从文件名 / 主题确定的来源必须进入「待追问」。
✗
缺 _msg_meta.json：先回 data-prep 抽取附件，再重跑本 skill。
✗
缺视觉记录：不阻塞来源归一，把图片 / PDF 保留为待归属或待分类来源。
⌥

LESSONS

复盘沉淀
⤳
B 型客户的问题不是单个 Excel 解析失败，而是凭证散落在邮件、附件、图片、PDF 中——必须先归一再进异常审核。
⤳
新的来源类型、误归属模式、证据分类关键词写入本 skill 的 LESSONS.md；重复出现后再提升为脚本规则和测试。