@happyvertical/smrt-expenses

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

SMRT框架的费用记录 -- -- 对照一个费用对象审查费用、重复的收据和承付款提用

中文使用文档
文档目录16 节
  1. 安装
  2. 司马
  3. 使用量
  4. 审查
  5. 收到和复制
  6. 货币和货币
  7. 偿还
  8. 消费者控制
  9. 消费模式绘图
  10. 测试
  11. 另见
  12. 支出和收款
  13. 可选供应商财务事实
  14. 退还现金收款人和偿还职位
  15. 供应商保留和应付款证据
  16. 审查支出分配

@ happyvertical/ smrt- 费用

S-m-r-t框架的开销记录:某人发生的费用,记入a 工作、工作包或项目,有证明的收据,明确 审查、偿还记录和削减定购单承付款.

  • 支出 ——多形态成本对象,类别,以整数为小数 以货币计的单位,发生日期与记录时间(记录时间) (公司、有名人或有名第三方) 销售商和承诺,以及审查状态.
  • 支出收取 ——支出 . . Asset 加入上传器, 文件名、 MIME 类型、 字节数和 contentSha256。同一文件两次打开 拒绝支付1项费用;关于2项费用的同一档案报告为: 人看着.
  • 承诺缩编 ——经审查的实数减少目前尚未解决的问题 商业 PurchaseOrder (或其中一行),各一一一一一.

范围以外:收货OCR或解析、向会计提供商寄出,以及 劳动力(参见 @happyvertical/smrt-timesheets, 第3288页.

安装

pnpm add @happyvertical/smrt-expenses

取决于 @happyvertical/smrt-commerce (票据、承诺)和 @happyvertical/smrt-assets (收到文件). 配置文件以 id 为参考 (单位:千美元)@happyvertical/smrt-profiles:Profile)没有硬依赖.

司马

表格由迁移而来,从不运行:

smrt db:migrate          # creates expenses and expense_receipts
smrt db:status --parity  # verifies the live schema matches

使用量

import {
  ExpenseCollection,
  ExpenseReceiptCollection,
  computeContentSha256,
} from '@happyvertical/smrt-expenses';
import { withTenant } from '@happyvertical/smrt-tenancy';

await withTenant({ tenantId }, async () => {
  const expenses = await ExpenseCollection.create({ db });
  const expense = await expenses.create({
    costObjectType: '@happyvertical/smrt-projects:Project',
    costObjectId: project.id,
    category: 'material',
    description: 'Framing lumber',
    amount: 100000, // $1,000.00 — integer minor units
    currency: 'USD',
    incurredOn: '2026-09-15',
    recordedByProfileId: recorder.id,
    commitmentId: purchaseOrder.id, // optional; must share the currency
  });
  await expense.save();

  // Receipt: the hash is what makes duplicates detectable.
  const receipts = await ExpenseReceiptCollection.create({ db });
  await receipts.attachReceipt({
    expenseId: expense.id,
    assetId: asset.id,
    contentSha256: computeContentSha256(fileBytes),
    byteCount: fileBytes.byteLength,
    uploadedByProfileId: recorder.id,
  });

  // Review is its own action — gate it in your route (e.g. `expenses.review`).
  await expense.review({ reviewerProfileId: manager.id });

  const position = await expenses.commitmentPosition(purchaseOrder.id);
  // A 4,600.00 award with 1,000.00 reviewed: { drawn: 100000, open: 360000 }
});

审查

每笔开支都开始 unreviewed。只有这些方法才能移动它:

方法从改为:
review({ reviewerProfileId })unreviewedreviewed
reject({ reviewerProfileId, reason })unreviewed, (中文(简体) ), reviewedrejected
markDuplicate({ reviewerProfileId, duplicateOfId })unreviewed, (中文(简体) ), reviewedrejected + 重复标记
reopen({ reviewerProfileId })reviewed, (中文(简体) ), rejectedunreviewed

写入 reviewStatus (或审查者、时间、说明或重复标记) 直接和保存被拒绝。 经审查的费用数额、货币、日期、, 费用对象、供应商、承付款和付款人被冻结,直至 reopen()。 。 。 . 附上收据并记录报销情况,不会改变审查状态.

收到和复制

