@lark-apaas/coding-steering 0.1.14 → 0.1.15-alpha.0

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

@@ -43,6 +43,8 @@ match-template-name: nestjs-react-fullstack
 > （范围限定：上一条只约束 `useCurrentUserProfile()` 的消费代码。**项目其他场景** —— 例如调 spark `id_convert`、调飞书通讯录 API —— 出现 `open_id` / `union_id` 是正常且必要的，不在禁止之列。）
 >
 > **严禁**：当 `lark_user_id` 为空时回退到 `user_id` 展示。两套 ID 含义完全不同，回退会误导用户。正确做法是条件渲染：有值则展示，无值则不展示或展示"未关联飞书账号"。
+>
+> **严禁（大整数精度）**：妙搭 `user_id` 与飞书 `lark_user_id` / `employee_id` 虽是"纯数字字符串"，但实为 **I64 大整数（可超 9e15，超出 JS `Number.MAX_SAFE_INTEGER` 53 位安全整数上限）**。跨 JS ↔ SQL / Dataloom / 飞书插件边界一律**按 string 透传**，严禁 `Number()` / `parseInt()` / `+id` 转换——会静默丢精度，把通知/查询打到错误用户。
 
 ---
 
@@ -81,7 +83,7 @@ match-template-name: nestjs-react-fullstack
         └─ 是 ──→ 注入 AuthNPaasService 编写 Controller（第四节，仅适用于 user_id）
 ```
 
-> **相关技能**：接口认证/守卫/401 参见 `authn-guide`；登录/登出/获取用户信息等 Dataloom SDK 操作参见 `client-builtins-user-service`；**"用户能做什么"**（角色/权限点位鉴权）参见 `authz-guide`。本 skill 只解决**"用户是谁"**。
+> **相关技能**：接口认证/守卫/401 参见 `authn-guide`；登录/登出/获取用户信息等 Dataloom SDK 操作参见 `client-builtins-user-service`；**搜人 / 人员·部门·群组选择器返回的 ID 处理与字段获取**（employee_id / open_department_id、禁用字段、id_convert）参见 `contacts-service`；**"用户能做什么"**（角色/权限点位鉴权）参见 `authz-guide`。本 skill 只解决**"用户是谁"**（当前登录用户），其 `lark_user_id` == `employee_id`。
 
 ---
 
@@ -208,7 +210,6 @@ const UserInfoPanel = () => {
 ```
 
 **注意**：
-
 - `lark_user_id` 通过额外异步请求获取，可能晚于 `user_id` 等基础字段就绪
 - 请求失败或用户无对应飞书账号时值为 `undefined`，**必须用条件渲染**
 - `useCurrentUserProfile()` 的返回值里**不存在** `open_id`、`feishu_id`、`openId` 字段——在这个 Hook 的消费代码里飞书 ID 唯一字段名是 `lark_user_id`（仅约束本 Hook；项目其他场景调 spark `id_convert` / 通讯录 API 出现 `open_id` 是正常的）

package/steering/nestjs-react-fullstack/skills_local/coding-guide/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: coding-guide
-description: "项目全局编码规范，必须在任何代码编写、阅读、修改、排查前加载。覆盖：项目结构、目录组织、文件命名、NestJS 后端（MVCS/Drizzle ORM/API 规范/异常处理/用户上下文）、React 19 前端（shadcn/ui/Tailwind/路由/样式/组件规范）、前后端联调（shared 类型/axiosForBackend）、数据库操作、质量保障流程、日志规范。Use when: 编写任意前端或后端代码、新建页面或模块、修改接口或数据库操作、排查编译错误或运行时问题、代码审查、理解项目架构。"
+description: '项目全局编码规范，必须在任何代码编写、阅读、修改、排查前加载。覆盖：项目结构、目录组织、文件命名、NestJS 后端（MVCS/Drizzle ORM/API 规范/异常处理/用户上下文）、React 19 前端（shadcn/ui/Tailwind/路由/样式/组件规范）、前后端联调（shared 类型/axiosForBackend）、数据库操作、质量保障流程、日志规范。Use when: 编写任意前端或后端代码、新建页面或模块、修改接口或数据库操作、排查编译错误或运行时问题、代码审查、理解项目架构。'
 ---
+
 # 项目结构
 
 ## 根目录组织
