history.ts

apps/dashboard/src/history.ts

1. /**
2. * Day-over-day deltas.
3. *
4. * The briefing mockup shows "▲ 5 vs yesterday" next to the artwork-review count,
5. * and that arrow is the most useful thing on the page: a queue of 40 means
6. * nothing, a queue of 40 that grew by 5 overnight means the designers are losing
7. * ground. But nothing in Plinth or Bitrix records history, so the only way to have
8. * a yesterday is to keep one.
9. *
10. * This writes one small row per run to `data/dashboard-history.json` and reads
11. * the most recent row from a previous local day back out.
12. *
13. * The rule this file exists to enforce: no prior run means no delta. Not a zero,
14. * not a dash that reads like "unchanged". The arrow is simply absent and the
15. * page says the comparison is not available yet. An invented "▼ 0" on the first
16. * morning would be the dashboard's first lie, and the second one is much easier.
17. *
18. * Runs are keyed by America/Chicago day, not by UTC, because the 6:00 AM CT sync
19. * is what people are comparing. Several runs on the same day overwrite each
20. * other rather than accumulating, so re-running the build at 9:00 does not make
21. * "yesterday" mean "an hour ago".
22. */
24. import { localDay } from '@meridian/ninety-client'
25. import type { Headline } from './collect.js'
27. // File I/O lives in history-file.ts, not here. `rowFrom`, `previousRun` and
28. // `delta` are pure and are needed by the Cloudflare Worker, which stores history
29. // in KV and has no filesystem. A static `node:fs` import in this module would
30. // break the Worker build even though it never calls any of it (rule 7).
32. /**
33. * Bump this whenever the meaning of a recorded number changes (rule 6).
34. *
35. * Comparing rows across a definition change announces a swing that never
36. * happened, the morning after a code change nobody outside this repo knew
37. * about. A delta is only meaningful between two rows that counted the same thing.
38. * Rows with a different `defs` are ignored by previousRun(), so the comparison
39. * simply restarts and says so, which is the same rule as the first morning.
40. *
41. * 1 original
42. * 2 openLeads excludes terminal stages (Junk, Reorder Completed, Converted
43. * Lead, Out of Scope, Unconverted Lead); ourMove excludes them too
44. * 3 the Plinth sweep pages through its whole window rather than stopping
45. * after the oldest page; every order-derived number (ourMove,
46. * designQueue, waitingOnClient, atVendor, needsReply) grows
47. * 4 order lines are classified on the product status, gated on the order
48. * not having shipped past Part Dispatched (see classifyLine); every
49. * order-derived number moves, including the per-person workloads and the
50. * queue
51. */
52. export const DEFS_VERSION = 4
54. /** Kept deliberately small: only the numbers a delta is ever shown for. */
55. export interface HistoryRow {
56. /** America/Chicago calendar day, YYYY-MM-DD. */
57. day: string
58. at: string
59. /** Definition version these numbers were computed under. See DEFS_VERSION. */
60. defs?: number
61. ourMove: number
62. designQueue: number
63. waitingOnClient: number
64. atVendor: number
65. needsReply: number
66. openLeads: number
67. }
69. export interface Delta {
70. value: number
71. /** 'up' | 'down' | 'flat', from the reader's point of view, not the number's. */
72. direction: 'up' | 'down' | 'flat'
73. /** The day being compared against, for the tooltip. */
74. since: string
75. }
77. /** How many rows to keep. Enough for a month of weekdays, small enough to read. */
78. export const KEEP = 40
80. export function rowFrom(h: Headline, at: Date = new Date()): HistoryRow {
81. return {
82. day: localDay(at),
83. at: at.toISOString(),
84. defs: DEFS_VERSION,
85. ourMove: h.ourMove,
86. designQueue: h.designQueue,
87. waitingOnClient: h.waitingOnClient,
88. atVendor: h.atVendor,
89. needsReply: h.needsReply,
90. openLeads: h.realLeads,
91. }
92. }
94. /**
95. * The most recent row from a day before `today`. Returns null when there is no
96. * previous day on file, which is the honest answer on the first morning and
97. * after any gap, and which every caller must render as "no comparison" rather
98. * than as zero.
99. */
100. export function previousRun(history: HistoryRow[], today: string): HistoryRow | null {
101. // Rows recorded under an older definition are skipped, not compared. A delta
102. // across a definition change is a fabricated swing (see DEFS_VERSION).
103. const earlier = history.filter((r) => r.day < today && (r.defs ?? 1) === DEFS_VERSION)
104. return earlier.length ? earlier[earlier.length - 1]! : null
105. }
107. /**
108. * `up` and `down` describe the number, not whether it is good news. Which
109. * direction is good depends on the metric, so the caller decides the color:
110. * our-move falling is good, at-vendor falling may just mean nothing shipped.
111. */
112. export function delta(now: number, prev: HistoryRow | null, key: keyof HistoryRow): Delta | null {
113. if (!prev) return null
114. const was = prev[key]
115. if (typeof was !== 'number') return null
116. const d = now - was
117. return { value: d, direction: d > 0 ? 'up' : d < 0 ? 'down' : 'flat', since: prev.day }
118. }