@lark-apaas/coding-steering 0.1.14 → 0.1.15

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

@@ -1,19 +1,18 @@
 ---
 name: client-builtins-user-service
-description: 前端用户鉴权服务与组件指南，提供 Dataloom SDK 用户认证 API 和 React 用户组件。Use when 需要：(1) 实现登录/登出功能，(2) 获取当前用户信息或展示用户头像姓名，(3) 使用用户选择器或部门选择器组件，(4) 处理 401 未授权错误，或其他用户身份认证相关开发
+description: 前端用户鉴权服务与组件指南，提供 authClient（来自 @lark-apaas/client-toolkit/auth）用户认证 API 和 React 用户组件。Use when 需要：(1) 实现登录/登出功能，(2) 获取当前用户信息或展示用户头像姓名，(3) 使用用户/部门选择器组件的 props 与挂载（选完拿哪个 ID/传飞书/字段获取见 contacts-service），(4) 处理 401 未授权错误
 steering: true
 steering-topic: client_builtins_user_service
 match-template-name: nestjs-react-fullstack
 ---
 
-
-# Dataloom 用户信息与鉴权 SDK
+# 账户/会话 SDK (authClient)
 
 ## 概述
 
-项目提供了 Dataloom SDK 的用户信息与鉴权服务，用于用户登录、登出、获取用户信息等身份认证相关功能。
+项目通过 `authClient`（来自 `@lark-apaas/client-toolkit/auth`）提供用户信息与鉴权服务，用于用户登录、登出、获取用户信息等身份认证相关功能。
 
-> **边界说明**：`dataloom.service.session` 仅用于用户登录/登出/获取用户信息等鉴权操作。**插件调用（capability）不属于 dataloom**，须使用独立的 `capabilityClient`（参见 plugin-guide）。
+> **边界说明**：`authClient.session` 仅用于用户登录/登出/获取用户信息等鉴权操作。**插件调用（capability）不属于账户 SDK**，须使用独立的 `capabilityClient`（参见 plugin-guide）。
 
 ## 统一响应结构
 