// Same file, same expense → DuplicateReceiptError (code EXPENSE_RECEIPT_DUPLICATE)
// Same file, different expenses → allowed, and listed here:
const groups = await receipts.findDuplicateReceipts();
// [{ contentSha256, expenseIds: [a, b], receipts: [...] }]

货币和货币

数量为整数小单位($19.99 实值 1999) (中文(简体) ). 总数按货币计算 并且从未用货币进行总和:

await expenses.totalsByCurrency({ where: { costObjectId: job.id } });
// { USD: { amount: 125000, count: 3 }, CAD: { amount: 4000, count: 1 } }

与承诺相匹配的支出必须使用承诺的货币;a 保存时拒绝不匹配 .

偿还

费用 paidBy: 'person' 与 paidByProfileId 也许 reimbursable (退缩了). markReimbursed({ at, reference }) 记录回报。 支付 这是工资单或应付工资的工作(# 3292).

消费者控制

  • 封闭产生的表面. 没有生成 CRUD, 读取, MCP 或 CLI 操作达到成本数据(生成的读取不读权限). 列表 费用通过您本人许可的路线支付.

  • 生成了写动作 (# 4001). ExpenseCollection 出版四册 由服务支持的REST行动, 每一个行动都由它的 expenses.<action> 租户和演员简介 副主席:

    路线体质
    POST /expenses/record支出领域(amount 小型单位, currency, (中文(简体) ), incurredOn,成本对象,支付者,.)
    POST /expenses/attachReceipt{ expenseId, assetId, contentSha256, filename?, mimeType?, byteCount? }
    POST /expenses/recordReview{ expenseId, decision: 'approve' | 'reject', note?, reason? }
    POST /expenses/recordReimbursement{ expenseId, reference? }

    recordReview 财务报告和审定财务报表 recordReimbursement 拒绝超市绕行。 演员 支付他人费用 expenses.recordReview。记录 费用为 unreviewed (等待审查);没有单独提交.

  • 必要的租赁. 租房在默认情况下是可选的,如smrt-commerce. 要求每次阅读和写作都要有租户背景:

    import { registerTenantScopedClass } from '@happyvertical/smrt-tenancy';
    
    registerTenantScopedClass('@happyvertical/smrt-expenses:Expense', { mode: 'required' });
    registerTenantScopedClass('@happyvertical/smrt-expenses:ExpenseReceipt', { mode: 'required' });
    

消费模式绘图

捐助方领域费用
domacraft.com (英语) FinancialCost.kind = actuala 一个 Expense
FinancialCost.kind = commitment商业 PurchaseOrder (单位:千美元)Contract),与 ContractLineItem 线条
FinancialCost.kind = labour@happyvertical/smrt-timesheets (# 3288),不是费用
FinancialCost.kind = allowance超出范围:计划数额是预算记录,不是已发生的费用
FinancialCost.currency, (中文(简体) ), amount (单位)currency, (中文(简体) ), amount
FinancialCost.reviewStatusreviewStatus + 键 reviewedByProfileId, (中文(简体) ), reviewedAt, (中文(简体) ), reviewNote
FinancialCost 重复审查标记markDuplicate() → duplicateOfId, (中文(简体) ), rejected
FinancialCost.matchedCommitmentIdcommitmentId (+ 可选) commitmentLineId(中文(简体) )
domacraft.com#143 供应商/工人/工作包vendorId 编号 : paidByProfileId 编号 : costObjectType + 键 costObjectId
FinancialCostAsset (成本,资产)ExpenseReceipt (单位:千美元)expenseId, (中文(简体) ), assetId(中文(简体) )
FinancialCostAsset 上传器、文件名、缩写、字节、, contentSha256uploadedByProfileId, (中文(简体) ), filename, (中文(简体) ), mimeType, (中文(简体) ), byteCount, (中文(简体) ), contentSha256
FinancialCostAsset 唯一租户+成本+散列独有索引 (expense_id, content_sha256) ——费用固定租户,同时也持有NULL租户行
团队合作 JobExpense.jobcostObjectType + 键 costObjectId
JobExpense.categorycategory (单位:千美元)material, (中文(简体) ), consumable, (中文(简体) ), outside-service, (中文(简体) ), freight, (中文(简体) ), other, (...) (中文(简体) )
JobExpense.descriptiondescription
JobExpense.amount (百分数)amount + 键 currency (设置明确)
JobExpense 发生日期incurredOn (单位:千美元)YYYY-MM-DD; 进入时间为 recordedAt
JobExpense 登录recordedByProfileId

导入行开始 unreviewed;通过 review() 编号 : reject() 编号 : markDuplicate() 因此,过渡规则适用.

测试

pnpm --filter @happyvertical/smrt-expenses test           # SQLite + UI SSR
pnpm --filter @happyvertical/smrt-expenses test:postgres  # PostgreSQL lane
pnpm --filter @happyvertical/smrt-expenses test:e2e       # Native browser forms

另见

支出和收款

ExpenseForm 财务报告和审定财务报表 ExpenseReviewPanel 从 @happyvertical/smrt-expenses/svelte 提供本地采购条目、呼叫者驱动的重复/更正审查 资产收据构成. ExpenseForm 使用共享本地化货币 选择器同时保留本地字段名称并拒绝原始草稿。 见 a. 投资单位合同 用于公共道具、选择器限制, 本地有效载荷、保留错误和服务器责任.

Svelte出口也提供 ExpenseList 费用目标 预测, ExpenseReceiptCapture 用于本地文件上传或共享相机 抓获,和 ExpenseReviewQueue 当地批准/拒绝保留 说明理由. ExpenseForm 包含一个可选量键盘和可编辑 成本-对象参考。 见 a. 投资单位合同 为公众服务 道具,请求身份,无JavaScript行为和服务器责任.

可选供应商财务事实

现有支出仅保留其入账数额: getFinancialBreakdown() 财务报告和审定财务报表 getCostBasis() 返回时 null 直到一个召唤者提供明确的事实。 一个 空税阵列主张不征税;没有事实就绝不意味着免税待遇.

setFinancialBreakdown({ currency, subtotal, taxes, total }) 接受整数 小型单位。 每一税收部分 { code, amount, recoverableAmount }页:1 唯一的小写 kebab 案例代码是调用器定义及其可收回部分 明确,包括零。 小计加税收必须完全等于两个总额 财务报告和审定财务报表 Expense.amount输入 Expense.currency组件共享总计的标志, 回收不能超过征收的税款,所有价值必须是安全的整数. 未知的字段和畸形持续JSON故障关闭. 这个 financialBreakdown 文本列存储这些事实; 使用帮助而不是编辑 JSON.

getCostBasis() 返回时 { currency, subtotal, taxTotal, recoverableTax, nonRecoverableTax, total, costBasis }成本基数等于小计加 不可收回税(等同总额减去可收回税),无四舍五入. 例如,小计1 000、税收1 000和可收回的税收400收益基础10600. 这是一个购买成本的事实,而不是客户加价或销售税的决定. 来电者会选择他们的税收待遇;该套件提供不默认管辖权.

paidBy: 'third-party' 需求 paidByName它排除了 paidByProfileId 财务报告和审定财务报表 reimbursable公司和个人的行为没有改变。 无偿还费用 或从指定的付款人推断结算.

负数 refundOfId,命名为正非退款支出 以同一房客和货币显示。 退款细目构成部分为负数 (或为零),包括收回的税款。 自我 失踪 外国所有者 货币交易, 并且退款来源未能结清。 来源查询使用呼叫者的数据库 执行者。 每一持续关联的退款准备金的现金能力毛额,包括 未审查或拒绝行。 累计退款不得超过来源毛额. 已知的财务逆转额外不能超过源小计或任何 准确来源税码组件的收取、可收回或不可收回金额; 组件无法相互补偿。 源码和退款编辑器重新验证 未来位置 已知的关联事实是无法澄清的。 此记录 逆转,而不是结算分配,客户信用授权,或应享权利.

await expenses.refundPosition(sourceId) (另见: source.getRefundPosition()(中文(简体) ) 返回正数 sourceAmount, (中文(简体) ), refundedAmount,以及 remainingAmount附加时 全部 refundIds。 。 financialPosition 包含原始细目,已签名 负累积数 refunded 和正/零 remaining 崩溃。 如果来源事实或任何退款事实不明,则无效 绝不意味着零税或完成倒置。 关于未知遗产的已知退款 来源仍然有效,以已知毛额为限。 当源的事实存在时,所有已知 即使另一退款的事实不明,退款部分仍受约束. 读取时保留了来电交易和租户边界. 来源毛额 保存:记录退款从未覆盖它.

费用节省验证并持续进行一项交易,包括窝点呼叫器 交易。 在 PostgreSQL 上, 源编辑和退款写入命令获取 在确认关系前 锁定开支和拟议来源, 通过书面和承付保持来源/退款核对的有效性。 SQLite 用途 框架的序列式写入交易。 现有的每行修订版 检查仍然拒绝 stale 对象写入; 额外保护关系 要求这些锁和以下来源修订索赔。 呼叫者不得同时重复使用同一可变设备 模式实例,而它暂时带有交易约束。 直接 SQL 写入 这些模式层面的保障不在此列.

将退款联系起来,改变来源,或编辑其金额/财务事实,声称来源修订 同一交易通过 claimRevision(source.updated_at)。这使得 在旧的 PostgreSQL 下编辑源代码 REPEATABLE READ 抓取失败 序列化错误,而不是缺少新的退款。 后装入源 在编辑/审查前链接退款; 在序列化失败时重试 包含新实例的整个呼叫者交易。 外部交易失败 退回退款 和源修订索赔。 保存不更改 与能力有关的领域不会推进源修订.

财务细目、第三方付款人姓名和退款来源加入 现有审查资金锁。 保存 reopen() 首先,纠正事实和审查 ; 纠正不能与重新开放的行动同时进行。 新栏为 通过 smrt db:migrate留下的遗产没有被捏造的事实. SQLite 和 PostgreSQL 套接字执行前作的升级 请检查date=中的日期值 (帮助).

退还现金收款人和偿还职位

退款可选 refundRecipient 由JSON守卫,读取/写入 getRefundRecipient() 编号 : setRefundRecipient({ kind: 'company' }) 或者说 setRefundRecipient({ kind: 'person', profileId }) 或者说 setRefundRecipient({ kind: 'third-party', name })。第三方名称是准确的 保留源证据(非空白,最多200个字符),不独立 核实的当事人/客户身份。 它从来没有修剪,模糊的匹配或解决 由这个API给另一个政党。 上面写着到底是谁 现金的收到情况 paidBy。丢失的收件人未知; 历史付款人字段从未被重新解释为收款证据。 实地 只属于链接的负退款,并加入被审查的冻结款.

对于一个积极的、由个人支付的可偿还来源, await expenses.reimbursementPosition(sourceId) (或 source.getReimbursementPosition()报告原件 sourceAmount, (中文(简体) ), personRefundAmount, (中文(简体) ), companyRefundAmount,保留 reimbursedAmount, (中文(简体) ), remainingAmount单独 owedToCompany公司收到的退款没有 减少此人最初的现金总额索赔。 同一人退款也一样 一会儿 偿还后收到的退款产生欠公司的款项; 它永远不会成为负偿还或自动记录结算. 这些现金价值与经济价值相分离 getCostBasis()。 。 。 .

markReimbursed({ amount?, at?, reference? }) 仅记录全部已知的 其余索赔和保留准确 reimbursedAmount保留源性粗糙. 一个可选的预期 amount 必须准确匹配;拒绝部分付款. 现有付款不能重叠,其现金索赔/付款人仍然保留 已经修好了 直接保存无法伪造支付字段 。 现有无退款 拨打者可以像以前一样省略数额并记录全部原始毛额.

unknownReason 识别身份不明的收件人,另一个人的收件人, (b) 明确的第三方收据(unknown-third-party-recipient),或历史 偿还标记,不保留已付现金。 第三方的收据永远不会 计为公司/个人现金或解释为收入或结算。 未知 返回无负债/应收款,而不是推断为零或a 历史毛付款。 明确解决遗留证据;这种API供应 不自动转换遗产 。 记录不是转移执行 。 两个公开 位置读取和写入保存的呼叫器交易亲和和源锁; 退款- 收款人更改也推进源修订以拒绝 stale 可重复阅读的偿还决定.

供应商保留和应付款证据

Expense.recordSupplierPayable() 匹配的收集方法保留一个 原供货方债务与发生的款项分开,退税, 公司费用和雇员补偿。 原画 payableBasisMinor 实值 明确或 null;付款人或支出毛额均不意味着未偿还供应商债务. 原本举行/释放/解决的事件带有确切的来源身份,原作者, 日历日期和明确的同一天顺序。 未知的原作者无效, 从来没有一个编造的当前审查员。 当前记录器并导入 复审证据是独立的。 返回的事件对主机具有不可改变的UUID 横行相道. 记录证据不批准开支,执行付款, 创建日志或联系会计提供者.

const position = await expenses.recordSupplierPayable(expenseId, {
  requestId, currency: 'CAD', payableBasisMinor: null,
  source: { namespace: 'original-books', key: 'receipt-42', version: '1', author: 'Original bookkeeper' },
  recordedByProfileId: reviewerProfileId,
  evidenceRef: 'Reviewed original source export',
  events: [{
    kind: 'hold', amountMinor: 1000, effectiveOn: '2026-09-15', sequence: 0,
    evidenceRef: 'Original retained amount',
    source: { namespace: 'original-books', key: 'hold-7', version: '1', author: 'Original bookkeeper' },
  }],
});
// position.retainedMinor === 1000; position.remainingPayableMinor === null

completeSupplierPayableBasis() 可以完成一次原先未知的基础, 明确审查证据,同时保留原无名快照. recordSupplierPayableEvent() 附上日期搁置、释放、供应商结算 或退款解释。 准确 recordedRetainedMinor 在 retainedMinor 如果一个 链接的退款缺乏分配证据。 和解是已经支付款项的证据 不是银行指示 目前定居点需要已知的基础和 链接退款的明确解释。 释放只消耗保留的能力. 现任呼叫员仍负责主机权限和审查员身份; 这些方法不产生REST/MCP/CLI行动.

连带负支出无法确定供应商债务减少多少 或者有多少现金被退回。 明确 refund 因此,事件名称 refundExpenseId, (中文(简体) ), payableReductionMinor, (中文(简体) ), retainedReductionMinor,以及 cashReturnedMinor,各以自有源/容量为界。 留存减少额 不得超过应付减少额。 未知的退款解释使应付款 位置不明并禁止新的和解或释放;从未变成零或 推断的分配。 支出退款毛额/构成部分上限继续适用.

每个时间顺序前缀保留和支付能力:义务是 基数减去应分明的扣减额;支付净额为结算额减去现金 返回; 保留被扣减释放和保留削减; 应付款 债务减去已支付和留存净额。 中间数额不得为负数. 原始未知基数只使用总开支作为上一级验证范围, 从未作为报告的应付金额。 源事件均在支出之前 以及同一天的活动需要独特的顺序. getSupplierPayablePosition({ asOfDate }) / 收藏 supplierPayablePosition 与原/现授权的完整来源关系. 它在原来的开销日期之前返回无效,而不是预测未来 将债务计入较早期间. 后来审查的完成基础是明确的追溯解释,而不是 证明原提交人在较早的日期知道这一数额.

命令与 Excess 交易、 源行锁定和 修订版 守护 共享 退款 精确重试返回保留ID; 更改的请求被拒绝 。 原文 源和当前完成/活动的证据不能被替换或删除; 管理下来源资金/付款人/契约和链接的退款事实不能编辑 在位置周围。 调用回滚既包括证据,也包括源修正. 没有供应商支付权的开支保持其现有行为.

审查支出分配

经审查的原件可通过不可改变、完全核对的部分归结 用于多个经核准的同一租户的费用物品,但不克隆其开支或 收据证据。 见 分配合同 现有行为者/目标权威、重审、更正、报告和 - 对开具的法案的保留草案。 现有的未分割支出 API 仍然有效.

版本与发布记录

@happyvertical/smrt-expenses 共发布 125 个版本,首次发布于 2026/10/15;过去 12 个月发布了 125 个版本。

版本发布日期距今
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-expenses 的常见问题

@happyvertical/smrt-expenses 是什么?

SMRT框架的费用记录 -- -- 对照一个费用对象审查费用、重复的收据和承付款提用

如何安装 @happyvertical/smrt-expenses?

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

@happyvertical/smrt-expenses 支持 TypeScript 吗?

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

@happyvertical/smrt-expenses 支持 ESM 还是 CommonJS?

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

@happyvertical/smrt-expenses 可以商用吗?

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

@happyvertical/smrt-expenses 的下载量有多少?

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

@happyvertical/smrt-expenses 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 125 个版本,其中过去 12 个月发布了 125 个;首次发布于 2026/10/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。