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

package/steering/design-stack/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/design-stack/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 必需此权限 |

package/steering/design-stack/skills/feishu/references/bitable.md

@@ -1,309 +0,0 @@
-# 多维表格 (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 写入 |