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

package/steering/nestjs-react-fullstack/skills/authz-guide/references/runtime-role-controller-spec.md

@@ -0,0 +1,203 @@
+# 运行态角色管理 Controller 实施规格
+
+> **前置条件**：应用必须已开启角色服务。
+
+---
+
+## 1. 注入
+
+```typescript
+import { AuthorizationSDK } from '@lark-apaas/fullstack-nestjs-core';
+
+// AuthorizationSDK 由 AuthZPaasModule 全局注册，直接注入即可
+// SDK 自动从请求上下文获取 appId 和 userId
+constructor(private readonly authzSDK: AuthorizationSDK) {}
+```
+
+## 2. DTO 定义
+
+```typescript
+import type { MemberMutationData, FilterParams, MemberType } from '@lark-apaas/fullstack-nestjs-core';
+
+export class CreateRoleDto {
+  role: { name: string; description?: string; bizID: string };
+  userID?: string;  // 可不传，默认为当前登录用户
+}
+
+export class UpdateRoleDto {
+  role: { name?: string; description?: string };
+  userID?: string;
+}
+
+export class AddMembersDto {
+  members: MemberMutationData;
+  userID?: string;
+}
+
+export class RemoveMembersDto {
+  members: MemberMutationData;
+  userID?: string;
+}
+
+export class SearchDto {
+  query: string;
+  filters?: FilterParams;
+  includeExternalUser?: boolean;
+  includeExternalGroup?: boolean;
+  pageSize?: number;
+  page?: number;
+  userID?: string;
+}
+
+export class ListMembersQueryDto {
+  type?: MemberType;
+  page?: number;
+  pageSize?: number;
+}
+```
+
+## 3. Controller
+
+管理接口可按需改为 `@CanRole(['admin'])`：
+
+```typescript
+import { Controller, Get, Post, Put, Delete, Body, Param, Query } from '@nestjs/common';
+import { AuthorizationSDK } from '@lark-apaas/fullstack-nestjs-core';
+
+@Controller('api/role_manager')
+export class AuthorizationController {
+  constructor(private readonly authzSDK: AuthorizationSDK) {}
+
+  @Get('roles')
+  listRoles() { return this.authzSDK.roles.list(); }
+
+  @Get('roles/:bizID')
+  getRole(@Param('bizID') bizID: string) { return this.authzSDK.roles.get(bizID); }
+
+  @Post('roles')
+  createRole(@Body() dto: CreateRoleDto) { return this.authzSDK.roles.create(dto); }
+
+  @Put('roles/:bizID')
+  updateRole(@Param('bizID') bizID: string, @Body() dto: UpdateRoleDto) {
+    return this.authzSDK.roles.update(bizID, dto);
+  }
+
+  @Delete('roles/:bizID')
+  deleteRole(@Param('bizID') bizID: string) { return this.authzSDK.roles.delete(bizID); }
+
+  @Get('roles/:bizID/members')
+  listMembers(@Param('bizID') bizID: string, @Query() query: ListMembersQueryDto) {
+    return this.authzSDK.members.list(bizID, query);
+  }
+
+  @Post('roles/:bizID/members')
+  addMembers(@Param('bizID') bizID: string, @Body() dto: AddMembersDto) {
+    return this.authzSDK.members.add(bizID, dto);
+  }
+
+  @Post('roles/:bizID/members/batch_remove')
+  removeMembers(@Param('bizID') bizID: string, @Body() dto: RemoveMembersDto) {
+    return this.authzSDK.members.remove(bizID, dto);
+  }
+
+  @Delete('roles/:bizID/members')
+  clearMembers(@Param('bizID') bizID: string) { return this.authzSDK.members.clear(bizID); }
+
+  @Post('search')
+  search(@Body() dto: SearchDto) { return this.authzSDK.search.search(dto); }
+}
+```
+
+## 4. Shared 类型定义
+
+在 `shared/api.interface.ts` 中定义前后端共享的接口类型。SDK 已导出的类型直接 re-export，请求/响应类型与 Controller DTO 对齐。
+
+```typescript
+// shared/api.interface.ts — 角色管理相关类型
+
+// ---- re-export SDK 类型，前后端统一引用 ----
+export type {
+  ForceRoleDTO,
+  RoleMemberDTO,
+  MemberMutationData,
+  MemberType,
+  UserSimpleDTO,
+  DepartmentDTO,
+  DepartmentMutationDTO,
+  ChatSimpleDTO,
+  PresetGroupDTO,
+  SearchResponse,
+  SearchResult,
+  FilterParams,
+  I18nText,
+} from '@lark-apaas/fullstack-nestjs-core';
+
+// ---- 请求类型（与 Controller DTO 一致） ----
+
+/** POST /api/role_manager/roles */
+export interface CreateRoleRequest {
+  role: { name: string; description?: string; bizID: string };
+}
+
+/** PUT /api/role_manager/roles/:bizID */
+export interface UpdateRoleRequest {
+  role: { name?: string; description?: string };
+}
+
+/** POST /api/role_manager/roles/:bizID/members */
+export interface AddMembersRequest {
+  members: MemberMutationData;
+}
+
+/** POST /api/role_manager/roles/:bizID/members/batch_remove */
+export interface RemoveMembersRequest {
+  members: MemberMutationData;
+}
+
+/** POST /api/role_manager/search */
+export interface SearchMembersRequest {
+  query: string;
+  filters?: FilterParams;
+  pageSize?: number;
+  page?: number;
+}
+```
+
+> **注意**：请求类型省略了 `userID` 字段——`userID` 由后端从请求上下文自动注入，前端无需传递。
+
+### 前端 API 层引用示例
+
+```typescript
+// client/src/api/index.ts
+import type {
+  ForceRoleDTO,
+  CreateRoleRequest,
+  UpdateRoleRequest,
+  AddMembersRequest,
+  RemoveMembersRequest,
+  SearchMembersRequest,
+  SearchResponse,
+} from '@shared/api.interface';
+
+export async function getRoles(): Promise<ForceRoleDTO[]> { ... }
+export async function createRole(data: CreateRoleRequest): Promise<void> { ... }
+export async function updateRole(bizID: string, data: UpdateRoleRequest): Promise<void> { ... }
+export async function deleteRole(bizID: string): Promise<void> { ... }
+export async function addRoleMembers(bizID: string, data: AddMembersRequest): Promise<void> { ... }
+export async function removeRoleMembers(bizID: string, data: RemoveMembersRequest): Promise<void> { ... }
+export async function searchMembers(data: SearchMembersRequest): Promise<SearchResponse> { ... }
+```
+
+## 5. 模块注册
+
+创建 `server/modules/role-manager/role-manager.module.ts`，并在 `app.module.ts` 中注册（ViewModule 之前）。
+
+## 错误处理
+
+SDK 内部统一将平台错误转为 `HttpException`，Controller 无需 try-catch：
+
+| 场景 | HTTP 状态码 | 说明 |
+|------|-----------|------|
+| 平台 4xx | 透传 | 参数错误、权限不足、角色不存在等 |
+| 平台 5xx | 502 | 平台内部错误 |
+| HTTP 200 + `status_code !== '0'` | 502 | 平台业务错误（如远程服务不可用） |

