# @courthive/provider-config 中文文档

规范地址：https://npmcn.com/package/%40courthive/provider-config/

版本：1\.1\.0
npm 元数据更新时间：2026-11-12T21:49:00.892Z
中文译文更新时间：2026-11-16T02:02:07.759Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：155 kB，17 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- 首次发布：2026-05-07T17:17:08.239Z
- 最新版本发布：2026-11-12T21:49:00.548Z
- 近 30 天下载量：1961（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

用于CurtHive提供者配置的Canonial类型、关键设备、验证器、计算有效功能和MUTION PERMISIONS.

## 安装

```sh
npm install @courthive/provider-config
```

也可以使用：`pnpm add @courthive/provider-config`、`yarn add @courthive/provider-config`、`bun add @courthive/provider-config`

## README

# @ courthive/ 提供者- 配置

手饰类型 关键设备 验证器, `computeEffectiveConfig`,以及 `MUTATION_PERMISSIONS` 用于 CurtHive 提供者配置.

纯 TypeScript, 没有运行时间依赖性 。 部分 [法院](https://github.com/CourtHive) 生态系统.

由下列人士组成:

-   `competition-factory-server` ——服务器侧验证, 执行队列
-   `competition-factory-server/admin-client` — 封顶+设置编辑器
-   `courthive-ams` 控制台-供应商盖/设置管理
-   `TMX` ——运行时间单通,变异地标,品牌+隐私应用

## 安装

```bash
pnpm add @courthive/provider-config
```

在CourseHive monorepo内部,这个包只用pnpm——本地兄弟 链接通过 `pnpm.overrides` 无法活下来 `npm install`。 。 。 .

## 双层提供者配置模型

提供者配置分为两个所有者级加计算 有效形状 :

-   **`ProviderConfigCaps`** ——供养自有. 供应商的上限 不能超过:白标签品牌默认,许可上限, 允许的宇宙(绘图类型、类别、分级系统),以及 集成(SSO,积分发射).
-   **`ProviderConfigSettings`** ——供养主体自有. 每日调试 在上限内:可能禁用上限允许的布尔,可能 缩窄 `allowedX` 数组,并拥有操作策略,默认值, 品牌覆盖, 参与者隐私完全.
-   **`ProviderConfigData`** ——有效形状TMX被消耗,被生产 以 `computeEffectiveConfig(caps, settings)`. TMX没有意识到 盖子/套子分开,它只看到合并的结果.

权限封顶覆模型是 **上限 qq 设置相交点**数字 : 只有在有效配置中启用布尔值 _两者_ 等级 允许它,和一个 `allowedX` 宇宙跨越两层. 见下文"有效配置计算".

## 出口

从软件包根中导出所有东西( E)`./dist/index.js`, (中文(简体) ), 类型 `./dist/index.d.ts`) (中文(简体) ).

### 类型

