@happyvertical/smrt-ledgers

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

SMRT框架双入帐分类账

中文使用文档
文档目录13 节
  1. 准确分类账和对应方
  2. 安装
  3. 使用量
  4. 双进会计
  5. 期刊生命周期
  6. API 密码
  7. 模型
  8. 收款
  9. 移徙
  10. 类型
  11. 从0.51x升级: ledger_accounts 表格 (# 3098)
  12. 依赖关系
  13. 贡献者指南

@ 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上不支持的. 这不是一个支持的精确引导器运行时间;没有削弱关系来制作 方言看起来是相容的.

安装

pnpm add @happyvertical/smrt-ledgers

使用量

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日记账内有货币和汇率的个别借项或贷记项

收款

导出关键方法
AccountCollectionfindChildren(), (中文(简体) ), findActive()
JournalCollectioncreateWithEntries(), (中文(简体) ), findByNumber(), (中文(简体) ), findByDateRange(), (中文(简体) ), findBySource(), (中文(简体) ), findByStatus(), (中文(简体) ), findDrafts(), (中文(简体) ), findPosted()
JournalEntryCollectionfindByJournal(), (中文(简体) ), findByAccount(), (中文(简体) ), getAccountBalance(), (中文(简体) ), getTrialBalance(), (中文(简体) ), getAccountLedger(), (中文(简体) ), getTotalsForDateRange()

移徙

导出说明
planLedgerAccountsTableMove(db)计算账簿行数前的 # 3098 accounts 表格仍然保留,不用写
migrateLedgerAccountsTable(db, options?)搬进去 ledger_accounts (见 升级(中文(简体) )
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 用于软件包结构、变化、验证、, 和贡献者的指导.

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

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

版本与发布记录

@happyvertical/smrt-ledgers 共发布 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-ledgers 的常见问题

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