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

package/steering/nestjs-react-fullstack/skills/server-builtins-file-storage-service/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: server-builtins-file-storage-service
+description: "Use when server-side code needs to upload or download files programmatically, such as file format conversion, automated report generation, or background tasks that produce files. NOT for frontend file operations. 触发词：服务端文件上传, 服务端文件下载, FileService, nestjs file, 后端文件处理, 文件格式转换, 生成文件上传"
+steering: true
+steering-topic: server_builtins_file_storage_service
+match-template-name: nestjs-react-fullstack
+---
+
+# NestJS File Service SDK
+
+在 NestJS 服务端代码中使用 `FileService` 进行文件上传、下载、删除和管理。
+
+> **使用注意**: 仅用于服务端文件处理场景，非必要文件上传下载场景请使用前端 `client-builtins-file-storage-service` skill。
+> CLI 调试场景请参考 `file-storage` skill。
+
+## 使用场景
+
+| 场景 | 说明 |
+|------|------|
+| 服务端文件处理 | 下载文件到本地处理后重新上传，如图片格式转换、docx 格式转换等 |
+| 自动化任务生成文件 | 定时任务或事件触发后，根据数据库/插件内容生成文件并上传，如定时生成 PDF 报告、图片海报等 |
+
+## Quick Reference
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `upload(file, options?)` | 上传文件 | `FileMeta` |
+| `download(path)` | 下载文件（≤50MB） | `FileDownloadBuilder` |
+| `remove(filePaths)` | 删除文件 | `RemoveResponse` |
+| `getFileMetadata(filePath)` | 获取文件元信息 | `FileMeta` |
+
+## 注入 FileService
+
+```typescript
+import { FileService } from '@lark-apaas/fullstack-nestjs-core';
+
+@Injectable()
+export class MyService {
+  constructor(private readonly fileService: FileService) {}
+}
+```
+
+## 公共类型
+
+```typescript
+interface FileMeta {
+  id: string;
+  name: string;
+  filePath: string;
+  metadata: { contentLength: string; mimeType: string };
+  downloadURL: string;
+  createdAt: string;
+  updatedAt: string;
+  bucketID: string;
+}
+```
+
+## 核心操作
+
+### 1. 上传文件
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `file` | `FileBody` | 是 | 文件内容（支持 `Buffer`、`ReadableStream`、`ArrayBuffer`、`Blob`、`string` 等） |
+| `options` | `UploadOptions` | 否 | 上传选项 |
+
+**UploadOptions：**
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `fileName` | `string` | 否 | 文件名称 |
+| `contentType` | `string` | 否 | MIME 类型 |
+| `cacheControl` | `string \| number` | 否 | 缓存控制 |
+| `upsert` | `boolean` | 否 | 是否覆盖已有文件 |
+
+**返回值：** `FileMeta`
+
+**示例：**
+
+```typescript
+// 基本上传
+const result = await this.fileService.upload(buffer);
+
+// 带选项上传
+const result = await this.fileService.upload(fileBody, {
+  fileName: 'report.pdf',
+  contentType: 'application/pdf',
+  upsert: false,
+});
+```
+
+### 2. 下载文件
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `path` | `string` | 是 | downloadURL 或文件存储路径 |
+
+**返回值 `DownloadResult`：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `content` | `Blob`（默认）/ `ReadableStream`（流式） | 文件内容 |
+| `metadata` | `FileMeta` | 文件元信息 |
+
+> **推荐始终使用 `.asStream()`**，避免大文件导致内存溢出。直接 `await download()` 有 50MB 限制。
+
+**示例：**
+
+```typescript
+// 推荐：使用 downloadURL + 流式下载
+const downloadURL = fileMeta.downloadURL; // 从上传返回值或数据库获取
+const { content, metadata } = await this.fileService
+  .download(downloadURL)
+  .asStream();
+
+// 也可以使用文件存储路径
+const { content, metadata } = await this.fileService
+  .download('file.pdf')
+  .asStream();
+
+// 不推荐：Blob 下载（限制 50MB，会将整个文件加载到内存）
+const { content, metadata } = await this.fileService.download(downloadURL);
+```
+
+### 3. 删除文件
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `filePaths` | `string[]` | 是 | downloadURL 或文件存储路径数组 |
+
+**返回值：** `FileMeta[]` - 删除成功的文件元信息数组
+
+**示例：**
+
+```typescript
+// 推荐：使用 downloadURL
+const result = await this.fileService.remove([fileMeta.downloadURL]);
+
+// 也可以使用文件存储路径
+const result = await this.fileService.remove(['file1.pdf', 'file2.png']);
+```
+
+### 4. 获取文件元信息
+
+**入参：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `filePath` | `string` | 是 | downloadURL 或文件存储路径 |
+
+**返回值：** `FileMeta | null` - 文件元信息或 `null` 表示文件不存在或删除失败
+
+**示例：**
+
+```typescript
+// 推荐：使用 downloadURL
+const meta = await this.fileService.getFileMetadata(fileMeta.downloadURL);
+
+// 也可以使用文件存储路径
+const meta = await this.fileService.getFileMetadata('file.pdf');
+```
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| 直接 `await download()` 导致内存溢出 | 始终使用 `.asStream()` 流式下载 |
+| 忘记设置 `contentType` 导致浏览器无法预览 | 上传时明确指定 `contentType` |
+| 直接 `new FileService()` 手动实例化 | 通过 NestJS DI 注入 `FileService` |
+| 在异步回调中调用 `download()` 导致上下文丢失 | 在请求处理函数中立即调用，SDK 内部已处理上下文捕获 |
+| 删除时传单个字符串 | `remove()` 参数为 `string[]` 数组 |

