809 lines
33 KiB
Python
809 lines
33 KiB
Python
#!/usr/bin/env python3
|
||
"""
|
||
考勤报表导出 — 明细粒度（打卡记录）
|
||
|
||
通过 `dws attendance check result` + `dws attendance check record`
|
||
查询打卡数据，每条打卡记录输出一行，不做聚合。
|
||
|
||
|
||
|
||
[AI Agent 强制门禁] 调用本脚本前必须先阅读：
|
||
references/attendance-report.md
|
||
|
||
本脚本仅是"考勤报表导出工作流"的执行末端，工作流完整定义在 attendance-report.md，
|
||
包含但不限于：
|
||
- 阶段 0：报表类型判断（默认月度汇总，明细需用户明确说"明细/原始记录/每条打卡"）
|
||
- 阶段 1：人员列表获取（aisearch person / contact dept list-members）
|
||
- 阶段 2：列选择（明细报表列固定，不支持 --column-keywords）
|
||
- 阶段 3：调用本脚本
|
||
- 阶段 4：结果回传给用户的标准格式
|
||
- 错误处理（403 权限、HSF_ILLEGALPARAMS、空数据等）
|
||
|
||
[严禁] 仅凭本脚本 docstring 或 --help 输出就直接拼命令执行，会导致：
|
||
- 用户本来要"汇总"被给成"明细"（粒度错误）
|
||
- 报表数据不全 / 人员遗漏
|
||
- 错误处理缺失，把环境错误当业务错误反馈给用户
|
||
|
||
与月度汇总/每日统计不同，明细报表：
|
||
- 不使用 report columns / report query-data
|
||
- 列固定（基础信息 + 打卡字段），不支持自定义列选择
|
||
- 分批限制：≤100 人/次（check result），时间跨度 ≤1 个月
|
||
|
||
用法:
|
||
python attendance_report_detail.py \
|
||
--users userId1,userId2,... \
|
||
--start "2026-03-01" \
|
||
--end "2026-03-31" \
|
||
[--out attendance_report_2026-03-01_2026-03-31_detail.xlsx]
|
||
[--inspect] # 首次跑时打印首条记录原始结构
|
||
|
||
约束:
|
||
- 仅管理员可用，否则 dws 接口返回 403
|
||
- --users 超过 100 人 → 自动按每批 100 人分批
|
||
- --start 到 --end 超过 31 天 → 自动按月切片
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import argparse
|
||
import json
|
||
import sys
|
||
from datetime import datetime
|
||
from typing import Any
|
||
|
||
import attendance_report_common as cmn
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# 接口限制（check result / check record）
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
|
||
CHECK_MAX_USERS_PER_BATCH = 100 # check result: --users 最多 100 人
|
||
CHECK_MAX_DAYS_PER_SLICE = 31 # check result/record: 跨度 ≤ 1 个月
|
||
CHECK_RESULT_PAGE_SIZE = 1000 # check result: --limit 最大值
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# 固定表头（与 SKILL.md 明细预定义列集合对齐）
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
|
||
# 基础信息列
|
||
BASE_HEADERS = ["姓名", "考勤组", "部门"]
|
||
|
||
# 打卡字段列（以打卡流水为主，关联 check result 的考勤时间和打卡结果）
|
||
# 对应 Diamond 配置中 termId 8-20 的列定义
|
||
CHECK_HEADERS = [
|
||
"考勤日期", "考勤时间", "打卡时间", "打卡结果",
|
||
"打卡地址", "打卡备注", "异常打卡原因",
|
||
"打卡图片1", "打卡图片2", "打卡设备", "管理员修改备注",
|
||
"管理员修改备注图片1", "管理员修改备注图片2", "管理员修改备注图片3",
|
||
]
|
||
|
||
ALL_HEADERS = BASE_HEADERS + CHECK_HEADERS
|
||
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# 参数解析
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
|
||
def parse_args() -> argparse.Namespace:
|
||
p = argparse.ArgumentParser(
|
||
description=(
|
||
"导出考勤报表 — 明细粒度（打卡记录）。"
|
||
"[强制] AI Agent 必须先读 references/attendance-report.md 再调用本脚本，"
|
||
"禁止凭 --help 或脚本路径自行拼命令。"
|
||
),
|
||
)
|
||
p.add_argument("--users", required=True,
|
||
help="userId 列表，逗号分隔（必填）")
|
||
p.add_argument("--start", required=True,
|
||
help='开始时间，YYYY-MM-DD 或 "YYYY-MM-DD HH:mm:ss"（必填）')
|
||
p.add_argument("--end", required=True,
|
||
help='结束时间，YYYY-MM-DD 或 "YYYY-MM-DD HH:mm:ss"（必填）')
|
||
p.add_argument("--out", default="",
|
||
help="输出 xlsx 文件名；不传则按规范自动生成")
|
||
p.add_argument("--inspect", action="store_true",
|
||
help="首次跑时打印首条记录原始结构（用于核对真实字段）")
|
||
p.add_argument("--no-images", action="store_true",
|
||
help="不在 Excel 中嵌入打卡图片（默认会下载 URL 并嵌入为缩略图，"
|
||
"图片多时较慢；加此参数仅保留 URL 文本）")
|
||
p.add_argument("--image-size", default="80x120",
|
||
help="嵌入图片像素尺寸 WxH，默认 80x120")
|
||
return p.parse_args()
|
||
|
||
|
||
# 含图片 URL 的列名（与 CHECK_HEADERS 中的中文名严格一致）
|
||
IMAGE_COLUMN_NAMES = [
|
||
"打卡图片1", "打卡图片2",
|
||
"管理员修改备注图片1", "管理员修改备注图片2", "管理员修改备注图片3",
|
||
]
|
||
|
||
|
||
def _parse_image_size(spec: str) -> tuple[int, int]:
|
||
"""解析 --image-size 参数，格式 WxH。失败时回退到默认 (80, 120)。"""
|
||
try:
|
||
parts = spec.lower().replace(" ", "").split("x")
|
||
w, h = int(parts[0]), int(parts[1])
|
||
if w > 0 and h > 0:
|
||
return (w, h)
|
||
except (ValueError, IndexError):
|
||
pass
|
||
cmn.warn(f"--image-size 格式无效: {spec!r}，使用默认 80x120")
|
||
return (80, 120)
|
||
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# check result 查询（打卡结果，含分页）
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
|
||
def query_check_results(
|
||
user_batch: list[str],
|
||
date_slice: cmn.DateSlice,
|
||
stats: cmn.CallStats,
|
||
*,
|
||
inspect: bool = False,
|
||
inspected_flag: list[bool] | None = None,
|
||
) -> list[dict]:
|
||
"""
|
||
对一批 users × 一个时间片调用 `dws attendance check result`。
|
||
|
||
自动分页：每次最多 1000 条，返回满 1000 条时递增 offset 继续拉取。
|
||
"""
|
||
from_date = date_slice.start.strftime(cmn.DATE_FMT)
|
||
to_date = date_slice.end.strftime(cmn.DATE_FMT)
|
||
all_records: list[dict] = []
|
||
offset = 0
|
||
|
||
while True:
|
||
cmn.log(
|
||
f"[check-result] users={len(user_batch)} "
|
||
f"slice={date_slice.label} offset={offset}"
|
||
)
|
||
try:
|
||
payload = cmn.run_dws([
|
||
"attendance", "check", "result",
|
||
"--users", ",".join(user_batch),
|
||
"--from", from_date,
|
||
"--to", to_date,
|
||
"--offset", str(offset),
|
||
"--limit", str(CHECK_RESULT_PAGE_SIZE),
|
||
])
|
||
stats.total_dws_calls += 1
|
||
except cmn.DwsCallError as exc:
|
||
stats.total_dws_calls += 1
|
||
stats.failed_calls += 1
|
||
if exc.is_permission_error:
|
||
cmn.error(
|
||
"权限错误：当前账号无管理员权限，无法查询打卡结果。"
|
||
"请联系考勤管理员或换号重试。"
|
||
)
|
||
raise SystemExit(2) from exc
|
||
stats.add_warning(f"[check-result failed] {date_slice.label} offset={offset}: {exc}")
|
||
break
|
||
|
||
records = cmn.extract_records(payload)
|
||
|
||
if inspect and records and inspected_flag is not None and not inspected_flag[0]:
|
||
cmn.dump_first_record_for_inspection(records, "check-result")
|
||
inspected_flag[0] = True
|
||
|
||
all_records.extend(records)
|
||
|
||
# 未满一页 → 无需翻页
|
||
if len(records) < CHECK_RESULT_PAGE_SIZE:
|
||
break
|
||
offset += CHECK_RESULT_PAGE_SIZE
|
||
|
||
return all_records
|
||
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# check record 查询（打卡流水）
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
|
||
def query_check_records(
|
||
user_batch: list[str],
|
||
date_slice: cmn.DateSlice,
|
||
stats: cmn.CallStats,
|
||
*,
|
||
inspect: bool = False,
|
||
inspected_flag: list[bool] | None = None,
|
||
) -> list[dict]:
|
||
"""对一批 users × 一个时间片调用 `dws attendance check record`。"""
|
||
from_date = date_slice.start.strftime(cmn.DATE_FMT)
|
||
to_date = date_slice.end.strftime(cmn.DATE_FMT)
|
||
|
||
cmn.log(
|
||
f"[check-record] users={len(user_batch)} slice={date_slice.label}"
|
||
)
|
||
try:
|
||
payload = cmn.run_dws([
|
||
"attendance", "check", "record",
|
||
"--users", ",".join(user_batch),
|
||
"--from", from_date,
|
||
"--to", to_date,
|
||
])
|
||
stats.total_dws_calls += 1
|
||
except cmn.DwsCallError as exc:
|
||
stats.total_dws_calls += 1
|
||
stats.failed_calls += 1
|
||
if exc.is_permission_error:
|
||
cmn.error(
|
||
"权限错误：当前账号无管理员权限，无法查询打卡流水。"
|
||
"请联系考勤管理员或换号重试。"
|
||
)
|
||
raise SystemExit(2) from exc
|
||
stats.add_warning(f"[check-record failed] {date_slice.label}: {exc}")
|
||
return []
|
||
|
||
records = cmn.extract_records(payload)
|
||
|
||
if inspect and records and inspected_flag is not None and not inspected_flag[0]:
|
||
cmn.dump_first_record_for_inspection(records, "check-record")
|
||
inspected_flag[0] = True
|
||
|
||
return records
|
||
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# 值提取工具
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
|
||
def _humanize_timestamp(value: Any) -> str:
|
||
"""把毫秒/秒级时间戳转成可读字符串；非时间戳原样返回。"""
|
||
if value is None:
|
||
return ""
|
||
if isinstance(value, (int, float)):
|
||
# 13 位毫秒时间戳
|
||
if 1_000_000_000_000 <= value <= 9_999_999_999_999:
|
||
try:
|
||
return datetime.fromtimestamp(value / 1000).strftime(cmn.DATETIME_FMT)
|
||
except (OSError, ValueError, OverflowError):
|
||
return str(value)
|
||
# 10 位秒级时间戳
|
||
if 1_000_000_000 <= value <= 9_999_999_999:
|
||
try:
|
||
return datetime.fromtimestamp(value).strftime(cmn.DATETIME_FMT)
|
||
except (OSError, ValueError, OverflowError):
|
||
return str(value)
|
||
return str(value) if value != "" else ""
|
||
|
||
|
||
def _extract_field(record: dict, candidate_keys: tuple[str, ...]) -> Any:
|
||
"""从 record 中按候选 key 顺序取第一个非空值。"""
|
||
return cmn._first_nonempty(record, candidate_keys)
|
||
|
||
|
||
def _extract_date_str(record: dict) -> str:
|
||
"""从 check result 记录中提取考勤日期（YYYY-MM-DD）。"""
|
||
raw = _extract_field(record, (
|
||
"workDate", "work_date", "checkDate", "userCheckDate", "date", "day",
|
||
))
|
||
if raw is None:
|
||
return ""
|
||
# 毫秒时间戳
|
||
if isinstance(raw, (int, float)) and raw > 1_000_000_000_000:
|
||
try:
|
||
return datetime.fromtimestamp(raw / 1000).strftime(cmn.DATE_FMT)
|
||
except (OSError, ValueError, OverflowError):
|
||
return str(raw)
|
||
s = str(raw).strip()
|
||
# 已经是 YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss → 取前 10 位
|
||
if len(s) >= 10 and s[4] == "-" and s[7] == "-":
|
||
return s[:10]
|
||
return s
|
||
|
||
|
||
def _extract_time_str(record: dict, candidate_keys: tuple[str, ...]) -> str:
|
||
"""从记录中提取时间字段，毫秒时间戳自动转 HH:mm:ss。"""
|
||
raw = _extract_field(record, candidate_keys)
|
||
if raw is None:
|
||
return ""
|
||
if isinstance(raw, (int, float)) and raw > 1_000_000_000_000:
|
||
try:
|
||
return datetime.fromtimestamp(raw / 1000).strftime("%H:%M:%S")
|
||
except (OSError, ValueError, OverflowError):
|
||
return str(raw)
|
||
if isinstance(raw, (int, float)) and raw > 1_000_000_000:
|
||
try:
|
||
return datetime.fromtimestamp(raw).strftime("%H:%M:%S")
|
||
except (OSError, ValueError, OverflowError):
|
||
return str(raw)
|
||
return str(raw)
|
||
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# 字段翻译 / 提取工具函数（与 Java DataProvider 实现对齐）
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
|
||
# 打卡结果映射（对应 CheckResultUtil.java 的 getCheckResultStr 逻辑）
|
||
_CHECK_RESULT_MAP: dict[str, str] = {
|
||
"Normal": "正常",
|
||
"Late": "迟到",
|
||
"Early": "早退",
|
||
"NotSigned": "未打卡",
|
||
"SeriousLate": "严重迟到",
|
||
"Absenteeism": "旷工迟到",
|
||
"LeaveEarly": "早退",
|
||
}
|
||
|
||
# 打卡设备 / 来源类型映射（对应 SourceType 枚举 + UserDeviceOriginData.java）
|
||
_SOURCE_TYPE_MAP: dict[str, str] = {
|
||
"ATM": "考勤机",
|
||
"BEACON": "蓝牙",
|
||
"DING_ATM": "钉钉考勤机",
|
||
"USER": "手机打卡",
|
||
"BOSS": "管理员",
|
||
"SYSTEM": "系统",
|
||
"CARD": "门禁",
|
||
"SELF_SERVICE": "自助补卡",
|
||
}
|
||
|
||
# 异常打卡原因中文描述（对应 SecurityConfigureUtil DEFAULT_CHEAT_LIST）
|
||
_CHEAT_REASON_MAP: dict[str, str] = {
|
||
"LocationNotMatch": "定位异常",
|
||
"WifiNotMatch": "WIFI异常",
|
||
"MockLocation": "模拟定位",
|
||
"FaceNotMatch": "人脸比对失败",
|
||
"DeviceNotMatch": "设备异常",
|
||
"OutsideRange": "不在打卡范围",
|
||
"NoBluetooth": "蓝牙未开启",
|
||
"BluetoothNotMatch": "蓝牙不匹配",
|
||
}
|
||
|
||
|
||
def _translate_check_result(raw_result: str) -> str:
|
||
"""
|
||
把接口返回的英文打卡结果翻译成中文，与 CheckResultUtil.getCheckResultStr 对齐。
|
||
未命中翻译表时原样返回。
|
||
"""
|
||
if not raw_result:
|
||
return ""
|
||
return _CHECK_RESULT_MAP.get(raw_result, raw_result)
|
||
|
||
|
||
def _translate_source_type(raw_source: str) -> str:
|
||
"""
|
||
把接口返回的 sourceType 枚举值翻译成中文，与 UserDeviceOriginData 对齐。
|
||
未命中翻译表时原样返回。
|
||
"""
|
||
if not raw_source:
|
||
return ""
|
||
return _SOURCE_TYPE_MAP.get(raw_source, raw_source)
|
||
|
||
|
||
def _extract_location(record: dict) -> str:
|
||
"""
|
||
拼接打卡地址：地点名称 + 详细地址，与 UserLocationOriginData 对齐。
|
||
|
||
Java 逻辑：
|
||
locationResult.getSpaceName() → 地点名称
|
||
locationResult.getDetailAddr() → 详细地址（含省市区+街道）
|
||
两者均有时拼接，只有一个时单独返回。
|
||
"""
|
||
space_name = str(_extract_field(record, (
|
||
"spaceName", "space_name", "locationName", "location_name",
|
||
)) or "").strip()
|
||
detail_addr = str(_extract_field(record, (
|
||
"detailAddr", "detail_addr", "detailAddress", "address", "userAddress",
|
||
)) or "").strip()
|
||
|
||
if space_name and detail_addr:
|
||
return f"{space_name} {detail_addr}"
|
||
return space_name or detail_addr
|
||
|
||
|
||
def _extract_exception_reason(record: dict) -> str:
|
||
"""
|
||
提取并翻译异常打卡原因，与 CheckExceptionReasonOriginData 对齐。
|
||
|
||
Java 逻辑：
|
||
取 features.getInvalidRecordMsg()（逗号分隔的错误码列表）
|
||
逐个从 DEFAULT_CHEAT_LIST 查中文描述后再拼接返回。
|
||
"""
|
||
raw = str(_extract_field(record, (
|
||
"invalidRecordMsg", "invalid_record_msg",
|
||
"outsideRemark", "outside_remark",
|
||
"exceptionReason",
|
||
)) or "").strip()
|
||
|
||
if not raw:
|
||
return ""
|
||
|
||
# 逗号分隔的多个错误码，逐个翻译后重新拼接
|
||
codes = [c.strip() for c in raw.split(",") if c.strip()]
|
||
translated = [_CHEAT_REASON_MAP.get(code, code) for code in codes]
|
||
return ",".join(translated)
|
||
|
||
|
||
def _extract_photo_url(record: dict, candidate_keys: tuple[str, ...]) -> str:
|
||
"""从 record 或其 features 嵌套结构中提取图片 URL。"""
|
||
raw = _extract_field(record, candidate_keys)
|
||
if raw is None:
|
||
return ""
|
||
return str(raw).strip()
|
||
|
||
|
||
def _extract_remark_photo(record: dict) -> str:
|
||
"""
|
||
打卡图片1（备注/外勤打卡照片）。
|
||
|
||
dws check record 的真实返回字段（实测验证）：
|
||
- 顶层 photoUrl：外勤/拍照打卡的主图片 URL
|
||
- 顶层 outsideAttachment：外勤打卡的附件（可能含多张图片）
|
||
- 顶层 remarkPhotos：备注图片数组（旧字段，部分版本）
|
||
Java 侧 RemarkPhotoOriginData 对应 features.getRemarkPhotos()，
|
||
但 dws CLI 实际把图片字段提到了顶层，需直接读顶层字段。
|
||
"""
|
||
# 1) 兼容数组形式的 remarkPhotos（早期版本）
|
||
remark_photos = record.get("remarkPhotos") or record.get("remark_photos")
|
||
if isinstance(remark_photos, list) and remark_photos:
|
||
return str(remark_photos[0]).strip()
|
||
if isinstance(remark_photos, str) and remark_photos.strip():
|
||
parts = [p.strip() for p in remark_photos.split(",") if p.strip()]
|
||
return parts[0] if parts else ""
|
||
|
||
# 2) dws CLI 当前实际返回的字段（顶层）
|
||
# photoUrl 优先，其次 outsideAttachment，再次旧候选名
|
||
photo = _extract_photo_url(record, (
|
||
"photoUrl", "photo_url",
|
||
"outsideAttachment", "outside_attachment",
|
||
"remarkPhoto", "remark_photo",
|
||
"userImage", "user_image", "imageUrl", "image_url",
|
||
))
|
||
if photo:
|
||
# outsideAttachment 可能是逗号分隔多张，取第一张
|
||
if "," in photo:
|
||
first = photo.split(",")[0].strip()
|
||
if first:
|
||
return first
|
||
return photo
|
||
|
||
# 3) 兜底：从 features 嵌套 JSON 里翻
|
||
return _extract_photo_from_features(record, (
|
||
"photoUrl", "remarkPhoto", "remarkPhotos",
|
||
"outsideAttachment", "userImage", "imageUrl",
|
||
))
|
||
|
||
|
||
def _extract_face_check_photo(record: dict) -> str:
|
||
"""
|
||
打卡图片2（人脸识别照片）。
|
||
|
||
Java 侧 FaceCheckPhotoOriginData 对应 features.getFacePhoto()。
|
||
dws CLI 中人脸图未稳定暴露在顶层，优先读 features 嵌套字段。
|
||
"""
|
||
# 1) 顶层候选
|
||
face = _extract_photo_url(record, (
|
||
"facePhoto", "face_photo",
|
||
"faceCheckPhoto", "face_check_photo",
|
||
"faceImage", "face_image",
|
||
"faceUrl", "face_url",
|
||
))
|
||
if face:
|
||
return face
|
||
# 2) features 嵌套兜底
|
||
return _extract_photo_from_features(record, (
|
||
"facePhoto", "faceCheckPhoto", "faceImage", "faceUrl",
|
||
))
|
||
|
||
|
||
def _extract_photo_from_features(
|
||
record: dict,
|
||
candidate_keys: tuple[str, ...],
|
||
) -> str:
|
||
"""
|
||
从 record['features']（JSON 字符串或 dict）中提取图片 URL。
|
||
候选 key 命中 features 中第一个非空值则返回。
|
||
"""
|
||
feat = record.get("features")
|
||
if isinstance(feat, str):
|
||
feat_str = feat.strip()
|
||
if not feat_str or feat_str[0] not in "{[":
|
||
return ""
|
||
try:
|
||
feat = json.loads(feat_str)
|
||
except (ValueError, TypeError):
|
||
return ""
|
||
if not isinstance(feat, dict):
|
||
return ""
|
||
for key in candidate_keys:
|
||
val = feat.get(key)
|
||
if val in (None, "", [], {}):
|
||
continue
|
||
if isinstance(val, list) and val:
|
||
return str(val[0]).strip()
|
||
s = str(val).strip()
|
||
if "," in s:
|
||
return s.split(",")[0].strip()
|
||
return s
|
||
return ""
|
||
|
||
|
||
def _extract_boss_remark(record: dict) -> str:
|
||
"""
|
||
管理员修改备注，与 BossCheckRemarkOriginData 对齐。
|
||
Java 逻辑：features.getBossRemark()。
|
||
"""
|
||
return str(_extract_field(record, (
|
||
"bossRemark", "boss_remark",
|
||
"approveRemark", "approve_remark",
|
||
"adminModifyRemark", "admin_modify_remark",
|
||
)) or "").strip()
|
||
|
||
|
||
def _extract_boss_photo(record: dict, photo_index: int) -> str:
|
||
"""
|
||
管理员修改备注图片（1/2/3），与 BossCheckPhoto1/2/3OriginData 对齐。
|
||
Java 逻辑：features.getBossPhotos()，按 index 取对应张。
|
||
photo_index: 0-based 索引（0=图片1, 1=图片2, 2=图片3）
|
||
"""
|
||
boss_photos = record.get("bossPhotos") or record.get("boss_photos")
|
||
if isinstance(boss_photos, list):
|
||
if photo_index < len(boss_photos):
|
||
return str(boss_photos[photo_index]).strip()
|
||
return ""
|
||
if isinstance(boss_photos, str) and boss_photos.strip():
|
||
parts = [p.strip() for p in boss_photos.split(",") if p.strip()]
|
||
return parts[photo_index] if photo_index < len(parts) else ""
|
||
|
||
# 降级：尝试独立字段
|
||
val = _extract_field(record, (
|
||
f"bossPhoto{photo_index + 1}", f"boss_photo_{photo_index + 1}",
|
||
))
|
||
return str(val).strip() if val else ""
|
||
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# 关联合并 check result + check record → 明细行
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
|
||
def _build_result_index(
|
||
check_results: list[dict],
|
||
) -> dict[tuple[str, str], list[dict]]:
|
||
"""
|
||
把 check result 按 (userId, 打卡时间 YYYY-MM-DD HH:mm:ss) 建索引，
|
||
用于关联打卡流水获取考勤时间和打卡结果。
|
||
"""
|
||
index: dict[tuple[str, str], list[dict]] = {}
|
||
for rec in check_results:
|
||
uid = str(_extract_field(rec, ("userId", "userid", "user_id")) or "")
|
||
raw_time = _extract_field(rec, (
|
||
"userCheckTime", "user_check_time", "checkTime", "baseCheckTime",
|
||
))
|
||
time_key = _humanize_timestamp(raw_time) if raw_time else "_unknown"
|
||
key = (uid, time_key)
|
||
index.setdefault(key, []).append(rec)
|
||
return index
|
||
|
||
|
||
def build_record_rows(
|
||
check_records: list[dict],
|
||
check_results: list[dict],
|
||
user_info_map: dict[str, cmn.UserInfo],
|
||
group_name_map: dict[str, str],
|
||
) -> list[dict[str, str]]:
|
||
"""
|
||
以 check record（打卡流水）为主表构建明细行。
|
||
|
||
每条打卡流水记录输出一行，只展示有实际打卡的记录。
|
||
通过打卡时间关联 check result 获取"考勤时间"和"打卡结果"。
|
||
|
||
列顺序与 Diamond 配置 termId 8-20 对齐，各字段逻辑与 Java DataProvider 一致。
|
||
返回每行一个 dict，key 与 ALL_HEADERS 对齐。
|
||
"""
|
||
result_index = _build_result_index(check_results)
|
||
rows: list[dict[str, str]] = []
|
||
|
||
for record in check_records:
|
||
uid = str(_extract_field(record, ("userId", "userid", "user_id")) or "")
|
||
info = user_info_map.get(uid, cmn.UserInfo(name=uid))
|
||
|
||
# ── 打卡时间（实际打卡时间，OriginUserCheckTimePlug）────────────────
|
||
actual_time_raw = _extract_field(record, (
|
||
"userCheckTime", "user_check_time", "checkTime",
|
||
))
|
||
actual_time = _humanize_timestamp(actual_time_raw)
|
||
|
||
# ── 关联 check result 获取"考勤时间"和"打卡结果" ──────────────────
|
||
time_key = actual_time if actual_time else "_unknown"
|
||
matched_results = result_index.get((uid, time_key), [])
|
||
result_rec = matched_results[0] if matched_results else {}
|
||
|
||
# 考勤时间 = 班次规定的应打卡时间（OriginPlanCheckTimePlug）
|
||
plan_time_raw = _extract_field(result_rec, (
|
||
"planCheckTime", "plan_check_time", "baseCheckTime",
|
||
)) if result_rec else None
|
||
plan_time = _humanize_timestamp(plan_time_raw) if plan_time_raw else ""
|
||
|
||
# 打卡结果（OriginUserCheckResultPlug）：英文枚举 → 中文
|
||
raw_check_result = str(_extract_field(result_rec, (
|
||
"checkResult", "check_result", "timeResult", "result",
|
||
)) or "") if result_rec else ""
|
||
check_result_str = _translate_check_result(raw_check_result)
|
||
|
||
# ── 打卡设备（OriginUserDevicePlug）：sourceType 枚举 → 中文 ────────
|
||
raw_source_type = str(_extract_field(record, (
|
||
"sourceType", "source_type", "deviceType", "device_type",
|
||
)) or "")
|
||
device_str = _translate_source_type(raw_source_type)
|
||
|
||
row: dict[str, str] = {
|
||
# 基础信息
|
||
"姓名": info.name or uid,
|
||
"考勤组": group_name_map.get(uid, ""),
|
||
"部门": info.dept_name,
|
||
|
||
# termId=8 考勤时间（OriginPlanCheckTimePlug）
|
||
"考勤日期": _extract_date_str(record),
|
||
"考勤时间": plan_time,
|
||
|
||
# termId=9 打卡时间（OriginUserCheckTimePlug）
|
||
"打卡时间": actual_time,
|
||
|
||
# termId=10 打卡结果（OriginUserCheckResultPlug）
|
||
"打卡结果": check_result_str,
|
||
|
||
# termId=11 打卡地址（OriginUserLocationPlug）
|
||
# Java 逻辑：spaceName + detailAddr 拼接
|
||
"打卡地址": _extract_location(record),
|
||
|
||
# termId=12 打卡备注（OriginUserRemarkPlug）
|
||
# Java 逻辑：features.getRemark()
|
||
"打卡备注": str(_extract_field(record, (
|
||
"remark", "userRemark", "user_remark",
|
||
)) or "").strip(),
|
||
|
||
# termId=13 异常打卡原因（OriginCheckExceptionReasonPlug）
|
||
# Java 逻辑：features.getInvalidRecordMsg() → 翻译错误码
|
||
"异常打卡原因": _extract_exception_reason(record),
|
||
|
||
# termId=14 打卡图片1（OriginRemarkPhotoPlug）
|
||
# Java 逻辑：features.getRemarkPhotos()[0]
|
||
"打卡图片1": _extract_remark_photo(record),
|
||
|
||
# termId=15 打卡图片2（OriginFaceCheckPhotoPlug）
|
||
# Java 逻辑：features.getFacePhoto()
|
||
"打卡图片2": _extract_face_check_photo(record),
|
||
|
||
# termId=16 打卡设备（OriginUserDevicePlug）
|
||
# Java 逻辑：SourceType 枚举 → 中文
|
||
"打卡设备": device_str,
|
||
|
||
# termId=17 管理员修改备注（OriginBossCheckRemarkPlug）
|
||
# Java 逻辑：features.getBossRemark()
|
||
"管理员修改备注": _extract_boss_remark(record),
|
||
|
||
# termId=18/19/20 管理员修改备注图片1/2/3（OriginBossCheckPhoto1/2/3Plug）
|
||
# Java 逻辑：features.getBossPhotos()[0/1/2]
|
||
"管理员修改备注图片1": _extract_boss_photo(record, 0),
|
||
"管理员修改备注图片2": _extract_boss_photo(record, 1),
|
||
"管理员修改备注图片3": _extract_boss_photo(record, 2),
|
||
}
|
||
rows.append(row)
|
||
|
||
return rows
|
||
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# main
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
|
||
def main() -> int:
|
||
args = parse_args()
|
||
|
||
# 1. 解析参数
|
||
raw_ids = [u.strip() for u in args.users.split(",") if u.strip()]
|
||
if not raw_ids:
|
||
cmn.error("--users 不能为空")
|
||
return 2
|
||
|
||
# 自动识别部门ID并展开为员工userId
|
||
user_ids = cmn.resolve_users_from_input(raw_ids)
|
||
if not user_ids:
|
||
cmn.error("未能解析出任何有效的员工userId")
|
||
return 2
|
||
cmn.log(f"[users] 最终用户列表：{len(user_ids)} 人")
|
||
|
||
try:
|
||
start = cmn.parse_datetime_arg(args.start, end_of_day=False)
|
||
end = cmn.parse_datetime_arg(args.end, end_of_day=True)
|
||
except ValueError as exc:
|
||
cmn.error(str(exc))
|
||
return 2
|
||
|
||
if end < start:
|
||
cmn.error(f"--end ({end}) 早于 --start ({start})")
|
||
return 2
|
||
|
||
# 2. 解析 userId → 用户信息（使用 resolve_user_info，已适配 labels 职位提取）
|
||
cmn.log(f"[users] 获取 {len(user_ids)} 个用户基础信息")
|
||
user_info_map = cmn.resolve_user_info(user_ids)
|
||
|
||
# 3. 切批 + 切片（明细用 100 人/批、31 天/片）
|
||
user_batches = cmn.chunk_users(user_ids, size=CHECK_MAX_USERS_PER_BATCH)
|
||
date_slices = cmn.slice_date_range(start, end, max_days=CHECK_MAX_DAYS_PER_SLICE)
|
||
stats = cmn.CallStats(
|
||
user_batches=len(user_batches),
|
||
date_slices=len(date_slices),
|
||
)
|
||
cmn.log(f"[plan] 共 {len(user_batches)} 批 × {len(date_slices)} 个时间片")
|
||
|
||
# 4. 拉数据：check record（打卡流水）+ check result（用于关联考勤时间和打卡结果）
|
||
inspected_result_flag = [False]
|
||
inspected_record_flag = [False]
|
||
all_check_results: list[dict] = []
|
||
all_check_records: list[dict] = []
|
||
|
||
for batch_idx, batch in enumerate(user_batches, start=1):
|
||
for slice_idx, date_slice in enumerate(date_slices, start=1):
|
||
cmn.log(f"[batch {batch_idx}/{len(user_batches)}] "
|
||
f"[slice {slice_idx}/{len(date_slices)}]")
|
||
|
||
results = query_check_results(
|
||
batch, date_slice, stats,
|
||
inspect=args.inspect, inspected_flag=inspected_result_flag,
|
||
)
|
||
all_check_results.extend(results)
|
||
|
||
records = query_check_records(
|
||
batch, date_slice, stats,
|
||
inspect=args.inspect, inspected_flag=inspected_record_flag,
|
||
)
|
||
all_check_records.extend(records)
|
||
|
||
cmn.log(f"[data] check result: {len(all_check_results)} 条, "
|
||
f"check record: {len(all_check_records)} 条")
|
||
|
||
if not all_check_records:
|
||
stats.add_warning("查询完成，但未得到任何打卡流水记录")
|
||
|
||
# 5. 获取考勤组信息（通过 group API 反向映射 userId → 考勤组名称）
|
||
group_name_map = cmn.extract_group_names_from_records(all_check_records, user_ids)
|
||
|
||
# 6. 构建明细行（以 check record 为主表，关联 check result 获取考勤时间和打卡结果）
|
||
detail_rows = build_record_rows(
|
||
all_check_records, all_check_results, user_info_map, group_name_map,
|
||
)
|
||
|
||
# 7. 写 Excel
|
||
rows_2d = [[row.get(h, "") for h in ALL_HEADERS] for row in detail_rows]
|
||
out_name = args.out or cmn.build_output_filename(start, end, suffix="detail")
|
||
|
||
title = (
|
||
f"考勤明细展示 统计日期：{start.strftime(cmn.DATE_FMT)} "
|
||
f"至 {end.strftime(cmn.DATE_FMT)}"
|
||
)
|
||
subtitle = f"报表生成时间：{datetime.now().strftime('%Y-%m-%d %H:%M')}"
|
||
|
||
# 图片嵌入参数：默认开启，--no-images 关闭
|
||
image_columns = None if args.no_images else IMAGE_COLUMN_NAMES
|
||
image_size = _parse_image_size(args.image_size)
|
||
|
||
try:
|
||
cmn.write_excel(
|
||
out_name, ALL_HEADERS, rows_2d,
|
||
sheet_name="考勤明细",
|
||
title=title,
|
||
subtitle=subtitle,
|
||
image_columns=image_columns,
|
||
image_size=image_size,
|
||
)
|
||
except RuntimeError as exc:
|
||
cmn.error(str(exc))
|
||
return 1
|
||
|
||
# 8. 摘要
|
||
cmn.print_summary(
|
||
granularity_label="明细（打卡流水）",
|
||
out_path=out_name,
|
||
user_count=len(user_ids),
|
||
column_names=CHECK_HEADERS,
|
||
start=start,
|
||
end=end,
|
||
rows_count=len(rows_2d),
|
||
stats=stats,
|
||
)
|
||
return 0
|
||
|
||
|
||
if __name__ == "__main__":
|
||
sys.exit(main()) |