Convex Helpers Guide 是一份围绕 convex-helpers 工具库的使用指南。convex-helpers 是 Convex 官方提供的实用工具集合，用于为 Convex 后端补充常见模式，减少重复实现。安装命令为：npm install convex-helpers。
一、关系助手（Relationships） 用于以可读、类型安全的方式在表之间遍历关联数据，适用于跨表加载关联数据、跟随外键关系、构建嵌套数据结构。主要函数包括 getOneFrom（获取单条关联文档）、getManyFrom（获取多条关联文档）、getManyVia（通过中间表获取多对多关系）。示例从 convex-helpers/server/relationships 导入 getOneFrom 与 getManyFrom，在查询中先取任务，再加载关联用户与评论。
二、自定义函数（Custom Functions，数据保护） 这是 Convex 中替代行级安全（RLS）的方案：通过自定义函数包装器，为所有查询与变更自动附加鉴权和访问控制。适用于数据保护与访问控制（主要用途）、为所有函数添加鉴权逻辑、多租户应用、基于角色的访问控制（RBAC）、向 ctx 注入公共数据、构建仅内部可用的函数、为所有函数添加日志监控。相比 RLS 的优势被描述为：使用 TypeScript 而非 SQL 策略、完整类型安全、易于测试与调试、比数据库策略更灵活、可作用于整个后端。示例通过 customQuery 包装 query，在 input 中读取身份、查询用户并注入 ctx.user；另有组织级 orgQuery 示例校验成员身份并注入 orgId 与 role，以及 adminMutation 示例限制仅管理员可调用。
三、过滤助手（Filter） 用于对数据库查询结果应用复杂的 TypeScript 过滤，适用于按计算值过滤、过滤逻辑过于复杂而无法用索引表达、结果集较小的场景。示例从 convex-helpers/server/filter 导入 filter，按完成状态、创建时间与优先级筛选任务。指南提醒：仍应优先使用索引，filter 仅用于无法索引的复杂逻辑。
四、会话（Sessions） 用于在用户未登录时跨请求跟踪用户，适用于跟踪匿名用户、为访客构建购物车、在注册前跟踪行为、无鉴权的 A/B 测试。服务端通过 SessionIdArg 为参数增加 sessionId；客户端（React）通过 useSessionId 获取会话标识并随请求传入。
五、Zod 校验 使用 Zod schema 替代 Convex 校验器，适用于项目已使用 Zod、需要更复杂校验逻辑或自定义错误信息的场景。示例从 convex-helpers/server/zod 导入 zCustomQuery，定义邮箱与年龄的 schema 并在处理函数中使用。
六、行级安全助手（替代方案） 指南说明 Convex 推荐以自定义函数作为主要数据保护模式，RLS 助手是模仿传统 RLS 的替代方案，适用于偏好 PostgreSQL 式 RLS 模式、需在多个函数间应用相同规则、希望集中管理访问控制规则的场景。示例通过 RowLevelSecurity 添加规则并按规则过滤查询结果。指南同时指出自定义函数通常更优：编译期类型安全、更显式、错误信息更好、更易于测试。
七、数据迁移（Migrations） 用于安全执行数据迁移，适用于回填新字段、转换现有数据、在 schema 版本间迁移。示例通过 makeMigration 定义迁移，对缺少 priority 的文档补默认值，并可通过 npx convex run 执行。
八、触发器（Triggers） 在数据变化时自动执行代码，适用于数据变更时发送通知、更新关联记录、记录日志、维护计算字段。示例注册 on insert 触发器，在任务创建时写入通知记录。
九、聚合（Aggregations） 用于高效计算聚合值。示例通过 aggregation 统计任务总数、完成数与优先级加权总分。
常见模式部分给出三类示例：带用户上下文的鉴权查询（authedQuery 注入 ctx.user）、加载关联数据（作者、评论、多对多标签）、带错误处理的批量操作（使用 asyncMap 逐条更新并返回结果）。
最佳实践包括：优先使用 convex-helpers 而非重复造轮子；用自定义函数处理鉴权；以关系助手替代深层嵌套、保持数据规范化；谨慎使用 filter，优先索引；用会话跟踪匿名用户并在之后迁移到用户账户。文末提供核对清单与“何时使用什么”的对照表。除上述示例与说明外，关于收费、价格、平台支持与效果等事实暂未提供。