first commit

2026-09-02 11:44:52 +08:00
commit 0c8fa2653e
309 changed files with 57278 additions and 0 deletions
@@ -0,0 +1,140 @@
+# 假期余额导出参考 (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：参数解析
+
+1. 识别人员范围：
+   - 指定员工姓名：用 `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：直接使用
+2. 识别假期列范围：
+   - 未指定假期类型：导出所有假期规则余额，不传 `--leave-keywords`
+   - 指定假期类型：传 `--leave-keywords "年假,病假"`
+
+### 阶段 1: 获取完整人员列表
+
+**场景 A — 指定员工姓名**:
+```bash
+dws aisearch person --query "<员工姓名>" --dimension name --format json
+```
+
+**场景 B — 按部门查询**:
+```bash
+dws contact dept search --query "<部门名>" --format json
+dws contact dept list-members --ids <deptId> --format json
+```
+
+**场景 C — 多个部门**: 对每个部门分别执行 B，汇总去重。
+
+**场景 D — 全公司**: 暂不支持，引导用户指定部门。
+
+**场景 E — 用户已给 userId 列表**: 直接跳过本步。
+
+### 阶段 2：调用脚本生成 Excel
+
+```bash
+python scripts/attendance_vacation_balance.py \
+  --users <userId1>,<userId2>,... \
+  [--leave-keywords "年假,病假,调休"] \
+  [--out 假期余额列表.xlsx]
+```
+
+脚本内部自动执行：
+1. `dws attendance vacation types --format json` 获取假期规则列表、`leaveCode`、展示单位、规则来源 `source` 和列顺序
+2. 对匹配到的每个假期规则，调用 `dws attendance vacation balance --users <批量用户> --leave-code <单个leaveCode> --format json` 查询余额；`vacation balance` 不支持 `--leave-keywords`
+3. 处理特殊业务返回：
+   - 返回“假期类型没有余额”类业务错误：该 `leaveCode` 对应列填充 `不限制余额`
+   - 返回员工维度 `visible=false`：该员工 + 该 `leaveCode` 单元格填充 `不适用`
+   - 返回“员工未设置入职时间”或“员工未设置首次参加工作时间”：该员工 + 该 `leaveCode` 单元格填充 `不适用`
+   - `source=external` 的外部假期规则查询失败且不是权限错误：该员工 + 该 `leaveCode` 单元格填充 `外部规则暂无余额，需通过接口初始化更新余额`
+4. `dws contact user get --ids <批量用户> --format json` 获取姓名、部门等信息
+5. 生成 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](../scripts/attendance_vacation_balance.py) | 假期余额列表 Excel 导出；脚本按假期名称关键词筛选规则，并逐个 `leaveCode` 调用余额查询 | `--users [--leave-keywords] [--out] [--inspect]` |