# @happyvertical/smrt-tenancy 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-tenancy/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:57:04.070Z
中文译文更新时间：2026-11-17T09:28:59.550Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/smrt-tenancy
原文对照：https://npmcn.com/package/%40happyvertical/smrt-tenancy/?lang=original
项目主页：https://github.com/happyvertical/smrt#readme
源码仓库：https://github.com/happyvertical/smrt

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：427 kB，81 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：svelte ^5\.57\.0
- 首次发布：2026-06-23T01:18:55.124Z
- 最新版本发布：2026-11-17T07:57:03.852Z
- 近 30 天下载量：46636（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：365（近 12 个月 365 个）

## 中文简介

自动租户隔离和强制执行的SMRT生产准备多租房框架

## 安装

```sh
npm install @happyvertical/smrt-tenancy
```

也可以使用：`pnpm add @happyvertical/smrt-tenancy`、`yarn add @happyvertical/smrt-tenancy`、`bun add @happyvertical/smrt-tenancy`

## README

# @happyvertical/ smrt- 租借

S-m-r-t的多重租借,同时使用Async LocalStorage上下文传播,自动查询过滤,以及租户身份证人口.

## 安装

```bash
pnpm install @happyvertical/smrt-tenancy
```

## 使用量

```typescript
import { enableTenancy, TenantScoped, tenantId, withTenant } from '@happyvertical/smrt-tenancy';
import { smrt, SmrtObject } from '@happyvertical/smrt-core';

// 1. Enable tenancy globally (once at app startup)
enableTenancy();

// 2. Mark classes as tenant-scoped
@smrt()
@TenantScoped({ mode: 'optional' })
class Document extends SmrtObject {
  @tenantId({ nullable: true })
  tenantId: string | null = null;

  title: string = '';
}

// 3. Wrap operations in tenant context
await withTenant({ tenantId: 'tenant-123' }, async () => {
  const docs = await collection.list({ where: { status: 'active' } });
  // Executes: WHERE tenant_id = 'tenant-123' AND status = 'active'
});
```

## API 密码

### 账单关系

计费亲子关系与 `@happyvertical/smrt-users` 租户 等级。 重新指定转售者或改变谁付费并不重新识别 租户获得许可,不得移动其记录。 没有账单的房客 关系是自费的。 每个孩子最多有一个关系 `billingOwnerMode` 实值 `self` 或者说 `reseller`,而所有者来源于此 单行。 租户UUID在存储和查询前实现常态化为小写. 因此,转卖商可以管理一个自负盈亏的孩子.

```typescript
import {
  BillingRelationshipService,
  withSystemContext,
} from '@happyvertical/smrt-tenancy';

const billing = await BillingRelationshipService.create({
  db,
  // Resolve IDs against the application's tenant directory (for example,
  // smrt-users TenantCollection). The tenancy package does not own Tenant.
  tenantExists: async (id) => Boolean(await tenants.get({ id })),
});

await withSystemContext(() =>
  billing.setRelationship({
    childTenantId: childId,
    resellerTenantId: resellerId,
    billingOwnerMode: 'reseller',
  }),
);

const ownerId = await withSystemContext(() =>
  billing.resolveBillingOwner(childId),
);
const billedChildren = await withSystemContext(() =>
  billing.listChildrenBilledTo(ownerId),
);
```

`setRelationship()` 在 a 中更改父目录和默认所有者 交易。 设置 `billingOwnerMode: 'self'` 保持回售父目录 让孩子自己付钱. `clearRelationship()` 删除亲子关系 将孩子返回到自控状态。 循环和自我父母制被拒绝. 关系变化在支持的 SQL 适配器上序列化; PostgreSQL 使用咨询交易锁。 本地 SQLite、 DuckDB 和 PostgreSQL 是 支持; 拒绝远程 LibSQL 是因为其作者无法共享 正在处理中的图锁。 新的 `_smrt_billing_relationships` 图表 必须通过正常程序应用 `smrt db:migrate` 部署流动.

