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

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

@@ -1,90 +0,0 @@
-# 权限管理 (Permission)
-
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/docs/permission/overview
-
-使用 `@larksuiteoapi/node-sdk` 在 NestJS 中管理飞书云文档的协作者权限。
-
-## 所需权限
-
-| 权限标识 | 说明 |
-|----------|------|
-| `drive:permission` | 管理文档/文件的协作者权限 |
-
-> **敏感操作警告**：权限管理涉及文档访问控制，添加/移除协作者会直接影响用户的文档可见性。操作前请确认目标对象和权限级别。
-
-## 列出协作者
-
-```typescript
-const res = await client.drive.permissionMember.list({
-  path: { token: 'ABC123' },
-  params: { type: 'docx' },
-});
-const members = res.data?.items ?? [];
-// members: [{member_type, member_id, perm, name}, ...]
-```
-
-## 添加协作者
-
-```typescript
-const res = await client.drive.permissionMember.create({
-  path: { token: 'ABC123' },
-  params: { type: 'docx', need_notification: false },
-  data: {
-    member_type: 'email',
-    member_id: 'user@example.com',
-    perm: 'edit',
-  },
-});
-```
-
-## 移除协作者
-
-```typescript
-await client.drive.permissionMember.delete({
-  path: { token: 'ABC123', member_id: 'user@example.com' },
-  params: { type: 'docx', member_type: 'email' },
-});
-```
-
-## Token 类型参考
-
-| 类型 | 说明 |
-|------|------|
-| `doc` | 旧版文档 |
-| `docx` | 新版文档 |
-| `sheet` | 电子表格 |
-| `bitable` | 多维表格 |
-| `folder` | 文件夹 |
-| `file` | 上传的文件 |
-| `wiki` | 知识库节点 |
-| `mindnote` | 思维导图 |
-
-## 成员类型参考
-
-| 类型 | 说明 |
-|------|------|
-| `email` | 邮箱地址 |
-| `openid` | 用户 open_id |
-| `userid` | 用户 user_id |
-| `unionid` | 用户 union_id |
-| `openchat` | 群聊 open_id |
-| `opendepartmentid` | 部门 open_id |
-| `groupid` | 用户组 ID |
-| `wikispaceid` | 知识空间 ID |
-
-## 权限级别参考
-
-| 权限值 | 说明 |
-|--------|------|
-| `view` | 仅查看 |
-| `edit` | 可编辑 |
-| `full_access` | 完全访问（可管理权限） |
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| token 类型与文件实际类型不匹配 | `type` 参数必须与文件实际类型一致（docx/sheet/bitable 等） |
-| 用 wiki URL 的 token 直接操作权限 | Wiki 节点需用 `wiki` 类型，或先获取 `obj_token` 用对应类型 |
-| 添加协作者时成员不存在 | 确认 member_id 正确，email 需要是飞书注册邮箱 |
-| 移除自身的 full_access 权限 | 文档至少需要一个管理员，避免移除最后一个 full_access 成员 |

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