package/steering/nestjs-react-fullstack/skills/user-management-best-practices/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: user-management-best-practices
+description: "Use when 决定是否创建用户表、选择用户唯一标识（user_id vs email/手机号）、设计 user_profile 字段与 UNIQUE 约束、处理防重复提交/upsert 去重，或涉及问卷、抽奖、报名、投票等用户提交场景的表结构设计。触发词：用户管理, 用户表设计, user_id, email, user_profile, 去重, 防重复提交, 批量导入用户, upsert, UNIQUE约束, UserSelect, UserDisplay, user management, deduplication"
+steering: true
+steering-topic: user_management_best_practices
+match-template-name: nestjs-react-fullstack
+---
+
+# 用户管理最佳实践指南
+
+## 概述
+
+本指南适用于生成涉及用户管理、问卷、抽奖、报名、投票等用户提交场景的代码。
+
+**核心问题：**
+
+- 妙搭 Agent 无法获取企业的所有用户数据，需要构建应用维度的用户表
+- 企业无法显式感知飞书的 user_id（不透明的数字字符串，如 "1847292357012580"），无法批量导入飞书用户到应用的用户表
+- 推荐使用邮箱或者手机号作为业务层唯一标识（不是 user_id）
+- UserSelect 返回的 IUserProfile 对象已包含 email 和 phone_number 字段，可直接使用
+
+**本指南解决：**
+
+- 何时使用 UserSelect 组件 vs 何时创建用户表
+- 如何设计用户业务表（正确的唯一约束）
+- 防止重复提交的正确实现方式
+
+---
+
+## 核心原则：禁止事项
+
+| 禁止操作                              | 说明                                                   | 正确做法                                                                                     |
+| ------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| 不推荐实现批量导入用户的功能          | Agent 无法获取企业全量用户，批量 INSERT users 表行不通 | 推荐使用 UserSelect 组件动态选择用户                                                         |
+| 不推荐用 user_id 作为去重逻辑         | 企业不感知飞书用户 id，无法感知是谁                    | 使用 email 或者手机号做唯一约束（UNIQUE(email)），不要使用姓名，可能会重复                   |
+| 禁止编造 user_id                      | Mock 数据中不能随意编造 user_id 值                     | 必须使用 SQL skill 规定的测试用户列表                                                        |
+| 禁止全量查询用户列表                  | 全量拉取数据会导致接口超时或 OOM                       | 使用后端分页查询（skip/take）                                                                |
+| 禁止前端分页用户列表                  | 前端分页需要全量拉取数据，导致性能问题                 | 使用后端分页，前端仅控制页码                                                                 |
+| 禁止只存 user_id 不存 email or 手机号 | 业务层无法用 user_id 做防重和查询                      | 存储 user_profile 字段（已包含 email/phone），并在表中单独添加 email 或 phone 列用于唯一约束 |
+
+---
+
+## 决策树示例：何时创建用户表 vs 何时使用 user_profile
+
+```text
+需要记录用户相关业务数据？
+    │
+    ├─ 仅需要识别"谁"执行操作（发帖人、评论者）
+    │   └─ ✅ 直接使用 user_profile 类型字段
+    │       示例：posts.author（user_profile）
+    │
+    └─ 需要存储业务特定的用户数据
+        │
+        ├─ 数据与具体业务资源强绑定（问卷提交、抽奖记录）
+        │   └─ ✅ 创建业务表 + user_profile 字段 + email 唯一约束
+        │       示例：questionnaire_responses (id, respondent, email, UNIQUE(questionnaire_id, email))
+        │
+        └─ 数据代表"用户在系统中的身份"（员工、学生、会员）
+            └─ ✅ 创建人员实体表，user_profile 作为主键
+                示例：employees (employee_profile PRIMARY KEY, department, position)
+```
+
+---
+
+## 用户列表查询与性能注意事项
+
+### UserSelect vs 分页列表的选择
+
+根据场景选择正确的用户选择方式：
+
+| 场景               | 使用组件         | 数据加载方式 | 典型数量 |
+| ------------------ | ---------------- | ------------ | -------- |
+| 表单选择用户       | UserSelect       | 搜索驱动     | 1-10     |
+| 用户管理后台       | Table + 后端分页 | 分页加载     | 100+     |
+| 问卷提交记录列表   | Table + 后端分页 | 分页加载     | 100+     |
+| 抽奖参与者名单展示 | Table + 后端分页 | 分页加载     | 100+     |
+
+- **UserSelect 组件**：搜索驱动，返回完整 IUserProfile 对象（含 email、phone_number）。详细用法参考 **client-builtins-user-service**
+- **Table + 后端分页**：详细实现参考 **table-skill**
+
+### 分页实现
+
+用户列表必须使用后端分页，禁止前端全量拉取。具体实现参考 **table-skill**。
+
+### 动态创建用户记录
+
+**何时动态创建：**
+
+1. **首次提交场景**：用户首次提交问卷/参与抽奖时，使用 `upsert` 方法
+2. **首次登录场景**：用户首次登录系统时，创建用户记录
+
+## 常见错误速查表
+
+| 错误模式                | 问题                   | 正确做法                                                     | 影响        |
+| ----------------------- | ---------------------- | ------------------------------------------------------------ | ----------- |
+| 批量 INSERT users       | Agent 无法获取全量用户 | 使用 UserSelect 组件                                         | 🔴 CRITICAL |
+| `UNIQUE(user_id)`       | 企业不认识 user_id     | `UNIQUE(email)`                                              | 🔴 CRITICAL |
+| 编造 user_id            | Mock 数据无效          | 使用测试用户列表                                             | 🔴 CRITICAL |
+| 全量查询用户列表        | 接口超时或 OOM         | 使用后端分页（skip/take）                                    | 🔴 CRITICAL |
+| 前端分页（全量拉取）    | 首次加载超时           | 使用后端分页                                                 | 🔴 CRITICAL |
+| 只存 user_id 不存 email | 无法做业务层防重       | 存储 user_profile（已含 email），并添加 email 列用于唯一约束 | 🟠 BUG      |
+| 直接显示 user_id        | 用户体验差             | 使用 UserDisplay 组件                                        | 🟡 UX       |
+| 创建 users 基础表       | 无法同步飞书数据       | 使用 user_profile 类型                                       | 🟠 DESIGN   |
+
+## 相关技能参考
+
+- **client-builtins-user-service**: UserSelect 详细用法、IUserProfile 类型定义、UserDisplay 组件、useCurrentUserProfile hook
+- **sql**: user_profile 类型约束、JSONB 验证规则、测试用户列表
+- **table-skill**: Table 组件使用、后端分页实现、前端分页最佳实践
+- **authz-guide**: 结合基于角色的访问控制（如：只允许用户查看/编辑自己的提交）
+
+## 自查清单
+
+### 表设计
+
+- [ ] 判断是否需要创建用户表（参考决策树）
+- [ ] 人员实体表使用 `user_profile PRIMARY KEY`
+- [ ] 业务表使用 `id UUID PRIMARY KEY` + `user_profile` 字段
+- [ ] 业务表包含 `email VARCHAR(255)` or `phone VARCHAR(255)` 字段
+- [ ] 设置了正确的唯一约束（使用 email or 手机号，如 `UNIQUE(resource_id, email)`）
+
+### 前端实现
+
+- [ ] 使用 UserSelect 组件而非手动输入
+- [ ] 使用 UserDisplay 展示用户（不直接显示 user_id）
+- [ ] 用户列表使用后端分页（不全量拉取）
+- [ ] Table 组件的 onChange 触发后端请求
+
+### 后端实现
+
+- [ ] Entity 定义了正确的唯一约束（`@Unique(['resourceId', 'email'])` or `@Unique(['resourceId', 'phone'])`）
+- [ ] 错误处理包含唯一约束冲突（409 Conflict）
+- [ ] 存储 user_profile 字段（已包含 email/phone）
+- [ ] 在表中单独添加 email 或 phone 列，用于唯一约束和索引查询
+- [ ] 列表接口使用 skip/take 分页查询
+- [ ] 返回 pagination 对象（page, pageSize, total）
+
+### Mock 数据
+
+- [ ] user_id 使用测试用户列表（不编造）
+- [ ] user_profile 中的 email/phone 与 user_id 对应正确
+- [ ] 测试了重复提交场景（唯一约束生效）

