# @bsuite/charge-calc 中文文档

规范地址：https://npmcn.com/package/%40bsuite/charge-calc/

版本：0\.15\.0
npm 元数据更新时间：2026-11-09T09:19:55.897Z
中文译文更新时间：2026-11-09T20:13:37.999Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：501 kB，130 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：zod ^4\.0\.0
- 首次发布：2026-03-02T04:43:09.294Z
- 最新版本发布：2026-11-09T09:19:55.710Z
- 近 30 天下载量：1757（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

供澳大利亚GTO和劳务经营者使用的电荷率计算和BOOT评估引擎. 包括FWC奖的参照物、故障式探测器、F17出口和GTO多位置变体(第193/193A节,《2009年公平工作法》).

## 安装

```sh
npm install @bsuite/charge-calc
```

也可以使用：`pnpm add @bsuite/charge-calc`、`yarn add @bsuite/charge-calc`、`bun add @bsuite/charge-calc`

## README

# @ bsuite/ 充电- calc

用于澳大利亚GTO和劳动力雇用经营者的共享电荷率计算和BOOT评估引擎.

用于 **风险管理7** (收费率建模)和 **第80.3号公路** (公谊协委会授予工资比较).

* * *

## 特征

| 能力 | 入境点 | 主要出口 |
| --- | --- | --- |
| 费率计算 | `@bsuite/charge-calc` | `calculateChargeRate`, (中文(简体) ), `buildCalcConfig` |
| 账单回收 | `@bsuite/charge-calc` | `calculateBilling`, (中文(简体) ), `calculateRecovery` |
| FWC 取景奖 | `@bsuite/charge-calc/awards` | `AwardRegistry`, (中文(简体) ), `fetchAward`, (中文(简体) ), `AwardScheduleZ` |
| **BOOT 评估引擎** | `@bsuite/charge-calc/boot` | `compareBOOT`, (中文(简体) ), `compareGTOBOOT`, (中文(简体) ), `detectFailurePatterns`, (中文(简体) ), `generateRecommendations`, (中文(简体) ), `generateF17Data` |
| 共享类型 | `@bsuite/charge-calc/types` | 所有 Zod 策略和类型脚本 |

* * *

## 安装

```bash
pnpm add @bsuite/charge-calc
```

要求数 `zod ^4.0.0` 作为同伴的依赖.

* * *

## 费率计算

```ts
import { calculateChargeRate, buildCalcConfig } from '@bsuite/charge-calc';

const config = buildCalcConfig({
  baseHourlyRate: 28.50,
  casualLoading: 0.25,
  superRate: 0.12,
  workersCompRate: 0.021,
  publicLiabilityRate: 0.005,
  margin: 0.18,
});

const result = calculateChargeRate(config);
// result.chargeRate — all-up hourly charge rate
// result.breakdown — itemised cost components
```

### 命名的付费项目组ID

`calculate()` 接受CRM7自有软件 `pay_item_groups.id` 价值观使消费者能够 键速率,由命名的付费项目组 UUID 而不是类似 enum 字符串。 遗产 键在迁移时仍然可用.

```ts
import { calculate, DEFAULT_CONFIG } from '@bsuite/charge-calc';

const ordinaryPayItemGroupId = crm7PayItemGroups.ordinary.id;
const overtimePayItemGroupId = crm7PayItemGroups.overtime15.id;

const result = calculate({
  ...DEFAULT_CONFIG,
  ordinaryPayItemGroup: {
    id: ordinaryPayItemGroupId,
    name: 'Ordinary Time',
    code: 'ORD',
    category: 'ordinary_time',
    sortPriority: 10,
  },
  penalties: DEFAULT_CONFIG.penalties.map((penalty) =>
    penalty.id === 'ot15'
      ? {
          ...penalty,
          payItemGroup: {
            id: overtimePayItemGroupId,
            name: 'Overtime 1.5x',
            code: 'OT1.5',
            category: 'overtime_1_5',
            sortPriority: 20,
          },
        }
      : penalty,
  ),
});

result.rates[ordinaryPayItemGroupId]; // canonical named-group lookup
result.rates['ord']; // legacy compatibility alias
result.ratesByPayItemGroupId[overtimePayItemGroupId];
```

