@lark-apaas/coding-steering 0.1.14 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [

package/steering/nestjs-react-fullstack/skills/anycross-forward/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: anycross-forward
+description: "Use when generating client-side code that calls an internal / intranet HTTP API through the platform's built-in `/api/__platform__/http-forward` endpoint. 触发词：anycross, http-forward, http forwarder, 内网转发, 内网接口, 内网 API, 请求内网, 请求内网接口, 调用内网接口, 转发到内网, 请求内部接口"
+steering: true
+steering-topic: anycross_forward
+steering-inclusion: manual
+match-template-name: nestjs-react-fullstack
+available-agents:
+  - Code
+  - Worker
+  - DevOps
+  - Reviewer
+unavailable-agents:
+  - AppInit
+---
+
+# anycross-forward 内网请求转发指南
+
+通过平台内置 `/api/__platform__/http-forward` 端点，从前端把请求转发到客户内网地址。后端 SDK 通过 `PlatformModule.forRoot()` **自动装配**，业务零接入；前端用 `axiosForBackend` 调用即可。
+
+> SDK 不感知代理 / 鉴权 / 隧道。实际通路由部署环境（沙箱 mihomo + iptables）处理，生成代码里**不要**拼 `proxy_group_id` / `jwtToken` / `anycross-host`。
+
+## 一、决策树
+
+```text
+需要从前端发请求？
+    │
+    ├─ 目标是平台内置 capability / Dataloom？
+    │   └─ 是 ──→ 用对应 SDK，不走 forwarder
+    │
+    ├─ 目标是公网公共 API（github.com 等）？
+    │   └─ 是 ──→ 直接 fetch / axios（不走 forwarder）
+    │
+    ├─ 目标是客户内网 HTTP/HTTPS API？
+    │   └─ 是 ──→ ✅ 用 forwarder：axiosForBackend + `/api/__platform__/http-forward`
+    │
+    └─ 目标是 ws:// / file:// / 二进制流 / FormData？
+        └─ 是 ──→ ❌ 当前版本不支持，回退方案见"限制"小节
+```
+
+## 二、Quick reference
+
+| 项           | 值                                                                           |
+| ------------ | ---------------------------------------------------------------------------- |
+| 端点路径     | `ALL /api/__platform__/http-forward`                                     |
+| Query 参数   | `targetUrl` （必填，仅 `http://` / `https://`）                              |
+| 前端 SDK     | `axiosForBackend` from `@lark-apaas/client-toolkit/utils/getAxiosForBackend` |
+| HTTP method  | 透传：GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS                     |
+| Body 形态    | string / JSON-able object（axios 自动序列化） / null                         |
+| Headers      | 自动透传（剔除 hop-by-hop / accept-encoding / host / content-length）        |
+| 响应         | 上游 `status` / `headers` / `data` 原样投射                                  |
+| 默认超时     | 30000 ms（可在 `PlatformModule.forRoot({ httpForwarder })` 改）              |
+| 默认响应上限 | 10485760 bytes (10 MB)                                                       |
+| 鉴权         | SDK **不内置**；业务方在路由上加 `@NeedLogin()` 等 guard                     |
+
+## 三、标准前端代码模板
+
+```ts
+// client/src/api/corp-api.ts
+import { axiosForBackend } from "@lark-apaas/client-toolkit/utils/getAxiosForBackend";
+
+const FORWARD = "/api/__platform__/http-forward";
+const BASE = "http://api.corp.com/v1";
+
+// GET — 拉用户列表
+export async function fetchUsers() {
+  const res = await axiosForBackend.get(FORWARD, {
+    params: { targetUrl: `${BASE}/users` },
+  });
+  return res.data; // 上游真实响应 data
+}
+
+// POST — 创建订单，body 直接传对象
+export async function createOrder(payload: { qty: number }) {
+  const res = await axiosForBackend.post(FORWARD, payload, {
+    params: { targetUrl: `${BASE}/orders` },
+    headers: { "X-Tenant": "demo" }, // 自定义 headers 自动透传上游
+  });
+  return res.data;
+}
+
+// DELETE — 路径参数拼在 targetUrl 上
+export async function deleteOrder(id: string) {
+  await axiosForBackend.delete(FORWARD, {
+    params: { targetUrl: `${BASE}/orders/${id}` },
+  });
+}
+```
+
+## 四、错误处理模板
+
+> ⚠️ 模板的 `GlobalExceptionFilter`（`server/common/filters/exception.filter.ts`）会把 forwarder 抛的 `HttpException` 重新打包为 `{ error: { code: 'BAD_REQUEST' | 'BAD_GATEWAY' | ..., message, details } }`：顶层 `error.code` 是 HTTP 状态映射，**forwarder 自己的业务码（`INVALID_REQUEST` / `UPSTREAM_TIMEOUT` 等）被 `JSON.stringify` 进 `error.details`**，需要 `JSON.parse` 才能拿到。
+
+```ts
+import { axiosForBackend } from "@lark-apaas/client-toolkit/utils/getAxiosForBackend";
+import type { AxiosError } from "axios";
+
+type ForwarderInner = { code?: string; message?: string };
+type ApiError = {
+  error?: { code?: string; message?: string; details?: string };
+};
+
+function parseForwarder(err: unknown): ForwarderInner | undefined {
+  const details = (err as AxiosError<ApiError>)?.response?.data?.error?.details;
+  if (typeof details !== "string") return undefined;
+  try {
+    return JSON.parse(details) as ForwarderInner;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function safeForward(targetUrl: string) {
+  try {
+    const res = await axiosForBackend.get("/api/__platform__/http-forward", {
+      params: { targetUrl },
+    });
+    // 上游 4xx/5xx 也走这里：res.status 是上游真实 status
+    return { ok: true, status: res.status, data: res.data };
+  } catch (err) {
+    // 只有 forwarder 自身错才走 catch
+    const inner = parseForwarder(err);
+    switch (inner?.code) {
+      case "INVALID_REQUEST":
+      case "INVALID_TARGET_PROTOCOL":
+        // targetUrl 缺失 / 格式非法 / 协议非 http(s)
+        return { ok: false, reason: "targetUrl 配置错误" };
+      case "UPSTREAM_TIMEOUT":
+        return { ok: false, reason: "上游 30s 超时" };
+      case "UPSTREAM_UNREACHABLE":
+        // DNS 解析失败 / 连接拒绝 / 网络层不可达；
+        // inner.message 形如 "upstream unreachable (ENOTFOUND)"，括号里是 cause code
+        return { ok: false, reason: inner.message ?? "上游不可达" };
+      case "RESPONSE_TOO_LARGE":
+        return { ok: false, reason: "上游响应 > 10MB" };
+      default:
+        throw err;
+    }
+  }
+}
+```
+
+## 五、生成代码必须遵守的 6 条
+
+1. **路径恒为 `/api/__platform__/http-forward`**，HTTP method 来自调用方，service 透传给上游。
+2. **`targetUrl` 永远放 `params`**，不要拼到 URL 字符串里、不要放 body、不要放 header。
+3. **服务端零接入**——`PlatformModule.forRoot()` 已自动装配 `HttpForwarderModule`，**不要**在用户 `AppModule` 里再写 `HttpForwarderModule.forRoot()`。
+4. **前端只用 `axiosForBackend`**，它已带 401 → `x-login-url` 自动跳转拦截器，**不要**再实现登录跳转。
+5. **响应原样投射**：`res.status` / `res.headers` / `res.data` 都来自上游真实响应。forwarder 自身错被模板 `GlobalExceptionFilter` 包成 `error.response.data.error`，业务码需从 `error.details`（JSON 字符串）里 parse 出来，详见第四节。
+6. **headers 直接走 `headers: {...}`**，无需手剔 `host` / `content-length` / hop-by-hop，service 端会处理。
+
+## 六、Common Mistakes
+
+| ❌ 错误                                                                               | ✅ 正确                                                                                                                        |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `axiosForBackend.post('/api/__platform__/http-forward?targetUrl=...')` 手拼 query | `params: { targetUrl }`，让 axios 做 URL 编码                                                                                  |
+| `axiosForBackend.post(targetUrl, body)` 把 targetUrl 当路径                           | 路径永远 `/api/__platform__/http-forward`，targetUrl 走 `params`                                                           |
+| 用裸 `axios.get('/api/__platform__/http-forward', ...)`（直接 import 'axios'）    | 用 `axiosForBackend`（带 baseURL / 401 拦截器）                                                                                |
+| body 传 `FormData` / `Blob` / 流                                                      | v0.1.0 仅支持 string / JSON-able；二进制走 base64 字符串                                                                       |
+| 上游 4xx/5xx 被当作转发失败                                                           | 上游响应**原样投射**到 `res`；只有 forwarder 自身错才进 catch，业务码在 `error.response.data.error.details`（需 `JSON.parse`） |
+| 用户 `AppModule` 手写 `HttpForwarderModule.forRoot()`                                 | 已被 `PlatformModule` 自动装配，重复注册冲突                                                                                   |
+| 拼 `?targetUrl=...&proxy_group_id=xxx&jwt=yyy` 等自定义参数                           | 部署环境接管路由，SDK 不感知；唯一参数是 `targetUrl`                                                                           |
+| `targetUrl: 'ws://...'` / `'file://...'`                                              | 仅 `http://` / `https://`，否则 `INVALID_TARGET_PROTOCOL`                                                                      |
+| 在生成代码里手动加 `Authorization` 模拟 anycross                                      | 部署环境处理鉴权，业务代码只关心**业务**header                                                                                 |
+| 假设响应可流式读取                                                                    | 当前版本响应统一 utf-8 string，不流式                                                                                          |
+
+## 七、限制（v0.1.0）
+
+- **Body**：仅 `string` / JSON-able object / `null`；不支持 binary / FormData / 流
+- **响应**：统一 utf-8 string；不支持流式 / 二进制下载
+- **不做请求重试**（透传语义，重试由业务方决定）
+- **超时 / 响应上限可配**：业务方可在 `PlatformModule.forRoot({ httpForwarder: { requestTimeoutMs, maxResponseBytes } })` 处覆盖默认值
+- **错误码 contract**：`INVALID_REQUEST` / `INVALID_TARGET_PROTOCOL` / `UPSTREAM_UNREACHABLE` / `UPSTREAM_TIMEOUT` / `RESPONSE_TOO_LARGE`
+
+## 八、相关
+
+- 后端 SDK 实现：`@lark-apaas/nestjs-http-forwarder`
+- 前端 SDK：`axiosForBackend` from `@lark-apaas/client-toolkit/utils/getAxiosForBackend`
+- 自动装配点：`@lark-apaas/nestjs-core` 的 `PlatformModule`
+- 鉴权约束：参见 `user-identity`——forwarder 不内置鉴权，路由级 `@NeedLogin()` 仍生效

package/steering/nestjs-react-fullstack/skills/app-init-feasibility-guide/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: app-init-feasibility-guide
+description: "Use when AppInit or SpecDoc needs a lightweight WHAT-level feasibility and capability-boundary guide for nestjs-react-fullstack apps: feasibility judgment, platform capability boundaries, architecture mode choice, data/integration assumptions, and spec handoff signals. 触发词：AppInit, SpecDoc, 初始化判断, 需求可行性, 能力边界, 轻量可行性指南, WHAT规范, 应用初始化, 规格文档"
+steering: true
+steering-inclusion: always
+steering-topic: tech
+match-template-name: nestjs-react-fullstack
+available-agents:
+  - AppInit
+  - SpecDoc
+---
+
+# AppInit / SpecDoc 可行性与规格指南
+
+本 skill 只提供应用初始化和规格编写所需的 WHAT 级判断信息：需求能否做、应选哪类能力、哪些地方要澄清。不要在 AppInit 或 SpecDoc 阶段加载完整 `coding-guide` 或展开实现细节。
+
+## Quick Reference
+
+| 判断项 | 结论 |
+|--------|------|
+| 企业管理、流程、台账、数据看板、内容工具 | 适合全栈应用 |
+| 静态展示、活动页、无后端状态 | 可做纯前端 |
+| 需要持久化业务数据、权限、通知、统计 | 选全栈 |
+| 飞书集成、AI 能力（生文/生图/识别） | 通过平台插件接入 |
+| 用户身份、角色权限、文件存储 | 平台内置能力 |
+| 实时音视频、长连接、WebSocket/SSE | 不适合，需改交替方案 |
+| 原生客户端、浏览器插件、系统级后台服务 | 超出模板能力边界 |
+
+## Feasibility Decision
+
+```text
+用户需求
+  │
+  ├─ 是企业应用/业务流程/数据管理/看板/内容工具？
+  │    └─ 是：通常可实现
+  │
+  ├─ 仅需页面展示或前端交互，无持久化业务状态？
+  │    └─ 是：纯前端即可
+  │
+  ├─ 需要数据持久化、用户隔离、权限、后端集成或定时任务？
+  │    └─ 是：需要全栈
+  │
+  ├─ 依赖实时双向通信、音视频、游戏级同步或长连接？
+  │    └─ 是：标记为不适合；建议改为轮询、异步任务或非实时替代
+  │
+  └─ 依赖外部系统但接口、凭证、数据源不明确？
+       └─ 需要澄清或在规格中标记假设
+```
+
+## Platform Capabilities
+
+| 能力域 | 可用于规划的范围 |
+|--------|------------------|
+| 前端应用 | 页面、路由、表单、表格、图表、文件预览、交互组件 |
+| 后端服务 | HTTP JSON API：CRUD、聚合统计、业务规则、外部 API 编排 |
+| 数据库 | 应用自有业务数据的持久化、关系建模、查询与统计 |
+| 用户身份 | 登录、当前用户、用户信息展示 |
+| 权限 | 角色可见性、操作权限点位 |
+| 文件 | 前端上传至平台文件服务，后端保存元信息 |
+| 插件集成 | 飞书多维表格、消息、群组、AI 能力等通过插件接入 |
+| 自动化 | 定时任务、数据变更触发、webhook、审批触发 |
+| OpenAPI | 对外 HTTP 接口，需明确鉴权与数据边界 |
+| 内网接口 | 客户内网 HTTP 接口转发，需用户提供目标接口与访问条件 |
+
+## Capability Boundaries
+
+| 不适合直接承诺 | 可替代方向 |
+|---------------|------------|
+| WebSocket、SSE、持续流式响应 | 短轮询、任务状态查询、一次性返回 |
+| 实时多人编辑、毫秒级协同 | 弱实时刷新、提交后同步 |
+| 原生 App、桌面端、浏览器插件 | Web 应用、响应式页面 |
+| 服务端持久写本地文件 | 平台文件服务、数据库、临时 `/tmp` |
+| 无凭证调用受限第三方系统 | 要求用户提供 API、凭证或授权方式 |
+| 自建账号体系绕过平台登录 | 使用平台内置身份与权限 |
+| 多语言 i18n、深浅色主题切换（非平台内置） | 需自行实现并计入工作量；规格中先确认是否必要 |
+
+## Architecture Choice
+
+| 需求特征 | 建议模式 |
+|----------|----------|
+| 无持久化状态、纯展示或前端工具 | 纯前端 |
+| 需要数据存储、用户隔离、后端逻辑 | 全栈 |
+| 涉及文件上传与管理 | 全栈 + 文件服务 |
+| 以飞书多维表格为数据源 | 插件优先；复杂查询场景评估是否同步至本地库 |
+| 需要飞书通知、群组、AI 能力 | 插件集成，标记插件实例需求 |
+| 需要定时或事件驱动的后台处理 | 全栈 + 自动化任务 |
+
+## Data Source Choice
+
+| 数据来源 | 规划原则 |
+|----------|----------|
+| 应用自身创建和维护的数据 | 本地数据库 |
+| 飞书多维表格为既有事实源 | 通过多维表格插件读写 |
+| 多维表格上的统计看板 | 优先使用插件聚合能力，避免全量拉取后计算 |
+| 需要跨表关联、全文搜索、高频读写 | 规划同步至本地数据库后查询 |
+| 外部系统 API | 明确接口、鉴权、网络可达性与失败策略 |
+
+## AppInit Checklist
+
+- 判断需求可行性（可行 / 部分可行 / 不建议），给出一句原因。
+- 明确应用模式：纯前端或全栈。
+- 识别需求中缺失的关键信息：数据源、权限角色、外部依赖。
+- 对不支持的能力给出可替代方向，不包装平台边界。
+- 只做 WHAT 级判断，不输出文件结构、技术选型、代码片段。
+
+## SpecDoc Checklist
+
+- 页面清单：每页目标、主要操作与状态。
+- 数据对象：实体、关键字段、筛选与统计口径。
+- 角色权限：查看、创建、编辑、删除、导出、配置等操作的分配。
+- 集成点：飞书、多维表格、AI、内网接口、OpenAPI、自动化触发。
+- 边界与限制：不支持的能力、外部依赖、数据权限边界。
+- 交给 Code agent 时标明需要加载的专项 skill（表格、表单、图表、插件、权限、文件、自动化）。
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| AppInit 阶段读取完整 `coding-guide` | 使用本轻量规范即可 |
+| 把 HOW 细节写进需求判断 | 只判断可行性、模式、边界和风险 |
+| 对长连接、原生端、实时协作直接承诺 | 标记不适合并给替代方向 |
+| 数据源不清时默认建表或默认接多维表格 | 先澄清事实源，或在规格中写明假设 |
+| 插件能力只写"可以调用" | 标明需要插件实例、授权或用户确认的数据源 |
+| 忽略权限和身份 | 规格中至少列出角色与关键操作权限 |

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

@@ -98,6 +98,9 @@ export class ApiController {
 | 用 `@Public()` 标记公开接口 | `@Public()` 是 no-op；公开接口不需要任何装饰器（opt-in 模式默认放行未标 `@NeedLogin()` 的接口） |
 | 在未标 `@NeedLogin()` 的接口里依赖 `req.userContext.userId` 做业务判断 | 该接口默认放行未登录请求，`userId` 可能为 `undefined`，必须先判空 |
 | 业务层自行返回 401 实现"未登录跳转" | 用 `@NeedLogin()` 让守卫统一处理，确保 `x-login-url` 头被正确写入 |
+| 自建认证传输：自签 JWT 走自定义 `Authorization` / `X-Auth-Token` 头、自定义 cookie、query token | 这些头在妙搭网关转发时**不透传**（白名单只放 `x-suda-csrf-token` / `x-larkgw-suda-webuser` + 标准头），后端必拿不到 → 401，且易被误诊为网关故障。任何自有账号体系/自分配账号需求，身份一律取 `req.userContext`（网关注入，解析自 `x-larkgw-suda-webuser`）、用 `@NeedLogin()` 认证 + 业务角色表授权，不要自签 JWT 走自定义传输 |
+
+> ⚠️ **"去飞书化 / 自分配账号"需求专项**：哪怕用户要"完全自己的账号体系"，登录态仍走平台 `x-larkgw-suda-webuser` 身份，自建的只是"业务角色/资料表"。自签 token 走任何自定义传输通道都会被网关白名单拦掉（必踩 401）。
 
 ---
 

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

@@ -24,6 +24,8 @@ match-template-name: nestjs-react-fullstack
 
 > **⛔ 点位全覆盖**：编写鉴权代码时，必须对照权限设计方案的**功能权限表**，将每个权限点位逐一落实到对应的后端 API（`@CanRole` / `@Can`）和前端入口（`<CanRole>` / `<Can>`），完成后逐行核对确认无遗漏。
 
+> **⛔ 角色来源一律是平台，禁止另搞一套平台不认的权限系统**：多级审批、按城市/部门分权、多角色组合等复杂授权，角色必须是**平台真实角色**（先 `role create` / `role list`，标识与代码对齐）。**消费平台角色的方式不限**——`@CanRole`/`@Can` 是语法糖；在 service 里读 `req.userContext.roles` 再 `roles.includes('admin')` 同样是走平台机制（roles 来自平台），按场景选用即可，**不强制每个 API 都用 `@CanRole`**（注解 cover 不了的细粒度场景就读 `userContext.roles` 自行判断）。**真正要禁止的是绕开平台另起炉灶**：自建任何平行的角色/权限存储（自建角色表 / 角色字段 / 用户名单，不限具体命名）、引用平台上不存在（没 create 过）的角色标识——这些 dev 看似能跑、线上必失效。复杂度用「**平台角色（组合）+ 数据层行级过滤**」表达——例如"审核人只审本城市"=`reviewer` 角色把门 + service 按 `cityBranchId` 过滤；"多级审批"=每级一个平台角色 + 把"当前在第几级"存成业务数据状态。
+
 ### DESIGN 前置步骤
 
 "开启权限服务"/"设计权限体系"/"规划角色"/"升级鉴权模式"/"开启角色服务" → **必须先调用 `rbac_role_manager` tool 的 DESIGN action**，用户确认后再实施。日常"给某功能加权限"不触发 DESIGN。
@@ -42,6 +44,8 @@ const response = await axiosForBackend(config);
 if (response.status === 403) throw new Error('无操作权限，请联系管理员分配角色');
 ```
 
+（403 落 catch 会被吞成通用错误提示如'操作失败请稍后重试'，掩盖真实无权限信号，导致排查方向跑偏）
+
 ### 平台的角色面板入口
 
 **只允许在对话中给其入口链接，严禁写到代码中**：`[角色面板](BaseURL?openPanel=auth)` 或 `[角色面板](?openPanel=auth)`
@@ -52,10 +56,11 @@ if (response.status === 403) throw new Error('无操作权限，请联系管理
 
 ### 核心原则
 
-1. 系统已内置角色权限表，无需建表
+1. 系统已内置角色权限表，**无需也禁止自建任何平行的角色/权限存储**（自建角色表 / 角色字段 / 用户名单等，不限具体命名）——@CanRole 只读平台角色，应用自建的存储对鉴权无效
 2. 统一使用 `useAuth()` 获取 `{ ability, isLoading }`，**禁止** `useAuthAbility` / `useCanRole`（已移除）
 3. 必须处理 `isLoading`——加载期间 `ability.can()` 返回 false，不检查会误判无权限
 4. 创建角色后必须编写鉴权代码，切忌只创建角色不编写代码
+5. **`@CanRole([X])`/`<CanRole roles={[X]}>` 里的 X 必须等于平台实际角色标识（bizID），不能凭语义臆造**——创建角色时用 `miaoda-auth-cli role create --biz-id <X>` 把标识固定成代码要用的值，或先 `miaoda-auth-cli role list` 取实际标识再写代码。若代码写 `'admin'`/`'reviewer'` 但平台分配给用户的角色标识是 `role_xxx`，两者对不上 → 线上恒 403（日志可见 `用户角色 [role_xxx], 需要 [admin, reviewer]`）
 
 ### 前端
 
@@ -110,7 +115,6 @@ import { CanRole } from '@lark-apaas/fullstack-nestjs-core';
 | SDK 调用示例 | [sdk-examples.md](references/sdk-examples.md) |
 
 **关键约束**：
-
 - 成员按类型分组传递（`MemberMutationData`），不是扁平数组
 - `allEmployees`/`public` 只读，包含「企业全员」或「互联网公开」的角色不支持删除
 - `userID` 可不传，默认为当前登录用户
@@ -131,6 +135,7 @@ import { CanRole } from '@lark-apaas/fullstack-nestjs-core';
 
 **必须严格遵循 [dynamic-permission-guide.md](references/dynamic-permission-guide.md) 实施，从 Step 0 开始逐步执行。** 禁止跳步或自由发挥。
 
+
 ---
 
 ## 四、禁止行为清单
@@ -145,6 +150,9 @@ import { CanRole } from '@lark-apaas/fullstack-nestjs-core';
 | 绕过 AuthorizationSDK 自行封装接口 | 必须通过 SDK 操作运行时角色和权限点位 |
 | 升级权限体系时未调用 DESIGN 就编码 | 先调用 DESIGN 产出方案，确认后再动手 |
 | 在业务组件中单独处理 403 | API 层统一拦截 403 |
+| 自建任意平行的角色/权限存储（自建角色表 / 角色字段 / 用户名单，不限具体命名）来做鉴权判断 | @CanRole 只认平台角色，应用自建的存储不会被鉴权读取；角色一律用平台真实角色 |
+| 复杂授权就**另起炉灶搞一套平台不认的权限**（自建角色表 / 引用平台没 create 过的标识 / 写死 user_id 名单） | 角色一律用平台真实角色；消费方式不限（`@CanRole` 或读 `req.userContext.roles` 都行），复杂度用「平台角色 + 数据层行级过滤」表达 |
+| `@CanRole([X])` 的 X 凭语义臆造、与平台角色标识(bizID)不一致 | X 必须 = 平台角色 bizID；`role create --biz-id` 固定标识或 `role list` 取实际标识再写代码 |
 | 在 `.catch()` 或 catch 块中处理 403 | 403 不触发异常，必须在 response 层面检查 `status` |
 
 ---
@@ -154,6 +162,7 @@ import { CanRole } from '@lark-apaas/fullstack-nestjs-core';
 | 问题 | 处理方式 |
 |------|---------|
 | 403 错误 | 明确告知是无权限报错，确认是否符合预期；用 `miaoda-auth-cli` MOCK 模拟角色调试 |
+| 线上 403 但 dev 正常 / 用户"已授权"仍 403 | 先核对两件事：(1) 角色面板授给用户的角色**标识(bizID)** 是否等于代码 `@CanRole` 里的字符串（`miaoda-auth-cli role list` 取实际标识比对）；(2) 是否另搞了一套平台不认的权限（自建角色表 / 引用平台没 create 过的标识 / user_id 名单）绕开平台。两者任一不符即解释 403 |
 | 开发环境授权不生效 | 引导用户使用 `miaoda-auth-cli` MOCK 功能 |
 | 用户要求管理角色 | 开发态：`[角色面板](BaseURL?openPanel=auth)`；运行态：按第二节实施 |
 

package/steering/nestjs-react-fullstack/skills/authz-guide/references/dynamic-permission-guide.md

@@ -25,7 +25,6 @@
 > **前端无需手动配置权限点位获取**：auth-sdk 的 `AuthProvider` 会自动请求内置端点获取当前用户的权限点位，业务侧不需要传任何额外配置。
 
 **关键约束**：
-
 - 权限点位（`authz_permissions` 表）的增删改**由 Agent 通过 DDL 操作**，确保与代码中的 `@Can`/`<Can>` 保持一致
 - 管理页面**只负责角色-点位映射**的勾选/取消，不提供权限点位的 CRUD
 - **⛔ 启用动态权限后禁止使用 CanRole**：所有鉴权（包括管理 API）统一使用 `@Can`/`<Can>`，不允许 CanRole 与 Can 混用
@@ -354,7 +353,6 @@ import { Can } from '@lark-apaas/fullstack-nestjs-core';
 ```
 
 **关键约束**：
-
 - **⛔ 动态权限模式下禁止 `@CanRole`**，所有鉴权（含管理 API）统一用 `@Can`
 - 未注入 `permissionResolver` 时使用 `@Can` 会抛出 500 错误
 - 多权限叠加装饰器：`@Can('read', 'Task') @Can('read', 'User')`
@@ -366,7 +364,6 @@ import { Can } from '@lark-apaas/fullstack-nestjs-core';
 ### 前端 API 函数
 
 在 `client/src/api/index.ts` 中添加**管理页面所需**的请求函数：
-
 - 权限点位查询 API（listPermissions）
 - 角色-权限映射 CRUD API（listRoleMappings / createRoleMapping / deleteRoleMapping）
 
@@ -563,7 +560,6 @@ function ConfigPermissionsDialog({ role, permissions, mappings, open, onOpenChan
 ```
 
 **布局规则**：
-
 - 按 `subject` 分组为可展开/收起的 Accordion 卡片，标题 `Subject中文名 (已开启/总数)`
 - 有已勾选权限的 Subject 默认展开，全未勾选的默认收起
 - 每行：`Checkbox + description + action:subject badge（置灰小字）`
@@ -598,11 +594,9 @@ SDK 内部统一将平台错误转为 `HttpException`，Controller 无需 try-ca
 
 1. 确认编译通过
 2. grep 确认 CanRole 零残留：
-
    ```bash
    grep -r "CanRole\|useCanRole\|ROLE_SUBJECT" --include="*.ts" --include="*.tsx" server/ client/ shared/
    ```
-
    ⛔ 结果必须为空，否则回到 Step 5 继续替换
 3. 逐项对照下方「实现检查表」
 

package/steering/nestjs-react-fullstack/skills/authz-guide/references/management-page-spec.md

@@ -79,7 +79,6 @@ Step 5: 验证
 ### 操作列
 
 每行包含：
-
 - **编辑成员** 按钮（文字按钮）
 - **更多操作** 下拉菜单（`...` 按钮，DropdownMenu），包含：
   - 配置权限（仅动态权限点位模式下显示）
@@ -187,6 +186,7 @@ const members: MemberMutationData = {
 await addRoleMembers(bizID, { members });
 ```
 
+
 ### 4. 编辑角色信息
 
 Dialog 弹窗，编辑角色名称和描述。调用 `sdk.roles.update(bizID, { role: { name, description } })`。
@@ -194,7 +194,6 @@ Dialog 弹窗，编辑角色名称和描述。调用 `sdk.roles.update(bizID, {
 ### 5. 删除角色
 
 删除前必须：
-
 1. 检查 `role.roleMembers?.allEmployees` 或 `role.roleMembers?.public` 是否为 `true`
 2. 若为 `true`，**禁用删除按钮**并通过 tooltip 提示「包含企业全员/互联网公开的角色不支持删除」
 3. 若可删除，弹出二次确认对话框，确认后调用 `sdk.roles.delete(bizID)`
@@ -474,7 +473,6 @@ SDK 内部统一将平台错误转为 `HttpException`，Controller 无需 try-ca
 | 权限点位 | `permissions`（自定义渲染） | 250 | 展示该角色绑定的权限点位 |
 
 渲染规则：
-
 - 每个点位优先展示中文说明（`description`），`action:subject` 作为辅助置灰小字
 - 最多展示 3 个，超出部分用 `+N` Badge + HoverCard 展示剩余
 - 无绑定点位时显示 `--`
@@ -484,7 +482,6 @@ SDK 内部统一将平台错误转为 `HttpException`，Controller 无需 try-ca
 在「更多操作」`...` 下拉菜单中（与「编辑角色信息」「删除角色」同级）新增「配置权限」菜单项，**禁止外露为独立按钮**（与 § 操作列 的排版硬规则对齐）。
 
 点击后打开 Dialog，列出所有权限点位，每行一个 Checkbox + `action:subject` 标识 + 描述：
-
 - **勾选**：调用 `createRoleMapping({ roleKey, permissionId })`
 - **取消勾选**：找到映射记录，调用 `deleteRoleMapping(id)`
 - 操作即时生效，无需保存按钮

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

@@ -3,6 +3,8 @@
 > 完整类型定义见 [sdk-types.md](./sdk-types.md)
 
 ```typescript
+import { logger } from "@lark-apaas/client-toolkit/logger";
+
 // ===================== 角色管理 =====================
 
 // 获取所有角色列表，needMember=true 会在每个角色中附带成员数据
@@ -79,12 +81,12 @@ const searchRes: SearchResponse = await sdk.search.search({
 
 // 响应按类型分组，分别遍历
 searchRes.result.userResult?.items?.forEach(u =>
-  console.log('用户:', u.name, u.userID, u.avatar),
+  logger.info('用户:', u.name, u.userID, u.avatar),
 );
 searchRes.result.departmentResult?.items?.forEach(d =>
-  console.log('部门:', d.name, d.departmentID),
+  logger.info('部门:', d.name, d.departmentID),
 );
 searchRes.result.chatResult?.items?.forEach(c =>
-  console.log('群组:', c.name, c.chatID, '成员数:', c.userCount),
+  logger.info('群组:', c.name, c.chatID, '成员数:', c.userCount),
 );
 ```

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

@@ -1,6 +1,8 @@
 # AuthorizationSDK 类型定义
 
 > 所有类型均从 `@lark-apaas/fullstack-nestjs-core` 导入。
+>
+> **ID 字段语义**（哪个用于飞书 API、哪个禁用、employee_id/open_department_id/open_chat_id 含义）见 [`contacts-service`](../../contacts-service/SKILL.md) skill。下表 `larkUserID`/`larkDepartmentID` 为纯数字内部 ID（禁用），飞书 API 用 `employeeID`/`openDepartmentID`/`openChatID`。
 
 ```typescript
 // ===================== 通用 =====================
@@ -75,25 +77,30 @@ type MemberType =
   | 'AllEmployee';
 
 interface UserSimpleDTO {
-  userID?: string;       // 用户 ID
+  userID?: string;       // 妙搭用户 ID（入库/插件用它）
   name?: I18nText;
   avatar?: string;
   email?: string;
   userType?: string;
-  larkUserID?: number;
+  larkUserID?: number;   // 飞书内部数字 ID，禁用（飞书 API 不认）
   department?: DepartmentSimpleDTO;
+  employeeID?: string;   // 飞书企业内 user_id，调飞书开放平台 API 用它
+  larkID?: string;       // 飞书用户全局唯一 ID（larkUserID 别名），禁用
+  miaodaUserID?: string; // 妙搭用户 ID（userID 别名）
 }
 
 interface DepartmentSimpleDTO {
   departmentID?: number;
-  larkDepartmentID?: number;
+  larkDepartmentID?: number;       // 纯数字内部 ID，禁用
   name?: I18nText;                // SDK 归一化后统一为 { zh_cn, en_us } 格式
+  openDepartmentID?: string;       // 飞书部门 open id（od- 开头），部门统一用它
 }
 
 /** 查询响应中的部门（SDK 已将平台的数组格式归一化为 I18nText） */
 interface DepartmentDTO {
   id?: string;           // 部门 ID
   name?: I18nText;                // 部门名称，SDK 归一化后统一为 { zh_cn, en_us } 格式
+  openDepartmentID?: string;       // 飞书部门 open id（od- 开头）；需后端确认成员部门是否返回
 }
 
 /** 变更入参中的部门（提交接口只需 id） */
@@ -106,6 +113,7 @@ interface ChatSimpleDTO {
   name?: I18nText;
   avatar?: string;
   isExternal?: boolean;
+  openChatID?: string;             // 飞书群组 open id（oc_ 开头），群组统一用它
 }
 
 interface PresetGroupDTO {
@@ -179,19 +187,23 @@ interface SearchParams {
 
 interface SearchUserEntity {
   userID?: string;
-  larkUserID?: number;
+  larkUserID?: number;             // 纯数字内部 ID，禁用
   name?: I18nText;
   avatar?: string;
   department?: DepartmentSimpleDTO; // 用户所属部门（name 已归一化）
   userType?: string;
   email?: string;
   userStatus?: number;
+  employeeID?: string;             // 飞书企业内 user_id，调飞书开放平台 API 用它
+  larkID?: string;                 // larkUserID 别名，禁用
+  miaodaUserID?: string;           // userID 别名
 }
 
 interface DepartmentEntity {
   departmentID?: number;
   larkDepartmentID?: number;
   name?: I18nText;                // SDK 归一化后统一为 { zh_cn, en_us } 格式
+  openDepartmentID?: string;       // 飞书部门 open id（od- 开头）
 }
 
 interface SearchChatEntity {
@@ -200,6 +212,7 @@ interface SearchChatEntity {
   avatar?: string;
   isExternal?: boolean;
   userCount?: number;
+  openChatID?: string;             // 飞书群组 open id（oc_ 开头）
 }
 
 interface SearchResult {