数据存储

后端插件的业务数据存在 store 全局对象里（平台数据库）。这一页讲六方法签名、过滤写法、建表方式和设计限制。权限：data:read 给 query/count，data:write 给 insert/createIfAbsent/update/delete，三条代码路线（HTTP/事件/流程脚本）都可用。

六个方法，没有 put/get

store.insert(entity, record)              -> {ok, data} | {ok:false, error}
store.createIfAbsent(entity, record, uniqueBy)  -> {ok, data} | {ok:false, error}
store.update(entity, filter, patch)       -> {ok, data} | {ok:false, error}
store.delete(entity, filter)              -> {ok, data} | {ok:false, error}
store.query(entity, filter, options)      -> {ok, data} | {ok:false, error}
store.count(entity, filter)               -> {ok, data} | {ok:false, error}

返回值语义：

方法	返回数据（`data`）
`insert`	新记录（平铺 `id`、`createdAt`、`updatedAt` 与业务字段）
`createIfAbsent`	`{ created: boolean, record }`——原子地"有则取、无则建"
`update`	`{ affected: number }`——实际改了几行
`delete`	`{ deleted: number }`
`query`	`{ list, total, limit, offset }`；每条记录含公开平台字段与业务字段
`count`	`{ count: number }`

失败不抛异常，统一返回 { ok: false, error: { code, message } }。标准处理：

function must<T>(result: { ok: true, data: T } | { ok: false, error: { code: string, message: string } }): T {
  if (!result.ok) throw { code: result.error.code, message: result.error.message }
  return result.data
}

查询与过滤

const page = must(store.query(
  "lane_change_event",
  {
    dock_sn: { eq: input.dockSn },
    crossed_at_ms: { gte: input.fromMs, lte: input.toMs },
    post_status: { in: ["pending_video", "processing"] }
  },
  { limit: 50, offset: 0, orderBy: [{ field: "crossed_at_ms", dir: "desc" }] }
))

过滤算子：eq、neq、gt、gte、lt、lte、in、nin、contains、startsWith、endsWith、isNull、isNotNull；多个条件 AND 组合。

orderBy 必须是数组，最多 3 个字段。

update 和 delete 强制要求非空筛选条件（防止误操作全表）。

主要上限：查询默认 100 条、最多 1000 条；offset 最大 100000；in/nin 最多 1000 项；单字符串 64 KiB；单记录 512 KiB。超限返回 LIMIT_EXCEEDED，不会静默截断。

以上是后端运行时的契约。JS 读取、筛选和排序平台时间时用 createdAt / updatedAt，不要使用 SQL 物理列名 created_at / updated_at。本地模拟器的对象排序等支持有差异，保持正式查询声明，并在已部署测试环境验证，见已知限制。

示例：幂等去重 + 条件抢占

// handlers/lane-change/create-event.ts
export function createEvent(input: RecordInput, ctx: HandlerCtx) {
  // 1. 原子去重：同一 event_key 只建一条
  const created = must(store.createIfAbsent(
    "lane_change_event",
    {
      id: ctx.stableId("event:" + input.eventKey),
      event_key: input.eventKey,
      post_status: "pending_video",
      crossed_at_ms: String(input.crossedAtMs).padStart(13, "0")
    },
    ["event_key"]
  ))
  if (!created.created) {
    return { id: created.record.id, duplicate: true }
  }

  // 2. 条件抢占：affected=1 才说明抢到了
  const claimed = must(store.update(
    "lane_change_event",
    { id: { eq: created.record.id }, post_status: { eq: "pending_video" } },
    { post_status: "processing" }
  ))
  return { id: created.record.id, claimed: claimed.affected === 1 }
}

实体与建表

实体名：^[a-z][a-z0-9_]*$；业务字段名建议统一用下划线命名，业务查询、写入和排序使用同一键名；平台时间字段使用公开名 createdAt / updatedAt。

物理表：plugin_db_<实体名>（如实体 lane_change_event → 表 plugin_db_lane_change_event），由部署方在发布流程中执行包里的 schema.sql 建表——后端运行时不会自动建表，漏跑建表脚本首次访问会报 STORAGE_ERROR。

SQL 平台列：id、tenant_id、created_at、updated_at；业务字段从 JS 写入时传字符串。JS store 的公开平台字段为 id、createdAt、updatedAt，tenant_id 不作为脚本可读写字段。

insert 可以指定 id；创建/更新时间由平台维护，不写入业务记录，平台字段不能用于更新内容。业务响应数据结构若声明 created_at，从 record.createdAt 映射，不改变响应数据结构或 SQL 建表语句，见共享契约。

毫秒时间戳存定宽 13 位字符串（如 padStart(13,"0")），否则文本列上的范围比较和排序会乱。

存储契约由 schema.sql 单点定义（≤32 实体、≤64 字段/实体）：本地 dev 按派生声明在内存建表，构建时投影进运行时清单，不要在源清单手写 entities。

错误码

错误码（`code`）	含义
`UNKNOWN_ENTITY` / `UNKNOWN_FIELD`	实体/字段名形状非法（表或列不存在通常是 `STORAGE_ERROR`）
`INVALID_FILTER`	算子、值、排序或分页参数非法
`EMPTY_FILTER`	写操作缺过滤器，或 `uniqueBy` 为空
`TYPE_MISMATCH`	参数形状或值类型不符
`DUPLICATE`	`insert` 撞唯一约束
`LIMIT_EXCEEDED`	超出各类上限
`STORAGE_ERROR`	未装配、表/列不存在、超时等底层错误

设计限制（写代码前必读）

没有事务、没有关联查询、没有 OR、没有聚合。设计约束是"一张表一个唯一键"。

并发互斥判据只有两个：update 的 affected 行数、createIfAbsent 的 created。

delete 是物理删除，没有软删除。

"先 query 再 update"判断抢占是错的——两次调用之间有竞争窗口，必须用条件 update 的 affected。

常见问题

现象	原因与处理
`store is not defined`	清单没申报 `data:read`/`data:write`
首次访问报 `STORAGE_ERROR`	`schema.sql` 没被执行，表不存在
时间范围查询结果不对	毫秒时间戳没存成定宽 13 位字符串
想用 `store.put` / `store.get`	没有这两个方法；写用 `insert`/`update`，读用 `query`/`count`
并发下出现两条"唯一"记录	`uniqueBy` 字段缺真实唯一索引，或用了 `insert` 而不是 `createIfAbsent`
`EMPTY_FILTER`	`update`/`delete` 的筛选条件为空对象；至少带一个条件

方法签名速查见数据存储 API。

六个方法，没有 put/get#

查询与过滤#

示例：幂等去重 + 条件抢占#

实体与建表#

错误码#

设计限制（写代码前必读）#

相关能力：cache#

常见问题#