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

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` 取值即可。