orders.ts

packages/plinth-client/src/resources/orders.ts

1. /**
2. * Orders, and (more importantly) the product-level statuses inside them.
3. *
4. * Order status and product status disagree routinely: an order can read "On
5. * Press" at the order level while its line items are still in "File Check". Counting orders by
6. * `status_code` therefore undercounts the design queue.
7. *
8. * So the unit of work here is the product line, not the order.
9. */
11. import { assignedPerson } from '../assignment-values.js'
12. import { GET_ORDERS_PARAMS, num, phpCollection, str, toPlinthDate } from '../hazards.js'
13. import { projectOrder, projectProduct } from '../projection.js'
14. import type { PlinthClient } from '../http.js'
16. /** Days since the order was placed. Plinth records no status-change timestamps,
17. * so this is age-since-order, not age-in-status. */
18. function placedAgeDays(placed: string | null, now = new Date()): number | null {
19. if (!placed) return null
20. const t = Date.parse(placed.replace(' ', 'T'))
21. return Number.isFinite(t) ? Math.floor((now.getTime() - t) / 86_400_000) : null
22. }
24. export interface OrderLine {
25. orderId: number
26. /** The product-line id. Exact per-line identity, unlike order_ref + item_ref. */
27. ordersProductsId: number | null
28. productId: number | null
29. orderStatus: string
30. orderStatusId: number
31. /** The one that actually reflects where the work is. */
32. productStatus: string
33. /**
34. * Preferred over the name for classification: status names
35. * collide across the Order and Product catalogs ("File Check" is 53 and
36. * 44, "On Press" is 40 and 10).
37. */
38. productStatusId: number | null
39. productTitle: string
40. quantity: number
41. price: number
42. customer: string
43. company: string | null
44. /** Despite the field name, this is when the order was placed. */
45. placedAt: string | null
46. amount: number
47. vendor: string | null
48. userGroup: string | null
49. /**
50. * The designer, from the API. The `--` sentinel is already
51. * null here; the raw Plinth account label is mapped to a roster name in collect.ts.
52. */
53. productionOwner: string | null
54. /** The CS rep overseeing the order. Same normalization as productionOwner. */
55. accountOwner: string | null
56. /** Days since the order was placed. Best available age signal; Plinth records no
57. * status-change timestamps, so this is age-since-order, not age-in-status. */
58. ageDays: number | null
59. }
61. /**
62. * How many fetched lines actually carried each assignment field: key present,
63. * regardless of value.
64. *
65. * production_owner / account_owner arrive on orders.fetch (order level and per
66. * product line). Fields that arrived by vendor change can vanish by vendor
67. * change, and a vanished field
68. * would make every line read unassigned, which looks like free capacity, the
69. * exact lie this board exists to prevent. So presence is counted, and the caller
70. * reports zero coverage as missing rather than as zero work.
71. *
72. * Presence is judged per line because Plinth omits keys per record rather than
73. * sending them null: the same call returns different key sets across orders.
74. */
75. export interface AssignmentFieldCoverage {
76. production: number
77. accountOwner: number
78. total: number
79. }
81. /**
82. * A window of order lines, plus whether it is the whole window.
83. *
84. * `truncated` is not optional and is not cosmetic. Plinth pages by product
85. * line and gives no total, so a caller cannot tell a complete sweep from a
86. * capped one by looking at the rows. When this is true the counts are a floor,
87. * and a floor presented as a total misstates the window (rule 5). Same
88. * contract as LeadWindow in the Bitrix client.
89. */
90. export interface OrderWindow {
91. lines: OrderLine[]
92. /** True when maxPages ran out before Plinth returned a short page. */
93. truncated: boolean
94. /** Requests actually made. Useful for spotting a window that is too wide. */
95. pages: number
96. /** Assignment field presence across `lines`. Never inferred; counted. */
97. assignmentFields: AssignmentFieldCoverage
98. }
100. export class OrdersResource {
101. constructor(private readonly client: PlinthClient) {}
103. /**
104. * Orders placed in a date window, flattened to one row per product line.
105. *
106. * Windowed rather than filtered by status because a sweep by status would need
107. * one call per status. 30+ calls at 9-per-10-seconds is over half a minute for
108. * data one windowed call can return.
109. */
110. async linesInWindow(
111. fromIso: string,
112. toIso: string,
113. limit = 500,
114. maxPages = 20,
115. ): Promise<OrderWindow> {
116. const raws: unknown[] = []
117. let pages = 0
118. let truncated = true
120. // Paginate, and count the right thing when deciding to stop.
121. //
122. // `limit` and `offset` on orders.fetch are measured in product lines, not
123. // orders. Against the live API:
124. //
125. // limit=100 offset=0 -> 61 orders, 100 lines
126. // limit=100 offset=100 -> 57 orders, 100 lines
127. // limit=500 offset=0 -> 297 orders, 500 lines
128. //
129. // So stopping on `batch.length < limit` would compare orders against a line
130. // budget: a full page of 100 lines is around 60 orders, so it would stop
131. // after one page every time. Because Plinth orders by date ascending, that
132. // one page is the oldest slice of the window, and the board would describe
133. // a different fortnight while labelling it "the last 60 days".
134. //
135. // A short page is the only end signal Plinth gives, so the line count is what
136. // has to be compared. maxPages is a guard, not an expectation; hitting it
137. // means the window is wider than this can fetch, and `truncated` says so
138. // rather than the caller assuming it got everything.
139. for (let page = 0; page < maxPages; page++) {
140. const body = await this.client.call<{ order_map?: Record<string, unknown> }>(
141. 'orders.fetch',
142. {
143. since: toPlinthDate(fromIso),
144. until: toPlinthDate(toIso),
145. limit,
146. offset: page * limit,
147. },
148. GET_ORDERS_PARAMS,
149. )
150. // null means "Invalid request", which is also how Plinth says zero results.
151. const batch = body?.order_map ? Object.values(body.order_map) : []
152. pages = page + 1
153. raws.push(...batch)
155. // Lines, not orders. See above.
156. let batchLines = 0
157. for (const o of batch) {
158. batchLines += phpCollection<Record<string, unknown>>(
159. (o as Record<string, unknown>).lines,
160. ).length
161. }
162. if (batchLines < limit) {
163. truncated = false
164. break
165. }
166. }
168. const lines: OrderLine[] = []
169. let poPresent = 0
170. let aoPresent = 0
171. for (const rawOrder of raws) {
172. const o = projectOrder(rawOrder as Record<string, unknown>)
173. const rawAll = rawOrder as Record<string, unknown>
174. const products = phpCollection<Record<string, unknown>>(rawAll.lines)
175. const customer = [str(o.first_name), str(o.last_name)]
176. .filter(Boolean)
177. .join(' ')
178. .trim()
180. for (const rawProduct of products) {
181. const p = projectProduct(rawProduct)
182. const poInLine = 'production_owner' in rawProduct
183. const aoInLine = 'account_owner' in rawProduct
184. if (poInLine || 'production_owner' in rawAll) poPresent++
185. if (aoInLine || 'account_owner' in rawAll) aoPresent++
186. lines.push({
187. orderId: num(o.order_ref),
188. ordersProductsId: p.line_ref != null ? num(p.line_ref) : null,
189. productId: p.item_ref != null ? num(p.item_ref) : null,
190. orderStatus: str(o.status_label) ?? 'unknown',
191. orderStatusId: num(o.status_code),
192. productStatus: str(p.line_status) ?? 'unknown',
193. productStatusId: typeof p.line_status_code === 'number' ? p.line_status_code : null,
194. productTitle: str(p.item_name) ?? '(untitled)',
195. quantity: num(p.qty, 1),
196. price: num(p.unit_price),
197. customer: customer || '(no name)',
198. company: str(o.company_name),
199. placedAt: str(o.closed_on),
200. amount: num(o.grand_total),
201. vendor: str(o.press_name),
202. userGroup: str(o.customer_group),
203. // Present at order level and per product line. The per-line value
204. // wins; the order-level value is used only when the product record
205. // lacks the key, because a product-level `--` means this line is
206. // unassigned even when the order names someone. `--` is the
207. // unassigned sentinel (as observed live, whatever the vendor
208. // documents) and becomes null here, never a person. Raw Plinth account
209. // labels ("Marco-Acct7-Desk") pass through unmapped; collect.ts turns
210. // them into roster names via config/plinth-people.ts.
211. productionOwner: assignedPerson(
212. poInLine ? str(rawProduct.production_owner) : str(rawAll.production_owner),
213. ),
214. accountOwner: assignedPerson(
215. aoInLine ? str(rawProduct.account_owner) : str(rawAll.account_owner),
216. ),
217. ageDays: placedAgeDays(str(o.closed_on)),
218. })
219. }
220. }
221. return {
222. lines,
223. truncated,
224. pages,
225. assignmentFields: { production: poPresent, accountOwner: aoPresent, total: lines.length },
226. }
227. }
228. }