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

package/steering/nestjs-react-fullstack/skills/plugin-guide/references/table.md

@@ -0,0 +1,515 @@
+# 飞书多维表格 (feishu-bitable)
+
+本插件提供了一整套与飞书多维表格进行交互（CRUD + 聚合查询）的接口。
+
+> ⚠️ **前端禁止手写 OAuth**：`feishu-bitable` 内置授权机制，前端通过 `capabilityClient.load(<pluginInstanceId>).call(...)` 调用即可，**禁止**在前端拼 `https://open.feishu.cn/open-apis/authen/v1/...` URL 触发用户跳转——多维表格 `appToken` 不是飞书自建应用的 OAuth `app_id`，混用会让用户看到"请求非法"。详见 SKILL.md `## 外部服务插件 fallback 规则`。
+
+> ⚠️ **业务功能禁用 mock 同步**：依赖本插件的同步函数（如 `syncToFeishu` / `batchSync`）**禁止**用 `setTimeout` + 直接 `successCount = totalRows` 假装写入；plugin 未配置时应明确 `toast.error` + 配置入口指引，不许编一个"假成功"。
+
+## 开发者注意事项
+
+**本文档是为 妙搭助手 设计的技术指南。**
+
+在查看本插件的 Action 时，你将同时获得两部分信息：
+
+1. **本文档 (README)**: 提供高级指引、业务逻辑、使用场景、重要约束。
+2. **Action 的 `inputSchema` 和 `outputSchema`**: 提供精确的 JSON Schema 格式的输入/输出结构。
+
+**请遵循以下原则：**
+
+- **以 `Schema` 为结构基准**：严格按照 `inputSchema` 构建你的输入对象，并参照 `outputSchema` 解析返回结果。
+- **以 `README` 为语义权威**：`README` 中的描述包含了 `Schema` 无法表达的关键信息。**必须优先遵循 `README` 中的指引和约束。**
+
+---
+
+## 重要提醒
+
+**禁止修改插件配置中的任何字段！即使出现字段类型错误或 Action 执行错误也不能修改。**
+
+使用前需读取配置中的 `fields` 字段，了解可操作的字段及其 `bizType`。
+
+## 字段使用规范
+
+1. **使用字段名称而非 ID**：所有操作必须使用 `fields.name`（字段名称），禁止使用字段 ID
+
+2. **选项字段必须严格匹配 enumValues**：`SingleSelect` 和 `MultiSelect` 类型的选项值必须完全参考配置中的 `enumValues`，禁止自行编造
+
+   ```json
+   // 示例：假设字段配置如下
+   {
+     "name": "状态",
+     "bizType": "SingleSelect",
+     "enumValues": ["待处理", "进行中", "已完成"]
+   }
+   // ✅ 正确：使用 enumValues 中的值
+   { "状态": "进行中" }
+   // ❌ 错误：使用不存在的选项
+   { "状态": "处理中" }
+   ```
+
+3. **字段名称可能包含中文或特殊字符**：必须使用括号表示法，禁止点表示法
+
+   ```javascript
+   // ✅ 正确
+   record['状态']
+   record['v1.0版本']
+   { '状态': '进行中', 'v1.0版本': '已发布' }
+
+   // ❌ 错误
+   record.状态        // 语法错误
+   record.v1.0版本    // 会被错误解析
+   ```
+
+4. **特殊字段需特化展示**：Progress（进度条）、Currency（货币符号）、Rating（星级）、DateTime（格式化日期）、Checkbox（勾选图标）、User（头像+名称）、Barcode（条码图形）
+5. **特殊字段需专用录入组件**：SingleSelect/MultiSelect（下拉选择器）、Checkbox（开关）、DateTime（日期选择器）、User（人员选择器）
+
+---
+
+## BizType 字段类型对照表
+
+| 字段类型 | BizType        | 字段类型     | BizType        | 字段类型 | BizType       |
+| -------- | -------------- | ------------ | -------------- | -------- | ------------- |
+| 文本     | `Text`         | 单选         | `SingleSelect` | 附件     | `Attachment`  |
+| 邮箱     | `Email`        | 多选         | `MultiSelect`  | 单向关联 | `SingleLink`  |
+| 条码     | `Barcode`      | 日期         | `DateTime`     | 双向关联 | `DuplexLink`  |
+| 数字     | `Number`       | 复选框       | `Checkbox`     | 查找引用 | `Lookup`      |
+| 进度     | `Progress`     | 人员         | `User`         | 公式     | `Formula`     |
+| 货币     | `Currency`     | 电话号码     | `Phone`        | 地理位置 | `Location`    |
+| 评分     | `Rating`       | 超链接       | `Url`          | 群组     | `GroupChat`   |
+| 创建时间 | `CreatedTime`  | 最后更新时间 | `ModifiedTime` | 创建人   | `CreatedUser` |
+| 修改人   | `ModifiedUser` | 自动编号     | `AutoNumber`   | 按钮     | `Button`      |
+
+---
+
+## BizType 读写格式对照表
+
+**重要**：读取和写入时的数据格式可能不同，必须严格按照下表处理。
+
+### 可写字段
+
+| BizType                                 | 写入格式         | 读取格式           | 说明                     |
+| --------------------------------------- | ---------------- | ------------------ | ------------------------ |
+| `Text`/`Email`/`Barcode`                | `string`         | `{ text: string }` | 写入纯字符串，读取为对象 |
+| `Phone`                                 | `string`         | `string`           | 读写均为字符串           |
+| `Number`/`Progress`/`Currency`/`Rating` | `number`         | `number`           | 数值类型                 |
+| `SingleSelect`                          | `string`         | `string`           | 必须匹配 enumValues      |
+| `MultiSelect`                           | `string[]`       | `string[]`         | 必须匹配 enumValues      |
+| `DateTime`                              | `number`         | `number`           | Unix 时间戳（毫秒）      |
+| `Checkbox`                              | `boolean`        | `boolean \| null`  | 读取时可能为 null        |
+| `User`                                  | `number[]`       | `number[]`         | suda user id 数组        |
+| `Url`                                   | `{ text, link }` | `{ text, link }`   | 读写格式一致             |
+| `Attachment`                            | `string[]`       | 复杂对象           | 写入文件 URL 数组        |
+
+### 只读字段
+
+| BizType                      | 读取格式                                       |
+| ---------------------------- | ---------------------------------------------- |
+| `CreatedTime`/`ModifiedTime` | `number`（时间戳）                             |
+| `CreatedUser`/`ModifiedUser` | `number[]`（user id 数组）                     |
+| `AutoNumber`                 | `{ text: string }`                             |
+| `Formula`                    | `{ bizType: string, value: any }`              |
+| `Location`                   | `{ fullAddress, provinceName, cityName, ... }` |
+| `GroupChat`                  | `[{ groupID, displayName, avatarImageUrl }]`   |
+
+---
+
+## Actions 概览
+
+| Action               | 说明                           |
+| -------------------- | ------------------------------ |
+| `searchRecords`      | 搜索记录，支持筛选、排序、分页 |
+| `getRecord`          | 根据 ID 查询单条记录           |
+| `batchAddRecords`    | 批量新增记录（最多 500 条）    |
+| `batchUpdateRecords` | 批量更新记录（最多 500 条）    |
+| `deleteRecords`      | 批量删除记录（最多 500 条）    |
+| `aggregateQuery`     | 聚合查询，支持分组、聚合计算、筛选、排序、分页 |
+
+> 注意：分析/统计类场景应优先使用 `aggregateQuery`，不要用 `searchRecords` 模拟统计。
+
+### Action 选择决策树
+
+```
+需要什么？
+├─ 查看/编辑单条记录 → getRecord / batchUpdateRecords
+├─ 列表分页浏览 → searchRecords（游标分页，pageToken 翻页）
+├─ 按条件筛选少量记录 → searchRecords + filter + pageSize
+├─ 排行榜 / TOP N → searchRecords + sort + pageSize=N
+├─ 统计数值（计数/求和/平均/最大最小） → aggregateQuery
+├─ 分组统计（按部门/状态等维度） → aggregateQuery + dimensions
+├─ 统计 + 明细下钻 → 聚合用 aggregateQuery，下钻用 searchRecords + filter
+├─ 新增数据 → batchAddRecords
+└─ 删除数据 → deleteRecords
+
+⚠️ 禁止模式：
+❌ searchRecords 拉全量 → 内存 reduce/filter 做统计 → 必须用 aggregateQuery
+❌ searchRecords 拉全量 → sort → slice 取 TOP N → 必须用 searchRecords + sort + pageSize
+❌ searchRecords 拉全量 → find 找单条 → 必须用 getRecord
+```
+
+## 数据分析类Action补充说明
+
+`aggregateQuery` 用于分组聚合统计，支持 dimensions（分组维度）和 measures（聚合计算）。
+
+### 输入参数
+
+- **dimensions 支持的 bizType**：`Text`、`Email`、`Barcode`、`Number`、`Progress`、`Currency`、`Rating`、`SingleSelect`、`MultiSelect`、`DateTime`、`CreatedTime`、`ModifiedTime`、`Checkbox`、`User`、`CreatedUser`、`ModifiedUser`
+
+### 输出结构
+
+- 返回 `{ result, hasMore, pageToken }`
+- `result` 是聚合结果数组，每个元素是对象，key 对应 dimensions/measures 中声明字段，value 结构为 `{ value: <actual_value> }`
+
+### dimensions value 类型（常见）
+
+- `Text` / `Email` / `Barcode`: `{ text: string }`
+- `Number`: `string`
+- `Progress`: `string`
+- `Currency`: `string`
+- `Rating`: `string`
+- `SingleSelect`: `string`
+- `MultiSelect`: `string[]`
+- `DateTime` / `CreatedTime` / `ModifiedTime`: `string`（按多维表格配置格式）
+- `Checkbox`: `string`（`"true"` / `"false"`）
+- `User`: `Array<{ id, name }>`
+- `CreatedUser` / `ModifiedUser`: `{ id, name }`
+
+### measures value 类型
+
+- 所有 measures 的 `value` 都是 `number`
+
+### measures 支持的 bizType
+
+| aggregation | 支持的 bizType | 不支持 |
+|-------------|---------------|--------|
+| `count` | 所有类型（但只统计非空值，统计总行数建议用不会为空的 Number 字段） | - |
+| `sum` / `avg` | `Number`、`Currency`、`Progress`、`Rating` | **`Formula`**、`Text` |
+| `max` / `min` | `Number`、`Currency`、`DateTime` | `Formula`、`Text` |
+
+### filter
+
+aggregateQuery 的 filter 格式与 searchRecords **完全相同**，遵循下方"搜索过滤条件规则"章节的所有规则。
+
+### expandArrayDimension
+
+- `expandArrayDimension=true` 时会先展开数组维度再聚合统计
+- 典型场景：`MultiSelect`、`User`
+
+---
+
+## 代码示例
+
+```typescript
+import { capabilityClient } from '@lark-apaas/client-toolkit';
+
+// 搜索记录
+const response = await capabilityClient.load('plugin_instance_id').call<{
+  records: Array<{ id: string; record: Record<string, any> }>;
+  hasMore: boolean;
+  pageToken?: string;
+  total: number;
+}>('searchRecords', {
+  filter: {
+    conjunction: 'and',
+    conditions: [{ fieldName: '状态', operator: 'is', value: ['进行中'] }],
+  },
+  pageSize: 20,
+});
+
+// ⚠️ 响应数据直接从 response 访问，不要加 .data 或 .output 前缀
+// ✅ 正确：response.records / response.hasMore / response.total / response.pageToken
+// ❌ 错误：response.data.records / response.data.output.records
+const { records, hasMore, total, pageToken } = response;
+console.log(`共 ${total} 条，本页 ${records.length} 条，还有更多: ${hasMore}`);
+
+// 获取单条记录
+const detail = await capabilityClient.load('plugin_instance_id').call<{
+  id: string;
+  record: Record<string, any>;
+}>('getRecord', { recordID: 'recXXX' });
+// ✅ 正确：detail.id / detail.record
+// ❌ 错误：detail.data.output.id
+const title = detail.record['标题']?.text;
+
+// 批量新增（注意：写入时用写入格式，字段名必须用引号包裹）
+await capabilityClient.load('plugin_instance_id').call('batchAddRecords', {
+  records: [
+    {
+      record: {
+        文本字段: '内容', // Text: string（非 { text: string }）
+        数字字段: 100, // Number: number
+        单选字段: '选项A', // SingleSelect: string（必须匹配 enumValues）
+        多选字段: ['标签1', '标签2'], // MultiSelect: string[]
+        复选框: true, // Checkbox: boolean
+        日期字段: Date.now(), // DateTime: number (毫秒时间戳)
+        人员字段: [123456, 789012], // User: number[] (suda user id)
+        超链接: { text: '链接文本', link: 'https://example.com' }, // Url
+      },
+    },
+  ],
+});
+
+// 批量更新
+await capabilityClient.load('plugin_instance_id').call('batchUpdateRecords', {
+  records: [{ id: 'record_id', record: { 文本字段: '新内容' } }],
+});
+
+// 删除记录
+await capabilityClient
+  .load('plugin_instance_id')
+  .call('deleteRecords', { recordIDs: ['id1', 'id2'] });
+
+// 读取时注意格式差异
+const textValue = record.record['文本字段']?.text; // 读取时是 { text: string }
+const numberValue = record.record['数字字段']; // number
+const userIds = record.record['人员字段']; // number[]
+
+// 聚合查询
+const aggResp = await capabilityClient
+  .load('plugin_instance_id')
+  .call<{ result: Array<Record<string, { value: unknown }>> }>('aggregateQuery', {
+    dimensions: ['region'],
+    measures: [{ fieldName: 'order_id', aggregation: 'count', alias: 'order_count' }],
+    sort: [{ fieldName: 'region', desc: false }],
+    pageSize: 100,
+  });
+
+const chartData =
+  aggResp.result?.map((item) => ({
+    region: String(item.region?.value || ''),
+    order_count: Number(item.order_count?.value || 0),
+  })) || [];
+```
+
+## 代码实现注意事项
+
+1. **响应数据直接访问，禁止猜测嵌套路径**。`capabilityClient.call()` 返回的就是最终数据，直接用 `response.records`、`response.total` 等。**禁止**加 `.data`、`.output`、`.data.output` 等前缀。如果不确定响应结构，先用 `console.log` 打印完整响应再编码，禁止凭猜测修改数据路径。
+2. 在进行写入操作时，比如确认提交时，应该有loading效果，禁止用户重复点击。
+3. 如果capabilityClient call失败，命中了error逻辑，要打印日志，同时把error message提示给用户。
+4. 在进行更新操作时，只更新需要更新的字段即可，不需要对全量字段进行更新。
+5. **分页必须使用游标分页，禁止全量拉取后切片**。先拉全部数据再 `slice` 会导致性能极差、浪费带宽和内存。每次只拉当前页数据，通过 `pageToken` 翻页：
+
+   ```typescript
+   const result = await capabilityClient.load(pluginInstanceId).call('searchRecords', {
+     pageSize: 10,
+     pageToken: cursor, // 上一页返回的 pageToken
+   });
+   // 返回：{ records, pageToken（下一页游标）, hasMore, total }
+   ```
+
+---
+
+## 推荐 UI 组件
+
+| BizType                      | 展示                                                                  | 录入                                        |
+| ---------------------------- | --------------------------------------------------------------------- | ------------------------------------------- |
+| `User`                       | `<UserDisplay users={ids.map(id => ({ user_id: id.toString() }))} />` | `<UserSelect multiple />`                   |
+| `Url`                        | `<Hyperlink value={val} readOnly />`                                  | `<Hyperlink readOnly={false} />`            |
+| `SingleSelect`/`MultiSelect` | 文本/标签                                                             | `<Select>` 选项来自 enumValues              |
+| `DateTime`                   | `new Date(ts).toLocaleDateString()`                                   | `<Input type="date" />`                     |
+| `Checkbox`                   | `value ? '是' : '否'`                                                 | `<Checkbox />`                              |
+| `Currency`                   | `¥${value.toFixed(2)}`                                                | `<Input type="number" />`                   |
+| `Progress`                   | `${value}%` 或进度条                                                  | `<Input type="number" min={0} max={100} />` |
+| `Rating`                     | `'★'.repeat(value) + '☆'.repeat(5-value)`                             | `<Input type="number" min={0} max={5} />`   |
+
+### 组件代码示例
+
+```tsx
+// 人员展示
+<UserDisplay
+  users={record['人员字段']?.map(userId => ({ user_id: userId.toString() })) || []}
+  size="small"
+  showLabel={true}
+/>
+
+// 人员录入（多选）
+<UserSelect
+  multiple
+  value={userIds.map(String)}
+  onChange={(val) => setUserIds(val.map(Number))}
+  placeholder="请选择人员"
+/>
+
+// 人员录入（单选）— 注意：单选时 value 是 string | null，不是数组
+// 不要传 accountType="lark"，否则返回 larkUserID 与多维表格的 userID 不匹配
+<UserSelect
+  value={formData.assignee || null}
+  onChange={(val) => setFormData({ ...formData, assignee: val || '' })}
+  placeholder="请选择负责人"
+/>
+
+// 超链接展示/录入
+<Hyperlink
+  value={record['超链接']}
+  onChange={(val) => setHyperlink(val)}
+  readOnly={false}
+  placeholder={{ text: "链接文本", link: "https://example.com" }}
+/>
+
+// 单选下拉（选项必须来自 enumValues）
+<Select value={value} onValueChange={setValue}>
+  <SelectTrigger><SelectValue placeholder="请选择" /></SelectTrigger>
+  <SelectContent>
+    {enumValues.map(opt => (
+      <SelectItem key={opt} value={opt}>{opt}</SelectItem>
+    ))}
+  </SelectContent>
+</Select>
+```
+
+---
+
+## 表格列渲染示例
+
+```tsx
+const columns = [
+  // 文本字段 - 注意读取格式是 { text: string }
+  { title: '文本', dataIndex: ['record', '文本字段', 'text'], key: 'text' },
+  // 人员字段 - 使用 UserDisplay 组件
+  {
+    title: '负责人',
+    key: 'user',
+    render: (_, record) => (
+      <UserDisplay
+        users={record.record['人员字段']?.map((id) => ({ user_id: id.toString() })) || []}
+        size="small"
+      />
+    ),
+  },
+  // 日期字段 - 格式化显示
+  {
+    title: '创建日期',
+    dataIndex: ['record', '日期字段'],
+    key: 'date',
+    render: (v) => (v ? new Date(v).toLocaleDateString() : '-'),
+  },
+  // 货币 - 格式化显示
+  {
+    title: '金额',
+    dataIndex: ['record', '货币字段'],
+    key: 'currency',
+    render: (v) => (v != null ? `¥${v.toFixed(2)}` : '-'),
+  },
+  // 超链接 - 使用 Hyperlink 组件
+  {
+    title: '链接',
+    key: 'hyperlink',
+    render: (_, record) => <Hyperlink value={record.record['超链接']} readOnly />,
+  },
+  // 多选 - 逗号分隔显示
+  {
+    title: '标签',
+    dataIndex: ['record', '多选字段'],
+    key: 'multiSelect',
+    render: (v) => v?.join(', ') || '-',
+  },
+];
+```
+
+---
+
+## 搜索过滤条件规则
+
+### 核心规则
+
+1. **value 始终是字符串数组**：数字需转为字符串，如 `["23.4"]`
+2. **空值判断**：`isEmpty`/`isNotEmpty` 时 value 填 `[]`
+3. **Formula 字段不支持筛选**
+4. **Text 字段 `is`/`isNot` 的 value 只能传一个元素**（见下方常见错误）
+
+### 各 BizType 的 value 格式与支持的操作符
+
+| BizType                                              | value 格式                                              | 支持的操作符                                                                                   |
+| ---------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `Text`/`Email`/`Barcode`/`Phone`                     | `["内容"]`（只能一个元素）                              | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Number`/`Currency`/`Progress`/`Rating`/`AutoNumber` | `["23.4"]`（数字转字符串）                              | `is`, `isNot`, `isGreater`, `isGreaterEqual`, `isLess`, `isLessEqual`, `isEmpty`, `isNotEmpty` |
+| `SingleSelect`/`MultiSelect`                         | `["选项A", "选项B"]`（`is`/`isNot` 填一个，其他可多个） | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Checkbox`                                           | `["true"]` 或 `["false"]`                               | `is`（仅此一个）                                                                               |
+| `User`/`CreatedUser`/`ModifiedUser`                  | `["123456"]`（suda user id）                            | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Url`                                                | `["显示名称"]`（填显示文本，非 URL）                    | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `GroupChat`                                          | `["328472133423"]`（群组 ID）                           | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Location`                                           | `["地址文本"]`（只能一个元素）                          | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Attachment`                                         | `[]`（仅支持空值判断）                                  | `isEmpty`, `isNotEmpty`                                                                        |
+| `DateTime`/`CreatedTime`/`ModifiedTime`              | 见下方                                                  | `is`, `isEmpty`, `isNotEmpty`, `isGreater`, `isLess`                                           |
+
+### 日期字段 value
+
+| value                                                                     | 含义                   | operator 限制 |
+| ------------------------------------------------------------------------- | ---------------------- | ------------- |
+| `["ExactDate", "1702449755000"]`                                          | 具体日期（毫秒时间戳） | -             |
+| `["Today"]`/`["Tomorrow"]`/`["Yesterday"]`                                | 今天/明天/昨天         | -             |
+| `["CurrentWeek"]`/`["LastWeek"]`/`["CurrentMonth"]`/`["LastMonth"]`       | 本周/上周/本月/上月    | 仅 `is`       |
+| `["TheLastWeek"]`/`["TheNextWeek"]`/`["TheLastMonth"]`/`["TheNextMonth"]` | 过去/未来七天/三十天   | 仅 `is`       |
+
+### ⚠️ 常见错误（必读）
+
+**1. Text 字段 `is`/`isNot` 传多个 value → 查询返回空结果**
+
+```typescript
+// ❌ 错误：Text 类型 is 只能传一个元素，传多个会静默返回空
+{ fieldName: '状态', operator: 'is', value: ['红色', '黑色'] }
+
+// ✅ 排除少数值：多条 isNot + conjunction: 'and'
+{
+  conjunction: 'and',
+  conditions: [
+    { fieldName: '进展', operator: 'isNot', value: ['已完成'] },
+    { fieldName: '进展', operator: 'isNot', value: ['已终止'] },
+  ],
+}
+
+// ✅ 匹配多个值：用 contains 模糊匹配（适合有公共子串的场景）
+{ fieldName: '进展', operator: 'contains', value: ['付款'] }  // 匹配"付款审批"和"付款动作"
+```
+
+**2. Formula 字段不支持 filter 和 sum/avg 聚合**
+
+同一数据常有两个字段：原始 Number 字段（如 `金额`，单位元）和计算 Formula 字段（如 `金额(万元)`）。聚合和过滤**必须用 Number 字段**，在代码里做单位转换：
+
+```typescript
+// ❌ 错误：金额(万元) 是 Formula，不能聚合也不能过滤
+{ fieldName: '金额(万元)', aggregation: 'sum' }
+{ fieldName: '金额(万元)', operator: 'isGreater', value: ['0'] }
+
+// ✅ 正确：用 Number 类型的 金额 字段，代码里除以 10000 转万元
+{ fieldName: '金额', aggregation: 'sum', alias: 'total_amount' }
+// 结果处理：const amountWan = totalAmount / 10000;
+```
+
+**3. aggregateQuery 的 `isNot` 会排掉字段为空/null 的记录**
+
+与 searchRecords 不同，aggregateQuery 中 `isNot` 会把字段值为空的记录也排除。如果很多记录的该字段为空，结果会远少于预期甚至为 0。
+
+解决方案：不在 filter 里用 `isNot` 排除 Text 值，改为在 dimensions 里加上该字段，在结果侧用 if 跳过不要的分组：
+
+```typescript
+// ❌ 错误：isNot 会把「目前进展」为空的记录也排掉
+filter: { conditions: [{ fieldName: '目前进展', operator: 'isNot', value: ['已完成'] }] }
+
+// ✅ 正确：不加 filter，在 dimensions 里加「目前进展」，结果侧排除
+dimensions: ['当前状态', '目前进展'],
+// 解析时：if (progress === '已完成' || progress === '已终止') continue;
+```
+
+**4. count 聚合只统计非空值** — 统计总行数时用不会为空的 Number 字段（如"行号"），不要用可能为空的 Text 字段
+
+### 筛选条件构建示例
+
+```typescript
+const filter = {
+  conjunction: 'and', // 或 'or'
+  conditions: [
+    { fieldName: '标题', operator: 'contains', value: ['关键词'] }, // 文本包含
+    { fieldName: '状态', operator: 'is', value: ['进行中'] }, // 单选匹配
+    { fieldName: '金额', operator: 'isGreater', value: ['1000'] }, // 数字比较
+    { fieldName: '创建日期', operator: 'is', value: ['Today'] }, // 日期-今天
+    { fieldName: '截止日期', operator: 'isLess', value: ['ExactDate', Date.now().toString()] }, // 日期-具体
+    { fieldName: '负责人', operator: 'is', value: ['123456'] }, // 人员筛选
+    { fieldName: '备注', operator: 'isEmpty', value: [] }, // 空值检查
+    { fieldName: '已归档', operator: 'is', value: ['true'] }, // 复选框
+  ],
+};
+
+const response = await capabilityClient
+  .load('plugin_instance_id')
+  .call<SearchResponse>('searchRecords', { filter, pageSize: 20 });
+```

package/steering/nestjs-react-fullstack/skills/react-hook-best-practices/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: react-hook-best-practices
+description: "在编写 React Hooks 时遇到闭包陷阱、冗余 Effect、派生状态管理、useEffect 死循环（含「Maximum update depth exceeded」/「循环渲染」/「无限循环」/「页面卡死」等症状）等问题时使用。涵盖 React 19 的 use()、useActionState、useOptimistic 等新特性，以及依赖数组管理、事件处理 vs Effect 等现代模式。React Hooks best practices for stale closures, redundant Effects, derived state, and infinite loop / Maximum update depth diagnosis."
+steering: true
+steering-topic: react_hook_best_practices
+match-template-name: nestjs-react-fullstack
+---
+
+# React Hook 最佳实践 (React 19+)
+
+## ⚡️ 核心原则 (TL;DR)
+
+1. **优先 React 19 新特性**: 用 `use()` 读取异步数据，用 `useActionState` 管理表单，替代繁琐的 `useEffect` + `useState`。
+2. **拒绝冗余 State**: 能计算得到的变量（派生状态），绝不存入 State，直接计算 or `useMemo`。
+3. **事件驱动 > Effects**: 用户交互（点击、提交）产生的逻辑写在事件处理函数中，`useEffect` 仅用于同步外部系统（订阅、DOM）。
+4. **依赖诚实**: `useEffect/useCallback/useMemo` 的依赖数组必须包含所有引用的响应式变量，禁止欺骗 Linter。
+
+---
+
+## 🚫 关键禁忌与陷阱 (Critical Anti-Patterns)
+
+| ❌ 错误模式                       | ✅ 正确做法                       | 说明                                                                                                  |
+| --------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| **依赖数组撒谎**                  | **诚实的依赖数组**                | 漏写依赖会导致闭包陷阱（读到旧值）。若不希望频繁触发，用 `useRef` 或拆分逻辑。                        |
+| **useEffect 获取数据**            | **use() / useActionState**        | React 19 中，数据获取应配合 Suspense 或 Action，而非手动管理 loading/error。                          |
+| **useCallback 依赖 loading**      | **Functional Updates / 移除依赖** | 若 `useCallback` 修改 `loading` 又依赖 `loading`，会导致引用不稳定，触发 `useEffect` 循环或双重请求。 |
+| **useEffect 同步 Props 到 State** | **派生状态 / key**                | 直接在 Render 中计算；若需重置状态，给组件加 `key` prop。                                             |
+| **useEffect 回调直接 async**      | **内部定义 async 函数**           | `useEffect(async () => ...)` 返回 Promise 会破坏清理机制。                                            |
+| **手动管理 Form Loading**         | **useActionState**                | 自动处理 pending/error，减少样板代码。                                                                |
+| **遗漏副作用清理**                | **返回清理函数**                  | 监听器、定时器、订阅必须在 `return () => ...` 中清除。                                                |
+| **Context value 引用不稳定**      | **ref 持值 + 稳定 getter**        | `<Provider value={useMemo(() => ({ inst }), [inst])}>` 中若 `inst` 是会更新的实例，每帧 identity 翻 → 所有 consumer 重渲染 → 子组件 ref-callback 链触发 setState → 死循环。改用 `ref.current = inst` + 一次性 `useMemo(() => ({ get: () => ref.current }), [])`。 |
+| **selector / hook 返回 `.bind()` 或新对象字面量** | **直接传引用，不 bind**           | `useStore({ selector })` / `useContextSelector` 类用 shallow equality bailout。`selector: ctx => ({ fn: ctx.fn.bind(ctx) })` 每帧产生新函数 → 所有 consumer 重渲染 → setRef 链路放大成死循环。直接传 `ctx.fn`，consumer 自己访问。 |
+| **callback ref 在 render 中创建** | **稳定引用 + useCallback**        | `ref={(node) => { map[key] = node }}` 每次 render 新函数 → React commit 阶段先调旧 ref(null) 再调新 ref(node) → 若 callback 含 setState 即死循环。同理 `useMemo(..., [模板字符串/字面量/.map结果])` 让 memo 失效。 |
+
+> **死循环根因模式**（针对上方最后 3 条 anti-pattern）：报错栈含 `Maximum update depth exceeded` / `setRef` 内调 `dispatchSetState` / `Array.map` + `setRef`（`composeRefs` / `Slot` 链路）时，真根因**始终在 ref provider 一侧**——hook / context 返回值不稳定，被 ref 消费方放大成死循环。不要在 ref 接收方做兜底（关闭自动 focus、外层条件渲染、移除 `asChild`、加 unique key 等都不会修好），按上方 3 条 anti-pattern 追到 ref provider 上游。
+
+#### Safe Destructuring (安全解构)
+
+**禁止**对可能为空的 Hook 返回值（如 `useActionState` 的 state 或 `use` 读取的异步数据）直接进行深层解构。
+
+```typescript
+// ❌ Anti-pattern
+const [state, action] = useActionState(updateUser, null);
+const {
+  data: { name },
+} = state; // 如果 state 初始为 null，直接崩溃
+
+// ✅ Best Practice
+const [state, action] = useActionState(updateUser, null);
+const name = state?.data?.name ?? "Guest";
+```
+
+---
+
+## 🆕 React 19 现代 Hooks 速查
+
+| Hook               | 场景                   | 示例模式                                                       |
+| ------------------ | ---------------------- | -------------------------------------------------------------- |
+| **use(Promise)**   | **读取异步数据**       | `const data = use(fetchData(id))` (需配合 `<Suspense>`)        |
+| **useActionState** | **表单提交/Mutation**  | `const [state, action, isPending] = useActionState(fn, null)`  |
+| **useOptimistic**  | **乐观 UI 更新**       | `const [optTodos, addOpt] = useOptimistic(todos, reducer)`     |
+| **useFormStatus**  | **子组件获取表单状态** | `const { pending } = useFormStatus()` (仅限 `<form>` 内部组件) |
+| **useTransition**  | **非阻塞 UI 更新**     | `startTransition(() => setFilter(value))`                      |
+
+### 代码对比：异步数据获取
+
+**🔴 旧模式 (React 18-)**:
+
+```typescript
+const [data, setData] = useState(null);
+const [loading, setLoading] = useState(true);
+useEffect(() => {
+  fetch(`/api/user/${id}`).then(d => { setData(d); setLoading(false); });
+}, [id]);
+if (loading) return <Spinner />;
+```
+
+**🟢 新模式 (React 19+)**:
+
+```typescript
+// 结合 Suspense 使用
+const data = use(fetchUserPromise(id)); // 支持条件调用！
+return <div>{data.name}</div>;
+```
+
+---
+
+## 🧠 思维模型：State vs Effect
+
+### 1. 派生状态 (Derived State)
+
+**规则**: 如果一个值可以由现有的 props 或 state 计算得出，**不要**把它放入 state。
+
+- ❌ `const [fullName, setFullName] = useState('')` + `useEffect` 更新
+- ✅ `const fullName = ${firstName} ${lastName}`
+- ✅ (昂贵计算) `const list = useMemo(() => sort(items), [items])`
+
+### 2. Effect 的正确归宿
+
+`useEffect` 是用来**同步** React 之外的东西（非 React 组件状态）的。
+
+- **用户点击加载数据?** -> ❌ Effect -> ✅ Event Handler (`onClick`)
+- **表单提交?** -> ❌ Effect -> ✅ `useActionState` / Event Handler
+- **WebSocket 连接?** -> ✅ `useEffect` (因为要保持连接同步)
+- **DOM 元素测量?** -> ✅ `useLayoutEffect` / `useEffect`
+
+---
+
+## ✅ 代码审查清单 (Checklist)
+
+在提交代码前，请自查：
+
+- [ ] **Hooks 规则**: 顶层调用，不嵌套在循环/条件中（`use()` 除外）。
+- [ ] **依赖数组**: `useEffect`, `useMemo`, `useCallback` 包含所有外部变量。
+- [ ] **清理工作**: `useEffect` 中是否清理了定时器/订阅？
+- [ ] **竞态处理**: 异步 Effect 是否处理了组件卸载或 id 变更的情况？(如 `ignore` 标志)。
+- [ ] **引用稳定**: `Context` value 或自定义 Hook 返回的对象，是否做了 `useMemo` 缓存？
+- [ ] **React 19 升级**: 是否还在手动写 `loading` state？能否用 `useActionState` 或 `Suspense` 替代？