#!/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())