生成的API,MCP,以及这些行的CLI突变表面被禁用. `BillingRelationship` 仅仅是因为 s -m -r -t 消费者注册,才成为根导出 从软件包根导入每个已公布的显示模式; 保存它 直接绕过服务的租户、周期和授权检查. `BillingRelationshipCollection` 不导出。 来电者用之. 没有 `authorize` 调回,突变需要明确的系统上下文. 阅读仅限于儿童、其再销售者或系统上下文;主机可能 提供 `authorize` 用于额外许可检查的访问。 供应租户 解决者,不取决于打电话者目前的租户范围 操作故意跨越租户,并在 主机在允许关系变化前的回调 .

### 装饰者

| 导出 | 说明 |
| --- | --- |
| `TenantScoped(options?)` | 阶级装饰. 模式 : `'required'` (违约)或 `'optional'` |
| `tenantId(options?)` | 租户身份证栏的财产装饰 |

### 背景运行器

| 导出 | 说明 |
| --- | --- |
| `withTenant(ctx, fn)` | 向租户运行代码 |
| `withTenantSync(ctx, fn)` | 同步变体 |
| `withSystemContext(fn)` | 所有租户检查(管理/移民) |
| `withSuperAdminBypass(fn)` | 保持租户的上下文; 仅跳过租户的强制执行 `allowSuperAdminBypass: true` |
| `enterTenantContext(ctx)` | 输入上下文而不回调( 对于中间软件) |

### 上下文访问器

| 导出 | 说明 |
| --- | --- |
| `getCurrentTenant()` | 获取当前租户上下文( 可能未定义) |
| `getTenantId()` | 获取租户身份字符串( 可能未定义) |
| `requireTenant()` | 获取租户的背景或丢弃 |
| `requireTenantId()` | 取得租户身份证或扔出 |
| `hasTenantContext()` | 检查租户的背景 |
| `isSystemContext()` | 检查系统上下文 |
| `isSuperAdminBypass()` | 检查超级管理员绕行是否活动 |
| `TenantContext` | Async 本地软件集实例(先进使用) |

### 错误

`TenantContextError` (缺少必要的上下文), `TenantIsolationError` (租户不匹配).

### 截取器

| 导出 | 说明 |
| --- | --- |
| `enableTenancy()` | 全球登记租户拦截器 |
| `disableTenancy()` | 删除租户拦截器 |
| `isTenancyEnabled()` | 检查租赁是否有效 |
| `createTenantInterceptor(options?)` | 手动创建截取器 |

### 框架适应器

| 导出 | 说明 |
| --- | --- |
| `createSvelteKitHandle(options)` | SvelteKit 钩子.server.ts 处理器 |
| `createExpressMiddleware(options)` | 显示中间软件 |
| `createCliContext(options)` | CLI 语境 `run()`, (中文(简体) ), `runWithTenant()`, (中文(简体) ), `runAsSystem()` |

### 书记官处(高级)

| 导出 | 说明 |
| --- | --- |
| `isTenantScopedClass(name)` | 检查一个班级是否为租户范围 |
| `getTenantScopedConfig(name)` | 获得一个班级的租户配置 |
| `getAllTenantScopedClasses()` | 列出所有登记的租户类别 |
| `registerTenantScopedClass()` | 在程序上注册一个类 |
| `unregisterTenantScopedClass()` | 从注册中删除一个类 |
| `clearTenantScopedRegistry()` | 清除所有注册 |

### 测试

| 导出 | 说明 |
| --- | --- |
| `setupTestTenancy(options?)` | 启用测试租赁 |
| `resetTenancy()` | 清理测试之间的租赁状态 |
| `createTestTenantContext(ctx, fn)` | 在租户上下文中运行测试代码 |
| `testTenantIsolation(tenantIds, fn)` | 核实租户之间的隔离 |
| `assertTenantContextRequired(fn)` | 自动操作需要上下文 |
| `assertTenantIsolationViolation(fn)` | 自动操作违反隔离 |