| 导出 | 目的 |
| --- | --- |
| `ProviderConfigCaps` | 提供人拥有的上限(品牌、许可、政策、整合) |
| `ProviderConfigSettings` | 供应商拥有的设置(许可、政策、默认、品牌、参与者 |
| `ProviderConfigData` | 交付给TMX的计算有效形状 |
| `ProviderBranding` | 白色标签品牌领域 |
| `ProviderPermissions` | 完全允许表面( booleans + 允许的阵列) |
| `ProviderCapsPermissions` | `Pick` 联 合 国 `ProviderPermissions` 限于可封存的密钥 |
| `ProviderCapsPolicies` | 顶级允许的宇宙(格式、类别、分级系统) |
| `ProviderPolicyDefaults` | 设置级操作政策+允许列表 |
| `ProviderDefaults` | 新实体默认(事件类型、绘图类型、语言、PDF字体、.) |
| `ProviderIntegrations` | SSO 供应商 + 积分- 发射配置 |
| `ProviderParticipantPrivacy` | 外观隐私切换( 目前) `cityState`(中文(简体) ) |
| `ProviderBranding`, (中文(简体) ), `AllowedCategory`, (中文(简体) ), `AllowedTierSystem` | 分级共享的子类型 |
| `RankingPointsPolicy`, (中文(简体) ), `RankingPointsPolicyKind` | 分级政策分类器 |
| `PrintPoliciesByType` | 每印花型的不透明 pdf 构件政策 |
| `ScoringLaunchConfig`, (中文(简体) ), `ScoringLaunchApp` | 科学应用发射目标 |
| `ScoringLaunchContext` | 用于 URL 替换的占位符值 |
| `BooleanPermissionKey`, (中文(简体) ), `ArrayPermissionKey`, (中文(简体) ), `CappablePermissionKey` | 许可基联盟 |
| `ValidationIssue`, (中文(简体) ), `ValidationIssueCode` | 校验结果形状 |

### 常数

| 导出 | 价值/目的 |
| --- | --- |
| `BOOLEAN_PERMISSION_KEYS` | 所有布尔权限密钥的排序列表 |
| `ARRAY_PERMISSION_KEYS` | `allowedDrawTypes`, (中文(简体) ), `allowedCreationMethods`, (中文(简体) ), `allowedScoringApproaches` |
| `ARRAY_POLICY_KEYS` | `allowedMatchUpFormats`, (中文(简体) ), `allowedCategories`, (中文(简体) ), `allowedTierSystems` |
| `PERMISSIONS_DEFAULT_FALSE` | `Set` 默认权限 `false` (单位:千美元)`canModifyCompletedScores`, (中文(简体) ), `canAccessProviderAdmin`(中文(简体) ) |
| `RANKING_POINTS_POLICY_KINDS` | `['BASIC', 'CUSTOM', 'NATIONAL']` |
| `SCORING_LAUNCH_APPS` | `['EPIXODIC', 'EMBEDDED', 'EXTERNAL']` |
| `SCORING_LAUNCH_PLACEHOLDERS` | `['tournamentId', 'matchUpId', 'eventId', 'drawId']` |
| `DEFAULT_SCORING_LAUNCH` | `{ app: 'EPIXODIC' }` |
| `MUTATION_PERMISSIONS` | 工厂变异方法图 • `keyof ProviderPermissions` |

### 职能

| 导出 | 签署 |
| --- | --- |
| `computeEffectiveConfig` | `(caps?: ProviderConfigCaps, settings?: ProviderConfigSettings) => ProviderConfigData` |
| `mergePermissions` | `(caps?: Partial<ProviderPermissions>, settings?: Partial<ProviderPermissions>) => ProviderPermissions` |
| `mergePolicies` | `(caps?: Partial<ProviderPolicyDefaults>, settings?: Partial<ProviderPolicyDefaults>) => ProviderPolicyDefaults` |
| `resolveRankingPointsPolicy` | `(settings?: Partial<ProviderPolicyDefaults>) => RankingPointsPolicy` |
| `validateCaps` | `(caps: unknown) => ValidationIssue[]` |
| `validateSettings` | `(settings: unknown, caps?: ProviderConfigCaps) => ValidationIssue[]` |
| `isMutationAllowed` | `(method: string, permissions?: ProviderPermissions) => boolean` |
| `resolveScoringLaunchUrl` | `(urlTemplate: string, ctx: ScoringLaunchContext) => string` |
| `scoringLaunchPlaceholders` | `(urlTemplate: string) => string[]` |

> 说明: `computeEffectiveConfig` 调用 `mergeBranding` 内部, 不过 `mergeBranding` 未从软件包根导出 下文将逐个实地/象征性的合并行为作为组成部分记录 联 合 国 `computeEffectiveConfig`。 。 。 .

```ts
import {
  // Types
  type ProviderConfigCaps,
  type ProviderConfigSettings,
  type ProviderConfigData,
  type ProviderPermissions,
  type ProviderBranding,
  type ScoringLaunchConfig,
  type ValidationIssue,
  // KEYS + constants
  BOOLEAN_PERMISSION_KEYS,
  ARRAY_PERMISSION_KEYS,
  PERMISSIONS_DEFAULT_FALSE,
  SCORING_LAUNCH_APPS,
  DEFAULT_SCORING_LAUNCH,
  // Functions
  computeEffectiveConfig,
  mergePermissions,
  mergePolicies,
  resolveRankingPointsPolicy,
  resolveScoringLaunchUrl,
  validateCaps,
  validateSettings,
  // Mutation gate
  MUTATION_PERMISSIONS,
  isMutationAllowed,
} from '@courthive/provider-config';
```

## 类型

### `ProviderBranding`

白色标签品牌,由TMX在靴子和提供商开关上应用. 一切田地可选.

| 外地 | 类型 | 目的 |
| --- | --- | --- |
| `navbarLogoUrl` | `string` | 导航栏标志的 URL 或 data- URI (替换"TMX"文本) |
| `navbarLogoAlt` | `string` | 导航栏标志的替代文本 |
| `navbarLogoHeight` | `number` | Px 中最大导航- logo 高度( 默认 32) |
| `splashLogoUrl` | `string` | 喷出/登录标志的 URL/data-URI(取代 CurtHive hex) |
| `appName` | `string` | 页面标题 + 导航栏中的 App 名称( 默认“ TMX ”) |
| `accentColor` | `string` | 角色覆盖( CSS 颜色值) |
| `themeTokens` | `Record<string, string>` | 适用于 `document.documentElement`键 `--tmx-` 或者说 `--chc-` |
| `stylesheetUrl` | `string` | URL 到提供者托管的样式表 `<head>` (逃出舱门) `themeTokens`(中文(简体) ) |

### `ProviderPermissions`

完全允许表面。 布尔字段加三 `allowedX` 字符串 数组。 大多数布尔值默认为 `true` (允许);例外 列入清单 `PERMISSIONS_DEFAULT_FALSE` 默认为 `false`。 。 。 .

布尔键( 按区域分组) :

-   **与会者** —— 说 `canCreateCompetitors`, (中文(简体) ), `canCreateOfficials`, (中文(简体) ), `canDeleteParticipants`, (中文(简体) ), `canImportParticipants`, (中文(简体) ), `canEditParticipantDetails`
-   **活动** —— 说 `canCreateEvents`, (中文(简体) ), `canDeleteEvents`, (中文(简体) ), `canModifyEventFormat`
-   **绘图** —— 说 `canCreateDraws`, (中文(简体) ), `canDeleteDraws`, (中文(简体) ), `canUseDraftPositioning`, (中文(简体) ), `canUseManualPositioning`
-   **时间安排** —— 说 `canModifySchedule`, (中文(简体) ), `canUseBulkScheduling`
-   **地点** —— 说 `canCreateVenues`, (中文(简体) ), `canDeleteVenues`, (中文(简体) ), `canModifyCourtAvailability`
-   **分数** —— 说 `canEnterScores`, (中文(简体) ), `canModifyCompletedScores` (默认) `false`(中文(简体) )
-   **出版** —— 说 `canPublish`, (中文(简体) ), `canUnpublish`
-   **设置** —— 说 `canModifyTournamentDetails`, (中文(简体) ), `canModifyPolicies`, (中文(简体) ), `canAccessProviderAdmin` (默认) `false`(中文(简体) )
-   **通讯** —— 说 `canUseChat` (导出聊天;默认为 `true`,一个提供者可以设置它 `false` 以禁用整个比赛的聊天)

矩阵密钥 : `allowedDrawTypes`, (中文(简体) ), `allowedCreationMethods`, (中文(简体) ), `allowedScoringApproaches`。空阵列表示“不受限制”.

### `ProviderParticipantPrivacy` 财务报告和审定财务报表 `participantPrivacyPolicy`

两个供应商拥有(只有等级——提供方没有) 说) 参与者隐私的表面:

