@lark-apaas/coding-steering 0.1.6-alpha.1 → 0.1.6-alpha.10

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

@@ -0,0 +1,163 @@
+# 考勤 (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 必需此权限 |

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

@@ -0,0 +1,309 @@
+# 多维表格 (Bitable)
+
+> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/docs/bitable-v1/bitable-overview.md
+
+使用 `@larksuiteoapi/node-sdk` 在 NestJS 中操作飞书多维表格。
+
+## 所需权限
+
+| 权限标识 | 说明 |
+|----------|------|
+| `bitable:app` | 读写多维表格 |
+| `drive:drive` | 访问云空间（创建/列出多维表格时需要） |
+
+> 对于已有的多维表格，需确保应用已被添加为协作者：云文档右上角「...」→「更多」→「添加文档应用」。
+
+## 获取 app_token
+
+多维表格的 `app_token` 有三种获取方式：
+1. **通过 API 创建** → 响应中包含 `app_token`
+2. **通过 API 列出** → 从文件列表中获取
+3. **从 URL 提取** → 见下方 URL 解析
+
+### URL 解析
+
+多维表格有两种 URL 格式：
+
+| 格式 | URL 示例 | 说明 |
+|------|----------|------|
+| `/base/` | `https://xxx.feishu.cn/base/{app_token}?table=tblXXX` | 直接提取 `app_token` |
+| `/wiki/` | `https://xxx.feishu.cn/wiki/{node_token}?table=tblXXX` | 需先通过 Wiki API 获取 `obj_token` |
+
+```typescript
+// /base/ 格式：直接提取
+const baseUrl = 'https://xxx.feishu.cn/base/ABC123?table=tblXXX';
+const u = new URL(baseUrl);
+const appToken = u.pathname.match(/\/base\/([A-Za-z0-9]+)/)?.[1]; // 'ABC123'
+const tableId = u.searchParams.get('table'); // 'tblXXX'
+
+// /wiki/ 格式：需先获取 obj_token
+const wikiUrl = 'https://xxx.feishu.cn/wiki/XYZ789?table=tblXXX';
+const nodeToken = new URL(wikiUrl).pathname.match(/\/wiki\/([A-Za-z0-9]+)/)?.[1];
+const nodeRes = await client.wiki.space.getNode({ params: { token: nodeToken } });
+const appTokenFromWiki = nodeRes.data?.node?.obj_token; // 这才是真正的 app_token
+```
+
+## 创建多维表格
+
+```typescript
+const res = await client.bitable.app.create({
+  data: {
+    name: '项目跟踪表',
+    // folder_token: 'fldcnxxxxxx', // 可选：目标文件夹
+  },
+});
+const appToken = res.data?.app?.app_token;
+const defaultTableId = res.data?.app?.table_id;
+```
+
+## 获取多维表格信息
+
+```typescript
+const info = await client.bitable.app.get({
+  path: { app_token: appToken },
+});
+```
+
+## 列出数据表
+
+```typescript
+const tables = await client.bitable.appTable.list({
+  path: { app_token: appToken },
+  params: { page_size: 20 },
+});
+// tables.data?.items — [{table_id, name, revision}, ...]
+```
+
+## 创建数据表
+
+```typescript
+const newTable = await client.bitable.appTable.create({
+  path: { app_token: appToken },
+  data: {
+    table: {
+      name: '新数据表',
+      default_view_name: '默认视图',
+      fields: [
+        { field_name: '任务名称', type: 1 }, // 1 = 多行文本
+        { field_name: '状态', type: 3 },      // 3 = 单选
+        { field_name: '截止日期', type: 5 },  // 5 = 日期
+      ],
+    },
+  },
+});
+```
+
+## 列出字段
+
+```typescript
+const fields = await client.bitable.appTableField.list({
+  path: { app_token: appToken, table_id: tableId },
+  params: { page_size: 100 },
+});
+// fields.data?.items — [{field_id, field_name, type, is_primary, property}, ...]
+```
+
+## 查询记录
+
+```typescript
+// 使用 search 方法支持 filter 和 sort
+const records = await client.bitable.appTableRecord.search({
+  path: { app_token: appToken, table_id: tableId },
+  data: {
+    field_names: ['任务名称', '负责人', '状态'],
+    filter: {
+      conjunction: 'and',
+      conditions: [
+        { field_name: '状态', operator: 'is', value: ['进行中'] },
+      ],
+    },
+    sort: [
+      { field_name: '截止日期', desc: false },
+    ],
+    page_size: 20,
+  },
+});
+// records.data?.items — [{record_id, fields: {...}}, ...]
+```
+
+### filter 语法
+
+```typescript
+// conjunction: 'and' | 'or'
+// operator: 'is' | 'isNot' | 'contains' | 'doesNotContain' | 'isEmpty' | 'isNotEmpty' | 'isGreater' | 'isLess'
+{
+  conjunction: 'and',
+  conditions: [
+    { field_name: '状态', operator: 'is', value: ['进行中'] },
+    { field_name: '优先级', operator: 'is', value: ['高'] },
+  ],
+}
+```
+
+## 获取单条记录
+
+```typescript
+const record = await client.bitable.appTableRecord.get({
+  path: { app_token: appToken, table_id: tableId, record_id: 'recXXX' },
+});
+```
+
+## 列出记录（简单查询）
+
+```typescript
+const list = await client.bitable.appTableRecord.list({
+  path: { app_token: appToken, table_id: tableId },
+  params: {
+    page_size: 100,
+    // filter: '...', // URL filter 表达式
+    // sort: '...', // URL sort 表达式
+  },
+});
+```
+
+## 新增记录
+
+```typescript
+const created = await client.bitable.appTableRecord.create({
+  path: { app_token: appToken, table_id: tableId },
+  data: {
+    fields: {
+      '任务名称': '设计数据库表结构',
+      '状态': '待开始',
+      '优先级': '高',
+      '截止日期': 1708300800000, // 毫秒时间戳
+    },
+  },
+});
+const recordId = created.data?.record?.record_id;
+```
+
+## 批量新增记录
+
+```typescript
+await client.bitable.appTableRecord.batchCreate({
+  path: { app_token: appToken, table_id: tableId },
+  data: {
+    records: [
+      { fields: { '任务名称': '任务1', '状态': '待开始' } },
+      { fields: { '任务名称': '任务2', '状态': '待开始' } },
+    ],
+  },
+});
+```
+
+## 更新记录
+
+```typescript
+await client.bitable.appTableRecord.update({
+  path: { app_token: appToken, table_id: tableId, record_id: recordId },
+  data: {
+    fields: {
+      '状态': '已完成',
+      '完成日期': Date.now(), // 毫秒时间戳
+    },
+  },
+});
+```
+
+## 删除记录
+
+```typescript
+// 单条删除
+await client.bitable.appTableRecord.delete({
+  path: { app_token: appToken, table_id: tableId, record_id: 'recXXX' },
+});
+
+// 批量删除
+await client.bitable.appTableRecord.batchDelete({
+  path: { app_token: appToken, table_id: tableId },
+  data: {
+    records: ['recXXX', 'recYYY', 'recZZZ'],
+  },
+});
+```
+
+## 字段 CRUD
+
+### 创建字段
+
+```typescript
+const res = await client.bitable.appTableField.create({
+  path: { app_token: appToken, table_id: tableId },
+  data: {
+    field_name: '优先级',
+    type: 3, // SingleSelect
+    // property: { options: [{name: '高'}, {name: '中'}, {name: '低'}] }, // 可选
+  },
+});
+const fieldId = res.data?.field?.field_id;
+```
+
+### 更新字段
+
+```typescript
+await client.bitable.appTableField.update({
+  path: { app_token: appToken, table_id: tableId, field_id: fieldId },
+  data: {
+    field_name: '新字段名',
+    type: 1, // 字段类型
+  },
+});
+```
+
+### 删除字段
+
+```typescript
+await client.bitable.appTableField.delete({
+  path: { app_token: appToken, table_id: tableId, field_id: fieldId },
+});
+```
+
+> **注意**：主字段（`is_primary: true`）不能删除，只能重命名。
+
+## 新建多维表格清理建议
+
+新建的多维表格会自动创建默认字段（单选、日期、附件）和空行。建议创建后清理：
+1. 删除不需要的默认字段（类型 3/5/17）
+2. 重命名主字段为有意义的名称
+3. 批量删除空的占位行
+
+## 字段类型与写入格式
+
+| 类型编号 | 字段类型 | 写入格式 | 示例 |
+|----------|----------|----------|------|
+| 1 | 多行文本 | string 或 text 对象数组 | `"Hello"` 或 `[{"text":"Hello","type":"text"}]` |
+| 2 | 数字 | number | `2323.23` |
+| 3 | 单选 | string | `"选项1"` |
+| 4 | 多选 | string[] | `["选项1", "选项2"]` |
+| 5 | 日期 | number（毫秒时间戳） | `1690992000000` |
+| 7 | 复选框 | boolean | `true` |
+| 11 | 人员 | object[] | `[{"id": "ou_xxx"}]` |
+| 13 | 电话号码 | string | `"13800138000"` |
+| 15 | 超链接 | object | `{"text": "链接", "link": "https://..."}` |
+| 17 | 附件 | object[] | `[{"file_token": "xxx"}]` |
+| 18 | 单向关联 | string[] | `["recXXX"]` |
+| 19 | 查找引用 | — | 只读，由关联字段自动计算 |
+| 20 | 公式 | — | 只读，由公式自动计算 |
+| 21 | 双向关联 | string[] | `["recXXX"]` |
+| 22 | 地理位置 | object | `{"location": "北京市朝阳区", "pname": "北京市"}` |
+| 23 | 群组 | string[] | `["oc_xxx"]` |
+| 1001 | 创建时间 | — | 只读，系统自动生成 |
+| 1002 | 修改时间 | — | 只读，系统自动生成 |
+| 1003 | 创建人 | — | 只读，系统自动生成 |
+| 1004 | 修改人 | — | 只读，系统自动生成 |
+| 1005 | 自动编号 | — | 只读，系统自动生成 |
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| 应用无法访问已有多维表格 | 需先添加应用为协作者 |
+| 日期字段传 ISO 字符串 | 必须传毫秒时间戳数字 |
+| 人员字段传字符串 | 必须传 `[{id: 'ou_xxx'}]` 数组格式 |
+| 单选/多选传不存在的选项 | 选项会自动创建，但注意拼写一致 |
+| `app_token` 和 `table_id` 搞混 | `app_token` 是多维表格级别，`table_id` 是数据表级别 |
+| 查询用 `list` 不支持复杂筛选 | 使用 `search` 方法支持 filter/sort |
+| `/wiki/` URL 直接当 app_token 用 | Wiki URL 的 token 是 node_token，需先 `wiki.space.getNode()` 获取 `obj_token` |
+| 删除主字段 | 主字段（`is_primary: true`）不能删除，只能重命名 |
+| 写入只读字段（公式/创建时间等） | 类型 19/20/1001-1005 为只读，不能通过 API 写入 |

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

