后端数据存储

store 是后端脚本读写业务数据的全局对象，数据存在插件自己的平台数据库表里。读取需申报 data:read，写入需申报 data:write（见能力目录）。

六个方法

所有方法同步返回统一结果：{ok: true, data} | {ok: false, error: {code, message}}。

store.query(entity, filter, options)                   // → {list, total, limit, offset}
store.count(entity, filter)                            // → {count}
store.insert(entity, record)                           // → 新记录（id/createdAt/updatedAt + 业务字段；未给 id 自动生成）
store.createIfAbsent(entity, record, uniqueBy)         // → {created, record}  原子「有则取、无则建」
store.update(entity, filter, patch)                    // → {affected}
store.delete(entity, filter)                           // → {deleted}

query 是三参：第二参是筛选条件（字段算子对象），第三参是 {orderBy, limit, offset} 选项。

要点	说明
`orderBy`	必须是数组，如 `[{field: 'createdAt', dir: 'desc'}]`；不指定按 `id ASC`，自定义排序末尾也会追加 `id ASC` 保证分页稳定
`createIfAbsent`	`uniqueBy` 必填（字段名数组），数据库要有对应唯一索引——这是并发去重的标准做法
`update` / `delete`	filter 强制非空；`affected === 0` 是正常的并发未命中，不是错误

没有 put/get，也没有事务、表连接、聚合和裸 SQL。

写入值为字符串映射（StoreFields）：布尔存 '1'/'0'，毫秒时间戳存定宽 13 位字符串。

筛选条件写法（`filter`）

const result = store.query('capture_record', {
  status: {eq: 'pending'},
  occurred_at_ms: [{gte: '1780000000000'}, {lte: '1780003600000'}],
}, {
  orderBy: [{field: 'occurred_at_ms', dir: 'desc'}],
  limit: 100,
})

操作符：eq、neq、gt、gte、lt、lte、in、nin、contains、startsWith、endsWith、isNull、isNotNull。字段之间、同字段多个条件都是 AND；没有 OR（对象式与数组式两种写法都接受）。

限制	值
limit 默认 / 最大	100 / 1000
offset 最大	100000
条件数最大	256
`in` / `nin` 最大项数	1000
排序字段最大	3

表结构与类型

源码工程在后端成员根的 schema.sql 单点定义实体、字段与索引。源清单 fh2-plugin.json 不手写 entities；校验 / 构建从 SQL 派生实体声明，写入 dist/plugin.json。已有源清单包含 entities 时，当前工具不会合并或覆盖为 SQL 派生结果，不能维护两份声明并假设它们自动一致。

运行时读取的是构建产物里的 entities，不是临时解析 SQL。types/ 提供能力和上下文声明，不从 schema.sql 生成业务实体 TypeScript 类型；不手改生成清单或类型。

本地 dev 按有效实体声明模拟存储；目标环境的建表与索引须由发布流程执行 schema.sql。构建成功不代表建表完成；已声明的实体缺表或存储不可用时返回 STORAGE_ERROR。

store 使用逻辑实体名，返回记录中的平台字段是 id、createdAt、updatedAt；时间筛选和排序也用这些公开字段，不使用物理列名。业务写入按 StoreFields 传字符串，物理列类型以 schema.sql 为准；使用字符串保存毫秒时间戳时须定宽 13 位，避免字典序比较出错。

错误码

UNKNOWN_ENTITY、UNKNOWN_FIELD、INVALID_FILTER、EMPTY_FILTER、TYPE_MISMATCH、DUPLICATE、LIMIT_EXCEEDED、STORAGE_ERROR、PERMISSION_DENIED。错误消息是净化后的固定文案，不含 SQL 和业务值。

边界与注意

无事务：并发互斥用 createIfAbsent，或用 update 影响行数判断抢占结果。

调用存储前检查逻辑实体是否在当前插件的有效 entities 声明中；未声明实体返回 UNKNOWN_ENTITY，持有 data:* 不代表可访问任意表。业务字段的实际存在性仍由目标存储确认，不能把实体校验当成全部字段或多插件部署隔离已验证。

常见问题

现象	原因与处理
报 `DUPLICATE`	唯一键冲突；用 `createIfAbsent` 表达「有则取」
报 `UNKNOWN_ENTITY`	逻辑实体未进入当前插件的运行时声明；核对 `schema.sql` 和本次生成的 `dist/plugin.json`，不要手补生成字段
报 `STORAGE_ERROR`	表没建（`schema.sql` 未执行）或数据库不可用
数字排序不对	存成了不定长字符串；毫秒时间戳用定宽 13 位字符串
想一次写多张表并保证原子性	不支持事务；把「要么都成功要么都不算」的判断改成 `createIfAbsent` + 补偿

六个方法#

筛选条件写法（filter）#

表结构与类型#

错误码#

边界与注意#

常见问题#

六个方法

筛选条件写法（`filter`）

表结构与类型

错误码

边界与注意

常见问题