# @happyvertical/smrt-ledgers 中文文档

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

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

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

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

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

- 包体积（解压后）：595 kB，50 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-06-23T01:18:37.367Z
- 最新版本发布：2026-11-17T07:53:42.892Z
- 近 30 天下载量：17163（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：365（近 12 个月 365 个）

## 中文简介

SMRT框架双入帐分类账

## 安装

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

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

## README

# @ happyvertical/ smrt- lidgeers (笑) (笑) (掌声)

S-m-r-t框架的双入帐分类账. 分级记账图,寄出后不可更改的日记账周期,并平衡执行与epsilon容忍度.

## 准确分类账和对应方

创建一个 `Ledger` 与 `balanceMode: 'exact-integer'` 和 ISO 货币时 会计范围储存小单位。 分配给这一机构的账户和日记 分类账必须分享其租户和货币;账出拒绝分数或不安全 \* 数额和所需借记和贷记总额完全相等。 现有期刊 没有分类账 保留兼容的容忍小数规则。 直接进入 写入需要可访问的同所有者日志和匹配账户/期刊 分类账范围;遗留的日记不能写出范围账户的变动情况。 一个 现有账户不能改变分类账范围,包括未指定账户的采用 账户; 创建新范围账户。 范围账户的创建得到验证 引用的分类账所有者. `createChild()` 继承持续存在的被限制的父程序 分类账和所有者 拒绝相互矛盾的重置.

`JournalEntry` 携带不透明 `counterpartyKind` 编号 : `counterpartyId` 数值, 加上可选 `dueDate`。 。 。 . `JournalEntryCollection.getCounterpartyBalances()` 报告公布了来电账户的AR/AP移动情况。 衰老是一个 打开项目报告:原始行需要源代码和到期日,以及 后期定居用途 `settlesSourceRef`. 勿从网中推断老化 对方余额.

使用 `postReceivable`, (中文(简体) ), `postPayable`,或 `postSettlement` 准确分类账 事件。 他们用一个租户扫描的独能键 并创建日记加行 根据框架的原子重试要求。 内容已更改的重放 拒绝。 同上,proptity是永久性的,不受重试要求的约束 保留窗口:在裁剪索赔后,重试解决现有 日记 `(tenantId, ledgerId, key)` 并在请求摘要时返回 匹配,或拒绝更改的重放。 退款及纠纷必须另加赔偿 新密钥; 已张贴的分类账日记账及其行不能编辑、删除, 或 无效。 转回借方/贷方账户和设置 `settlesSourceRef` 页:1 缩小时原始打开的项目 。 部分倒置使用部分整数 金额; 全部倒转使用所剩金额。 商业/销售拥有决定权 和保留外部付款/退款活动,包括争议 支付后; 分类账从不启动转账。 之后重试相同的密钥 外部支付完成和分类账公布之间发生的意外。 失败的分类账 交易卷起日记、行和重试收据。 手动 编辑和张贴交易中母日记订正案的草稿; 同步失败者无法关闭,在重试前必须重新装入.

钥匙是独一无二的 `(tenantId, ledgerId)` 并约束所有会计投入, 包括明确规定的日期。 使用第一个成功日期 发布时间。 调用者的参考文献必须在 选中的账户 。 使用 `normalBalance: 'credit'` aP老化/余额(AR为 借项 -- -- 默认正常)。 平衡报告的使用情况 `from`编号 :`to`; 衰老用途 `from`编号 :`asOf`选择一个 `from` 包括原始义务。 包括非订单结算 一旦来源存在; 未来运动被排除在历史之外 报告。 负结余/贷方在结余中仍然可见,而不是老化的桶子.

版面货币,所有者和余额模式是不可改变的. 数量是安全的整数 零 epsilon 的小型单位; 帮助者从不绕行、 分配剩余部分或转换 货币。 销售拥有确定性分配四舍五入和剩余任务; 商业拥有原毛/税/费。 每个边界必须经过和解 整数,例如CAD 100.00工人合作发票 和10 000个项目收入入帐额。 CAD 40.00 的解决方案推翻了其中的4000 应收,留作6000. 未分配的遗留日记保留其现有的空白 和小数行为.

交易寄出和子化套件覆盖了SQLite和PostgreSQL. DuckDB 无法提供此软件包的现有 `JournalEntry` 外国 键:框架明确拒绝DuckDB在更新 CASCADE上不支持的. 这不是一个支持的精确引导器运行时间;没有削弱关系来制作 方言看起来是相容的.

