@lark-people/cli 0.0.0-beta.3 → 0.0.0-beta.4

package/skills/people-overtime/references/people-attendance-submission.md

@@ -1,203 +0,0 @@
-# submission (submission.get / submission.query_month_summary)
-
-> ⚠️ **地域强约束**：`submission.*` **默认支持非 CN 员工**（新加坡 SGP / 马来西亚 MY / 其他海外）；**CN 中国大陆员工默认请走 `user_approval_over_time.list`**。**仅当 `submission.get` / `submission.query_month_summary` 返回报错文案包含 `method not support CHN country` 时，才允许自动回退到 `user_approval_over_time.list`**；若只是空结果，则直接按无记录处理，不要切换接口。
-
-用于查询**当前登录用户**（非 CN）：
-
-- 指定日期的加班提报记录（`submission.get`，`time_type=2`）
-- 指定月份的加班月累计汇总（`submission.query_month_summary`）
-
-> **前置条件：** 先阅读 [`../../people-shared/SKILL.md`](../../people-shared/SKILL.md)
-
-**CRITICAL — 只支持查询当前登录用户，不支持查询其他人；只读，不支持提交/修改/撤回/删除（CN 员工提交加班请走 `+overtime-apply-*`，非 CN 员工提交加班请去审批系统）。**
-
-## 与 `user_approval_over_time` 的分工（按地域互斥）
-
-| 接口 | 适用地域 | 何时使用 |
-|------|---------|----------|
-| `submission.get` (`time_type=2`) | **仅非 CN（SGP / MY 等）** | 查"加班提报记录"，需要 `calculation_tag` / `display_name` / `更正审批中` 等详情字段；按字段二次过滤；多日聚合 |
-| `submission.query_month_summary` | **仅非 CN（SGP / MY 等）** | 查"某月累计加班时长"，单月口径汇总 |
-| `user_approval_over_time.list` | **仅 CN 中国大陆** | 查"加班审批单"，按 `status`（已通过/已拒绝/已撤回/已撤销）和日期范围筛选；不返回 `calculation_tag` |
-
-## 用法
-
-### 步骤1：查看 schema（必须）
-
-```bash
-people-cli schema attendance.submission.get
-people-cli schema attendance.submission.query_month_summary
-```
-
-> 两个接口均为 GET 请求，所有参数均在 `--params` 中传递。
-
-### 步骤2：调用
-
-```bash
-people-cli attendance submission get --params '<query_params_json>' --as user
-people-cli attendance submission query_month_summary --params '<query_params_json>' --as user
-```
-
-## 方法：submission.get
-
-### --params (query 参数)
-
-| 参数          | 类型 | 必填 | 说明                               |
-|-------------|------|------|----------------------------------|
-| `date`      | string | 是 | 查询日期，格式 `YYYYMMDD`（如 `20260408`） |
-| `time_type` | string | 是 | `1`=出勤提报记录；`2`=**加班提报记录**（本 skill 必传 `2`） |
-| `accept_language` | string | 否  | 语言环境，**仅 `"zh-CN"` 或 `"en-US"`**，默认 `zh-CN`；**字面值严格**，详见下方 CAUTION |
-
-> [!CAUTION]
-> **`accept_language` 字面值严格**：服务端只识别 **`"zh-CN"`** 与 **`"en-US"`** 两个值。传 `en` / `en_US` / `en-us` / `en_us` / `english` / `EN-US` / `zh` / `zh_CN` / `cn` 等任何变体，服务端都会**默默回退到中文**，让英文用户拿到中文 `display_name` / `status` / `calculation_tag` 字段，看似查到了数据其实跑偏。
->
-> **强制行为**：
-> - 英文上下文（用户用英文提问 / 系统语言为英文 / query 主词是英文 attendance/overtime 业务词）→ **必须**传 `accept_language="en-US"`，不允许省略。
-> - 中文上下文 → 显式传 `accept_language="zh-CN"`，不省略以避免依赖默认值。
-> - 任何输入变体（`en` / `en_us` / `english` 等）→ LLM 必须先**归一化**为 `en-US` / `zh-CN` 再写入 `--params`。
-
-### 输出
-
-返回 JSON，主要关注 `data.rows`（数组），每项为键值对结构 `{code, value}`：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `code` | string | 字段标识（如 `overtime_date`、`status`、`duration` 等） |
-| `value` | string | 字段展示值（已格式化文本，例如 `"已通过"`、`"2026-04-08 02:00"`、`"3"`） |
-
-#### 常见 `code`
-
-> 实际返回字段会随业务/场景变化，以下为高频字段。
-
-| code | 说明 / 取值示例 |
-|------|------|
-| `overtime_date` | 加班提报日期 |
-| `display_name` | 展示名称（如「出勤」） |
-| `status` | 审批状态：`已通过` / `审批中` / `已拒绝` / `更正审批中` |
-| `calculation_tag` | 计算标签/口径，常见取值：`Working Day Overtime`、`Normal Working Hours`、`Overtime Pay`（加班费）、`Time off in Lieu (Overtime)`（调休假）、`1.5 Hourly`、`1.5x Daily Salary`、`2x Daily Salary`、`【SGP】1 倍日薪` 等 |
-| `duration` | 时长数值（需结合 `unit` 解读） |
-| `unit` | 时长单位（如「小时」） |
-| `start_time` | 加班开始时间 |
-| `end_time` | 加班结束时间（跨日时为次日时间） |
-| `reason` | 加班原因（部分场景才返回） |
-
-#### 常见报错
-
-`code:1000020904` → `当前员工未灰度到出勤加班新功能`，向用户原文透传该提示。
-`code:1000020847` → 当前账号没有相应权限点（无访问出勤/加班数据的权限），向用户提示「当前账号没有查询该数据的权限点，请联系管理员开通后再试」，不要重试。
-
-## 方法：submission.query_month_summary
-
-### --params (query 参数)
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `month` | string | 是 | 查询月份，格式 `YYYYMM`（如 `202605`、跨年 `202512`），**不是 `YYYY-MM`** |
-| `accept_language` | string | 否  | 语言环境，**仅 `"zh-CN"` 或 `"en-US"`**，默认 `zh-CN`；**字面值严格**，传 `en` / `en_US` / `en-us` / `en_us` / `english` 等任何变体都会被默默回退到中文，必须先归一化为 `en-US` / `zh-CN` 再传 |
-
-### 输出
-
-返回 JSON，主要关注：
-
-- `data.overtime_summary_stats`：加班汇总
-
-数组每项：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `label` | string | 汇总项标题（如「5 月加班时长」） |
-| `value` | string | 汇总值（如「12.5 小时」） |
-| `detail_stats_lists` | array | 明细列表，每项为 `{ "label": "...", "value": "..." }` |
-
-#### 常见报错
-
-`code:1000020904` → `当前员工未灰度到出勤加班新功能`。
-
-## 多日聚合查询规则（重要）
-
-接口本身**只支持单日**。所有「本周/上周/本月/上月/最近两周/上月最后一周」等范围意图，必须按下面的步骤执行：
-
-1. 解析日期范围 → 列出每一个具体日期（YYYYMMDD），未来日期不查询。
-2. 逐日调用 `submission.get`（`time_type=2`），并行/串行均可。
-3. 在内存中聚合 `data.rows`：
-   - 求和：`sum(duration)`，如「上周累计加班时长」「本月已通过加班总时长」。
-   - 计数：满足条件的天数，如「上周已通过的加班几天」「上周哪几天加班 > 2 小时」。
-   - 过滤：按 `status` / `calculation_tag` / `duration` 阈值过滤；多条件用 AND（如「duration > 2 且 status = 已通过」「calculation_tag = Overtime Pay 且 status = 已通过」）。
-   - 分组：按 `calculation_tag` 分组汇总 `duration`，如「本月已通过按计算标签分类各多少小时」。
-   - 比较：找最大/最小或两段对比，如「上周和上上周哪周加班更多」。
-4. 输出时回显具体日期 + 字段值，避免只返回总和而丢失上下文。
-
-### 工作日 / 周末处理
-
-- 「上周工作日」按周一~周五；用户明示「上周六/上周日有没有加班」时仍按所给日期查询。
-- 「本周到现在」按周一 ~ 今天（`<= today`），未来不查询。
-- 「上半年/下半年」逐月查询 `query_month_summary` 后汇总。
-
-### 时间推理参考（基于当前日期 = 2026-06-09 周二，仅作示例口径，实际应以系统当前日期为准）
-
-| 表达 | 解析 |
-|------|------|
-| 今天 / today | 2026-06-09 |
-| 昨天 / yesterday | 2026-06-08 |
-| 前天 | 2026-06-07 |
-| 4 天前 / N 天前 | 2026-06-05 / 减 N 天 |
-| 这周 / 本周（到现在） | 周一(2026-06-08) ~ 今天 |
-| 上周 | 上周一 ~ 上周日 |
-| 上上周 | 再往前推 7 天 |
-| 上周一/三/四/五/六/日 | 上周对应工作日（last Mon/Wed/Thu/Fri/Sat/Sun） |
-| 这个月 / 本月（到现在） | 当月 1 号 ~ 今天 |
-| 上个月 | 上月 1 号 ~ 上月最后一天 |
-| 去年 12 月 | 跨年，month=202512 |
-| May / 5 月 28 号 | 2026-05 / 2026-05-28 |
-| 下周二 / 明天 / 未来日期 | 拒绝查询 |
-
-### SGP 加班规则提示（仅 SGP 员工，发起加班时使用）
-
-- **周日加班**：duration ≤ 4h → 0 daily allowance；4h < duration ≤ 8h → 1 daily；duration > 8h → 2 daily。
-- **周六加班**：按 Saturday OT 规则。
-- **工作日加班**：calculation_tag 通常为 `Working Day Overtime`。
-- 跨日加班（如 `22:00 → 次日 01:00`）：`overtime_date` 通常归属开始日期，`duration` 为实际跨日累计时长。
-
-## 不支持的操作（直接拒绝，不调用 CLI）
-
-| 用户意图 | 处理 |
-|----------|------|
-| 帮我撤回 / 取消 / 修改 / 删除加班申请 | 「不支持撤回/取消/修改/删除，请前往审批系统操作」 |
-| 查询他人 / 工号 / employee_id / 下属加班 | 「只支持查询当前登录账号本人的加班提报记录」 |
-| 查询未来日期（如下周二、明天） | 「不支持查询未来日期的加班记录」 |
-| 非法日期（2 月 30 日、13 月） | 「只支持查询合法日期的加班记录」 |
-| 加班够不够抵扣迟到 / 加班补贴怎么算 / 哪天可以加班 | 「当前只支持查询加班数据，不支持其他联动能力」 |
-| 导出加班记录 | 「不支持导出操作」 |
-| 单日加班时长 > 24h / = 0 / 为负数 | 拒绝并提示用户填写合理时长，不调用 CLI |
-
-## 所需权限
-
-| Scope |
-|-------|
-| `corehr:people_cli` |
-
-## 示例
-
-```bash
-# 查看参数结构
-people-cli schema attendance.submission.get
-people-cli schema attendance.submission.query_month_summary
-
-# 查询指定日期的加班提报记录
-people-cli attendance submission get --params '{"date":"20260408","time_type":"2","accept_language":"zh-CN"}' --as user
-
-# 查询本月加班累计汇总
-people-cli attendance submission query_month_summary --params '{"month":"202606","accept_language":"zh-CN"}' --as user
-
-# 多日聚合：上周加班按 calculation_tag=Working Day Overtime 汇总
-people-cli attendance submission get --params '{"date":"20260601","time_type":"2","accept_language":"zh-CN"}' --as user
-people-cli attendance submission get --params '{"date":"20260602","time_type":"2","accept_language":"zh-CN"}' --as user
-people-cli attendance submission get --params '{"date":"20260603","time_type":"2","accept_language":"zh-CN"}' --as user
-people-cli attendance submission get --params '{"date":"20260604","time_type":"2","accept_language":"zh-CN"}' --as user
-people-cli attendance submission get --params '{"date":"20260605","time_type":"2","accept_language":"zh-CN"}' --as user
-people-cli attendance submission get --params '{"date":"20260606","time_type":"2","accept_language":"zh-CN"}' --as user
-people-cli attendance submission get --params '{"date":"20260607","time_type":"2","accept_language":"zh-CN"}' --as user
-# → 在内存中按 calculation_tag / status / duration 过滤后再求和
-
-# 跨年单月汇总
-people-cli attendance submission query_month_summary --params '{"month":"202512","accept_language":"zh-CN"}' --as user
-```