chenmingxuan/EP-Hub-Skill

Fork 0

Files

T

chenmingxuan 0c8fa2653e first commit

2026-09-02 11:44:52 +08:00

9.4 KiB

Raw Permalink Blame History

假期余额导出参考 (attendance-vacation)

本文档由 attendance.md 路由调用。当用户提到“导出假期余额”、“假期余额列表”、“所有假期规则余额”、“假期余额 Excel”、“年假/病假/调休余额导出”等诉求时，必须先阅读本文档，再调用配套脚本。

强制门禁

任何调用 attendance_vacation_balance.py 的请求，都必须经过本文档定义的工作流，禁止只凭脚本路径或 --help 自行拼命令。

执行前必须确认：

人员范围：指定员工 / 部门 / 多部门；缺失时必须追问
导出范围：默认导出所有假期规则余额；用户指定“年假/病假/调休”等时才传 --leave-keywords
输出形式：生成 Excel，不在对话中粘贴完整表格

核心原则

Agent 只负责解析人员范围并获取 userId 列表；假期规则查询、leaveCode 解析、假期规则单位解析、余额查询、字段解析、用户信息补齐、Excel 生成都由脚本完成。

--leave-keywords 是 attendance_vacation_balance.py 的脚本入参，只用于按假期名称筛选导出列；不是 dws attendance vacation balance 的入参。vacation balance 当前只支持批量 --users 和单个 --leave-code，因此脚本必须先获取假期规则列表，再按每个匹配到的 leaveCode 分别查询余额。

脚本输出结构参考钉钉假期余额列表：

每名员工一行
基础列固定：姓名、部门、入职时间、首次工作时间
假期规则横向动态展开为多列，表头必须携带 vacation types 返回的规则单位，例如 年假(天)、病假(天)、调休(小时)
特殊值统一展示为 不限制余额、不适用、未设置
当某个假期规则 leaveCode 查询余额时接口返回“假期类型没有余额”类业务错误，表示该规则不限制余额，脚本应为该规则列填充 不限制余额
当余额记录中返回 visible=false，表示该员工不适用该假期规则，脚本应为该员工 + 该规则单元格填充 不适用
当接口返回“员工未设置入职时间”或“员工未设置首次参加工作时间”类业务错误，表示该假期规则依赖员工时间字段且当前员工缺失配置，脚本应为该员工 + 该规则单元格填充 不适用
当 vacation types 返回假期规则 source=external，表示该规则由开放接口写入；若这类外部规则调用余额接口失败且不是权限错误，脚本不应阻断导出，应为该员工 + 该规则单元格填充 外部规则暂无余额，需通过接口初始化更新余额

严格禁止 (NEVER DO)

禁止凭历史记忆复用 userId、deptId、leaveCode
禁止 Agent 手工汇总、转置或目测假期余额
禁止 Agent 自行只查单个 leave-code 再声称是“所有假期规则余额”；如需导出所有假期规则余额，必须交由脚本按假期规则列表逐个 leaveCode 查询并汇总
禁止直接输出裸 userId；脚本会通过 contact user get 转换姓名和部门
禁止把 Excel 明细内容完整贴在对话里，只返回路径和摘要

严格要求 (MUST DO)

所有 dws 命令必须携带 --format json
假期规则名称--leave-keywords与假期规则leaveCode的映射必须从 vacation types 实时建立，禁止硬编码
假期规则单位必须从 vacation types 实时读取，优先使用 leaveViewUnit 等展示单位字段，并在 Excel 表头中展示为 假期名称(单位)
假期规则来源必须从 vacation types 实时读取；当 source=external 时按外部接口写入规则处理
任何接口失败必须向用户清晰报错，禁止静默吞掉
vacation balance 返回“假期类型没有余额”时不作为致命错误处理，应按该假期规则 leaveCode 生成 不限制余额
vacation balance 返回员工维度 visible=false 时不作为查询失败处理，应按该员工 + 假期规则 leaveCode 生成 不适用
vacation balance 返回“员工未设置入职时间”或“员工未设置首次参加工作时间”时不作为查询失败处理，应按该员工 + 假期规则 leaveCode 生成 不适用
对 source=external 的外部假期规则，vacation balance 查询失败且不是权限错误时不作为导出失败处理，应按该员工 + 假期规则 leaveCode 生成 外部规则暂无余额，需通过接口初始化更新余额

涉及工具