@@ -0,0 +1,190 @@
+# 日历与会议室 (Calendar)
+
+> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/calendar-v4/overview.md
+
+使用 `@larksuiteoapi/node-sdk` 在 NestJS 中管理日程、预约会议室和查询忙闲状态。
+
+## 所需权限
+
+| 权限标识 | 说明 |
+|----------|------|
+| `calendar:calendar` | 读写日历及日程信息 |
+| `vc:room:readonly` | 查询/搜索会议室 |
+| `contact:user.employee_id:readonly` | 获取用户 ID（可选） |
+
+## 创建日程
+
+```typescript
+const res = await client.calendar.calendarEvent.create({
+  path: { calendar_id: 'primary' }, // 'primary' 表示主日历
+  data: {
+    summary: '产品评审会议',
+    description: 'Q1 产品路线图评审',
+    start_time: {
+      timestamp: String(Math.floor(new Date('2026-02-13T14:00:00+08:00').getTime() / 1000)),
+    },
+    end_time: {
+      timestamp: String(Math.floor(new Date('2026-02-13T15:00:00+08:00').getTime() / 1000)),
+    },
+    attendee_ability: 'can_invite_others',
+  },
+});
+const eventId = res.data?.event?.event_id;
+```
+
+## 更新日程
+
+```typescript
+await client.calendar.calendarEvent.patch({
+  path: { calendar_id: 'primary', event_id: eventId },
+  data: {
+    summary: '产品评审会议（更新）',
+    end_time: {
+      timestamp: String(Math.floor(new Date('2026-02-13T15:30:00+08:00').getTime() / 1000)),
+    },
+  },
+});
+```
+
+## 获取日程详情
+
+```typescript
+const detail = await client.calendar.calendarEvent.get({
+  path: { calendar_id: 'primary', event_id: eventId },
+});
+```
+
+## 获取日程列表
+
+```typescript
+const events = await client.calendar.calendarEvent.list({
+  path: { calendar_id: 'primary' },
+  params: {
+    start_time: String(Math.floor(new Date('2026-02-13T00:00:00+08:00').getTime() / 1000)),
+    end_time: String(Math.floor(new Date('2026-02-14T00:00:00+08:00').getTime() / 1000)),
+    page_size: 50,
+  },
+});
+```
+
+## 删除日程
+
+```typescript
+await client.calendar.calendarEvent.delete({
+  path: { calendar_id: 'primary', event_id: eventId },
+});
+```
+
+## 添加参与人
+
+```typescript
+await client.calendar.calendarEventAttendee.create({
+  path: { calendar_id: 'primary', event_id: eventId },
+  data: {
+    attendees: [
+      { type: 'user', user_id: 'ou_xxx1' },
+      { type: 'user', user_id: 'ou_xxx2' },
+      { type: 'resource', room_id: 'omm_xxx' }, // 预约会议室
+    ],
+    need_notification: true,
+  },
+  params: { user_id_type: 'open_id' },
+});
+```
+
+> **会议室预约是异步的**：添加会议室参与人成功不代表预约成功。需后续通过日程参与人列表中会议室的 `rsvp_status` 确认预约状态。
+
+## 获取参与人列表
+
+```typescript
+const attendees = await client.calendar.calendarEventAttendee.list({
+  path: { calendar_id: 'primary', event_id: eventId },
+  params: { user_id_type: 'open_id', page_size: 50 },
+});
+```
+
+## 删除参与人
+
+```typescript
+await client.calendar.calendarEventAttendee.batchDelete({
+  path: { calendar_id: 'primary', event_id: eventId },
+  data: {
+    attendee_ids: ['user_xxx'],
+  },
+});
+```
+
+## 忙闲查询
+
+```typescript
+// 注意：方法名是 batch，不是 list
+const freebusy = await client.calendar.freebusy.batch({
+  data: {
+    time_min: String(Math.floor(new Date('2026-02-13T09:00:00+08:00').getTime() / 1000)),
+    time_max: String(Math.floor(new Date('2026-02-13T18:00:00+08:00').getTime() / 1000)),
+    user_id: { user_id: 'ou_xxx', id_type: 'open_id' },
+  },
+});
+// 返回 freebusy.data?.freebusy_list — 忙碌时间段数组
+```
+
+查询会议室忙闲时，使用 `room_id` 代替 `user_id`：
+
+```typescript
+const roomFreebusy = await client.calendar.freebusy.batch({
+  data: {
+    time_min: '...',
+    time_max: '...',
+    room_id: 'omm_xxx',
+  },
+});
+```
+
+## 会议室列表
+
+```typescript
+const rooms = await client.vc.room.list({
+  params: {
+    page_size: 20,
+    // room_level_id: 'xxx', // 可选：指定层级
+  },
+});
+```
+
+## 搜索会议室
+
+```typescript
+const searchResult = await client.vc.room.search({
+  data: {
+    query: '大会议室',
+  },
+  params: { page_size: 10 },
+});
+```
+
+## 典型工作流
+
+### 预约会议室
+
+1. **搜索会议室** → `client.vc.room.search({ data: { query: '关键词' } })`
+2. **查询忙闲** → `client.calendar.freebusy.batch({ data: { room_id, time_min, time_max } })`
+3. **创建日程** → `client.calendar.calendarEvent.create({ ... })`
+4. **添加会议室** → `client.calendar.calendarEventAttendee.create({ data: { attendees: [{ type: 'resource', room_id }] } })`
+5. **确认状态** → 查看参与人列表中会议室的 `rsvp_status`
+
+### 安排团队会议
+
+1. 分别查询每位成员忙闲 → `client.calendar.freebusy.batch()`
+2. 找到共同空闲时间段
+3. 搜索可用会议室
+4. 创建日程并添加参与人和会议室
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| 时间传 ISO 字符串 | SDK 需要 Unix 秒时间戳字符串 |
+| 忙闲查询用 `freebusy.list` | 正确方法名是 `freebusy.batch` |
+| 会议室查询用 `calendar.*` | 会议室在 `vc.room.*` 域下 |
+| 以为添加会议室立即生效 | 会议室预约是异步的，需查询 `rsvp_status` |
+| 忘记传 `calendar_id` | path 中必须传 `calendar_id`，主日历用 `'primary'` |