@@ -1,164 +0,0 @@
-# 知识库 (Wiki)
-
-> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/docs/wiki-v2/wiki-overview
-
-使用 `@larksuiteoapi/node-sdk` 在 NestJS 中操作飞书知识库。
-
-## 所需权限
-
-| 权限标识 | 说明 |
-|----------|------|
-| `wiki:wiki` | 读写知识库 |
-| `wiki:wiki:readonly` | 只读知识库 |
-
-> 机器人需被添加为知识空间成员才能访问：知识空间 → 设置 → 成员管理 → 添加机器人。
-
-## 从 URL 提取 Token
-
-URL 格式：`https://xxx.feishu.cn/wiki/{token}`
-
-```typescript
-const url = 'https://xxx.feishu.cn/wiki/ABC123def';
-const token = new URL(url).pathname.split('/wiki/')[1]; // 'ABC123def'
-```
-
-## 列出知识空间
-
-```typescript
-const res = await client.wiki.space.list({});
-const spaces = res.data?.items ?? [];
-// spaces: [{space_id, name, description, visibility}, ...]
-```
-
-> 如果返回空列表，说明机器人未被添加到任何知识空间。
-
-## 列出节点
-
-```typescript
-// 列出空间根节点
-const res = await client.wiki.spaceNode.list({
-  path: { space_id: '7xxx' },
-});
-const nodes = res.data?.items ?? [];
-// nodes: [{node_token, obj_token, obj_type, title, has_child}, ...]
-
-// 列出子节点
-const childRes = await client.wiki.spaceNode.list({
-  path: { space_id: '7xxx' },
-  params: { parent_node_token: 'wikcnXXX' },
-});
-```
-
-## 获取节点详情
-
-```typescript
-const res = await client.wiki.space.getNode({
-  params: { token: 'ABC123def' }, // 从 URL 提取的 token
-});
-const node = res.data?.node;
-// node: {node_token, space_id, obj_token, obj_type, title, parent_node_token, has_child, creator}
-```
-
-> **关键**：返回的 `obj_token` 是实际文档/表格的 token，需用它来调用 docx/bitable 等 API。
-
-## 创建节点
-
-```typescript
-const res = await client.wiki.spaceNode.create({
-  path: { space_id: '7xxx' },
-  data: {
-    obj_type: 'docx',              // 节点类型
-    node_type: 'origin',            // 固定值
-    title: '新页面',
-    // parent_node_token: 'wikcnXXX', // 可选：父节点
-  },
-});
-const node = res.data?.node;
-// node: {node_token, obj_token, obj_type, title}
-```
-
-### obj_type 取值
-
-| 值 | 说明 |
-|------|------|
-| `docx` | 新版文档（默认） |
-| `doc` | 旧版文档 |
-| `sheet` | 电子表格 |
-| `bitable` | 多维表格 |
-| `mindnote` | 思维导图 |
-| `file` | 文件 |
-| `slides` | 幻灯片 |
-
-## 移动节点
-
-```typescript
-await client.wiki.spaceNode.move({
-  path: { space_id: '7xxx', node_token: 'wikcnXXX' },
-  data: {
-    target_space_id: '7yyy',         // 目标空间（不传则同空间内移动）
-    target_parent_token: 'wikcnYYY', // 目标父节点
-  },
-});
-```
-
-## 重命名节点
-
-```typescript
-await client.wiki.spaceNode.updateTitle({
-  path: { space_id: '7xxx', node_token: 'wikcnXXX' },
-  data: { title: '新标题' },
-});
-```
-
-## Wiki-Doc 工作流（关键）
-
-知识库页面的内容读写必须通过 docx API，流程：
-
-```typescript
-// 1. 获取节点详情 → 拿到 obj_token
-const nodeRes = await client.wiki.space.getNode({
-  params: { token: wikiToken },
-});
-const objToken = nodeRes.data?.node?.obj_token;
-
-// 2. 用 obj_token 作为 doc_token 读取文档
-const contentRes = await client.docx.document.rawContent({
-  path: { document_id: objToken },
-});
-
-// 3. 用 obj_token 作为 doc_token 写入文档
-const convertRes = await client.docx.document.convert({
-  data: { content_type: 'markdown', content: '# 新内容\n\n正文...' },
-});
-await client.docx.documentBlockChildren.create({
-  path: { document_id: objToken, block_id: objToken },
-  data: { children: convertRes.data?.blocks ?? [] },
-});
-```
-
-> **重要**：不要用 `node_token` 或 URL 中的 `token` 直接调用 docx API，必须用 `getNode()` 返回的 `obj_token`。
-
-## 搜索不可用
-
-Wiki API 不提供搜索功能。获取内容需通过以下方式：
-
-- 通过 `spaceNode.list()` 浏览节点树
-- 通过 `space.getNode()` + URL 中的 token 直接查询
-
-## 知识库访问设置
-
-机器人需要被添加为知识空间成员才能访问：
-
-1. 打开知识空间 → 设置 → 成员管理
-2. 添加机器人应用
-3. 参考：https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| 用 wiki URL 中的 token 直接调用 docx API | 必须先 `getNode()` 获取 `obj_token`，再用 `obj_token` 调用 docx API |
-| 列出空间返回空但实际有内容 | 机器人未被添加为空间成员 |
-| 尝试搜索知识库内容 | Wiki API 不支持搜索，只能通过 `list` 浏览或 `getNode` 查询 |
-| 创建节点忘记传 `node_type: 'origin'` | `node_type` 是必填字段，值固定为 `'origin'` |
-| 混淆 `node_token` 和 `obj_token` | `node_token` 是知识库节点标识，`obj_token` 是实际文档标识 |

