@lark-apaas/coding-steering 0.1.6-alpha.1 → 0.1.6-alpha.10

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

@@ -0,0 +1,628 @@
+---
+name: client-builtins-user-service
+description: 前端用户鉴权服务与组件指南，提供 Dataloom SDK 用户认证 API 和 React 用户组件。Use when 需要：(1) 实现登录/登出功能，(2) 获取当前用户信息或展示用户头像姓名，(3) 使用用户选择器或部门选择器组件，(4) 处理 401 未授权错误，或其他用户身份认证相关开发
+steering: true
+steering-topic: client_builtins_user_service
+match-template-name: nestjs-react-fullstack
+---
+
+
+# Dataloom 用户信息与鉴权 SDK
+
+## 概述
+项目提供了 Dataloom SDK 的用户信息与鉴权服务，用于用户登录、登出、获取用户信息等身份认证相关功能。
+
+> **边界说明**：`dataloom.service.session` 仅用于用户登录/登出/获取用户信息等鉴权操作。**插件调用（capability）不属于 dataloom**，须使用独立的 `capabilityClient`（参见 plugin-guide）。
+
+## 统一响应结构
+
+### 响应类型定义
+```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;
+}
+
+interface DataloomServiceSuccess<T> extends DataloomServiceBase {
+  error: null;
+  data: T;
+}
+
+interface DataloomServiceFailure extends DataloomServiceBase {
+  error: {
+    code: number;
+    details: string;
+    hint: string | null;
+    message: string;
+  };
+  data: null;
+}
+
+type DataloomServiceResponse<T> = DataloomServiceSuccess<T> | DataloomServiceFailure;
+```
+
+## Dataloom实例获取方式
+```typescript
+import { getDataloom } from "@lark-apaas/client-toolkit/dataloom";
+
+// 异步获取dataloom实例
+const dataloom = await getDataloom();
+```
+
+## 鉴权服务接口
+
+#### 1. 登录跳转接口 (redirectToLogin)
+
+##### 用途
+跳转至 Dataloom 登录页面，适用于：用户身份认证、单点登录、权限验证
+
+##### 适用场景
+需要用户进行身份认证的场景
+
+##### 入参说明
+```typescript
+interface SignInRedirectionOptions {
+  /**
+   * 选填，登录成功后跳转回的页面。省略会默认用调用接口时页面的url。
+   */
+  returnUrl?: string;
+  /**
+   * 选填，是否在新浏览器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'> = dataloom
+  .service
+  .session
+  .redirectToLogin(options: SignInRedirectionOptions);
+
+// 基本使用
+const loginResult = dataloom
+  .service
+  .session
+  .redirectToLogin();
+
+// 带参数使用
+const loginResult = dataloom
+  .service
+  .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 dataloom
+  .service
+  .session
+  .signOut();
+
+// 使用示例
+import { logger } from "@lark-apaas/client-toolkit/logger";
+
+try {
+  const result = await dataloom
+    .service
+    .session
+    .signOut();
+
+  if (result.error) {
+    logger.error('退出登录失败:', result.error.message);
+  } else {
+    logger.info('退出登录成功');
+    // 跳转到登录页或首页
+    dataloom.service.session.redirectToLogin();
+  }
+} catch (error) {
+  logger.error('退出登录异常:', error);
+}
+```
+
+#### 3. 跳转用户详情页接口 (navigateToUserProfile)
+
+##### 用途
+跳转至当前登录用户的详情页，适用于：查看个人资料、从用户头像/姓名点击进入详情页面
+
+##### 适用场景
+需要在应用中快速打开用户详情页面的场景
+
+##### 入参说明
+```typescript
+interface NavigateToUserProfileOptions {
+  /**
+   * 选填，是否在新浏览器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'> = dataloom
+  .service
+  .session
+  .navigateToUserProfile();
+
+// 在新标签页打开
+const resNewTab = dataloom
+  .service
+  .session
+  .navigateToUserProfile({ newTab: true });
+```
+
+## 用户信息服务
+
+#### 4. 获取用户信息接口 (getUserInfo)
+
+##### 用途
+根据当前登录态获取已登录的用户信息，适用于：用户资料展示、权限判断、个性化配置
+
+##### 适用场景
+需要获取当前登录用户详细信息的场景
+
+##### 数据类型定义
+```typescript
+interface I18n {
+  language_code: number;
+  text: string;
+}
+
+type I18ns = I18n[];
+
+interface Avatar {
+  source?: string;
+  image?: {
+    large?: string; // 图片url, 可能不返回
+  };
+  color?: string; // 颜色，可能不返回。
+}
+
+interface UserBaseInfo {
+  user_id?: number;
+  name?: I18ns;
+  avatar?: Avatar;
+  email?: string;
+  phone_number?: string;
+  tenant_name?: string;
+}
+
+interface UserInfoResponse {
+  user_info?: UserBaseInfo;
+}
+```
+
+##### 入参说明
+无需传入参数
+
+##### 出参说明
+| 字段名 | 类型 | 说明 |
+|--------|------|---------|
+| `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 dataloom
+  .service
+  .session
+  .getUserInfo();
+
+// 使用示例
+import { logger } from "@lark-apaas/client-toolkit/logger";
+
+try {
+  const result = await dataloom
+    .service
+    .session
+    .getUserInfo();
+
+  if (result.error) {
+    logger.error('获取用户信息失败:', result.error.message);
+    // 可能需要重新登录
+    if (result.status === 401) {
+      // 跳转到登录页
+      dataloom.service.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;
+    }
+  }
+} catch (error) {
+  logger.error('获取用户信息异常:', error);
+}
+```
+
+## 错误处理
+
+### 常见错误类型
+| 错误码 | 说明 | 处理建议 |
+|--------|------|---------|
+| `400` | 请求参数错误 | 检查传入参数是否正确 |
+| `401` | 未授权访问 | 需要重新登录 |
+| `403` | 权限不足 | 联系管理员分配权限 |
+| `404` | 资源不存在 | 检查请求的资源是否存在 |
+| `500` | 服务器内部错误 | 稍后重试或联系技术支持 |
+
+### 错误处理最佳实践
+```typescript
+// 统一错误处理函数
+function handleDataloomError(response: DataloomServiceResponse<any>) {
+  if (response.error) {
+    switch (response.status) {
+      case 401:
+        // 未授权，跳转登录
+        dataloom.service.session.redirectToLogin();
+        break;
+      case 403:
+        // 权限不足
+        alert('权限不足，请联系管理员');
+        break;
+      case 500:
+        // 服务器错误
+        alert('服务器错误，请稍后重试');
+        break;
+      default:
+        alert(`操作失败: ${response.error.message}`);
+    }
+    return false;
+  }
+  return true;
+}
+
+// 使用示例
+import { logger } from "@lark-apaas/client-toolkit/logger";
+
+const userInfoResult = await dataloom.service.session.getUserInfo();
+if (handleDataloomError(userInfoResult)) {
+  // 处理成功逻辑
+  logger.info('用户信息:', userInfoResult.data);
+}
+```
+
+## 注意事项
+
+1. **环境限制**：部分接口只能在浏览器环境中使用，服务端调用会返回环境不兼容错误
+2. **登录状态**：获取用户信息前需要确保用户已登录，否则会返回401错误
+3. **跨域配置**：确保应用域名已在 Dataloom 后台配置白名单
+4. **安全性**：不要在客户端代码中暴露敏感的配置信息
+5. **错误处理**：建议对所有接口调用进行统一的错误处理
+
+# 用户系统前端相关规范
+
+## 概述
+内置的用户前端组件规范，提供了 UserSelect（支持单选/多选的用户选择器）和 UserDisplay（用户信息展示组件）两个核心 React 组件，基于统一的userid数据，并且用户选择组件中会通过onchange返回User类型数据，专门用于处理用户相关的表单输入和数据展示场景。
+
+同时提供 DepartmentSelect（部门选择组件），用于部门字段的单选/多选选择，交互与受控规范与 UserSelect 保持一致。
+## 类型定义
+
+### 用户数据类型
+```typescript
+import type { User } from '@/types/common';
+```
+
+`User` 接口包含用户的基本信息，如用户 ID、姓名、头像字段。
+
+```typescript
+export type User = {
+  user_id: string;
+  name: string;
+  avatar: string;
+};
+```
+
+## 当前用户信息的获取方案
+
+### 常用场景
+- **用户信息展示**：在界面中显示当前用户名称和头像
+- **权限验证**：基于用户ID进行权限检查和控制
+- **数据关联**：在数据操作时关联当前用户信息
+- **日志记录**：记录用户操作日志时获取用户标识
+
+### Hooks 方法: `useCurrentUserProfile` - 在 React 中获取当前用户信息
+
+### 基本信息
+- **文件路径**：`@lark-apaas/client-toolkit/hooks/useCurrentUserProfile`
+- **功能**：获取当前登录用户的个人信息（含飞书 user_id）
+- **返回值**：`Partial<IUserProfile>`（初始为空对象 `{}`，异步获取后填充完整字段）
+
+**IUserProfile 字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `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`（加载中/获取失败/无飞书账号），使用时必须条件渲染
+
+### 使用方法
+```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>
+  );
+};
+```
+
+> **飞书 ID 转换详细指南**（后端 `AuthNPaasService` 用法、自定义转换接口等）参见 `user-identity` skill。
+
+## 用户展示与选择方案
+{% if projectMeta['flags']['supportBusinessUser'] %}
+这些组件在使用之前必须读取 client/src/components/business-ui/README.md文件来理解用法
+
+目前可用的组件有：
+- UserSelect 用户选择组件（@/components/business-ui/user-select）
+- DepartmentSelect 部门选择组件（@/components/business-ui/department-select）
+- UserDisplay - 用户展示组件（@/components/business-ui/user-display）
+
+{% 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"
+/>
+```
+
+## 使用注意事项
+
+### 最佳实践
+- 根据展示场景选择合适的组件尺寸（`small`、`medium`、`large`）
+- 对于用户信息 userId，禁止直接展示文本，总是使用 UserDisplay 组件展示
+{% endif %}