工具	用途	安全等级
`dws attendance vacation types`	获取当前可见的假期规则清单，用于建立假期名称/关键词 → `leaveCode` 的映射，读取 `leaveViewUnit` 等规则单位、`source` 规则来源，并决定 Excel 假期列顺序	只读
`dws attendance vacation balance`	按批量 `--users` + 单个 `--leave-code` 查询员工假期余额；由脚本按匹配到的 `leaveCode` 逐个调用	只读
`dws aisearch person`	按姓名搜索用户获取 userId（搜人首选）	只读
`dws contact user get`	批量查询 userId → 用户信息（姓名/部门/入职时间等），用于 Excel 基础列补齐	只读
`dws contact dept search`	搜索部门获取 deptId	只读
`dws contact dept list-members`	获取部门成员 userId 列表	只读

工作流

阶段 0：参数解析

识别人员范围：
- 指定员工姓名：用 dws aisearch person --query "<姓名>" --dimension name --format json 获取 userId
- 指定部门：用 dws contact dept search --query "<部门名>" --format json，再用 dws contact dept list-members --ids <deptId> --format json 获取成员
- 已提供 userId：直接使用
识别假期列范围：
- 未指定假期类型：导出所有假期规则余额，不传 --leave-keywords
- 指定假期类型：传 --leave-keywords "年假,病假"

阶段 1: 获取完整人员列表

场景 A — 指定员工姓名:

dws aisearch person --query "<员工姓名>" --dimension name --format json

场景 B — 按部门查询:

dws contact dept search --query "<部门名>" --format json
dws contact dept list-members --ids <deptId> --format json

场景 C — 多个部门: 对每个部门分别执行 B，汇总去重。

场景 D — 全公司: 暂不支持，引导用户指定部门。

场景 E — 用户已给 userId 列表: 直接跳过本步。

阶段 2：调用脚本生成 Excel

python scripts/attendance_vacation_balance.py \
  --users <userId1>,<userId2>,... \
  [--leave-keywords "年假,病假,调休"] \
  [--out 假期余额列表.xlsx]

脚本内部自动执行：

dws attendance vacation types --format json 获取假期规则列表、leaveCode、展示单位、规则来源 source 和列顺序
对匹配到的每个假期规则，调用 dws attendance vacation balance --users <批量用户> --leave-code <单个leaveCode> --format json 查询余额；vacation balance 不支持 --leave-keywords
处理特殊业务返回：
- 返回“假期类型没有余额”类业务错误：该 leaveCode 对应列填充 不限制余额
- 返回员工维度 visible=false：该员工 + 该 leaveCode 单元格填充 不适用
- 返回“员工未设置入职时间”或“员工未设置首次参加工作时间”：该员工 + 该 leaveCode 单元格填充 不适用
- source=external 的外部假期规则查询失败且不是权限错误：该员工 + 该 leaveCode 单元格填充 外部规则暂无余额，需通过接口初始化更新余额
dws contact user get --ids <批量用户> --format json 获取姓名、部门等信息
生成 Excel：attendance_vacation_balance_<yyyyMMdd_HHmmss>.xlsx

阶段 3：返回结果

向用户返回脚本 stdout 摘要即可，必须包含：

输出文件路径
员工数量
假期规则列数
如传了 --leave-keywords，说明筛选关键词

不要粘贴 Excel 全量内容。

错误处理

错误	处理方式
权限不足	提示当前账号无权查询目标员工假期余额，需管理员或管理范围权限
人员范围缺失	追问员工或部门，禁止猜测
无假期规则	提示未匹配到假期规则，建议先执行 `dws attendance vacation types --format json` 验证
假期类型没有余额	不作为失败返回；按对应假期规则 `leaveCode` 填充 `不限制余额`
`visible=false`	不作为失败返回；按对应员工 + 假期规则 `leaveCode` 填充 `不适用`
员工未设置入职时间 / 首次参加工作时间	不作为失败返回；说明该规则依赖员工时间字段，按对应员工 + 假期规则 `leaveCode` 填充 `不适用`
外部假期规则查询失败	当假期规则 `source=external` 且失败不是权限错误时，不作为导出失败；按对应员工 + 假期规则 `leaveCode` 填充 `外部规则暂无余额，需通过接口初始化更新余额`
openpyxl 缺失	提示执行 `pip install openpyxl`
接口返回结构不确定	使用脚本 `--inspect` 重新执行一次，查看首条原始结构

配套脚本

脚本	场景	CLI 参数
attendance_vacation_balance.py	假期余额列表 Excel 导出；脚本按假期名称关键词筛选规则，并逐个 `leaveCode` 调用余额查询	`--users [--leave-keywords] [--out] [--inspect]`

9.4 KiB Raw Permalink Blame History Unescape Escape