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

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

@@ -1,256 +0,0 @@
-# 云文档 (Document)
-
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/docs/docs-overview
-
-使用 `@larksuiteoapi/node-sdk` 在 NestJS 中操作飞书云文档。
-
-## 所需权限
-
-| 权限标识 | 说明 |
-|----------|------|
-| `docx:document` | 读写新版文档 |
-| `docx:document:readonly` | 只读新版文档 |
-| `docx:document.block:convert` | Markdown 转 Block（写入/追加需要） |
-| `drive:drive` | 访问云空间（创建文档到指定文件夹时需要） |
-
-> 对于已有的文档，需确保应用已被添加为协作者：文档右上角「...」→「更多」→「添加文档应用」。
-
-## 从 URL 提取 Token
-
-URL 格式：`https://xxx.feishu.cn/docx/{doc_token}`
-
-```typescript
-const url = 'https://xxx.feishu.cn/docx/ABC123def';
-const docToken = new URL(url).pathname.split('/docx/')[1]; // 'ABC123def'
-```
-
-## 创建文档
-
-```typescript
-const res = await client.docx.document.create({
-  data: {
-    title: '新文档',
-    // folder_token: 'fldcnXXX', // 可选：目标文件夹
-  },
-});
-const docId = res.data?.document?.document_id;
-const docUrl = `https://feishu.cn/docx/${docId}`;
-```
-
-## 读取文档
-
-### 读取工作流
-
-1. **先获取纯文本** — 快速了解文档内容
-2. **检查 hint** — 如果返回中包含 `hint` 字段，说明文档含有表格、图片等结构化内容
-3. **获取 Block 列表** — 需要结构化内容时使用 `documentBlock.list()`
-
-### 读取纯文本
-
-```typescript
-const [contentRes, infoRes] = await Promise.all([
-  client.docx.document.rawContent({ path: { document_id: docToken } }),
-  client.docx.document.get({ path: { document_id: docToken } }),
-]);
-const title = infoRes.data?.document?.title;
-const content = contentRes.data?.content;
-```
-
-### 读取 Block 列表（结构化内容）
-
-```typescript
-const blocksRes = await client.docx.documentBlock.list({
-  path: { document_id: docToken },
-});
-const blocks = blocksRes.data?.items ?? [];
-```
-
-## 写入文档（替换全部内容）
-
-工作流：清空现有内容 → 转换 Markdown → 插入新 Block
-
-```typescript
-// 1. 清空文档内容（保留 Page block）
-const existing = await client.docx.documentBlock.list({
-  path: { document_id: docToken },
-});
-const childIds = existing.data?.items
-  ?.filter(b => b.parent_id === docToken && b.block_type !== 1)
-  .map(b => b.block_id) ?? [];
-
-if (childIds.length > 0) {
-  await client.docx.documentBlockChildren.batchDelete({
-    path: { document_id: docToken, block_id: docToken },
-    data: { start_index: 0, end_index: childIds.length },
-  });
-}
-
-// 2. 转换 Markdown 为 Block
-const convertRes = await client.docx.document.convert({
-  data: { content_type: 'markdown', content: markdownContent },
-});
-const blocks = convertRes.data?.blocks ?? [];
-
-// 3. 插入 Block
-await client.docx.documentBlockChildren.create({
-  path: { document_id: docToken, block_id: docToken },
-  data: { children: blocks },
-});
-```
-
-## 追加内容
-
-与写入相同，但跳过清空步骤：
-
-```typescript
-// 转换 + 插入（不清空）
-const convertRes = await client.docx.document.convert({
-  data: { content_type: 'markdown', content: markdownContent },
-});
-await client.docx.documentBlockChildren.create({
-  path: { document_id: docToken, block_id: docToken },
-  data: { children: convertRes.data?.blocks ?? [] },
-});
-```
-
-## Block 操作
-
-### 获取单个 Block
-
-```typescript
-const res = await client.docx.documentBlock.get({
-  path: { document_id: docToken, block_id: blockId },
-});
-```
-
-### 更新 Block 文本
-
-```typescript
-await client.docx.documentBlock.patch({
-  path: { document_id: docToken, block_id: blockId },
-  data: {
-    update_text_elements: {
-      elements: [{ text_run: { content: '新文本内容' } }],
-    },
-  },
-});
-```
-
-### 删除 Block
-
-```typescript
-// 需要知道 block 在父容器中的 index
-const children = await client.docx.documentBlockChildren.get({
-  path: { document_id: docToken, block_id: parentId },
-});
-const index = children.data?.items?.findIndex(item => item.block_id === blockId);
-
-await client.docx.documentBlockChildren.batchDelete({
-  path: { document_id: docToken, block_id: parentId },
-  data: { start_index: index, end_index: index + 1 },
-});
-```
-
-## 图片上传
-
-```typescript
-import { Readable } from 'stream';
-
-// 1. 上传图片到文档
-const uploadRes = await client.drive.media.uploadAll({
-  data: {
-    file_name: 'image.png',
-    parent_type: 'docx_image',
-    parent_node: blockId, // 图片 Block 的 block_id
-    size: imageBuffer.length,
-    file: Readable.from(imageBuffer) as any,
-  },
-});
-if (uploadRes.code !== 0) {
-  throw new Error(`Image upload failed [${uploadRes.code}]: ${uploadRes.msg}`);
-}
-const fileToken = uploadRes.data?.file_token;
-
-// 2. 替换图片 Block 的内容
-await client.docx.documentBlock.patch({
-  path: { document_id: docToken, block_id: blockId },
-  data: {
-    replace_image: { token: fileToken },
-  },
-});
-```
-
-## Block 类型参考
-
-| block_type | 名称 | 说明 | 可编辑 |
-|------------|------|------|--------|
-| 1 | Page | 文档根节点（包含标题） | 否 |
-| 2 | Text | 纯文本段落 | 是 |
-| 3 | Heading1 | 一级标题 | 是 |
-| 4 | Heading2 | 二级标题 | 是 |
-| 5 | Heading3 | 三级标题 | 是 |
-| 6 | Heading4 | 四级标题 | 是 |
-| 7 | Heading5 | 五级标题 | 是 |
-| 8 | Heading6 | 六级标题 | 是 |
-| 9 | Heading7 | 七级标题 | 是 |
-| 10 | Heading8 | 八级标题 | 是 |
-| 11 | Heading9 | 九级标题 | 是 |
-| 12 | Bullet | 无序列表项 | 是 |
-| 13 | Ordered | 有序列表项 | 是 |
-| 14 | Code | 代码块 | 是 |
-| 15 | Quote | 引用块 | 是 |
-| 16 | Equation | LaTeX 公式 | 部分 |
-| 17 | Todo | 任务/复选框 | 是 |
-| 18 | Bitable | 多维表格嵌入 | 否 |
-| 19 | Callout | 高亮块 | 是 |
-| 20 | ChatCard | 会话卡片嵌入 | 否 |
-| 21 | Diagram | 绘图嵌入 | 否 |
-| 22 | Divider | 分割线 | 否 |
-| 23 | File | 文件附件 | 否 |
-| 24 | Grid | 分栏布局容器 | 否 |
-| 25 | GridColumn | 分栏列 | 否 |
-| 26 | Iframe | 内嵌网页 | 否 |
-| 27 | Image | 图片 | 部分（replace_image） |
-| 28 | ISV | 第三方小组件 | 否 |
-| 29 | MindnoteBlock | 思维导图嵌入 | 否 |
-| 30 | Sheet | 电子表格嵌入 | 否 |
-| 31 | Table | 表格 | 部分（仅读取，无法通过 API 创建） |
-| 32 | TableCell | 表格单元格 | 是 |
-| 33 | View | 视图嵌入 | 否 |
-| 34 | Undefined | 未知类型 | 否 |
-| 35 | QuoteContainer | 引用容器 | 否 |
-| 36 | Task | 飞书任务集成 | 否 |
-| 37 | OKR | OKR 集成 | 否 |
-| 38 | OKRObjective | OKR 目标 | 否 |
-| 39 | OKRKeyResult | OKR 关键结果 | 否 |
-| 40 | OKRProgress | OKR 进展 | 否 |
-| 41 | AddOns | 扩展块 | 否 |
-| 42 | JiraIssue | Jira Issue 嵌入 | 否 |
-| 43 | WikiCatalog | 知识库目录 | 否 |
-| 44 | Board | 画板嵌入 | 否 |
-| 45 | Agenda | 议程块 | 否 |
-| 46 | AgendaItem | 议程项 | 否 |
-| 47 | AgendaItemTitle | 议程项标题 | 否 |
-| 48 | SyncedBlock | 同步块引用 | 否 |
-
-> 可编辑的文本类 block（2-17, 19）通过 `documentBlock.patch()` 的 `update_text_elements` 更新；容器类 block（24, 25, 35）需编辑其子 block。
-
-## Markdown 写入限制
-
-- **表格不支持**：Markdown 中的表格无法通过 `document.convert()` → `documentBlockChildren.create()` 创建（error 1770029）
-- 支持的 Markdown 元素：标题、列表、代码块、引用、链接、图片（`![](url)` 自动上传）、加粗/斜体/删除线
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| 直接用 wiki token 调用 docx API | Wiki 页面需先通过 `wiki.space.getNode()` 获取 `obj_token`，再用 `obj_token` 作为 `doc_token` |
-| 写入时未清空旧内容导致重复 | 写入前先调用 `documentBlockChildren.batchDelete()` 清空 |
-| 删除 Block 传 block_id 而非 index | `batchDelete` 使用 `start_index` 和 `end_index`，非 block_id |
-| 尝试通过 API 创建表格 Block | Table block 无法通过 `documentBlockChildren.create()` 创建 |
-| `document.convert()` 缺少权限 | 需要 `docx:document.block:convert` 权限 |
-| 图片上传 parent_type 填错 | 文档图片必须用 `docx_image`，不是 `doc_image` |
-| 更新文本时覆盖了富文本样式 | `update_text_elements` 会替换整个文本内容，包括样式 |
-| 并发写入同一文档 | 飞书文档不支持并发写入，需串行操作 |
-| 忘记检查 `res.code !== 0` | 所有 API 调用都需检查返回码 |
-| 清空文档时删除了 Page block | `block_type !== 1` 的才能删除，Page block 是根节点 |

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

@@ -1,103 +0,0 @@
-# 云空间 (Drive)
-
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/docs/drive-v1/introduction
-
-使用 `@larksuiteoapi/node-sdk` 在 NestJS 中管理飞书云空间文件和文件夹。
-
-## 所需权限
-
-| 权限标识 | 说明 |
-|----------|------|
-| `drive:drive` | 读写云空间（创建、移动、删除） |
-| `drive:drive:readonly` | 只读云空间（列出、查看） |
-
-## 从 URL 提取 Token
-
-文件夹 URL 格式：`https://xxx.feishu.cn/drive/folder/{folder_token}`
-
-```typescript
-const url = 'https://xxx.feishu.cn/drive/folder/ABC123';
-const folderToken = new URL(url).pathname.split('/drive/folder/')[1]; // 'ABC123'
-```
-
-## 列出文件夹内容
-
-```typescript
-// 列出指定文件夹
-const res = await client.drive.file.list({
-  params: { folder_token: 'fldcnXXX' },
-});
-const files = res.data?.files ?? [];
-// files: [{token, name, type, url, created_time, modified_time, owner_id}, ...]
-
-// 列出根目录（不传 folder_token）
-const rootRes = await client.drive.file.list({
-  params: {},
-});
-```
-
-## 创建文件夹
-
-```typescript
-const res = await client.drive.file.createFolder({
-  data: {
-    name: '新文件夹',
-    folder_token: 'fldcnXXX', // 父文件夹 token
-  },
-});
-const folderToken = res.data?.token;
-const folderUrl = res.data?.url;
-```
-
-## 移动文件
-
-```typescript
-const res = await client.drive.file.move({
-  path: { file_token: 'ABC123' },
-  data: {
-    type: 'docx', // 文件类型
-    folder_token: 'fldcnXXX', // 目标文件夹
-  },
-});
-```
-
-## 删除文件
-
-```typescript
-const res = await client.drive.file.delete({
-  path: { file_token: 'ABC123' },
-  params: {
-    type: 'docx', // 文件类型
-  },
-});
-```
-
-## 文件类型参考
-
-| 类型 | 说明 |
-|------|------|
-| `doc` | 旧版文档 |
-| `docx` | 新版文档 |
-| `sheet` | 电子表格 |
-| `bitable` | 多维表格 |
-| `folder` | 文件夹 |
-| `file` | 上传的文件 |
-| `mindnote` | 思维导图 |
-| `shortcut` | 快捷方式 |
-
-## 机器人根文件夹限制
-
-飞书机器人使用 `tenant_access_token`，没有自己的「我的空间」根文件夹。这意味着：
-
-- 不指定 `folder_token` 创建文件夹会失败（400 错误）
-- 机器人只能访问**已共享给它**的文件和文件夹
-- **解决方案**：用户先手动创建一个文件夹并共享给机器人，机器人就可以在其中创建子文件夹和文件
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| 机器人不指定 folder_token 创建文件夹 | 必须指定一个已共享给机器人的 folder_token |
-| move/delete 时 type 参数搞错 | type 必须与文件实际类型一致 |
-| 用 folder_token 当 file_token | `folder_token` 用于列出目录，`file_token` 用于移动/删除 |
-| 文件不在机器人可访问范围内 | 需先将文件/文件夹共享给机器人应用 |

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

