@lark-base-open/base-database-cli 1.1.1 → 1.3.7

package/skills/lark-base-database/references/database-function.md

@@ -0,0 +1,349 @@
+# Database Function 专项
+
+Database Function 通过固定查询语句读取 Base 数据，定义位于 `database-functions/<functionId>/`。
+
+Database Function 只支持本文明确列出的只读查询语法和函数，不从通用关系型数据库的语法或函数推断其能力。
+
+## 阅读路径
+
+1. [Catalog](#catalog)
+2. [查询类型与结果值](#查询类型与结果值)
+3. [Function-文件与参数](#function-文件与参数)
+4. [查询约束](#查询约束)
+5. [调用与结果](#调用与结果)
+6. [校验](#校验)
+
+## Catalog
+
+`catalog.json` 是已绑定 Base 的查询 schema。查询语句中的表名、字段名、OPTION 值和关联关系只从这里读取：
+
+```json
+{
+  "tables": [
+    {
+      "baseToken": "basxxx",
+      "id": "tblTasks",
+      "name": "任务",
+      "fields": {
+        "状态": {
+          "id": "fldStatus",
+          "name": "状态",
+          "baseType": "SingleSelect",
+          "sqlType": {
+            "kind": "OPTION",
+            "options": [{ "id": "optTodo", "name": "待处理" }]
+          },
+          "nullable": true
+        },
+        "主客户": {
+          "id": "fldPrimaryCustomer",
+          "name": "主客户",
+          "baseType": "Link",
+          "sqlType": { "kind": "TEXT" },
+          "nullable": true,
+          "reference": {
+            "baseToken": "basxxx",
+            "tableId": "tblCustomers"
+          }
+        },
+        "协作客户": {
+          "id": "fldCustomers",
+          "name": "协作客户",
+          "baseType": "DuplexLink",
+          "sqlType": {
+            "kind": "ARRAY",
+            "element": { "kind": "TEXT" }
+          },
+          "nullable": true,
+          "reference": {
+            "baseToken": "basxxx",
+            "tableId": "tblCustomers"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+- 查询语句使用 `tables[].name` 和 `fields[key].name`；中文、空格或标点名称用双引号。
+- `fields[key].sqlType` 决定可查询类型；`UNSUPPORTED` 字段不查询。
+- OPTION 是 `{id, name}` UDT。按展示名筛选时显式写 `(option_field).name`，按稳定标识筛选时显式写 `(option_field).id`；不要把整个 OPTION 与 TEXT 隐式比较。
+- `ARRAY` 的元素类型在 `sqlType.element`。
+- `Link` / `DuplexLink` 的单向或双向语义不决定 SQL 是否为数组；以 `sqlType` 为准：单值关联是 `TEXT`，多值关联是 `ARRAY<TEXT>`。不要只凭 `baseType`、字段名或关联方向猜单多值。
+- 关联目标由 `reference` 定位，JOIN 使用目标表名和其 `rec_id`。单值关联使用 `link_field = target.rec_id`，多值关联使用 `link_field @> ARRAY[target.rec_id]`。
+- 每张表自动提供 `rec_id`，类型为 `TEXT`。Base、table、field ID 不写进查询语句。
+
+## 查询类型与结果值
+
+`sqlType` 是递归结构：标量为 `{"kind":"TEXT"}`，数组为 `{"kind":"ARRAY","element":{...}}`，OPTION 额外带 `options`。查询返回的行会序列化成普通 JSON：
+
+| 查询类型 | ResultJSON 中的值 |
+|---|---|
+| `TEXT` | string |
+| `OPTION` | object；`{id, name}` |
+| `INT` | JavaScript safe integer number |
+| `DOUBLE` | number |
+| `BOOL` | boolean |
+| `TIMESTAMP` | Base 执行时区下的无偏移时间字符串；固定为 `YYYY-MM-DD HH:mm:ss.SSS` |
+| `INTERVAL` | 以毫秒为单位的固定时长字符串；值为 `1` / `-1` 时用 `millisecond`，其余用 `milliseconds`（聚合结果可含小数） |
+| `AUTONUMBER` | object；`{sequence, number}`，`.sequence` 用于数值排序/计算，`.number` 用于展示 |
+| `USER` | object；`{id, name}`，查询读取 `.id`、`.name` |
+| `CHAT` | object；`{id, name}`，查询读取 `.id`、`.name` |
+| `LOCATION` | object；`{address, lng, lat}` |
+| `URL` | object；`{text, link}`，比较或投影文本时显式读取 `.text` 或 `.link` |
+| `FILE` | object；`{token, name, mime_type, size}`，其中 `token` 对应附件的 `attachmentToken`、`size` 为整数；展示走[文件传输](file-transfer.md) |
+| `ARRAY<T>` | `T[]`；例如 `OPTION[]` 的元素为 `{id, name}` |
+| nullable field | 原类型或 `null` |
+
+执行时区按显式请求时区、Base 设置、Base 默认 `Asia/Shanghai` 的优先级确定；未设置时区的 Base 也按默认时区解析 TIMESTAMP 参数并渲染返回值。`TO_CHAR` 和时间投影使用同一生效时区。
+
+日期表单回填与时间展示按[日期与时区](development.md#日期与时区)处理。
+
+## Function 文件与参数
+
+```text
+database-functions/<functionId>/
+├── main.sql
+└── meta.json
+```
+
+`main.sql` 只包含一条固定 `SELECT`。`meta.json` 包含非空 `name`、可选 `description` 和参数声明。
+
+查询使用位置参数 `$1`、`$2`……；`meta.params` 按相同顺序声明：
+
+```sql
+SELECT rec_id AS record_id, "任务名称" AS title, ("状态").name AS status
+FROM "任务"
+WHERE "任务名称" LIKE $1 AND ("状态").name = $2
+ORDER BY rec_id DESC
+LIMIT $3
+```
+
+```json
+{
+  "name": "搜索任务",
+  "description": "按关键词和状态搜索任务",
+  "meta": {
+    "params": [
+      { "kind": "TEXT", "description": "$1，已包含 % 的关键词" },
+      { "kind": "TEXT", "description": "$2，任务状态选项名" },
+      { "kind": "INT", "description": "$3，已由调用方限制上限的返回条数" }
+    ]
+  }
+}
+```
+
+`$n`、`meta.params[n-1]` 和调用 `params[n-1]` 必须连续、一一对应。每项只写 `kind` 和可选的 `description`。
+
+参数 `kind` 只使用 `TEXT`、`INT`、`DOUBLE`、`BOOL`、`TIMESTAMP`、`INTERVAL`，或为其中任一类型追加一个 `[]` 表示一维数组，例如 `TEXT[]`。标量、整个数组及数组元素都可传 `null`；不支持多维数组，也不接受 `OPTION`、`USER`、`CHAT`、`FILE`、`LOCATION`、`URL`、`AUTONUMBER` 等对象类型。SingleSelect 的动态展示名参数仍声明为 `TEXT`，但 SQL 必须显式写 `(option_field).name = $n`；按 ID 筛选则写 `(option_field).id = $n`。
+
+`TIMESTAMP` 参数接受 RFC 3339 字符串、Base 执行时区下的无偏移 `YYYY-MM-DD HH:mm:ss.SSS` 字符串，或 JavaScript safe integer 范围内的 Unix epoch 毫秒整数。无偏移字符串遇到夏令时不存在或重复的当地时间会被拒绝，此时改传带偏移的 RFC 3339 或 epoch 毫秒。`INTERVAL` 参数只接受一个数字和一个单位组成的固定时长字符串。单位支持 `ms`、`millisecond(s)`、`second(s)`、`sec(s)`、`minute(s)`、`min(s)`、`hour(s)`、`day(s)`、`week(s)`，不区分大小写；数字可带符号或小数，但结果必须能无损换算为整数毫秒，例如 `250 ms`、`1.5 seconds`、`2 hours`。不接受复合形式 `1 day 02:03:04`、时钟形式 `02:03:04`，也不支持月、年等日历单位。数组参数的每个非 `null` 元素遵循相同规则。`INT` 必须处于 JavaScript safe integer 范围。CLI 不做类型推断，以 `meta.params[].kind` 为唯一声明。
+
+`INT` 参数可用于支持集内的数值表达式，也可用于 `LIMIT` 或 `OFFSET`。页面输入不能直接决定返回规模；确需动态条数时，先在 Page/FaaS 校验为非负整数并限制最大值，再传入参数。正常列表优先使用代码中固定的有界 `LIMIT`。
+
+按文本数组参数筛选标量文本字段，使用 `= ANY($1)`：
+
+```sql
+SELECT f.rec_id AS record_id, f."分组" AS group_name
+FROM "跟进记录" AS f
+WHERE f."分组" = ANY($1)
+LIMIT 30
+```
+
+对应参数声明为 `{"kind":"TEXT[]"}`，例如调用 `params: [["重点", "普通"]]`。左侧必须是 `TEXT`，右侧必须是一维 `TEXT[]` 位置参数；其他元素类型的参数化 `ANY` 尚不支持。空数组不会选中记录；整个数组为 `null`，或没有匹配且数组含 `null` 时，表达式为 `null`，`WHERE` 不选中该行。不要把 `IN ($1)` 当作数组展开，也不要对标量字段直接使用 `<@`。显式 `ARRAY[字段] <@ $1` 是数组包含判断，与 `ANY` 在含 `null` 时的布尔结果不同。
+
+无参数 Function 可以省略 `meta` 或 `meta.params`；归档统一补成 `{"params":[]}`。
+
+Database Function 的 `inputSchema` 由 CLI 根据参数顺序与 kind 生成固定长度数组 Schema，不在 Database Function 的 `meta.json` 中手写。FaaS 则必须显式声明，见[FaaS 开发](faas.md#faas-开发)。
+
+## 查询约束
+
+只编写只读 `SELECT`，页面输入只能进入位置参数。查询使用以下支持集：
+
+- 每条查询的最终查询计划必须引用至少一个 Catalog 中的真实表，用于 Project 执行时选择可路由的表依赖。根 `FROM` 可以是带别名的 `FROM (SELECT ...) AS alias` 派生表，但该派生表或它依赖的 CTE 必须读取真实表。
+- 不要用 Database Function 实现纯常量、纯参数、仅 `FROM (SELECT ...)`、仅 CTE 常量或仅 `UNNEST(...)` 的查询；这些查询没有真实表依赖，会在绑定 Base 的 Validate 或 Execute 阶段失败。与 Base 数据无关的常量在 Page/FaaS 中用代码返回。
+- 查询结构使用显式投影、`WHERE`、`GROUP BY`、`HAVING`、`ORDER BY`；不使用 `SELECT *` 或 `table.*`。`GROUP BY` 最多 5 项。
+- 连接使用 `INNER JOIN`、`LEFT JOIN`、`CROSS JOIN` 或逗号连接。每个 JOIN 的右侧保持为一个表或一个带别名的派生表；`UNNEST` 只能写成逗号连接或 `CROSS JOIN UNNEST(...)`，禁止生成 `LEFT JOIN UNNEST` 或 `INNER JOIN UNNEST`。不要把含 `GROUP BY`、`COUNT`、`SUM`、`AVG`、`MIN` 或 `MAX` 的聚合派生表再 `JOIN` 回主表。单条查询的 JOIN 总数不超过 10。
+- 非递归顶层 CTE 可用；正常建站优先用带别名的 `FROM (SELECT ...) AS alias`，不要写递归 CTE 或嵌套 CTE。
+- 子查询优先作为带别名的 `FROM` 派生表使用，外层通过派生表输出列名引用结果。成员判断可以直接写 `WHERE x IN (SELECT ...)`、`NOT IN`、`EXISTS`、`NOT EXISTS`；相关子查询只使用等值关联（`inner.k = outer.k`）。投影、`ORDER BY`、`OR` 或 `CASE` 之下的标量子查询和 `EXISTS` 默认不生成，需要时拆成派生表或单独查询。
+- 列表使用有界 `LIMIT` 和稳定排序；排序值可能重复时最后按 `rec_id` 排序。不把截断结果的前端分页视为完整分页或全量导出。
+- 返回字段逐列列出并使用 `AS snake_case`。
+- 搜索写 `field LIKE $1`，由参数携带 `%`。
+- `IN (..., NULL)` / `NOT IN (..., NULL)` 保留三值逻辑：未命中但列表含 NULL 时结果为 NULL，WHERE 不选中该行。字符串 `a || b` 任一侧为 NULL 时结果为 NULL；`CONCAT(a,b)` 则跳过 NULL。
+- UDT 只与相同 UDT 类型直接比较；UDT 与成员标量之间没有隐式比较。OPTION 展示名筛选写 `(option_field).name = $n` / `IN (...)`，ID 筛选写 `(option_field).id = $n`；不要写 `option_field = $n`，也不要把 OPTION 或其成员与 `''` 比较。
+- 当前访问者使用 `CURRENT_USER_ID()`，不由页面传入用户 ID。
+- UDT 列成员统一使用 PostgreSQL 复合类型括号语法：无表别名写 `("负责人").id`、`("链接").link`，带表别名写 `(t."负责人").id`。FILE 可写 `("附件").token`、`.name`、`.mime_type`、`.size`；不再使用 `"字段".member` 或 `t."字段".member`。多值对象需要逐元素读取时写 `FROM 表 AS t, UNNEST(t."人员") AS u`，range alias 成员仍写 `u.id`。
+- 不把 `USER`、`CHAT`、`FILE`、`URL` 完整对象投影到派生表后再 JOIN；需要身份过滤时在对象字段所在的真实表查询中直接比较标量子字段。权限关系的实现边界按[权限设计](permission-design.md#读路径database-function-就是策略面)。
+- 集合字段只使用 PostgreSQL 数组运算符：`@>`（包含）、`<@`（被包含）、`&&`（有交集）。不要生成 `ARRAY_CONTAINS` 或 `ARRAY_OVERLAP`。单值关联的 `sqlType` 是 `TEXT`，按文本标量使用 `=`、`IN`、`NOT IN`、`LIKE`、`NOT LIKE`，不要对它使用数组运算符。只有业务本来就是 INNER/逐元素明细语义时，才通过逗号连接或 `CROSS JOIN UNNEST(...)` 展开；展开会过滤空集合主表行，不能替代 `LEFT JOIN UNNEST`。
+- 条件分支：`CASE WHEN bool_expr THEN value ... ELSE value END` 与 `CASE expr WHEN value THEN ... END` 都可用，各分支结果类型一致（`INT` 与 `DOUBLE` 会统一为 `DOUBLE`）。空值兜底可用 `COALESCE(x, fallback)` / `NULLIF`，参数类型必须完全相同，`INT` 与 `DOUBLE` 混用时先写成同类型，例如 `COALESCE(x, 0.0)`。
+- 时间条件使用 Catalog 中确认为 `TIMESTAMP` 的字段和 `TIMESTAMP` 位置参数；当前时间使用 `CURRENT_TIMESTAMP`。查询结果固定为 Base 执行时区下的 `YYYY-MM-DD HH:mm:ss.SSS` 字符串。`EXTRACT(EPOCH FROM timestamp_expr)` 返回保留小数秒的 `DOUBLE`；明确只需整数秒时再写 `::bigint`。不要对 `TEXT` 日期字符串使用顺序比较；若业务必须做日期范围筛选，把 Base 字段建成 DateTime/TIMESTAMP。
+- 时间格式化与分桶：按月、按天展示写 `TO_CHAR(ts, 'YYYY-MM')`，格式只使用 `YYYY`、`MM`、`DD`、`HH24`、`MI`、`SS` 及分隔符；按天、周、月、季、年分组也可写 `DATE_TRUNC('month', ts)`，其结果只用于投影、`GROUP BY`、`ORDER BY`，不再参与比较或运算。时间偏移使用固定时长的 `INTERVAL`（毫秒到周），不使用月、年单位；需要按自然月计算的范围由 Page/FaaS 算好边界后作为 `TIMESTAMP` 参数传入。`EXTRACT` / `DATE_PART` 返回 `DOUBLE`。
+- 聚合函数使用 `COUNT(*)`、`COUNT(expr)`、`SUM(NUMBER)`、`AVG(NUMBER)`、`MIN(scalar)`、`MAX(scalar)`；`ARRAY_AGG(expr)` 可用但默认少生成。聚合结果需要回填到列表行时，拆成列表查询、聚合查询和必要的明细查询，在 Page/FaaS 按稳定业务键合并。
+- 条件计数、通过率等聚合写 `SUM(CASE WHEN cond THEN 1.0 ELSE 0.0 END)`；不要生成 `SUM/AVG(CASE WHEN cond THEN 1 ELSE 0 END)`。行数统计用 `COUNT(*)` / `COUNT(expr)`。
+- 窗口函数可用：`ROW_NUMBER`、`RANK`、`DENSE_RANK`、`PERCENT_RANK`、`CUME_DIST`、`NTILE(n)`、`LAG` / `LEAD`、`FIRST_VALUE`，以及 `COUNT` / `SUM` / `AVG` / `MIN` / `MAX` 作为整个分区的汇总。“每组最新一条”写派生表 `ROW_NUMBER() OVER (PARTITION BY k ORDER BY t DESC, rec_id DESC) AS rn`，外层 `WHERE rn = 1`。窗口只支持整个分区的计算范围：带 `ORDER BY` 的聚合窗口（逐行累计）、`ROWS/RANGE BETWEEN ... CURRENT ROW` 等范围不支持，累计值在 Page/FaaS 中计算；`LAST_VALUE` 只能配合 `ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING`。
+- 字符串函数使用 `LOWER(TEXT)`、`UPPER(TEXT)`、`CONCAT(TEXT, ...)`、`CONCAT_WS(sep, TEXT, ...)`、`REPLACE`、`STARTS_WITH`，拼接也可写 `||`（两侧都是 `TEXT`）。包含判断写 `STRPOS(text, 'x') > 0`，结尾匹配写 `text LIKE '%x'`；`STRPOS` 只能与 0 或 1 比较，不能取具体位置。`LENGTH`、`LEFT`、`RIGHT`、`SUBSTRING`、`LPAD`、`RPAD`、`TRIM` / `LTRIM` / `RTRIM` 和正则函数不支持，长度、截取、去空白、拆分在 Page/FaaS 中处理。
+- 数字计算使用 `+`、`-`、`*`、`/`、`%` / `MOD`（仅整数）、`ABS`、`CEIL`、`FLOOR`、`ROUND(x)`；保留 n 位小数写 `ROUND(x::numeric, n)`，不写 `ROUND(x, n)`。两个整数相除按 PostgreSQL 做整数除法（`7 / 2 = 3`，`COUNT(a) / COUNT(*)` 也是整数除法），比例、通过率写 `COUNT(a)::float8 / COUNT(*)` 或 `SUM(CASE WHEN cond THEN 1.0 ELSE 0.0 END) / COUNT(*)`。
+
+字段筛选使用以下支持形态：
+
+| 字段类型 | 支持的筛选形态 |
+|---|---|
+| `rec_id`、`TEXT`、Phone | `=`、`IN`、`NOT IN`、`LIKE`、`NOT LIKE` |
+| `INT`、`DOUBLE` | `=`、`IN`、`NOT IN`、`<`、`<=`、`>`、`>=`、`BETWEEN` |
+| `BOOL` | `= TRUE`、`= FALSE` |
+| `TIMESTAMP` | 与 `TIMESTAMP` 参数使用 `=`、`!=`、`<`、`<=`、`>`、`>=`、`BETWEEN` |
+| `OPTION` | 显式比较 `.name` 或 `.id`；整个 OPTION 只与 OPTION 比较 |
+| `AUTONUMBER` | `.sequence` 做数值比较、排序和计算；`.number` 做文本展示或等值筛选 |
+| 单值关联（Catalog `sqlType.kind = TEXT`） | 按 `TEXT` 使用 `=`、`IN`、`NOT IN`、`LIKE`、`NOT LIKE` |
+| 多选、多值关联等集合（Catalog `sqlType.kind = ARRAY`） | 只使用 `@>`、`<@`、`&&`；UDT 数组先显式访问 `.id` / `.name` 成员数组 |
+| `USER`、`CHAT`、`FILE`、`URL` | 使用括号语法比较已声明的标量子字段；FILE 为 `.token/.name/.mime_type/.size`，URL 为 `.text/.link`；多值对象只有逐元素明细语义才展开 |
+
+条件聚合示例：
+
+```sql
+SELECT
+  COUNT(s.rec_id) AS submitted_count,
+  SUM(CASE WHEN s."是否通过" = TRUE THEN 1.0 ELSE 0.0 END) AS passed_count,
+  ROUND(AVG(CASE WHEN s."得分" IS NULL THEN 0.0 ELSE s."得分" END)::numeric, 1) AS average_score
+FROM "在线考试系统 - 答卷记录" AS s
+```
+
+路由表依赖：
+
+```sql
+-- 错误：只读取派生常量，没有 Catalog 真实表依赖
+SELECT anchor.ok AS ok
+FROM (SELECT TRUE AS ok) AS anchor
+LIMIT 1
+```
+
+```sql
+-- 正确：从真实表读取或聚合，让执行器可以选择路由表
+SELECT COUNT(t.rec_id) AS task_count
+FROM "任务" AS t
+```
+
+如果业务只是返回前端常量、默认配置或入参回显，不创建 Database Function；直接在 Page 状态或 FaaS handler 中构造结果。只有结果必须由 Base 数据决定时才编写查询语句，并选择业务相关的真实表作为查询锚点。
+
+状态排序等固定映射也按上述写法：
+
+```sql
+CASE
+  WHEN (c."客户状态").name = '线索' THEN 1
+  WHEN (c."客户状态").name = '潜在客户' THEN 2
+  WHEN (c."客户状态").name = '意向客户' THEN 3
+  WHEN (c."客户状态").name = '成交客户' THEN 4
+  WHEN (c."客户状态").name = '流失' THEN 5
+  ELSE 6
+END AS sort_order
+```
+
+集合筛选：
+
+```sql
+SELECT f.rec_id AS followup_id, f."跟进时间" AS followed_at
+FROM "跟进记录" AS f
+WHERE f."关联线索" @> ARRAY[$1]
+ORDER BY f."跟进时间" DESC, f.rec_id DESC
+LIMIT 30
+```
+
+单值关联按 record ID 标量筛选：
+
+```sql
+SELECT o.rec_id AS order_id, o."订单号" AS order_no
+FROM "订单" AS o
+WHERE o."主客户" = $1
+ORDER BY o."订单号" DESC, o.rec_id DESC
+LIMIT 30
+```
+
+读取关联表字段且需要保留主表空关联行时，`LEFT JOIN` 真实目标表，不要 `LEFT JOIN UNNEST`：
+
+```sql
+SELECT
+  o.rec_id AS order_id,
+  o."订单号" AS order_no,
+  c."客户名称" AS customer_name
+FROM "订单" AS o
+LEFT JOIN "客户" AS c ON o."客户" @> ARRAY[c.rec_id]
+WHERE o."订单号" LIKE $1
+ORDER BY o."订单号" DESC, o.rec_id DESC
+LIMIT 20
+```
+
+上例是多值关联。若 Catalog 中关联字段为 `TEXT`，左连接改用标量等值：
+
+```sql
+SELECT
+  o.rec_id AS order_id,
+  o."订单号" AS order_no,
+  c."客户名称" AS customer_name
+FROM "订单" AS o
+LEFT JOIN "客户" AS c ON o."主客户" = c.rec_id
+ORDER BY o."订单号" DESC, o.rec_id DESC
+LIMIT 20
+```
+
+如果没有真实目标表可 JOIN，又必须保留空集合主表行，拆成主表查询与明细展开查询，并在 Page/FaaS 里按主表 `rec_id` 左合并。拆分后的输入若在开始时已经确定，应并发调用；不要用 `CROSS JOIN UNNEST` 冒充 LEFT 语义。
+
+搜索、筛选、关联和聚合尽量在查询中完成。没有关系、不同步消费或需要隔离失败语义的结果集可以拆分；拆分后的输入若在开始时已经确定，应并发调用。
+
+## 调用与结果
+
+Database Function 的业务参数在两条链路上都是数组，但调用入口不同。Page 使用 starter 的 runtime client，不传 projectId：
+
+```ts
+import { invokeDatabaseFunction } from '../lib/database-runtime'
+
+await invokeDatabaseFunction<{ rows: unknown[] }>(
+  'searchTasks',
+  ['%评审%', '待处理', 20],
+)
+```
+
+FaaS handler 内部使用 context，projectId 为当前 应用 的工程常量：
+
+```ts
+await context.invokeFunction({
+  projectId: PROJECT_ID,
+  functionId: 'searchTasks',
+  params: ['%评审%', '待处理', 20],
+})
+```
+
+公开 HTTP body：
+
+```json
+{ "params": ["%评审%", "待处理", 20] }
+```
+
+返回是 ResultJSON，不是 rows 数组：
+
+```json
+{
+  "data": {
+    "rows": [
+      {
+        "record_id": "recxxx",
+        "title": "准备评审",
+        "status": "待处理",
+        "due_at": 1784311200000
+      }
+    ],
+    "columns": [],
+    "row_count": 1,
+    "fxdb_version": "...",
+    "log_id": "..."
+  },
+  "code": 0,
+  "msg": "success"
+}
+```
+
+先检查 `code===0` 和 `data`，再验证 `data.rows` 以及每一行的数据结构。
+
+## 校验
+
+`base-database-cli deploy` 统一调用服务端查询校验。编译成功仅证明编译阶段；实际读取按[发布与交付](release.md)或用户要求的[专项验收](verification.md)执行。失败时保留具体错误节点和 LogID，按 Catalog、参数与支持边界修复，不猜测响应 envelope 绕过。

package/skills/lark-base-database/references/design/components/actions-fields.md

@@ -0,0 +1,16 @@
+# 按钮与字段
+
+适用于主/次/文字/危险/图标按钮、单行输入、搜索、标签、错误、帮助与多行输入。基础几何从[配方](../control-recipes.md)取得，颜色从[主题](../theme.md)取得；[组件代码](code/controls.tsx)和[共享样式](code/controls.css)展示可适配实现。
+
+| 区域 | A / B / C 共用要求 |
+| --- | --- |
+| 普通按钮 | 文字行高 20px、图标视觉 16px；高度、水平内边距、圆角和间隙用配方值。主动作实底，次动作轻填充，低优先级动作透明；不叠灰底、灰边和阴影 |
+| 图标按钮 | 宽度可等于当前按钮高度；必须有可访问名称，图标垂直与水平居中。触控场景另扩展命中区 |
+| 单行输入与搜索 | 同配方高度和字形；值字号可读，placeholder 仅提供例子，不替代 label。A 用单层轻边界，B/C 用轻填充并保留透明 1px 边界占位 |
+| 输入焦点 | 原边界位置变为一层 1px 主题焦点色，不叠 outline/ring/内外阴影；正常输入和错误同时存在时只画一个边界层 |
+| 禁用/加载 | 禁用不可操作，loading 仅用于真实异步状态；大小不跳动，必要时阻止重复提交 |
+| 帮助与错误 | 只在必要时显示。错误靠近字段并通过 `aria-describedby` 关联；校验恢复后移除错误及关联，不补“已填写”或空白帮助行 |
+
+Textarea 从约三行起步，`resize: none` 去掉右下角拖拽斜线；随输入、初值、预填、粘贴和容器尺寸增高。达到任务合适上限时在字段内部滚动，预览中的 220px 是可改参考值，不是业务限制。不能把输入截断或固定矮框。参考实现的 `ResizeObserver` 只处理控件自身尺寸，不要求普通搭建启动浏览器巡检。
+
+按钮文案说明实际操作；保存成功只能来自真实业务返回或用户明确的模拟流程。页面头与按钮已经表达的功能不再写副标题。选择主按钮不自动在其外层生成背景卡片。

package/skills/lark-base-database/references/design/components/code/controls.css

@@ -0,0 +1,122 @@
+.ds-theme, .ds-theme * { box-sizing: border-box; }
+.ds-control { font: inherit; font-size: var(--ds-font); line-height: 20px; color: var(--ds-text); }
+.ds-button, .ds-field, .ds-trigger, .ds-segment button, .ds-option, .ds-page-button { font: inherit; font-size: var(--ds-font); }
+.ds-button { display: inline-flex; align-items: center; justify-content: center; gap: var(--ds-gap); min-height: var(--ds-height); padding: 0 var(--ds-pad); border: 1px solid transparent; border-radius: var(--ds-radius); background: transparent; color: var(--ds-text); font-weight: 500; line-height: 20px; box-shadow: none; cursor: pointer; white-space: nowrap; }
+.ds-button[data-variant="primary"] { background: var(--ds-action); color: var(--ds-on-action); }
+.ds-button[data-variant="primary"]:hover:not(:disabled) { background: var(--ds-action-hover); }
+.ds-button[data-variant="secondary"] { background: var(--ds-action-soft); color: var(--ds-action); }
+.ds-button[data-variant="secondary"]:hover:not(:disabled) { background: var(--ds-action-soft-hover); }
+.ds-button[data-variant="quiet"]:hover:not(:disabled) { background: var(--ds-hover); }
+.ds-button[data-variant="danger"] { color: var(--ds-danger); }
+.ds-button[data-variant="danger"]:hover:not(:disabled) { background: var(--ds-error-soft); }
+.ds-button[data-icon-only="true"] { width: var(--ds-height); padding: 0; flex: none; }
+.ds-button:disabled { opacity: .48; cursor: not-allowed; }
+.ds-button:focus-visible { outline: 2px solid var(--ds-focus); outline-offset: 2px; }
+.ds-spinner { width: 14px; height: 14px; border: 1.5px solid currentColor; border-right-color: transparent; border-radius: 50%; animation: ds-spin .8s linear infinite; }
+@keyframes ds-spin { to { transform: rotate(360deg); } }
+.ds-field-wrap { display: grid; gap: 7px; min-width: 0; }
+.ds-label { font-size: var(--ds-font); font-weight: 500; line-height: 20px; }
+.ds-help, .ds-error { font-size: 12px; line-height: 18px; margin: 0; }
+.ds-help { color: var(--ds-muted); }
+.ds-error { color: var(--ds-danger); }
+.ds-field, .ds-trigger, .ds-number, .ds-affix { width: 100%; min-width: 0; min-height: var(--ds-height); padding: 0 var(--ds-pad); border: 1px solid var(--ds-field-border); border-radius: var(--ds-radius); background: var(--ds-field-fill); color: var(--ds-text); box-shadow: none; outline: 0; font-weight: 400; line-height: 20px; }
+.ds-field::placeholder { color: var(--ds-placeholder); opacity: 1; }
+.ds-field:hover:not(:disabled):not(:focus), .ds-trigger:hover:not(:disabled), .ds-number:hover, .ds-affix:hover { background: var(--ds-field-hover); }
+.ds-field:focus, .ds-trigger:focus-visible, .ds-number:focus-within, .ds-affix:focus-within { border-color: var(--ds-focus); outline: 0; box-shadow: none; }
+.ds-field[aria-invalid="true"], .ds-trigger[aria-invalid="true"], .ds-number[data-invalid="true"], .ds-affix[data-invalid="true"] { border-color: var(--ds-danger); background: var(--ds-error-soft); }
+.ds-field:disabled, .ds-trigger:disabled { opacity: .5; cursor: not-allowed; }
+.ds-textarea { padding: 10px var(--ds-pad); min-height: 92px; max-height: var(--ds-textarea-max, 220px); resize: none; line-height: 1.55; overflow-y: auto; }
+.ds-trigger { display: flex; align-items: center; justify-content: space-between; gap: 8px; text-align: left; cursor: pointer; }
+.ds-trigger-value { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.ds-trigger-caret { flex: none; color: var(--ds-muted); }
+.ds-trigger[aria-expanded="true"]:not(:focus-visible) { background: var(--ds-action-soft); }
+.ds-popover { position: fixed; z-index: 60; overflow: auto; padding: 6px; border: 0; border-radius: calc(var(--ds-radius) + 2px); background: var(--ds-popover); color: var(--ds-text); box-shadow: 0 6px 28px var(--ds-shadow); font-size: var(--ds-font); }
+.ds-option-list { max-height: 236px; overflow-y: auto; }
+.ds-option { width: 100%; min-height: var(--ds-height); display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 6px 10px; border: 0; border-radius: var(--ds-radius); background: transparent; color: var(--ds-text); text-align: left; line-height: 20px; cursor: pointer; }
+.ds-option:hover, .ds-option:focus-visible { background: var(--ds-hover); outline: 0; }
+.ds-option:focus-visible { box-shadow: inset 2px 0 var(--ds-focus); }
+.ds-option[aria-selected="true"], .ds-option[aria-checked="true"] { background: var(--ds-action-soft); color: var(--ds-action); font-weight: 500; }
+.ds-option[data-danger="true"] { color: var(--ds-danger); }
+.ds-option[data-danger="true"]:hover { background: var(--ds-error-soft); }
+.ds-popup-search { display: flex; align-items: center; gap: 8px; position: relative; padding: 4px 8px 8px; color: var(--ds-muted); }
+.ds-popup-search input { min-width: 0; width: 100%; padding: 7px 4px; border: 0; border-radius: 0; background: transparent; color: var(--ds-text); font: inherit; outline: 0; box-shadow: none; caret-color: var(--ds-text); }
+.ds-popup-search input:focus, .ds-popup-search input:focus-visible { border: 0; outline: 0; background: transparent; box-shadow: none; }
+.ds-popup-search[data-keyboard-focus="true"]:focus-within::before { content: ""; position: absolute; left: 0; top: 50%; width: 2px; height: 14px; border-radius: 1px; background: var(--ds-focus); transform: translateY(-50%); }
+.ds-popup-empty { padding: 18px 8px; color: var(--ds-muted); text-align: center; font-size: 13px; }
+.ds-popup-footer { display: flex; justify-content: space-between; gap: 8px; padding: 6px 2px 0; border-top: 1px solid var(--ds-border); }
+.ds-calendar-head { display: flex; align-items: center; justify-content: space-between; margin-bottom: 8px; font-weight: 600; }
+.ds-calendar-week { display: grid; grid-template-columns: repeat(7, minmax(0, 1fr)); gap: 2px; text-align: center; }
+.ds-calendar-weekdays { color: var(--ds-muted); font-size: 11px; line-height: 28px; }
+.ds-calendar-day { width: 100%; height: 34px; border: 0; border-radius: var(--ds-radius); background: transparent; color: var(--ds-text); font: inherit; font-size: 13px; cursor: pointer; }
+.ds-calendar-day:hover, .ds-calendar-day:focus-visible { background: var(--ds-hover); outline: 0; }
+.ds-calendar-day:focus-visible { outline: 2px solid var(--ds-focus); outline-offset: -2px; }
+.ds-calendar-day[data-outside="true"] { color: var(--ds-muted); }
+.ds-calendar-day[data-today="true"]:not([aria-selected="true"]) { color: var(--ds-action); font-weight: 700; text-decoration: underline; text-underline-offset: 4px; }
+.ds-calendar-day[aria-selected="true"] { background: var(--ds-action); color: var(--ds-on-action); }
+.ds-calendar-day[aria-selected="true"]:focus-visible { outline-color: var(--ds-on-action); outline-offset: -4px; }
+.ds-calendar-day:disabled { opacity: .35; cursor: not-allowed; }
+.ds-check, .ds-radio, .ds-switch { display: inline-flex; align-items: center; gap: 7px; min-height: 32px; font-size: var(--ds-font); cursor: pointer; }
+.ds-check input, .ds-radio input { appearance: none; display: grid; place-content: center; width: 16px; height: 16px; margin: 0; border: 1px solid var(--ds-border); background: var(--ds-field); }
+.ds-check input { border-radius: 3px; }
+.ds-check input:checked { background: var(--ds-action); border-color: var(--ds-action); }
+.ds-check input:checked::after { content: ""; width: 7px; height: 4px; border: solid var(--ds-on-action); border-width: 0 0 1.7px 1.7px; transform: translateY(-1px) rotate(-45deg); }
+.ds-radio input { border-radius: 50%; }
+.ds-radio input:checked { border-color: var(--ds-action); }
+.ds-radio input:checked::after { content: ""; width: 8px; height: 8px; border-radius: 50%; background: var(--ds-action); }
+.ds-switch input { position: absolute; opacity: 0; width: 30px; height: 18px; margin: 0; }
+.ds-switch-track { width: 30px; height: 18px; position: relative; border-radius: 20px; background: var(--ds-border); }
+.ds-switch-track::after { content: ""; position: absolute; top: 3px; left: 3px; width: 12px; height: 12px; border-radius: 50%; background: var(--ds-surface); transition: transform .15s; }
+.ds-switch input:checked + .ds-switch-track { background: var(--ds-action); }
+.ds-switch input:checked + .ds-switch-track::after { background: var(--ds-on-action); }
+.ds-switch input:checked + .ds-switch-track::after { transform: translateX(12px); }
+.ds-switch input:focus-visible + .ds-switch-track, .ds-check input:focus-visible, .ds-radio input:focus-visible { outline: 2px solid var(--ds-focus); outline-offset: 2px; }
+.ds-segment, .ds-tabs { display: inline-flex; align-items: center; gap: 3px; }
+.ds-segment { padding: 3px; border-radius: calc(var(--ds-radius) + 2px); background: var(--ds-hover); }
+.ds-segment button, .ds-tabs button { padding: 4px 12px; border: 0; border-radius: var(--ds-radius); background: transparent; color: var(--ds-muted); line-height: 20px; cursor: pointer; }
+.ds-segment button[aria-pressed="true"] { background: var(--ds-surface); color: var(--ds-action); }
+.ds-tabs button { border-radius: 0; border-bottom: 2px solid transparent; }
+.ds-tabs button[aria-selected="true"] { border-bottom-color: var(--ds-action); color: var(--ds-action); }
+.ds-segment button:focus-visible, .ds-tabs button:focus-visible { outline: 2px solid var(--ds-focus); outline-offset: 1px; }
+.ds-number, .ds-affix { display: flex; align-items: center; gap: 4px; padding: 0 var(--ds-pad); }
+.ds-number { padding: 0; }
+.ds-number input, .ds-affix input { flex: 1; min-width: 0; height: calc(var(--ds-height) - 2px); padding: 0 6px; border: 0; background: transparent; color: var(--ds-text); font: inherit; font-size: var(--ds-font); outline: 0; }
+.ds-number input { text-align: center; font-variant-numeric: tabular-nums; }
+.ds-number button { width: calc(var(--ds-height) - 2px); height: calc(var(--ds-height) - 2px); border: 0; border-radius: var(--ds-radius); background: transparent; color: var(--ds-muted); cursor: pointer; }
+.ds-number button:hover, .ds-number button:focus-visible { background: var(--ds-action-soft); color: var(--ds-action); outline: 0; }
+.ds-affix > span { white-space: nowrap; color: var(--ds-muted); font-size: 12px; }
+.ds-status { display: inline-flex; align-items: center; gap: 6px; font-size: 12px; line-height: 20px; color: var(--ds-muted); }
+.ds-status::before { content: ""; width: 5px; height: 5px; border-radius: 50%; background: currentColor; }
+.ds-status[data-tone="success"] { color: var(--ds-success); }
+.ds-status[data-tone="warning"] { color: var(--ds-warning); }
+.ds-status[data-tone="danger"] { color: var(--ds-danger); }
+.ds-tag { display: inline-flex; align-items: center; gap: 6px; padding: 3px 6px 3px 9px; border-radius: var(--ds-radius); background: var(--ds-hover); font-size: 12px; }
+.ds-tag button { width: 22px; height: 22px; border: 0; border-radius: 3px; background: transparent; color: var(--ds-muted); cursor: pointer; }
+.ds-tag button:hover, .ds-tag button:focus-visible { background: var(--ds-action-soft); color: var(--ds-action); outline: 0; }
+.ds-slider { appearance: none; display: block; width: 100%; height: 20px; margin: 10px 0; background: transparent; cursor: pointer; }
+.ds-slider::-webkit-slider-runnable-track { height: 4px; border-radius: 4px; background: linear-gradient(to right, var(--ds-action) 0 var(--ds-slider-progress), var(--ds-hover) var(--ds-slider-progress) 100%); }
+.ds-slider::-webkit-slider-thumb { appearance: none; width: 14px; height: 14px; margin-top: -5px; border: 3px solid var(--ds-action); border-radius: 50%; background: var(--ds-surface); }
+.ds-slider::-moz-range-track { height: 4px; border-radius: 4px; background: var(--ds-hover); }
+.ds-slider::-moz-range-progress { height: 4px; background: var(--ds-action); }
+.ds-slider::-moz-range-thumb { width: 10px; height: 10px; border: 3px solid var(--ds-action); border-radius: 50%; background: var(--ds-surface); }
+.ds-slider:focus-visible { outline: 2px solid var(--ds-focus); outline-offset: 3px; }
+.ds-progress { width: 100%; height: 4px; appearance: none; border: 0; border-radius: 4px; overflow: hidden; background: var(--ds-hover); }
+.ds-progress::-webkit-progress-bar { background: var(--ds-hover); }
+.ds-progress::-webkit-progress-value { background: var(--ds-action); }
+.ds-progress::-moz-progress-bar { background: var(--ds-action); }
+.ds-pagination { display: flex; align-items: center; gap: 4px; flex-wrap: wrap; }
+.ds-page-button[aria-current="page"] { background: var(--ds-action-soft); color: var(--ds-action); }
+.ds-dialog { width: min(480px, calc(100vw - 32px)); max-height: calc(100dvh - 32px); padding: 28px; border: 0; border-radius: calc(var(--ds-radius) + 4px); background: var(--ds-popover); color: var(--ds-text); box-shadow: 0 20px 80px var(--ds-shadow); overflow: auto; }
+.ds-dialog::backdrop { background: var(--ds-scrim); }
+.ds-dialog[data-drawer="true"] { width: min(440px, calc(100vw - 20px)); height: 100dvh; max-height: 100dvh; margin: 0 0 0 auto; border-radius: 0; }
+.ds-dialog-head, .ds-dialog-actions { display: flex; align-items: center; justify-content: space-between; gap: 16px; }
+.ds-dialog-head { margin-bottom: 24px; }
+.ds-dialog-head h2 { margin: 0; font-size: 20px; line-height: 28px; font-weight: 600; }
+.ds-dialog-actions { justify-content: flex-end; margin-top: 24px; }
+.ds-toast { position: fixed; z-index: 90; bottom: 24px; left: 50%; transform: translateX(-50%); padding: 10px 16px; border-radius: var(--ds-radius); background: var(--ds-text); color: var(--ds-surface); box-shadow: 0 6px 24px var(--ds-shadow); font-size: 13px; }
+.ds-flat-toolbar { display: flex; align-items: center; flex-wrap: wrap; gap: 10px; }
+.ds-flat-toolbar .ds-field-wrap { flex: 0 1 180px; }
+.ds-flat-toolbar .ds-field-wrap:first-of-type { flex-basis: 240px; }
+.ds-flat-form { display: grid; gap: 22px 20px; grid-template-columns: repeat(2, minmax(0, 1fr)); max-width: 920px; }
+.ds-flat-form [data-full="true"] { grid-column: 1 / -1; }
+@media (max-width: 640px) { .ds-flat-form { grid-template-columns: 1fr; } .ds-flat-form [data-full="true"] { grid-column: auto; } .ds-dialog { padding: 22px; } }
+@media (prefers-reduced-motion: reduce) { .ds-spinner { animation: none; } .ds-switch-track::after { transition: none; } }

package/skills/lark-base-database/references/design/components/code/controls.tsx

@@ -0,0 +1,73 @@
+import { forwardRef, useEffect, useId, useRef, useState, type ButtonHTMLAttributes, type CSSProperties, type InputHTMLAttributes, type ReactNode, type TextareaHTMLAttributes } from 'react';
+
+export type ControlVariant = 'primary' | 'secondary' | 'quiet' | 'danger';
+export type NamedOption<T extends string = string> = { value: T; label: string; disabled?: boolean };
+
+export const Button = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTMLButtonElement> & { variant?: ControlVariant; loading?: boolean; iconOnly?: boolean }>(function Button({ variant = 'quiet', loading = false, iconOnly = false, children, disabled, ...props }, ref) {
+  return <button {...props} ref={ref} type={props.type ?? 'button'} className={`ds-button ${props.className ?? ''}`} data-variant={variant} data-icon-only={iconOnly} disabled={disabled || loading} aria-busy={loading || undefined}>
+    {loading && <span className="ds-spinner" aria-hidden="true" />}{children}
+  </button>;
+});
+
+export function Field({ label, help, error, id, children }: { label: string; help?: string; error?: string; id: string; children: ReactNode }) {
+  return <div className="ds-field-wrap"><label className="ds-label" htmlFor={id}>{label}</label>{children}
+    {error ? <p className="ds-error" id={`${id}-message`}>{error}</p> : help ? <p className="ds-help" id={`${id}-help`}>{help}</p> : null}
+  </div>;
+}
+
+export const TextField = forwardRef<HTMLInputElement, InputHTMLAttributes<HTMLInputElement> & { error?: string; help?: string; label: string }>(function TextField({ id, label, error, help, className = '', ...props }, ref) {
+  const generated = useId(); const fieldId = id ?? generated;
+  return <Field id={fieldId} label={label} help={help} error={error}><input {...props} id={fieldId} ref={ref} className={`ds-field ${className}`} aria-label={label} aria-invalid={!!error || undefined} aria-describedby={error ? `${fieldId}-message` : help ? `${fieldId}-help` : undefined} /></Field>;
+});
+
+export const Textarea = forwardRef<HTMLTextAreaElement, TextareaHTMLAttributes<HTMLTextAreaElement> & { error?: string; help?: string; label: string }>(function Textarea({ id, label, error, help, className = '', onInput, value, defaultValue, ...props }, outerRef) {
+  const generated = useId(); const fieldId = id ?? generated; const localRef = useRef<HTMLTextAreaElement>(null);
+  const resize = () => { const el = localRef.current; if (!el) return; el.style.height = 'auto'; const cap = Number.parseFloat(getComputedStyle(el).maxHeight) || 220; el.style.height = `${Math.min(el.scrollHeight, cap)}px`; el.style.overflowY = el.scrollHeight > cap ? 'auto' : 'hidden'; };
+  useEffect(() => { resize(); const el = localRef.current; if (!el) return; const observer = new ResizeObserver(resize); observer.observe(el); return () => observer.disconnect(); }, [value, defaultValue]);
+  return <Field id={fieldId} label={label} help={help} error={error}><textarea {...props} id={fieldId} value={value} defaultValue={defaultValue} rows={props.rows ?? 3} className={`ds-field ds-textarea ${className}`} aria-label={label} aria-invalid={!!error || undefined} aria-describedby={error ? `${fieldId}-message` : help ? `${fieldId}-help` : undefined} ref={node => { localRef.current = node; if (typeof outerRef === 'function') outerRef(node); else if (outerRef) outerRef.current = node; }} onInput={event => { resize(); onInput?.(event); }} /></Field>;
+});
+
+export function Checkbox({ label, ...props }: InputHTMLAttributes<HTMLInputElement> & { label: string }) {
+  return <label className="ds-check"><input {...props} type="checkbox" />{label}</label>;
+}
+
+export function RadioGroup<T extends string>({ label, name, options, value, onChange }: { label: string; name: string; options: NamedOption<T>[]; value: T; onChange: (value: T) => void }) {
+  return <fieldset style={{ border: 0, padding: 0, margin: 0 }}><legend className="ds-label">{label}</legend><div style={{ display: 'flex', gap: 20, flexWrap: 'wrap' }}>{options.map(option => <label className="ds-radio" key={option.value}><input name={name} type="radio" checked={value === option.value} disabled={option.disabled} onChange={() => onChange(option.value)} />{option.label}</label>)}</div></fieldset>;
+}
+
+export function Switch({ label, checked, onChange, disabled = false }: { label: string; checked: boolean; onChange: (checked: boolean) => void; disabled?: boolean }) {
+  return <label className="ds-switch"><input type="checkbox" role="switch" checked={checked} onChange={event => onChange(event.target.checked)} disabled={disabled} /><span className="ds-switch-track" aria-hidden="true" />{label}</label>;
+}
+
+export function Segmented<T extends string>({ label, options, value, onChange }: { label: string; options: NamedOption<T>[]; value: T; onChange: (value: T) => void }) {
+  return <div className="ds-segment" role="group" aria-label={label}>{options.map(option => <button key={option.value} type="button" aria-pressed={value === option.value} disabled={option.disabled} onClick={() => onChange(option.value)}>{option.label}</button>)}</div>;
+}
+
+export function Tabs<T extends string>({ label, options, value, onChange, children }: { label: string; options: NamedOption<T>[]; value: T; onChange: (value: T) => void; children: ReactNode }) {
+  const id = useId(); const enabled = options.filter(option => !option.disabled);
+  return <><div className="ds-tabs" role="tablist" aria-label={label}>{options.map(option => <button key={option.value} id={`${id}-${option.value}`} type="button" role="tab" aria-controls={`${id}-panel`} aria-selected={value === option.value} tabIndex={value === option.value ? 0 : -1} disabled={option.disabled} onClick={() => onChange(option.value)} onKeyDown={event => { if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) return; event.preventDefault(); const index = enabled.findIndex(item => item.value === option.value); const next = event.key === 'Home' ? 0 : event.key === 'End' ? enabled.length - 1 : (index + (event.key === 'ArrowRight' ? 1 : -1) + enabled.length) % enabled.length; onChange(enabled[next].value); requestAnimationFrame(() => document.getElementById(`${id}-${enabled[next].value}`)?.focus()); }}>{option.label}</button>)}</div><div role="tabpanel" id={`${id}-panel`} aria-labelledby={`${id}-${value}`}>{children}</div></>;
+}
+
+export function NumberStepper({ label, value, onChange, min, max, step = 1, error }: { label: string; value: number; onChange: (value: number) => void; min?: number; max?: number; step?: number; error?: string }) {
+  const id = useId(), [draft, setDraft] = useState(String(value));
+  useEffect(() => setDraft(String(value)), [value]);
+  const clamp = (n: number) => Math.min(max ?? Infinity, Math.max(min ?? -Infinity, n));
+  const adjust = (direction: number) => { const places = Math.max((String(step).split('.')[1] ?? '').length, (String(value).split('.')[1] ?? '').length); onChange(clamp(Number((value + direction * step).toFixed(places)))); };
+  const commit = () => { const n = Number(draft); const next = draft.trim() && Number.isFinite(n) ? clamp(n) : value; onChange(next); setDraft(String(next)); };
+  return <Field id={id} label={label} error={error}><div className="ds-number" data-invalid={!!error}><button type="button" aria-label={`减少${label}`} disabled={min !== undefined && value <= min} onClick={() => adjust(-1)}>−</button><input id={id} type="text" inputMode="decimal" role="spinbutton" value={draft} aria-label={label} aria-valuenow={value} aria-valuemin={min} aria-valuemax={max} aria-invalid={!!error || undefined} aria-describedby={error ? `${id}-message` : undefined} onChange={event => { const text = event.target.value; setDraft(text); if (text.trim() && Number.isFinite(Number(text))) onChange(Number(text)); }} onBlur={commit} onKeyDown={event => { if (event.key === 'ArrowUp' || event.key === 'ArrowDown') { event.preventDefault(); adjust(event.key === 'ArrowUp' ? 1 : -1); } }} /><button type="button" aria-label={`增加${label}`} disabled={max !== undefined && value >= max} onClick={() => adjust(1)}>+</button></div></Field>;
+}
+
+export function AffixInput({ label, prefix, suffix, error, ...props }: InputHTMLAttributes<HTMLInputElement> & { label: string; prefix?: string; suffix?: string; error?: string }) {
+  const id = useId(); return <Field id={id} label={label} error={error}><div className="ds-affix" data-invalid={!!error}>{prefix && <span aria-hidden="true">{prefix}</span>}<input {...props} id={id} aria-label={label} aria-invalid={!!error || undefined} aria-describedby={error ? `${id}-message` : undefined} />{suffix && <span aria-hidden="true">{suffix}</span>}</div></Field>;
+}
+
+export function Status({ children, tone = 'neutral' }: { children: ReactNode; tone?: 'neutral' | 'success' | 'warning' | 'danger' }) { return <span className="ds-status" data-tone={tone}>{children}</span>; }
+export function Tag({ children, onRemove, removeLabel }: { children: ReactNode; onRemove?: () => void; removeLabel?: string }) { return <span className="ds-tag">{children}{onRemove && <button type="button" aria-label={removeLabel ?? '移除标签'} onClick={onRemove}>×</button>}</span>; }
+export function Slider({ label, value, onChange, min = 0, max = 100, step = 1 }: { label: string; value: number; onChange: (value: number) => void; min?: number; max?: number; step?: number }) {
+  const id = useId(); const pct = max > min ? Math.max(0, Math.min(100, (value - min) / (max - min) * 100)) : 0; return <div className="ds-field-wrap"><div style={{ display: 'flex', justifyContent: 'space-between' }}><label htmlFor={id}>{label}</label><output htmlFor={id}>{value}</output></div><input className="ds-slider" id={id} type="range" value={value} min={min} max={max} step={step} style={{ '--ds-slider-progress': `${pct}%` } as CSSProperties} onChange={event => onChange(Number(event.target.value))} /></div>;
+}
+export function Progress({ label, value, max = 100 }: { label: string; value?: number; max?: number }) { return <progress className="ds-progress" aria-label={label} value={value} max={max} />; }
+export function Pagination({ page, pageCount, onPageChange, label = '分页' }: { page: number; pageCount: number; onPageChange: (page: number) => void; label?: string }) {
+  const pages = Array.from({ length: Math.min(pageCount, 5) }, (_, i) => Math.min(Math.max(1, page - 2), Math.max(1, pageCount - 4)) + i);
+  return <nav className="ds-pagination" aria-label={label}><Button iconOnly aria-label="上一页" disabled={page <= 1} onClick={() => onPageChange(page - 1)}>‹</Button>{pages.map(n => <Button key={n} className="ds-page-button" aria-current={n === page ? 'page' : undefined} onClick={() => onPageChange(n)}>{n}</Button>)}<Button iconOnly aria-label="下一页" disabled={page >= pageCount} onClick={() => onPageChange(page + 1)}>›</Button></nav>;
+}

package/skills/lark-base-database/references/design/components/code/date-picker.tsx

@@ -0,0 +1,42 @@
+import { useEffect, useId, useRef, useState, type KeyboardEvent } from 'react';
+import { Button, Field } from './controls';
+import { Floating } from './floating';
+
+const iso = (date: Date) => `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+const parse = (value: string) => { const [y, m, d] = value.split('-').map(Number); return new Date(y, m - 1, d); };
+const shift = (value: string, days: number) => { const d = parse(value); d.setDate(d.getDate() + days); return iso(d); };
+const monthShift = (value: string, months: number) => { const d = parse(value), day = d.getDate(); const target = new Date(d.getFullYear(), d.getMonth() + months, 1); target.setDate(Math.min(day, new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate())); return iso(target); };
+
+export function DatePicker({ label, value, onChange, min, max, disabledDate, error, help, disabled = false }: { label: string; value: string | null; onChange: (value: string | null) => void; min?: string; max?: string; disabledDate?: (date: string) => boolean; error?: string; help?: string; disabled?: boolean }) {
+  const id = useId(), ref = useRef<HTMLButtonElement>(null), [open, setOpen] = useState(false);
+  const [month, setMonth] = useState(() => value ? parse(value) : new Date());
+  const [active, setActive] = useState(() => value ?? iso(new Date()));
+  const today = iso(new Date());
+  const start = new Date(month.getFullYear(), month.getMonth(), 1);
+  start.setDate(1 - (start.getDay() + 6) % 7);
+  const days = Array.from({ length: 42 }, (_, i) => { const d = new Date(start); d.setDate(start.getDate() + i); return iso(d); });
+  const allowed = (date: string) => (!min || date >= min) && (!max || date <= max) && !disabledDate?.(date);
+  const close = () => setOpen(false);
+  const focusDay = (next: string) => { const direction = next >= active ? 1 : -1; let target = next; for (let i = 0; i < 42 && !allowed(target); i++) target = shift(target, direction); if (!allowed(target)) return; setActive(target); setMonth(parse(target)); requestAnimationFrame(() => document.getElementById(`${id}-${target}`)?.focus()); };
+  useEffect(() => { if (open) requestAnimationFrame(() => document.getElementById(`${id}-${active}`)?.focus()); }, [open]);
+  const onCalendarKey = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (!(event.target instanceof HTMLButtonElement) || !event.target.dataset.date) return;
+    const current = event.target.dataset.date;
+    const offsets: Record<string, number> = { ArrowLeft: -1, ArrowRight: 1, ArrowUp: -7, ArrowDown: 7 };
+    let next = event.key in offsets ? shift(current, offsets[event.key]) : null;
+    if (event.key === 'Home') next = shift(current, -((parse(current).getDay() + 6) % 7));
+    if (event.key === 'End') next = shift(current, 6 - ((parse(current).getDay() + 6) % 7));
+    if (event.key === 'PageUp' || event.key === 'PageDown') next = monthShift(current, (event.key === 'PageUp' ? -1 : 1) * (event.shiftKey ? 12 : 1));
+    if (next) { event.preventDefault(); focusDay(next); }
+  };
+  return <Field id={id} label={label} error={error} help={help}>
+    <button id={id} ref={ref} type="button" className="ds-trigger" aria-label={`${label}：${value ?? '选择日期'}`} aria-haspopup="dialog" aria-expanded={open} aria-invalid={!!error || undefined} aria-describedby={error ? `${id}-message` : help ? `${id}-help` : undefined} disabled={disabled} onClick={() => { if (!open) { setMonth(value ? parse(value) : new Date()); setActive(value ?? today); } setOpen(!open); }}><span className="ds-trigger-value">{value ? value.replaceAll('-', ' / ') : '选择日期'}</span><span className="ds-trigger-caret" aria-hidden="true">▦</span></button>
+    <Floating triggerRef={ref} open={open} onClose={close} ariaLabel={`${label}选择器`} width={304}>
+      <div onKeyDown={onCalendarKey}><div className="ds-calendar-head"><Button iconOnly aria-label="上个月" onClick={() => focusDay(iso(new Date(month.getFullYear(), month.getMonth() - 1, 1)))}>‹</Button><span aria-live="polite">{month.getFullYear()} 年 {month.getMonth() + 1} 月</span><Button iconOnly aria-label="下个月" onClick={() => focusDay(iso(new Date(month.getFullYear(), month.getMonth() + 1, 1)))}>›</Button></div>
+        <div role="grid" aria-label={`${month.getFullYear()}年${month.getMonth() + 1}月`}><div role="row" className="ds-calendar-week ds-calendar-weekdays">{['一','二','三','四','五','六','日'].map(name => <span role="columnheader" key={name}>{name}</span>)}</div>
+          {Array.from({ length: 6 }, (_, row) => <div role="row" className="ds-calendar-week" key={row}>{days.slice(row * 7, row * 7 + 7).map(date => <div role="gridcell" aria-selected={date === value} key={date}><button id={`${id}-${date}`} className="ds-calendar-day" type="button" data-date={date} data-outside={parse(date).getMonth() !== month.getMonth()} data-today={date === today} aria-current={date === today ? 'date' : undefined} aria-selected={date === value} aria-label={`${parse(date).getFullYear()}年${parse(date).getMonth() + 1}月${parse(date).getDate()}日`} tabIndex={date === active ? 0 : -1} disabled={!allowed(date)} onClick={() => { onChange(date); close(); ref.current?.focus(); }}>{parse(date).getDate()}</button></div>)}</div>)}</div>
+        <div className="ds-popup-footer"><Button onClick={() => { onChange(null); close(); ref.current?.focus(); }}>清空</Button><Button variant="secondary" disabled={!allowed(today)} onClick={() => { onChange(today); close(); ref.current?.focus(); }}>今天</Button></div>
+      </div>
+    </Floating>
+  </Field>;
+}