Skip to main content

DMS, Partners & Loyalty

Channel partners (the notes' "vendor"), their targets/schemes/ledgers, and the loyalty/affiliate engine. Operational data in Mongo; financial ledgers in Postgres.

ChannelPartner (Mongo)​

ChannelPartner {
_id: uuid
code: string // short ID
tenantId: string
name: string
tier: 'distributor'|'dealer'|'retailer'|'installer'
parentId?: string // upstream partner (hierarchy)
territory: { regions: string[]; pincodes?: string[] }
kyc: { gstin?: string; pan?: string; docs: string[]; status: 'pending'|'verified'|'rejected' }
contacts: Array<{ name: string; phone: string; role: string }>
creditLimit?: number // policy; balance lives in PG ledger
status: 'active'|'suspended'
assignedManagerIds: string[] // for data-scoping
}

Target & Scheme (Mongo)​

SalesTarget {
_id: uuid
partnerId: string
period: { from: Date; to: Date }
metric: 'revenue'|'units'|'category'
targetValue: number
achievedValue: number // updated from secondary_sale.recorded / order.placed
incentive?: { type: 'slab'|'flat'; rules: any }
}

Scheme {
_id: uuid
name: string
appliesTo: { tiers: string[]; regions?: string[] }
period: { from: Date; to: Date }
benefit: { type: 'discount'|'bonus'|'points'; rules: any } // offers/bonuses (notes)
status: 'draft'|'published'|'expired'
}

BeatPlan { // sales-rep field plan
_id: uuid
salesRepId: string
visits: Array<{ partnerId: string; plannedFor: Date; doneAt?: Date; geo?: {lat:number;lng:number} }>
}

DealerLedger (Postgres — financial truth)​

// PG schema owned by Finance domain
DealerLedger {
id: uuid
partnerId: string // ref to ChannelPartner
entries: LedgerEntry[] // append-only
balance: numeric
}
LedgerEntry {
id: uuid
at: timestamp
type: 'invoice'|'payment'|'credit_note'|'debit_note'|'scheme_credit'|'payout'
amount: numeric
ref: string // order/invoice/payout id
}

Loyalty (Mongo)​

PointsLedger {
_id: uuid
ownerType: 'customer'|'dealer'|'installer'|'electrician'
ownerId: string
entries: Array<{ at: Date; type: 'accrue'|'redeem'|'expire'|'bonus'; points: number; ref?: string }>
balance: number
tier?: string // scales with cumulative purchase
}

AffiliateLink {
_id: uuid
code: string
ownerId: string
clicks: number
conversions: Array<{ orderId: string; value: number; commission: number; at: Date }>
status: 'active'|'disabled'
}

Loyalty points are not money. They are an operational liability tracked in Mongo. Actual payouts/commissions (affiliate, scheme cash) post to the PG ledger via Finance.

Loyalty earn scaling (notes #11)​

// earn rate increases with cumulative spend → higher tier → higher multiplier
earnRate(tier) => base * tierMultiplier(tier)

Tiers + multipliers are tenant-config.

Scoping​

Every DMS read is scope-filtered by assignedManagerIds / territory.regions per RBAC.

Cross-store rules​

  • order.placed / secondary_sale.recorded → update SalesTarget.achievedValue + accrue points (pending until payment.captured).
  • Financial movements → PG ledger, never Mongo.