@@ -1,198 +0,0 @@
-# 事件订阅 (Events)
-
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/event-subscription-guide/overview
-
-通过 WebSocket 长连接接收飞书事件推送，无需公网 IP / 域名，无需加解密。
-
-## WebSocket 长连接（推荐）
-
-使用 NestJS `OnModuleInit` 生命周期钩子启动 WebSocket 长连接：
-
-```typescript
-import { Injectable, OnModuleInit } from '@nestjs/common';
-import * as lark from '@larksuiteoapi/node-sdk';
-
-@Injectable()
-export class FeishuEventService implements OnModuleInit {
-  private readonly wsClient: lark.WSClient;
-
-  constructor(private readonly feishuService: FeishuService) {
-    const client = this.feishuService.getClient();
-    this.wsClient = new lark.WSClient({
-      appId: FEISHU_APP_ID,
-      appSecret: FEISHU_APP_SECRET,
-      loggerLevel: lark.LoggerLevel.info,
-    });
-  }
-
-  onModuleInit() {
-    this.wsClient.start({
-      eventDispatcher: new lark.EventDispatcher({}).register({
-        'im.message.receive_v1': async (data) => {
-          // 处理收到的消息事件
-        },
-      }),
-    });
-  }
-}
-```
-
-## 消息卡片回调（card.action.trigger）
-
-用户点击卡片按钮、选择下拉项等交互操作会触发 `card.action.trigger` 回调，通过长连接接收，在 `EventDispatcher.register()` 中注册处理函数即可。
-
-> **前置配置**：开发者后台 → 事件与回调 → 订阅方式 → 选择「**使用长连接接收事件/回调**」（而非 HTTP 回调地址）
-
-```typescript
-import { Injectable, OnModuleInit } from '@nestjs/common';
-import * as lark from '@larksuiteoapi/node-sdk';
-
-@Injectable()
-export class FeishuEventService implements OnModuleInit {
-  private readonly wsClient: lark.WSClient;
-
-  constructor(private readonly feishuService: FeishuService) {
-    this.wsClient = new lark.WSClient({
-      appId: FEISHU_APP_ID,
-      appSecret: FEISHU_APP_SECRET,
-      loggerLevel: lark.LoggerLevel.info,
-    });
-  }
-
-  onModuleInit() {
-    this.wsClient.start({
-      eventDispatcher: new lark.EventDispatcher({}).register({
-        // 普通消息事件
-        'im.message.receive_v1': async (data) => {
-          // 处理收到的消息事件
-        },
-
-        // 消息卡片交互回调
-        'card.action.trigger': async (data) => {
-          const {
-            action,    // 用户触发的交互动作
-            operator,  // 操作者信息
-            context,   // 卡片上下文
-          } = data;
-
-          // action.value      — 交互元素配置的 value（JSON 对象）
-          // action.tag        — 触发的组件类型：'button' | 'select_static' | 'date_picker' 等
-          // action.option     — 下拉选框选中的值（select_static 专用）
-          // action.form_value — 表单容器提交数据（Record<string, string | string[]>）
-          // action.name       — 用户操作的交互组件名称（开发者自定义）
-          // operator.open_id  — 操作者 open_id（直接字段，非嵌套）
-          // operator.user_id  — 操作者 user_id（字符串）
-          // operator.union_id — 操作者 union_id
-          // context.open_message_id   — 卡片消息 ID（可用于 patch 更新）
-          // context.open_chat_id      — 所在会话 ID
-
-          // 返回新卡片内容可直接更新该卡片（返回 undefined 则不更新）
-          // 响应体为 v2 格式：{ toast?, card: { type: 'raw', data: { schema: '2.0', ... } } }
-          if (action.value?.confirm) {
-            return {
-              toast: {
-                type: 'success',
-                content: '操作已完成',
-                i18n: { zh_cn: '操作已完成', en_us: 'Done' },
-              },
-              card: {
-                type: 'raw',
-                data: {
-                  schema: '2.0',
-                  config: { update_multi: true },
-                  header: {
-                    template: 'green',
-                    title: { content: '已确认', tag: 'plain_text' },
-                  },
-                  body: {
-                    direction: 'vertical',
-                    elements: [
-                      { tag: 'markdown', content: '操作已完成 ✅' },
-                    ],
-                  },
-                },
-              },
-            };
-          }
-        },
-      }),
-    });
-  }
-}
-```
-
-### card.action.trigger 事件数据结构
-
-长连接模式下事件为 v2 格式，`EventDispatcher` 解析后将 `header` 和 `event` 字段平铺到 `data` 中：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `action.value` | `Record<string, any>` | 交互元素配置的 value 数据 |
-| `action.tag` | `string` | 组件类型：`button` / `select_static` / `date_picker` 等 |
-| `action.option` | `string?` | 下拉选框选中项（select_static 触发时有值） |
-| `action.timezone` | `string?` | 时区（日期选择器触发时有值） |
-| `action.form_value` | `Record<string, string \| string[]>?` | 表单容器提交数据（form 组件触发时有值） |
-| `action.name` | `string?` | 用户操作的交互组件名称（开发者在组件上自定义） |
-| `operator.open_id` | `string` | 操作者 open_id（直接字段，非嵌套） |
-| `operator.user_id` | `string?` | 操作者 user_id |
-| `operator.union_id` | `string?` | 操作者 union_id |
-| `operator.tenant_key` | `string?` | 操作者所在租户 key |
-| `context.open_message_id` | `string` | 卡片所在消息 ID |
-| `context.open_chat_id` | `string` | 卡片所在会话 ID |
-| `token` | `string` | 回调 token（验签用，长连接模式无需手动验签） |
-| `host` | `string` | 宿主环境，如 `im_message` |
-
-### card.action.trigger 响应体结构（v2 格式）
-
-处理函数 return 的对象会作为响应体直接更新卡片，必须使用 v2 格式：
-
-```json
-{
-  "toast": {
-    "type": "info",
-    "content": "提示内容",
-    "i18n": { "zh_cn": "提示内容", "en_us": "Message" }
-  },
-  "card": {
-    "type": "raw",
-    "data": {
-      "schema": "2.0",
-      "config": { "update_multi": true },
-      "header": {
-        "title": { "tag": "plain_text", "content": "标题" },
-        "template": "blue"
-      },
-      "body": {
-        "direction": "vertical",
-        "elements": [
-          { "tag": "markdown", "content": "卡片内容" }
-        ]
-      }
-    }
-  }
-}
-```
-
-| 字段 | 必需 | 说明 |
-|------|------|------|
-| `toast` | 否 | 在用户侧显示浮层提示；`type` 可选 `info` / `success` / `error` / `warning` |
-| `card` | 否 | 更新后的卡片内容；不返回则卡片保持不变 |
-| `card.type` | 是 | 固定为 `"raw"` |
-| `card.data.schema` | 是 | 固定为 `"2.0"` |
-| `card.data.body.elements` | 是 | 卡片元素列表（嵌套在 `body` 中，非根级） |
-
-> **与旧版区别**：v1 格式直接在根级放 `elements`；v2 格式必须将元素放在 `card.data.body.elements` 中，且外层需要 `card.type: "raw"` 包装。
-
-### 卡片更新方式对比
-
-| 方式 | 说明 |
-|------|------|
-| 处理函数直接 return 卡片 | 即时更新触发交互的卡片（推荐，3 秒内处理完成） |
-| `client.im.message.patch()` | 异步更新，适合耗时操作（需在另一协程/队列中处理） |
-
-## 当前不支持
-
-以下模式需要飞书通过 HTTP 回调应用服务，当前环境暂不支持：
-
-- Webhook 事件订阅（HTTP 模式）— 使用上方 WebSocket 长连接代替
-- HTTP 模式 CardActionHandler — 使用长连接 `card.action.trigger` 代替（见上方）

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

