auto backup 2026-07-02 11:00

2026-07-02 11:00:05 +08:00
parent 022b6edbe4
commit c7ff34d012
199 changed files with 43050 additions and 0 deletions
@@ -0,0 +1,97 @@
+# 考勤 (attendance) 命令参考
+
+## 命令总览
+
+### 查询个人考勤详情
+```
+Usage:
+  dws attendance record get [flags]
+Example:
+  dws attendance record get --user <USER_ID> --date 2026-03-08
+Flags:
+      --date string   查询日期, 格式 YYYY-MM-DD (必填)
+      --user string   钉钉用户 ID (必填)
+```
+
+### 批量查询员工班次信息
+```
+Usage:
+  dws attendance shift list [flags]
+Example:
+  dws attendance shift list --users userId1,userId2 --start 2026-03-03 --end 2026-03-07
+Flags:
+      --end string     结束日期, 格式 YYYY-MM-DD (必填)
+      --start string   开始日期, 格式 YYYY-MM-DD (必填)
+      --users string   用户 ID 列表, 逗号分隔, 最多 50 个 (必填)
+```
+
+返回每条记录含：用户 ID、工作日期、打卡类型（OnDuty/OffDuty）、计划打卡时间、是否休息日。间隔不超过 7 天，最多 50 人。
+
+### 查询某个人的考勤统计摘要
+```
+Usage:
+  dws attendance summary [flags]
+Example:
+  dws attendance summary --user USER_ID --date "2026-03-12 15:00:00" --stats-type month
+  dws attendance summary --user USER_ID --date "2026-03-12 15:00:00" --stats-type week
+Flags:
+      --date string         工作日期, 格式 yyyy-MM-dd HH:mm:ss (必填)
+      --stats-type string   统计类型：week（周统计）或 month（月统计）（必填，钉钉服务端业务层强制要求；CLI 层会直接拒绝缺失/非法值）
+      --user string         钉钉用户 ID (必填)
+```
+
+> ⚠️ **重要**：`--stats-type` 在钉钉 schema 中标记为 `required: []`（看似可选），但服务端业务层**强制要求**，不传服务端会回 `C0002 / 统计类型错误`。CLI 已在客户端层做了 fail-fast：缺失或非 `week`/`month` 的取值会直接被 CLI 拒绝，不会发出请求。
+
+### 查询考勤组与考勤规则
+```
+Usage:
+  dws attendance rules [flags]
+Example:
+  dws attendance rules --date 2026-03-14
+  dws attendance rules --date "2026-03-14 09:00:00"
+Flags:
+      --date string   考勤日期, 格式 YYYY-MM-DD 或 yyyy-MM-dd HH:mm:ss (必填)
+```
+
+查询考勤组/考勤规则。例如：我属于哪个考勤组、打卡范围是什么、弹性工时怎么算。
+
+## 意图判断
+
+用户说"打卡记录/出勤/考勤" → `record get`
+用户说"排班/班次/当班" → `shift list`
+用户说"考勤汇总/统计" → `summary`
+用户说"考勤组/考勤规则/打卡规则" → `rules`
+
+## 核心工作流
+
+```bash
+# 查看某人考勤
+dws attendance record get --user <USER_ID> --date 2026-03-08 --format json
+
+# 批量查排班
+dws attendance shift list --users userId1,userId2 \
+  --start 2026-03-03 --end 2026-03-07 --format json
+
+# 查看考勤统计摘要
+dws attendance summary --user <USER_ID> --date "2026-03-12 15:00:00" --format json
+
+# 查看考勤组和规则
+dws attendance rules --date 2026-03-14 --format json
+```
+## 上下文传递表
+| 操作 | 提取 | 用于 |
+|------|------|------|
+| `contact user get-self` | `userId` | record get 的 --user, shift list 的 --users, summary 的 --user |
+## 注意事项
+- `record get` 的 `--date` 格式: YYYY-MM-DD（如 `2026-03-08`），CLI 自动转换为毫秒时间戳
+- `shift list` 的 `--start/--end` 同样使用 YYYY-MM-DD 格式，间隔不超过 7 天
+- `summary` 的 `--date` 格式: yyyy-MM-dd HH:mm:ss（如 `2026-03-12 15:00:00`）
+- `rules` 的 `--date` 支持 YYYY-MM-DD 或 yyyy-MM-dd HH:mm:ss 两种格式
+- 用户 ID 需从 `contact user get-self` 或 `contact user search` 获取
+
+## 自动化脚本
+
+| 脚本 | 场景 | 用法 |
+|------|------|------|
+| [attendance_my_record.py](../../scripts/attendance_my_record.py) | 查看我今天/指定日期的考勤记录 | `python attendance_my_record.py today` |
+| [attendance_team_shift.py](../../scripts/attendance_team_shift.py) | 查询团队成员本周排班 | `python attendance_team_shift.py --users userId1,userId2` |