-   **`participantPrivacy`** (单位:千美元)`ProviderParticipantPrivacy`)——颗粒体 放松个人属性默认隐私的布尔切换 政策从公共有效载荷中剥离。 目前一个领域, `cityState`, (中文(简体) ), 允许 `person.addresses[0].city / .state` 通过(街道和 邮政编码被取消). 每个字段的默认值是 `false` (原始内容存档于2013-10-12). (privacy-first).
-   **`participantPrivacyPolicy`** (单位:千美元)`Record<string, any>`)——富人 后继者:完整的工厂 `POLICY_TYPE_PARTICIPANT` 属性过滤器 (内相. 这里不透明( 结构上被验证为平原) object),所以工厂拥有属性计划. 附于 提供商的锦标赛记录 所以工厂的条纹/保值属性 在与会者询问期间.

### `ScoringLaunchConfig` 财务报告和审定财务报表 `ScoringLaunchApp`

提供商宣布的评分应用发射目标 上场公众 每场比赛 "评分这场比赛"动作. 活着 `caps.integrations.scoringLaunch` (盖所拥有——提供人控制) (b) 一体化).

```ts
type ScoringLaunchApp = 'EPIXODIC' | 'EMBEDDED' | 'EXTERNAL';

interface ScoringLaunchConfig {
  app: ScoringLaunchApp;
  urlTemplate?: string; // required when app === 'EXTERNAL'
}
```

发射模式 :