@@ -1,128 +0,0 @@
-# 妙搭与飞书开放平台 — ID 识别与转换
-
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/spark-v1/overview.md
->
-> 飞书用户身份体系官方说明：https://open.larkoffice.com/document/platform-overveiw/basic-concepts/user-identity-introduction/introduction
->
-> **承接 `user-identity` skill 决策树**：如果只需 妙搭 userId → 飞书 user_id（employee_id），在 nestjs-react-fullstack 项目内优先用 `AuthNPaasService`。本文覆盖 `AuthNPaasService` 不支持的场景：需要 `open_id` / `union_id`、或需要任何方向的反查、或不在该模板内的项目。
-
-## ID 识别速查
-
-拿到一个 ID 后，先判断它属于哪个体系：
-
-| ID 来源 | 获取方式 | 格式特征 | 说明 |
-|---------|---------|---------|------|
-| 妙搭 userId | 后端 `req.userContext.userId`、前端 `useCurrentUserProfile().user_id` | 纯数字字符串 | **两者是同一个 ID**（dataloom 底层同源） |
-| 妙搭 tenantId | `req.userContext.tenantId` | 纯数字字符串 | 租户/工作区标识 |
-| 妙搭 appId | `req.userContext.appId` | 纯数字字符串 | 当前应用标识 |
-| 飞书 open_id | 飞书开放平台 API 返回 | `ou_` 开头 | 应用级，同一用户在不同应用中 open_id 不同 |
-| 飞书 union_id | 飞书开放平台 API 返回 | `on_` 开头 | 开发者级，同一开发者下的多个应用中相同 |
-| 飞书 user_id（即 `employee_id`） | 飞书通讯录 API 返回 / `AuthNPaasService` 返回 | 无固定前缀 | 企业级，用户在企业内的身份标识，全企业唯一 |
-
-> 官方定义：`user_id` 也称为 `employee_id`，两者在多数业务场景等价（除飞书招聘）。它**不是**员工工号（`employee_no` 是另一个独立字段）。
->
-> 飞书还有第四种 ID `lark_id`（跨企业全局物理身份），仅用于跨企业场景，应用开发流程中基本不接触，本文不涉及。
-
-## 决策树：我需要转换吗？
-
-```
-拿到的 ID 是什么？
-├─ 妙搭 userId（纯数字）
-│  ├─ nestjs-react-fullstack 项目内要拿飞书 user_id → 用 AuthNPaasService（见 user-identity skill），单向
-│  ├─ 要调飞书开放平台 API 拿 open_id/union_id → 用下方 spark id_convert API
-│  └─ 仅妙搭内部使用 → 直接用，不需要转换
-├─ 飞书 open_id（ou_ 开头）→ 要在妙搭中查用户？
-│  ├─ 是 → 转换为妙搭 userId（用下方 spark id_convert API type 20）
-│  └─ 否（仅飞书 API 使用）→ 直接用
-├─ 飞书 union_id（on_ 开头）→ 要在妙搭中查用户？
-│  ├─ 是 → 转换为妙搭 userId（用下方 spark id_convert API type 21）
-│  └─ 否 → 直接用
-└─ 飞书 user_id（即 employee_id）
-   ├─ 妙搭 userId → 飞书 user_id：nestjs-react-fullstack 项目内用 AuthNPaasService（仅此一种方法）
-   └─ 飞书 user_id → 妙搭 userId：无单步方案，必须两步走（见下方"反向：飞书 user_id → 妙搭 userId"）
-```
-
-### 反向：飞书 user_id → 妙搭 userId（两步走）
-
-`spark id_convert` 不接受 `user_id` 作为输入；`AuthNPaasService` 也没有反向方法。要把飞书 user_id 转回妙搭 userId，必须分两步：
-
-```typescript
-// Step 1: 飞书通讯录 API，用 user_id 查询用户，从响应里读 open_id
-//         需要权限 contact:contact.base:readonly
-const userRes = await client.contact.user.get({
-  path: { user_id: '<飞书 user_id / employee_id>' },
-  params: { user_id_type: 'user_id' },   // ← 告诉接口"我传入的是 user_id 类型"
-});
-if (userRes.code !== 0) throw new Error(`contact.user.get failed: ${userRes.msg}`);
-const openId = userRes.data?.user?.open_id;
-if (!openId) throw new Error('open_id missing in contact.user.get response');
-
-// Step 2: spark id_convert type 20，open_id → 妙搭 userId
-//         需要权限"获取 ID 转换信息"
-type IdConvertResp = { items: { source_id: string; target_id: string }[] };
-const convRes = await client.request<IdConvertResp>({
-  method: 'POST',
-  url: '/open-apis/spark/v1/directory/user/id_convert',
-  data: { id_convert_type: 20, ids: [openId] },
-});
-if (convRes.code !== 0) throw new Error(`id_convert failed: ${convRes.msg}`);
-const miaodaUserId = convRes.data?.items?.[0]?.target_id;
-```
-
-> 批量场景同理：先调通讯录批量接口（`GET /open-apis/contact/v3/users/batch`，参数 `user_ids[]` + `user_id_type=user_id`，可通过 `client.request({ method: 'GET', url: '...', params: {...} })` 直接调）拿一组 `open_id`，再传给 spark id_convert（最多 100 个）。**响应里用 `source_id` 字段匹配回原 user_id**，不要按下标对位，飞书不保证返回顺序与请求一致。
-
-## 转换 API
-
-### 所需权限
-
-| 权限标识 | 说明 |
-|----------|------|
-| `获取 ID 转换信息` | spark 通讯录 ID 转换权限（需在开发者后台申请） |
-
-### 转换类型
-
-| id_convert_type | 方向 |
-|-----------------|------|
-| `10` | 妙搭 userId → 飞书 open_id |
-| `11` | 妙搭 userId → 飞书 union_id |
-| `20` | 飞书 open_id → 妙搭 userId |
-| `21` | 飞书 union_id → 妙搭 userId |
-
-### 调用示例
-
-```typescript
-// 妙搭 userId → 飞书 open_id
-const res = await client.request({
-  method: 'POST',
-  url: '/open-apis/spark/v1/directory/user/id_convert',
-  data: {
-    id_convert_type: 10,
-    ids: ['123456789837364'],  // 妙搭 userId 列表，最多 100 个
-  },
-});
-// res.data.items — [{ source_id: '123456789837364', target_id: 'ou_1234cdjhjfedgfhgdhy3884' }]
-
-// 飞书 open_id → 妙搭 userId
-const res2 = await client.request({
-  method: 'POST',
-  url: '/open-apis/spark/v1/directory/user/id_convert',
-  data: {
-    id_convert_type: 20,
-    ids: ['ou_1234cdjhjfedgfhgdhy3884'],
-  },
-});
-```
-
-> 频率限制 50 次/秒，批量最多 100 个 ID。优先批量调用，避免逐个转换。
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| 把妙搭 userId 当飞书 open_id 传给飞书 API | 两套体系不互通；nestjs-react-fullstack 项目内用 `AuthNPaasService`，其他场景调 spark `id_convert` |
-| 混淆 `req.userContext.userId` 和 `useCurrentUserProfile().user_id` | 同一个 ID，dataloom 同源，前后端获取方式不同而已 |
-| 把 `employee_id` 当作员工工号 | `employee_id` 等价于 `user_id`，是企业内身份标识；工号是另一个独立字段 `employee_no` |
-| 误以为 `AuthNPaasService` 能反查（飞书 user_id → 妙搭 userId） | 只支持 妙搭 userId → 飞书 user_id 单向；反向需要"通讯录 API user_id → open_id"+"spark id_convert type 20 open_id → 妙搭 userId"两步 |
-| 想用飞书 user_id (employee_id) 直接调 spark `id_convert` 反查妙搭 | spark `id_convert` 只支持 open_id (type 20) / union_id (type 21) 反查，不支持 user_id；走两步方案 |
-| 逐个调用 ID 转换接口 | 一次传入多个 ID（最多 100 个），减少请求次数 |
-| 用 `client.spark.*` 语义化调用 | SDK 无内置 spark 模块，需用 `client.request()` 通用方式 |