@lark-apaas/coding-steering 0.1.6-alpha.0 → 0.1.6-alpha.2

package/steering/nestjs-react-fullstack/skills/feishu/SKILL.md

@@ -1,270 +0,0 @@
----
-name: feishu
-description: Use when integrating with Feishu (飞书) or Lark Open Platform using @larksuiteoapi/node-sdk in NestJS/TypeScript, including converting miaoda userId ↔ Feishu open_id / union_id / employee_id via spark id_convert. 触发词：飞书, Feishu, Lark, 飞书开放平台, 飞书SDK, 飞书机器人, 飞书消息, 飞书日历, 飞书审批, 多维表格, 飞书通讯录, 飞书考勤, 飞书文档, 云文档, 飞书云空间, 飞书知识库, open_id, union_id, employee_id, 飞书open_id, 飞书union_id, 飞书employee_id, open_id转换, union_id转换, 妙搭飞书ID互转, 妙搭userId转open_id, open_id反查妙搭, spark id_convert, id_convert
----
-
-# Feishu Node SDK — NestJS/TypeScript 集成指南
-
-使用 `@larksuiteoapi/node-sdk` 在 NestJS/TypeScript 项目中集成飞书开放平台。
-
-## 集成工作流
-
-**在写任何飞书代码之前，必须按顺序走完以下步骤：**
-
-```
-Step 1: 检查项目现状
-  ├─ 检查 package.json 是否有 @larksuiteoapi/node-sdk
-  ├─ 检查是否有 FeishuService / FeishuModule
-  └─ 检查 FeishuService 是否已有凭证（appId 非占位符）
-
-  ↓ 已有凭证（FeishuService 已配置）→ 跳到 Step 4
-  ↓ 没有 → Step 2
-
-Step 2: 引导用户创建飞书自建应用
-  - 向用户发送以下完整操作清单（假设用户对飞书开放平台不熟悉）：
-
-      1. 打开 https://open.feishu.cn/app → 点击「创建企业自建应用」
-      2. 进入应用 →「凭证与基础信息」页面 → 复制 App ID 和 App Secret
-      3. 「添加应用能力」→ 开启「机器人」（发消息必须）
-      4. 「权限管理」→ 申请以下权限：[根据用户需求列出具体权限，见"常用场景所需权限"表]
-      5. 「版本管理与发布」→ 创建版本 → 提交审核（企业管理员审核通过后应用生效）
-
-  - 清单发送完毕后，补充说明：
-      「完成以上步骤后，请将 App ID 和 App Secret 发给我，我来帮你写代码。」
-
-  - 等待用户提供真实凭证，**不要使用占位符生成代码**
-
-Step 3: 确认权限 + 保存凭证
-  - 根据用户需求告知需申请的权限（见"常用场景所需权限"表）
-  - 将凭证写入 FeishuService 源码常量（见"NestJS 模块设置"）
-  - 将 App ID 和用途写入 agent.md（见"飞书应用信息持久化"模板）
-
-Step 4: 安装依赖
-  - npm install @larksuiteoapi/node-sdk
-
-Step 5: 编写代码
-  - 创建 FeishuService（将凭证写入模块顶部常量）
-  - 创建 FeishuModule
-```
-
-## 代码生成约束
-
-- 所有飞书 API 调用必须放在 NestJS `@Injectable()` Service 的方法中
-- `client` 始终通过 `this.client`（FeishuService 内部）或 `this.feishuService.getClient()`（其他 Service）获取
-- 数据库操作使用 Drizzle ORM 注入实例（`@Inject(DRIZZLE_DATABASE)`），不使用裸 SQL 或自建连接
-- 禁止生成独立运行的 `.ts` 脚本文件
-
-> reference 文件中的代码示例省略了 Service 类包裹，实际使用时 `client` 应替换为 `this.client` 或从注入的 FeishuService 获取。
-
-## 插件优先原则
-
-以下飞书能力存在**平台一方插件**，优先使用插件，不要直接用 node-sdk：
-
-| 需求 | 应使用 | 说明 |
-|------|--------|------|
-| 发送飞书文本/富文本消息 | **插件**（参考 `plugin_guide`） | 插件在 Client 侧调用，无需后端 Service |
-| **发送飞书消息卡片** | **node-sdk**（本文档） | 插件不支持卡片消息，必须用 node-sdk |
-| 飞书多维表格增删改查 | **插件**（参考 `plugin_guide`） | 同上 |
-| 创建飞书群组 | **插件**（参考 `plugin_guide`） | 同上 |
-
-> **操作步骤（插件）**：先调用 `plugin_guide` 查询候选插件实例 → 调用 `get_plugin_ai_json` 获取 schema → 按文档生成 Client 侧调用代码。
-
-以下能力**无对应插件**，使用本文档的 node-sdk 方案：
-消息卡片、日历、审批、云文档、云空间、知识库、权限管理、通讯录、考勤、事件订阅、OAuth 授权。
-
-## Quick Reference
-
-| 模块 | 参考文件 | 简介 |
-|------|----------|------|
-| 消息 | `references/messaging.md` | 发送文本/富文本消息优先用插件；**卡片消息**用 node-sdk |
-| 日历 | `references/calendar.md` | 日程创建/查询/会议室 |
-| 审批 | `references/approval.md` | 审批流创建/查询/同意/拒绝 |
-| 多维表格 | `references/bitable.md` | 表格/记录/字段 CRUD ⚠️ 优先用插件 |
-| 云文档 | `references/doc.md` | 文档创建/Block 读写 |
-| 云空间 | `references/drive.md` | 文件夹/文件上传下载 |
-| 知识库 | `references/wiki.md` | 知识空间/节点管理 |
-| 权限管理 | `references/perm.md` | 文档协作者权限设置 |
-| 通讯录 | `references/contacts.md` | 用户/部门信息查询 |
-| 飞书妙搭 | `references/id-convert.md` | 妙搭与飞书开放平台用户 ID 互转 |
-| 考勤 | `references/attendance.md` | 打卡记录/考勤规则查询 |
-| 事件订阅 | `references/events.md` | WebSocket 长连接接收事件 |
-| OAuth 授权 | `references/oauth.md` | user_access_token 授权 |
-
-> 按需读取 `references/` 下的模块文档获取详细 API 用法和代码示例。
-
-## 飞书应用创建指南
-
-1. 打开 [飞书开发者后台](https://open.feishu.cn/app) → 创建企业自建应用
-2. 进入「凭证与基础信息」页面，复制 **App ID** 和 **App Secret** 发给开发者
-3. 添加应用能力 → 开启**机器人**（发消息必需）
-4. 权限管理 → 申请对应模块的 API 权限（见下方权限映射表）
-5. 安全设置 → 配置**通讯录权限范围**（使用通讯录/考勤 API 必需，设为「全部成员」或指定部门）
-6. 可用范围 → 添加需要使用该应用的人员或部门（默认仅创建者可用）
-7. 版本管理与发布 → 创建版本 → 提交管理员审核
-8. 对于已有文档/多维表格/知识库：需要将应用机器人添加为文档协作者（否则 API 无权访问）
-
-### 常用场景所需权限
-
-| 用户需求 | 需要申请的权限 | 额外要求 |
-|----------|---------------|----------|
-| 发送消息 | `im:message:send_as_bot` | 开启机器人能力 |
-| 读写文档 | `docx:document` | 机器人需为文档协作者 |
-| Markdown 转文档 | `docx:document` + `docx:document.block:convert` | — |
-| 读写多维表格 | `bitable:app` | 机器人需为表格协作者 |
-| 管理知识库 | `wiki:wiki` | 机器人需为知识空间成员 |
-| 文件上传下载 | `drive:drive` | — |
-| 文档权限管理 | `drive:permission` | — |
-| 日历日程 | `calendar:calendar` | — |
-| 审批流操作 | `approval:approval` + `approval:task` | — |
-| 查询通讯录 | `contact:contact.base:readonly` | 配置通讯录权限范围 |
-| 妙搭↔飞书用户 ID 转换 | `获取 ID 转换信息`（spark 权限） | — |
-| 查询考勤 | `attendance:task:readonly` | 配置通讯录权限范围 |
-| 事件订阅 | 对应事件的订阅权限 | 需在开发者后台配置「使用长连接接收事件/回调」 |
-| 卡片交互回调 | `card:action.trigger` | 开启长连接订阅方式，订阅 card.action.trigger 回调 |
-
-### 飞书应用信息持久化
-
-引导用户完成应用配置后，将 App ID 和项目的飞书用途写入 `agent.md`，供后续会话判断是否需要重新引导：
-
-```markdown
-## 飞书集成
-
-- **App ID**: cli_xxxxxxxxxxxxxxxx
-- **用途**: 通过飞书 API 实现消息通知、文档自动生成（描述项目实际使用飞书做了什么）
-```
-
-## NestJS 模块设置
-
-### 安装 SDK
-
-```bash
-npm install @larksuiteoapi/node-sdk
-```
-
-### FeishuService 单例
-
-> ⚠️ **凭证写入源码**：全栈框架不支持自定义环境变量，因此 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 必须直接写在源码常量中，**不要改为 `process.env`**。
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import * as lark from '@larksuiteoapi/node-sdk';
-
-const FEISHU_APP_ID = 'cli_xxxx';      // ← 用户提供的真实值
-const FEISHU_APP_SECRET = 'xxxx';      // ← 用户提供的真实值
-
-@Injectable()
-export class FeishuService {
-  private readonly client: lark.Client;
-
-  constructor() {
-    this.client = new lark.Client({
-      appId: FEISHU_APP_ID,
-      appSecret: FEISHU_APP_SECRET,
-      appType: lark.AppType.SelfBuild,
-      domain: lark.Domain.Feishu,
-    });
-  }
-
-  getClient(): lark.Client {
-    return this.client;
-  }
-}
-```
-
-在 Module 中注册为全局 provider：
-
-```typescript
-@Module({
-  providers: [FeishuService],
-  exports: [FeishuService],
-})
-export class FeishuModule {}
-```
-
-## 核心 API 调用模式
-
-### 语义化调用
-
-```typescript
-// 调用模式: client.<domain>.<resource>.<method>({ params, data, path })
-const res = await client.im.message.create({
-  params: { receive_id_type: 'chat_id' },
-  data: {
-    receive_id: 'oc_xxx',
-    content: JSON.stringify({ text: 'hello' }),
-    msg_type: 'text',
-  },
-});
-
-// 检查返回值
-if (res.code !== 0) {
-  throw new Error(`Feishu API error [${res.code}]: ${res.msg}`);
-}
-```
-
-### 分页迭代器
-
-接口名后缀加 `WithIterator` 自动处理 page_token：
-
-```typescript
-for await (const items of await client.contact.user.listWithIterator({
-  params: { department_id: '0', page_size: 50 },
-})) {
-  console.log(items);
-}
-```
-
-## 错误处理与权限诊断
-
-> **排查优先级**：遇到 API 调用失败或配置问题时，先查阅对应 `references/` 文件顶部的开放平台文档链接，获取最新的参数说明、权限要求和错误码解释，再对照下方速查表定位问题。
-
-### 常见错误码
-
-| 错误码 | 含义 | 修复方法 |
-|--------|------|----------|
-| 99991672 | 权限不足 | 开发者后台 → 权限管理 → 申请对应权限 |
-| 99991671 | access_token 无效/过期 | 检查 app_id/app_secret 是否正确 |
-| 99991663 | tenant_access_token 过期 | SDK 自动刷新，检查网络连接 |
-| 230001 | 应用不可见/未安装 | 管理员审核发布应用 |
-| 99991400 | 参数错误 | 检查必填字段和参数类型 |
-| 99991668 | 用户不在通讯录权限范围 | 安全设置 → 通讯录权限范围设为「全部成员」 |
-
-### 权限速查
-
-遇到 `99991672 Permission denied` 时，根据 API 域查找所需权限：
-
-| API 域 | 权限标识 | 说明 |
-|--------|----------|------|
-| `im.message.*` | `im:message:send_as_bot` | 发送消息 |
-| `calendar.calendarEvent.*` | `calendar:calendar` | 日历日程读写 |
-| `vc.room.*` | `vc:room:readonly` | 会议室查询 |
-| `approval.approval.*` | `approval:approval` | 审批信息读写 |
-| `approval.instance.query` | `approval:approval.list:readonly` | 审批实例列表 |
-| `approval.task.*` | `approval:task` | 审批操作（同意/拒绝/转交） |
-| `bitable.app*` | `bitable:app` | 多维表格读写 |
-| `docx.document.*` | `docx:document` | 云文档读写 |
-| `docx.document.convert()` | `docx:document.block:convert` | Markdown 转 Block |
-| `drive.*` | `drive:drive` | 云空间文件/文件夹 |
-| `wiki.space.*` / `wiki.spaceNode.*` | `wiki:wiki` | 知识库读写 |
-| `drive.permissionMember.*` | `drive:permission` | 文档权限管理 |
-| `contact.user.*` | `contact:contact.base:readonly` | 通讯录用户信息 |
-| `contact.department.*` | `contact:department.base:readonly` | 部门信息 |
-| `contact.user.*.employee_id` | `contact:user.employee_id:readonly` | 用户 employee_id |
-| `attendance.userTask.*` | `attendance:task:readonly` | 打卡数据 |
-| `attendance.group.*` | `attendance:rule:readonly` | 考勤规则 |
-| `spark.directory.user.id_convert` | `获取 ID 转换信息` | 妙搭 userId ↔ 飞书 open_id/union_id；nestjs-react-fullstack 项目内优先用 `AuthNPaasService`（见 user-identity skill） |
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| 将凭证改为 process.env 读取 | 全栈框架不支持自定义环境变量，凭证必须写入源码常量 |
-| `content` 传对象而非 JSON 字符串 | `content: JSON.stringify({ text: 'hello' })` |
-| 每次请求都新建 `lark.Client` | NestJS `@Injectable()` 单例模式复用 |
-| `receive_id_type` 与 ID 前缀不匹配 | `oc_` → `chat_id`, `ou_` → `open_id`, `on_` → `union_id` |
-| 未配置通讯录权限范围 | 安全设置 → 通讯录权限范围 → 全部成员 |
-| 应用未发布直接调 API | 创建版本 → 管理员审核 → 发布后才能使用 |
-| 忘记开启机器人能力 | 应用能力 → 添加机器人（发消息必须） |
-| 日期格式搞混 | 日历用 RFC3339 (`2026-01-01T09:00:00+08:00`)，考勤用整数 (`20260101`) |
-| 生成独立可运行的脚本文件 | 所有飞书调用放在 NestJS Service 方法中，由 Controller 调用 |
-

package/steering/nestjs-react-fullstack/skills/feishu/references/approval.md

@@ -1,214 +0,0 @@
-# 审批 (Approval)
-
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/approval-v4/approval-overview.md
-
-使用 `@larksuiteoapi/node-sdk` 在 NestJS 中管理飞书审批流程。
-
-## 所需权限
-
-| 权限标识 | 说明 |
-|----------|------|
-| `approval:approval` | 读写审批信息 |
-| `approval:approval.list:readonly` | 查询审批实例列表 |
-| `approval:task` | 审批人操作（同意/拒绝/转交、查询任务） |
-
-## 获取 Approval Code
-
-飞书不提供「列出所有审批定义」的 API，需从管理后台手动获取：
-
-1. 打开 [飞书审批管理后台（开发者模式）](https://www.feishu.cn/approval/admin/approvalList?devMode=on)
-2. 找到目标审批 → 点击 **编辑**
-3. 从浏览器地址栏复制 `definitionCode=` 后面的值
-   - 示例：`https://www.feishu.cn/approval/admin/edit?definitionCode=48D49517-C979-447E-AD93-4BAE0FBC57EA`
-4. 获取到的 Code 即为 `approval_code`
-
-## 获取审批定义
-
-查看审批表单结构，了解需要填写哪些字段：
-
-```typescript
-const definition = await client.approval.approval.get({
-  path: { approval_code: '48D49517-C979-447E-AD93-4BAE0FBC57EA' },
-});
-// definition.data?.form — 表单控件 JSON 字符串
-// definition.data?.node_list — 审批节点列表
-```
-
-## 创建审批实例
-
-```typescript
-const instance = await client.approval.instance.create({
-  data: {
-    approval_code: '48D49517-C979-447E-AD93-4BAE0FBC57EA',
-    open_id: 'ou_xxx', // 发起人
-    form: JSON.stringify([
-      {
-        id: 'widget001',
-        type: 'input',
-        value: '出差事由：参加客户交流会',
-      },
-      {
-        id: 'widget002',
-        type: 'date',
-        value: '2026-03-01T09:00:00+08:00',
-      },
-    ]),
-    // department_id: 'od_xxx', // 多部门用户需填写
-  },
-});
-const instanceCode = instance.data?.instance_code;
-```
-
-## 获取审批详情
-
-```typescript
-const detail = await client.approval.instance.get({
-  path: { instance_id: instanceCode },
-});
-// detail.data?.status — PENDING / APPROVED / REJECTED / CANCELED
-// detail.data?.form — 表单数据
-// detail.data?.task_list — 任务列表
-// detail.data?.timeline — 审批动态
-```
-
-## 查询审批实例列表
-
-```typescript
-const list = await client.approval.instance.query({
-  data: {
-    approval_code: '48D49517-...',
-    instance_status: 'PENDING', // PENDING / APPROVED / REJECT / RECALL / ALL
-    // user_id: 'ou_xxx', // 按发起人过滤
-    // start_time: '1708300800000', // Unix 毫秒时间戳
-    // end_time: '1708387200000',
-    page_size: 20,
-  },
-});
-```
-
-## 撤回审批
-
-```typescript
-await client.approval.instance.cancel({
-  data: {
-    approval_code: '48D49517-...',
-    instance_code: instanceCode,
-    user_id: 'ou_xxx', // 审批提交人
-  },
-});
-```
-
-> 撤回需要在审批后台对应审批定义中勾选「允许撤销审批中的申请」或「允许撤销 x 天内通过的审批」。
-
-## 查询审批人待办任务
-
-```typescript
-const tasks = await client.approval.task.search({
-  data: {
-    user_id: 'ou_xxx', // 审批人 open_id
-    approval_code: '48D49517-...', // 可选
-    task_status: 'PENDING', // PENDING / APPROVED / REJECTED / TRANSFERRED
-    page_size: 10,
-  },
-  params: { user_id_type: 'open_id' },
-});
-```
-
-也可以通过 `query` 方法查询任务：
-
-```typescript
-const taskQuery = await client.approval.task.query({
-  params: {
-    page_size: 20,
-    // page_token: '...',
-  },
-  data: {
-    topic: 'pending', // pending / approved / rejected
-    user_id: 'ou_xxx',
-  },
-});
-```
-
-## 同意审批
-
-```typescript
-await client.approval.task.approve({
-  data: {
-    approval_code: '48D49517-...',
-    instance_code: instanceCode,
-    user_id: 'ou_xxx', // 审批人
-    task_id: '7605931414537653476',
-    comment: '同意，请注意安全',
-    // form: '...', // 部分审批需要补充表单
-  },
-});
-```
-
-## 拒绝审批
-
-```typescript
-await client.approval.task.reject({
-  data: {
-    approval_code: '48D49517-...',
-    instance_code: instanceCode,
-    user_id: 'ou_xxx',
-    task_id: '7605931414537653476',
-    comment: '时间冲突，建议改期',
-  },
-});
-```
-
-## 转交审批
-
-```typescript
-await client.approval.task.transfer({
-  data: {
-    approval_code: '48D49517-...',
-    instance_code: instanceCode,
-    user_id: 'ou_xxx', // 当前审批人
-    task_id: '7605931414537653476',
-    comment: '转交给主管处理',
-    transfer_user_id: 'ou_yyy', // 转交目标
-  },
-});
-```
-
-## 常见表单控件类型
-
-| 控件类型 | 说明 | value 格式 |
-|----------|------|------------|
-| `input` | 单行文本 | `"文本内容"` |
-| `textarea` | 多行文本 | `"文本内容"` |
-| `number` | 数字 | `123.45` |
-| `date` | 日期 | `"2026-02-12T09:00:00+08:00"` (RFC3339) |
-| `leaveGroup` | 请假控件组 | `{"name":"年假","start":"...","end":"...","interval":2.0}` |
-| `remedyGroupV2` | 补卡控件组 | `[{"date":"2026-02-12","remedy_time":"...","reason":"..."}]` |
-| `tripGroup` | 出差控件组 | `{"schedule":[...],"interval":2.0,"reason":"..."}` |
-| `radioV2` | 单选 | `"选项名称"` |
-| `checkboxV2` | 多选 | `["选项1","选项2"]` |
-| `attachmentV2` | 附件 | 附件 token 列表 |
-
-## 典型工作流
-
-### 发起审批（发起人视角）
-
-1. 获取 approval_code（管理后台或预配置）
-2. `client.approval.approval.get()` → 查看表单结构
-3. 组装 form JSON → `client.approval.instance.create()` 发起审批
-4. `client.approval.instance.get()` → 查询审批状态
-
-### 处理审批（审批人视角）
-
-1. `client.approval.task.search({ data: { user_id, task_status: 'PENDING' } })` → 获取待办
-2. 根据标题/申请人匹配目标任务 → 拿到 `task_id` 和 `instance_code`
-3. `client.approval.task.approve()` 同意 / `reject()` 拒绝 / `transfer()` 转交
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| 想用 API 列出所有审批定义 | 无此 API，从管理后台获取 approval_code |
-| form 传对象而非 JSON 字符串 | `form: JSON.stringify([{id, type, value}])` |
-| 忘记传 `task_id` 执行同意/拒绝 | 先通过 `task.search()` 获取 task_id |
-| 撤回失败 | 检查审批定义是否允许撤回 |
-| `instance_status` 拼写 | `REJECT`（不是 `REJECTED`），`RECALL`（不是 `CANCELED`） |

package/steering/nestjs-react-fullstack/skills/feishu/references/attendance.md

@@ -1,163 +0,0 @@
-# 考勤 (Attendance)
-
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/attendance-v1/overview.md
-
-使用 `@larksuiteoapi/node-sdk` 在 NestJS 中查询飞书考勤数据。
-
-## 所需权限
-
-| 权限标识 | 说明 |
-|----------|------|
-| `attendance:task:readonly` | 导出打卡数据 |
-| `attendance:rule:readonly` | 导出打卡管理规则（查询考勤组时需要） |
-| `contact:user.employee_id:readonly` | 获取用户 employee_id（open_id 转换必需） |
-
-> **重要**：考勤 API 使用 `employee_id` 而非 `open_id`。需先通过通讯录 API 将 `open_id` 转换为 `employee_id`。
-
-## open_id 转 employee_id
-
-```typescript
-// 通过通讯录 API 获取用户的 employee_id
-const user = await client.contact.user.get({
-  path: { user_id: 'ou_xxx' },
-  params: { user_id_type: 'open_id' },
-});
-const employeeId = user.data?.user?.employee_id; // 如 'abd754f7'
-```
-
-## 查询打卡结果
-
-```typescript
-const tasks = await client.attendance.userTask.query({
-  params: { employee_type: 'employee_id' },
-  data: {
-    user_ids: ['abd754f7'], // employee_id 列表，最多 50 个
-    check_date_from: 20260209, // yyyyMMdd 格式整数
-    check_date_to: 20260213,
-  },
-});
-
-// 遍历结果
-for (const task of tasks.data?.user_task_results || []) {
-  console.log(`${task.employee_name} - ${task.day}`);
-  for (const record of task.records || []) {
-    console.log(`  上班: ${record.check_in_result}, 下班: ${record.check_out_result}`);
-  }
-}
-```
-
-### 日期格式
-
-考勤 API 的日期格式是 `yyyyMMdd` **整数**（不是字符串，不是时间戳）：
-
-```typescript
-// 正确
-check_date_from: 20260209
-
-// 错误
-check_date_from: '2026-02-09'     // 不是字符串
-check_date_from: 1739059200        // 不是 Unix 时间戳
-check_date_from: '20260209'        // 不是字符串
-```
-
-### 打卡状态码
-
-| 值 | 含义 |
-|----|------|
-| `Normal` | 正常 |
-| `Late` | 迟到 |
-| `Early` | 早退 |
-| `Lack` | 缺卡 |
-| `Todo` | 未打卡 |
-| `NoNeedCheck` | 无需打卡 |
-
-## 查询补卡记录
-
-```typescript
-const remedys = await client.attendance.userTaskRemedy.query({
-  params: { employee_type: 'employee_id' },
-  data: {
-    user_ids: ['abd754f7'],
-    check_time_from: '1738800000', // Unix 秒时间戳字符串
-    check_time_to: '1739404800',
-    status: 2, // 0=待审批, 1=未通过, 2=已通过, 3=已取消, 4=已撤回
-  },
-});
-```
-
-### 补卡状态码
-
-| 值 | 含义 |
-|----|------|
-| 0 | 待审批 |
-| 1 | 未通过 |
-| 2 | 已通过 |
-| 3 | 已取消 |
-| 4 | 已撤回 |
-
-## 查询考勤组
-
-```typescript
-// group_id 从打卡结果中获取
-const group = await client.attendance.group.get({
-  path: { group_id: '6737202939523236110' },
-  params: { employee_type: 'employee_id' },
-});
-// group.data — { group_name, time_zone, group_type, locations, ... }
-```
-
-### 考勤组类型
-
-| 值 | 含义 |
-|----|------|
-| 0 | 固定班制 |
-| 2 | 排班制 |
-| 3 | 自由班制 |
-
-## 列出考勤组
-
-```typescript
-const groups = await client.attendance.group.list({
-  params: { page_size: 20 },
-});
-```
-
-## 搜索考勤组
-
-```typescript
-const search = await client.attendance.group.search({
-  data: { group_name: '产品部' },
-});
-```
-
-## 典型工作流
-
-### 查看本周考勤
-
-1. **获取 employee_id** → `client.contact.user.get()` 转换 open_id
-2. **查询打卡结果** → `client.attendance.userTask.query({ data: { user_ids, check_date_from, check_date_to } })`
-3. 汇总每天上下班打卡状态
-4. 标记异常（Late/Early/Lack）
-
-### 查看考勤规则
-
-1. **查询打卡结果** → 获取 `group_id`
-2. **查询考勤组** → `client.attendance.group.get({ path: { group_id } })`
-3. 查看打卡地点、考勤时间、补卡策略等配置
-
-### 批量查询团队考勤
-
-1. 获取部门成员 → `client.contact.user.findByDepartment()`
-2. 提取所有成员的 `employee_id`
-3. 分批查询（每批最多 50 人）→ `client.attendance.userTask.query()`
-4. 汇总统计异常情况
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| 用 open_id 调考勤 API | 先转换为 employee_id |
-| 日期格式传字符串或时间戳 | 必须是 yyyyMMdd 整数如 `20260209` |
-| 补卡查询时间传整数 | 补卡时间是 Unix 秒时间戳**字符串** |
-| 一次查超过 50 人 | `user_ids` 最多 50 个，需分批 |
-| 未申请 `contact:user.employee_id:readonly` | open_id 转 employee_id 必需此权限 |