@happyvertical/smrt-sales

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

SMRT框架的模块销售:协议执行、客户关系管理、查询接收、中性佣金和可重复使用的斯维尔特表面

中文使用文档
文档目录13 节
  1. 安装
  2. 模块
  3. 快速启动:委托条件
  4. 瀑布计划
  5. 集合收件人
  6. 组织和财政工作者
  7. 核心模式
  8. 推荐提名
  9. 铅摄入量和生命周期
  10. 协议边界
  11. 租赁和交叉包装参考
  12. 从附属机构的移徙
  13. 发展

@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号。 。 。 .

版本与发布记录

@happyvertical/smrt-sales 共发布 292 个版本,首次发布于 2026/07/11;过去 12 个月发布了 292 个版本。

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

@happyvertical/smrt-sales 是什么?

SMRT框架的模块销售:协议执行、客户关系管理、查询接收、中性佣金和可重复使用的斯维尔特表面

如何安装 @happyvertical/smrt-sales?

在项目目录运行 npm install @happyvertical/smrt-sales,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:svelte(^5.57.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@happyvertical/smrt-sales 支持 TypeScript 吗?

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

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

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

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

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

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

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

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

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