package/steering/nestjs-react-fullstack/skills/authz-guide/references/sdk-examples.md

@@ -0,0 +1,90 @@
+# AuthorizationSDK 调用示例
+
+> 完整类型定义见 [sdk-types.md](./sdk-types.md)
+
+```typescript
+// ===================== 角色管理 =====================
+
+// 获取所有角色列表，needMember=true 会在每个角色中附带成员数据
+const roles: ForceRoleDTO[] = await sdk.roles.list({ needMember: true });
+
+// 获取单个角色详情
+const role: ForceRoleDTO = await sdk.roles.get('editor');
+
+// 创建角色，bizID 为角色唯一 key，应用内不可重复
+const created: CreateRoleResponse = await sdk.roles.create({
+  role: { bizID: 'editor', name: '编辑者', description: '可编辑内容' },
+});
+// created.bizID → 'editor', created.apiID → 平台分配的 API 标识
+
+// 更新角色名称或描述
+await sdk.roles.update('editor', { role: { name: '高级编辑者' } });
+
+// 删除角色（⚠️ 包含「企业全员」或「互联网公开」成员的角色不支持删除）
+await sdk.roles.delete('editor');
+
+// ===================== 成员管理 =====================
+// 成员按类型分组传递（MemberMutationData），不是扁平数组
+
+// 添加用户到角色
+await sdk.members.add('admin', {
+  members: { userList: [{ userID: '1826968659245100' }] },
+});
+
+// 添加部门到角色（ID 保持字符串）
+await sdk.members.add('admin', {
+  members: { departmentList: [{ id: '7579138586559286811' }] },
+});
+
+// 添加群组到角色
+await sdk.members.add('admin', {
+  members: { groupChatList: [{ chatID: '123456' }] },
+});
+
+// 设置包含应用开发者（唯一可通过 SDK 修改的特殊范围）
+await sdk.members.add('admin', { members: { isContainsAdmin: true } });
+// 取消包含应用开发者
+await sdk.members.remove('admin', { members: { isContainsAdmin: true } });
+
+// 查询成员列表，不传 type 返回所有类型（用户+部门+群组）
+const membersRes: ListMembersResponse = await sdk.members.list('admin');
+// 响应按类型分组：
+// membersRes.members.userList       → 用户列表
+// membersRes.members.departmentList → 部门列表
+// membersRes.members.groupChatList  → 群组列表
+// membersRes.members.allEmployees   → 是否包含企业全员（只读）
+// membersRes.members.public         → 是否互联网公开（只读）
+// membersRes.members.presetGroup?.isContainsAdmin → 是否包含应用开发者
+// membersRes.total / membersRes.hasMore → 分页信息
+
+// 按类型过滤查询，只获取用户成员
+const userMembers = await sdk.members.list('admin', { type: 'User', pageSize: 20 });
+
+// 从角色移除指定用户
+await sdk.members.remove('admin', {
+  members: { userList: [{ userID: '1826968659245100' }] },
+});
+
+// 清空角色下所有成员
+await sdk.members.clear('admin');
+
+// ===================== 混合搜索 =====================
+// 同时搜索用户、部门、群组，不传 filters 时默认三种类型各 pageSize=20
+
+const searchRes: SearchResponse = await sdk.search.search({
+  query: '张三',
+  pageSize: 20,
+  page: 1,
+});
+
+// 响应按类型分组，分别遍历
+searchRes.result.userResult?.items?.forEach(u =>
+  console.log('用户:', u.name, u.userID, u.avatar),
+);
+searchRes.result.departmentResult?.items?.forEach(d =>
+  console.log('部门:', d.name, d.departmentID),
+);
+searchRes.result.chatResult?.items?.forEach(c =>
+  console.log('群组:', c.name, c.chatID, '成员数:', c.userCount),
+);
+```