@@ -96,7 +97,7 @@ shared/ # 前后端共享的目录
   ```typescript
   // ❌ 错误：变量无类型注解 → 回调参数隐式 any → TS7006
   const items = await this.service.getItems();
-  items.map(item => item.name);  // TS7006: item 隐式具有 any 类型
+  items.map((item) => item.name); // TS7006: item 隐式具有 any 类型
 
   // ✅ 正确：变量显式类型 + 回调参数显式类型
   const items: Item[] = await this.service.getItems();
@@ -177,7 +178,6 @@ shared/ # 前后端共享的目录
   项目有三个**聚合文件**：`server/app.module.ts`、`client/src/app.tsx`、`client/src/api/index.ts`。它们是所有业务模块的汇聚入口，**必须由主 agent 在派发任何业务模块任务之前一次性串行预填**，业务模块任务（可能并行执行）**不得编辑**这三个文件。多方并发编辑同一聚合文件会触发 `old_string` mismatch 和 LLM 兜底重写，显著拖慢生成。
 
   **主 agent 预填职责**（规划阶段产出**业务模块清单**后立即执行，任务派发前完成）：
-
   - 清单命名约定：目录名 / 路由 / namespace / `api_prefix` 末段统一 `kebab-case`；`module_class` / 页面组件名统一 `PascalCase`；目录名与模块 `name` 一致
   - **严格串行**编辑以下三个文件（一次一个 tool 调用）：
     - `server/app.module.ts`：在文件顶部追加 `import { UsersModule } from './modules/users/users.module';`，在 `@Module` 的 `imports` 数组里加入 `UsersModule`；`ViewModule` 必须保持 `imports` 数组最后一项（fallback 路由）
@@ -186,7 +186,6 @@ shared/ # 前后端共享的目录
   - 预填完成后才派发业务模块任务；聚合文件引用的符号（`UsersModule` / `UsersPage` / `./users`）在任务产出前暂时悬空，任务完成后自然对齐
 
   **业务模块任务的工作边界**：
-
   - 产出只能落在以下目录之一：`server/modules/<name>/`（Module / Controller / Service / DTO）、`client/src/pages/<name>/`、`client/src/api/<name>/`
   - **禁止编辑** `server/app.module.ts` / `client/src/app.tsx` / `client/src/api/index.ts`（已由主 agent 预填）
   - 跨模块依赖（不涉及聚合文件）：在源 Module 的 `exports` 中导出即可
@@ -194,8 +193,8 @@ shared/ # 前后端共享的目录
 
     ```yaml
     cross_module_needs:
-      - type: extra_module       # 或 extra_route / extra_provider
-        reason: "需要 SharedAuthModule 让 UsersController 使用 @Auth"
+      - type: extra_module # 或 extra_route / extra_provider
+        reason: '需要 SharedAuthModule 让 UsersController 使用 @Auth'
         module_class: SharedAuthModule
         module_file: server/modules/shared-auth/shared-auth.module.ts
     ```
@@ -218,7 +217,7 @@ shared/ # 前后端共享的目录
 **必须使用注入的 Drizzle 实例**，禁止自建连接：
 
 ```typescript
