@lark-apaas/coding-steering 0.1.5 → 0.1.6-alpha.0

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.5",
+  "version": "0.1.6-alpha.0",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
-  "files": ["steering"],
+  "files": [
+    "steering"
+  ],
   "scripts": {
     "lint:md": "markdownlint 'steering/**/*.md'"
   },
@@ -14,6 +16,9 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "keywords": ["miaoda", "coding-steering"],
+  "keywords": [
+    "miaoda",
+    "coding-steering"
+  ],
   "license": "MIT"
 }

package/steering/nestjs-react-fullstack/skills/authn-guide/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: authn-guide
+description: "Use when implementing authentication features: @NeedLogin decorator (AuthN is opt-in, public interfaces need no decorator), AuthNPaasGuard flow, or handling 401 errors. 触发词：认证, authn, 身份验证, 登录检查, NeedLogin, Public, 公开接口, AuthNPaasGuard, x-login-url, 401, 未授权"
+steering: true
+steering-topic: authn_guide
+match-template-name: nestjs-react-fullstack
+---
+
+# 身份认证（AuthN）编码指南
+
+本 skill 专注于**接口认证**：装饰器、守卫流程、401 处理。
+
+**用户身份**（`req.userContext` 字段定义、`useCurrentUserProfile`、`AuthNPaasService`、`lark_user_id`、妙搭 ↔ 飞书 ID 转换）请使用 [`user-identity`](../user-identity/SKILL.md) skill。本文也会在认证流程里出现 `req.userContext`，那是守卫语义，**字段含义**仍以 user-identity 为准。
+
+## 一、功能决策树
+
+```text
+用户需求
+    │
+    ├─ 需要标记某些接口必须登录才能访问？
+    │   └─ 是 ──→ 使用 @NeedLogin() 装饰器（第二节）
+    │
+    ├─ 需要让某些接口公开访问？
+    │   └─ 不需要任何装饰器 ──→ AuthNPaasGuard 默认放行未标 @NeedLogin() 的接口
+    │       （`@Public()` 是历史遗留 no-op，不要使用，详见第二节）
+    │
+    ├─ 接口返回 401 / 登录跳转不对？
+    │   └─ 是 ──→ 第四节 · 401 未授权
+    │
+    └─ 想读取当前用户 ID / 角色 / 飞书 ID？
+        └─ 这属于"用户身份"范畴 ──→ 跳到 `user-identity` skill
+```
+
+> **相关技能**：用户身份/ID 转换/userContext 字段参见 `user-identity`；登录/登出/获取用户信息的 Dataloom SDK 操作参见 `client-builtins-user-service`；权限点位鉴权参见 `authz-guide`。
+
+---
+
+## 二、认证装饰器
+
+### 模块注册
+
+`AuthNPaasModule` 已通过 `PlatformModule.forRoot()` 自动注册，**无需手动导入**。模块全局生效，自动注册 `AuthNPaasGuard` 守卫。
+
+### @NeedLogin()
+
+标记接口需要登录。未登录用户访问时，守卫设置 `x-login-url` 响应头并返回 401。
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { NeedLogin } from '@lark-apaas/fullstack-nestjs-core';
+
+// 控制器级别 — 所有路由都需要登录
+@Controller('api/dashboard')
+@NeedLogin()
+export class DashboardController {
+  @Get()
+  getDashboard() { return '仪表板'; }
+}
+
+// 方法级别 — 仅特定路由需要登录
+@Controller('api')
+export class ApiController {
+  @Get('public-data')
+  getPublicData() { return '公开数据'; }
+
+  @Get('private-data')
+  @NeedLogin()
+  getPrivateData() { return '私密数据'; }
+}
+```
+
+### ⚠️ @Public() 是 no-op，不要使用
+
+`@lark-apaas/fullstack-nestjs-core` 仍然 export 了 `@Public()`，但 `AuthNPaasGuard` / `AuthZPaasGuard` 都**不读** `IS_PUBLIC_KEY`，整段是历史遗留死代码。Guard 默认 opt-in：**没标 `@NeedLogin()` 的接口直接放行**——这意味着公开接口本身就不需要任何装饰器。如果项目里有现存的 `@Public()` 用法，可以删掉。
+
+### 认证流程
+
+`AuthNPaasGuard` 是 **opt-in 模式**：未标记 `@NeedLogin()` 的接口默认放行，**公开接口无需任何装饰器**。
+
+```text
+请求 → Gateway 注入 x-larkgw-suda-webuser 头
+     → UserContextMiddleware 解析 → req.userContext { userId, tenantId, appId, loginUrl, ... }
+     → AuthNPaasGuard 检查：
+         有 @NeedLogin() 且无 userId → 设置 x-login-url + 401
+         其他（含未标记的接口）→ 放行
+```
+
+> `req.userContext` 的完整字段表（`userId` / `tenantId` / `roles` / `userName` 等）见 `user-identity` skill 第二节。
+
+---
+
+## 三、禁止行为清单
+
+| 禁止行为 | 正确做法 |
+|---------|---------|
+| 单独注册 `AuthNPaasModule.forRoot()` | 已通过 `PlatformModule.forRoot()` 自动注册，无需手动导入 |
+| 手动实例化 `AuthNPaasGuard` | 模块自动注册为全局守卫，无需手动 `@UseGuards()` |
+| 用 `@Public()` 标记公开接口 | `@Public()` 是 no-op；公开接口不需要任何装饰器（opt-in 模式默认放行未标 `@NeedLogin()` 的接口） |
+| 在未标 `@NeedLogin()` 的接口里依赖 `req.userContext.userId` 做业务判断 | 该接口默认放行未登录请求，`userId` 可能为 `undefined`，必须先判空 |
+| 业务层自行返回 401 实现"未登录跳转" | 用 `@NeedLogin()` 让守卫统一处理，确保 `x-login-url` 头被正确写入 |
+
+---
+
+## 四、常见问题
+
+### 401 未授权
+
+1. 确认接口是否标记了 `@NeedLogin()`
+2. 检查请求是否携带了正确的 Cookie（`credentials: 'include'`）
+3. 确认 Gateway 是否正确注入了 `x-larkgw-suda-webuser` 头
+4. 确认响应头是否包含 `x-login-url`，前端拦截器需读取此头执行跳转
+
+### 登录跳转 URL 错误
+
+1. 检查 `req.userContext.loginUrl` 是否被中间件正确解析
+2. 确认应用部署环境（preview / online）对应的网关配置
+
+### 公开接口被错误地要求登录
+
+1. 检查 Controller 或父级是否打了 `@NeedLogin()`（继承到本方法）；按 opt-in 默认行为，**移除装饰器**接口就会公开
+2. **不要**用 `@Public()` 试图取消登录要求——它是 no-op，对 guard 无影响
+3. 检查是否有自定义 Guard 比 `AuthNPaasGuard` 更早执行并主动拦了未登录请求

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」 |