@happyvertical/smrt-features

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 2.1万

SMRT框架的代码第一特征旗帜和租户意识

中文使用文档
文档目录11 节
  1. 安装
  2. 快开始
  3. 决议
  4. 计划赠款和已付款特征
  5. 存储
  6. 生成的表面
  7. 管理 UI
  8. 消费者食谱
  9. 消费者仍然拥有的
  10. 特性密钥是持续存在的标识符
  11. 文档

@happyvertical/smrt-features (英语)

S-m-r-t应用的代码第一特征旗帜,具有全球和租户等级分辨率.

安装

pnpm add @happyvertical/smrt-features

快开始

自行申报地物. 同步或同步前导入该类 解决它。 供应 dbOptions 用于您已迁移的应用程序数据库和 currentTenantId 从您认证的服务器上下文.

import { SmrtObject, smrt } from '@happyvertical/smrt-core';
import {
  FeatureResolver,
  FeatureSyncService,
} from '@happyvertical/smrt-features';

@smrt({
  packageName: '@your/app',
  features: {
    drafts: {
      defaultEnabled: false,
      label: 'Invoice drafts',
      description: 'Save invoices as drafts before sending.',
    },
  },
})
export class Invoice extends SmrtObject {}

const sync = new FeatureSyncService(dbOptions);
await sync.syncDefinitions({ constructors: [Invoice] });

// This example uses flat tenant resolution.
const resolver = new FeatureResolver(dbOptions, {
  tenantHierarchyLoader: async () => null,
});
const enabled = await resolver.isEnabledFor(Invoice, 'drafts', {
  tenantId: currentTenantId,
});
// Equivalent key-based lookup:
const enabledByKey = await resolver.isEnabled('@your/app:Invoice#drafts', {
  tenantId: currentTenantId,
});

键有形式 <qualifiedClassName>#<localId>。示例的关键是 @your/app:Invoice#drafts。 。 。 . syncDefinitions() 选择 classNames, (中文(简体) ), constructors,以及 pruneStale 选项; 过滤的同步从不剪接兄弟 类别定义。 未过滤的同步使用所有已注册的类和笔记 默认情况下在被触摸的软件包中 stale design in touched package in success. syncManifest() 单独 接受一个 s -m -r -t SmartObjectManifest 包含类装饰元数据.

决议

解析器从注册类开始 defaultEnabled (坠落) ),然后适用租户计划赠款(见 租户按此顺序推翻。 没有 租户的情况,只适用全球管辖. explain() 返回时 答案与 isEnabled() 加号 decidedBy,设定它的地层 (单位:千美元)default, (中文(简体) ), plan_grant, (中文(简体) ), global_override 或者说 tenant_override) (中文(简体) ).

默认等级加载器发现 @happyvertical/smrt-users 何时 可用。 或者,供应 tenantHierarchyLoader 作为解决者 第二个构造参数; 返回 a FeatureTenantHierarchyProvider 或者说 null 平房房客解决。 分级向叶子延伸: 子女只有在父母一方有 cascadePermissions 和孩子拥有 inheritPermissions;否则 基线重排到全球状态(计划赠款加全球覆盖) (适用)。 然后适用每个房客的自负. inherit 保持了基线。 支持的范围是: global 财务报告和审定财务报表 tenant。 。 。 .

计划赠款和已付款特征

租户的订阅计划可以授予地物钥匙. 给定的密钥打开 房客, 和未授予的钥匙 保持它的违约。 那么,全球覆盖 顶端应用:全局行是明确的操作者行为,所以全局可分解 停止每个租户的功能,不管是否批准。 租户的否决适用 最后一次并击败赠款和全局覆盖。 特性不取决于 @happyvertical/smrt-subscriptions;它咨询a FeatureGrantSource,以及 没有注册的(当地安装)没有赠款.

标准支付密钥导出为常数并全部默认值 : FEATURE_SYNC_DEVICES, (中文(简体) ), FEATURE_BACKUP_VAULT, (中文(简体) ), FEATURE_CLOUD_HOSTED, (中文(简体) ), FEATURE_INFERENCE_HOSTED, (中文(简体) ), FEATURE_PLUGINS_REMOTE。 。 。 .

import { FEATURE_SYNC_DEVICES, FeatureResolver, featureGateResponse, requireFeature } from '@happyvertical/smrt-features';
import { SubscriptionFeatureSource } from '@happyvertical/smrt-subscriptions';