## 依赖关系

-   `@happyvertical/smrt-core` -- Smrt对象、Smrt Collection、全球干扰器
-   `@happyvertical/sql` -- 数据库操作
-   `@happyvertical/utils` -- 公用事业职能

可选同伴 : `svelte`, (中文(简体) ), `@happyvertical/smrt-users`, (中文(简体) ), `@happyvertical/smrt-svelte`

## 许可证

麻省理工学院

### 授权租户/全球名单如下:

`withTenantGlobalRead(tenantId, callback)` 许可列表 - 家庭读取名称 房客加全球一行 验证了打电话者的房客 它保存着 业务截取器的原始角色、权限和系统状态;它确实 不把普通呼叫器变成系统呼叫器。 内地租房 `beforeList` 把这个范围钩入每个已有的上游分支,并重新检查身份 如果巢穴代码改变租户。 点读取,原始查询和写作 保留他们的 普通警卫 能力是当地合成的,在例外情况下恢复,而且 不影响同时提出的请求。 真正的系统/超级管理呼叫者保留 已存在的绕行行为。 使用范围化的集合读取在调用回调中 .

### 授权等级读取范围

主机使用自有设备 `TenantCollection.withTenantCatalogReadScope()` 或者说 `withTenantHierarchyContext()` API 输入 `@happyvertical/smrt-users`状态 `enableTenancy()` 执行和肯定服务器侧授权人。 目录 范围允许自我、祖先和全球行;树下范围只允许 (原始内容存档于2013-10-12). Professioned root and genders. 参见用户包的分级租借量docs.

`runTenantHierarchyReadScope()` 财务报告和审定财务报表 `getTenantHierarchyReadScope()` 被信任 用于拥有软件包的管道,而不是主机授权入口。 那个跑者 检查执行是启用的,但不授权行为者或得出 等级。 不从请求输入构建范围 .

在范围中,只允许列入清单的租户范围 -- -- 家庭阅读 过滤器仍然缩小。 点 `get()` 保留主动租户的上游, 包括窝式超级管理员绕道 租户范围保存、删除和原始 拒绝询问,包括明确的未结选入。 演员开关和 巢形瞄准镜闭合失败. 回调不会改变演员/会议权限, postgreSQL RLS 仍然是另一个限制。 这些收藏钩是 不是沙盒直接数据库访问或没有租赁的模型。 在范围之外, 正常选择的超admin绕行行为不变.

消费者在启动时可以加强已经租户范围包模型 `ObjectRegistry.registerOverride(qualifiedName, { tenancy: { mode: 'required' } })`。 。 。 . 这项政策在重新登记后仍然有效,并优先于 可选择的直接租户登记,包括当一个后人继承 登记。 它保留申报的租地 过滤器/人口设置;不能引入租赁或改变方案。 继续 允许租房拦截器。 明确系统/超级管理员上下文 已存在的旁接语义。 见Smrt-core的消费者跑步时间限制合同.

## 常见问题

### @happyvertical/smrt-tenancy 是什么？

自动租户隔离和强制执行的SMRT生产准备多租房框架

### 如何安装 @happyvertical/smrt-tenancy？

在项目目录运行 npm install @happyvertical/smrt-tenancy，或使用 pnpm add / yarn add / bun add。

### @happyvertical/smrt-tenancy 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @happyvertical/smrt-tenancy 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @happyvertical/smrt-tenancy 可以商用吗？

@happyvertical/smrt-tenancy 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @happyvertical/smrt-tenancy 的下载量有多少？

根据 npm 官方下载统计，@happyvertical/smrt-tenancy 在 2026/10/17 – 2026/11/15 这 30 天内被下载 46,636 次，日均约 1,555 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @happyvertical/smrt-tenancy 还在维护吗？

最新版本 0\.62\.1 发布于 2026/11/17（今天）；至今共发布 365 个版本，其中过去 12 个月发布了 365 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

