@happyvertical/smrt-sales (欢快的倒数)
S-m-r-t供应商中立销售业务:协议执行、客户关系管理、转介 接收和归属、中立的佣金核心和可重复使用的斯维尔特 表面 。 它是一个可安装的软件包,有子路径 保持消费者范围 切入它们使用的模块.
@happyvertical/smrt-affiliates 是一个被扭曲的相容性 shim
佣金模块。 新应用程序应该直接导入此软件包 .
安装
pnpm add @happyvertical/smrt-sales
添加 svelte 当消耗可选的 UI 导出时.
模块
| 入境点 | 责任 |
|---|---|
@happyvertical/smrt-sales/agreements | 商业术语版本、经核实的电子签名执行和不可改变的证据 |
@happyvertical/smrt-sales/crm | 铅、管道、机会、活动、转换 |
@happyvertical/smrt-sales/referrals | 参照人、链接、归属、资格、协议 |
@happyvertical/smrt-sales/commissions | 收入者、计划、收入活动、佣金、报酬 |
@happyvertical/smrt-sales/svelte | 客户关系管理、裁判、委托和操作员表面 |
根导出后再导出所有 TypeScript 模块以方便.
快速启动:委托条件
import {
CommissionPlanCollection,
EarnerCollection,
} from '@happyvertical/smrt-sales/commissions';
const db = 'sales.db';
const earners = await EarnerCollection.create({ db });
const plans = await CommissionPlanCollection.create({ db });
const earner = await earners.create({
tenantId: 'tenant-1',
profileId: 'profile-42',
displayName: 'North Region Partner',
status: 'active',
currency: 'CAD',
});
const plan = await plans.create({
tenantId: 'tenant-1',
planKey: 'referral-standard',
name: 'Standard referral plan',
currency: 'CAD',
});
plan.setComponents([
{
key: 'collected-revenue',
trigger: 'collected_revenue',
basis: 'gross',
rate: 0.1,
recurrence: { kind: 'one_time' },
},
]);
plan.activate();
await plan.save();
console.log(earner.id, plan.getComponents());
所有钱田都使用整数分. 使用率和概率等值
小数从 0 改为 1; 四舍五入是通过出口货币帮助者进行的.
瀑布计划
二版计划可以执行 steps,一个 effectiveTo 边界和 a
remainderSink。 。 。 . calculateWaterfall() 纯粹的通用分配服务:
主机注册收件人解析器,然后将返回的跟踪作为
重放证据. 步键必须是非空字符串; 已存在错误的键
在分配或启动之前被拒绝。 重放快照复制收件人
和汇值,包括嵌入式元数据,所以以后调用-输入突变
无法更改返回的证据。 追踪冻结了已解析的接收者、输入事实和
页:1 所有数额均为整数小单位;每个百分比
半个回合从零开始 接收者加上水槽总等于毛.
离职时已经结清的申请费模式仅作为冲抵 所配置的收款人应付款分配。 从来没有像第二次一样发射 拨款或应付款项。 偏移匹配使用整个收件人描述符, 包括嵌入式元数据;对象密钥顺序不会改变身份。 服务 不启动付款或转账.
转介资格和委托桥仍然是以组成部分为基础的。 两者
资格和重新明确资格 拒绝通过
unsupported_plan_engine,在撰写快照或更改推荐之前.
这适用于固定的计划和最新的积极计划修正案。 已冻结
v1快照继续支配收入. 恢复、激活和绑定兼容性
组件术语,然后重试资格; 使用 calculateWaterfall() 直接
用于v2分配。 切换计划密钥引擎不会迁移转介.
集合收件人
一个步骤可以由一组成员分享其数额,按衡量标准加权
例如交付、公布物品或发送转介。 步骤
recipient 与其它收件人一样命名池并解析; 主机
确定谁属于该组织,每个成员贡献多少:
import {
calculateWaterfallWithPools,
WaterfallRecipientResolverRegistry,
} from '@happyvertical/smrt-sales/commissions';
const resolver = new WaterfallRecipientResolverRegistry();
resolver.register('treasury', () => ({ kind: 'treasury', id: 'valley-coop' }));
resolver.register('grower_pool', (d) => ({ kind: 'grower_pool', id: d.id ?? 'all' }));
const { trace } = await calculateWaterfallWithPools(
{
planKey: 'valley-coop-wholesale',
version: 1,
currency: 'USD',
steps: [
{ key: 'treasury', base: 'gross', amount: { kind: 'percent', rate: 0.1 },
recipient: { kind: 'treasury' } },
{ key: 'growers', base: 'previous_remainder', amount: { kind: 'percent', rate: 1 },
recipient: { kind: 'grower_pool', id: '2026-season' },
pool: { metric: 'kg_delivered' } },
],
remainderSink: { kind: 'treasury' },
},
{ grossAmountCents: 10_000, currency: 'USD' },
{
resolver,
poolMembers: async (pool) => loadGrowers(pool.id),
metricProvider: { getMetricValues: async (req) => loadKgDelivered(req) },
metricPeriod: { start: '2026-09-01', end: '2026-10-01' },
},
);
奥米 metric 平等份额。 重量是非负整数,而且
供货商离开时的重量为零。 股份是精确整数小于
单位。 无法分割的分钱默认会转到所剩的汇.
与 residual: 'largest_remainder'一次一个去最大的
分数余相. 绑在更大的重量,然后是会员 kind
财务报告和审定财务报表 id 秩序。 秩序。 空池去入水槽. 游泳池的重量也一样
全部为0, 除非步骤设定 zeroWeight: 'equal'。微量冻结
成员,权重,和度量期, 所以重播与 frozenInputs 永远
再次给供应商打电话。 一张快照也必须符合步骤的宣布
metric重放时信任它收到的被冻结的输入,所以把它们存放在
它们不能被编辑,例如不可变的计算跟踪
在此无法检测到编辑到存储的证据 . calculateWaterfall()
保持同步; 通过
pools 从 prepareWaterfallPools() 当你需要两个阶段分开.
组织和财政工作者
Earner.kind 实值 person (默认), organisation,或 treasury。 。 。 .
组织和财政工作者不需要个人简介。 付款方法
包含 stripe_connect 财务报告和审定财务报表 crypto· ; setPayoutDestination() 存储
连接账户 id 或公众接收地址, 以及活跃的挣取者
使用两种方法都必须有一个。 包裹记录了钱应该放在哪里
永远不要叫支付供应商.
CommissionPayoutService.createPayoutBatch() 抓取在
CommissionPayout.payoutDestination。执行者和批准屏幕必须读取
payout.getPayoutDestination() 从批量,永远不要目前的Earner.
批量的方法和目的地从第一次节省开始是不可改变的,包括:
等待批次和失败批次重置以重试。 收入偏好的变化,
一流的重播 和中断的会员维修 从来没有刷新路线.
拒绝批次通过 transitionPayoutForSource 并创建新批次,其中
一个新的一能键,用于使用另一个目的地。 这还保留了路线
(b) 此处没有要求付款提供者.
在采用新字段之前, 运行正常的直列迁移 。 现有 条纹连接/crypto批次没有记录的描述符仍然可以读取, 但不能批准或提前支付。 拒绝和再创造这些产品; 永远不要回填一个历史路线 从今天的Earner。 继续采用人工方法 以使用空描述符。 未知/变形描述符和额外字段 (包括全权证书在内)被拒绝.
核心模式
- 角色与金钱是分开的.
SalesRepresentative财务报告和审定财务报表Referrer为: 两者都指向一个中立Earner支付身份. - 术语为版本行. 启动的委员会计划、归属 政策、转介协议和转介协议都经过了新版本的修订.
- 证据不可改变. 收入活动、执行协议、转介 触摸,调整则仅由附件进行,或在激活后加以保护.
- 复问已明. 稳定的去dupe/低能键防止重复 收入,点击,调整,协议,支付业务.
- 写作需要时使用服务. 付款过渡、调整、, 协议执行,归属具有服务自有的未变体 无法绕过 CRUD .
推荐提名
登记已知的别名 ReferrerIdentifierCollection.register()。东道主
可以在录入时使用 ReferralNominationResolver
并随后根据转介方案的积极政策解决. 模棱两可
或未知的提名将打开操作员审查,其中包含原始输入和
政策版本。 运行正常显示的迁移以添加
referrer_identifiers。见 转诊行为 用于匹配
规则 重放 租户的界限.
铅摄入量和生命周期
LeadWorkflowService 是租户安全、可应用的通用接缝
录取、跟踪、资格、舞台移动和机会关闭。 在主机数据库内构造它
活动 withTenant() 上下文; 主机用品授权、演员/简介
ids),和取景-模型映射.
import { LeadWorkflowService } from '@happyvertical/smrt-sales/crm';
const workflow = await LeadWorkflowService.create({ db });
await workflow.startWorking({ leadId, actorProfileId });
await workflow.scheduleNextAction({
leadId,
actorProfileId,
summary: 'Call after product review',
dueAt: new Date('2026-10-01T16:00:00Z'),
});
该服务在解剖学上记录任务和状态审计事件,人
完成单调任务.
createLead() 需要名称和电子邮件或电话,将电子邮件规范化,支持
可选主机授权 profileId,并支持
活性铅分解和调用人提供的一能键。 终端复制
由主办方明确解决. qualifyLead() 代表团
LeadCollection.qualify() 并返回链接的机会.
moveOpportunityToStage() 原子移动打开机会
非终端同管相; 精确的复试不增加审计. closeOpportunity()
选择管道的胜/败阶段,并选择记录胜的转换
链接。 CRM从未创造出下游目标. 钱仍然是整数美分通过
expectedValueCents; 演员属性使用 actorProfileId。 。 。 .
LeadCollection.listInbox() 提供租户范围过滤、分类、计数,
并标出批量所有者/下一步动作. getLeadWorkState() 包含
联系的机会。 复制的合并遗迹,由
LeadCollection.mergeLeads()。 。 。 .
LeadCreateForm, (中文(简体) ), LeadList,以及 LeadDetail 从 /svelte 接收视图数据
召回电话。 主机控制收件箱过滤器和页码,重复决定,
路线、授权和援引服务。 组件从不获取数据 .
见 客户关系管理合同 用于重试和重复语义
斯维尔特合同 用于组件表面.
协议边界
Agreement 是一个反方不可知的、有效的术语记录。 缔约方
命令 { kind, id } 描述者,消费者可以使用租户,挣取者,
简介、组织、工人或他们自己的中性类型,而不进口
消费领域. 版本为行: createAmendment() 创建草稿
activateAmendment() 在继任者的开始时关闭前身。 有效
间隔为半开( x)[effectiveFrom, effectiveTo)),以及 activeFor() 实值
as-as-查询:它可以返回一个被取代或终止的版本
提供记录日期,从未从今天的状况中推断出条件。 含蓄
重叠间隔无法关闭 。 活动拒绝日期倒数或超时
修正案将重复现有历史。 结束一个草稿取消它而不
(b) 无法重新开放闭合间隔。 党JSON是神通化的
因此财产令不会改变协议的身份.
在没有租户的情况下,每个要求的日期的房客查询情况都回到全球范围
版本规范该日期。 租户必须明确创建其初始版本
; 全球术语从未被隐含地复制成
租户修正. 计算钱的打电话者必须快照
返回的版本在其权威事件上; 此模式未结算
或分配资金.
协议模块的执行部分接受中性提供者
@happyvertical/signatures 合同加一项 AssetRuntimeLike提供方
证书保留在被注入的SDK适配器和秘密商店. 已执行
协议冻结确切的来源、已签署的文件、审计线索、散列物和
签名人证据; 修改后创建新记录.
租赁和交叉包装参考
大多数商业模式都是可选的租户 如此有意的全球范围 操作行仍然是可能的。 执行证据和私人行动围栏 需要的租户记录。 概况、发票和资产参考使用情况 跨包字符串引用,而不是循环运行时间依赖.
从附属机构的移徙
见 smrt-affiliates 及其移徙指南
遗留映射 : Partner 变成 Earner,以及 Payout 变成
CommissionPayout。兼容软件包没有重复的模型或
图表.
发展
pnpm --filter @happyvertical/smrt-sales test
pnpm --filter @happyvertical/smrt-sales typecheck
pnpm --filter @happyvertical/smrt-sales test:postgres
pnpm --filter @happyvertical/smrt-sales build
见 AGENTS.md 寿命周期、证据、货币和付款
变化无常.
通过 activateAmendment 可通过
withdrawAmendment(id) 仅仅在它开始之前,而它仍然活跃。 这个
交易取消永远无效的后继者,并恢复其确切的持久性
前端(包括有限度的结束);它从不推断一个无限制的间隔.
一再地,迟到地,或相互冲突的撤退失败而不会改变历史. 直接
模式终止仍然是已经有效的条件。 仅适用于全局默认值
- 终止、终止和以后的空白
而不是悄悄地恢复全球收费.
恢复出处完全通过修正激活书写 创建和保存无法提供或编辑。 双方继续推进撤离 修订符号, 因此预退出模型实例不能覆盖结果 .
初步协议产生严格插入的使用:同时调用相同的 租户、类型、政党和版本不能取代获胜的行或其条件. 丢失的创建失败; 加载已存在的版本或创建修正.
同时 createAmendment 在自有区域内调用序列化版本分配
道:PostgreSQL锁定最古老的坚持版本并重读最新版本;
嵌入式引擎使用核心的交易/写入队列. 每一次成功的通话都保持
它自己的条款和版本。 直接 supersede() 需要限制 effectiveTo
; 保存一个无限制的已替换行被拒绝.
管理下的销售额可从 /crm数字 : SalesGovernanceService 授权
销售者,专为租赁冠名广告商,冻结引文修订和
需要准确的制造商/检查商折扣批准。 东道主提供目前的成员资格,
暂停、库存和销售/财务政策。 见
受管销售一体化合同
用于交易执行人所有权、迁移和提供者签名边界.
Svelte 导出包括 SellerGovernancePanel 及其观点/行动合同.
治理目前接受自有 PostgreSQL 连接配置 只有这个 其他适配器在连接创建前失败. 第4264号完整问题仍然存在 已封锁 SDK DuckDB 连接能见度 # 1452。 。 。 .
SQLite 治理在打开前也被拒绝,因为同一进程恢复 来自 BUSY 的无效性在此工作流程中未被证明 。 上一个 SQLite 行为测试是调查证据,不是支持运行时间的说法. 跟踪后续验证 -m -r -t #4269号。 。 。 .