convex-tenants

Convex 租户

通过 @djpanda/convex-authz 为 Convex 提供灵活授权，支持多租户组织和团队管理。

快速入门

1. 注册组件，在 convex/convex.config.ts 中：

import { defineApp } from "convex/server";
import tenants from "@djpanda/convex-tenants/convex.config";
import authz from "@djpanda/convex-authz/convex.config";

const app = defineApp();
app.use(tenants);
app.use(authz);

export default app;

2. 定义 authz，在 convex/authz.ts 中使用包提供的 TENANTS_PERMISSIONS 和 TENANTS_ROLES。参见 node_modules/@djpanda/convex-tenants/docs/quick-start.md。

3. 创建租户 API，在 convex/tenants.ts 中：

import { makeTenantsAPI } from "@djpanda/convex-tenants";
import { components } from "./_generated/api";
import { authz } from "./authz";

export const { listOrganizations, createOrganization, inviteMember, ... } =
  makeTenantsAPI(components.tenants, {
    authz,
    creatorRole: "owner",
    auth: async (ctx) => (await getAuthUserId(ctx)) ?? null,
    getUser: async (ctx, userId) => {
      const user = await ctx.db.get(userId);
      return user ? { name: user.name, email: user.email } : null;
    },
  });

4. 在 React 中使用 — 使用 useQuery(api.tenants.listOrganizations)，或通过 TenantsProvider 使用预构建组件。参见 node_modules/@djpanda/convex-tenants/docs/react-components.md。

核心概念

• authz 是同级组件 — 将 authz 与 tenants 并列注册，而不是将其注册为子组件。应用的其他部分也可以在 tenants 之外使用 authz。
• 角色是普通字符串 — 在 authz.ts 中定义。默认角色：owner、admin、member。参见 node_modules/@djpanda/convex-tenants/docs/flexible-roles.md。
• 结构性所有者 — 每个组织都有一个 ownerId。所有者离开前请使用 transferOwnership。所有权限检查都通过 authz 进行。
• 组织状态 — suspended 或 archived 状态会阻止变更；只有使用 status: "active" 调用 updateOrganization 才能重新激活组织。

导出项

导出项	说明
TENANTS_PERMISSIONS	definePermissions() 的默认权限
TENANTS_ROLES	defineRoles() 的默认角色（owner、admin、member）
DEFAULT_TENANTS_PERMISSION_MAP	操作 → 权限映射
TENANTS_REQUIRED_PERMISSIONS	权限字符串列表

文档（从包中读取）

基础路径：node_modules/@djpanda/convex-tenants/docs/。根据用户提到的关键词或任务选择对应文档 — 仅加载所需内容：

文档	路径	在用户询问以下内容时加载……
quick-start	docs/quick-start.md	设置、安装、首次集成、convex.config、authz.ts、tenants.ts、入门、初始设置
api-reference	docs/api-reference.md	函数名称（listOrganizations、createOrganization、addMember、inviteMember 等）、makeTenantsAPI 选项、事件钩子、变更/查询参数、分页（listMembers/listTeams/listTeamMembers/listInvitations 支持可选 paginationOpts）、API 签名
permission-map	docs/permission-map.md	权限、permissionMap、谁能做什么、操作权限、覆盖权限、守卫、各操作的访问控制
flexible-roles	docs/flexible-roles.md	角色、自定义角色、owner/admin/member、creatorRole、defineRoles、结构性所有者、transferOwnership、添加/移除角色
invitation-system	docs/invitation-system.md	邀请、inviteMember、acceptInvitation、validateInvitationCreate、validateInvitationAccept、标识符类型、电子邮件/电话/用户名、域名白名单、邀请速率限制
react-components	docs/react-components.md	TenantsProvider、OrganizationSwitcher、MembersSection、TeamsSection、InviteMemberDialog、useOrganization、useMembers、useTeams、useOrganizationInvitations、MembersTable、TeamsGrid、AcceptInvitation、JoinByDomainSection、分页钩子
organization-store	docs/organization-store.md	活跃组织、切换组织、useOrganizationStore、setActiveOrganizationId、localStorage、storageKey、配置组织存储

安装

npm install @djpanda/convex-tenants @djpanda/convex-authz

React UI 需要：npm install clsx tailwind-merge（可选的对等依赖）。