// Once per request.
const grantSource = await SubscriptionFeatureSource.create(dbOptions);
const resolver = new FeatureResolver(dbOptions);

// SvelteKit +server.ts: a structured 403 naming the key and the reason.
const denied = await featureGateResponse(FEATURE_SYNC_DEVICES, { resolver, tenantId, grantSource });
if (denied) return denied;

// Services: throws FeatureUnavailableError (status 403, .code, .denial, .toResponse()).
await requireFeature(FEATURE_SYNC_DEVICES, { resolver, tenantId, grantSource });

一个拒绝身体 code: 'feature_upgrade_required' 与 grantingPlan 当计划是缺失的,或 code: 'feature_disabled' 与 disabledBy (单位:千美元)global_override 或者说 tenant_override)和没有计划当一个 关闭功能, 因为任何升级都无济于事.

大门只检查租户的特征;认证 先检查一下房客的许可 然后通过你核实的房客. 注册全应用程序源 setFeatureGrantSource() 而不是通过 每个电话一个. defineFrameworkFeature() 添加您自己的点形密钥,以及 FeatureSyncService.syncFrameworkDefinitions() 保存到设置中 屏幕.

存储

  • _smrt_feature_definitions ——代码所属阶级身份,本地代号,布尔默认,标签,描述和元数据
  • _smrt_feature_overrides 按特性键、范围类型和范围 id 键的运行时间覆盖

生成的表面

FeatureDefinition 财务报告和审定财务报表 FeatureOverride 船与生成的REST路线, MCP工具,和CLI命令关闭(api: false, (中文(简体) ), mcp: false, (中文(简体) ), cli: false) (中文(简体) ). 覆盖行是每个范围的授权状态,所以 只从服务器代码写入 FeatureOverrideService,哪个 请求授权人在每次写入之前与当前呼叫者绑定 未关闭 :

const service = new FeatureOverrideService(overrides, (request) =>
  request.scopeType === 'tenant' && request.scopeId === session.tenantId &&
  session.permissions.has('features.manage'),
);
await service.setOverride(key, 'tenant', session.tenantId, FeatureOverrideEffect.ENABLE);

管理 UI

软件包将设置屏幕传送到如此耗用应用程序的屏幕上,不是每个程序重建 内容: FeatureSettingsService (根导出) 产生行,和 FeatureSettingsPanel (单位:千美元) ./svelte 子路径)让他们。 根导出 保持Svelte免费,所以只有服务器的消费者不会受到影响; svelte 是一个 可选对等依赖.

消费者食谱

1. 宣布守则中的定义. 特性切换在 @smrt() 属于下列类别的装饰者:

@smrt({
  features: {
    drafts: { defaultEnabled: false, label: 'Invoice drafts', description: 'Save invoices as drafts before sending.' },
  },
})
export class Invoice extends SmrtObject {}

2. 启动时同步这样 _smrt_feature_definitions 匹配代码 :

await new FeatureSyncService(dbOptions).syncDefinitions();

3. 装入服务器载荷中的行. 负载在哪里  允许检查生命——软件包没有做出授权决定:

// src/routes/settings/features/+page.server.ts
export async function load(event) {
  const auth = requirePermission(event, APP_PERMISSIONS.tenantAdmin);
  const settings = await FeatureSettingsService.create(dbOptions);
  return {
    tenantId: auth.tenantId,
    features: await settings.listFeatureSettings({
      tenantId: auth.tenantId,
      packageName: '@your/app',
    }),
  };
}

listFeatureSettings() 返回一个 FeatureSettingsRow 根据定义—— 定义字段, effectiveEnabled 作为 FeatureResolver 解决它 给那个房客的 globalEffect 编号 : tenantEffect 用于原始覆盖行 每个级别。 该行的结构可以分配到面板上 FeatureSettingsView,因此不需要绘图步骤.

4. 小组:

<script lang="ts">
  import { FeatureSettingsPanel } from '@happyvertical/smrt-features/svelte';
  let { data, form } = $props();
</script>

<FeatureSettingsPanel
  features={data.features}
  tenantLabel="Shop"
  contextKey={data.tenantId}
  formAction="?/saveFeature"
  message={form?.message}
  error={form?.error}
/>

