@lark-apaas/coding-steering 0.1.6-alpha.3 → 0.1.6-alpha.5

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'` |

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

@@ -0,0 +1,160 @@
+# 通讯录 (Contacts)
+
+> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/contact-v3/resources.md
+
+使用 `@larksuiteoapi/node-sdk` 在 NestJS 中查询飞书通讯录用户和部门信息。
+
+## 所需权限
+
+| 权限标识 | 说明 |
+|----------|------|
+| `contact:contact.base:readonly` | 读取通讯录基本信息 |
+| `contact:user.base:readonly` | 获取用户基础信息 |
+| `contact:department.base:readonly` | 获取部门基础信息 |
+| `contact:user.employee_id:readonly` | 获取用户 employee_id（可选） |
+
+> **通讯录权限范围**：必须在安全设置中配置，否则 API 只能查到权限范围内的用户/部门。建议设为「全部成员」。
+
+## 获取用户信息
+
+```typescript
+const user = await client.contact.user.get({
+  path: { user_id: 'ou_xxx' },
+  params: { user_id_type: 'open_id' },
+});
+// user.data?.user — { name, en_name, email, mobile, department_ids, status, ... }
+```
+
+### 用户 ID 类型说明
+
+| user_id_type | 说明 | 示例 |
+|--------------|------|------|
+| `open_id` | 应用级唯一标识 | `ou_xxx`（默认） |
+| `union_id` | 跨应用统一标识 | `on_xxx` |
+| `user_id` | 企业内用户 ID | 无固定前缀 |
+
+## 列出部门下的用户
+
+```typescript
+const users = await client.contact.user.findByDepartment({
+  params: {
+    department_id: 'od_xxx',
+    page_size: 50,
+    department_id_type: 'open_department_id',
+    user_id_type: 'open_id',
+  },
+});
+// users.data?.items — [{user_id, name, email, ...}, ...]
+// users.data?.has_more, users.data?.page_token — 用于分页
+```
+
+### 分页遍历所有成员
+
+```typescript
+for await (const items of client.contact.user.listWithIterator({
+  params: {
+    department_id: 'od_xxx',
+    page_size: 50,
+    department_id_type: 'open_department_id',
+    user_id_type: 'open_id',
+  },
+})) {
+  for (const user of items?.items || []) {
+    console.log(user.name, user.open_id);
+  }
+}
+```
+
+## 搜索用户
+
+```typescript
+const searchResult = await client.contact.user.search({
+  data: { query: '张三' },
+  params: {
+    user_id_type: 'open_id',
+    page_size: 20,
+  },
+});
+// searchResult.data?.items — 匹配的用户列表
+```
+
+> 搜索用户需要 `user_access_token`（用户授权），不支持 `tenant_access_token`。如果只有应用凭证，使用 `findByDepartment` 遍历 + 本地过滤替代。
+
+## 获取部门信息
+
+```typescript
+const dept = await client.contact.department.get({
+  path: { department_id: 'od_xxx' },
+  params: { department_id_type: 'open_department_id' },
+});
+// dept.data?.department — { name, parent_department_id, leader_user_id, member_count, ... }
+```
+
+## 列出子部门
+
+```typescript
+const children = await client.contact.department.children({
+  path: { department_id: 'od_xxx' },
+  params: {
+    department_id_type: 'open_department_id',
+    page_size: 50,
+  },
+});
+// children.data?.items — [{department_id, name, member_count, ...}, ...]
+```
+
+## 搜索部门
+
+```typescript
+const deptSearch = await client.contact.department.search({
+  data: { query: '产品' },
+  params: {
+    department_id_type: 'open_department_id',
+    page_size: 20,
+  },
+});
+```
+
+> 搜索部门同样需要 `user_access_token`。应用凭证可用 `department.children()` 遍历代替。
+
+## 列出所有部门（从根开始）
+
+```typescript
+const rootDepts = await client.contact.department.list({
+  params: {
+    parent_department_id: '0', // 0 表示根部门
+    page_size: 50,
+    department_id_type: 'open_department_id',
+  },
+});
+```
+
+## 典型工作流
+
+### 查找某部门所有成员
+
+1. **搜索部门** → `client.contact.department.search({ data: { query: '市场部' } })`
+   - 或遍历子部门 → `client.contact.department.children()`
+2. **获取部门成员** → `client.contact.user.findByDepartment({ params: { department_id } })`
+
+### 查找用户所在部门
+
+1. **获取用户信息** → `client.contact.user.get({ path: { user_id } })`
+2. 从返回的 `department_ids` 获取部门 ID
+3. **获取部门详情** → `client.contact.department.get({ path: { department_id } })`
+
+### 遍历整个组织架构
+
+1. 从根部门开始 → `client.contact.department.list({ params: { parent_department_id: '0' } })`
+2. 递归获取子部门 → `client.contact.department.children()`
+3. 获取每个部门成员 → `client.contact.user.findByDepartment()`
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| 未配置通讯录权限范围 | 安全设置 → 通讯录权限范围 → 全部成员 |
+| 用 `tenant_access_token` 搜索用户 | `user.search()` 需 `user_access_token`，否则用 `findByDepartment` |
+| 部门 ID 类型不匹配 | `od_` 开头用 `open_department_id`，纯数字用 `department_id` |
+| 忘记传 `user_id_type` 参数 | 不传默认 `open_id`，注意和实际传入的 ID 类型一致 |
+| 分页获取不完整 | 检查 `has_more`，使用 `listWithIterator` 自动分页 |