first commit
This commit is contained in:
@@ -0,0 +1,344 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
考勤排班查询导出脚本
|
||||
|
||||
[AI Agent 强制门禁] 本脚本执行前必须先阅读：
|
||||
references/attendance-schedule.md
|
||||
|
||||
职责：
|
||||
1. 分批查询排班记录（支持大量用户自动分批）
|
||||
2. 将 classId 转为班次名称
|
||||
3. 将 userId 转为员工姓名
|
||||
4. 输出日历表格式的排班表 Excel（行=员工，列=日期，单元格=班次名称）
|
||||
|
||||
用法:
|
||||
python attendance_schedule_export.py \
|
||||
--users userId1,userId2,userId3 \
|
||||
--start 2026-05-19 --end 2026-05-23
|
||||
|
||||
python attendance_schedule_export.py \
|
||||
--users userId1,userId2 \
|
||||
--start 2026-05-01 --end 2026-05-31 \
|
||||
--output my_schedule.xlsx
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import os
|
||||
import sys
|
||||
from datetime import datetime, timedelta
|
||||
from typing import Any
|
||||
|
||||
from attendance_report_common import (
|
||||
DATE_FMT,
|
||||
DATETIME_FMT,
|
||||
DwsCallError,
|
||||
chunk_users,
|
||||
error,
|
||||
extract_records,
|
||||
log,
|
||||
parse_datetime_arg,
|
||||
resolve_user_names,
|
||||
run_dws,
|
||||
warn,
|
||||
write_excel,
|
||||
)
|
||||
|
||||
# schedule get 接口每批最多用户数（保守值，避免超时）
|
||||
SCHEDULE_BATCH_SIZE = 20
|
||||
|
||||
WEEKDAY_NAMES = ["周一", "周二", "周三", "周四", "周五", "周六", "周日"]
|
||||
|
||||
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
# 排班数据查询（分批）
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
def fetch_schedule_batch(
|
||||
user_ids: list[str],
|
||||
start_date: str,
|
||||
end_date: str,
|
||||
) -> list[dict]:
|
||||
"""调用 dws attendance schedule get 查询一批用户的排班记录。"""
|
||||
users_str = ",".join(user_ids)
|
||||
try:
|
||||
result = run_dws([
|
||||
"attendance", "schedule", "get",
|
||||
"--users", users_str,
|
||||
"--start", start_date,
|
||||
"--end", end_date,
|
||||
])
|
||||
except DwsCallError as exc:
|
||||
error(f"查询排班失败 (users={len(user_ids)}, {start_date}~{end_date}): {exc}")
|
||||
return []
|
||||
return extract_records(result) if result else []
|
||||
|
||||
|
||||
def fetch_all_schedules(
|
||||
user_ids: list[str],
|
||||
start_date: str,
|
||||
end_date: str,
|
||||
) -> list[dict]:
|
||||
"""分批查询所有用户的排班记录，自动处理用户数超限。"""
|
||||
all_records: list[dict] = []
|
||||
batches = chunk_users(user_ids, SCHEDULE_BATCH_SIZE)
|
||||
total = len(batches)
|
||||
|
||||
log(f"📋 共 {len(user_ids)} 人，分 {total} 批查询排班 ({start_date} ~ {end_date})")
|
||||
|
||||
for idx, batch in enumerate(batches, start=1):
|
||||
if total > 1:
|
||||
log(f" 批次 {idx}/{total}: {len(batch)} 人")
|
||||
records = fetch_schedule_batch(batch, start_date, end_date)
|
||||
all_records.extend(records)
|
||||
|
||||
log(f"✅ 查询完成，共 {len(all_records)} 条排班记录")
|
||||
return all_records
|
||||
|
||||
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
# 班次名称映射
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
def build_class_name_map(records: list[dict]) -> dict[int, str]:
|
||||
"""从排班记录中提取 classId → className 映射。
|
||||
|
||||
优先使用记录自带的 className；缺失时回退 class search 补全。
|
||||
"""
|
||||
class_map: dict[int, str] = {}
|
||||
missing_ids: set[int] = set()
|
||||
|
||||
for record in records:
|
||||
raw_id = record.get("classId") or record.get("class_id")
|
||||
raw_name = record.get("className") or record.get("class_name")
|
||||
if raw_id is None:
|
||||
continue
|
||||
cid = int(raw_id)
|
||||
if raw_name and str(raw_name).strip():
|
||||
class_map[cid] = str(raw_name).strip()
|
||||
elif cid != 0 and cid not in class_map:
|
||||
missing_ids.add(cid)
|
||||
|
||||
if missing_ids:
|
||||
log(f"🔍 {len(missing_ids)} 个班次缺名称，从 class search 补全 ...")
|
||||
try:
|
||||
result = run_dws(["attendance", "class", "search", "--page-size", "200"])
|
||||
for cls in (extract_records(result) if result else []):
|
||||
cid_raw = cls.get("id") or cls.get("classId")
|
||||
cname = cls.get("name") or cls.get("className")
|
||||
if cid_raw is not None and cname:
|
||||
class_map[int(cid_raw)] = str(cname).strip()
|
||||
except DwsCallError as exc:
|
||||
warn(f"class search 失败，部分班次将显示为 ID: {exc}")
|
||||
|
||||
return class_map
|
||||
|
||||
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
# 日期工具
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
def normalize_work_date(raw: Any) -> str:
|
||||
"""将排班记录中的 workDate 标准化为 YYYY-MM-DD。"""
|
||||
if raw is None:
|
||||
return ""
|
||||
if isinstance(raw, (int, float)):
|
||||
ts = raw / 1000 if raw > 1e12 else raw
|
||||
try:
|
||||
return datetime.fromtimestamp(ts).strftime(DATE_FMT)
|
||||
except (OSError, ValueError, OverflowError):
|
||||
return ""
|
||||
s = str(raw).strip()
|
||||
if len(s) >= 10 and s[4] == "-" and s[7] == "-":
|
||||
return s[:10]
|
||||
return s
|
||||
|
||||
|
||||
def generate_date_range(start: datetime, end: datetime) -> list[str]:
|
||||
"""生成 start 到 end 之间的所有日期字符串列表。"""
|
||||
dates: list[str] = []
|
||||
current = start
|
||||
while current <= end:
|
||||
dates.append(current.strftime(DATE_FMT))
|
||||
current += timedelta(days=1)
|
||||
return dates
|
||||
|
||||
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
# 构建排班表（日历表格式）
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
def build_schedule_table(
|
||||
records: list[dict],
|
||||
user_ids: list[str],
|
||||
user_names: dict[str, str],
|
||||
class_map: dict[int, str],
|
||||
date_range: list[str],
|
||||
) -> tuple[list[str], list[list[str]]]:
|
||||
"""构建日历表格式的排班表。
|
||||
|
||||
Returns:
|
||||
(headers, rows)
|
||||
headers = ["员工姓名", "05-19\n周一", "05-20\n周二", ...]
|
||||
rows = [["张三", "早班", "早班", "休息", ...], ...]
|
||||
"""
|
||||
# 构建 (userId, date) → 班次显示文本
|
||||
schedule_lookup: dict[tuple[str, str], str] = {}
|
||||
for record in records:
|
||||
uid = str(record.get("userId") or record.get("userid") or "")
|
||||
work_date = normalize_work_date(record.get("workDate") or record.get("work_date"))
|
||||
if not uid or not work_date:
|
||||
continue
|
||||
|
||||
is_rest = str(record.get("isRest") or record.get("is_rest") or "N").upper()
|
||||
raw_cid = record.get("classId") or record.get("class_id") or 0
|
||||
raw_cname = record.get("className") or record.get("class_name") or ""
|
||||
|
||||
if is_rest == "Y":
|
||||
display = "休息"
|
||||
elif raw_cname and str(raw_cname).strip():
|
||||
display = str(raw_cname).strip()
|
||||
else:
|
||||
cid = int(raw_cid) if raw_cid else 0
|
||||
if cid in class_map:
|
||||
display = class_map[cid]
|
||||
elif cid == 0:
|
||||
display = "休息"
|
||||
else:
|
||||
display = f"班次{cid}"
|
||||
|
||||
schedule_lookup[(uid, work_date)] = display
|
||||
|
||||
# 表头
|
||||
headers = ["员工姓名"]
|
||||
for date_str in date_range:
|
||||
dt = datetime.strptime(date_str, DATE_FMT)
|
||||
weekday = WEEKDAY_NAMES[dt.weekday()]
|
||||
headers.append(f"{date_str[5:]}\n{weekday}")
|
||||
|
||||
# 数据行
|
||||
rows: list[list[str]] = []
|
||||
for uid in user_ids:
|
||||
name = user_names.get(uid, uid)
|
||||
row = [name]
|
||||
for date_str in date_range:
|
||||
row.append(schedule_lookup.get((uid, date_str), ""))
|
||||
rows.append(row)
|
||||
|
||||
return headers, rows
|
||||
|
||||
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
# 摘要输出
|
||||
# ─────────────────────────────────────────────────────────────────────────────
|
||||
|
||||
def print_summary(
|
||||
rows: list[list[str]],
|
||||
date_range: list[str],
|
||||
out_path: str,
|
||||
record_count: int,
|
||||
) -> None:
|
||||
"""输出排班查询摘要到 stdout。"""
|
||||
out_abs = os.path.abspath(out_path)
|
||||
print(f"\n✅ 排班表导出成功！")
|
||||
print(f" 文件: {out_abs}")
|
||||
print(f" 人数: {len(rows)}")
|
||||
print(f" 日期: {date_range[0]} ~ {date_range[-1]} ({len(date_range)} 天)")
|
||||
print(f" 记录: {record_count} 条")
|
||||
|
||||
# 预览前 10 人 × 前 7 天
|
||||
preview_rows = min(len(rows), 10)
|
||||
preview_cols = min(len(date_range), 7)
|
||||
if preview_rows > 0:
|
||||
print(f"\n排班预览（前 {preview_rows} 人 × 前 {preview_cols} 天）:")
|
||||
header_line = f"{'姓名':<10}" + "".join(
|
||||
f"{d[5:]:<8}" for d in date_range[:preview_cols]
|
||||
)
|
||||
print(header_line)
|
||||
print("-" * len(header_line))
|
||||
for row in rows[:preview_rows]:
|
||||
line = f"{row[0]:<10}" + "".join(
|
||||
f"{cell:<8}" for cell in row[1:preview_cols + 1]
|
||||
)
|
||||
print(line)
|
||||
if len(date_range) > preview_cols:
|
||||
print(f" ... 共 {len(date_range)} 天，完整数据见 Excel")
|
||||
if len(rows) > preview_rows:
|
||||
print(f" ... 共 {len(rows)} 人，完整数据见 Excel")
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(
|
||||
description="考勤排班查询导出（排班表格式）",
|
||||
epilog="执行前必须阅读 attendance-schedule.md",
|
||||
)
|
||||
parser.add_argument("--users", required=True, help="userId 列表，逗号分隔（必填）")
|
||||
parser.add_argument("--start", required=True, help="开始日期 YYYY-MM-DD（必填）")
|
||||
parser.add_argument("--end", required=True, help="结束日期 YYYY-MM-DD（必填）")
|
||||
parser.add_argument("--output", default="", help="输出文件路径（可选）")
|
||||
args = parser.parse_args()
|
||||
|
||||
# ── 解析参数 ──
|
||||
user_ids = [uid.strip() for uid in args.users.split(",") if uid.strip()]
|
||||
if not user_ids:
|
||||
error("--users 不能为空")
|
||||
raise SystemExit(1)
|
||||
|
||||
try:
|
||||
start_dt = parse_datetime_arg(args.start)
|
||||
end_dt = parse_datetime_arg(args.end, end_of_day=True)
|
||||
except ValueError as exc:
|
||||
error(str(exc))
|
||||
raise SystemExit(1) from exc
|
||||
|
||||
start_date = start_dt.strftime(DATE_FMT)
|
||||
end_date = end_dt.strftime(DATE_FMT)
|
||||
|
||||
if end_dt < start_dt:
|
||||
error(f"结束日期 {end_date} 早于开始日期 {start_date}")
|
||||
raise SystemExit(1)
|
||||
|
||||
output_path = args.output or f"attendance_schedule_{start_date}_{end_date}.xlsx"
|
||||
|
||||
log(f"🗓️ 排班查询: {len(user_ids)} 人, {start_date} ~ {end_date}")
|
||||
|
||||
# ── 阶段 1: 查询排班记录（分批） ──
|
||||
records = fetch_all_schedules(user_ids, start_date, end_date)
|
||||
if not records:
|
||||
print(f"⚠️ 未查询到排班记录 ({start_date} ~ {end_date})")
|
||||
return
|
||||
|
||||
# ── 阶段 2: 构建班次名称映射 ──
|
||||
class_map = build_class_name_map(records)
|
||||
|
||||
# ── 阶段 3: 解析员工姓名 ──
|
||||
user_names = resolve_user_names(user_ids)
|
||||
|
||||
# ── 阶段 4: 生成日期范围 & 构建排班表 ──
|
||||
date_range = generate_date_range(start_dt, end_dt)
|
||||
headers, rows = build_schedule_table(
|
||||
records, user_ids, user_names, class_map, date_range,
|
||||
)
|
||||
|
||||
# ── 阶段 5: 输出 Excel ──
|
||||
title = f"排班表 {start_date} 至 {end_date}"
|
||||
subtitle = f"生成时间：{datetime.now().strftime(DATETIME_FMT)} 共 {len(rows)} 人"
|
||||
|
||||
write_excel(
|
||||
output_path,
|
||||
headers,
|
||||
rows,
|
||||
sheet_name="排班表",
|
||||
title=title,
|
||||
subtitle=subtitle,
|
||||
)
|
||||
|
||||
log(f"📄 Excel 已保存: {os.path.abspath(output_path)}")
|
||||
|
||||
# ── 阶段 6: 输出摘要 ──
|
||||
print_summary(rows, date_range, output_path, len(records))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user