面板是演示式的:它取出行和回调,不取出任何内容 授权什么。 每行使标签、描述、密钥、有效状态 (单位:千美元) 默认/ 启用/ 禁用 控制,在 默认 删除 覆盖行并返回特性到上面级别决定的任意位置. 过 showGlobal (和 globalEditable) 只有当您的应用程序有平台管理员时 分级; 应用程序, 没有完全省略列。 供应 onSave 改为 formAction 从客户端处理器驱动它.

有两个细节值得了解:

  • 租户专栏的 默认 选项从不命名代码默认值,因为 租户范围从全球范围继承,如果 FeatureTenantHierarchyProvider 也是从祖先的房客那里 这个 当行携带时, 命名继承状态 inheritedEnabled (帮助者) 当它完全可以知道时, 即当房客没有重置 ),其他内容为"过失(固有)". 全球栏目 默认 因为全局范围继承 没什么.
  • 未保存的编辑器随时被丢弃 contextKey 更改,或者,当您省略 无论何时 features 改为新的数组。 传出房客身份 contextKey 因此,一个租户的半人半人半人的选择 永远不能提交 对抗别人的行.

5. 用你本人的许可检查线接通写作. setFeatureOverride() 拒绝任何没有定义的密钥 和任何范围 解析器永远不会 读回——未知 scopeType,一个全局写在任何东西,但是 GLOBAL_FEATURE_SCOPE_ID,或空白/未调整的租户身份证——然后派代表到 FeatureOverrideService,它向您的授权方询问,失败关闭:

export const actions = {
  saveFeature: async (event) => {
    const auth = requirePermission(event, APP_PERMISSIONS.tenantAdmin);
    const form = await event.request.formData();
    const settings = await FeatureSettingsService.create(dbOptions, {
      // Your decision, bound to this caller. Returning anything but `true` denies.
      authorize: (request) =>
        request.scopeType === 'tenant' && request.scopeId === auth.tenantId,
    });

    try {
      await settings.setTenantFeatureOverride(
        String(form.get('featureKey') ?? ''),
        auth.tenantId,
        featureOverrideEffectFromValue(form.get('tenantEffect')),
      );
    } catch (error) {
      if (error instanceof UnknownFeatureKeyError) return fail(400, { error: 'Unknown feature.' });
      if (error instanceof InvalidFeatureScopeError) return fail(400, { error: 'Invalid scope.' });
      if (error instanceof FeatureOverrideAuthorizationError) return fail(403, { error: 'Not permitted.' });
      throw error;
    }
    return { message: 'Feature overrides saved.' };
  },
};

构建服务 无 a 一个 authorize 选项 只读 : 每封信都无法关闭 FeatureOverrideAuthorizationError。这是一个负载的正确形状 函数.

消费者仍然拥有的

  • 路线、导航条目和页壳;
  • 允许检查负载和动作;
  • 页:1 authorize 回调( 此软件包从未决定谁可以写入 ) ;
  • 解决会话 tenantId URL或表格中的租户身份 字段是一个选择器,而不是授权;
  • 电话 FeatureSyncService 启动时.

特性密钥是持续存在的标识符

覆盖按精确键存储 featureKey 字符串和解决方式 运行时的弦. 重命名一个关键孤儿, (中文(简体) ), 默默地将所有租户恢复到定义默认状态——变化看起来 {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}在沙发上无害 {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}以神秘地重起旗子的姿态出现 {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}这太奇怪了 处理密钥 永远无法改变 重命名需要重写的数据迁移 _smrt_feature_overrides.feature_key,而不是编辑。 (更名自有 软件包是这种情况的通常方式:在合格类身份改变时迁移已存储的密钥。)

文档

版本与发布记录

@happyvertical/smrt-features 共发布 365 个版本,首次发布于 2026/06/23;过去 12 个月发布了 365 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-features 的常见问题

@happyvertical/smrt-features 是什么?

SMRT框架的代码第一特征旗帜和租户意识

如何安装 @happyvertical/smrt-features?

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

@happyvertical/smrt-features 支持 TypeScript 吗?

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

@happyvertical/smrt-features 支持 ESM 还是 CommonJS?

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

@happyvertical/smrt-features 可以商用吗?

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

@happyvertical/smrt-features 的下载量有多少?

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

@happyvertical/smrt-features 还在维护吗?

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