package/steering/design-stack/skills/client-add-aily-web-chat/SKILL.md

@@ -1,139 +0,0 @@
----
-name: client-add-aily-web-chat
-description: Use when integrating Aily AI chat panel into a web app using @lark-apaas/client-toolkit/aily-chat. 触发词：Aily 聊天, Aily 对话面板, Aily chat, aily-chat SDK, AI 对话组件集成
----
-
-# 添加 Aily Web 对话面板
-
-使用 `@lark-apaas/client-toolkit/aily-chat` 将 Aily 对话面板集成到 Web 应用。SDK 与框架无关（纯 DOM 操作）。
-
-## Quick Reference
-
-| 操作 | 方法 |
-|------|------|
-| 初始化 | `await initAilyChat(container, config)` |
-| 发送消息 | `chatPanel.sendMessage({ content, skillID? })` |
-| 清空记录 | `chatPanel.clear()` |
-| 清空并停止 | `chatPanel.clearAndStop()` |
-| 更新配置 | `chatPanel.updateConfig(partialConfig)` |
-| 销毁 | `chatPanel.destroy()` |
-
-## 核心流程
-
-### 1. 向用户获取 appKey
-
-实现前必须先询问用户：
-
-> "请提供你的 Aily `appKey` 以配置对话组件。你可以在 [Aily 平台](https://apaas.feishu.cn/ai/projects) 中找到对应应用的 appKey。"
-
-### 2. 集成代码
-
-React 组件示例（vanilla JS 同理，对 DOM 元素调用 `initAilyChat` 即可）：
-
-```tsx
-import { useEffect, useRef } from "react";
-import { initAilyChat, type ChatPanel } from "@lark-apaas/client-toolkit/aily-chat";
-
-interface AilyChatProps {
-  appKey: string;
-  anonymous?: boolean;
-}
-
-const containerStyle = { width: "100%", height: "500px" };
-
-const AilyChat = ({ appKey, anonymous }: AilyChatProps) => {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const chatPanelRef = useRef<ChatPanel | null>(null);
-
-  useEffect(() => {
-    if (!containerRef.current) return;
-    let destroyed = false;
-
-    initAilyChat(containerRef.current, {
-      appKey,
-      anonymous,
-      conversion: { needAvatar: true },
-      events: {
-        onReady: () => console.log("对话就绪"),
-        onError: (err) => console.error("对话错误", err),
-      },
-    }).then((panel) => {
-      if (destroyed) panel.destroy();
-      else chatPanelRef.current = panel;
-    });
-
-    return () => {
-      destroyed = true;
-      chatPanelRef.current?.destroy();
-      chatPanelRef.current = null;
-    };
-  }, [appKey, anonymous]);
-
-  return <div ref={containerRef} style={containerStyle} />;
-};
-
-export default AilyChat;
-```
-
-### 3. 告知用户 UI 定制选项
-
-代码集成完成后，**必须**向用户展示以下可定制选项：
-
-- 修改组件标题/顶部标题
-- 关闭/开启组件标题栏
-- 显示/隐藏关闭按钮
-- 隐藏/展示用户头像、隐藏/展示系统头像
-- 修改用户头像或系统头像，并发送新头像图片 
-- 隐藏/展示组件欢迎语
-
-## 配置参考
-
-### WebSDKConfig（顶层）
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `appKey` | string | 是 | 应用标识 |
-| `uuid` | string | 否 | 用户标识，启用 `needCache` 时必填 |
-| `anonymous` | boolean | 否 | `true` 开启匿名模式，跳过登录。**须在 Aily 应用「渠道管理」中将 SDK 模式开启匿名访问，否则会报错「匿名SDK没有开启支持使用应用身份调用API和SDK」** |
-| `conversion` | object | 否 | 对话配置（头像、缓存、欢迎语） |
-| `editor` | object | 否 | 顶部栏配置（标题、关闭按钮） |
-| `events` | object | 否 | 事件回调 |
-
-### conversion
-
-| 字段 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `needCache` | boolean | `false` | 启用消息缓存（需同时提供 `uuid`） |
-| `storageType` | string | `"memory"` | `memory` / `sessionStorage` / `localStorage` / `indexDB` / `server` |
-
-> 头像和欢迎语相关字段见上方「UI 定制选项」表。
-
-### editor
-
-| 字段 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `display` | boolean | `true` | 是否显示编辑器 |
-| `needHeader` | boolean | `true` | 是否显示顶部 header（含标题和新建对话按钮），仅 V2 生效 |
-| `headerTitle` | string | 应用名称 | 对话标题，显示在 header 中 |
-| `needCloseButton` | boolean | `false` | 是否显示关闭按钮。配合 `events.onClose` 监听点击 |
-
-### events
-
-| 事件 | 签名 | 说明 |
-|------|------|------|
-| `onReady` | `() => void` | 对话就绪 |
-| `onError` | `(error: Error) => void` | 发生错误 |
-| `onMessage` | `(message: unknown) => void` | 收到消息 |
-| `onInited` | `(data: { sessionId, conversationId, handler }) => void` | 会话已创建 |
-| `onInitedWithWelcome` | `() => void` | 欢迎语已创建 |
-| `onClose` | `() => void` | 用户点击关闭按钮时触发（需配合 `editor.needCloseButton: true`） |
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| 忘记在 useEffect 清理时调用 `destroy()` | 必须在 cleanup 中销毁 ChatPanel，否则内存泄漏 |
-| 启用 `needCache` 但未传 `uuid` | 缓存依赖 `uuid` 识别用户，缺失则无法恢复历史消息 |
-| 容器元素无固定宽高 | 容器必须有明确尺寸，否则面板不可见 |
-| 在 React 严格模式下未处理重复初始化 | 用 `destroyed` 标志防止 StrictMode 双重 mount 导致重复面板 |
-| 设置 `anonymous: true` 但未在 Aily 平台开启匿名访问 | 须前往 Aily 应用「渠道管理」将 SDK 模式开启匿名访问，否则报错「匿名SDK没有开启支持使用应用身份调用API和SDK」 |