status-taxonomy.ts

packages/plinth-client/src/status-taxonomy.ts

1. /**
2. * Plinth product-status taxonomy: the judgment layer.
3. *
4. * Plinth has no notion of "open work." It has statuses. Whether a status means Meridian
5. * owes the next move, the client owes it, a vendor owes it, or the line is done
6. * is a judgment that differs per status, and no system can tell you.
7. *
8. * 'ours' Meridian owes the next move. The only class that counts as load.
9. * 'client' Blocked on the client. A follow-up list, not workload. Aging here
10. * measures client responsiveness, not our capacity.
11. * 'vendor' At the printer or in transit. Delivery risk, not load.
12. * 'parked' Deliberately paused.
13. * 'terminal' Done, cancelled, or refunded.
14. *
15. * These are judgements read from status names. The 'ours' vs 'client' calls
16. * are the ones to confirm with the people who run production: that boundary
17. * decides whether a number describes the team's backlog or the client's.
18. */
20. export type WorkClass = 'ours' | 'client' | 'vendor' | 'parked' | 'terminal'
22. export interface StatusRule {
23. id: number
24. name: string
25. class: WorkClass
26. /** Design-queue statuses roll up into the designer-load number. */
27. design?: boolean
28. note?: string
29. }
31. /** catalog: "Product", the granular, truthful layer. */
32. export const PRODUCT_STATUSES: StatusRule[] = [
33. { id: 176, name: 'File Check', class: 'ours', design: true, note: 'The designer queue.' },
34. { id: 144, name: 'Design Requested', class: 'ours', design: true },
35. { id: 101, name: 'Proof In Progress', class: 'ours', design: true },
36. { id: 120, name: 'Revisions In Progress', class: 'ours', design: true },
37. { id: 115, name: 'Reproof Needed', class: 'ours', design: true },
38. { id: 136, name: 'Files Resubmitted', class: 'ours', design: true, note: 'Back in the queue; needs re-review.' },
39. { id: 138, name: 'Waiting On Files', class: 'client' },
40. { id: 161, name: 'Proof With Client', class: 'client' },
41. { id: 122, name: 'Question For Client', class: 'client' },
42. { id: 175, name: 'Proof Signed Off', class: 'ours', note: 'Approved, not yet moved on. Should be near zero.' },
43. { id: 145, name: 'Cleared For Print', class: 'ours' },
44. { id: 179, name: 'On Press', class: 'vendor' },
45. { id: 182, name: 'At Partner Shop', class: 'vendor' },
46. { id: 112, name: 'Partner Dispatched', class: 'vendor' },
47. { id: 126, name: 'Packed', class: 'ours' },
48. { id: 103, name: 'Payment Due', class: 'client' },
49. { id: 143, name: 'Line Cancel Requested', class: 'ours', note: 'Needs a decision.' },
50. { id: 139, name: 'Line Cancelled', class: 'terminal' },
51. { id: 194, name: 'Line Refunded', class: 'terminal' },
52. { id: 157, name: 'Signed Off With Edits (Retired)', class: 'terminal', note: 'Marked for deletion by Plinth.' },
53. ]
55. /**
56. * catalog: "Order", the coarser layer.
57. *
58. * Kept separate from the product catalog on purpose. The two use different ids
59. * for the same label ("File Check" is 121 here and 176 there) and they do not
60. * contain the same set: `Proof Out` (159) exists only at order level. Merging
61. * them would let an order-level status fall through the product classifier
62. * and be counted as "our move" when it is actually sitting with the client.
63. */
64. export const ORDER_STATUSES: StatusRule[] = [
65. { id: 134, name: 'Received', class: 'ours' },
66. { id: 171, name: 'Allocated', class: 'ours' },
67. { id: 121, name: 'File Check', class: 'ours', design: true },
68. { id: 181, name: 'Design Requested', class: 'ours', design: true },
69. { id: 195, name: 'Proof In Progress', class: 'ours', design: true },
70. { id: 186, name: 'Revisions In Progress', class: 'ours', design: true },
71. { id: 159, name: 'Proof Out', class: 'client', note: 'Waiting on client approval. NOT team load.' },
72. { id: 167, name: 'Waiting On Files', class: 'client' },
73. { id: 163, name: 'Payment Due', class: 'client' },
74. { id: 168, name: 'Proof Signed Off', class: 'ours', note: 'Approved, not yet moved on.' },
75. { id: 185, name: 'Cleared For Print', class: 'ours' },
76. { id: 177, name: 'Rush Print', class: 'ours' },
77. { id: 140, name: 'Rush Prep', class: 'ours' },
78. { id: 111, name: 'PO In Review', class: 'ours' },
79. { id: 137, name: 'Payment Error', class: 'ours', note: 'Revenue at risk.' },
80. { id: 106, name: 'Cancel Requested', class: 'ours', note: 'Needs a decision.' },
81. { id: 108, name: 'Packed', class: 'ours' },
82. { id: 125, name: 'On Press', class: 'vendor' },
83. { id: 117, name: 'PO Dispatched', class: 'vendor' },
84. { id: 133, name: 'Dispatched', class: 'vendor' },
85. { id: 162, name: 'Part Dispatched', class: 'vendor' },
86. { id: 193, name: 'Awaiting Collection', class: 'vendor' },
87. { id: 135, name: 'On Hold', class: 'parked' },
88. { id: 189, name: 'Delivered', class: 'terminal', note: 'Graveyard: thousands of records, none ever exit.' },
89. { id: 129, name: 'Cancelled', class: 'terminal' },
90. { id: 166, name: 'Refunded', class: 'terminal' },
91. { id: 191, name: 'Claim Opened', class: 'ours' },
92. { id: 131, name: 'Claim Settled', class: 'terminal' },
93. { id: 158, name: 'PO Paid', class: 'ours' },
94. { id: 196, name: 'PO Payment Due', class: 'client' },
95. { id: 107, name: 'Legacy Review (retired)', class: 'terminal' },
96. { id: 174, name: 'Legacy Processing (retired)', class: 'terminal' },
97. ]
99. const orderById = new Map(ORDER_STATUSES.map((s) => [s.id, s]))
100. const orderByName = new Map(ORDER_STATUSES.map((s) => [s.name.toLowerCase(), s]))
102. function resolveOrder(statusName: string, statusId?: number | null) {
103. if (typeof statusId === 'number') {
104. const hit = orderById.get(statusId)
105. if (hit) return hit
106. }
107. return orderByName.get(statusName.trim().toLowerCase())
108. }
110. export function classifyOrder(statusName: string, statusId?: number | null): WorkClass {
111. return resolveOrder(statusName, statusId)?.class ?? 'ours'
112. }
114. export function isOrderDesignQueue(statusName: string, statusId?: number | null): boolean {
115. return resolveOrder(statusName, statusId)?.design ?? false
116. }
118. export function isKnownOrderStatus(statusName: string, statusId?: number | null): boolean {
119. return resolveOrder(statusName, statusId) !== undefined
120. }
122. const byId = new Map(PRODUCT_STATUSES.map((s) => [s.id, s]))
123. const byName = new Map(PRODUCT_STATUSES.map((s) => [s.name.toLowerCase(), s]))
125. /**
126. * Resolve a status rule, preferring the ID.
127. *
128. * `line_status_code` matters more than it looks: status names are duplicated
129. * across the two catalogs. "File Check"
130. * is id 121 as an Order status and id 176 as a Product status; "On Press" is
131. * 125 and 179; "Proof Signed Off" is 168 and 175. Matching on the name alone cannot
132. * tell those apart, so a name-keyed lookup is silently one wrong field away
133. * from classifying an order-level status against product-level rules.
134. *
135. * The name fallback stays for records that carry no id.
136. */
137. function resolve(statusName: string, statusId?: number | null) {
138. if (typeof statusId === 'number') {
139. const hit = byId.get(statusId)
140. if (hit) return hit
141. }
142. return byName.get(statusName.trim().toLowerCase())
143. }
145. /** Unknown statuses classify as 'ours' so a new one is noticed, not hidden. */
146. export function classifyProduct(statusName: string, statusId?: number | null): WorkClass {
147. return resolve(statusName, statusId)?.class ?? 'ours'
148. }
150. export function isDesignQueue(statusName: string, statusId?: number | null): boolean {
151. return resolve(statusName, statusId)?.design ?? false
152. }
154. /**
155. * Order statuses past the point where the line has left the building.
156. *
157. * A line is ours when the product status says ours and the order has not moved
158. * past Part Dispatched. So Part Dispatched is still
159. * eligible and these two are the first that are not; Delivered, Cancelled
160. * and Refunded are caught by their `terminal` class instead of being listed
161. * again here.
162. */
163. const PAST_FULFILMENT = new Set([
164. 133, // Dispatched
165. 193, // Awaiting Collection
166. ])
168. /**
169. * Has this order moved beyond the point where anybody here still owes it a move?
170. *
171. * Unknown statuses answer false: the line keeps showing. Same direction as
172. * `classifyProduct`'s unknown default: a status nobody has classified yet should
173. * be noticed on the page, not quietly filtered off it.
174. */
175. export function isOrderPastFulfilment(statusName: string, statusId?: number | null): boolean {
176. const rule = resolveOrder(statusName, statusId)
177. if (!rule) return false
178. return rule.class === 'terminal' || PAST_FULFILMENT.has(rule.id)
179. }
181. /**
182. * The one classifier for an order line. Product status decides, unless the
183. * order has shipped, in which case the line is done whatever the product row
184. * says. Every count on the board goes through this, so the counts agree with
185. * the product status the Status column shows.
186. *
187. * Neither field alone is right:
188. *
189. * - Order status alone hides real design work. An order sitting On Press
190. * with a product line still in File Check is somebody's job today.
191. * - Product status alone invents work that is already out of the door. The
192. * product row parks at its last value when an order ships, so many
193. * design-stage product lines sit on orders already shipped or delivered.
194. * Counting those makes the team look behind when it is not.
195. *
196. * So: the product row says what the work is, and the order says whether the
197. * work is still here, with the cutoff at Part Dispatched.
198. */
199. export function classifyLine(line: {
200. productStatus: string
201. productStatusId?: number | null
202. orderStatus: string
203. orderStatusId?: number | null
204. }): WorkClass {
205. if (isOrderPastFulfilment(line.orderStatus, line.orderStatusId)) return 'terminal'
206. return classifyProduct(line.productStatus, line.productStatusId)
207. }
209. /** Does this line's design-queue claim still stand? Same gate. */
210. export function isLineDesignQueue(line: {
211. productStatus: string
212. productStatusId?: number | null
213. orderStatus: string
214. orderStatusId?: number | null
215. }): boolean {
216. if (isOrderPastFulfilment(line.orderStatus, line.orderStatusId)) return false
217. return isDesignQueue(line.productStatus, line.productStatusId)
218. }
220. export const CLASS_LABELS: Record<WorkClass, string> = {
221. ours: 'Our move',
222. client: 'Waiting on client',
223. vendor: 'At vendor / in transit',
224. parked: 'Parked',
225. terminal: 'Closed',
226. }