@lark-apaas/coding-miaoda-sandbox-skills 0.1.29 → 0.1.30

package/miaoda/feishu/references/id-convert.md

@@ -4,7 +4,7 @@
 >
 > 飞书用户身份体系官方说明：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`（任一方向）、或不在该模板内的项目。**`employee_id` ↔ 妙搭 userId 双向**在模板内一律用 `AuthNPaasService`。
+> **承接 `user-identity` skill 决策树**：如果只需 妙搭 userId → 飞书 user_id（employee_id），在 nestjs-react-fullstack 项目内优先用 `AuthNPaasService`。本文只覆盖**不在该模板内**的项目。模板内 **`employee_id` / LarkID / open_id / union_id ↔ 妙搭 userId 双向**一律用 `AuthNPaasService`（open_id / union_id 用 `getBatchOpenIds` / `getBatchUnionIds` / `getBatchMiaodaUserIdsByOpenIds` / `getBatchMiaodaUserIdsByUnionIds`，`feishuClientId` 传 open_id 所属飞书应用 App ID），不要手写 spark `id_convert`。
 
 ## ID 识别速查
 
@@ -21,7 +21,7 @@
 
 > 官方定义：`user_id` 也称为 `employee_id`，两者在多数业务场景等价（除飞书招聘）。它**不是**员工工号（`employee_no` 是另一个独立字段）。
 >
-> 飞书还有第四种 ID `lark_id`（跨企业全局物理身份），仅用于跨企业场景，应用开发流程中基本不接触，本文不涉及。
+> 飞书还有第四种 ID `lark_id`（LarkID，全局物理身份，纯数字），飞书 OpenAPI 不认。LarkID ↔ 妙搭 userId 在模板内用 `AuthNPaasService.getBatchMiaodaUserIdsByLarkIds` / `getBatchLarkIds`（见 `user-identity`），本文不涉及。
 
 ## 决策树：我需要转换吗？
 
@@ -29,13 +29,13 @@
 拿到的 ID 是什么？
 ├─ 妙搭 userId（纯数字）
 │  ├─ nestjs-react-fullstack 项目内要拿飞书 user_id → 用 AuthNPaasService（见 user-identity skill），双向均可
-│  ├─ 要调飞书开放平台 API 拿 open_id/union_id → 用下方 spark id_convert API
+│  ├─ 要调飞书开放平台 API 拿 open_id/union_id → 模板内 AuthNPaasService.getBatchOpenIds / getBatchUnionIds；模板外用下方 spark id_convert API
 │  └─ 仅妙搭内部使用 → 直接用，不需要转换
 ├─ 飞书 open_id（ou_ 开头）→ 要在妙搭中查用户？
-│  ├─ 是 → 转换为妙搭 userId（用下方 spark id_convert API type 20）
+│  ├─ 是 → 模板内 AuthNPaasService.getBatchMiaodaUserIdsByOpenIds；模板外 spark id_convert type 20
 │  └─ 否（仅飞书 API 使用）→ 直接用
 ├─ 飞书 union_id（on_ 开头）→ 要在妙搭中查用户？
-│  ├─ 是 → 转换为妙搭 userId（用下方 spark id_convert API type 21）
+│  ├─ 是 → 模板内 AuthNPaasService.getBatchMiaodaUserIdsByUnionIds；模板外 spark id_convert type 21
 │  └─ 否 → 直接用
 └─ 飞书 user_id（即 employee_id）
    ├─ 妙搭 userId → 飞书 user_id：nestjs-react-fullstack 项目内用 AuthNPaasService（仅此一种方法）
@@ -121,7 +121,7 @@ const res2 = await client.request({
 
 | 错误 | 正确做法 |
 |------|----------|
-| 把妙搭 userId 当飞书 open_id 传给飞书 API | 两套体系不互通；nestjs-react-fullstack 项目内用 `AuthNPaasService`，其他场景调 spark `id_convert` |
+| 把妙搭 userId 当飞书 open_id 传给飞书 API | 两套体系不互通；nestjs-react-fullstack 项目内用 `AuthNPaasService.getBatchOpenIds`（`feishuClientId` 传调 API 用的那个飞书应用 App ID），其他场景调 spark `id_convert` |
 | 混淆 `req.userContext.userId` 和 `useCurrentUserProfile().user_id` | 同一个 ID，dataloom 同源，前后端获取方式不同而已 |
 | 把 `employee_id` 当作员工工号 | `employee_id` 等价于 `user_id`，是企业内身份标识；工号是另一个独立字段 `employee_no` |
 | 反查 employee_id → 妙搭 userId 时还手写两步 | 模板内直接用 `AuthNPaasService.getBatchMiaodaUserIds()` 一步；仅模板外 / open_id 场景才两步 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-miaoda-sandbox-skills",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "description": "Miaoda 合并沙箱 skills 包（包含原 miaoda-skills 的 miaoda / miaoda-modern / miaoda-design / shared 四条业务线）；发布公网 npm，随沙箱运行时经 update-skills 同步到 .agent/skills/",
   "type": "module",
   "files": [