-   **`EPIXODIC`** ——CourseHive Epixodic 深度链接. 虚无时的默认 已宣布(`DEFAULT_SCORING_LAUNCH = { app: 'EPIXODIC' }`) (中文(简体) ).
-   **`EMBEDDED`** ——法庭-公众自己的页面 `/track` 得分壳.
-   **`EXTERNAL`** - 供应商自己的应用程序通过 `urlTemplate`,与 `${tournamentId}`, (中文(简体) ), `${matchUpId}`, (中文(简体) ), `${eventId}`, (中文(简体) ), `${drawId}` 发射时替换为 `resolveScoringLaunchUrl`。 。 。 .

```ts
import { resolveScoringLaunchUrl } from '@courthive/provider-config';

const url = resolveScoringLaunchUrl('https://score.example.com/m/${matchUpId}?t=${tournamentId}', {
  matchUpId: 'mu-1',
  tournamentId: 't-9',
});
// → 'https://score.example.com/m/mu-1?t=t-9'
// Values are URI-component-encoded; unknown/absent placeholders → ''.
```

### `RankingPointsPolicy`

分类谁拥有提供者使用的排名点政策: `kind` 这是其中之一 `'BASIC' | 'CUSTOM' | 'NATIONAL'` (当 字段被声明),加上可选 `name` 财务报告和审定财务报表 `version`未宣布 提供者决心 `{ kind: 'BASIC' }` 通过 `resolveRankingPointsPolicy` 为后相.

## 有效配置计算

`computeEffectiveConfig(caps, settings)` 将两层合并到 `ProviderConfigData` TMX消耗. 两种参数默认为 `{}`。 。 。 .

按字段合并规则 :

| 外地 | 规则 |
| --- | --- |
| `branding` | 设置将覆盖字段; `themeTokens` 按键合并 |
| `permissions` (布尔斯) | `(caps[X] ?? defaultForX) && (settings[X] ?? defaultForX)` - 两层必须允许 |
| `permissions` (阵列) | `intersect(caps[X], settings[X])` ——两侧空出 = 无限制 |
| `policies.allowedMatchUpFormats` 编号 : `allowedCategories` | 跨越上限+设置相交 |
| `policies.scheduling/scoring/seeding/rankingPointsPolicy` | 设置拥有 |
| `defaults` | 设置拥有 |
| `integrations` | 盖有 |
| `participantPrivacy` | 设置拥有; 已规范为 `{ cityState: settings.participantPrivacy?.cityState === true }` |
| `participantPrivacyPolicy` | 设置拥有;通过逐字记录 |

