05
审核 · 异常

考勤异常审核

attendance-exception-review
🔎
审核与计算 skills/attendance/
接在 attendance-data-prep 之后，把资料来源和异常问题整理成可复核的考勤异常审核工作簿——来源清单 / 员工覆盖 / 异常清单 / 待追问 / 处理日志。不直接生成最终考勤备注，也不猜测截图、审批结论或客户特殊口径。
⚡

TRIGGERS

触发场景
▸考勤异常审核 / 考勤待追问
▸缺卡审批核验
▸attendance exception review
▸

PREREQUISITE

前置条件
  1. 1
    extract_msg_attachments.py
    从 data/raw/<目录名> 抽出邮件附件到 outputs/<目录名>/attachments。
  2. 2
    preprocess_pdfs_for_vision.py
    对 PDF 做视觉预处理，覆盖 data/raw 与 attachments 两个来源目录。
  3. 3
    prepare_attendance_data.py
    整理考勤资料，指定 --attachments-dir 与 --base-table 底表。

推荐先跑 data-prep 的这三个脚本，再运行本 skill；本段全部为 data-prep 脚本，详见 attendance-data-prep。

↹

INPUT & OUTPUT

输入 / 产出
↘ INPUT · 输入
  • attachments/（data-prep 抽出的附件目录）
  • reference_roster.xlsx（底表 roster）
  • vision_extracted_records.jsonl（视觉结构化记录）
  • <config.json>（判异常口径，命令传 --config）
↗ OUTPUT · 产出
  • exception_review.xlsx
  • 固定 5 sheet：来源清单 · 员工覆盖 · 异常清单 · 待追问 · 处理日志
🪜

STEPS

处理流程
  1. 1
    建来源清单
    逐文件登记来源类型、归属员工、解析状态、置信度。
  2. 2
    算员工覆盖
    底表员工是否有考勤资料、来源数、来源列表；roster 有员工无来源 → missing_attendance_source。
  3. 3
    出异常清单
    缺卡、审批缺失、假别不明、夜班跨天、视觉低置信度等逐条列出。
  4. 4
    列待追问
    面向 HR / 客户 / 员工的确认问题和建议动作；Excel 可解析但无法确定员工 → missing_employee_name。
  5. 5
    写处理日志
    本次规则、文件数、员工数、异常数、解析失败原因，与各 sheet 可核对。
▤

OUTPUTS

产物结构exception_review.xlsx · 5 sheet
来源清单
文件、来源类型、归属员工、解析状态、置信度。
员工覆盖
底表员工、是否有考勤资料、来源数、来源列表。
异常清单
缺卡、审批缺失、假别不明、夜班跨天、视觉低置信度等。
待追问
面向 HR / 客户 / 员工的确认问题和建议动作。
处理日志
本次规则、文件数、员工数、异常数、解析失败原因。
⊞

CORE FIELDS

核心固定字段15 字段
client_nameemployee_nameid_numberpay_periodsource_typesource_filesheet_or_pageissue_typeseverityownerquestionsuggested_actionevidence_summaryconfidencestatus
⚖

PRINCIPLES

处理原则
⇄

PIPELINE

与其他 skill 衔接
←
上游 attendance-data-prep：本 skill 基于其输出生成审核工作簿。
→
下游 attendance-remarks 算最终考勤备注。（图谱推断；源仅声明本 skill 不直接生成最终备注。）
✓

ACCEPTANCE

闭环验收

交付说明应包含：异常总数、待追问总数、最高优先级问题和建议下一步。

⊘

ANTI-PATTERNS

反例检查
✗
图片 / PDF / 截图没有 vision_extracted_records.jsonl 或人工记录，却被写成已解析。
✗
来源清单显示解析失败，但异常清单和处理日志没有对应记录。
✗
员工在 roster 中无资料，却没有 missing_attendance_source。
✗
低置信度视觉记录没有进入待追问。
↻

FAILURE & RETRY

失败重试
✗
缺少 reference_roster.xlsx 或配置文件时，先回到 attendance-data-prep 或补配置，不要生成半成品。
✗
解析单个 Excel 失败时，记录到处理日志，继续处理其他文件；失败文件进入待追问。
✗
视觉记录缺失时，先补跑 data-prep 的视觉预处理或人工复核，再重跑本 skill。
✦

LESSONS

复盘沉淀

异常类型、追问口径或来源归类出现新模式时，先记录到 LESSONS.md；稳定后再补到处理原则、脚本规则或测试用例。

⌘

RUN

运行命令
RUN · 运行命令
uv run python skills/attendance/attendance-exception-review/scripts/build_exception_review.py \
  outputs/<目录名>/attachments \
  <YYYYMM> \
  outputs/<目录名>/exception_review.xlsx \
  --source-dir data/raw/<目录名> \
  --reference-summary outputs/<目录名>/reference_roster.xlsx \
  --config <config.json>