stages.py

07-Automation/partner_pipeline/stages.py

1. """Bitrix funnels and stage tokens: names, sends, terminal stages."""
3. from __future__ import annotations
5. # Stage names are keyed by stage token, never by display name: display names get
6. # renamed in Bitrix and the same label can mean different things in different funnels.
8. # The three funnels the census maps (reconcile-deals, route).
9. FUNNEL_KEYS = {"24": "partner_outreach", "26": "winback", "36": "quarterly_checkin"}
10. FUNNEL_DISPLAY = {"24": "Partner Tier Upgrade", "26": "Winback",
11. "36": "Quarterly Check-In"}
12. STAGE_NAMES = {
13. "24": {"UC_2YNXWE": "LinkedIn Research & Connection", "NEW": "Update Info Plinth",
14. "UC_6H9C8U": "TIER CHANGE EMAIL SENT", "UC_5DTN59": "Need Artwork/Mockup",
15. "PREPAYMENT_INVOIC": "Gift Mockup Sent", "EXECUTING": "No Reply Mockup",
16. "UC_PT8D2U": "Client Approved", "FINAL_INVOICE": "Gift Sent",
17. "UC_HWT78S": "Gift Delivered",
18. "UC_L2S2TK": "Potential Partners (PP) - HAZEL ONLY",
19. "UC_2EYUH4": "PP LinkedIn Connection - HAZEL ONLY",
20. "UC_2DE6NT": "PP Email Reachout Sent - HAZEL ONLY",
21. "UC_RCNECL": "Client Replied", "UC_N5U7JC": "Qtly Touch-Point Scheduled",
22. "WON": "Deal won", "LOSE": "Not Interested"},
23. "26": {"UC_JUUNES": "Client", "UC_L2JMHY": "Activated",
24. "NEW": "LinkedIn Research & Connection",
25. "PREPARATION": "First Email", "UC_K9M6LT": "No Reply 1st Email (Auto)",
26. "PREPAYMENT_INVOIC": "Follow-Up Email", "UC_D6LU8W": "No Reply 2nd Email (Auto)",
27. "EXECUTING": "LinkedIn DM", "FINAL_INVOICE": "Pre-Call Email",
28. "UC_BMQAKY": "Call Booked / Voicemail", "UC_EPG639": "Changed Companies",
29. "UC_YUE3NB": "Placed Order / Quote", "WON": "Winback Outreach Completed",
30. "LOSE": "No Reply from Customer"},
31. "36": {"NEW": "Active Check-In List", "UC_LXCMAV": "Dormant",
32. "PREPARATION": "LinkedIn Research & Connection",
33. "PREPAYMENT_INVOIC": "First Email Sent", "UC_X25FL3": "Call Booked",
34. "UC_7XQR9H": "No - Reply", "EXECUTING": "Second Email Sent",
35. "UC_32CNNC": "Email Defunct", "FINAL_INVOICE": "Changed Companies/Jobs",
36. "WON": "Quarterly Completed", "LOSE": "Never Replied", "1": "Not Interested"},
37. }
38. # Check a stage rename against live pipeline output before editing this table: a name
39. # recorded against the wrong token is written onto every census block in that stage
40. # at the next reconcile-deals run (C36:NEW is "Active Check-In List", C36:UC_LXCMAV is
41. # "Dormant"). A token missing here resolves to the raw token, with a warning.
43. # "Not Interested"-class closures are opt-outs: full email suppression, see DECISIONS.md.
44. OPTOUT_STAGES = {"Not Interested"}
47. # The outreach audit (Stage F5) covers the funnels that carry client outreach: the three
48. # the census maps plus Abandoned Carts. Order, production and fulfillment funnels are
49. # left out because customer email there is order handling, not outreach, and so are
50. # funnels that send email for other reasons (delivery follow-up, cold outreach): this
51. # is a client-outreach tracker, not an inventory of every funnel that sends email.
52. # The scope is a recorded decision (DECISIONS.md); change it there first.
53. AUDIT_FUNNELS = {
54. "24": "Partner Tier Upgrade",
55. "26": "Winback",
56. "36": "Quarterly Check-In Flow",
57. "16": "Abandoned Carts",
58. }
59. AUDIT_TAB = {
60. "24": "Partner Tier Upgrade (24)", "26": "Winback (26)",
61. "36": "Quarterly Check-In (36)", "16": "Abandoned Carts (16)",
62. }
64. # Stage names for the audit-only funnel (16). Kept separate from STAGE_NAMES so
65. # reconcile-deals' cat 24/26/36 behaviour is untouched.
66. AUDIT_STAGE_NAMES = {
67. "16": {"NEW": "New Abandoned Cart", "UC_2AAJ7Q": "Guests",
68. "PREPARATION": "First Email Sent", "UC_6V2M93": "No Reply 1st Email",
69. "PREPAYMENT_INVOIC": "Follow-Up Email Sent", "EXECUTING": "No Reply 2nd Email",
70. "WON": "Converted", "LOSE": "Not Converted / Closed"},
71. }
73. # Retired stages were deleted from the Bitrix funnel config, so the API returns a bare
74. # token with no name and a naive audit silently drops them. They were identified by
75. # matching each stage-entry timestamp against the deal's outbound email timeline (see
76. # DECISIONS.md). Do not remove these: stage histories still reference them, and without
77. # them clients who were emailed read as never contacted.
78. RETIRED_STAGE_NAMES = {
79. "24": {"PREPARATION": "Email Sent (retired)",
80. "UC_CEAGAV": "2nd Reachout - call + email (retired)",
81. "UC_V6JARB": "3rd Reachout - follow-up email (retired)",
82. "UC_N4JCMW": "Bulk re-stage, no send (retired)"},
83. "26": {"UC_PMLDJW": "Feedback Survey Email (retired)",
84. "UC_GDHDJR": "Feedback Survey Reminder Email (retired)"},
85. }
86. for _c, _m in RETIRED_STAGE_NAMES.items():
87. STAGE_NAMES.setdefault(_c, {})
88. for _t, _n in _m.items():
89. STAGE_NAMES[_c].setdefault(_t, _n) # setdefault: never shadow a live stage
91. # Stage tokens where a real outbound email, call or LinkedIn DM sits behind the stage
92. # move. Everything else is a system reaction (No - Reply, No Reply Nth Email (Auto),
93. # Email Defunct, Changed Companies, Not Interested, Completed) and must not count as
94. # contact.
95. #
96. # Two traps, both checked against deal timelines:
97. # * cat 26 FINAL_INVOICE is called "Pre-Call Email" and is a real send. A funnel
98. # outside this audit's scope uses that same label for its creation stage, which
99. # sends nothing, so the rule is keyed on the token, never on the stage name.
100. # * cat 26 UC_L2JMHY ("Activated") is excluded on purpose. It is the intake bucket
101. # clients land in when they are made active in Winback: the funnel is too big to
102. # work in one quarter, so activating is how a slice gets picked up for this quarter.
103. # Nothing is sent on that move; the send happens further down the funnel. Adding it
104. # here would read every activation as outreach.
105. SEND_TOKENS = {
106. "24": {"UC_6H9C8U", "PREPAYMENT_INVOIC", "FINAL_INVOICE", "UC_2DE6NT",
107. "PREPARATION", "UC_CEAGAV", "UC_V6JARB"}, # not UC_N4JCMW: a bulk re-stage, no send
108. "26": {"PREPARATION", "PREPAYMENT_INVOIC", "EXECUTING", "FINAL_INVOICE",
109. "UC_BMQAKY", "UC_PMLDJW", "UC_GDHDJR"},
110. "36": {"PREPAYMENT_INVOIC", "EXECUTING"},
111. "16": {"PREPARATION", "PREPAYMENT_INVOIC"},
112. }
114. # Terminal stages: once a deal is here and its stage has not changed since the last
115. # run, its touch history is treated as frozen and reused from the cache instead of
116. # being re-pulled. This is what makes the audit affordable weekly.
117. TERMINAL_TOKENS = {"WON", "LOSE"}
118. TERMINAL_EXTRA = {"36": {"1"}} # cat 36 "Not Interested" is its own token
120. # Known test / non-client records. Flagged in the sheet, never deleted.
121. TEST_DEALS = {"400017", "400023"}
124. def token(stage_id: str) -> str:
125. """The stage token of a Bitrix stage id: "C36:EXECUTING" -> "EXECUTING"."""
126. return stage_id.split(":", 1)[1] if ":" in stage_id else stage_id
129. def stage_status(cat: str, stage_id: str) -> tuple[str, str]:
130. """(human stage name, block status) from a raw Bitrix stage id like C36:EXECUTING."""
131. tok = token(stage_id)
132. name = STAGE_NAMES.get(cat, {}).get(tok)
133. if name is None:
134. print(f"WARNING: unknown stage {stage_id} in cat {cat}: using raw token. "
135. "Add it to STAGE_NAMES.")
136. name = tok
137. if tok == "WON":
138. status = "completed"
139. elif tok == "LOSE" or (cat == "36" and tok == "1"):
140. status = "lost"
141. else:
142. status = "active"
143. return name, status
146. def audit_stage_name(cat: str, stage_id: str) -> str:
147. tok = token(stage_id)
148. for src in (STAGE_NAMES, AUDIT_STAGE_NAMES, RETIRED_STAGE_NAMES):
149. n = src.get(cat, {}).get(tok)
150. if n:
151. return n
152. return tok
155. def is_terminal(cat: str, stage_id: str) -> bool:
156. tok = token(stage_id)
157. return tok in TERMINAL_TOKENS or tok in TERMINAL_EXTRA.get(cat, set())