Subversion Repositories SmartDukaan

Last modification

• Rev 37729 2026-09-21 12:31:43
• Author: amit

• Log message:

  lead: one workable lead per mobile, with a 6-month supersede and an L2+ override
  
  There was no choke point for lead creation. Ten sites did `new Lead()` across four
  modules -- three in web's LeadController, two in V2FofoLeadController, three in fofo's
  LeadController, one in TrialServiceImpl and one in the cron LeadSyncRunner -- and only
  ONE of them (fofo /createLead) checked for an existing lead at all. Result on live data:
  5,137 mobiles carrying duplicate leads over 12,156 rows, worst case 29 on one number,
  and two agents unknowingly working the same shop.
  
  THE RULE, in new LeadCreationService, which all ten now route through:
  
  no active lead on the number -> create
  active, last activity >= 6 months -> retire the old one, create the new one, SILENTLY
  active, last activity < 6 months -> BLOCK; only an L2+ user may override
  
  Active = status in (pending, followUp) AND the assignee is still an active auth_user.
  Last activity = GREATEST(lead.updated/created, MAX(lead_activity.created)).
  
  The stale branch is deliberately quiet. A shop enquiring again after six months is a
  handover, not a clash, and mailing on it would train the desk to ignore the alert -- so
  only a genuine collision notifies. Live split: 195 stale against 1,241 fresh, and roughly
  three blocks a month.
  
  WHY "ACTIVE" ALSO MEANS A LIVE OWNER
  
  331 open leads are assigned to 11 DEACTIVATED accounts (157 to sm@smartdukaan.com alone,
  whose newest lead is from 2022). Counting them as active would block fresh enquiries
  behind an account nobody can log in to and therefore nobody can close. Requiring a live
  owner defuses all 331 without retiring a single row. Retirement here is only ever
  REACTIVE -- triggered by a new entry on the same number. Nothing runs on a schedule.
  
  ASSUMPTION worth flagging: a superseded lead becomes status=notInterested (stage DROPPED)
  with closure_timestamp and reason 'Superseded after 6 months inactivity', rather than a
  new `expired` status. "Closed" is an explicit allow-list in the UI --
  Arrays.asList(notInterested, finalized) at V2FofoLeadController:150 and fofo
  LeadController:313 -- and there are ~107 references to specific LeadStatus values, so a
  new enum value would make these leads vanish from BOTH the open and closed screens.
  Stage DROPPED keeps the nuance (the shop never said no) and still maps to notInterested
  via LeadStage.toLegacyStatus().
  
  OVERRIDE is L2+ in ANY team, not Call Center only: Sales L1 owns 1,063 of the 1,776 open
  leads, so a Call-Center-only gate would funnel every team's collisions through three
  people. The MAIL still goes to Call Center L2+, resolved from cs.position at send time
  rather than hardcoded. An override is a TAKEOVER -- it closes the existing lead -- because
  a second live lead is the exact thing the rule exists to prevent.
  
  UNATTENDED CALLERS (cron sync, CSV upload, trial registration, AI intake) have nobody to
  offer an override to, so they use createUnattended: skip the colliding row and mail the
  desk rather than throwing. CSV reports imported/duplicateSkipped/duplicateMobiles back to
  the operator instead of failing the whole file over one number.
  
  ALSO FIXES selectByMobileNumber, which called getSingleResult and therefore threw
  NonUniqueResultException on any mobile with more than one lead -- GlitchTip #99 and #1359,
  both still firing. It now prefers the open lead, then the most recently touched.
  
  NOT INCLUDED, deliberately: no DB unique constraint. 10 mobiles already carry more than
  one open lead and would have to be resolved by hand first, which conflicts with the
  no-auto-retirement rule. The service enforces the invariant going forward.
  
  NEEDS A DBA STEP: user.lead.mobile is unindexed on 37,580 rows, so this check is a full
  scan on every create. Index DDL is in the accompanying note; it has NOT been applied.