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

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

@@ -0,0 +1,323 @@
+# 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[]` 位置参数；其他形态按[生成参考](base-sql-errors.generated.md)判定。空数组不会选中记录。数组含 `null` 时不保证 PostgreSQL 三值语义，具体结果与预处理规则见[NULL 与数值边界](database-function-limitations.md#null-与数值边界)。成员判断与数组展开的区别及修法以[生成参考](base-sql-errors.generated.md)为准。
+
+无参数 Function 可以省略 `meta` 或 `meta.params`；归档统一补成 `{"params":[]}`。
+
+Database Function 的 `inputSchema` 由 CLI 根据参数顺序与 kind 生成固定长度数组 Schema，不在 Database Function 的 `meta.json` 中手写。FaaS 则必须显式声明，见[FaaS 开发](faas.md#faas-开发)。
+
+## 查询约束
+
+只编写只读 `SELECT`，页面输入只能进入位置参数。具体能力、拒绝条件与修法以[目录生成的错误与替代写法](base-sql-errors.generated.md)为准；生成原则见[能力边界](database-function-limitations.md#查询生成边界)。
+
+- 每条查询的最终查询计划必须引用至少一个 Catalog 中的真实表，用于 Project 执行时选择可路由的表依赖。根 `FROM` 可以是带别名的 `FROM (SELECT ...) AS alias` 派生表，但该派生表或它依赖的 CTE 必须读取真实表。
+- 默认逐列投影并使用 `AS snake_case`，保持输出 Schema 稳定；连接的每一侧保持为一个表或带别名的派生表。常规生成优先简单连接、顶层查询和带别名的派生表，复杂组合依据生成参考及验证结果决定。
+- 子查询优先作为带别名的 `FROM` 派生表使用，外层通过输出列名引用结果。需要其他形态时先核对业务语义与生成参考，不把默认生成偏好当作支持清单。
+- 列表使用有界 `LIMIT` 和稳定排序；排序值可能重复时最后按 `rec_id` 排序。不把截断结果的前端分页视为完整分页或全量导出。
+- 搜索写 `field LIKE $1`，由参数携带 `%`。
+- 当前访问者使用 `CURRENT_USER_ID()`，不由页面传入用户 ID。权限关系的实现边界按[权限设计](permission-design.md#读路径database-function-就是策略面)。
+- UDT 列成员使用 PostgreSQL 复合类型括号语法：无表别名写 `("负责人").id`、`("链接").link`，带表别名写 `(t."负责人").id`。FILE 的成员为 `.token/.name/.mime_type/.size`；逐元素读取后的 range alias 成员写 `u.id`。
+- 集合字段的 PostgreSQL 数组运算符含义为：`@>`（包含）、`<@`（被包含）、`&&`（有交集）。先用 Catalog 的 `sqlType` 区分标量与集合，再按生成参考判断操作是否适用；展开集合前确认业务是否允许改变主表行数。
+- 时间条件使用 Catalog 中确认为 `TIMESTAMP` 的字段和 `TIMESTAMP` 位置参数；当前时间使用 `CURRENT_TIMESTAMP`。查询结果固定为 Base 执行时区下的 `YYYY-MM-DD HH:mm:ss.SSS` 字符串。`EXTRACT(EPOCH FROM timestamp_expr)` 返回保留小数秒的 `DOUBLE`；明确只需整数秒时再写 `::bigint`。
+- 窗口、聚合、字符串、日期和数值计算先明确结果契约，再查[目录生成的修法与已验证 SQL](base-sql-errors.generated.md)。默认采用满足前提的形式；例外是没有等价 SQL 或改写改变所需语义，此时统一按[SQL 外实现放在哪](../SKILL.md#sql-外实现放在哪)选择实现位置。
+
+字段类型和成员来自 Catalog，输入按本节参数协议声明；适用的字段操作与修复路径查[生成参考](base-sql-errors.generated.md)，而不是从字段名称推断。示例演示参数和结果消费，不作为完整能力清单。
+
+条件聚合示例：
+
+```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，又需要保留空集合主表行，先核对[生成参考中的语义前提](base-sql-errors.generated.md)；没有等价形式时按[SQL 外实现选择原则](../SKILL.md#sql-外实现放在哪)处理。拆分后的输入若在开始时已经确定，应并发调用。
+
+搜索、筛选、关联和聚合尽量在查询中完成。没有关系、不同步消费或需要隔离失败语义的结果集可以拆分；拆分后的输入若在开始时已经确定，应并发调用。
+
+## 调用与结果
+
+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": "2026-07-18 10:00:00.000"
+      }
+    ],
+    "columns": [],
+    "row_count": 1,
+    "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/development.md

@@ -1,51 +1,94 @@
 # Page 开发与 Function 调用
 
-实现或修改 Page 的运行时接入时读取。FaaS 新增或修改时，还须在 meta.json 显式声明 inputSchema，见[FaaS 开发](faas.md#faas-开发)。SQL 方言见[SQL Function](sql-function.md)，服务端 handler 与记录写入见[FaaS 协议](faas.md)，设计原则见[工程质量](style-guide.md)。
+实现或修改 Page 的运行时接入时读取。FaaS 新增或修改时，还须在 meta.json 显式声明 inputSchema，见[FaaS 开发](faas.md#faas-开发)。基础单表写入与批量调用见[Mutation Function](mutations.md)。查询语法见[Database Function](database-function.md)，服务端 handler 与记录写入见[FaaS 协议](faas.md)，设计原则见[工程质量](style-guide.md)。
 
 ## 工程结构
 
 ```text
 project/
 ├── page/
-├── sql/<functionId>/{main.sql,meta.json}
+├── database-functions/<functionId>/{main.sql,meta.json}
+├── mutations/<functionId>/{spec.json,meta.json}
 └── server-functions/functions/<functionId>/{index.ts,meta.json}
 ```
 
-SQL 与 FaaS 的 `functionId` 在 应用 内全局唯一，匹配 `/^[A-Za-z0-9_-]+$/`；SQL ID 长度为 1～64。`functionId` 会作为 URL 路径段参与运行态调用，除该字符集外不接受其它字符。不同 FaaS Function 目录独立构建，不跨目录 import。Page 和 `server-functions/` 分别维护自己的 npm 工程与 `package-lock.json`。
+Database Function、Mutation 与 FaaS 的 `functionId` 在应用内全局唯一，匹配 `/^[A-Za-z0-9_-]+$/`；Database Function ID 长度为 1～64。`functionId` 会作为 URL 路径段参与运行态调用，除该字符集外不接受其它字符。不同 FaaS Function 目录独立构建，不跨目录 import。Page 和 `server-functions/` 分别维护自己的 npm 工程与 `package-lock.json`。
+
+## 第三方依赖策略
+
+为 Page 或 FaaS 新增、升级第三方 npm 依赖前，先查询当前应用的服务端策略。路径参数 `<app-token>` 是当前应用的 appToken，从工程的 `base-database.jsonc` 读取（不是 Base token）：
+
+```bash
+base-database-cli lark-cli -- api GET /open-apis/base/v3/sites/<app-token>/get --params '{"withDependencyPolicy":true}' --json
+```
+
+响应中的 `data.dependencyPolicy` 是唯一策略事实源，字段形如：
+
+```json
+{
+  "restrictedProtocols": ["file", "git"],
+  "rejectLocalPaths": true,
+  "rejectScpGitSyntax": true,
+  "rejectHostedGitShorthand": true,
+  "allowedValues": ["https://registry[.]example[.]com/.*[.]tgz"]
+}
+```
+
+普通 npm registry 版本、semver、`npm:` alias 和服务端未限制的协议默认可用。四个限制字段分别控制：`restrictedProtocols` 列出禁用的 URL 协议，如 `file:../pkg`、`git+https://example.com/pkg.git`；`rejectLocalPaths` 拒绝本地路径，如 `../pkg`、`/tmp/pkg`；`rejectScpGitSyntax` 拒绝 SCP 风格 Git 地址，如 `git@example.com:team/pkg.git`；`rejectHostedGitShorthand` 拒绝 hosted-git shorthand，如 `github:team/pkg`、`team/pkg`。
+
+`allowedValues` 的每一项都是 RE2 语法的正则表达式；受限来源只有在原始 dependency value（未 trim、未改大小写）被其中某项**完整匹配**时才可用。不能按包名、域名、前缀或子串推断放行，也不能把 `allowedValues` 解释成 npm 包名白名单。固定字符串里的 `.`、`+`、`?` 等正则元字符必须写成 `[.]`、`\+`、`[?]` 等转义形式。
+
+策略查询失败、字段缺失或类型错误，或 `allowedValues` 含非法正则时，停止添加依赖，保留错误信息与 LogID 并通过支持渠道反馈；不用内置列表或历史策略继续。`deploy` 会在安装依赖前再次查询策略，递归校验最终制品范围内的全部 `package.json`；本地预检通过不替代上传接口的最终校验。
 
 ## Function 调用契约
 
-ABI 是 Page、应用 loader 与 Function 之间固定的数据边界。Page 侧两类 Function 都通过 `invokeDatabaseFunction(functionId, params)` 调用，但 `params` 类型不同：
+Page 与 Function 之间使用固定的调用契约。Page 侧三类 Function 都通过 `invokeDatabaseFunction(functionId, params)` 调用，但 `params` 类型不同：
 
 `functionId` 使用源码目录名，是工程常量。应用 token 由 `page/src/lib/database-runtime.ts` 从产物托管路径解析，不由业务代码传入；FaaS 内部的 `context.invokeFunction` 仍使用 `{projectId,functionId,params}`，两者不要混用。
 
-| Function | `params` | 实现 | 结果 |
-|---|---|---|---|
-| SQL | 按 `$1`、`$2` 排列的数组 | `main.sql` + `meta.json` | 一层 `{data:{rows},code,msg}` |
-| FaaS | 业务对象 | `index.ts` + `meta.json` | 一层 `{data,code,msg}`，`data` 是 handler 业务数据 |
+| Function               | `params`                                   | 实现                     | 结果                                                                                 |
+| ---------------------- | ------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------ |
+| Database Function       | 按 `$1`、`$2` 排列的数组                   | `main.sql` + `meta.json` | 一层 `{data:{rows},code,msg}`                                                        |
+| Mutation               | 声明顺序的位置数组；多组参数用批量 helper | `spec.json` + `meta.json` | 一层 `{data:{record_ids,records?,record_not_found?,ignored_fields?},code,msg}`       |
+| FaaS                   | 业务对象                                   | `index.ts` + `meta.json` | 一层 `{data,code,msg}`，`data` 是 handler 业务数据                                   |
 
-SQL 示例：
+Database Function 查询示例：
 
 ```ts
-await invokeDatabaseFunction<{ rows: unknown[] }>('listTasks', ['待处理'])
+await invokeDatabaseFunction<{ rows: unknown[] }>('listTasks', ['待处理']);
 ```
 
+Mutation 一组参数使用 `invokeDatabaseFunction(functionId, params)`，每组操作一条记录；多组参数使用 `invokeDatabaseMutationBatch(functionId, parameterGroups)`，包装成 `{batch:[{params:[...]}]}`，不能与顶层 params 混用。两个 helper 均从 `page/src/lib/database-runtime.ts` 导出。`code=0` 仍须检查 `data.record_not_found/ignored_fields`，见[调用与结果](mutations.md#调用与结果)。
+
 FaaS 创建操作示例：
 
 ```ts
 await invokeDatabaseFunction<{ created: boolean | null }>('createTask', {
   title: '准备评审',
   status: '待处理',
-})
+});
 ```
 
+`base-database-cli check --json` 与 Preview `deploy` 会先校验本地 Function metadata，再把 Database Function 的
+`meta.params` 和 FaaS `inputSchema` 生成到
+`page/src/lib/database-function-inputs.generated.ts`，随后才编译 Page。不要手改该文件；新增或修改
+Function 后运行 `check`，让 `functionId`、查询参数顺序以及 FaaS 必填字段和枚举值在 Page
+编译时保持一致。动态字符串不能作为 `functionId` 绕过这份本地契约。
+
+metadata 只声明输入，因此生成文件只约束调用参数。调用结果仍由 Page 按 operation 定义
+`invokeDatabaseFunction<TData>` 的 `TData`，并在运行时校验真实响应；CLI 不根据 handler
+实现或查询投影猜测返回类型。生成类型覆盖标量类型、对象属性、必填项、枚举、数组元素和
+`prefixItems` 位置，以及 Database Function 的固定参数 tuple；`minimum`、`maximum`、`minLength`、
+`maxLength`、非固定数组的 `minItems` / `maxItems` 和对象精确性仍由 Function 运行时校验；
+数组的元素类型和 `prefixItems` 位置仍保留在生成类型中。TypeScript 类型不能替代输入解析。
+
 `invokeDatabaseFunction` 调用统一网关的 `POST /space/api/bitable/site/v1/:token/invoke_function/:function_id`，由 BaseApp 父页面以同源身份代发；应用 token 与环境由 `src/lib/database-runtime.ts` 统一解析，`env` 走 query，请求体固定为 `{"params": <上述 params>}`。返回统一包裹结构 `{code,msg,data}`，页面使用当前登录用户身份，不保存也不传递任何凭证。
 
 ## Page 调用
 
-默认 Page 的 `page/index.html` 需要把 `<title>` 设置为本次生成的 应用 名称，不留空。
+默认 Page 的 `page/index.html` 需要把 `<title>` 设置为本次生成的应用名称，不留空。
 
-默认 Page 必须引用并渲染 `page/src/components/floating-button/index.tsx` 中的 `FloatingButton` 组件，并显式传入 `language`。该组件自行解析应用 token，不接受 `projectId`。悬浮控件提供「编辑应用」和 Chatbot 入口。
+默认 Page 必须引用并渲染 `page/src/components/floating-button/index.tsx` 中的 `FloatingButton` 组件。该组件自行解析应用 token，不接受 `projectId`。悬浮控件仅在正式环境向服务端判定有管理权限的访问者提供「编辑应用」入口。
 
 当前账号信息（头像、姓名、组织、退出登录）由**应用自己的导航**承载，用 `page/src/components/database-user-menu/index.tsx` 的 `DatabaseUserMenu`。账号菜单位于应用导航区域，例如顶栏右上角或侧边栏底部：
 
@@ -54,13 +97,13 @@ await invokeDatabaseFunction<{ created: boolean | null }>('createTask', {
 <header className="flex items-center justify-between ...">
   <h1>设备台账</h1>
   {/* 判据：员工 / 部门 / 领用归还属于组织内多角色协作 */}
-  <DatabaseUserMenu language="zh" audience="enterprise" />
+  <DatabaseUserMenu audience="enterprise" />
 </header>
 
 // 侧边栏左下角
 <aside className="flex flex-col ...">
   <nav className="flex-1">…</nav>
-  <DatabaseUserMenu language="zh" audience="enterprise" align="left" side="up" />
+  <DatabaseUserMenu audience="enterprise" align="left" side="up" />
 </aside>
 ```
 
@@ -71,36 +114,126 @@ await invokeDatabaseFunction<{ created: boolean | null }>('createTask', {
 `page/src/main.tsx` 已在首屏挂载后通过 `DatabaseRuntimeReady` 上报 `siteRuntime.ready()`，并在启动失败时上报 `reportLoadFailed`。宿主从握手完成起 10 秒内等不到 ready 会展示加载失败态，因此不要把 ready 上报移到数据加载完成之后，也不要删除该组件。
 
 涉及人员搜索或人员选择的页面，优先引用 `page/src/components/UserSelectorEditor` 和 `page/src/components/UserSelectorPanel` 等 `page/src/components/` 下的人员组件；只有现有组件无法满足交互契约时才做局部扩展。
-选人组件返回的 `User.user_id` 是 Base 人员单元格使用的内部用户 ID；写入人员字段时固定传 `[{"id": user.user_id}]`。`User.open_id` 只是可选的开放平台标识，不得填入 应用记录 写入 payload。
+这些一方组件以及 `DatabaseUserMenu`、`FloatingButton`、`PageState`、`AttachmentImage` 内置中文、英文、日文固定文案，不依赖 Starling。组件统一按宿主 Runtime Context 的 locale → 浏览器语言 → 英语选择文案，无需 Page 传入或写死语言；宿主切换语言后，组件随重新加载的页面重新解析。Page 自己编写的业务文案仍由应用负责。
+选人组件返回的 `User.user_id` 是 Base 人员单元格使用的内部用户 ID。Mutation 的 `USER_ID` 参数传该 ID 字符串，`list:true` 时传 ID 数组；FaaS 下游人员单元格传 `[{"id": user.user_id}]`。`User.open_id` 只是可选的开放平台标识，不得填入应用记录写入 payload。
 
 业务请求集中在 operation/runtime client，不散落在组件中：
 
 ```ts
-import { invokeDatabaseFunction } from '../lib/database-runtime'
+import { invokeDatabaseFunction } from '../lib/database-runtime';
 
-interface SqlRows<TRow> {
-  rows: TRow[]
-  columns?: unknown[]
-  row_count?: number
-  log_id?: string
+interface DatabaseRows<TRow> {
+  rows: TRow[];
+  columns?: unknown[];
+  row_count?: number;
+  log_id?: string;
 }
 ```
 
-浏览器 SDK 对 SQL 和 FaaS 都只返回一层 `{data,code,msg}`。`invokeDatabaseFunction<TData>` 的 `TData` 只描述当前 operation 约定的顶层 `data`：SQL 通常是 ResultJSON，FaaS 则以各 handler 的业务结果为准，不能统一假设存在 `recordId`。页面只检查一次顶层 `code`，再按 operation 契约校验 `data`；不得写成 `invokeDatabaseFunction<FaasHandlerResult<TData>>`，也不得对 `result.data` 二次解包。否则后端已经写入成功时，页面仍可能误报失败。
+浏览器 SDK 对 Database Function、Mutation 和 FaaS 都只返回一层 `{data,code,msg}`。`invokeDatabaseFunction<TData>` 的 `TData` 只描述当前 operation 约定的顶层 `data`：Database Function 通常是 ResultJSON，FaaS 则以各 handler 的业务结果为准，不能统一假设存在 `recordId`。页面只检查一次顶层 `code`，再按 operation 契约校验 `data`；不得写成 `invokeDatabaseFunction<FaasHandlerResult<TData>>`，也不得对 `result.data` 二次解包。否则后端已经写入成功时，页面仍可能误报失败。
 
 运行时业务数据在边界处校验，不能只依赖 TypeScript 泛型。`functionId` 和所有路由是工程常量；用户输入只进入已声明的业务参数。
 
-Page 的所有业务 HTTP 都经父页面代理，使用 `page/src/lib/database-runtime.ts` 导出的 `fetch` 或 `invokeHttp`，URL 必须是以单个 `/` 开头的同源相对路径；绝对 URL、跨域 URL、路径穿越以及 Cookie、Authorization、Host、Origin 等受限 Header 都会被父页面拒绝。请求体只支持字符串，4xx/5xx 会正常返回 `Response`，业务必须自行判断 `response.ok`。禁止直连业务域名，也不得把直连作为代理失败时的兜底。Page 发起的 Base 业务读取和写入仍分别走 SQL Function 与 FaaS。
+Page 的所有业务 HTTP 都经父页面代理，使用 `page/src/lib/database-runtime.ts` 导出的 `fetch` 或 `invokeHttp`，URL 必须是以单个 `/` 开头的同源相对路径；绝对 URL、跨域 URL、路径穿越以及 Cookie、Authorization、Host、Origin 等受限 Header 都会被父页面拒绝。请求体只支持字符串，4xx/5xx 会正常返回 `Response`，业务必须自行判断 `response.ok`。禁止直连业务域名，也不得把直连作为代理失败时的兜底。Page 发起的 Base 业务读取和写入分别走 Database Function 与 Mutation/FaaS。
+
+## 日期与时区
+
+Database Function 返回类型与 FaaS 写入格式分别以 [查询类型](database-function.md#查询类型与结果值) 和 [CellValue 协议](faas.md#base-读写协议)为准；Mutation 日期参数见 [Mutation 声明与参数](mutations.md#声明与参数)。转换时先区分字段语义：
+
+| 业务语义                       | 应用内表示             | 转换边界                                                                     |
+| ------------------------------ | ---------------------- | ---------------------------------------------------------------------------- |
+| 入库日、生日、到期日等日历日期 | `YYYY-MM-DD` 字符串    | 从 Base TIMESTAMP 回填时按该字段约定的业务时区取日期；表单编辑期间保持字符串 |
+| 下单、上传等事件时刻           | Unix epoch 毫秒 number | 显示时按目标时区格式化；写入无偏移文本时按写入端解析时区格式化               |
+
+已有 Base 先通过 `lark-cli base +base-get --base-token <base-token>` 核对 `time_zone`；新建使用本次明确设置的 Base 时区。记录业务日期时区、写入解析时区及显示时区是否一致。`init` 的默认值、浏览器时区和 FaaS 进程时区都不能代替已有 Base 的真实配置；不要给所有应用固定加八小时。多 Base 应用分别确认。
+
+`toISOString()` 输出 UTC。`toISOString().slice(0, 10)` 只适用于明确要求 UTC 日期的场景，不能用于其他业务时区的日期回填；同样，截掉 `Z` 再将 UTC 文本作为本地时间写入，会改变事件时刻。不要对已正确的 epoch 再加偏移后交给带 `timeZone` 的格式化器，否则会重复转换。
+
+### 转换与编辑示例
+
+工程 `page/src/lib/date-time.ts` 提供不依赖浏览器或 SDK 的纯函数：
+
+- `formatDateInput(epochMs, timeZone)`：时间戳到该业务时区的 `YYYY-MM-DD`。
+- `formatBaseDateTime(epochMs, timeZone)`：时间戳到该时区的 `YYYY-MM-DD HH:mm:ss`。
+- `dateInputToBaseDateTime(value)`：校验日历日期并补 `00:00:00`，不先转成 UTC。
+
+旧工程没有 helper 时，从当前 CLI 的 starter 复制此文件并保持原工程其余接入。FaaS 需要使用时，将该无依赖文件复制到目标 `server-functions/functions/<functionId>/`，在同一 Function 内导入；不要跨 Function 或从 Page 目录运行时导入。
+
+以下 `BASE_TIME_ZONE` 是应用根据 Base 信息确定的常量，示例值不是默认值。不要让任意请求参数改变写入解释时区。
+
+```ts
+// Page：时间戳只在回填边界转换，用户输入仍保持日历日期。
+import { formatDateInput } from './lib/date-time';
+
+const BASE_TIME_ZONE = 'Asia/Shanghai'; // 示例：已核对该 Base 的 time_zone
+
+export function initialDate(stored: number | null): string {
+  return stored === null ? '' : formatDateInput(stored, BASE_TIME_ZONE);
+}
+
+export function editPayload(
+  publisher: string,
+  dateValue: string,
+  originalDate: string,
+) {
+  return {
+    publisher,
+    ...(dateValue !== originalDate ? { addedAt: dateValue } : {}),
+  };
+}
+```
+
+```ts
+// FaaS：同一 Function 目录内使用 helper，产生符合现有 CellValue 的文本。
+import { dateInputToBaseDateTime, formatBaseDateTime } from './date-time';
+
+const BASE_TIME_ZONE = 'Asia/Shanghai'; // 示例：已核对无偏移写入按此时区解释
+
+export function updateFields(input: { publisher: string; addedAt?: string }) {
+  return {
+    出版社: input.publisher,
+    ...(input.addedAt !== undefined
+      ? { 入库日期: dateInputToBaseDateTime(input.addedAt) }
+      : {}),
+  };
+}
+
+export function eventFields(now: number) {
+  return { 上传时间: formatBaseDateTime(now, BASE_TIME_ZONE) };
+}
+```
+
+示例采用日期字段的增量更新，因此更新 Schema 中 `addedAt` 为可选项，创建 Schema 可继续要求必填。handler 按 [FaaS 输入契约](faas.md#faas-开发)校验并处理 helper 抛出的无效日期错误。清空日期需明确提交清空操作，不把空字符串解释成清空或今天。
+
+无偏移文本不能唯一表示夏令时回拨时的重复小时。业务需要这类精确时刻往返时，先确认写入端支持的无歧义表示，不靠固定偏移或 helper 宣称已保证。显示时区与写入时区不同可以成立，但界面必须清楚表达，不能将显示文本直接回写。
+
+### 日期与时间验证
+
+- 纯日期：午夜前后、月末/年末、闰日；在不同浏览器/进程时区下回填相同业务日期。
+- 编辑：只修改其他字段，写入 payload 不包含日期，底表原日期不变；主动修改日期后回读与选择一致；空值和 epoch `0` 分别处理。
+- 事件：用已知 epoch 验证写入文本与目标时区，Database Function 回读后对应同一时刻（按接口精度比较），再分别验证页面和底表显示。覆盖实际使用时区的偏移和夏令时边界。
+
+历史数据偏移先核对原始值、字段语义与时区配置，再判断是否需要修复；不要因发现一处转换错误而批量平移历史时间。
+
+## AI 对话与调用
+
+AI 调用使用 AI Function，不创建 FaaS 模型代理，也不直连模型域名。
+Preview 使用草稿版本；Prod 使用正式发布的版本。Function 配置为 `disabled: true` 时不得调用。
+能力归属按运行场景判断：面向当前页面业务流程的生成、分类、总结和推荐使用 AI Function；Base 查询与写入仍分别使用 Database Function 和 FaaS。
+
+Page 需要 AI 对话、生成、分类、总结、文生图或文生视频时，默认按 `functionKey` 使用 `page/src/lib/database-runtime.ts` 导出的 `callSiteAIFunction` / `invokeSiteAIFunctionStream`，不创建 FaaS 模型代理，也不直连模型域名。AI 能力被收口成一类版本化托管的 AI Function 配置；四类能力配置契约、CLI 建模/调试、计费与单流约束见 [AI Function](ai-function.md)。starter 的 `page/src/examples/ai-function/TextStreamOperation.tsx` 提供最小组件示例。搭建时可复用这些示例的界面及 `ai-copy.ts`，保留 `useUiLanguage()` 接入；内置标题、提示、按钮、任务状态和本地兜底错误自动跟随宿主 locale → 浏览器语言 → 英语。Page 显式传入的 `title` 由 Page 自行处理，服务端错误与 AI 生成内容保留原文。
+
+AI 与 Base 数据组合时保持既有边界：先用 Database Function 读取，再由 Page 裁剪必要数据并拼入 `messages` 或 `variables`；需要把结果写回 Base 时另行调用 FaaS。AI 调用本身不经过 FaaS。
 
 ## 开发期与运行态输出
 
-| 调用层 | 判定方式 |
-| --- | --- |
-| lark-cli 默认 JSON 输出 | 先检查进程退出与外层 `ok`，再按该命令的 `data` 契约取值；错误诊断见 `error` |
-| Page `invokeDatabaseFunction` | 检查一次顶层 `code`，再校验 operation 的 `data` |
-| SQL Function | `data` 为 ResultJSON，包含 rows 等查询信息 |
-| FaaS handler | 返回 `{data,code,msg}`，data 为业务结果，不再由 Page 二次解包 |
-| FaaS 下游记录写入 | 检查下游 envelope 和各 batch 的结果语义，见[FaaS 协议](faas.md#应用记录-写入协议) |
+| 调用层                        | 判定方式                                                                          |
+| ----------------------------- | --------------------------------------------------------------------------------- |
+| lark-cli 默认 JSON 输出       | 先检查进程退出与外层 `ok`，再按该命令的 `data` 契约取值；错误诊断见 `error`       |
+| Page `invokeDatabaseFunction` | 检查一次顶层 `code`，再校验 operation 的 `data`                                   |
+| Database Function             | `data` 为 ResultJSON，包含 rows 等查询信息                                        |
+| FaaS handler                  | 返回 `{data,code,msg}`，data 为业务结果，不再由 Page 二次解包                     |
+| FaaS 下游记录写入             | 检查下游 envelope 和各 batch 的结果语义，见[FaaS 协议](faas.md#应用记录写入协议) |
 
 不要把 SDK 的 `code===0` 套在 CLI 外层，也不要将 CLI 外层的 data 当作 handler 业务数据。raw API 的命令封装与业务响应按当前 lark-cli reference 分别解析。
 
@@ -108,8 +241,8 @@ Page 的所有业务 HTTP 都经父页面代理，使用 `page/src/lib/database-
 
 实现前确定 operation 固定输入输出，按[工程质量](style-guide.md)检查远程调用依赖。新建示例数据在[发布阶段](release.md#从零建站示例数据验收)通过 CLI 写入真实 Base；不创建仅用于播种的 FaaS，也不在 Page 加载时自动写入。
 
-保留 starter 的 `createArgusCsrfPlugin()` 配置；不手写 CSRF token。Page 的读取与写入分别通过 SQL/FaaS，自动化使用[原生能力](base-capability-routing.md)，不从页面模拟后台定时任务。附件上传使用 `siteRuntime.uploadAttachment()`，缩略图与下载复用 starter 的 `buildAttachmentCoverUrl`、`fetchAttachmentDownloadUrl`；附件单元格追加/移除经 FaaS 调用增量路由，能力、并发和重试边界见[文件传输](file-transfer.md)。不能以 mock、未约定网关或旧列表整格覆盖代替。
+Page 的读取与写入分别通过 Database Function 与 Mutation/FaaS，自动化使用[原生能力](base-capability-routing.md)，不从页面模拟后台定时任务。附件上传使用 `siteRuntime.uploadAttachment()`，缩略图与下载复用 starter 的 `fetchAttachmentCover`、`fetchAttachmentDownloadUrl`；附件的写入选型、上传、展示与重试边界见[文件传输](file-transfer.md)。不能以 mock、未约定网关或旧列表整格覆盖代替。
 
-修改或恢复旧 应用 时，不能假定工程已接入该插件。写请求出现 CSRF 相关失败时，按[旧工程与 CSRF 排查](verification.md#旧工程与-csrf-排查)核对插件、依赖和构建产物；缺失时按当前 starter 补齐，必要时升级 JSSDK，再重建发布。不得复制插件实现或手写 `x-secsdk-csrf-token`。
+修改或恢复旧应用时，按[旧工程与 CSRF 排查](verification.md#旧工程与-csrf-排查)迁移页面通信和构建配置。业务请求的身份与 CSRF 处理由宿主负责；Page 不注入 CSRF 脚本或手写 CSRF Header。
 
 实现完成后按[发布与交付](release.md)继续；用户明确要求运行态检查时按[诊断与验收](verification.md)执行。