# @happyvertical/smrt-features 中文文档

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

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

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

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

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

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

## 中文简介

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

## 安装

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

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

## README

# @happyvertical/smrt-features (英语)

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

## 安装

```bash
pnpm add @happyvertical/smrt-features
```

## 快开始

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

```typescript
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`。 。 。 .

```ts
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`,哪个 请求授权人在每次写入之前与当前呼叫者绑定 未关闭 :

```typescript
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()` 属于下列类别的装饰者:

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

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

```typescript
await new FeatureSyncService(dbOptions).syncDefinitions();
```

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

```typescript
// 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\. 小组:**

```svelte
<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`,它向您的授权方询问,失败关闭:

```typescript
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`,而不是编辑。 (更名自有 软件包是这种情况的通常方式:在合格类身份改变时迁移已存储的密钥。)

## 文档

-   见 [`AGENTS.md`](https://npmcn.com/package/%40happyvertical/smrt-features/AGENTS.md) 用于软件包内部模式
-   见 [`docs/content/standards.md`](https://npmcn.com/package/docs/content/standards.md) 单一权利公约
-   见 [`docs/content/architecture/`](https://npmcn.com/package/docs/content/architecture/) 用于跨包装结构

## 常见问题

### @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 和提交记录判断。

