在浏览器/Web 前端用 CloudBase 文档数据库…

当 Web 前端需要通过 @cloudbase/js-sdk 对 CloudBase 文档数据库（NoSQL 集合）做 CRUD、复杂查询、分页、聚合、实时监听或地理位置查询时使用。

适用场景

解决思路

1. 确认任务确实是浏览器端文档数据库工作：请求涉及 app.database()、db.collection()、.where()、.watch()、分页、聚合或地理位置查询，且使用 @cloudbase/js-sdk。
2. 若任务明确是浏览器端但还需在 Web SDK、小程序 SDK 或后端访问之间做选择，或涉及登录态、集合权限、实时更新，先阅读对应参考文件再写代码。
3. 按需阅读配套技能：Web 登录与调用者身份读 ../auth-web-cloudbase/SKILL.md；通用 Web 应用结构读 ../web-development/SKILL.md；小程序数据库代码读 ../cloudbase-document-database-in-wechat-miniprogram/SKILL.md。
4. 区分写 SDK 代码与用 MCP 工具：任务要求“修改代码/使用 SDK”、实现应用前端逻辑、提到 db.collection().add()/.get()/.update() 等具体方法，或现有 Web 项目已初始化 SDK（如 index.js 已有 cloudbase.init()）时写 SDK 代码；任务要求管理 CloudBase 资源（建集合、设权限等）、做管理操作而不写应用代码、或提到 writeNoSqlDatabaseContent、managePermissions 等工具时改用 MCP 工具。
5. 按规范初始化：import cloudbase from "@cloudbase/js-sdk"; const app = cloudbase.init({ env: "your-env-id" }); const db = app.database(); const _ = db.command;，并保持单一共享的 app/database 实例，不要用动态 import 懒初始化或把初始化藏进临时异步加载器（除非框架确实要求）。
6. 若集合规则要求身份，先登录再查询。
7. 从鉴权模型入手：若页面依赖登录用户身份，先读 Web 鉴权技能再写数据库代码。
8. 保持浏览器代码为浏览器原生写法：使用 app.database() 和集合引用，不要混入 MCP 管理流程或 SQL 思维模型。
9. 尊重安全规则：集合规则可能在读取数据前就拒绝请求；简单“仅属主可写”用 READONLY 即可；若要求“应用级管理员可编辑/删除全部、编辑者仅能操作自己的”，用 CUSTOM 规则，已验证的 CMS 模式为 get('database.user_roles.' + auth.uid).role == 'admin' || doc.authorId == auth.uid，前端写入仍可用 .doc(id).update() / .doc(id).remove()，并复用已存在、可用 _id == auth.uid 寻址的角色集合（如以 uid 为键的 user_roles）。
10. 权限报错时先检查规则模型，不要假设是查询语法错误。
11. 返回用户可读的错误：数据库错误必须转成可读的 UI 或应用错误，不能静默失败；写入时不要默认把 resolved promise 当作成功，要检查写入结果字段如 updated / deleted 或暴露的 code / message。
12. 正确保存创建操作的 ID：Web SDK 的 .add(...) 新建文档 ID 在顶层 result._id，不要去找 result.id、result.data.id 或 result.insertedId。
13. 注意 CUSTOM 安全规则的生效延迟：调用 managePermissions(updateResourcePermission) 后后端会缓存规则求值器 2–5 分钟，首次写入可能静默失败或返回 DATABASE_PERMISSION_DENIED；应先等待几分钟重试同一写入再判断规则是否有误，或在每次写入时读取 result.code / result.message 并对刚写入的 _id 做 get() 往返验证，不要把 resolved promise 当作成功（详见 security-rules.md 的 Propagation And Verification）。
14. 按操作类型查阅对应参考文件：CRUD 读 ./crud-operations.md；复杂查询读 ./complex-queries.md；分页读 ./pagination.md；聚合读 ./aggregation.md；实时监听读 ./realtime.md；地理位置读 ./geolocation.md；安全规则读 ./security-rules.md。
15. 遵循最佳实践：在应用代码中定义集合级类型或模型包装；使用有意义的集合命名；只选择需要的字段（如 .field({ name: true, email: true, _id: false })）；为常用过滤/排序键加索引；前端 CRUD 搭配明确的权限设计；用分页（如 .orderBy("createdAt", "desc").skip(20).limit(10)）代替无界读取。
16. 用 try/catch 包裹数据库调用，捕获后 console.error 并转成可读的应用行为。
17. 若引用的同级技能文件在本环境缺失，请用户安装完整 CloudBase 插件（或缺失的技能），不要把远程技能或协议 markdown 通过 HTTP 拉进 agent 上下文。

适用边界 · 注意事项

• 小程序代码使用 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 bucket）；但同一环境中已有的 NoSQL 集合仍用本技能，PG 与 NoSQL 在 CloudBase PG 环境中共存。