@ 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 }) | unreviewed | reviewed |
reject({ reviewerProfileId, reason }) | unreviewed, (中文(简体) ), reviewed | rejected |
markDuplicate({ reviewerProfileId, duplicateOfId }) | unreviewed, (中文(简体) ), reviewed | rejected + 重复标记 |
reopen({ reviewerProfileId }) | reviewed, (中文(简体) ), rejected | unreviewed |
写入 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 = actual | a 一个 Expense |
FinancialCost.kind = commitment | 商业 PurchaseOrder (单位:千美元)Contract),与 ContractLineItem 线条 |
FinancialCost.kind = labour | @happyvertical/smrt-timesheets (# 3288),不是费用 |
FinancialCost.kind = allowance | 超出范围:计划数额是预算记录,不是已发生的费用 |
FinancialCost.currency, (中文(简体) ), amount (单位) | currency, (中文(简体) ), amount |
FinancialCost.reviewStatus | reviewStatus + 键 reviewedByProfileId, (中文(简体) ), reviewedAt, (中文(简体) ), reviewNote |
FinancialCost 重复审查标记 | markDuplicate() → duplicateOfId, (中文(简体) ), rejected |
FinancialCost.matchedCommitmentId | commitmentId (+ 可选) commitmentLineId(中文(简体) ) |
| domacraft.com#143 供应商/工人/工作包 | vendorId 编号 : paidByProfileId 编号 : costObjectType + 键 costObjectId |
FinancialCostAsset (成本,资产) | ExpenseReceipt (单位:千美元)expenseId, (中文(简体) ), assetId(中文(简体) ) |
FinancialCostAsset 上传器、文件名、缩写、字节、, contentSha256 | uploadedByProfileId, (中文(简体) ), filename, (中文(简体) ), mimeType, (中文(简体) ), byteCount, (中文(简体) ), contentSha256 |
FinancialCostAsset 唯一租户+成本+散列 | 独有索引 (expense_id, content_sha256) ——费用固定租户,同时也持有NULL租户行 |
团队合作 JobExpense.job | costObjectType + 键 costObjectId |
JobExpense.category | category (单位:千美元)material, (中文(简体) ), consumable, (中文(简体) ), outside-service, (中文(简体) ), freight, (中文(简体) ), other, (...) (中文(简体) ) |
JobExpense.description | description |
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 仍然有效.