@lark-apaas/coding-steering 0.1.16 → 0.1.17-beta.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.16",
+  "version": "0.1.17-beta.0",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [
     "steering"
   ],
   "scripts": {
-    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**'"
+    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
   },
   "devDependencies": {
     "markdownlint-cli": "^0.47.0"

package/steering/nestjs-react-fullstack/skills/client-builtins-user-service/SKILL.md

@@ -13,27 +13,20 @@ match-template-name: nestjs-react-fullstack
 项目通过 `authClient`（来自 `@lark-apaas/client-toolkit/auth`）提供用户信息与鉴权服务，用于用户登录、登出、获取用户信息等身份认证相关功能。
 
 > **边界说明**：`authClient.session` 仅用于用户登录/登出/获取用户信息等鉴权操作。**插件调用（capability）不属于账户 SDK**，须使用独立的 `capabilityClient`（参见 plugin-guide）。
+>
+> **运行时边界**：本 skill 所有能力（`authClient`、`useCurrentUserProfile`、UserSelect/UserDisplay 等）仅限前端代码使用，**严禁在 `server/**` 中 import**。服务端获取用户身份用 `req.userContext` / `AuthNPaasService`（见 `user-identity` skill），完整边界规则见 coding-guide。
+
+## 怎么选（决策指引）
+
+- **React 组件内展示当前用户**（名称/头像/邮箱/飞书 ID）→ 用 `useCurrentUserProfile()`（见下文），不要手动调 `getUserInfo`
+- **登录/登出/跳转用户详情页，或非 React 上下文取用户信息** → `authClient.session.*`（本节）
+- **选人/选部门/展示任意用户** → UserSelect / DepartmentSelect / UserDisplay 组件（见下文）
 
 ## 统一响应结构
 
-### 响应类型定义
+所有 `authClient.session.*` 接口返回统一的 `DataloomServiceResponse<T>` 结构。在非浏览器环境调用会返回失败结构（`status: 400`，`error.message: 'Incompatible runtime environment'`）。
 
 ```typescript
-/**
- * 统一结果返回结构
- * 在非浏览器环境调用时返回示例：
- * {
- *   data: null,
- *   error: {
- *     code: 400,
- *     message: 'Incompatible runtime environment',
- *     hint: 'Please check if the current environment is browser.',
- *     details: 'This method can only be invoked in browser environment.',
- *   },
- *   status: 400,
- *   statusText: 'Bad Request',
- * }
- */
 interface DataloomServiceBase {
   status: number;
   statusText: string;
@@ -64,202 +57,32 @@ import { authClient } from "@lark-apaas/client-toolkit/auth";
 // authClient 是 SDK 内置的 singleton，零参可用，不需要异步初始化
 ```
 
-## 鉴权服务接口
-
-#### 1. 登录跳转接口 (redirectToLogin)
-
-##### 用途
+## 接口速查表
 
-跳转至 Dataloom 登录页面，适用于：用户身份认证、单点登录、权限验证
+| 方法                                      | 入参                           | 成功时 data 类型           | 说明                                           |
+| ----------------------------------------- | ------------------------------ | -------------------------- | ---------------------------------------------- |
+| `session.redirectToLogin(options?)`       | `SignInRedirectionOptions`     | `'success'`                | 跳转至 Dataloom 登录页（身份认证/单点登录）    |
+| `session.signOut()`                       | 无                             | `null`（异步）             | 退出登录，删除 cookie 中的登录态               |
+| `session.navigateToUserProfile(options?)` | `NavigateToUserProfileOptions` | `'success'`                | 跳转至当前登录用户详情页（头像/姓名点击进入）  |
+| `session.getUserInfo()`                   | 无                             | `UserInfoResponse`（异步） | 获取当前登录用户信息，未登录返回 `status: 401` |
 
-##### 适用场景
-
-需要用户进行身份认证的场景
-
-##### 入参说明
+### 入参类型定义
 
 ```typescript
 interface SignInRedirectionOptions {
-  /**
-   * 选填，登录成功后跳转回的页面。省略会默认用调用接口时页面的url。
-   */
+  /** 选填，登录成功后跳转回的页面。省略默认用当前页面 URL */
   returnUrl?: string;
-  /**
-   * 选填，是否在新浏览器tab上打开登录页。默认为false
-   */
+  /** 选填，是否在新浏览器 tab 打开登录页。默认 false */
   newTab?: boolean;
 }
-```
-
-| 属性名      | 类型      | 必填 | 默认值      | 说明                           |
-| ----------- | --------- | ---- | ----------- | ------------------------------ |
-| `returnUrl` | `string`  | ❌   | 当前页面URL | 登录成功后跳转回的页面         |
-| `newTab`    | `boolean` | ❌   | `false`     | 是否在新浏览器标签页打开登录页 |
-
-##### 出参说明
-
-| 字段名       | 类型        | 说明                   |
-| ------------ | ----------- | ---------------------- |
-| `data`       | `'success'` | 成功标识               |
-| `error`      | `null`      | 错误信息，成功时为null |
-| `status`     | `200`       | HTTP状态码             |
-| `statusText` | `'OK'`      | HTTP状态文本           |
-
-##### 使用示例
-
-```typescript
-/**
- * 跳转至dataloom登录页
- * @param {string} brand - 品牌id 例如：妙搭为 1.
- * @param {string} appId - 运行态应用的id，由dataloom authn 服务下发。
- * @return 成功返回示例：
- * {
- *   data: 'success',
- *   error: null,
- *   status: 200,
- *   statusText: 'OK',
- *  }
- */
-const res: DataloomServiceResponse<'success'> = authClient
-  .session
-  .redirectToLogin(options: SignInRedirectionOptions);
-
-// 基本使用
-const loginResult = authClient
-  .session
-  .redirectToLogin();
-
-// 带参数使用
-const loginResult = authClient
-  .session
-  .redirectToLogin({
-    returnUrl: 'https://example.com/dashboard',
-    newTab: true
-  });
-```
-
-#### 2. 退出登录接口 (signOut)
-
-##### 用途
-
-退出登录，删除cookie中的登录态，适用于：用户主动登出、会话清理、安全退出
-
-##### 适用场景
-
-需要清除用户登录状态的场景
-
-##### 入参说明
-
-无需传入参数
-
-##### 出参说明
-
-| 字段名       | 类型   | 说明                   |
-| ------------ | ------ | ---------------------- |
-| `data`       | `null` | 数据为空               |
-| `error`      | `null` | 错误信息，成功时为null |
-| `status`     | `200`  | HTTP状态码             |
-| `statusText` | `'OK'` | HTTP状态文本           |
-
-##### 使用示例
-
-```typescript
-/**
- * 退出登录，删除cookie中的登陆态
- * @return 成功返回示例：
- * {
- *   data: null,
- *   error: null,
- *   status: 200,
- *   statusText: 'OK',
- *  }
- */
-const res: Promise<DataloomServiceResponse<null>> = await authClient.session.signOut();
-
-// 使用示例
-import { logger } from "@lark-apaas/client-toolkit/logger";
-
-try {
-  const result = await authClient.session.signOut();
-
-  if (result.error) {
-    logger.error("退出登录失败:", result.error.message);
-  } else {
-    logger.info("退出登录成功");
-    // 跳转到登录页或首页
-    authClient.session.redirectToLogin();
-  }
-} catch (error) {
-  logger.error("退出登录异常:", error);
-}
-```
-
-#### 3. 跳转用户详情页接口 (navigateToUserProfile)
-
-##### 用途
-
-跳转至当前登录用户的详情页，适用于：查看个人资料、从用户头像/姓名点击进入详情页面
-
-##### 适用场景
-
-需要在应用中快速打开用户详情页面的场景
 
-##### 入参说明
-
-```typescript
 interface NavigateToUserProfileOptions {
-  /**
-   * 选填，是否在新浏览器tab上打开详情页。默认为false
-   */
+  /** 选填，是否在新浏览器 tab 打开详情页。默认 false */
   newTab?: boolean;
 }
 ```
 
-| 属性名   | 类型      | 必填 | 默认值  | 说明                           |
-| -------- | --------- | ---- | ------- | ------------------------------ |
-| `newTab` | `boolean` | ❌   | `false` | 是否在新浏览器标签页打开详情页 |
-
-##### 出参说明
-
-| 字段名       | 类型        | 说明                   |
-| ------------ | ----------- | ---------------------- |
-| `data`       | `'success'` | 成功标识               |
-| `error`      | `null`      | 错误信息，成功时为null |
-| `status`     | `200`       | HTTP状态码             |
-| `statusText` | `'OK'`      | HTTP状态文本           |
-
-##### 使用示例
-
-```typescript
-/**
- * 跳转至用户详情页
- * @return 成功返回示例：
- * {
- *   data: 'success',
- *   error: null,
- *   status: 200,
- *   statusText: 'OK',
- * }
- */
-const res: DataloomServiceResponse<"success"> = authClient.session.navigateToUserProfile();
-
-// 在新标签页打开
-const resNewTab = authClient.session.navigateToUserProfile({ newTab: true });
-```
-
-## 用户信息服务
-
-#### 4. 获取用户信息接口 (getUserInfo)
-
-##### 用途
-
-根据当前登录态获取已登录的用户信息，适用于：用户资料展示、权限判断、个性化配置
-
-##### 适用场景
-
-需要获取当前登录用户详细信息的场景
-
-##### 数据类型定义
+### getUserInfo 返回类型定义
 
 ```typescript
 interface I18n {
@@ -291,75 +114,39 @@ interface UserInfoResponse {
 }
 ```
 
-##### 入参说明
-
-无需传入参数
-
-##### 出参说明
-
-| 字段名                        | 类型           | 说明                   |
-| ----------------------------- | -------------- | ---------------------- |
-| `data.user_info`              | `UserBaseInfo` | 用户基本信息对象       |
-| `data.user_info.user_id`      | `number`       | 用户唯一标识符         |
-| `data.user_info.name`         | `I18ns`        | 用户名称（支持多语言） |
-| `data.user_info.avatar`       | `Avatar`       | 用户头像信息           |
-| `data.user_info.email`        | `string`       | 用户邮箱地址           |
-| `data.user_info.phone_number` | `string`       | 用户手机号码           |
-| `data.user_info.tenant_name`  | `string`       | 租户名称               |
-| `error`                       | `null`         | 错误信息，成功时为null |
-
-##### 使用示例
+### 综合示例
 
 ```typescript
-/**
- * 根据当前登陆态获取已登录的用户信息。
- * @param {string} brand - 品牌id 例如：妙搭为 1.
- * @param {string} appId - 运行态应用的id，由dataloom authn 服务下发。
- * @return
- */
-const res: Promise<DataloomServiceResponse<UserInfoResponse>> = await authClient.session.getUserInfo();
-
-// 使用示例
+import { authClient } from "@lark-apaas/client-toolkit/auth";
 import { logger } from "@lark-apaas/client-toolkit/logger";
 
-try {
-  const result = await authClient.session.getUserInfo();
-
-  if (result.error) {
-    logger.error("获取用户信息失败:", result.error.message);
-    // 可能需要重新登录
-    if (result.status === 401) {
-      // 跳转到登录页
-      authClient.session.redirectToLogin();
-    }
-  } else if (result.data?.user_info) {
-    const userInfo = result.data.user_info;
-    logger.info("用户信息:", userInfo);
-
-    // 显示用户名
-    const userName = userInfo.name?.[0]?.text || "未知用户";
-    document.getElementById("username").textContent = userName;
-
-    // 显示用户头像
-    const avatarUrl = userInfo.avatar?.image?.large;
-    if (avatarUrl) {
-      document.getElementById("avatar").src = avatarUrl;
-    }
-
-    // 显示用户邮箱
-    if (userInfo.email) {
-      document.getElementById("email").textContent = userInfo.email;
-    }
+// 获取用户信息（React 组件内展示当前用户请优先用 useCurrentUserProfile，见下文）
+const result = await authClient.session.getUserInfo();
+if (result.error) {
+  logger.error("获取用户信息失败:", result.error.message);
+  if (result.status === 401) {
+    // 未登录：跳转登录页（可传 returnUrl / newTab，默认回到当前页）
+    authClient.session.redirectToLogin();
   }
-} catch (error) {
-  logger.error("获取用户信息异常:", error);
+} else if (result.data?.user_info) {
+  const info = result.data.user_info;
+  const userName = info.name?.[0]?.text || "未知用户"; // 名称是多语言数组
+  const avatarUrl = info.avatar?.image?.large; // 头像 URL 可能不返回
+  // React 中通过 state 渲染上述字段，禁止 document.getElementById 等直接 DOM 操作
+}
+
+// 退出登录后回到登录页
+const signOutResult = await authClient.session.signOut();
+if (!signOutResult.error) {
+  authClient.session.redirectToLogin();
 }
+
+// 跳转当前用户详情页（新标签页打开）
+authClient.session.navigateToUserProfile({ newTab: true });
 ```
 
 ## 错误处理
 
-### 常见错误类型
-
 | 错误码 | 说明           | 处理建议               |
 | ------ | -------------- | ---------------------- |
 | `400`  | 请求参数错误   | 检查传入参数是否正确   |
@@ -368,60 +155,19 @@ try {
 | `404`  | 资源不存在     | 检查请求的资源是否存在 |
 | `500`  | 服务器内部错误 | 稍后重试或联系技术支持 |
 
-### 错误处理最佳实践
-
-```typescript
-import { toast } from "sonner";
-
-// 统一错误处理函数
-function handleDataloomError(response: DataloomServiceResponse<any>) {
-  if (response.error) {
-    switch (response.status) {
-      case 401:
-        // 未授权，跳转登录
-        authClient.session.redirectToLogin();
-        break;
-      case 403:
-        // 权限不足
-        toast.error("权限不足，请联系管理员");
-        break;
-      case 500:
-        // 服务器错误
-        toast.error("服务器错误，请稍后重试");
-        break;
-      default:
-        toast.error(`操作失败: ${response.error.message}`);
-    }
-    return false;
-  }
-  return true;
-}
-
-// 使用示例
-import { logger } from "@lark-apaas/client-toolkit/logger";
-
-const userInfoResult = await authClient.session.getUserInfo();
-if (handleDataloomError(userInfoResult)) {
-  // 处理成功逻辑
-  logger.info("用户信息:", userInfoResult.data);
-}
-```
+统一处理建议：`401` 调用 `authClient.session.redirectToLogin()`（见综合示例）；`403`/`500` 用 toast（如 `sonner`）提示用户；其余情况展示 `error.message`。
 
 ## 注意事项
 
-1. **环境限制**：部分接口只能在浏览器环境中使用，服务端调用会返回环境不兼容错误
-2. **登录状态**：获取用户信息前需要确保用户已登录，否则会返回401错误
-3. **跨域配置**：确保应用域名已在 Dataloom 后台配置白名单
-4. **安全性**：不要在客户端代码中暴露敏感的配置信息
-5. **错误处理**：建议对所有接口调用进行统一的错误处理
+1. **环境限制**：本 skill 涉及的 `@lark-apaas/client-toolkit/**` 能力只能在前端/浏览器环境中使用，服务端调用会返回环境不兼容错误；更重要的是，服务端代码中禁止 import 这些前端 SDK
+2. **跨域配置**：确保应用域名已在 Dataloom 后台配置白名单
+3. **安全性**：不要在客户端代码中暴露敏感的配置信息
 
 # 用户系统前端相关规范
 
 ## 概述
 
-内置的用户前端组件规范，提供了 UserSelect（支持单选/多选的用户选择器）和 UserDisplay（用户信息展示组件）两个核心 React 组件，基于统一的userid数据，并且用户选择组件中会通过onchange返回User类型数据，专门用于处理用户相关的表单输入和数据展示场景。
-
-同时提供 DepartmentSelect（部门选择组件），用于部门字段的单选/多选选择，交互与受控规范与 UserSelect 保持一致。
+内置用户前端组件：UserSelect（单选/多选用户选择器，onChange 返回用户对象）、DepartmentSelect（部门选择组件，交互与受控规范与 UserSelect 一致）、UserDisplay（用户信息展示组件）。均基于统一的 userid 数据，用于用户相关的表单输入和数据展示场景。
 
 ## 类型定义
 
@@ -448,17 +194,8 @@ export type User = {
 
 ## 当前用户信息的获取方案
 
-### 常用场景
-
-- **用户信息展示**：在界面中显示当前用户名称和头像
-- **权限验证**：基于用户ID进行权限检查和控制
-- **数据关联**：在数据操作时关联当前用户信息
-- **日志记录**：记录用户操作日志时获取用户标识
-
 ### Hooks 方法: `useCurrentUserProfile` - 在 React 中获取当前用户信息
 
-### 基本信息
-
 - **文件路径**：`@lark-apaas/client-toolkit/hooks/useCurrentUserProfile`
 - **功能**：获取当前登录用户的个人信息（含飞书 user_id）
 - **返回值**：`Partial<IUserProfile>`（初始为空对象 `{}`，异步获取后填充完整字段）
@@ -473,29 +210,18 @@ export type User = {
 | `avatar`       | `string` | 用户头像 URL                                             |
 | `lark_user_id` | `string` | 飞书 user_id，通过额外异步请求获取，可能晚于其他字段就绪 |
 
-> ⚠️ **空值处理（CRITICAL）**：Hook 初始返回空对象 `{}`（truthy）、字段均 `undefined`。**MUST** 用可选链，并以 `if (!userInfo?.user_id)` 判加载态（不是 `!userInfo`）；`lark_user_id` 异步获取、可能为 `undefined`，使用前条件渲染。
-
-### 使用方法
+> ⚠️ **空值处理（CRITICAL）**：Hook 初始返回空对象 `{}`（truthy），**MUST** 用 `if (!userInfo?.user_id)` 判加载态（不是 `!userInfo`）；`lark_user_id` 可能为 `undefined`，使用前条件渲染。完整禁止行为清单与飞书 ID 转换指南（后端 `AuthNPaasService` 等）参见 `user-identity` skill。
 
 ```typescript
 import { useCurrentUserProfile } from "@lark-apaas/client-toolkit/hooks/useCurrentUserProfile";
 
 const MyComponent = () => {
   const userInfo = useCurrentUserProfile();
-
-  // 正确：安全访问 + 加载态处理
   if (!userInfo?.user_id) return <div>加载中...</div>;
-  return (
-    <div>
-      <p>{userInfo.name}</p>
-      {userInfo.lark_user_id && <p>飞书 ID: {userInfo.lark_user_id}</p>}
-    </div>
-  );
+  return <p>{userInfo.name}</p>;
 };
 ```
 
-> **飞书 ID 转换详细指南**（后端 `AuthNPaasService` 用法、自定义转换接口等）参见 `user-identity` skill。
-
 ## 用户展示与选择方案
 
 {% if projectMeta['flags']['supportBusinessUser'] %}
@@ -509,7 +235,7 @@ const MyComponent = () => {
 
 {% else %}
 
-##
+## UserSelect - 用户选择组件
 
 ### 基本信息
 
@@ -529,14 +255,9 @@ interface UserSelectProps {
 }
 ```
 
-### 值类型说明
-
-- **单选模式** (`mode="single"`)：值为 userid，返回为`IUserProfile` 对象
-- **多选模式** (`mode="multiple"`)：值为 userid数组，返回为`IUserProfile` 数组
+值类型：单选模式（`mode="single"`）值为 userid、onChange 返回 `IUserProfile` 对象；多选模式（`mode="multiple"`）值为 userid 数组、onChange 返回 `IUserProfile` 数组。
 
-### 使用示例
-
-#### 表单集成
+### 使用示例（表单集成）
 
 ```typescript
 import { useForm } from "react-hook-form";
@@ -545,10 +266,8 @@ import * as z from "zod";
 import { Form, FormControl, FormField, FormItem, FormLabel } from "@/components/ui/form";
 import { UserSelect } from "@lark-apaas/client-toolkit/components/User";
 
-// 定义表单验证schema
 const formSchema = z.object({
   assignee: z.string(),
-  participants: z.array(z.string()).optional(),
 });
 
 const form = useForm<z.infer<typeof formSchema>>({
@@ -574,24 +293,8 @@ const form = useForm<z.infer<typeof formSchema>>({
         </FormItem>
       )}
     />
-
-    <FormField
-      control={form.control}
-      name="participants"
-      render={({ field }) => (
-        <FormItem>
-          <FormLabel>参与人（多选）</FormLabel>
-          <FormControl>
-            <UserSelect
-              mode="multiple"
-              placeholder="选择参与人员"
-              value={field.value}
-              onChange={(users) => field.onChange(users.map(user => user.user_id))}
-            />
-          </FormControl>
-        </FormItem>
-      )}
-    />
+    {/* 多选字段差异仅：schema 用 z.array(z.string())，mode="multiple"，
+        onChange={(users) => field.onChange(users.map((u) => u.user_id))} */}
   </form>
 </Form>
 ```
@@ -604,41 +307,24 @@ const form = useForm<z.infer<typeof formSchema>>({
 - **功能**：用于所有用户信息的展示场景
 - **特性**：显示用户**头像**和**姓名**，支持多用户展示
 
-IMPORTANT：当不传递showLabel时，组件会同时展示用户头像和姓名，如果只需要头像，则需要传递showLabel的值为false
-
 ### 属性定义
 
 ```typescript
 interface UserDisplayProps {
-  users: string[]; // 用户id数组（必需）
+  users: string[]; // 用户id数组（必需），单个用户传 [userId]
   size?: "small" | "medium" | "large"; // 头像尺寸
   className?: string; // 自定义样式类名
-  showLabel?: boolean; // 默认为true，会展示用户姓名，如果只需要展示头像则需要设置为false
+  showLabel?: boolean; // 默认为true，同时展示头像和姓名；只需要头像时必须显式传 false
 }
 ```
 
 ### 使用示例
 
-#### 基础用法
-
 ```jsx
 import { UserDisplay } from "@lark-apaas/client-toolkit/components/User";
-import { useEmployeeStore } from "@/models/employee";
-
-const { employeesId } = useEmployeeStore();
-
-// 单个用户展示
-<UserDisplay
-  users={[employeesId]}
-  size="small"
-/>
-
-// 多用户展示
-<UserDisplay
-  users={project.participants}
-  size="medium"
-  className="project-members"
-/>
+
+// 单个或多个用户展示：users 传用户 id 数组
+<UserDisplay users={project.participants} size="medium" className="project-members" />
 ```
 
 ## 使用注意事项

package/steering/nestjs-react-fullstack/{skills → skills_common}/user-identity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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, 用户角色, 当前用户角色, 获取请求者角色, 展示用户, 显示用户, 用户面板, 我是谁, 获取用户"
+description: "Use when getting current user info/profile, displaying user name/avatar/email, converting miaoda userId ↔ lark_user_id (both directions via AuthNPaasService), or reading req.userContext fields (userId/roles/tenantId): useCurrentUserProfile, AuthNPaasService, FeishuID conversion. 触发词：用户身份, 用户信息, 用户资料, 当前用户, userProfile, useCurrentUserProfile, 飞书ID, FeishuID, 飞书用户ID, lark_user_id, 用户ID转换, AuthNPaasService, getBatchMiaodaUserIds, 飞书ID转妙搭, employee_id 转 userId, 用户上下文, userContext, userContext.roles, 用户角色, 当前用户角色, 获取请求者角色, 展示用户, 显示用户, 用户面板, 我是谁, 获取用户"
 steering: true
 steering-topic: user_identity
 match-template-name: nestjs-react-fullstack
@@ -77,7 +77,7 @@ match-template-name: nestjs-react-fullstack
     │   └─ 跳到 `feishu` skill 的 `references/id-convert.md`（spark id_convert type 20/21）
     │
     ├─ 需要把 飞书 user_id（employee_id）反查成 妙搭 userId？
-    │   └─ 无单步方案 ──→ `feishu` skill `references/id-convert.md` "反向两步走"
+    │   └─ 后端 ──→ `AuthNPaasService.getBatchMiaodaUserIds()`（第三节，SDK 一步，convertType 31）；非模板项目 ──→ `feishu` skill 两步兜底
     │
     └─ 需要自定义飞书 ID 转换接口？
         └─ 是 ──→ 注入 AuthNPaasService 编写 Controller（第四节，仅适用于 user_id）
@@ -102,7 +102,7 @@ match-template-name: nestjs-react-fullstack
 | `appId` | `string` | 应用 ID |
 | `loginUrl` | `string` | 登录跳转 URL |
 | `userType` | `string` | 用户类型（如 `_employee`） |
-| `env` | `string` | 环境（如 `preview`、`online`） |
+| `env` | `string` | 环境（`preview` 预览态、`runtime` 发布运行态） |
 | `userName` | `string` | 用户名 |
 | `userNameI18n` | `{ zh_cn, en_us, ja_jp }` | 多语言用户名 |
 | `isSystemAccount` | `boolean` | 是否系统账号 |
@@ -146,9 +146,9 @@ export class TasksController {
 
 妙搭平台的用户 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 单向转换**。
+`AuthNPaasService` 暴露的飞书 ID 是 **`user_id`**（即 `employee_id`，飞书企业内的用户标识）这一种，支持 **妙搭 userId ↔ 飞书 user_id 双向**转换（正向 `getBatchLarkUserIds`/`getCurrentUserLarkUserId`，反向 `getBatchMiaodaUserIds`）。
 
-> 如果需要 `open_id` / `union_id`，或者需要"飞书 ID → 妙搭 userId"反向，请改用飞书开放平台 `spark id_convert` 接口，参见 `feishu` skill 的 `references/id-convert.md`。
+> 如果需要 `open_id` / `union_id`（无论正反向），请改用飞书开放平台 `spark id_convert` 接口，参见 `feishu` skill 的 `references/id-convert.md`。`employee_id` ↔ 妙搭 userId 双向都在本 SDK 内（见下方方法表）。
 
 ### 后端 API
 
@@ -168,6 +168,10 @@ export class MyService {
     // 批量转换（最多 100 个）
     const larkUserIds = await this.authnService.getBatchLarkUserIds(['uid1', 'uid2']);
     // => ['<飞书 user_id>', null]  顺序与输入对应，失败项为 null
+
+    // 反向：飞书 user_id（employee_id） → 妙搭 userId
+    const miaodaUserIds = await this.authnService.getBatchMiaodaUserIds(['emp1', 'emp2']);
+    // => ['<妙搭 userId>', null]  顺序与输入对应，失败项为 null
   }
 }
 ```
@@ -176,6 +180,7 @@ export class MyService {
 |------|------|------|
 | `getCurrentUserLarkUserId` | `() → Promise<string \| null>` | 从请求上下文获取当前用户的飞书 ID |
 | `getBatchLarkUserIds` | `(userIds: string[]) → Promise<(string \| null)[]>` | 批量转换，最多 100 个，与输入顺序一一对应 |
+| `getBatchMiaodaUserIds` | `(employeeIds: string[]) → Promise<(string \| null)[]>` | 反向：批量把飞书 user_id（employee_id）转为妙搭 userId，最多 100 个，顺序一一对应，失败项 `null`（底层 convertType 31） |
 
 ### 内置接口
 
@@ -249,6 +254,8 @@ export class FeishuIdController {
 }
 ```
 
+> 反向转换（employee_id → 妙搭 userId）同理，把 `getBatchLarkUserIds` 换成 `getBatchMiaodaUserIds` 即可，无需新增 Controller。
+
 前端调用示例：
 
 ```typescript