* * *

## BOOT 评估引擎

BOOT( 更好的全面测试) 引擎执行在 **2009年《公平工作法》第193和193A条** 由公平工作委员会批准企业协议.

> **法律免责声明**:引擎仅是一个决策支持工具. 它不构成法律咨询。 每一个结果都带着 `humanReviewRequired: true` 并且必须在依赖之前由合格的劳资关系专业人员审查。 见 `F17_DISCLAIMER` 全文.

### 建筑

```
src/boot/
├── types.ts           — Zod schemas: EATerms, AwardSchedule, RosterScenario, BOOTResult, GTOBOOTResult
├── compare.ts         — compareBOOT() — core BOOT comparator (ss.193A algorithm)
├── annual-value.ts    — computeAnnualEmployeeValue() — monetary value per scenario
├── non-monetary.ts    — compareNonMonetary() — span, rostering, leave entitlements
├── failure-detector.ts — detectFailurePatterns() — 8 known EA failure pattern codes
├── recommender.ts     — generateRecommendations() — prioritised remediation steps
├── f17-export.ts      — generateF17Data() — structured JSON for FWC Form F17
└── gto.ts             — compareGTOBOOT() — multi-placement GTO variant (s.193)
```

### 核心参照系统

```ts
import { compareBOOT } from '@bsuite/charge-calc/boot';
import type { AwardSchedule, EATerms, RosterScenario } from '@bsuite/charge-calc/boot';

const result = compareBOOT(
  [awardSchedule],    // AwardSchedule[] — modern award classification data
  eaTerms,            // EATerms — enterprise agreement to assess
  [typicalScenario, worstCaseScenario], // RosterScenario[]
  { marginalThreshold: 0.05 },          // optional MarginalConfig
);

// result.overallVerdict — 'pass' | 'fail' | 'marginal' | 'indeterminate'
// result.classResults   — per-classification breakdown with scenario-level detail
// result.warnings       — critical / warning / info diagnostics
// result.humanReviewRequired — always true (legally mandated)
```

**判决规则:**

-   `pass` ——所有情况下的EA年值 裁决额,超过边际阈值(违约5%)
-   `marginal` - EA通过但不超过5%的门槛值——建议调节条款
-   `fail` ——任何情况下EA年度价值 < 裁决
-   `indeterminate` ——缺少授标分类数据

### 失败模式检测器

```ts
import { detectFailurePatterns } from '@bsuite/charge-calc/boot';

const patterns = detectFailurePatterns(bootResult, awards, ea, scenarios);
// patterns[].code — one of 8 known failure codes:
//   'higher_base_no_penalties' | 'loaded_rate_insufficient' | 'casual_overlooked'
//   'allowances_absorbed_unproven' | 'award_entitlements_omitted' | 'stale_modelling'
//   'vague_all_inclusive' | 'non_monetary_offset_claimed'
```

### 建议者

```ts
import { generateRecommendations } from '@bsuite/charge-calc/boot';

const recs = generateRecommendations(bootResult, patterns);
// Sorted by priority: critical → high → medium → low
// recs[].action — human-readable action description
// recs[].estimatedCost — dollar amount where calculable
```

### FWC 表格F17出口

生成结构化的JSON数据,与FWC的F17比较电子表格格式相匹配,准备由演示文稿层进行PDF/XLSX渲染.

```ts
import { generateF17Data } from '@bsuite/charge-calc/boot';

const f17 = generateF17Data(bootResult, ea, 'IR Consultant Name');
// f17.header              — agreement metadata + mandatory disclaimer
// f17.classifications     — per-classification sheets with scenario matrix
// f17.scenarioMatrix      — rows × columns overview grid
// f17.summary             — pass/fail/marginal counts + totalDelta
// f17.qualitativeAssessment — non-monetary terms and notes
```

### GTO 多位变量

由多个雇主主办的学徒集体培训组织。 第193条, **每个职位都必须通过** 脚.