## 安装

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

## 使用量

```typescript
import {
  Account, AccountCollection,
  Journal, JournalCollection,
  JournalEntry, JournalEntryCollection
} from '@happyvertical/smrt-ledgers';

// Set up chart of accounts
const accounts = await AccountCollection.create({ db });
const cash = await accounts.create({
  number: '1000',
  name: 'Cash',
  type: 'asset',
});
await cash.save();

const revenue = await accounts.create({
  number: '4000',
  name: 'Sales Revenue',
  type: 'revenue',
});
await revenue.save();

// Create a sub-account under Cash
const checking = await cash.createChild({
  number: '1010',
  name: 'Checking Account',
});

// Create a balanced journal with entries
const journals = await JournalCollection.create({ db });
const journal = await journals.createWithEntries({
  description: 'Cash sale',
  sourceModule: 'manual',
  entries: [
    { accountId: cash.id, debit: 100.00 },
    { accountId: revenue.id, credit: 100.00 },
  ],
});

// Post the journal (validates balance, then immutable)
await journal.post();

// Query balances
const cashBalance = await cash.getBalance();

// Get trial balance across all active accounts
const entries = await JournalEntryCollection.create({ db });
const trialBalance = await entries.getTrialBalance();

// Void a journal (cannot edit after posting, only void)
await journal.void('Duplicate entry');
```

## 双进会计

每份日记必须保持平衡才能张贴. 平衡检查使用 `BALANCE_EPSILON = 0.001` 处理浮点四舍五入:

```
Math.abs(totalDebits - totalCredits) < 0.001
```

账户类型遵循标准会计规则:

-   **调试正常** (资产,支出):余额=借方 -- -- 贷方
-   **信用 - 正常状态** (负债、权益、收入):余额=贷方 -- -- 借方

### 期刊生命周期

日记严格遵循 `draft -> posted -> voided` 生命周期:

-   **草案**: 可编辑, 条目可以通过 `journal.addEntry()`
-   **已张贴**: 不可改变,经核实的余额, `postedAt` 时间戳集
-   **虚拟**: 标记为 `voidReason` 财务报告和审定财务报表 `voidedAt`,无法编辑或重新张贴

每个期刊 Entry 都必须有借记或贷记(不是两个,不是零). 数量必须是非负数。 通过下列方式支持多种货币: `exchangeRate` 每个条目.

## API 密码

### 模型

| 导出 | 说明 |
| --- | --- |
| `Account` | 包含类型、数量、等级父和余额查询的账户条目图 |
| `Journal` | 具有状态生命周期、自动编号(JNL-\*)和源模块/源代码的交易日志 |
| `JournalEntry` | 日记账内有货币和汇率的个别借项或贷记项 |

### 收款

| 导出 | 关键方法 |
| --- | --- |
| `AccountCollection` | `findChildren()`, (中文(简体) ), `findActive()` |
| `JournalCollection` | `createWithEntries()`, (中文(简体) ), `findByNumber()`, (中文(简体) ), `findByDateRange()`, (中文(简体) ), `findBySource()`, (中文(简体) ), `findByStatus()`, (中文(简体) ), `findDrafts()`, (中文(简体) ), `findPosted()` |
| `JournalEntryCollection` | `findByJournal()`, (中文(简体) ), `findByAccount()`, (中文(简体) ), `getAccountBalance()`, (中文(简体) ), `getTrialBalance()`, (中文(简体) ), `getAccountLedger()`, (中文(简体) ), `getTotalsForDateRange()` |

### 移徙