组合相交语义( S)`allowedX` 和允许的政策清单:如果 双方都是 `undefined` 或为空,对方获胜(空="否" 限制"); 如果两者都是非空的,结果就是它们的相交. 类别相交 `ageCategoryCode`。 。 。 .

### 工作实例——权限上限 QQ 设置

```ts
import { computeEffectiveConfig } from '@courthive/provider-config';

const caps = {
  permissions: {
    canDeleteEvents: false, // provisioner forbids delete-events
    canEnterScores: true,
    allowedDrawTypes: ['SINGLE_ELIMINATION', 'ROUND_ROBIN', 'COMPASS'],
  },
};

const settings = {
  permissions: {
    canEnterScores: false, // provider chooses to disable
    canDeleteEvents: true, // provider tries to enable (blocked by cap)
    allowedDrawTypes: ['ROUND_ROBIN', 'FEED_IN'], // narrows within cap
  },
};

const effective = computeEffectiveConfig(caps, settings);

effective.permissions.canDeleteEvents; // false — cap forbids, AND wins
effective.permissions.canEnterScores; // false — settings disabled, AND wins
effective.permissions.allowedDrawTypes; // ['ROUND_ROBIN'] — intersection
effective.permissions.canCreateEvents; // true — unset both sides, permissive default
effective.permissions.canModifyCompletedScores; // false — PERMISSIONS_DEFAULT_FALSE
```

### 成功的例子——品牌合并(设定-上限)

`branding` 没有锁级 : `caps.branding` 是供养者种子 默认/倒置,以及 `settings.branding` (供应商拥有)获胜 字段逐字段定义一个值. `themeTokens` 地图合并 逐个按键, 供货商可以不降下而添加令牌 提供种子的——在关键相撞时,设置符号 赢了.

```ts
const caps = {
  branding: {
    appName: 'Provisioner Default',
    navbarLogoUrl: 'https://cdn.example.com/provisioner.png',
    themeTokens: { '--tmx-accent-blue': '#003366', '--tmx-bg-primary': '#ffffff' },
  },
};

const settings = {
  branding: {
    appName: 'Acme Tennis', // overrides caps value
    themeTokens: { '--tmx-accent-blue': '#1a5276' }, // overrides one token
  },
};

const { branding } = computeEffectiveConfig(caps, settings);

branding.appName; // 'Acme Tennis'                        (settings wins)
branding.navbarLogoUrl; // 'https://cdn.example.com/provisioner.png' (caps preserved)
branding.themeTokens; // { '--tmx-accent-blue': '#1a5276',   (settings token wins)
//   '--tmx-bg-primary': '#ffffff' }    (caps token preserved)
```

当两个层次都没有定义任何品牌时,有效的 `branding` 实值 `undefined`,保留"无品牌"合同.

## 验证器

两个验证器都是纯粹的函数——它们不扔任何东西,还原一个 数组 `ValidationIssue`来电者决定问题是否难解决 拒绝 (HTTP 400) 或信息警告 .

```ts
interface ValidationIssue {
  path: string; // dotted path, e.g. "permissions.allowedDrawTypes"
  code: ValidationIssueCode; // 'unknownField' | 'wrongType' | 'exceedsCap'
  message: string;
  disallowedValues?: string[]; // set for exceedsCap
}
```

-   **`validateCaps(caps)`** ——从结构上检查盖子写出. 拒绝 未知的顶级密钥( 只有 `branding`, (中文(简体) ), `permissions`, (中文(简体) ), `policies`, (中文(简体) ), `integrations` (允许),错误类型,未知品牌/许可/ 政策/集成键和前缀 `themeTokens`。 。 。 .
-   **`validateSettings(settings, caps)`** - 结构检查加 盖-尊重. 除了结构检查,它还标出 `exceedsCap` 当设置写入将超过提供方时 天花板: 使设定的天花板布尔到 `false`,或包括 `allowedX` / 允许政策值在盖子宇宙之外.

```ts
import { validateSettings } from '@courthive/provider-config';

const issues = validateSettings(
  { permissions: { canDeleteEvents: true } },
  { permissions: { canDeleteEvents: false } }, // caps forbid it
);
// issues → [{ path: 'permissions.canDeleteEvents', code: 'exceedsCap',
//             message: 'canDeleteEvents cannot be enabled — provisioner cap forbids it' }]
```

设置验证符也会在结构上验证内部政策 形状( e)`schedulingPolicy`, (中文(简体) ), `scoringPolicy`, (中文(简体) ), `seedingPolicy`, (中文(简体) ), `rankingPointsPolicy`对抗被人类所接受的野外宇宙 工厂发动机和验证 `integrations.scoringLaunch` (有效数) `app`,已知的占位者, `urlTemplate` 所需经费 `EXTERNAL`) (中文(简体) ).

## 变形

`MUTATION_PERMISSIONS` 地图厂变异方法名称 允许键打开它们. `isMutationAllowed(method, permissions)` 返回是否允许突变 :

-   默认允许在地图中不使用的方法.
-   布尔权限门( 未定义 ) – `true`允许.
-   矩阵权限是 _没有_ 在这里执行,它们有丰富的语义 检查不同的图层( 例如, 当绘图类型本身是 已选中).

```ts
import { isMutationAllowed } from '@courthive/provider-config';

isMutationAllowed('deleteEvents', { canDeleteEvents: false }); // false
isMutationAllowed('addEvent', {}); // true (permissive)
isMutationAllowed('someUngatedMethod', {}); // true (not in map)
```

用于TMX `mutationRequest()` 作为 UI 防御层和服务器 `executionQueue` 作为对WebSocket有效载荷的深度防御.

## 构建/ 测试

```bash
pnpm build         # rm -rf dist && tsc → dist/
pnpm test          # vitest --run
pnpm check-types   # tsc --noEmit
pnpm lint          # ESLint — non-mutating, fails on any warning
pnpm lint:fix      # ESLint with auto-fix (rewrites source)
pnpm format        # prettier --write "src/**/*.ts"
```

## 许可证

麻省理工学院

## 常见问题

### @courthive/provider-config 是什么？

用于CurtHive提供者配置的Canonial类型、关键设备、验证器、计算有效功能和MUTION PERMISIONS\.

### 如何安装 @courthive/provider-config？

在项目目录运行 npm install @courthive/provider-config，或使用 pnpm add / yarn add / bun add。

### @courthive/provider-config 支持 TypeScript 吗？

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

### @courthive/provider-config 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @courthive/provider-config 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @courthive/provider-config 可以商用吗？

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

### @courthive/provider-config 的下载量有多少？

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

### @courthive/provider-config 还在维护吗？

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

