审核 · 备注计算

考勤备注

attendance-remarks

🏷️

审核与计算 skills/attendance/

基于已归档好的考勤数据，按配置为每个员工生成「考勤备注」列（适用标准工时 / 综合工时），输出含审核明细与待追问的审核工作簿和 HTML 审核报告。配置化自动生成草表 + 审核明细 + flags 复核 + overrides 固化例外。支持结构化 Excel、邮件正文、AI 视觉结果、overrides 多来源合并。

⚡

TRIGGERS

触发场景

▸数据已准备好，要在汇总表里生成「考勤备注」列

▸标准工时 / 综合工时的月度考勤汇总

▸需要审核明细 + flags + HTML 报告供人工逐条复核

▸要把多来源（Excel / 邮件 / 视觉 / overrides）合并成最终备注

↹

INPUT & OUTPUT

输入 / 产出

↘ INPUT · 输入

DATASET_NAME + SOURCE_DIR + ATTACHMENTS_DIR（会话入口确认）
<config_json> 当月配置（无固定文件名，从 config.template.json 复制起点）
reference_roster.xlsx 或客户底表
_email_texts.jsonl · vision_extracted_records.jsonl（data-prep 预产）
可选 overrides JSON 人工覆盖最终 remark

↗ OUTPUT · 产出

attendance_remarks.xlsx：考勤备注 · 审核明细 · 待追问三 sheet
compare_result.xlsx 对比 / 自检结果
HTML 审核报告（可启动服务在线审阅）
交付说明：总人数 / 可追溯 / 需复核 / 待追问 / overrides 使用

⛒

BLOCK vs ASK

硬阻塞 vs 业务待追问HTML 不阻断原则

■硬阻塞 · 必须暂停询问

缺 DATASET_NAME、SOURCE_DIR 不存在、配置文件缺失。遇到这三类必须停下来问用户，不得继续。

▸业务待追问 · 不阻断 HTML

缺考勤资料、无法解析来源、低置信度视觉、加班去向不明、计薪天 / 客户口径不定。先写入 待追问 sheet 并在 HTML 展示，不强制用户逐条回答。

✓交付说明可列最重要的 1–3 个可选追问并给推荐处理方式；用户可回复「跳过」，此时照常交付 Excel 和 HTML。
✓HTML 是人工审阅和后续补 overrides 的入口，待追问仍存在时也照常生成；用户补答后再写入 overrides 并重新生成。

🪜

STEPS

处理流程

0
会话入口确认GATE
确认 DATASET_NAME（outputs/ 下子目录名）、配置是否就绪、reference_roster.xlsx 或底表是否就绪。缺则暂停。
1
先建配置
周期、标准计薪天、法定假日、调休补班 / 休息日、加班去向、假别映射、输出文案都进 <config_json>，客户名 / 月份 / 路径 / 姓名一律不写死。
2
读多来源
结构化 Excel 为优先来源（脚本直接解析）；邮件正文 / 视觉结果经 --email-texts / --vision-records 传入或自动发现；overrides 经 --overrides 人工覆盖最终 remark。
3
算休假
按小时汇总，默认 8h = 1 天输出 X天；休假小时数 为空时从原因里抽取 0.5H、8H 等。
4
算加班
法定日 → legal_settle；rest_days / 周末关键词 → 周末休息日加班；ot_keywords 明确命中转调休或结算时按关键词优先；未明确 → generic_settle 并在 flags 提示复核。
5
算计薪 / 全勤
无休假缺勤从 full_attendance 起；非整月计薪从 pay_days 起。计薪天不机械相加出勤小时，要结合入离职空白、法定日是否在雇佣区间、审批 / 客户确认。
6
拼接备注 + 明细 + 待追问
按推荐顺序中文逗号拼接备注，每片段写 审核明细，无法可靠推导的进 待追问，需复核的打 flags。
7
三步生成并启动 HTML 报告
compare_remarks.py 生成 compare_result.xlsx → build_compare_report.py 生成 output_html → serve_review_report.py 启动审阅服务。最终交付时必须启动 HTML 审核服务。

≣

JOIN ORDER

备注拼接顺序中文逗号「，」连接

1 计薪天 / 全勤 → 2 年假 → 3 调休 → 4 带薪病假 → 5 事假

起始段为计薪天或全勤；其后依次拼接四类休假。

6 工作日转调休 → 7 周末转调休 → 8 工作日结算 → 9 周末结算 → 10 法定结算

五类加班按去向顺序拼接；同存工作日结算与周末结算且省略某段后缀时须标记需复核。

11 特殊短句

来自非结构化材料或人工复核，写入 overrides。客户要求其他顺序时改配置或 overrides，不写死客户专属顺序。

▤

OUTPUTS

产物结构attendance_remarks.xlsx · 三 sheet

考勤备注 (sheet)

最终给业务用的汇总结果，含 审核状态、审核明细数、flags。

审核明细 (sheet)

每个备注片段的判断依据，供逐条复核：员工 / 身份证号 / 计薪周期 / 最终备注、证据层级（明细|汇总）、类型、分类（如 annual/workday_comp/legal_settle）、日期 / 小时 / 天数、规则、命中值、来源定位（文件|sheet|行号）、原始值 JSON、是否需人工复核、说明。

待追问 (sheet)

自动流程无法可靠推导的问题，供人工补信息或生成 overrides。是审核入口，不是 HTML 生成前的阻塞项。

视觉来源必保留字段