| 导出 | 说明 |
| --- | --- |
| `planLedgerAccountsTableMove(db)` | 计算账簿行数前的 # 3098 `accounts` 表格仍然保留,不用写 |
| `migrateLedgerAccountsTable(db, options?)` | 搬进去 `ledger_accounts` (见 [升级](https://npmcn.com/package/%40happyvertical/smrt-ledgers/#readme-upgrading-from-051x-the-ledger_accounts-table-3098)(中文(简体) ) |
| `LedgerAccountsTableMoveError` | 当移动拒绝时抛出( 不确定行、 id相冲突、 缺少表格、 非 PostgreSQL) |

### 类型

| 导出 | 说明 |
| --- | --- |
| `AccountType` | `'asset'`, (中文(简体) ), `'liability'`, (中文(简体) ), `'equity'`, (中文(简体) ), `'revenue'`, (中文(简体) ), `'expense'` |
| `JournalStatus` | `'draft'`, (中文(简体) ), `'posted'`, (中文(简体) ), `'voided'` |
| `AccountOptions` | 创建账户的选项 |
| `JournalOptions` | 创建日志的选项 |
| `JournalEntryOptions` | 创建日记条目的选项 |
| `JournalEntryData` | 条目数据 `addEntry()` 编号 : `createWithEntries()` |
| `CreateJournalData` | 完整的日记+条目创建有效载荷 |
| `TrialBalanceRow` | 试算表报告行(账目、数目、名称、类型、借项/贷方余额) |
| `AccountTree` | 账户节点树( 根数组) |
| `AccountTreeNode` | 账户树中的单一节点(账户+孩子) |

## 从0.51x升级: `ledger_accounts` 表格 (# 3098)

`Account` 存储于 `ledger_accounts`。较早的发布会生成表格 名称 `accounts`,哪个 `@happyvertical/smrt-messages` 也用于 不相关的消息 `Account`; 包含两个软件包的应用程序有一个工会表 每个包的行读作自己的行。 现有数据库移动其分类账 在 PostgreSQL 维护窗口中的账户 :

1.  `smrt db:migrate-ledger-accounts --dry-run`,则没有 `--dry-run` —— 说 创建 `ledger_accounts` 当它缺失时(`db:migrate` 无法先行 : 这是所有或没有,和 `journal_entries.account_id` 外国密钥 仍然点数 `accounts` 将每个分类账行(编号、等级和元数据不变)复制成 `ledger_accounts`,解开外国密钥的分类账 `accounts`,以及 删除一个锁定交易中移动的行。 通讯行( 那些 与科学、技术和创新歧视者在一起) 在写东西之前,它拒绝一行 他们的主人是不确定的, 已经存在 `ledger_accounts`,以及任意 输入外国密钥 `accounts` 没有注册的模型声明(它将 换句话说, 或级联; 重跑是无。 同样的步骤是 `migrateLedgerAccountsTable(db)` 编号 : `planLedgerAccountsTableMove(db)` 从 这个软件包——用注册的应用程序模型称之为 CLI确实如此.
2.  `smrt db:migrate` - 添加外国密钥对 `ledger_accounts`。 。 。 .

后来 `accounts` 要么是空的( 仅靠窗子 ) , 空的就丢掉 )或只持有信件账户外加未使用的分类账列 `number`, (中文(简体) ), `type`, (中文(简体) ), `parent_id`, (中文(简体) ), `description`, (中文(简体) ), `active` 财务报告和审定财务报表 `metadata`,哪个 一旦核实,即可丢弃。 一个从不运行分类账的数据库不需要任何东西.

该移动支持PostgreSQL. 在SQLite上,一个数据库 `accounts` 图表 只持有分类账账户 `ALTER TABLE accounts RENAME TO ledger_accounts` 步骤 1 之前; SQLite 数据库中还保存信件账户的,必须重建.

用光名引用分类账模型的代码 `'Account'` 应使用 构造器或合格名称 `@happyvertical/smrt-ledgers:Account`· ; 导出 `Account` 财务报告和审定财务报表 `AccountCollection` 不变.

## 依赖关系

-   `@happyvertical/smrt-core` -- ORM 和代码生成
-   `@happyvertical/smrt-tenancy` -- 多租户范围界定

## 贡献者指南

见 [`AGENTS.md`](https://npmcn.com/package/%40happyvertical/smrt-ledgers/AGENTS.md) 用于软件包结构、变化、验证、, 和贡献者的指导.

会计身份只插入其第一个保存:一个明确的shot/context 碰撞无法替换现有的分类账、账户、日记账或行。 装入 已存在的通过生命周期守护器更新它的对象。 这也适用于: 遗留未指定对象; 自然键替换不是一个支持的更新路径. 遗留的租户日记账可能仍然使用没有分类账的共享全球账户; 范围化日记账需要其分类账所属账户.

期刊在创建时选择其分类账范围. 无效的日记草稿 在分类账之间移动或在未指定和范围之间变动,即使为空. 为另一个范围创建新日记; 防止飞行中遗留线 在验证后输入准确的分类账。 一般同范围草案 编辑和遗赠的小数期刊保留了它们现有的行为.

## 常见问题

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

SMRT框架双入帐分类账

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

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

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

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

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

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

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

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

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

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

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

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