package/steering/nestjs-react-fullstack/skills/authz-guide/references/sdk-types.md

@@ -0,0 +1,216 @@
+# AuthorizationSDK 类型定义
+
+> 所有类型均从 `@lark-apaas/fullstack-nestjs-core` 导入。
+
+```typescript
+// ===================== 通用 =====================
+
+interface I18nText {
+  [locale: string]: string;
+}
+
+/** 部门名称的国际化格式（language_code: 2052=zh_cn, 1033=en_us） */
+interface I18nLangItem {
+  language_code: number;
+  text: string;
+}
+
+// ===================== 角色 =====================
+
+interface ForceRoleDTO {
+  id?: number;                    // 数据库自增 ID
+  apiID?: string;                 // 平台 API 标识
+  bizID?: string;                 // 角色唯一 key
+  tenantID?: number;              // 租户 ID
+  name?: string;                  // 角色名称
+  description?: string;           // 角色描述
+  type?: number;                  // 0-普通角色, 1-预置角色
+  source?: string;                // 来源: 'aPaaS' | 'MiaoDa'
+  status?: number;
+  memberScope?: string;           // 'all' | 'custom'
+  envScope?: string;              // 'all' | 'custom'
+  feature?: string;
+  deletedAt?: number;
+  version?: number;
+  createdBy?: number;
+  createdAt?: number;
+  updatedBy?: number;
+  updatedAt?: number;
+  roleMembers?: RoleMemberDTO;    // 仅 needMember=true 时返回
+}
+
+interface ListRolesParams {
+  needMember?: boolean;           // 是否返回成员信息，默认 true
+  userID?: string;       // 可不传，默认为当前登录用户
+}
+
+interface CreateRoleParams {
+  role: {
+    name: string;                 // 角色名称（必填）
+    description?: string;
+    bizID: string;                // 角色唯一 key（必填）
+  };
+  userID?: string;       // 可不传，默认为当前登录用户
+}
+
+interface CreateRoleResponse {
+  bizID: string;                  // 角色唯一 key
+  apiID: string;                  // 平台 API 标识
+}
+
+interface UpdateRoleParams {
+  role: { name?: string; description?: string };
+  userID?: string;       // 可不传，默认为当前登录用户
+}
+
+// ===================== 成员 =====================
+
+type MemberType =
+  | 'User'
+  | 'Department'
+  | 'GroupChat'
+  | 'Tenant'
+  | 'PresetGroup'
+  | 'Public'
+  | 'AllEmployee';
+
+interface UserSimpleDTO {
+  userID?: string;       // 用户 ID
+  name?: I18nText;
+  avatar?: string;
+  email?: string;
+  userType?: string;
+  larkUserID?: number;
+  department?: DepartmentSimpleDTO;
+}
+
+interface DepartmentSimpleDTO {
+  departmentID?: number;
+  larkDepartmentID?: number;
+  name?: I18nText;                // SDK 归一化后统一为 { zh_cn, en_us } 格式
+}
+
+/** 查询响应中的部门（SDK 已将平台的数组格式归一化为 I18nText） */
+interface DepartmentDTO {
+  id?: string;           // 部门 ID
+  name?: I18nText;                // 部门名称，SDK 归一化后统一为 { zh_cn, en_us } 格式
+}
+
+/** 变更入参中的部门（提交接口只需 id） */
+interface DepartmentMutationDTO {
+  id?: string;           // 部门 ID
+}
+
+interface ChatSimpleDTO {
+  chatID?: string;       // 群组 ID
+  name?: I18nText;
+  avatar?: string;
+  isExternal?: boolean;
+}
+
+interface PresetGroupDTO {
+  isContainsAdmin?: boolean;
+}
+
+/** 平台返回的成员数据（list 响应中使用） */
+interface RoleMemberDTO {
+  userList?: UserSimpleDTO[];
+  departmentList?: DepartmentDTO[];
+  groupChatList?: ChatSimpleDTO[];
+  allEmployees?: boolean;         // 是否包含企业全员（只读）
+  public?: boolean;               // 是否互联网公开（只读）
+  presetGroup?: PresetGroupDTO;   // 是否包含应用开发者
+}
+
+/** 用户接口的成员变更数据（add/remove 参数中使用），SDK 内部自动映射 isContainsAdmin 为 presetGroup */
+interface MemberMutationData {
+  userList?: UserSimpleDTO[];
+  departmentList?: DepartmentMutationDTO[];
+  groupChatList?: ChatSimpleDTO[];
+  isContainsAdmin?: boolean;      // 是否包含应用开发者，SDK 内部映射为 presetGroup.isContainsAdmin
+}
+
+interface ListMembersParams {
+  type?: MemberType;              // 不传返回所有类型
+  page?: number;
+  pageSize?: number;
+  userID?: string;       // 可不传，默认为当前登录用户
+}
+
+interface ListMembersResponse {
+  members: RoleMemberDTO;         // 按类型分组
+  total: number;
+  hasMore: boolean;
+}
+
+interface AddMembersParams {
+  members: MemberMutationData;
+  userID?: string;       // 可不传，默认为当前登录用户
+}
+
+interface RemoveMembersParams {
+  members: MemberMutationData;
+  userID?: string;       // 可不传，默认为当前登录用户
+}
+
+// ===================== 搜索 =====================
+
+interface CommonParam {
+  searchable?: boolean;
+  pageSize?: number;
+  offset?: number;
+}
+
+interface FilterParams {
+  userParam?: { commonParam?: CommonParam };
+  departmentParam?: { commonParam?: CommonParam; searchType?: string };
+  chatParam?: { commonParam?: CommonParam };
+}
+
+interface SearchParams {
+  query: string;                  // 关键词（必填）
+  filters?: FilterParams;        // 不传时默认三种类型各 pageSize=20
+  includeExternalUser?: boolean;  // 默认 true
+  includeExternalGroup?: boolean; // 默认 true
+  pageSize?: number;              // 默认 20
+  page?: number;                  // 默认 1
+  userID?: string;       // 可不传，默认为当前登录用户
+}
+
+interface SearchUserEntity {
+  userID?: string;
+  larkUserID?: number;
+  name?: I18nText;
+  avatar?: string;
+  department?: DepartmentSimpleDTO; // 用户所属部门（name 已归一化）
+  userType?: string;
+  email?: string;
+  userStatus?: number;
+}
+
+interface DepartmentEntity {
+  departmentID?: number;
+  larkDepartmentID?: number;
+  name?: I18nText;                // SDK 归一化后统一为 { zh_cn, en_us } 格式
+}
+
+interface SearchChatEntity {
+  chatID?: number;
+  name?: I18nText;
+  avatar?: string;
+  isExternal?: boolean;
+  userCount?: number;
+}
+
+interface SearchResult {
+  userResult?: { total?: number; items?: SearchUserEntity[] };
+  departmentResult?: { total?: number; items?: DepartmentEntity[] };
+  chatResult?: { total?: number; items?: SearchChatEntity[] };
+}
+
+interface SearchResponse {
+  result: SearchResult;
+}
+```
+
+> **部门名称归一化**：平台返回的部门 `name` 有两种格式（`I18nText` 对象或 `[{ language_code, text }]` 数组），SDK 在所有查询接口（`roles.list`、`roles.get`、`members.list`、`search.search`）中已统一归一化为 `I18nText`（`{ zh_cn: "...", en_us: "..." }`），下游直接用 `name?.zh_cn` 取值即可。

package/steering/nestjs-react-fullstack/skills/client-add-aily-web-chat/SKILL.md

@@ -0,0 +1,139 @@
+---
+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」 |