-import { DRIZZLE_DATABASE, type PostgresJsDatabase } from "@lark-apaas/fullstack-nestjs-core";
+import { DRIZZLE_DATABASE, type PostgresJsDatabase } from '@lark-apaas/fullstack-nestjs-core';
 
 @Injectable()
 export class TestService {
@@ -234,21 +233,30 @@ export class TestService {
 // ✅ 条件查询
 const conditions = [];
 if (status) conditions.push(eq(users.status, status));
-const query = conditions.length > 0
-  ? db.select().from(users).where(and(...conditions))
-  : db.select().from(users);
+const query =
+  conditions.length > 0
+    ? db
+        .select()
+        .from(users)
+        .where(and(...conditions))
+    : db.select().from(users);
 ```
 
 - Count 查询：
 
 ```typescript
 // 简单 count
-const result = await this.db.select({ count: count() }).from(users).where(eq(users.status, "active"));
+const result = await this.db
+  .select({ count: count() })
+  .from(users)
+  .where(eq(users.status, 'active'));
 // 子查询 count（关联计数）
-const users = await this.db.select({
-  ...users,
-  postsCount: this.db.$count(posts, eq(posts.authorId, users.id)),
-}).from(users);
+const users = await this.db
+  .select({
+    ...users,
+    postsCount: this.db.$count(posts, eq(posts.authorId, users.id)),
+  })
+  .from(users);
 ```
 
 ### userProfile 自定义类型
@@ -257,11 +265,11 @@ const users = await this.db.select({
 
 ```typescript
 // schema 示例
-export const mockTable = pgTable("mock_table", {
-  adminUser: userProfile("admin_user"), // custom_type, TS 中为 string
+export const mockTable = pgTable('mock_table', {
+  adminUser: userProfile('admin_user'), // custom_type, TS 中为 string
 });
 // 使用示例
-const userId: string = "user123"; // ✅ 显式注解
+const userId: string = 'user123'; // ✅ 显式注解
 await db.insert(users).values({ adminUser: userId });
 await db.select().from(users).where(eq(users.adminUser, userId));
 ```
@@ -273,7 +281,7 @@ await db.select().from(users).where(eq(users.adminUser, userId));
 - **UUID 列 `inArray` 必须显式 `::uuid[]`**：标准 `inArray(col, ids)` 会运行时报 `42809: op ANY/ALL (array) requires array on right side`。
 
   ```typescript
-  where: sql`${tasks.id} = ANY(${ids}::uuid[])`
+  where: sql`${tasks.id} = ANY(${ids}::uuid[])`;
   ```
 
 - **`customTimestamptz` 跨网络后是 string**：service 内查询返回 `Date`，但 API 响应经 JSON 序列化后前端拿到 ISO string。`shared/api.interface.ts` 中 timestamptz 字段声明为 `string`，前端需要 Date 时手动 `new Date(value)`。
@@ -312,9 +320,9 @@ await db.select().from(users).where(eq(users.adminUser, userId));
 
 ## 异常处理
 
-| 分层 | 目标 |
-|------|------|
-| service | 抛出业务异常 |
+| 分层       | 目标                            |
+| ---------- | ------------------------------- |
+| service    | 抛出业务异常                    |
 | controller | 不处理异常，交全局 Error Filter |
 
 ## 当前用户信息
@@ -336,15 +344,6 @@ async createArticle(@Req() req: Request, @Body() dto: CreateArticleDto) {
 }
 ```
 
-## 插件能力（Plugin）
-
-本地开发态**暂不支持** PluginInstance / capability 类插件能力的创建与调用 — 这套链路依赖云端 agent 工具(`plugin_instance` / `get_plugin_ai_json`)与平台下发的 `server/capabilities/` 配置,本地没有等价物。
-
-如果业务用到飞书多维表格、AI 生文/翻译/分类、消息推送等"插件能力"覆盖的场景:
-
-- **数据存储/查询类**(多维表格 CRUD、列表分页、聚合统计):优先用本应用自带的 Postgres + Drizzle,数据可在云端运行时再同步飞书 Base
-- **AI / 飞书消息类**:在云端发布后由平台插件链路承接;本地开发时可先用接口 mock 桩占位
-
 ## 自动化任务
 
 需要设计自动化任务配置与开发时，请调用文档工具召回自动化任务配置与代码编写文档
@@ -371,11 +370,11 @@ async createArticle(@Req() req: Request, @Body() dto: CreateArticleDto) {
 
 本地 dev 跑起来有**两个端口 + 一个前缀**，都由 `.env.local` 里的 env 控制：
 
-| Env | 进程 / 用途 | 默认 | 沙箱 env-pull 下发？ | 备注 |
-|---|---|---|---|---|
-| `CLIENT_DEV_PORT` | vite / rspack dev server | `8080` | ❌ 不下发 | **唯一入口**：serve 前端 + 反代 `/api/*` 给 NestJS + 注入 `x-larkgw-suda-webuser` 模拟登录态。端口被占就 Agent 自己改 `.env.local` |
-| `SERVER_PORT` | NestJS | `3000` | ❌ 不下发 | 仅 vite/rspack 反代用，不直接给 agent / curl 用。端口被占就 Agent 自己改 `.env.local` |
-| `CLIENT_BASE_PATH` | 前端路由 base + 后端 routes.json serve 路径 | `/` | ✅ `/app/<app_id>` | 浏览器 URL 前缀；agent / curl 调 `/api/*` 也必须带这个前缀 |
+| Env                | 进程 / 用途                                 | 默认   | 沙箱 env-pull 下发？ | 备注                                                                                                                               |
+| ------------------ | ------------------------------------------- | ------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `CLIENT_DEV_PORT`  | vite / rspack dev server                    | `8080` | ❌ 不下发            | **唯一入口**：serve 前端 + 反代 `/api/*` 给 NestJS + 注入 `x-larkgw-suda-webuser` 模拟登录态。端口被占就 Agent 自己改 `.env.local` |
+| `SERVER_PORT`      | NestJS                                      | `3000` | ❌ 不下发            | 仅 vite/rspack 反代用，不直接给 agent / curl 用。端口被占就 Agent 自己改 `.env.local`                                              |
+| `CLIENT_BASE_PATH` | 前端路由 base + 后端 routes.json serve 路径 | `/`    | ✅ `/app/<app_id>`   | 浏览器 URL 前缀；agent / curl 调 `/api/*` 也必须带这个前缀                                                                         |
 
 完整入口形态 = `http://localhost:<CLIENT_DEV_PORT><CLIENT_BASE_PATH>/...`。启动日志里
 vite/rspack 打印的 `Local: http://localhost:<port>/...` 才是入口，具体值以 `.env.local`
@@ -413,13 +412,13 @@ NestJS 自己不读 env。直连 NestJS 端口 → header 缺失 → `req.userCo
   和 header，值字面相等才放行。任意非空相等值都行（注意打**client dev port**，不是
   NestJS 端口）：
 
-   ```bash
-   # <PORT> = .env.local 里的 CLIENT_DEV_PORT（常见 8080 / 8001）
-   # <BASE_PATH> = .env.local 里的 CLIENT_BASE_PATH（沙箱下发为 /app/<app_id>，本地裸跑可能为空）
-   curl -H 'Cookie: suda-csrf-token=x' \
-        -H 'X-Suda-Csrf-Token: x' \
-        http://localhost:<PORT><BASE_PATH>/api/notes
-   ```
+  ```bash
+  # <PORT> = .env.local 里的 CLIENT_DEV_PORT（常见 8080 / 8001）
+  # <BASE_PATH> = .env.local 里的 CLIENT_BASE_PATH（沙箱下发为 /app/<app_id>，本地裸跑可能为空）
+  curl -H 'Cookie: suda-csrf-token=x' \
+       -H 'X-Suda-Csrf-Token: x' \
+       http://localhost:<PORT><BASE_PATH>/api/notes
+  ```
 
   **不要**因为撞 403 就去改后端 csrf 中间件或者怀疑业务逻辑 —— csrf 保护是有意的，
   业务本身没问题。
@@ -480,20 +479,20 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 
 ## 官方内置组件
 
-| 组件 | 来源 | 用途 |
-|------|------|------|
-| Table | `@lark-apaas/client-toolkit/antd-table` | 数据表格，**先调 `/table-skill`** |
-| UserSelect/UserDisplay/UserProfile/DepartmentSelect | `business-ui/*` | 用户/部门选择展示 |
-| TiptapEditorComplete | `business-ui/tiptap-editor` | 富文本编辑器 |
-| Streamdown | `components/ui/streamdown` | Markdown/流式渲染 |
+| 组件                                                | 来源                                    | 用途                              |
+| --------------------------------------------------- | --------------------------------------- | --------------------------------- |
+| Table                                               | `@lark-apaas/client-toolkit/antd-table` | 数据表格，**先调 `/table-skill`** |
+| UserSelect/UserDisplay/UserProfile/DepartmentSelect | `business-ui/*`                         | 用户/部门选择展示                 |
+| TiptapEditorComplete                                | `business-ui/tiptap-editor`             | 富文本编辑器                      |
+| Streamdown                                          | `components/ui/streamdown`              | Markdown/流式渲染                 |
 
 ### 组件 Skill 召回规则（强制执行）
 
-| 场景 | Skill | 说明 |
-|------|-------|------|
-| 表单、Form、Zod | `/forms-skill` | Shadcn Form + React Hook Form + Zod |
-| 图表、Chart、ECharts | `/charts-skill` | shadcn/ui + ReactECharts |
-| 表格、Table | `/table-skill` | antd-table |
+| 场景                 | Skill           | 说明                                |
+| -------------------- | --------------- | ----------------------------------- |
+| 表单、Form、Zod      | `/forms-skill`  | Shadcn Form + React Hook Form + Zod |
+| 图表、Chart、ECharts | `/charts-skill` | shadcn/ui + ReactECharts            |
+| 表格、Table          | `/table-skill`  | antd-table                          |
 
 禁止未调用 Skill 直接编写表单/图表/表格代码。
 
@@ -511,15 +510,15 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 
 **零假设原则**：绝不基于假设使用任何子模块。使用任何 `@lark-apaas/client-toolkit` 子模块前**必须**：① 先查询本地已加载的 Skills 或对应包文档 → ② 严格按文档编码。**禁止直接调用 `@lark-apaas/client-toolkit` 任何函数/方法**（不基于查询到的文档）。该库**仅可在前端代码中使用，禁止在后端代码中引用**。
 
-| 功能 | 导入路径 |
-|------|----------|
-| 插件调用（Client） | `import { capabilityClient } from "@lark-apaas/client-toolkit"` |
-| 日志 | `import { logger } from "@lark-apaas/client-toolkit/logger"` |
-| 文件上传下载 | `import { getDataloom } from "@lark-apaas/client-toolkit/dataloom"` |
-| 应用信息 | `import { useAppInfo } from "@lark-apaas/client-toolkit/hooks/useAppInfo"` |
-| 当前用户 | `import { useCurrentUserProfile } from "@lark-apaas/client-toolkit/hooks/useCurrentUserProfile"` |
-| URL 解析 | `import { resolveAppUrl } from "@lark-apaas/client-toolkit/utils/resolveAppUrl"` |
-| 批量用户信息 | `import { UserService } from "@lark-apaas/client-toolkit/tools/services"` |
+| 功能               | 导入路径                                                                                         |
+| ------------------ | ------------------------------------------------------------------------------------------------ |
+| 插件调用（Client） | `import { capabilityClient } from "@lark-apaas/client-toolkit"`                                  |
+| 日志               | `import { logger } from "@lark-apaas/client-toolkit/logger"`                                     |
+| 文件上传下载       | `import { getDataloom } from "@lark-apaas/client-toolkit/dataloom"`                              |
+| 应用信息           | `import { useAppInfo } from "@lark-apaas/client-toolkit/hooks/useAppInfo"`                       |
+| 当前用户           | `import { useCurrentUserProfile } from "@lark-apaas/client-toolkit/hooks/useCurrentUserProfile"` |
+| URL 解析           | `import { resolveAppUrl } from "@lark-apaas/client-toolkit/utils/resolveAppUrl"`                 |
+| 批量用户信息       | `import { UserService } from "@lark-apaas/client-toolkit/tools/services"`                        |
 
 **useCurrentUserProfile** 返回 `Partial<IUserProfile>`，初始为空对象：访问字段用 `?.`，判断加载完成用 `if (!userInfo?.user_id)`。
 
@@ -569,9 +568,9 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 
   ```typescript
   import { resolveAppUrl } from '@lark-apaas/client-toolkit/utils/resolveAppUrl';
-  const shareUrl = resolveAppUrl(`/detail/${id}`);     // ✅ 路由路径→完整 URL
+  const shareUrl = resolveAppUrl(`/detail/${id}`); // ✅ 路由路径→完整 URL
   const fixedUrl = resolveAppUrl(`${origin}/detail/${id}`); // ✅ 自动修正
-  resolveAppUrl('https://other-site.com/page');        // ✅ 外部链接原样返回
+  resolveAppUrl('https://other-site.com/page'); // ✅ 外部链接原样返回
   // ❌ 严禁自行拼接：`${window.location.origin}/detail/${id}`
   ```
 
@@ -605,11 +604,11 @@ return <h1>{data?.title || '未知标题'}</h1>;
 
 为特定功能的顶层容器添加 `data-ai-section-type` 属性：
 
-| 值 | 场景 |
-|----|------|
-| `card-stat` | 横向指标卡容器 |
-| `card-list` | Card 组件的 flex 列表 |
-| `button` | 任意 Button |
+| 值          | 场景                      |
+| ----------- | ------------------------- |
+| `card-stat` | 横向指标卡容器            |
+| `card-list` | Card 组件的 flex 列表     |
+| `button`    | 任意 Button               |
 | `card-menu` | Card 组件的 grid 网格菜单 |
 
 ## 图片规范
@@ -628,23 +627,23 @@ return <h1>{data?.title || '未知标题'}</h1>;
 
 ## 核心功能依赖
 
-| 类别 | 库 |
-|------|-----|
-| 动画 | Framer Motion, GSAP |
-| 日期 | dayjs |
-| 日期选择器 | shadcn Calendar + Popover（禁止 input[type="date"]） |
-| 验证 | zod |
-| 工具函数 | lodash |
-| 样式 | clsx |
-| Excel | xlsx（**仅前端实现，禁止服务端实现**。解析后将结构化数据传到服务端保存） |
-| PDF 导出 | jspdf + html2canvas（**仅前端实现，禁止服务端实现**） |
-| 文件上传 | react-dropzone |
-| 二维码 | qrcode.react |
-| 用户反馈 | sonner |
-| 拖拽 | @dnd-kit/core |
-| 数字动画 | react-countup |
-| Base64 | js-base64 — `import { encode, decode } from 'js-base64'` |
-| 3D 场景 | cobe |
+| 类别       | 库                                                                       |
+| ---------- | ------------------------------------------------------------------------ |
+| 动画       | Framer Motion, GSAP                                                      |
+| 日期       | dayjs                                                                    |
+| 日期选择器 | shadcn Calendar + Popover（禁止 input[type="date"]）                     |
+| 验证       | zod                                                                      |
+| 工具函数   | lodash                                                                   |
+| 样式       | clsx                                                                     |
+| Excel      | xlsx（**仅前端实现，禁止服务端实现**。解析后将结构化数据传到服务端保存） |
+| PDF 导出   | jspdf + html2canvas（**仅前端实现，禁止服务端实现**）                    |
+| 文件上传   | react-dropzone                                                           |
+| 二维码     | qrcode.react                                                             |
+| 用户反馈   | sonner                                                                   |
+| 拖拽       | @dnd-kit/core                                                            |
+| 数字动画   | react-countup                                                            |
+| Base64     | js-base64 — `import { encode, decode } from 'js-base64'`                 |
+| 3D 场景    | cobe                                                                     |
 
 ## 滚动分页最佳实践
 

package/steering/nestjs-react-fullstack/skills_local/openapi-guide/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: openapi-guide
+description: "OpenAPI 对外开放接口编码规范 + docs/openapi.json 产物维护。覆盖鉴权、用户身份、模块组织、OpenAPI 3.0 JSON 的结构与写入规则。Use when: 创建或修改 /openapi 路由、编写对外开放接口、维护 docs/openapi.json。触发词：openapi, 开放接口, 对外接口, 对外 API, open api, openapi controller, docs/openapi.json"
+---
+
+# OpenAPI 对外开放接口编码规范
+
+本规范适用于以 `/openapi` 为前缀的对外开放接口。**除下述差异外，均遵循 `/api` 的接口编码规范**。与 `/api` 的差异速查：
+
+| 维度 | `/api`（内部业务接口） | `/openapi`（对外开放接口） |
+|------|----------------------|--------------------------|
+| 鉴权 | 写操作加 `@NeedLogin()` | **不加** `@NeedLogin()`，鉴权在网关层通过 API Key 完成 |
+| 用户身份 | `req.userContext.userId` 区分用户 | 统一走系统身份，不依赖 `userId` 做业务区分 |
+| Controller 文件 | `xxx.controller.ts` | `xxx.openapi.controller.ts`，放在同一 module 下 |
+| OpenAPI 文档 | 不需要 | **必须**同步维护 `docs/openapi.json`（见下文） |
+
+## 鉴权
+
+`/openapi` 路由的鉴权完全在网关层通过 API Key 完成，Controller 层不需要任何鉴权相关代码。
+
+```typescript
+// ✅ 正确：/openapi 路由不加鉴权装饰器
+@Controller('openapi/orders')
+export class OpenApiOrdersController {
+  @Post()
+  create(@Body() body: CreateOrderRequest) { ... }
+}
+
+// ❌ 错误：给 /openapi 路由加 @NeedLogin()
+@Controller('openapi/orders')
+export class OpenApiOrdersController {
+  @NeedLogin()  // 不需要！
+  @Post()
+  create(@Body() body: CreateOrderRequest) { ... }
+}
+```
+
+## 用户身份
+
+OpenAPI 场景下不区分用户，统一走系统身份。禁止在 `/openapi` Controller 中使用 `req.userContext.userId` 做业务逻辑区分。
+
+```typescript
+// ✅ 正确：不依赖用户身份
+@Get()
+findAll(@Query() query: FindOrdersQuery) {
+  return this.ordersService.findAll(query);
+}
+
+// ❌ 错误：用 userId 过滤数据
+@Get()
+findAll(@Req() req: Request) {
+  return this.ordersService.findByUser(req.userContext.userId);  // OpenAPI 下无意义
+}
+```
+
+## 模块组织
+
+`/openapi` Controller 和 `/api` Controller 放在**同一个 module** 下，共享 Service 层。用文件名 `xxx.openapi.controller.ts` 区分。
+
+```
+modules/orders/
+├── orders.module.ts              # 同时注册两个 Controller
+├── orders.controller.ts          # @Controller('api/orders')      — 内部接口
+├── orders.openapi.controller.ts  # @Controller('openapi/orders')  — 开放接口
+└── orders.service.ts             # 共享业务逻辑
+```
+
+在 `orders.module.ts` 中注册：
+
+```typescript
+@Module({
+  controllers: [OrdersController, OpenApiOrdersController],
+  providers: [OrdersService],
+})
+export class OrdersModule {}
+```
+
+## OpenAPI 文档产物（必须维护）
+
+整个应用所有 `/openapi` 路由**汇总在一份** `docs/openapi.json` 文件里（仓库根目录）。
+
+- 路径 = 仓库根 `docs/openapi.json`
+- 所有 `*.openapi.controller.ts` 的 endpoint 共享这一个文件的 `paths`
+- 新仓库若没有该文件，Agent 自行创建
+- 该文件是对外 OpenAPI 的**权威 spec**（运行时被读取并对外暴露，不是纯文档）——精确性要求高，写错/漏写会直接影响外部调用方
+- 内部 `/api` 路由**不**写进来
+
+## 何时创建/更新
+
+| 修改场景 | 文档动作 |
+|---|---|
+| 新建 `*.openapi.controller.ts` | 在 `docs/openapi.json` 的 `paths` 下新增对应 path 项 |
+| 已有 openapi controller 上增删 endpoint、改方法/路径/参数 | 精准增删/改对应 `paths["/openapi/..."]` 条目 |
+| 修改 `shared/api.interface.ts` 里被 openapi 路由引用的 interface / type | 同步更新所有受影响 path 的 schema |
+| 修改 service 返回值或 drizzle schema，且类型变化反映到 openapi 路由的响应 | 同步更新对应 path 的 responses schema |
+
+> 编辑 service / interface / schema 时本 skill 不会被 file-match 自动注入；此时 `coding-guide` 的 `## API 规范` 第 8 条会提醒 Agent 主动加载本 skill 完成同步。
+
+## 安全更新协议（避免误删其它 path）
+
+单文件聚合场景下最大的风险是 Agent 编辑某个 path 时意外丢掉其它 controller 的 path。**必须**按以下步骤：
+
+1. **先 Read**：完整读入 `docs/openapi.json`
+2. **再 Edit**：用精确 `Edit` 改特定 `"/openapi/<path>": { ... }` 块，不要 `Write` 全文件
+3. **最后自检**：见末尾「写后自检」小节——确认 `paths` 下所有条目都在、且每条都有 `operationId` + `responses`
+
+## 文件格式
+
+顶层结构**固定**：
+
+```json
+{
+  "paths": {
+    "/openapi/<feature>": { <pathItem> },
+    "/openapi/<feature>/{id}": { <pathItem> }
+  }
+}
+```
+
+硬性规定：
+
+- **path 键**写完整绝对路径（含 `/openapi/` 前缀），与 `@Controller(...)` + `@Get/Post/...(...)` 拼接结果一致
+- **不**放 `basePath`、**不**放 `components`、**不**放 `info`/`servers`——所有 schema 内联，中间件会补齐其它顶层字段
+- 每个 operation 对象**必须**有：`operationId`（= controller 方法名，驼峰）、`summary`（一句中文说明）、`responses`（至少 `"200"`）
+- 路径参数、查询参数、请求体、响应体的位置由 controller 装饰器决定（见下）
+- 同一 URL 上的多个 HTTP 方法共用一个 path 键（如 `@Controller('openapi/tickets')` 下的 `@Post()` 与 `@Get()` 都映射到 `/openapi/tickets`，共享 pathItem）
+
+## Controller 装饰器 → OpenAPI 位置
+
+**位置看装饰器，类型看 TS**——两者缺一不可。
+
+| Nest 装饰器 | OpenAPI 位置 | 备注 |
+|---|---|---|
+| `@Body() body: T` | `requestBody.content['application/json'].schema` = `T` 的 schema | `T` 通常是 `shared/api.interface.ts` 的 interface |
+| `@Query('foo') foo: T` | `parameters[]` 一项：`in: 'query'`, `name: 'foo'`, `schema: T`；`?` → `required: false` | 每个 `@Query('x')` 产一项 |
+| `@Query() q: T` | `parameters[]` 每字段一项：`in: 'query'`, `name: <field>`, `schema: <field 类型>` | 整个 interface 被摊平到 query params |
+| `@Param('id') id: T` | `parameters[]` 一项：`in: 'path'`, `name: 'id'`, **`required: true`**, `schema: T` | path 参数恒 `required: true` |
+| `@Headers('x-foo') v: T` | `parameters[]` 一项：`in: 'header'`, `name: 'x-foo'`, `schema: T` | `X-Api-Key` 等鉴权头走网关层，不写进 spec |
+
+## Schema 权威来源
+
+对外接口的请求/响应类型统一在 `shared/api.interface.ts` 用 TS `interface` / `type` 维护，前后端共享。
+
+三层优先级（从高到低）：
+
+1. **`shared/api.interface.ts` 中的 TS interface** — 请求体类型 / controller 返回值类型的唯一权威。从 controller 方法签名找到对应 interface 名称，再递归展开成 JSON Schema。
+2. **controller 方法签名** — 各参数的 TS 类型与方法返回值类型，就是对应 OpenAPI 位置的 schema 来源（装饰器到 OpenAPI 位置的映射见上表）。类型可以是 `shared/api.interface.ts` 里的 interface、primitive、或 controller 文件内的内联类型声明；方法返回值类型即 OpenAPI 响应 schema 所描述的对象。
+3. **drizzle schema** — 仅作字段底层类型的辅助参考；**绝不**用来扩展 interface 里没有的字段（interface 已显式定义对外字段集合；drizzle 里多出来的内部字段如 `userId`/`internalRemark` 不得出现在 `docs/openapi.json` 里）。
+
+若 service 实现与 interface 脱节，属代码 bug；JSON schema 一律以 interface 为准。
+
+## TS → JSON Schema 映射
+
+| TS 写法 | JSON Schema |
+|---|---|
+| `foo: string` | `{ "type": "string" }`，`"foo"` 进 `required` |
+| `foo?: string` / `foo: string \| undefined` | `{ "type": "string" }`，**不**进 `required` |
+| `foo: number` | `{ "type": "number" }` 或 `"integer"`（看 drizzle 是 `integer()` 还是 `real()`） |
+| `foo: boolean` | `{ "type": "boolean" }` |
+| `type X = 'a' \| 'b' \| 'c'` 或直接字面量联合 | `{ "type": "string", "enum": ["a","b","c"] }` |
+| `foo: SomeInterface` | 递归展开 `{ "type": "object", "required": [...], "properties": { ... } }` |
+| `foo: T[]` | `{ "type": "array", "items": <T 的 schema> }` |
+| `foo: Date` | `{ "type": "string", "format": "date-time" }`（序列化多为 ISO 字符串） |
+| `foo: T \| null`（可空，非"可选"） | 在 `T` 的 schema 上加 `"nullable": true`；`"foo"` 仍进 `required` |
+
+## `required` 三个位置
+
+OpenAPI 3.0 里 `required` 按上下文有三种写法，判定依据**统一是 TS `?` 修饰符**。
+
+| 上下文 | 写法 | 放在哪 |
+|---|---|---|
+| Parameter Object（query/path/header） | `"required": true/false` | 参数对象顶层 |
+| RequestBody Object（请求体整体） | `"required": true` | requestBody 顶层 |
+| Object Schema（对象字段） | `"required": ["field1","field2"]` 字段名数组 | object schema 顶层，**不**在每个 property 内 |
+
+## description 与 example
+
+TS interface 本身不带 `description` 和 `example`。**按字段名语义自行生成**，不改 interface 源码或加 JSDoc hack。
+
+- `description`：一句中文解释，聚焦业务含义，别复述类型
+- `example`：选一个**真实合理**的值（`"13800000000"` 而不是 `"xxx"`）
+
+## 深层嵌套省略规则
+
+响应/请求结构很深时允许偷懒：
+
+- **第一层 properties** — 永远不省略
+- **深层嵌套对象** — 允许只写 `{ "type": "object" }` 不列 properties，但**必须**在这一层写 `example`（swagger-ui 合成不到深层）
+- **展开了 properties 的 object** — 不写顶层 `example`（swagger-ui 会从 property-level 合成）
+- **primitive 字段**（string/number/boolean） — 必须写 property-level `example`
+- **数组** — `items` 写一个元素的 schema + example，数组外层不写 `example`（由 `items` 合成）
+
+## 规则表讲不透的片段示例
+
+TS interface 怎么翻译、装饰器映射到 parameter 的哪个 `in`、`required` 怎么标——全部看上面各节的表。**本节只示范规则表替代不了的 3 件事**：混用装饰器形成的 parameters 数组、第一层完整展开 vs 深层对象省略的对照、description / example 的风格。
+
+```json
+{
+  "paths": {
+    "/openapi/tickets/{assigneeId}": {
+      "get": {
+        "operationId": "listByAssignee",
+        "summary": "按受理人查询工单列表（游标分页）",
+        "parameters": [
+          { "in": "path",  "name": "assigneeId", "required": true,
+            "schema": { "type": "string" }, "description": "受理人 ID", "example": "usr_007" },
+          { "in": "query", "name": "priority", "required": false,
+            "schema": { "type": "string", "enum": ["low","normal","urgent"] },
+            "description": "按优先级过滤", "example": "urgent" },
+          { "in": "query", "name": "cursor", "required": false,
+            "schema": { "type": "string" },
+            "description": "游标（首次请求省略）", "example": "tk_abc" }
+        ],
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["items", "hasMore"],
+                  "properties": {
+                    "items": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "description": "Ticket 详情（深层省略，schema 见 example）",
+                        "example": {
+                          "id": "tk_abc", "title": "空调故障报修", "priority": "urgent",
+                          "assigneeCount": 2, "location": { "building": "A 栋", "floor": 3 }
+                        }
+                      }
+                    },
+                    "nextCursor": { "type": "string", "description": "下一页游标（最后一页省略）", "example": "tk_abc" },
+                    "hasMore": { "type": "boolean", "description": "是否还有下一页", "example": true }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+要点：
+
+- **装饰器混用 → parameters 数组**：`@Param('assigneeId') + @Query('priority') + @Query('cursor')` 合并成 3 项 parameter，path 参数 `required: true`、query 参数 `required: false`
+- **第一层完整展开 + 深层对象省略**：响应外层对象展开，`items` / `hasMore` 进 `required` 数组而 `nextCursor` 不进；数组元素是 `Ticket`，这一层用深层省略——`type: 'object'` + `example` 示范元素结构，不重复翻译 Ticket 的 schema
+- **description / example 风格**：一句中文语义（"按优先级过滤" 而非"过滤参数"）、真实合理值（`"usr_007"` / `"tk_abc"` / `"A 栋"`，不是 `"xxx"` / `"foo"`）
+
+## 写后自检（强制）
+
+每次 Write/Edit 完 `docs/openapi.json` 之后，**必须**立即在项目根执行下面这条自检命令。未通过要当场修到通过为止，才视为本次任务完成：
+
+```bash
+node -e "const M=['get','post','put','patch','delete','head','options'];const s=require('fs').readFileSync('docs/openapi.json','utf8');const o=JSON.parse(s);if(!o.paths||typeof o.paths!=='object')throw new Error('missing paths');for(const [p,item] of Object.entries(o.paths))for(const [m,op] of Object.entries(item)){if(!M.includes(m))continue;if(!op.operationId||!op.responses)throw new Error(p+' '+m+' missing operationId/responses');}console.log('ok, '+Object.keys(o.paths).length+' paths');"
+```
+
+覆盖：JSON 语法错 / 顶层缺 `paths` / 某个 operation 缺 `operationId` 或 `responses`；最后打印 path 数量方便和修改前做比对，防止误删。