AI 视觉抽取的依据须在原始值 JSON 或说明中保留 vision_source_file、vision_page_or_image、vision_confidence、vision_review_reason、raw_text_or_visual_summary。

⚑

REVIEW FLAGS

需复核标记规则6 种必须 flag

⚑

overrides 人工覆盖

⚑

部分计薪天

⚑

未明确匹配去向的加班

⚑

同一人同时存在工作日结算和周末结算，且输出文案省略了某段结算后缀

⚑

来自邮件正文、截图、PDF、扫描件或其他非结构化材料的判断

⚑

所有 confidence 不是 high 的 AI 视觉抽取结果

⇲

SOURCES

数据来源与优先级

结构化 Excel（优先来源）：附件目录与源目录里的 .xlsx 考勤表，脚本直接解析。找目标月 sheet 优先匹配 YYYYMM / YYYY年M月 / M月；匹配不到则扫描 sheet 内日期，选目标月日期最多的。

邮件正文 _email_texts.jsonl：经 --email-texts 传入或自动发现。向后兼容：无 _email_texts.jsonl 时回退 _msg_meta.json 直接读取邮件正文。

LLM 视觉结果 vision_extracted_records.jsonl：多模态处理图片 / PDF 后回填，经 --vision-records 传入或自动发现。

overrides：经 --overrides 人工覆盖最终 remark。本脚本不再扫描图片和 PDF，也不依赖 tesseract OCR——图片 / PDF 内容理解统一由 LLM 多模态在 data-prep 阶段处理。

⌘

RUN

运行命令

RUN · 四步生成 + overrides 重跑

# 1) 生成备注草表（data-prep 中间产物自动发现）
uv run python skills/attendance/attendance-remarks/scripts/build_attendance_remarks.py \
  "$ATTACHMENTS_DIR" <pay_period_label> \
  "$OUTPUT_DIR/attendance_remarks.xlsx" \
  --config <config_json> --source-dir "$SOURCE_DIR" \
  --reference-summary "$OUTPUT_DIR/reference_roster.xlsx"
  # 可显式指定：--email-texts ... --vision-records ...
  # 确认例外后重跑覆盖：--overrides <overrides_json>
  #   overrides 形态： { "员工姓名": { "remark": "最终确认后的考勤备注" } }

# 2) 生成对比结果（有底表用底表/标准化底表作第一参数）
uv run python skills/attendance/attendance-remarks/scripts/compare_remarks.py \
  <reference_summary_xlsx> <attendance_remarks_xlsx> <compare_result_xlsx>

# 3) 生成 HTML 对比审核报告
uv run python skills/attendance/attendance-remarks/scripts/build_compare_report.py \
  <compare_result_xlsx> <attendance_remarks_xlsx> <output_html> \
  --source-root "$SOURCE_DIR" --source-root "$ATTACHMENTS_DIR" \
  --open-url-base http://127.0.0.1:8765/__open_file__

# 4) 启动 HTML 审核服务（两个 --allow-root）
uv run python skills/attendance/attendance-remarks/scripts/serve_review_report.py \
  "$OUTPUT_DIR" --allow-root "$SOURCE_DIR" --allow-root "$ATTACHMENTS_DIR"

⇄

PIPELINE

与其他 skill 衔接

←

唯一前置 skill：attendance-data-prep 预先准备结构化 Excel、_email_texts.jsonl、vision_extracted_records.jsonl、reference_roster.xlsx。源数据已是结构化 Excel 且不需额外归档时可跳过 data-prep。

⤳

图谱编排信息（非源声明）：本页在外部技能图谱中标注序号 06、lane = 审核与计算，上游叠加 rule-pack，下游 exception-review / delivery-pack。SKILL.md 本身未声明序号 / lane / 这些衔接。

✓

ACCEPTANCE

闭环验收

✓attendance_remarks.xlsx 存在且含 考勤备注 / 审核明细 / 待追问 三 sheet。
✓汇总行数覆盖 reference_roster.xlsx 或底表中所有目标员工；姓名 / 身份证号来自同一员工源表。
✓考勤备注 无空值；非全勤、部分计薪、加班、休假、特殊短句必须有可追溯审核明细。
✓审核明细数 与 审核明细 sheet 可核对；有 flags 的行必须能在 HTML 报告中看到。
✓待追问 不阻断 Excel/HTML 生成，但必须进工作簿和 HTML；HTML 审核服务已启动或已生成可打开的报告。
✓交付说明含：总人数、可追溯人数、需复核人数、待追问数、overrides 使用情况。无底表自检报告须注明仅用于审核证据与待追问。

⊘

ANTI-PATTERNS

反例检查

✗

备注非空但没有审核明细，尤其是非全勤备注。

✗

法定日、休息日、计薪天来自硬编码或历史月份配置。

✗

扫描件、截图、邮件正文、低置信度视觉结果没有标记需复核。

✗

有 generic_settle 或未写明去向的加班，却没有待追问或 flags。

✗

无底表自检报告被误当作与客户底表的正式对比报告。

↺

FAILURE & LESSONS

失败重试与复盘沉淀

↻

缺 DATASET_NAME / SOURCE_DIR / 配置时暂停；口径不定时先出带 待追问 的 Excel/HTML，不阻断人工审核入口。用户补口径后写入 overrides 或补充明细再重跑对比报告。

↻

某员工解析异常时，优先限定该员工来源文件检查，避免重写全局配置。

→

新客户口径 / 备注顺序 / 假别映射 / 加班去向 / overrides 模式先记入 LESSONS.md，确认可复用后再回写 config.template.json / 本 SKILL.md / 测试。