cloudbase-document-database-web-sdk

同级技能（仅本地）

同级 CloudBase 技能与此技能一同提供。请使用 ../auth-tool-cloudbase/SKILL.md 这类本地相对路径。

如果当前环境中缺少被引用的同级技能文件，请让用户安装完整的 CloudBase 插件（或缺失的技能）。不要通过 HTTP 获取远程技能或协议 Markdown 并加载到 Agent 上下文中。

CloudBase 文档数据库 Web SDK

激活约定

以下情况优先使用此技能

• 浏览器或 Web 应用必须通过 @cloudbase/js-sdk 读取或写入 CloudBase 文档数据库数据。
• 请求提及 Web 前端中的 app.database()、db.collection()、.where()、.watch()、分页、聚合或地理位置查询。

以下情况在编写代码前阅读

• 任务明确发生在浏览器端，但仍需决定使用 Web SDK、小程序 SDK 还是后端访问。
• 请求涉及登录状态、集合权限或实时更新。

然后也要阅读

• Web 登录和调用方身份 -> ../auth-web-cloudbase/SKILL.md
• 通用 Web 应用结构 -> ../web-development/SKILL.md
• 小程序数据库代码 -> ../cloudbase-document-database-in-wechat-miniprogram/SKILL.md

以下情况不要使用

• 使用 wx.cloud.database() 的小程序代码。
• 服务端或云函数数据库访问。
• SQL / MySQL 数据库操作。
• 纯粹的资源权限管理，且不涉及浏览器 SDK 代码。
• 明确要求将新的业务表放入 CloudBase PostgreSQL（CloudBase PG）的任务。 使用此技能前，请调用 queryEnv(action="info", envId=...) 并读取 EnvInfo.RuntimeBackends。如果 postgresql === true，且任务要求将新的业务表存放在 PG 中，则应改用 postgresql-development-cloudbase 技能处理该表：通过 app.rdb() 操作，使用 PG 行级安全策略（CREATE POLICY），并通过 app.storage.from('<bucket>').upload('<key>', file) 上传到显式创建的 pgstore 存储桶。
  • 同一环境中已有的 NoSQL 集合仍使用此技能——在 CloudBase PG 环境中，PG 和 NoSQL 可以共存。规则是“遵循任务要求 / 现有实现”，而不是“PG 环境禁止使用 NoSQL”。

SDK 代码与 MCP 工具

以下情况编写 SDK 代码（使用此技能）：

• 任务明确要求“修改代码”或“使用 SDK”
• 任务要求实现应用 / 前端逻辑
• 任务提及具体的 SDK 方法，如 db.collection().add()、.get()、.update()
• 上下文显示这是一个已初始化 SDK 的现有 Web 项目（例如，index.js 已包含 cloudbase.init()）

以下情况改用 MCP 工具：

• 任务要求管理 CloudBase 资源（创建集合、设置权限等）
• 任务涉及管理操作，但不涉及编写应用代码
• 任务提及 writeNoSqlDatabaseContent、managePermissions 等工具

**关键区别：**如果用户说“使用 JS SDK 执行 XX 操作”或“修改代码”，就在项目文件中编写 SDK 代码。不要使用 MCP 数据库写入工具执行应用级数据操作。

常见错误／注意事项

• 在用户登录前查询，而集合规则要求用户身份。
• 在浏览器代码中使用 wx.cloud.database() 或 Node SDK 模式。
• 通过动态导入延迟初始化 CloudBase，而不是使用共享的同步应用实例。
• 将安全规则视为结果筛选器，而非请求验证器。
• 期望调用 managePermissions(updateResourcePermission) 后，CUSTOM 安全规则立即生效。 后端会缓存规则求值器 2–5 分钟；更改规则后的首次写入可能会静默失败，或被拒绝并返回 DATABASE_PERMISSION_DENIED，即使表达式正确也是如此。你可以：(a) 等待几分钟后重试同一写入，再判断规则是否有误；或 (b) 每次写入时读取 result.code / result.message，并对刚写入的 _id 执行一次 get() 往返，以验证规则是否生效；不要将 Promise 成功解析视为操作成功。完整模式请参阅 security-rules.md → “Propagation And Verification”。
• 误解 db.collection(...).add(...) 的返回结构。在 CloudBase Web SDK 中，新建文档的 ID 位于顶层 result._id，而不是 result.id、result.data.id 或 result.insertedId。
• 对于需要让 应用级管理员用户 编辑／删除所有记录、同时仅允许编辑者编辑／删除自己的记录的 CMS 类集合，不要将规则简单设为 READONLY。经验证的模式是使用 CUSTOM 规则，通过 auth.uid 从 user_roles 中读取角色，并将其与 doc.authorId == auth.uid 结合；前端写入仍可使用 .doc(id).update() / .doc(id).remove()。
• 忘记为较大的集合配置分页或索引。