package/steering/design-stack/skills/user-identity/SKILL.md

@@ -1,300 +0,0 @@
----
-name: user-identity
-description: "Use when getting current user info/profile, displaying user name/avatar/email, converting miaoda userId to lark_user_id, or reading req.userContext fields (userId/roles/tenantId): useCurrentUserProfile, AuthNPaasService, FeishuID conversion. 触发词：用户身份, 用户信息, 用户资料, 当前用户, userProfile, useCurrentUserProfile, 飞书ID, FeishuID, 飞书用户ID, lark_user_id, 用户ID转换, AuthNPaasService, 用户上下文, userContext, userContext.roles, 用户角色, 当前用户角色, 获取请求者角色, 展示用户, 显示用户, 用户面板, 我是谁, 获取用户"
-steering: true
-steering-topic: user_identity
-match-template-name: design-stack
----
-
-# 用户身份与上下文
-
-本 skill 专注于**用户身份**：ID 体系、`req.userContext` 字段、`useCurrentUserProfile`、妙搭 ↔ 飞书 ID 转换。
-
-**接口认证**（`@NeedLogin()` 装饰器、`AuthNPaasGuard` opt-in 模式、公开接口处理、401）请使用 [`authn-guide`](../authn-guide/SKILL.md) skill。
-
-## 零、ID 体系警告（CRITICAL）
-
-⚠️ "user_id" 这个字面在本项目里指**三个不同的东西**，必须先区分清楚再写代码：
-
-**作为身份 ID 字段名（指代具体某个用户的 ID 值）：**
-
-| 出现位置 | 实际含义 | 体系 |
-|---|---|---|
-| `useCurrentUserProfile().user_id`、`req.userContext.userId` | 妙搭用户 ID（纯数字字符串） | 妙搭 |
-| `useCurrentUserProfile().lark_user_id`、`AuthNPaasService.getCurrentUserLarkUserId()` 返回值 | 飞书 user_id（== `employee_id`，企业内身份，**无固定前缀**） | 飞书 |
-
-**作为 API 参数的取值（不是一个 ID，而是告诉接口"我传入哪种类型的 ID"）：**
-
-| 出现位置 | 实际含义 |
-|---|---|
-| 飞书 OpenAPI 参数 `user_id_type: 'user_id'`（也可取 `'open_id'` / `'union_id'`） | 字符串字面，与上方的飞书 user_id 字段是一致体系但用途不同 |
-
-**严禁**：把 `useCurrentUserProfile().user_id`（妙搭 ID）直接当飞书 ID 传给飞书 API。飞书 ID 必须通过 `lark_user_id` 字段或 `AuthNPaasService` 获取。
-
-`useCurrentUserProfile()` 返回的字段中涉及**两套完全独立的 ID 体系**，严禁混用或互相回退：
-
-| 字段 | 体系 | 格式 | 说明 |
-|------|------|------|------|
-| `user_id` | 妙搭 | 纯数字字符串 | 妙搭平台用户 ID |
-| `lark_user_id` | 飞书 | 字符串 | 飞书 user_id（== employee_id），通过额外异步请求获取 |
-
-> **严禁**：`useCurrentUserProfile()` 返回值里**没有** `open_id`、`feishu_id`、`openId` 字段——飞书 ID 在这个 Hook 里**只通过 `lark_user_id`** 暴露。如果在本 Hook 的消费代码里看到 `userInfo.open_id` 等写法，属于历史错误，必须改成 `lark_user_id`。
->
-> （范围限定：上一条只约束 `useCurrentUserProfile()` 的消费代码。**项目其他场景** —— 例如调 spark `id_convert`、调飞书通讯录 API —— 出现 `open_id` / `union_id` 是正常且必要的，不在禁止之列。）
->
-> **严禁**：当 `lark_user_id` 为空时回退到 `user_id` 展示。两套 ID 含义完全不同，回退会误导用户。正确做法是条件渲染：有值则展示，无值则不展示或展示"未关联飞书账号"。
-
----
-
-## 一、功能决策树
-
-```text
-用户需求
-    │
-    ├─ 接口认证（@NeedLogin / 公开接口 / 401 / 守卫流程）？
-    │   └─ 跳到 `authn-guide` skill
-    │
-    ├─ 需要在服务端读取当前用户 ID / 租户 / 角色等？
-    │   └─ 是 ──→ req.userContext（第二节）
-    │
-    ├─ 需要在前端展示当前用户信息（名称/头像/邮箱）？
-    │   └─ 是 ──→ useCurrentUserProfile()（第三节）
-    │
-    ├─ 需要获取当前用户的飞书 user_id（即 employee_id，企业内身份）？
-    │   ├─ 后端 ──→ AuthNPaasService.getCurrentUserLarkUserId()（第三节）
-    │   └─ 前端 ──→ useCurrentUserProfile().lark_user_id（第三节）
-    │
-    ├─ 需要批量把 妙搭 userId 转成 飞书 **user_id (employee_id，无前缀)** —— 不是 open_id (`ou_`)、不是 union_id (`on_`)？
-    │   └─ 是 ──→ AuthNPaasService.getBatchLarkUserIds()（第三节）
-    │
-    ├─ 需要 飞书 open_id（`ou_` 开头）/ union_id（`on_` 开头）？
-    │   └─ ⚠️ **AuthNPaasService 不产出 open_id/union_id**，只能 user_id
-    │       └─ 跳到 `feishu` skill 的 `references/id-convert.md`（spark id_convert type 10/11）
-    │
-    ├─ 需要把 飞书 open_id / union_id 反查成 妙搭 userId？
-    │   └─ 跳到 `feishu` skill 的 `references/id-convert.md`（spark id_convert type 20/21）
-    │
-    ├─ 需要把 飞书 user_id（employee_id）反查成 妙搭 userId？
-    │   └─ 无单步方案 ──→ `feishu` skill `references/id-convert.md` "反向两步走"
-    │
-    └─ 需要自定义飞书 ID 转换接口？
-        └─ 是 ──→ 注入 AuthNPaasService 编写 Controller（第四节，仅适用于 user_id）
-```
-
-> **相关技能**：接口认证/守卫/401 参见 `authn-guide`；登录/登出/获取用户信息等 Dataloom SDK 操作参见 `client-builtins-user-service`；**"用户能做什么"**（角色/权限点位鉴权）参见 `authz-guide`。本 skill 只解决**"用户是谁"**。
-
----
-
-## 二、用户上下文（req.userContext）
-
-`UserContextMiddleware` 解析 Gateway 注入的 `x-larkgw-suda-webuser` 头，把当前用户上下文挂到 `req.userContext`，所有 Controller 均可通过 `@Req() req: Request` 读取。
-
-> 完整的解析→守卫流程见 `authn-guide` skill 第二节"认证流程"。
-
-### 字段表
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `userId` | `string` | 妙搭用户 ID |
-| `tenantId` | `number` | 租户 ID |
-| `appId` | `string` | 应用 ID |
-| `loginUrl` | `string` | 登录跳转 URL |
-| `userType` | `string` | 用户类型（如 `_employee`） |
-| `env` | `string` | 环境（如 `preview`、`online`） |
-| `userName` | `string` | 用户名 |
-| `userNameI18n` | `{ zh_cn, en_us, ja_jp }` | 多语言用户名 |
-| `isSystemAccount` | `boolean` | 是否系统账号 |
-| `roles` | `string[] \| null` | 用户角色列表。**未开启权限服务或用户无角色时为 `null`** |
-| `baseUrl` | `string` | 网关内部地址 |
-
-### 服务端读取角色示例
-
-`roles` 字段记录当前用户在应用中的角色列表，可在 Controller 业务逻辑中消费（如根据角色返回不同数据）：
-
-```typescript
-import { Controller, Get, Req } from '@nestjs/common';
-import { Request } from 'express';   // ⚠️ Request 类型必须来自 'express'，不要 import 自 'http' / 'undici' 或漏掉 import
-import { TaskService } from './task.service';   // 按项目实际路径 import 业务 Service
-
-// req.userContext 的类型由 @lark-apaas/fullstack-nestjs-core 通过 declare module 'express' 自动注入到 Request，无需手动声明
-@Controller('api/tasks')
-export class TasksController {
-  constructor(private readonly taskService: TaskService) {}
-
-  @Get()
-  async listTasks(@Req() req: Request) {
-    const roles: string[] | null = req.userContext?.roles ?? null;
-    // roles 示例：['text_editor', 'visitor', 'admin']
-    // ⚠️ 未开启权限服务或用户无角色时为 null
-    if (roles?.includes('admin')) {
-      return this.taskService.findAll();
-    }
-    return this.taskService.findByUser(req.userContext?.userId);
-  }
-}
-```
-
-> **注意**：`roles` 在未开启权限服务或用户无角色时为 `null`，使用前必须做空值处理。
-
----
-
-## 三、飞书 ID 转换（FeishuID Converter）
-
-### 核心概念
-
-妙搭平台的用户 ID（`userId`）与飞书用户 ID 是两套独立体系。调用飞书 OpenAPI 时需要传入某种飞书侧 ID（`open_id` / `union_id` / `user_id` 任选其一，具体通过哪个参数指定取决于 API：消息 API 用 `receive_id_type`，多数其他 API 用 `user_id_type`，文档协作者用 `member_id_type`）。
-
-`AuthNPaasService` 暴露的飞书 ID 是 **`user_id`**（即 `employee_id`，飞书企业内的用户标识）这一种，且**只支持 妙搭 userId → 飞书 user_id 单向转换**。
-
-> 如果需要 `open_id` / `union_id`，或者需要"飞书 ID → 妙搭 userId"反向，请改用飞书开放平台 `spark id_convert` 接口，参见 `feishu` skill 的 `references/id-convert.md`。
-
-### 后端 API
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { AuthNPaasService } from '@lark-apaas/fullstack-nestjs-core';
-
-@Injectable()
-export class MyService {
-  constructor(private readonly authnService: AuthNPaasService) {}
-
-  async example() {
-    // 获取当前登录用户的飞书 user_id
-    const larkUserId = await this.authnService.getCurrentUserLarkUserId();
-    // => '<飞书 user_id>' | null
-
-    // 批量转换（最多 100 个）
-    const larkUserIds = await this.authnService.getBatchLarkUserIds(['uid1', 'uid2']);
-    // => ['<飞书 user_id>', null]  顺序与输入对应，失败项为 null
-  }
-}
-```
-
-| 方法 | 签名 | 说明 |
-|------|------|------|
-| `getCurrentUserLarkUserId` | `() → Promise<string \| null>` | 从请求上下文获取当前用户的飞书 ID |
-| `getBatchLarkUserIds` | `(userIds: string[]) → Promise<(string \| null)[]>` | 批量转换，最多 100 个，与输入顺序一一对应 |
-
-### 内置接口
-
-模块自动注册了 `GET /api/authnpaas/lark-user-id`，返回当前登录用户的飞书 ID：
-
-```json
-{ "lark_user_id": "<飞书 user_id>" }
-```
-
-### 前端获取
-
-`useCurrentUserProfile()` Hook 已自动调用上述内置接口，返回值中包含 `lark_user_id` 字段：
-
-> 本节示例只涉及 ID 相关字段（`user_id` / `lark_user_id`）和顺手的 `name`。完整返回值（`name` / `avatar` / `email` / `tenantId` 等）见 `client-builtins-user-service` skill。
-
-```typescript
-import { useCurrentUserProfile } from '@lark-apaas/client-toolkit/hooks/useCurrentUserProfile';
-
-const UserInfoPanel = () => {
-  const userInfo = useCurrentUserProfile();
-
-  if (!userInfo?.user_id) return <div>加载中...</div>;
-
-  return (
-    <div>
-      <p>用户名: {userInfo.name}</p>
-      <p>用户 ID: {userInfo.user_id}</p>
-      {userInfo.lark_user_id && <p>飞书用户 ID: {userInfo.lark_user_id}</p>}
-    </div>
-  );
-};
-```
-
-**注意**：
-- `lark_user_id` 通过额外异步请求获取，可能晚于 `user_id` 等基础字段就绪
-- 请求失败或用户无对应飞书账号时值为 `undefined`，**必须用条件渲染**
-- `useCurrentUserProfile()` 的返回值里**不存在** `open_id`、`feishu_id`、`openId` 字段——在这个 Hook 的消费代码里飞书 ID 唯一字段名是 `lark_user_id`（仅约束本 Hook；项目其他场景调 spark `id_convert` / 通讯录 API 出现 `open_id` 是正常的）
-
----
-
-## 四、自定义飞书 ID 转换接口
-
-当内置接口不满足需求（如需要批量转换），可注入 `AuthNPaasService` 编写自定义 Controller：
-
-```typescript
-import { Controller, Get, Post, Body, HttpCode } from '@nestjs/common';
-import { AuthNPaasService } from '@lark-apaas/fullstack-nestjs-core';
-
-// 生产环境建议加 class-validator 装饰器（如 @IsArray() @IsString({ each: true })
-// @ArrayMaxSize(100)）并启用全局 ValidationPipe；本示例聚焦 AuthNPaas 用法，省略校验
-class BatchConvertDto {
-  userIds!: string[];
-}
-
-@Controller('api/feishu-id')
-export class FeishuIdController {
-  constructor(private readonly authnService: AuthNPaasService) {}
-
-  @Get('current')
-  async getCurrent() {
-    const larkUserId = await this.authnService.getCurrentUserLarkUserId();
-    return { larkUserId };
-  }
-
-  @Post('batch')
-  @HttpCode(200)
-  async batchConvert(@Body() dto: BatchConvertDto) {
-    const larkUserIds = await this.authnService.getBatchLarkUserIds(dto.userIds);
-    return { larkUserIds };
-  }
-}
-```
-
-前端调用示例：
-
-```typescript
-// 获取当前用户飞书 ID
-const { larkUserId } = await request<{ larkUserId: string | null }>({
-  url: '/api/feishu-id/current',
-  method: 'GET',
-});
-
-// 批量转换
-const { larkUserIds } = await request<{ larkUserIds: (string | null)[] }>({
-  url: '/api/feishu-id/batch',
-  method: 'POST',
-  data: { userIds: ['uid1', 'uid2', 'uid3'] },
-});
-```
-
----
-
-## 五、禁止行为清单
-
-| 禁止行为 | 正确做法 |
-|---------|---------|
-| 在 `useCurrentUserProfile()` 消费代码里使用 `open_id`、`feishu_id`、`openId` 等字段名 | `useCurrentUserProfile()` 中飞书 ID 的**唯一字段名**是 `lark_user_id`（限本 Hook；调 spark `id_convert` / 通讯录 API 出现 `open_id` 正常） |
-| `lark_user_id` 为空时回退到 `user_id` 展示 | 两套 ID 体系完全不同，严禁互相回退。无值时不展示或展示"未关联飞书账号" |
-| 前端直接展示 `lark_user_id` 而不处理空值 | `lark_user_id` 可能为 `undefined`（加载中/获取失败/无飞书账号），必须用条件渲染 |
-| 用 `if (!userInfo)` 判断加载状态 | 初始值为空对象（truthy），必须用 `if (!userInfo?.user_id)` |
-| 手动实例化 `AuthNPaasService` | 通过 NestJS 依赖注入获取：`constructor(private readonly authnService: AuthNPaasService)` |
-| 单独注册 `AuthNPaasModule.forRoot()` | 已通过 `PlatformModule.forRoot()` 自动注册，无需手动导入 |
-| 自行调用平台 `/v1/app/{appId}/account/user/convert` 接口 | 必须使用 `AuthNPaasService` 的方法，内置错误处理和可观测性 |
-| `getBatchLarkUserIds` 传入超过 100 个 ID | 分批调用，每批最多 100 个 |
-| 在前端自行封装飞书 ID 转换请求 | 使用 `useCurrentUserProfile()` 获取当前用户飞书 ID；批量转换通过后端接口 |
-
----
-
-## 六、常见问题
-
-> 接口 401 / 登录跳转相关问题见 `authn-guide` skill 第四节"常见问题"。
-
-### 飞书 ID 返回 null
-
-1. 确认用户已登录（`req.userContext.userId` 存在）
-2. 确认 `appId` 在请求上下文中存在
-3. 检查平台转换接口是否正常（查看后端日志中 `[batchConvertUserIds]` 相关输出）
-4. 部分用户可能无对应飞书账号，此时转换结果为 null 是预期行为
-
-### 前端 lark_user_id 一直为 undefined
-
-1. 确认后端 `AuthNPaasModule` 已注册（内置接口 `/api/authnpaas/lark-user-id` 可访问）
-2. 检查浏览器开发者工具中该接口的请求和响应
-3. `lark_user_id` 异步加载，确保组件正确处理了加载态