@lark-apaas/coding-steering 0.1.6-alpha.4 → 0.1.6-alpha.5

package/steering/nestjs-react-fullstack/skills/user-identity/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: user-identity
+description: "Use when getting current user info/profile, displaying user name/avatar/email, converting miaoda userId to lark_user_id, or reading req.userContext fields (userId/roles/tenantId): useCurrentUserProfile, AuthNPaasService, FeishuID conversion. 触发词：用户身份, 用户信息, 用户资料, 当前用户, userProfile, useCurrentUserProfile, 飞书ID, FeishuID, 飞书用户ID, lark_user_id, 用户ID转换, AuthNPaasService, 用户上下文, userContext, userContext.roles, 用户角色, 当前用户角色, 获取请求者角色, 展示用户, 显示用户, 用户面板, 我是谁, 获取用户"
+steering: true
+steering-topic: user_identity
+match-template-name: nestjs-react-fullstack
+---
+
+# 用户身份与上下文
+
+本 skill 专注于**用户身份**：ID 体系、`req.userContext` 字段、`useCurrentUserProfile`、妙搭 ↔ 飞书 ID 转换。
+
+**接口认证**（`@NeedLogin()` 装饰器、`AuthNPaasGuard` opt-in 模式、公开接口处理、401）请使用 [`authn-guide`](../authn-guide/SKILL.md) skill。
+
+## 零、ID 体系警告（CRITICAL）
+
+⚠️ "user_id" 这个字面在本项目里指**三个不同的东西**，必须先区分清楚再写代码：
+
+**作为身份 ID 字段名（指代具体某个用户的 ID 值）：**
+
+| 出现位置 | 实际含义 | 体系 |
+|---|---|---|
+| `useCurrentUserProfile().user_id`、`req.userContext.userId` | 妙搭用户 ID（纯数字字符串） | 妙搭 |
+| `useCurrentUserProfile().lark_user_id`、`AuthNPaasService.getCurrentUserLarkUserId()` 返回值 | 飞书 user_id（== `employee_id`，企业内身份，**无固定前缀**） | 飞书 |
+
+**作为 API 参数的取值（不是一个 ID，而是告诉接口"我传入哪种类型的 ID"）：**
+
+| 出现位置 | 实际含义 |
+|---|---|
+| 飞书 OpenAPI 参数 `user_id_type: 'user_id'`（也可取 `'open_id'` / `'union_id'`） | 字符串字面，与上方的飞书 user_id 字段是一致体系但用途不同 |
+
+**严禁**：把 `useCurrentUserProfile().user_id`（妙搭 ID）直接当飞书 ID 传给飞书 API。飞书 ID 必须通过 `lark_user_id` 字段或 `AuthNPaasService` 获取。
+
+`useCurrentUserProfile()` 返回的字段中涉及**两套完全独立的 ID 体系**，严禁混用或互相回退：
+
+| 字段 | 体系 | 格式 | 说明 |
+|------|------|------|------|
+| `user_id` | 妙搭 | 纯数字字符串 | 妙搭平台用户 ID |
+| `lark_user_id` | 飞书 | 字符串 | 飞书 user_id（== employee_id），通过额外异步请求获取 |
+
+> **严禁**：`useCurrentUserProfile()` 返回值里**没有** `open_id`、`feishu_id`、`openId` 字段——飞书 ID 在这个 Hook 里**只通过 `lark_user_id`** 暴露。如果在本 Hook 的消费代码里看到 `userInfo.open_id` 等写法，属于历史错误，必须改成 `lark_user_id`。
+>
+> （范围限定：上一条只约束 `useCurrentUserProfile()` 的消费代码。**项目其他场景** —— 例如调 spark `id_convert`、调飞书通讯录 API —— 出现 `open_id` / `union_id` 是正常且必要的，不在禁止之列。）
+>
+> **严禁**：当 `lark_user_id` 为空时回退到 `user_id` 展示。两套 ID 含义完全不同，回退会误导用户。正确做法是条件渲染：有值则展示，无值则不展示或展示"未关联飞书账号"。
+
+---
+
+## 一、功能决策树
+
+```text
+用户需求
+    │
+    ├─ 接口认证（@NeedLogin / 公开接口 / 401 / 守卫流程）？
+    │   └─ 跳到 `authn-guide` skill
+    │
+    ├─ 需要在服务端读取当前用户 ID / 租户 / 角色等？
+    │   └─ 是 ──→ req.userContext（第二节）
+    │
+    ├─ 需要在前端展示当前用户信息（名称/头像/邮箱）？
+    │   └─ 是 ──→ useCurrentUserProfile()（第三节）
+    │
+    ├─ 需要获取当前用户的飞书 user_id（即 employee_id，企业内身份）？
+    │   ├─ 后端 ──→ AuthNPaasService.getCurrentUserLarkUserId()（第三节）
+    │   └─ 前端 ──→ useCurrentUserProfile().lark_user_id（第三节）
+    │
+    ├─ 需要批量把 妙搭 userId 转成 飞书 **user_id (employee_id，无前缀)** —— 不是 open_id (`ou_`)、不是 union_id (`on_`)？
+    │   └─ 是 ──→ AuthNPaasService.getBatchLarkUserIds()（第三节）
+    │
+    ├─ 需要 飞书 open_id（`ou_` 开头）/ union_id（`on_` 开头）？
+    │   └─ ⚠️ **AuthNPaasService 不产出 open_id/union_id**，只能 user_id
+    │       └─ 跳到 `feishu` skill 的 `references/id-convert.md`（spark id_convert type 10/11）
+    │
+    ├─ 需要把 飞书 open_id / union_id 反查成 妙搭 userId？
+    │   └─ 跳到 `feishu` skill 的 `references/id-convert.md`（spark id_convert type 20/21）
+    │
+    ├─ 需要把 飞书 user_id（employee_id）反查成 妙搭 userId？
+    │   └─ 无单步方案 ──→ `feishu` skill `references/id-convert.md` "反向两步走"
+    │
+    └─ 需要自定义飞书 ID 转换接口？
+        └─ 是 ──→ 注入 AuthNPaasService 编写 Controller（第四节，仅适用于 user_id）
+```
+
+> **相关技能**：接口认证/守卫/401 参见 `authn-guide`；登录/登出/获取用户信息等 Dataloom SDK 操作参见 `client-builtins-user-service`；**"用户能做什么"**（角色/权限点位鉴权）参见 `authz-guide`。本 skill 只解决**"用户是谁"**。
+
+---
+
+## 二、用户上下文（req.userContext）
+
+`UserContextMiddleware` 解析 Gateway 注入的 `x-larkgw-suda-webuser` 头，把当前用户上下文挂到 `req.userContext`，所有 Controller 均可通过 `@Req() req: Request` 读取。
+
+> 完整的解析→守卫流程见 `authn-guide` skill 第二节"认证流程"。
+
+### 字段表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `userId` | `string` | 妙搭用户 ID |
+| `tenantId` | `number` | 租户 ID |
+| `appId` | `string` | 应用 ID |
+| `loginUrl` | `string` | 登录跳转 URL |
+| `userType` | `string` | 用户类型（如 `_employee`） |
+| `env` | `string` | 环境（如 `preview`、`online`） |
+| `userName` | `string` | 用户名 |
+| `userNameI18n` | `{ zh_cn, en_us, ja_jp }` | 多语言用户名 |
+| `isSystemAccount` | `boolean` | 是否系统账号 |
+| `roles` | `string[] \| null` | 用户角色列表。**未开启权限服务或用户无角色时为 `null`** |
+| `baseUrl` | `string` | 网关内部地址 |
+
+### 服务端读取角色示例
+
+`roles` 字段记录当前用户在应用中的角色列表，可在 Controller 业务逻辑中消费（如根据角色返回不同数据）：
+
+```typescript
+import { Controller, Get, Req } from '@nestjs/common';
+import { Request } from 'express';   // ⚠️ Request 类型必须来自 'express'，不要 import 自 'http' / 'undici' 或漏掉 import
+import { TaskService } from './task.service';   // 按项目实际路径 import 业务 Service
+
+// req.userContext 的类型由 @lark-apaas/fullstack-nestjs-core 通过 declare module 'express' 自动注入到 Request，无需手动声明
+@Controller('api/tasks')
+export class TasksController {
+  constructor(private readonly taskService: TaskService) {}
+
+  @Get()
+  async listTasks(@Req() req: Request) {
+    const roles: string[] | null = req.userContext?.roles ?? null;
+    // roles 示例：['text_editor', 'visitor', 'admin']
+    // ⚠️ 未开启权限服务或用户无角色时为 null
+    if (roles?.includes('admin')) {
+      return this.taskService.findAll();
+    }
+    return this.taskService.findByUser(req.userContext?.userId);
+  }
+}
+```
+
+> **注意**：`roles` 在未开启权限服务或用户无角色时为 `null`，使用前必须做空值处理。
+
+---
+
+## 三、飞书 ID 转换（FeishuID Converter）
+
+### 核心概念
+
+妙搭平台的用户 ID（`userId`）与飞书用户 ID 是两套独立体系。调用飞书 OpenAPI 时需要传入某种飞书侧 ID（`open_id` / `union_id` / `user_id` 任选其一，具体通过哪个参数指定取决于 API：消息 API 用 `receive_id_type`，多数其他 API 用 `user_id_type`，文档协作者用 `member_id_type`）。
+
+`AuthNPaasService` 暴露的飞书 ID 是 **`user_id`**（即 `employee_id`，飞书企业内的用户标识）这一种，且**只支持 妙搭 userId → 飞书 user_id 单向转换**。
+
+> 如果需要 `open_id` / `union_id`，或者需要"飞书 ID → 妙搭 userId"反向，请改用飞书开放平台 `spark id_convert` 接口，参见 `feishu` skill 的 `references/id-convert.md`。
+
+### 后端 API
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { AuthNPaasService } from '@lark-apaas/fullstack-nestjs-core';
+
+@Injectable()
+export class MyService {
+  constructor(private readonly authnService: AuthNPaasService) {}
+
+  async example() {
+    // 获取当前登录用户的飞书 user_id
+    const larkUserId = await this.authnService.getCurrentUserLarkUserId();
+    // => '<飞书 user_id>' | null
+
+    // 批量转换（最多 100 个）
+    const larkUserIds = await this.authnService.getBatchLarkUserIds(['uid1', 'uid2']);
+    // => ['<飞书 user_id>', null]  顺序与输入对应，失败项为 null
+  }
+}
+```
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `getCurrentUserLarkUserId` | `() → Promise<string \| null>` | 从请求上下文获取当前用户的飞书 ID |
+| `getBatchLarkUserIds` | `(userIds: string[]) → Promise<(string \| null)[]>` | 批量转换，最多 100 个，与输入顺序一一对应 |
+
+### 内置接口
+
+模块自动注册了 `GET /api/authnpaas/lark-user-id`，返回当前登录用户的飞书 ID：
+
+```json
+{ "lark_user_id": "<飞书 user_id>" }
+```
+
+### 前端获取
+
+`useCurrentUserProfile()` Hook 已自动调用上述内置接口，返回值中包含 `lark_user_id` 字段：
+
+> 本节示例只涉及 ID 相关字段（`user_id` / `lark_user_id`）和顺手的 `name`。完整返回值（`name` / `avatar` / `email` / `tenantId` 等）见 `client-builtins-user-service` skill。
+
+```typescript
+import { useCurrentUserProfile } from '@lark-apaas/client-toolkit/hooks/useCurrentUserProfile';
+
+const UserInfoPanel = () => {
+  const userInfo = useCurrentUserProfile();
+
+  if (!userInfo?.user_id) return <div>加载中...</div>;
+
+  return (
+    <div>
+      <p>用户名: {userInfo.name}</p>
+      <p>用户 ID: {userInfo.user_id}</p>
+      {userInfo.lark_user_id && <p>飞书用户 ID: {userInfo.lark_user_id}</p>}
+    </div>
+  );
+};
+```
+
+**注意**：
+- `lark_user_id` 通过额外异步请求获取，可能晚于 `user_id` 等基础字段就绪
+- 请求失败或用户无对应飞书账号时值为 `undefined`，**必须用条件渲染**
+- `useCurrentUserProfile()` 的返回值里**不存在** `open_id`、`feishu_id`、`openId` 字段——在这个 Hook 的消费代码里飞书 ID 唯一字段名是 `lark_user_id`（仅约束本 Hook；项目其他场景调 spark `id_convert` / 通讯录 API 出现 `open_id` 是正常的）
+
+---
+
+## 四、自定义飞书 ID 转换接口
+
+当内置接口不满足需求（如需要批量转换），可注入 `AuthNPaasService` 编写自定义 Controller：
+
+```typescript
+import { Controller, Get, Post, Body, HttpCode } from '@nestjs/common';
+import { AuthNPaasService } from '@lark-apaas/fullstack-nestjs-core';
+
+// 生产环境建议加 class-validator 装饰器（如 @IsArray() @IsString({ each: true })
+// @ArrayMaxSize(100)）并启用全局 ValidationPipe；本示例聚焦 AuthNPaas 用法，省略校验
+class BatchConvertDto {
+  userIds!: string[];
+}
+
+@Controller('api/feishu-id')
+export class FeishuIdController {
+  constructor(private readonly authnService: AuthNPaasService) {}
+
+  @Get('current')
+  async getCurrent() {
+    const larkUserId = await this.authnService.getCurrentUserLarkUserId();
+    return { larkUserId };
+  }
+
+  @Post('batch')
+  @HttpCode(200)
+  async batchConvert(@Body() dto: BatchConvertDto) {
+    const larkUserIds = await this.authnService.getBatchLarkUserIds(dto.userIds);
+    return { larkUserIds };
+  }
+}
+```
+
+前端调用示例：
+
+```typescript
+// 获取当前用户飞书 ID
+const { larkUserId } = await request<{ larkUserId: string | null }>({
+  url: '/api/feishu-id/current',
+  method: 'GET',
+});
+
+// 批量转换
+const { larkUserIds } = await request<{ larkUserIds: (string | null)[] }>({
+  url: '/api/feishu-id/batch',
+  method: 'POST',
+  data: { userIds: ['uid1', 'uid2', 'uid3'] },
+});
+```
+
+---
+
+## 五、禁止行为清单
+
+| 禁止行为 | 正确做法 |
+|---------|---------|
+| 在 `useCurrentUserProfile()` 消费代码里使用 `open_id`、`feishu_id`、`openId` 等字段名 | `useCurrentUserProfile()` 中飞书 ID 的**唯一字段名**是 `lark_user_id`（限本 Hook；调 spark `id_convert` / 通讯录 API 出现 `open_id` 正常） |
+| `lark_user_id` 为空时回退到 `user_id` 展示 | 两套 ID 体系完全不同，严禁互相回退。无值时不展示或展示"未关联飞书账号" |
+| 前端直接展示 `lark_user_id` 而不处理空值 | `lark_user_id` 可能为 `undefined`（加载中/获取失败/无飞书账号），必须用条件渲染 |
+| 用 `if (!userInfo)` 判断加载状态 | 初始值为空对象（truthy），必须用 `if (!userInfo?.user_id)` |
+| 手动实例化 `AuthNPaasService` | 通过 NestJS 依赖注入获取：`constructor(private readonly authnService: AuthNPaasService)` |
+| 单独注册 `AuthNPaasModule.forRoot()` | 已通过 `PlatformModule.forRoot()` 自动注册，无需手动导入 |
+| 自行调用平台 `/v1/app/{appId}/account/user/convert` 接口 | 必须使用 `AuthNPaasService` 的方法，内置错误处理和可观测性 |
+| `getBatchLarkUserIds` 传入超过 100 个 ID | 分批调用，每批最多 100 个 |
+| 在前端自行封装飞书 ID 转换请求 | 使用 `useCurrentUserProfile()` 获取当前用户飞书 ID；批量转换通过后端接口 |
+
+---
+
+## 六、常见问题
+
+> 接口 401 / 登录跳转相关问题见 `authn-guide` skill 第四节"常见问题"。
+
+### 飞书 ID 返回 null
+
+1. 确认用户已登录（`req.userContext.userId` 存在）
+2. 确认 `appId` 在请求上下文中存在
+3. 检查平台转换接口是否正常（查看后端日志中 `[batchConvertUserIds]` 相关输出）
+4. 部分用户可能无对应飞书账号，此时转换结果为 null 是预期行为
+
+### 前端 lark_user_id 一直为 undefined
+
+1. 确认后端 `AuthNPaasModule` 已注册（内置接口 `/api/authnpaas/lark-user-id` 可访问）
+2. 检查浏览器开发者工具中该接口的请求和响应
+3. `lark_user_id` 异步加载，确保组件正确处理了加载态

package/steering/nestjs-react-fullstack/skills_local/code-fix/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: code-fix
+description: Use when encountering code errors such as import failures, TypeScript/Dto type mismatches, JSX syntax issues, API call exceptions (traceid troubleshooting), production log troubleshooting that should route through miaoda-cli, route 404 errors, or **lucide-react icon not found / duplicate identifier / barrel-export naming conflicts**. 触发词：导入错误, 模块解析失败, 类型错误, Dto不匹配, JSX语法, API异常, traceid, 线上日志, 线上日志查询, 查询线上日志, 路由404, code fix, debugging, lucide-react import error, icon not found, 图标不存在, Cannot find name, 标识符重复, no-redeclare, export 冲突, 桶导出冲突, dual export, "请修复错误" 通用排错
+steering: true
+steering-topic: code_fix
+match-template-name: nestjs-react-fullstack
+---
+
+
+# 代码问题诊断与修复指南
+
+## 概述
+
+本文档提供开发过程中常见问题的诊断与修复流程，涵盖导入错误、语法问题、API 调用异常、路由配置等。规范性内容请参考 `coding-guide`，React Hook 相关问题请参考 `react-hook-best-practices`。
+
+## 导入和模块错误
+
+### 缺少导入声明
+
+**问题描述**：使用组件或图标时没有正确导入
+
+**解决方案**：
+
+- 使用前务必验证技术栈中组件的可用性
+- 添加正确的导入语句
+- 检查组件是否在当前技术栈中可用
+
+**代码示例**：
+
+```typescript
+// 正确的导入方式
+import { Button } from '@client/src/components/ui/button';
+import { Input } from "@client/src/components/ui/input"
+import { ListPlus, Cake, Home, Building, Twitter } from "lucide-react";
+```
+
+### 导入路径错误诊断
+
+**问题描述**：错误的导入路径导致模块解析失败
+
+**诊断步骤**：
+
+1. 检查是否使用了项目别名（`@client/`、`@server/`、`@shared/`），而非相对路径 `../`
+2. 确认别名对应的实际路径是否正确（如 `@client/` 对应 `client/`）
+3. 验证目标文件是否存在于指定路径
+
+> 路径别名的完整定义请参考 `coding-guide` 的"全局编码约定"部分。
+
+### 组件可用性验证
+
+**问题描述**：使用不存在的组件或错误的导入路径
+
+**解决方案**：
+
+- 严格遵循技术栈文档中的可用组件列表
+- 验证组件是否存在于指定路径
+- 检查组件参数是否匹配
+
+**检查清单**：
+
+- [ ] 导入路径是否正确
+- [ ] 组件是否存在
+- [ ] 组件参数是否匹配
+
+### lucide-react 图标存在性核查
+
+**问题描述**：从 `lucide-react` 导入的图标名拼错或臆造，渲染时得到 `undefined`，触发 React "type is invalid" 或 LSP "Cannot find name"。
+
+**预防规则（写 import 时主动核查，而非事后救援）**：
+
+1. **不确定就查**：图标名不在你已知列表里 → 先 `Read packages/client/lucide-react/iconMappings.json`（或 lucide-react 包的 d.ts 导出列表）确认存在，再写 import
+2. **替换图标必须连同 import 列表一起检查**：把旧图标替换成新图标时，**必须先 grep 当前文件 import 列表**确认新名未已 import，避免触发 LSP "标识符重复" / `no-redeclare`
+3. **LSP 警告是硬约束**：multi_edit / 写代码后看到 LSP 任意 "Cannot find name" / "标识符重复" → **必须先修完警告才能 commit**，禁止带 LSP 错误跑 `commit_task`
+
+### 同名 export 重复（修复 SOP）
+
+**症状**：LSP 报 "标识符 X 重复" / `no-redeclare`。
+
+**修复步骤**：
+
+1. 整个项目 `grep "export.*\bX\b"` 找所有同名 export 一并处理，**不能只改单点**——首次出 bug 时同类常已在多处复制粘贴
+2. 预防规则（跨子组件常量前缀化、行内/桶导出二选一）见 `coding-guide` 的「TypeScript 规范 · 命名约定」与「文件命名约定 · 导入导出」
+
+### 前端 Dto 类型使用错误
+**问题描述**：代码中使用的 Dto 类型属性与实际定义不一致，导致 TypeScript 类型检查报错
+
+**核心原则**：遇到类型错误，先查 `@client/src/api/gen/types.gen.ts` 确认定义，再修改代码
+
+**错误示例**：
+- 示例1： 赋值时缺失必需属性
+```
+Property 'dueDate' is missing in type {...} but required in type 'CreateBorrowRecordDto'
+```
+
+- 示例2：访问不存在的属性
+```
+Property 'avatar' does not exist on type 'LotteryParticipantResponseDto'
+```
+
+- 示例3：导入不存在的类型
+```
+Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponseDto'
+```
+**解决步骤**：
+1. 在 `@client/src/api/gen/types.gen.ts` 中搜索目标Dto实际定义
+2. 确认类型名称是否正确，明确完整定义
+
+**检查清单**：
+- [ ] 已查看 `@client/src/api/gen/types.gen.ts` 中的类型定义
+- [ ] 已对比代码使用与实际定义的差异
+- [ ] 已根据实际定义修正代码
+- [ ] 已验证修改后类型使用正确
+
+## JSX 和语法错误
+
+### 特殊字符转义处理
+
+**问题描述**：JSX 中未转义的特殊字符导致渲染错误
+
+**常见字符**：`<`, `>`, `{`, `}`, `&`, `"`, `` ` ``
+
+**解决方案**：
+
+| 字符 | HTML 实体 | 使用场景 |
+|------|-----------|----------|
+| `<` | `<` | 显示小于号 |
+| `>` | `>` | 显示大于号 |
+| `&` | `&` | 显示与符号 |
+| `"` | `"` | 显示双引号 |
+| `'` | `'` | 显示单引号 |
+
+**代码示例**：
+
+```jsx
+// ✅ 正确的特殊字符处理
+<div>
+  <p>价格: &lt; 100元</p>
+  <p>公司: A &amp; B 科技</p>
+  <p>标题: &quot;Hello World&quot;</p>
+</div>
+
+// ❌ 错误的写法
+<div>
+  <p>价格: < 100元</p>  {/* 会被解析为标签 */}
+  <p>公司: A & B 科技</p>  {/* 可能导致解析错误 */}
+</div>
+```
+
+## API 生成错误
+
+### 调用 API 客户端时参数与预期不符
+
+**问题描述**：调用 API 客户端时发现传参与后端定义不相同
+
+**解决方案**：检查后端 Swagger 注解中是否对 DTO 对象正确做了注解
+
+## 调用生成的 API 异常
+
+### 需要查询线上日志时使用 miaoda-cli
+
+**适用场景**：仅当用户提供 traceid、logid、线上报错、发布错误日志、线上运行日志、线上链路追踪，或排查必须依赖线上前端/后端日志。
+
+**处理要求**：引导并使用 `miaoda-cli` skill 查询线上日志。优先通过 `miaoda observability log/trace` 查询线上运行日志与链路追踪；排查发布错误时使用 `miaoda deploy error-log`。本地开发日志、构建日志、测试日志、浏览器控制台日志不在此范围内，按当前技能或对应工具排查。拿到线上日志后再回到本技能继续定位与修复代码问题。
+
+### 用户提供了 traceid，排查错误
+
+**解决方案**：使用 `miaoda-cli` skill 读取线上前端与后端日志，获取详细错误
+
+**排查示例**：
+
+用户输入：8ae6724e-277e-4d51-afbf-b524b654f27f 看看这个 trace 为什么报错了
+排查路径：
+1. 使用 `miaoda-cli` skill 查询线上服务端与 trace 日志
+2. 根据服务端日志中对应的日志内容修复对应代码逻辑
+
+### 调用 API 客户端时后端返回异常
+
+**解决方案**：检查并修复后端的实现，请勿修改 API 客户端相关代码
+
+**排查示例**：
+
+异常报错如下
+
+```json
+[ERROR]{"type":"HTTP Response","url":"/spark/p/app_4hnezxn4uy49c/api/hello/config","method":"GET","status":500,"statusText":"Internal Server Error","message":"Request failed with status code 500","responseData":{"code":"INTERNAL_ERROR","message":"服务器内部错误","success":false,"data":null,"timestamp":1761048452289,"httpStatus":500,"error":{"code":"INTERNAL_ERROR","message":"服务器内部错误","stack":"Error: 这是测试异常：HelloController.getConfig方法故意抛出的错误\n    at HelloController.getConfig (/home/gem/workspace/dist/server/modules/hello/hello.controller.js:17:15)\n    at /home/gem/workspace/node_modules/@nestjs/core/router/router-execution-context.js:38:29\n    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)"}},"responseTime":283}
+```
+
+排查步骤：
+
+1. 分析错误信息
+
+根据 ERROR 可以得知如下关键信息：
+请求的 URL：/spark/p/app_4hnezxn4uy49c/api/hello/config
+请求 METHOD：GET
+错误信息：服务内部错误
+错误堆栈（可选）：Error: 这是测试异常：HelloController.getConfig方法故意抛出的错误\n    at HelloController.getConfig (/home/gem/workspace/dist/server/modules/hello/hello.controller.js:17:15)\n    at /home/gem/workspace/node_modules/@nestjs/core/router/router-execution-context.js:38:29\n    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
+
+2. 如果错误堆栈存在，优先按照错误堆栈中的相关文件与行列号找到对应文件，读取内容并启发式分析
+3. 如果错误堆栈不存在，按照请求的 URL 找到对应的 controller，检查其中的逻辑，启发式的分析依赖。如发现问题可以直接处理。若仍未发现问题，可以在 controller 抛出的错误对象上增加 `message` 属性，改变 message 内容方便 debug。你可以在增加完之后让用户重新请求触发问题。
+
+```typescript
+try {
+	// some logic
+} catch (err) {
+        // 后端异常必须在后端打印日志
+	this.logger.error('...')
+   	// 后端异常同时需要抛出到前端，方便修复
+	// 构造为 http-errors compatible 的对象
+   	err.statusCode = 500;
+   	err.message = err.stack; // 抛出 stack 信息，保障有足够的错误内容透出
+   	throw err;
+}
+```
+
+注意：优先让错误信息中包含堆栈信息，以更精确的定位错误发生位置。
+
+## 路由和导航问题
+
+### 路由 404 错误诊断
+
+**问题描述**：新页面无法访问或出现 404 错误
+
+**诊断步骤**：
+
+1. 确认页面组件已在 `client/src/app.tsx` 中注册路由
+2. 验证路由路径拼写正确（注意大小写敏感）
+3. 检查导航链接路径与路由定义是否完全匹配
+4. 确认动态路由参数正确传递
+
+> 路由配置规范和导航开发详见 `coding-guide` 的"页面与路由开发规范"部分。
+
+## 性能优化
+
+### React Hook 相关问题
+
+useEffect 无限循环、依赖数组管理、useMemo/useCallback 记忆化等问题，请参考 `react-hook-best-practices` 技能，该技能涵盖 React 19 新特性、派生状态、事件 vs Effect 等完整内容。
+
+## 错误处理快速参考
+
+| 场景 | 做法 | 注意事项 |
+|------|------|----------|
+| 用户反馈 | 使用 `toast` (sonner) 显示友好消息 | 消息简洁、可操作，避免暴露技术细节 |
+| 前端日志 | 使用 `logger` (`@lark-apaas/client-toolkit/logger`) | 禁止 console；参数为 string，对象需 `JSON.stringify` |
+| 后端日志 | 使用 `@nestjs/common` 的 Logger | 禁止 console；参数为 string，对象需 `JSON.stringify` |
+| 业务错误 | 区分预期错误与意外错误 | 预期错误用 `logger.warn`，意外错误用 `logger.error` |
+| 异常处理 | 禁止静默处理异常 | 必须显示明确的错误信息，参考 `coding-guide` 相关规范 |