```ts
import { compareGTOBOOT } from '@bsuite/charge-calc/boot';

const gtoResult = compareGTOBOOT(
  {
    apprenticeId: 'abn-12345',
    currentYear: 2,
    placements: [
      {
        hostEmployerId: 'host-a',
        hostEmployerName: 'Acme Manufacturing',
        applicableAwards: [awardSchedule],
        scenarios: [typicalScenario],
        timeAllocation: 0.6,   // 60% of year at this host
      },
      {
        hostEmployerId: 'host-b',
        hostEmployerName: 'Beta Logistics',
        applicableAwards: [awardSchedule],
        scenarios: [typicalScenario],
        timeAllocation: 0.4,
      },
    ],
  },
  ea,
);

// gtoResult.overallVerdict       — fails if ANY placement fails
// gtoResult.weakestPlacement     — placement with worst delta
// gtoResult.weightedAggregateDelta — Σ(delta × timeAllocation)
```

* * *

## 测试覆盖率

在节点24上进行639个测试,TypeScript 6.0,Vite 8.

| 套间 | 文件 |
| --- | --- |
| 核心计算 | `src/__tests__/calculate.test.ts` |
| 计费 | `src/__tests__/billing.test.ts` |
| 公用事业 | `src/__tests__/utils.test.ts` |
| 类型 | `src/__tests__/types.test.ts` |
| 一体化(第一阶段) | `src/__tests__/integration.test.ts` |
| 一体化(第二阶段) | `src/__tests__/integration-phase2.test.ts` |
| 黄金案件 | `src/__tests__/golden.test.ts` |
| 变化因素 | `src/__tests__/invariants.test.ts` |
| **BOOT——核心项目** | `src/__tests__/boot/compare.test.ts` |
| **BOOT——年度价值** | `src/__tests__/boot/annual-value.test.ts` |
| **BOOT-故障探测器** | `src/__tests__/boot/failure-detector.test.ts` |
| **BOOT——建议者** | `src/__tests__/boot/recommender.test.ts` |
| **BOOT — F17 导出** | `src/__tests__/boot/f17-export.test.ts` |
| **BOTO — GTO (英语)** | `src/__tests__/boot/gto.test.ts` |
| **BOOT——类型** | `src/__tests__/boot/types.test.ts` |
| **BOOT——黄金案件** | `src/__tests__/boot/golden-boot.test.ts` |
| **BOOT——变化无常** | `src/__tests__/boot/invariants-boot.test.ts` |

```bash
pnpm test          # run all tests
pnpm test:coverage # generate coverage report
```

* * *

## 软件包出口

```jsonc
{
  ".":        "dist/index.js",           // charge-rate calc + billing + awards + boot
  "./types":  "dist/types.js",           // shared types only
  "./awards": "dist/awards/index.js",    // FWC award registry
  "./boot":   "dist/boot/index.js"       // BOOT assessment engine
}
```

* * *

## 构建

```bash
pnpm build      # tsc -p tsconfig.build.json → dist/
pnpm typecheck  # type-check only, no emit
```

* * *

## 捐款

见 [捐款额](https://npmcn.com/package/%40bsuite/charge-calc/CONTRIBUTING.md) 和根数 [克劳德·姆德](https://npmcn.com/package/CLAUDE.md) 项目范围标准.

修改此软件包时: 建出 + 凸起版本 `package.json` 将软件包释放的 PR 合并到 `main` 这样 `.github/workflows/publish-charge-calc.yml` 通过 npm 信任出版商出版(GitHub Actions OIDC, no) `NPM_TOKEN`• 更新消费者资料 `package.json` 文件 – 每页重生成锁文件 **锁定文件生成** 规则在CLAUDE.MD.

## 常见问题

### @bsuite/charge-calc 是什么？

供澳大利亚GTO和劳务经营者使用的电荷率计算和BOOT评估引擎\. 包括FWC奖的参照物、故障式探测器、F17出口和GTO多位置变体\(第193/193A节,《2009年公平工作法》\)\.

### 如何安装 @bsuite/charge-calc？

在项目目录运行 npm install @bsuite/charge-calc，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bsuite/charge-calc 支持 TypeScript 吗？

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

### @bsuite/charge-calc 支持 ESM 还是 CommonJS？

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

### @bsuite/charge-calc 可以商用吗？

@bsuite/charge-calc 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @bsuite/charge-calc 的下载量有多少？

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

### @bsuite/charge-calc 还在维护吗？

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