@@ -58,13 +57,11 @@ interface DataloomServiceFailure extends DataloomServiceBase {
 type DataloomServiceResponse<T> = DataloomServiceSuccess<T> | DataloomServiceFailure;
 ```
 
-## Dataloom实例获取方式
+## authClient 引入方式
 
 ```typescript
-import { getDataloom } from "@lark-apaas/client-toolkit/dataloom";
-
-// 异步获取dataloom实例
-const dataloom = await getDataloom();
+import { authClient } from "@lark-apaas/client-toolkit/auth";
+// authClient 是 SDK 内置的 singleton，零参可用，不需要异步初始化
 ```
 
 ## 鉴权服务接口
@@ -94,19 +91,19 @@ interface SignInRedirectionOptions {
 }
 ```
 
-| 属性名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|---------|
-| `returnUrl` | `string` | ❌ | 当前页面URL | 登录成功后跳转回的页面 |
-| `newTab` | `boolean` | ❌ | `false` | 是否在新浏览器标签页打开登录页 |
+| 属性名      | 类型      | 必填 | 默认值      | 说明                           |
+| ----------- | --------- | ---- | ----------- | ------------------------------ |
+| `returnUrl` | `string`  | ❌   | 当前页面URL | 登录成功后跳转回的页面         |
+| `newTab`    | `boolean` | ❌   | `false`     | 是否在新浏览器标签页打开登录页 |
 
 ##### 出参说明
 
-| 字段名 | 类型 | 说明 |
-|--------|------|---------|
-| `data` | `'success'` | 成功标识 |
-| `error` | `null` | 错误信息，成功时为null |
-| `status` | `200` | HTTP状态码 |
-| `statusText` | `'OK'` | HTTP状态文本 |
+| 字段名       | 类型        | 说明                   |
+| ------------ | ----------- | ---------------------- |
+| `data`       | `'success'` | 成功标识               |
+| `error`      | `null`      | 错误信息，成功时为null |
+| `status`     | `200`       | HTTP状态码             |
+| `statusText` | `'OK'`      | HTTP状态文本           |
 
 ##### 使用示例
 
@@ -123,20 +120,17 @@ interface SignInRedirectionOptions {
  *   statusText: 'OK',
  *  }
  */
-const res: DataloomServiceResponse<'success'> = dataloom
-  .service
+const res: DataloomServiceResponse<'success'> = authClient
   .session
   .redirectToLogin(options: SignInRedirectionOptions);
 
 // 基本使用
-const loginResult = dataloom
-  .service
+const loginResult = authClient
   .session
   .redirectToLogin();
 
 // 带参数使用
-const loginResult = dataloom
-  .service
+const loginResult = authClient
   .session
   .redirectToLogin({
     returnUrl: 'https://example.com/dashboard',
@@ -160,12 +154,12 @@ const loginResult = dataloom
 
 ##### 出参说明
 
-| 字段名 | 类型 | 说明 |
-|--------|------|---------|
-| `data` | `null` | 数据为空 |
-| `error` | `null` | 错误信息，成功时为null |
-| `status` | `200` | HTTP状态码 |
-| `statusText` | `'OK'` | HTTP状态文本 |
+| 字段名       | 类型   | 说明                   |
+| ------------ | ------ | ---------------------- |
+| `data`       | `null` | 数据为空               |
+| `error`      | `null` | 错误信息，成功时为null |
+| `status`     | `200`  | HTTP状态码             |
+| `statusText` | `'OK'` | HTTP状态文本           |
 
 ##### 使用示例
 
@@ -180,29 +174,23 @@ const loginResult = dataloom
  *   statusText: 'OK',
  *  }
  */
-const res: Promise<DataloomServiceResponse<null>> = await dataloom
-  .service
-  .session
-  .signOut();
+const res: Promise<DataloomServiceResponse<null>> = await authClient.session.signOut();
 
 // 使用示例
 import { logger } from "@lark-apaas/client-toolkit/logger";
 
 try {
-  const result = await dataloom
-    .service
-    .session
-    .signOut();
+  const result = await authClient.session.signOut();
 
   if (result.error) {
-    logger.error('退出登录失败:', result.error.message);
+    logger.error("退出登录失败:", result.error.message);
   } else {
-    logger.info('退出登录成功');
+    logger.info("退出登录成功");
     // 跳转到登录页或首页
-    dataloom.service.session.redirectToLogin();
+    authClient.session.redirectToLogin();
   }
 } catch (error) {
-  logger.error('退出登录异常:', error);
+  logger.error("退出登录异常:", error);
 }
 ```
 
@@ -227,18 +215,18 @@ interface NavigateToUserProfileOptions {
 }
 ```
 
-| 属性名 | 类型 | 必填 | 默认值 | 说明 |
-|--------|------|------|--------|---------|
-| `newTab` | `boolean` | ❌ | `false` | 是否在新浏览器标签页打开详情页 |
+| 属性名   | 类型      | 必填 | 默认值  | 说明                           |
+| -------- | --------- | ---- | ------- | ------------------------------ |
+| `newTab` | `boolean` | ❌   | `false` | 是否在新浏览器标签页打开详情页 |
 
 ##### 出参说明
 
-| 字段名 | 类型 | 说明 |
-|--------|------|---------|
-| `data` | `'success'` | 成功标识 |
-| `error` | `null` | 错误信息，成功时为null |
-| `status` | `200` | HTTP状态码 |
-| `statusText` | `'OK'` | HTTP状态文本 |
+| 字段名       | 类型        | 说明                   |
+| ------------ | ----------- | ---------------------- |
+| `data`       | `'success'` | 成功标识               |
+| `error`      | `null`      | 错误信息，成功时为null |
+| `status`     | `200`       | HTTP状态码             |
+| `statusText` | `'OK'`      | HTTP状态文本           |
 
 ##### 使用示例
 
@@ -253,16 +241,10 @@ interface NavigateToUserProfileOptions {
  *   statusText: 'OK',
  * }
  */
-const res: DataloomServiceResponse<'success'> = dataloom
-  .service
-  .session
-  .navigateToUserProfile();
+const res: DataloomServiceResponse<"success"> = authClient.session.navigateToUserProfile();
 
 // 在新标签页打开
-const resNewTab = dataloom
-  .service
-  .session
-  .navigateToUserProfile({ newTab: true });
+const resNewTab = authClient.session.navigateToUserProfile({ newTab: true });
 ```
 
 ## 用户信息服务
@@ -315,16 +297,16 @@ 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 |
+| 字段名                        | 类型           | 说明                   |
+| ----------------------------- | -------------- | ---------------------- |
+| `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 |
 
 ##### 使用示例
 
@@ -335,48 +317,42 @@ interface UserInfoResponse {
  * @param {string} appId - 运行态应用的id，由dataloom authn 服务下发。
  * @return
  */
-const res: Promise<DataloomServiceResponse<UserInfoResponse>> = await dataloom
-  .service
-  .session
-  .getUserInfo();
+const res: Promise<DataloomServiceResponse<UserInfoResponse>> = await authClient.session.getUserInfo();
 
 // 使用示例
 import { logger } from "@lark-apaas/client-toolkit/logger";
 
 try {
-  const result = await dataloom
-    .service
-    .session
-    .getUserInfo();
+  const result = await authClient.session.getUserInfo();
 
   if (result.error) {
-    logger.error('获取用户信息失败:', result.error.message);
+    logger.error("获取用户信息失败:", result.error.message);
     // 可能需要重新登录
     if (result.status === 401) {
       // 跳转到登录页
-      dataloom.service.session.redirectToLogin();
+      authClient.session.redirectToLogin();
     }
   } else if (result.data?.user_info) {
     const userInfo = result.data.user_info;
-    logger.info('用户信息:', userInfo);
+    logger.info("用户信息:", userInfo);
 
     // 显示用户名
-    const userName = userInfo.name?.[0]?.text || '未知用户';
-    document.getElementById('username').textContent = userName;
+    const userName = userInfo.name?.[0]?.text || "未知用户";
+    document.getElementById("username").textContent = userName;
 
     // 显示用户头像
     const avatarUrl = userInfo.avatar?.image?.large;
     if (avatarUrl) {
-      document.getElementById('avatar').src = avatarUrl;
+      document.getElementById("avatar").src = avatarUrl;
     }
 
     // 显示用户邮箱
     if (userInfo.email) {
-      document.getElementById('email').textContent = userInfo.email;
+      document.getElementById("email").textContent = userInfo.email;
     }
   }
 } catch (error) {
-  logger.error('获取用户信息异常:', error);
+  logger.error("获取用户信息异常:", error);
 }
 ```
 
@@ -384,35 +360,37 @@ try {
 
 ### 常见错误类型
 
-| 错误码 | 说明 | 处理建议 |
-|--------|------|---------|
-| `400` | 请求参数错误 | 检查传入参数是否正确 |
-| `401` | 未授权访问 | 需要重新登录 |
-| `403` | 权限不足 | 联系管理员分配权限 |
-| `404` | 资源不存在 | 检查请求的资源是否存在 |
-| `500` | 服务器内部错误 | 稍后重试或联系技术支持 |
+| 错误码 | 说明           | 处理建议               |
+| ------ | -------------- | ---------------------- |
+| `400`  | 请求参数错误   | 检查传入参数是否正确   |
+| `401`  | 未授权访问     | 需要重新登录           |
+| `403`  | 权限不足       | 联系管理员分配权限     |
+| `404`  | 资源不存在     | 检查请求的资源是否存在 |
+| `500`  | 服务器内部错误 | 稍后重试或联系技术支持 |
 
 ### 错误处理最佳实践
 
 ```typescript
+import { toast } from "sonner";
+
 // 统一错误处理函数
 function handleDataloomError(response: DataloomServiceResponse<any>) {
   if (response.error) {
     switch (response.status) {
       case 401:
         // 未授权，跳转登录
-        dataloom.service.session.redirectToLogin();
+        authClient.session.redirectToLogin();
         break;
       case 403:
         // 权限不足
-        alert('权限不足，请联系管理员');
+        toast.error("权限不足，请联系管理员");
         break;
       case 500:
         // 服务器错误
-        alert('服务器错误，请稍后重试');
+        toast.error("服务器错误，请稍后重试");
         break;
       default:
-        alert(`操作失败: ${response.error.message}`);
+        toast.error(`操作失败: ${response.error.message}`);
     }
     return false;
   }
@@ -422,10 +400,10 @@ function handleDataloomError(response: DataloomServiceResponse<any>) {
 // 使用示例
 import { logger } from "@lark-apaas/client-toolkit/logger";
 
-const userInfoResult = await dataloom.service.session.getUserInfo();
+const userInfoResult = await authClient.session.getUserInfo();
 if (handleDataloomError(userInfoResult)) {
   // 处理成功逻辑
-  logger.info('用户信息:', userInfoResult.data);
+  logger.info("用户信息:", userInfoResult.data);
 }
 ```
 
@@ -450,19 +428,24 @@ if (handleDataloomError(userInfoResult)) {
 ### 用户数据类型
 
 ```typescript
-import type { User } from '@/types/common';
+import type { User } from "@/types/common";
 ```
 
 `User` 接口包含用户的基本信息，如用户 ID、姓名、头像字段。
 
 ```typescript
 export type User = {
+  /** 妙搭用户 ID：入库、传飞书内置插件、跨边界透传一律用它 */
   user_id: string;
+  /** 飞书企业内 user_id（仅内部飞书用户），调飞书开放平台 API 用它 */
+  employee_id?: string;
   name: string;
   avatar: string;
 };
 ```
 
+> **用户/部门 ID 怎么选、字段获取与权限引导 → 见 [`contacts-service`](../contacts-service/SKILL.md) skill；本 skill 只讲组件 API 用法。**
+
 ## 当前用户信息的获取方案
 
 ### 常用场景
@@ -482,20 +465,15 @@ export type User = {
 
 **IUserProfile 字段**：
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `user_id` | `string` | 妙搭用户 ID |
-| `email` | `string` | 用户邮箱 |
-| `name` | `string` | 用户名称 |
-| `avatar` | `string` | 用户头像 URL |
+| 字段           | 类型     | 说明                                                     |
+| -------------- | -------- | -------------------------------------------------------- |
+| `user_id`      | `string` | 妙搭用户 ID                                              |
+| `email`        | `string` | 用户邮箱                                                 |
+| `name`         | `string` | 用户名称                                                 |
+| `avatar`       | `string` | 用户头像 URL                                             |
 | `lark_user_id` | `string` | 飞书 user_id，通过额外异步请求获取，可能晚于其他字段就绪 |
 
-> ⚠️ **空值处理（CRITICAL）**：该 Hook 初始返回空对象 `{}`（truthy），所有字段均为 `undefined`。
->
-> - **MUST** 使用可选链访问：`userInfo?.name`、`userInfo?.user_id`
-> - **MUST** 判断加载状态用 `if (!userInfo?.user_id)` 而非 `if (!userInfo)`（空对象是 truthy）
-> - **MUST** 渲染时提供默认值：`userInfo?.name ?? '加载中...'`
-> - **MUST** `lark_user_id` 通过额外异步请求获取，可能为 `undefined`（加载中/获取失败/无飞书账号），使用时必须条件渲染
+> ⚠️ **空值处理（CRITICAL）**：Hook 初始返回空对象 `{}`（truthy）、字段均 `undefined`。**MUST** 用可选链，并以 `if (!userInfo?.user_id)` 判加载态（不是 `!userInfo`）；`lark_user_id` 异步获取、可能为 `undefined`，使用前条件渲染。
 
 ### 使用方法
 
@@ -520,6 +498,7 @@ const MyComponent = () => {
 
 ## 用户展示与选择方案
 
+{% if projectMeta['flags']['supportBusinessUser'] %}
 这些组件在使用之前必须读取 client/src/components/business-ui/README.md文件来理解用法
 
 目前可用的组件有：
@@ -528,9 +507,139 @@ const MyComponent = () => {
 - DepartmentSelect 部门选择组件（@/components/business-ui/department-select）
 - UserDisplay - 用户展示组件（@/components/business-ui/user-display）
 
-<!-- legacy: client-toolkit User 组件备用方案,已不再推荐;按本地版静态化,仅保留 business-ui 路径 -->
-<!-- begin: removed Nunjucks else branch (line 532..672 in upstream) -->
-<!-- end -->
+{% else %}
+
+##
+
+### 基本信息
+
+- **组件路径**：`@lark-apaas/client-toolkit/components/User`
+- **功能**：用于所有用户字段的表单输入
+- **特性**：支持单选/多选模式，内置搜索功能
+
+### 组件 Props 定义
+
+```typescript
+interface UserSelectProps {
+  mode: "single" | "multiple"; // 选择模式
+  value?: string | string[]; // 当前userid的值
+  onChange?: (value: IUserProfile | IUserProfile[]) => void; // userid值变化回调
+  placeholder?: string; // 占位符文本
+  disabled?: boolean; // 是否禁用
+}
+```
+
+### 值类型说明
+
+- **单选模式** (`mode="single"`)：值为 userid，返回为`IUserProfile` 对象
+- **多选模式** (`mode="multiple"`)：值为 userid数组，返回为`IUserProfile` 数组
+
+### 使用示例
+
+#### 表单集成
+
+```typescript
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+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>>({
+  resolver: zodResolver(formSchema),
+});
+
+<Form {...form}>
+  <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+    <FormField
+      control={form.control}
+      name="assignee"
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>负责人</FormLabel>
+          <FormControl>
+            <UserSelect
+              mode="single"
+              placeholder="选择负责人"
+              value={field.value}
+              onChange={(user) => field.onChange(user.user_id)}
+            />
+          </FormControl>
+        </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>
+      )}
+    />
+  </form>
+</Form>
+```
+
+## UserDisplay - 用户展示组件
+
+### 基本信息
+
+- **组件路径**：`@lark-apaas/client-toolkit/components/User`
+- **功能**：用于所有用户信息的展示场景
+- **特性**：显示用户**头像**和**姓名**，支持多用户展示
+
+IMPORTANT：当不传递showLabel时，组件会同时展示用户头像和姓名，如果只需要头像，则需要传递showLabel的值为false
+
+### 属性定义
+
+```typescript
+interface UserDisplayProps {
+  users: string[]; // 用户id数组（必需）
+  size?: "small" | "medium" | "large"; // 头像尺寸
+  className?: string; // 自定义样式类名
+  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"
+/>
+```
 
 ## 使用注意事项
 
@@ -538,3 +647,4 @@ const MyComponent = () => {
 
 - 根据展示场景选择合适的组件尺寸（`small`、`medium`、`large`）
 - 对于用户信息 userId，禁止直接展示文本，总是使用 UserDisplay 组件展示
+  {% endif %}