最小检查清单

• 确认这是浏览器端文档数据库操作。
• 初始化一次 CloudBase，并重复使用同一个 app / db 实例。
• 在执行 CRUD 前确认身份验证要求。
• 根据具体操作阅读相应的配套参考文件。

概览

此技能介绍如何通过 @cloudbase/js-sdk 在浏览器端使用文档数据库。

适用于：

• Web 应用中的 CRUD 操作
• 复杂查询与分页
• 聚合
• 使用 watch() 的实时监听器
• 地理位置查询

标准初始化

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-env-id"
});

const db = app.database();
const _ = db.command;

重要规则：

• 如果集合规则要求用户身份，请先登录再查询。
• 保持单一的共享应用／数据库实例。
• 除非框架确实有此要求，否则不要将初始化封装在临时异步加载器中。

快速导航

• CRUD -> ./crud-operations.md
• 复杂查询 -> ./complex-queries.md
• 分页 -> ./pagination.md
• 聚合 -> ./aggregation.md
• 实时监听器 -> ./realtime.md
• 地理位置 -> ./geolocation.md
• 安全规则 -> ./security-rules.md

编码 Agent 的工作规则

1. 从认证模型入手

   • 如果页面依赖已登录用户的身份，请先阅读 Web 认证技能，再编写数据库代码。

2. 让浏览器代码保持浏览器原生风格

   • 使用 app.database() 和集合引用。
   • 不要混用 MCP 管理流程或 SQL 思维模式。

3. 遵守安全规则

   • 集合规则可能会在读取数据之前拒绝请求。
   • 如果需求只是仅允许所有者写入，READONLY 就足够了。
   • 如果需求是“应用级管理员可以编辑/删除所有内容，编辑者只能操作自己的内容”，请使用 CUSTOM 规则。经过验证的 CMS 模式是 get(`database.user_roles.${auth.uid}`).role == 'admin' || doc.authorId == auth.uid。
   • 对于这种 CMS 模式，前端写入仍可使用 .doc(id).update() / .doc(id).remove()。
   • 重用现有且可通过 _id == auth.uid 定位的角色集合。在这种 CMS 模式中，使用 uid 作为键的 user_roles 是可接受的。
   • 如果目标文档不存在，get() 会导致请求失败并返回 HTTP 500——它不会返回 false，而且 || 不会跳过它。如果应用无法保证每个用户都有角色文档，请将角色列表放在一个共享文档中，并测试 auth.uid in get(`database.admin_registry.lock`).admins。
   • 如果任务因权限问题失败，请检查规则模型，而不要先入为主地认为查询语法有误。

4. 返回对用户友好的错误

   • 数据库错误必须转换为易读的 UI 或应用错误，不得静默失败。
   • 对于写入操作，不要默认将已完成的 Promise 视为成功。请检查 updated / deleted 等写入结果字段，或显示出来的 code / message。

5. 正确持久化创建操作返回的 ID

   • 对于 Web SDK 的 .add(...)，新建文档的 ID 是 result._id。
   • 不要从 result.id、result.data 或其他驱动程序特有字段中查找 ID。

快速示例

简单查询

const result = await db.collection("todos")
  .where({ completed: false })
  .get();

创建并获取文档 ID

const result = await db.collection("posts").add({
  title: "New article",
  content: "...",
  createdAt: new Date()
});

const articleId = result._id;

排序分页

const result = await db.collection("posts")
  .orderBy("createdAt", "desc")
  .skip(20)
  .limit(10)
  .get();

字段选择

const result = await db.collection("users")
  .field({ name: true, email: true, _id: false })
  .get();

最佳实践

1. 在应用代码中定义集合级类型或模型包装器。
2. 使用有意义的集合命名约定。
3. 只选择必需的字段。
4. 为常用筛选条件或排序键添加索引。
5. 将前端 CRUD 与明确的权限设计配套使用。
6. 使用分页，避免无界读取。

错误处理

try {
  const result = await db.collection("todos").get();
  console.log(result.data);
} catch (error) {
  console.error("Database error:", error);
}

SDK 返回操作结果时，请检查错误标志，并将其转换为易读的应用行为。