collect.ts

apps/dashboard/src/collect.ts

1. /**
2. * Pull both sources and reduce to what the page renders.
3. *
4. * Design rules (see docs/ARCHITECTURE.md):
5. *
6. * - Group by stage, never by assignee. Bitrix's assignee is a routing default;
7. * every open lead sampled belonged to one person.
8. * - Count product lines, not orders. Order status and product status disagree.
9. * - Only 'ours' counts as load. Waiting-on-client is a follow-up list.
10. * - Flag automation noise; never silently drop it.
11. * - Report per-source failure. A source that dies must show as broken, not as
12. * zero. A dashboard that quietly reports zero is worse than one that errors.
13. */
15. import {
16. BitrixClient,
17. LeadsResource,
18. TasksResource,
19. partitionTasks,
20. type Lead,
21. type Task,
22. } from '@meridian/bitrix-client'
23. import { fetchTracker, type TrackerTask } from '@meridian/sheets-client'
24. import {
25. TRACKER_SHEET_ID,
26. TRACKER_TABS,
27. classifyTrackerStatus,
28. type TrackerClass,
29. } from '../../../config/content-tracker.js'
30. import { MERIDIAN_PEOPLE, personByName, personFromBitrix, personFromNinety, personFromTrackerOwner, unmappedTrackerOwners, offRosterBitrixIds, unpinnedBitrixPeople, SOURCE_LABELS, type Person } from '../../../config/meridian-people.js'
31. import {
32. attributeFathomRef,
33. isUnownedRef,
34. participantsOf,
35. COMMITMENT_WINDOW_DAYS,
36. } from '../../../config/fathom-people.js'
37. import { FATHOM_KEYS, FATHOM_WINDOW_DAYS } from '../../../config/fathom-keys.js'
38. import { FathomClient, MeetingsResource } from '@meridian/fathom-client'
39. import {
40. PlinthClient,
41. OrdersResource,
42. displayOrderNumber,
43. isKnownOrderStatus,
44. classifyProduct,
45. classifyLine,
46. isLineDesignQueue,
47. isOrderPastFulfilment,
48. type AssignmentFieldCoverage,
49. type OrderLine,
50. type OrderWindow,
51. type WorkClass,
52. } from '@meridian/plinth-client'
53. import {
54. assignmentSpread,
55. clientFromEnv,
56. isActuallyLate,
57. reviewGatesMissed,
58. type Todo,
59. } from '@meridian/ninety-client'
60. import { LEAD_STAGES, classify as classifyLead, stageName, unknownStageIds } from '../../../config/bitrix-stages.js'
61. import { displayName, isUnmappedAccount } from '../../../config/plinth-people.js'
62. import { errorMessage } from '@meridian/shared'
64. export interface SourceResult<T> {
65. ok: boolean
66. data: T
67. error: string | null
68. }
70. export interface Snapshot {
71. syncedAt: string
72. /**
73. * Where this snapshot came from. Every status, banner and payload field reads
74. * this first, so a fixture run can never render "live" pills over a frozen
75. * export: a source asserting a status it has not earned is the failure this
76. * board is built to avoid.
77. */
78. mode: 'live' | 'fixtures'
79. /** When the frozen data was captured. Null for a live run. */
80. fixtureCapturedAt: string | null
81. leads: SourceResult<Lead[]>
82. orderLines: SourceResult<OrderLine[]>
83. tasks: SourceResult<Task[]>
84. /**
85. * Company-wide Ninety to-dos, from one admin token via GET /todos/company.
86. *
87. * A 403 here is about the token's Ninety role, not a bug. The error text says
88. * so.
89. */
90. ninety: SourceResult<Todo[]>
91. /**
92. * The Content Creation tracker (Google Sheet).
93. *
94. * It is the only source here that is a hand-maintained document rather than a
95. * system of record, which makes it the one most likely to go quietly stale,
96. * and the one we can say the least about, because the public CSV endpoint
97. * carries no last-modified. Both facts are on the page rather than in this
98. * comment alone. See config/content-tracker.ts.
99. */
100. sheet: SourceResult<TrackerTask[]>
101. /** Which tabs answered and which did not. A partial read is reported, never thrown. */
102. sheetTabs: { ok: { label: string; gid: string; rows: number }[]; failed: { label: string; gid: string; reason: string }[] }
103. /**
104. * Assignments vs commitments. Never render one without the other: a real
105. * share of rows are one commitment carried by two or three people, so a bare
106. * row count overstates the work and hides that it is jointly owned.
107. */
108. ninetySpread: ReturnType<typeof assignmentSpread> | null
109. /**
110. * How the lead list was bounded. `sinceDays` changes what "open leads" means,
111. * so it belongs next to the number rather than buried in a config file, and
112. * `truncated` means the count is a floor rather than a total.
113. */
114. leadWindow: LeadWindow
115. /**
116. * How the order sweep was bounded. Same reason `leadWindow` exists: Plinth pages
117. * by product line and reports no total, so `truncated` is the only way to know
118. * whether these counts are the window or a slice of it.
119. */
120. orderWindow: OrderWindow
121. assignmentWarnings: string[]
122. /**
123. * Meetings and their action items, from the Fathom keys in config.
124. *
125. * Every meeting the keys can see is in here, including ones most viewers must
126. * never be shown. Nothing in this array is safe to render as-is: the gate is
127. * `meetingsFor(snap, viewer)` in view-model.ts, and the company variant gets
128. * none of it. That is a deliberate trade: one fetch, one snapshot, filtered
129. * per viewer at render time, the same shape as every other source here.
130. */
131. meetings: SourceResult<MeetingRecord[]>
132. /**
133. * False when no Fathom key is configured. Then `meetings` is empty because
134. * nobody was asked, which must read as "not tracked" and never as "no meetings".
135. * An empty meeting list and an unconfigured source look identical otherwise,
136. * and one of them means free capacity.
137. */
138. fathomConfigured: boolean
139. /**
140. * One row per key that was actually asked, in the order they were asked.
141. *
142. * A list and not a boolean because `meetings` is one SourceResult covering
143. * several fetches, so on its own it cannot distinguish "every key read
144. * cleanly" from "one key is revoked". The second is a partial view of the
145. * company's meetings, and the difference is invisible in the merged list: the
146. * key owner's page would simply be short, and short is what a quiet week
147. * looks like. Named per owner so the page can say which key is dark (rule 1).
148. *
149. * Empty when no key is configured at all. Then `fathomConfigured` is false
150. * and the whole source reads as not tracked.
151. */
152. fathomSources: FathomSourceStatus[]
153. }
155. /**
156. * How one Fathom key's own sweep went. `returned` counts what that key sent,
157. * before the cross-key dedupe, so the numbers here sum to at least the length
158. * of the merged list and never to less.
159. */
160. export interface FathomSourceStatus {
161. /** Roster display name of the key's owner, from config/fathom-keys.ts. */
162. owner: string
163. ok: boolean
164. /** The failure as reported, verbatim. Never a diagnosis. */
165. error: string | null
166. returned: number
167. /** The sweep hit its page cap. What is here is real but incomplete. */
168. truncated: boolean
169. }
171. /**
172. * One meeting, reduced to what the board renders and what it gates on.
173. *
174. * `participants` is an access list, not decoration. It is the only thing
175. * standing between a leadership meeting and the rest of the team, because
176. * Fathom's own permissions cannot help here (see config/fathom-keys.ts).
177. * Roster display names rather than Person objects so the snapshot stays
178. * JSON-serialisable for KV.
179. */
180. export interface MeetingRecord {
181. recordingId: number
182. title: string
183. date: string
184. url: string
185. /** Roster names of people who were in the room: who may see this meeting. */
186. participants: string[]
187. /** Outsiders, named for context. Never viewers. */
188. externals: string[]
189. /** Internal addresses matching nobody. A question for a human, not a viewer. */
190. unmatchedParticipants: string[]
191. items: MeetingItem[]
192. }
194. export interface MeetingItem {
195. text: string
196. /** Roster name. Null does not mean unowned; check the other two first. */
197. owner: string | null
198. /** External label when an outsider owns it; null otherwise. */
199. externalOwner: string | null
200. /**
201. * A name Fathom gave that the board cannot resolve.
202. *
203. * Distinct from unowned, and collapsing the two would lose the difference
204. * between "nobody was named" and "somebody was named and we do not know who".
205. * The first is work looking for an owner; the second is a config gap. All
206. * three owner fields null means genuinely unowned.
207. */
208. unknownOwner: string | null
209. /** Deep link to the moment it was said. */
210. playbackUrl: string | null
211. }
213. export interface LeadWindow {
214. /** True when the page cap was hit: the count is a floor, not a total. */
215. truncated: boolean
216. pages: number
217. /** Days of history included. Null means no floor: everything ever opened. */
218. sinceDays: number | null
219. }
221. export interface StageCount {
222. id: string
223. name: string
224. count: number
225. class: WorkClass | 'ours' | 'waiting' | 'vendor' | 'parked' | 'terminal'
226. }
228. export async function collect(
229. env: Record<string, string | undefined>,
230. days = 60,
231. ): Promise<Snapshot> {
232. const syncedAt = new Date().toISOString()
234. // Windowed to the same span as the Plinth pull, so the board describes one period
235. // rather than two. Without a floor this returns thousands of rows: the email-to-lead
236. // automation makes a lead out of every security alert, call log and chat, and
237. // nothing closes them. A lead untouched for eighteen months is debt, not
238. // pipeline, and counting it as pipeline makes every other number meaningless.
239. let leadWindow: LeadWindow = { truncated: false, pages: 0, sinceDays: days }
240. const leads = await safely(async () => {
241. const http = new BitrixClient({ webhookUrl: env.BITRIX_WEBHOOK_URL ?? '', debug: env.DEBUG === 'true' })
242. const res = await new LeadsResource(http).listOpen({ sinceDays: days })
243. leadWindow = { truncated: res.truncated, pages: res.pages, sinceDays: res.sinceDays }
244. return res.leads
245. }, [] as Lead[])
247. // Declared outside `safely` for the same reason leadWindow is: a failed sweep
248. // must leave the window describing a failure, not asserting a clean one.
249. let orderWindow: OrderWindow = {
250. lines: [],
251. truncated: false,
252. pages: 0,
253. // total 0 keeps the coverage guard silent when the Plinth fetch failed: that
254. // failure is already reported as failed, and reporting it a second time as a
255. // coverage gap would describe one outage as two problems.
256. assignmentFields: { production: 0, accountOwner: 0, total: 0 },
257. }
258. const orderLines = await safely(async () => {
259. const client = new PlinthClient({ token: env.PLINTH_API_KEY ?? '', debug: env.DEBUG === 'true' })
260. const to = new Date()
261. const from = new Date(to.getTime() - days * 86_400_000)
262. orderWindow = await new OrdersResource(client).linesInWindow(iso(from), iso(to))
263. return orderWindow.lines
264. }, [] as OrderLine[])
266. const tasks = await safely(async () => {
267. const http = new BitrixClient({ webhookUrl: env.BITRIX_WEBHOOK_URL ?? '', debug: env.DEBUG === 'true' })
268. return new TasksResource(http).listOpen()
269. }, [] as Task[])
271. // Hydrated, because the thin index carries no seriesId, milestoneId or
272. // dueDateChanged, and without those you cannot collapse recurrence, link a
273. // to-do to its rock, or spot a due date that has moved four times. ~2s for 40
274. // rows, which is a sync cost, not a page-load cost.
275. const ninety = await safely(async () => {
276. const client = clientFromEnv(env)
277. const snap = await client.companySnapshot({ detailed: true })
278. return snap.todos
279. }, [] as Todo[])
281. // No credential, by design: the tracker is read from Google's public CSV
282. // endpoint because the document is shared by link. That is what lets the
283. // Worker cron read it at all, and it is stated in config/content-tracker.ts
284. // because it is also a fact about who else can read it.
285. const sheetFetch = await safely(
286. () => fetchTracker(TRACKER_SHEET_ID, TRACKER_TABS),
287. { tasks: [] as TrackerTask[], tabs: [], failedTabs: [] } as Awaited<ReturnType<typeof fetchTracker>>,
288. )
290. // Meetings: one fetch per configured key. Keys buy coverage, not gating: each
291. // returns its owner's recordings plus whatever Fathom shares with that user,
292. // by a mechanism the API does not expose. The union is deduplicated by
293. // recording id below. See config/fathom-keys.ts.
294. //
295. // Everything the keys can see lands in the snapshot, including meetings most
296. // viewers must never be shown. The gate is at render time, per viewer.
297. const fathomKeys = FATHOM_KEYS.map((k) => ({ ...k, key: env[k.secret] })).filter(
298. (k): k is typeof k & { key: string } => Boolean(k.key),
299. )
300. const fathomConfigured = fathomKeys.length > 0
302. // One key's failure must not erase the others, so each key is caught on its
303. // own. A single try around the loop would blank meetings for everyone the
304. // first time one key is revoked, and name no cause.
305. //
306. // The other half of that trade is the prime invariant. A swallowed per-key
307. // failure would make a key that cannot reach someone's meetings look exactly
308. // like a person who recorded none, and one of those means free capacity. So
309. // a dark key is never silent: it rides in `fathomSources`, the source pill reads
310. // `partial`, and every surface that lists commitments says a key is dark.
311. const fathomSources: FathomSourceStatus[] = []
312. const meetings: SourceResult<MeetingRecord[]> = fathomConfigured
313. ? await (async () => {
314. const since = new Date(Date.now() - FATHOM_WINDOW_DAYS * 86_400_000).toISOString()
315. const byId = new Map<number, MeetingRecord>()
316. for (const { owner, key } of fathomKeys) {
317. try {
318. const window = await new MeetingsResource(
319. new FathomClient({ apiKey: key, owner }),
320. ).listSince(since)
321. for (const m of window.meetings) {
322. // Two keys can return the same meeting. Keyed by recording id so it
323. // is stored once; the participant list is a property of the meeting,
324. // not of whoever fetched it.
325. if (byId.has(m.recording_id)) continue
326. const people = participantsOf(m.calendar_invitees)
327. byId.set(m.recording_id, {
328. recordingId: m.recording_id,
329. title: m.title,
330. date: m.recording_start_time ?? m.created_at,
331. url: m.url,
332. participants: people.roster.map((x) => x.name),
333. externals: people.external,
334. unmatchedParticipants: people.unmatched,
335. items: (m.action_items ?? []).map((item) => {
336. const owned = isUnownedRef(item.assignee)
337. ? null
338. : attributeFathomRef(item.assignee, m.calendar_invitees)
339. return {
340. text: item.description,
341. owner: owned?.kind === 'roster' ? owned.person.name : null,
342. externalOwner: owned?.kind === 'external' ? owned.label : null,
343. unknownOwner: owned?.kind === 'unknown' ? owned.label : null,
344. playbackUrl: item.recording_playback_url ?? null,
345. }
346. }),
347. })
348. }
349. // A capped sweep keeps what it has and says so, or the shortfall
350. // reads as a quiet week.
351. fathomSources.push({
352. owner,
353. ok: true,
354. error: null,
355. returned: window.meetings.length,
356. truncated: window.truncated,
357. })
358. } catch (err) {
359. fathomSources.push({
360. owner,
361. ok: false,
362. error: errorMessage(err),
363. returned: 0,
364. truncated: false,
365. })
366. }
367. }
368. const data = [...byId.values()].sort((a, b) => Date.parse(b.date) - Date.parse(a.date))
370. // Every key dark is a failed source, not a thin one. Keeping ok:true
371. // there would render an empty list under a live pill, which is the exact
372. // shape the prime invariant exists to forbid.
373. return fathomSources.some((s) => s.ok)
374. ? { ok: true, data, error: null }
375. : {
376. ok: false,
377. data,
378. error: fathomSources.map((s) => `${s.owner}: ${s.error}`).join('; '),
379. }
380. })()
381. : // Nobody was asked. Empty because unconfigured, which `fathomConfigured`
382. // is what distinguishes from "we looked and there are no meetings".
383. { ok: true, data: [] as MeetingRecord[], error: null }
385. const assignmentWarnings = orderLines.ok
386. ? normalizeAssignments(orderLines.data, orderWindow.assignmentFields)
387. : []
389. return {
390. syncedAt,
391. mode: 'live',
392. fixtureCapturedAt: null,
393. leads,
394. orderLines,
395. tasks,
396. ninety,
397. ninetySpread: ninety.ok ? assignmentSpread(ninety.data) : null,
398. sheet: { ok: sheetFetch.ok, data: sheetFetch.data.tasks, error: sheetFetch.error },
399. sheetTabs: { ok: sheetFetch.data.tabs, failed: sheetFetch.data.failedTabs },
400. leadWindow,
401. orderWindow,
402. assignmentWarnings: [...new Set(assignmentWarnings)],
403. meetings,
404. fathomConfigured,
405. fathomSources,
406. }
407. }
409. /**
410. * Map raw Plinth account labels onto roster names, and judge field coverage.
411. *
412. * Assignments arrive on the same orders.fetch response as the orders, order
413. * level and per product line. Two normalizations already happened in
414. * plinth-client: the `--` sentinel became null, and a per-line value beat the
415. * order-level one. What happens here is the roster join. peopleBoard and myDay compare
416. * `l.productionOwner === p.name`, so a raw label ("Marco-Acct7-Desk") has to
417. * become a name before the snapshot leaves this file, or every person reads as
418. * holding nothing. An unmapped label is surfaced every run, never silently
419. * rendered raw.
420. *
421. * The coverage guard catches assignment data that quietly stops arriving,
422. * which otherwise looks like "nobody has much work" rather than like a break.
423. * Zero coverage is reported as missing, never as zero.
424. *
425. * Mutates `lines` in place.
426. */
427. export function normalizeAssignments(
428. lines: OrderLine[],
429. coverage: AssignmentFieldCoverage,
430. ): string[] {
431. const warnings: string[] = []
432. for (const line of lines) {
433. for (const raw of [line.productionOwner, line.accountOwner]) {
434. if (raw !== null && isUnmappedAccount(raw)) {
435. warnings.push(
436. `Unmapped Plinth account "${raw}". Add it to config/plinth-people.ts. ` +
437. `Rendering a best-effort cleanup of the label until then.`,
438. )
439. }
440. }
441. line.productionOwner = displayName(line.productionOwner)
442. line.accountOwner = displayName(line.accountOwner)
443. }
445. if (coverage.total > 0) {
446. const fields = [
447. ['production_owner', coverage.production],
448. ['account_owner', coverage.accountOwner],
449. ] as const
450. for (const [field, n] of fields) {
451. const pct = Math.round((n / coverage.total) * 100)
452. if (n === 0) {
453. warnings.push(
454. `Plinth returned ${field} on 0 of ${coverage.total} fetched lines. The field arrived ` +
455. `2026-09-02 and has stopped arriving. Per-person order load is MISSING, not zero. ` +
456. `Ask the Plinth maintainer before reading anyone here as free.`,
457. )
458. } else if (pct < 50) {
459. warnings.push(
460. `${field} present on only ${n} of ${coverage.total} lines (${pct}%). Lines without it ` +
461. `render unassigned, so per-person counts are a floor, not a total.`,
462. )
463. }
464. }
465. }
466. return warnings
467. }
469. async function safely<T>(fn: () => Promise<T>, fallback: T): Promise<SourceResult<T>> {
470. try {
471. return { ok: true, data: await fn(), error: null }
472. } catch (err) {
473. return { ok: false, data: fallback, error: errorMessage(err) }
474. }
475. }
477. const iso = (d: Date) => d.toISOString().slice(0, 10)
479. // --- derived views ----------------------------------------------------------
481. /**
482. * Where the live work sits, by product stage. Feeds the stage bars.
483. *
484. * Product status throughout: the key, the label and the classification. The
485. * order and product layers share status names with different ids, so mixing
486. * them gives wrong counts and wrong colours with nothing on the chart to show
487. * it. Lines whose order has shipped are left out, because a stage bar is a
488. * picture of what is still in the building.
489. */
490. export function productStages(lines: OrderLine[]): StageCount[] {
491. const live = lines.filter((l) => !isOrderPastFulfilment(l.orderStatus, l.orderStatusId || null))
492. const counts = new Map<string, number>()
493. for (const l of live) counts.set(l.productStatus, (counts.get(l.productStatus) ?? 0) + 1)
494. return [...counts.entries()]
495. .map(([name, count]) => ({ id: name, name, count, class: classifyProduct(name) }))
496. .sort((a, b) => b.count - a.count)
497. }
499. export interface Headline {
500. ourMove: number
501. waitingOnClient: number
502. atVendor: number
503. designQueue: number
504. /**
505. * Leads that are genuinely still in play: not noise, and not in a terminal
506. * stage (Junk, Reorder Completed, Converted Lead, Out of Scope, Unconverted).
507. * Terminal is not noise; it is completed work, and on live data it can be
508. * most of the list. Counting completed work as pipeline is the same error as
509. * counting it as workload, one column over.
510. *
511. * A Converted Lead is the worst of them: it became an order, so counting it
512. * here double-counts the same job in two systems.
513. */
514. realLeads: number
515. /** Excluded as automation exhaust. Always shown; silent filtering is lying. */
516. noiseLeads: number
517. /** Excluded as finished. Also always shown: these are real, just not open. */
518. completedLeads: number
519. needsReply: number
520. unknownStatuses: string[]
521. /**
522. * Ninety commitments. Null when the source failed, never 0, because 0 means
523. * "everything is done" and a dead source means "we cannot see".
524. */
525. commitments: number | null
526. /** Rows behind those commitments. Higher than `commitments` when work is shared. */
527. assignments: number | null
528. /** Commitments carried by more than one person. */
529. sharedCommitments: number | null
530. /** Open to-dos past due and past at least one review gate. */
531. lateTodos: number | null
532. /**
533. * Lead stages present in the data but absent from config/bitrix-stages.ts,
534. * with counts. Every one of these defaults to 'ours' and therefore inflates
535. * `ourMove`. Non-empty means the headline is partly made of unclassified rows
536. * and must not be presented as team workload without saying so.
537. */
538. unknownLeadStages: { id: string; count: number }[]
539. /** How many of `ourMove`'s leads sit in an unclassified stage. */
540. ourMoveUnclassified: number
541. }
543. export function headline(snap: Snapshot): Headline {
544. const lines = snap.orderLines.data
545. const leads = snap.leads.data
546. const real = leads.filter((l) => !l.noise)
548. // Product status decides, gated on the order not having shipped. See
549. // classifyLine's note for why neither layer alone is right.
550. const byClass = (c: string) => lines.filter((l) => classifyLine(l) === c).length
551. const leadOurs = real.filter((l) => classifyLead(l.statusId, l.semantic) === 'ours').length
553. // Not noise, but finished. Held separately from `real` so it can be shown
554. // rather than silently subtracted, the same rule the noise count follows.
555. const completed = real.filter((l) => classifyLead(l.statusId, l.semantic) === 'terminal')
556. const stillOpen = real.filter((l) => classifyLead(l.statusId, l.semantic) !== 'terminal')
558. return {
559. ourMove: byClass('ours') + leadOurs,
560. waitingOnClient: byClass('client') + real.filter((l) => classifyLead(l.statusId, l.semantic) === 'waiting').length,
561. atVendor: byClass('vendor'),
562. designQueue: lines.filter((l) => isLineDesignQueue(l)).length,
563. realLeads: stillOpen.length,
564. noiseLeads: leads.length - real.length,
565. completedLeads: completed.length,
566. // "Client Replied": they are waiting on us. Always surfaces first.
567. needsReply: real.filter((l) => stageName(l.statusId) === 'Client Replied').length,
568. unknownStatuses: [...new Set(lines.map((l) => l.orderStatus).filter((s) => !isKnownOrderStatus(s)))],
569. commitments: snap.ninety.ok ? (snap.ninetySpread?.commitments ?? 0) : null,
570. assignments: snap.ninety.ok ? (snap.ninetySpread?.assignments ?? 0) : null,
571. sharedCommitments: snap.ninety.ok ? (snap.ninetySpread?.sharedCommitments ?? 0) : null,
572. lateTodos: snap.ninety.ok
573. ? snap.ninety.data.filter((t) => isActuallyLate(t.dueDate, new Date())).length
574. : null,
575. unknownLeadStages: unknownStageIds(real.map((l) => l.statusId)),
576. ourMoveUnclassified: real.filter(
577. (l) => classifyLead(l.statusId, l.semantic) === 'ours' && !LEAD_STAGES.some((s) => s.id === l.statusId),
578. ).length,
579. }
580. }
582. export interface PersonRow {
583. name: string
584. role: string
585. /** Orders where this person owes the next move. Null when not covered. */
586. plinthOurMove: number | null
587. /** Orders sitting with the client. Context, not bandwidth. */
588. plinthWaiting: number | null
589. /** Open Bitrix tasks, junk excluded. Null when not covered. */
590. taskCount: number | null
591. taskOverdue: number | null
592. /**
593. * Open Ninety to-dos owned by this person. Null when the source failed.
594. * Without them, people who hold no order lines read as idle on the panel
595. * titled "workload by person".
596. */
597. todos: number | null
598. /** Of those, past due and past a review gate. */
599. todosLate: number | null
600. /**
601. * Content Creation tracker rows this person owes a move on. Null when the
602. * sheet failed or does not cover them.
603. *
604. * This work lives nowhere else: Ninety carries one rollup row where the
605. * sheet carries a dozen jobs, so without it the designers look far emptier
606. * than they are.
607. */
608. sheetOurMove: number | null
609. /** Finished by them and waiting on the launch step. Context, not workload. */
610. sheetWaiting: number | null
611. /** Oldest thing they owe, in days. */
612. oldestDays: number | null
613. /** Sources that cover this person, for the row annotation. */
614. coverage: string[]
615. coverageNote: string | null
616. /** True when nothing can see this person. Must never render as a zero. */
617. untracked: boolean
618. }
620. export interface PeopleBoard {
621. rows: PersonRow[]
622. /** Tasks excluded as automation exhaust. Shown, never hidden. */
623. junkTasks: number
624. /** Plinth accounts holding work that belong to nobody on the roster. */
625. offRosterAccounts: string[]
626. /**
627. * The meeting-commitment window, in days. This board carries no meeting
628. * content and no per-person commitment counts: it is company-visible, and
629. * even a count ("Leadership sync: 4 items") discloses that a meeting
630. * happened and who was left out. Meeting content renders in exactly one
631. * place, `myDay()`, filtered by `meetingsFor()`. One renderer is a boundary
632. * you can test.
633. */
634. commitmentWindowDays: number
635. /**
636. * The Content Creation tracker, in numbers the page can state.
637. *
638. * `unclassified` is separate from every other count on purpose: see the
639. * comment on trackerCounts().
640. */
641. tracker: TrackerCounts
642. /**
643. * The Bitrix task join, as numbers instead of a claim about the method. A
644. * description of a join can read as working while it attributes nothing; a
645. * count cannot.
646. *
647. * `offRoster` is expected and not a gap: the directory holds far more accounts
648. * than the roster, and most are already inactive in Bitrix. What it is for
649. * is the opposite failure: a roster id going stale and that person's tasks
650. * quietly joining this bucket, which looks exactly like having nothing to do.
651. */
652. taskJoin: {
653. attributed: number
654. real: number
655. junk: number
656. offRoster: { id: string; tasks: number }[]
657. /** Roster people covered by Bitrix with no id pinned. Should be empty. */
658. unpinned: string[]
659. }
660. }
662. export interface TrackerCounts {
663. rows: number
664. ours: number
665. waiting: number
666. done: number
667. unclassified: number
668. unknownStatuses: string[]
669. unmappedOwners: string[]
670. /** Rows naming more than one owner. Counted per person, so this is context. */
671. shared: number
672. }
674. /**
675. * The tracker in one place, because two surfaces need the same numbers and a
676. * second implementation is a second answer.
677. *
678. * Unclassified is not folded into anything (rule 2): a default that stands in
679. * for knowledge must be surfaced every run. Rows with a blank or unknown
680. * Status are counted apart and named on the page.
681. */
682. export function trackerCounts(snap: Snapshot): TrackerCounts {
683. const rows = snap.sheet.data
684. const isClass = (t: TrackerTask, c: TrackerClass | null) => classifyTrackerStatus(t.status) === c
685. return {
686. rows: rows.length,
687. ours: rows.filter((t) => isClass(t, 'ours')).length,
688. waiting: rows.filter((t) => isClass(t, 'waiting')).length,
689. done: rows.filter((t) => isClass(t, 'terminal')).length,
690. unclassified: rows.filter((t) => isClass(t, null)).length,
691. unknownStatuses: [
692. ...new Set(rows.filter((t) => isClass(t, null)).map((t) => t.status.trim() || '(blank)')),
693. ].sort(),
694. unmappedOwners: unmappedTrackerOwners(rows.flatMap((t) => t.owners)),
695. shared: rows.filter((t) => t.shared).length,
696. }
697. }
699. /**
700. * The bird's-eye view: one row per person, every source folded in.
701. *
702. * The rule that keeps this honest: a person no source can see renders as
703. * "not tracked", never as 0. Those look identical at a glance and only one of
704. * them means free capacity.
705. *
706. * Partial coverage is normal and is annotated quietly rather than flagged.
707. */
708. export function peopleBoard(snap: Snapshot): PeopleBoard {
709. const lines = snap.orderLines.data
710. const { real: realTasks, junk } = partitionTasks(snap.tasks.data)
712. const offRoster = new Set<string>()
713. for (const l of lines) {
714. for (const label of [l.productionOwner, l.accountOwner]) {
715. if (label && !personByName(label)) offRoster.add(label)
716. }
717. }
719. // Ninety is company-wide, so every roster person is covered by it.
720. const todosByPerson = todoLoad(snap.ninety.data)
722. // Tracker rows, split by what the Status column means. A row with two owners
723. // counts for both of them here: it is one commitment but two people have to
724. // show up for it, and a per-person board is asking who has to show up.
725. // Company totals must not sum these columns for the same reason Ninety's
726. // assignments and commitments are different numbers.
727. const sheetBy = new Map<string, { ours: number; waiting: number }>()
728. for (const t of snap.sheet.data) {
729. const cls: TrackerClass | null = classifyTrackerStatus(t.status)
730. if (cls !== 'ours' && cls !== 'waiting') continue
731. for (const owner of t.owners) {
732. const person = personFromTrackerOwner(owner)
733. if (!person) continue
734. const cur = sheetBy.get(person.name) ?? { ours: 0, waiting: 0 }
735. cur[cls]++
736. sheetBy.set(person.name, cur)
737. }
738. }
740. const rows: PersonRow[] = MERIDIAN_PEOPLE.map((p: Person) => {
741. const coversPlinth = p.coveredBy.some((c) => c.startsWith('plinth-'))
742. const coversTasks = p.coveredBy.includes('bitrix-tasks')
743. const coversSheet = p.coveredBy.includes('content-tracker')
744. const theirSheet = coversSheet && snap.sheet.ok ? (sheetBy.get(p.name) ?? { ours: 0, waiting: 0 }) : null
745. const theirTodos = snap.ninety.ok
746. ? (todosByPerson.find((t) => t.name === p.name) ?? { open: 0, late: 0 })
747. : null
749. const mine = coversPlinth
750. ? lines.filter((l) => l.productionOwner === p.name || l.accountOwner === p.name)
751. : []
752. const ourMove = mine.filter((l) => classifyLine(l) === 'ours')
753. const waiting = mine.filter((l) => classifyLine(l) === 'client')
755. // By id: `responsibleId` is Bitrix's numeric user id, so a name lookup on
756. // it matches nobody. Roster ids are pinned from user.get.
757. const theirTasks = coversTasks
758. ? realTasks.filter((t) => personFromBitrix(t.responsibleId)?.name === p.name)
759. : []
761. const ages = [
762. ...ourMove.map((l) => l.ageDays),
763. ...theirTasks.map((t) => t.ageDays),
764. ].filter((d): d is number => d !== null)
766. return {
767. name: p.name,
768. role: p.role,
769. plinthOurMove: coversPlinth ? ourMove.length : null,
770. plinthWaiting: coversPlinth ? waiting.length : null,
771. taskCount: coversTasks ? theirTasks.length : null,
772. taskOverdue: coversTasks ? theirTasks.filter((t) => t.overdue).length : null,
773. oldestDays: ages.length ? Math.max(...ages) : null,
774. todos: theirTodos ? theirTodos.open : null,
775. todosLate: theirTodos ? theirTodos.late : null,
776. sheetOurMove: theirSheet ? theirSheet.ours : null,
777. sheetWaiting: theirSheet ? theirSheet.waiting : null,
778. coverage: p.coveredBy.map((c) => SOURCE_LABELS[c]),
779. coverageNote: p.coverageNote ?? null,
780. untracked: p.coveredBy.length === 0,
781. }
782. })
784. return {
785. rows,
786. junkTasks: junk.length,
787. tracker: trackerCounts(snap),
788. taskJoin: {
789. attributed: realTasks.filter((t) => personFromBitrix(t.responsibleId)).length,
790. real: realTasks.length,
791. junk: junk.length,
792. offRoster: offRosterBitrixIds(realTasks.map((t) => t.responsibleId)),
793. unpinned: unpinnedBitrixPeople(),
794. },
795. offRosterAccounts: [...offRoster].sort(),
796. commitmentWindowDays: COMMITMENT_WINDOW_DAYS,
797. }
798. }
800. /**
801. * One actionable row per order line: the number a person can paste into Plinth,
802. * and the name of whoever is holding it.
803. *
804. * A count of "44 our move" tells leadership the shape of the day; it tells a
805. * designer nothing they can act on. A list of order numbers with their name
806. * against them does.
807. *
808. * Rules carried over from the rest of the file, restated because they decide
809. * what is in this list:
810. * - Product status, gated on the order not having shipped. The product row
811. * says what the work is; the order says whether it is still here.
812. * - Only 'ours'. A line waiting on the client is a follow-up, not a queue.
813. * - `designer: null` renders as "unassigned", never as a blank cell. A blank
814. * reads as "no designer needed" and this is the opposite of that.
815. */
816. export interface OrderQueueRow {
817. /** "MD2639582". Pasteable into Plinth. See displayOrderNumber(). */
818. orderNumber: string
819. orderId: number
820. /**
821. * Null when the source has no product name, which is the case whenever the
822. * row came from an order-level export. Renders as "product not in export",
823. * never as the order number repeated back. A column that echoes the column
824. * beside it is noise wearing the costume of data.
825. */
826. product: string | null
827. quantity: number
828. /** The real one. Product-level. */
829. status: string
830. /** Designer (Plinth production_owner). Null when unassigned or not reported. */
831. designer: string | null
832. /** CS rep (Plinth account_owner). Null when uncovered. */
833. accountOwner: string | null
834. customer: string
835. company: string | null
836. ageDays: number | null
837. designQueue: boolean
838. }
840. export function orderQueue(lines: OrderLine[]): OrderQueueRow[] {
841. return lines
842. .filter((l) => classifyLine(l) === 'ours')
843. .map((l) => {
844. const orderNumber = displayOrderNumber(l.orderId, l.placedAt)
845. const title = l.productTitle?.trim() ?? ''
846. return {
847. orderNumber,
848. orderId: l.orderId,
849. // An order-level export puts the order number in the title slot. Echoing
850. // it back as a product name is worse than admitting we do not have one.
851. product: !title || title === orderNumber || title === String(l.orderId) ? null : title,
852. quantity: l.quantity,
853. status: l.productStatus || l.orderStatus,
854. designer: l.productionOwner,
855. accountOwner: l.accountOwner,
856. customer: l.customer,
857. company: l.company,
858. ageDays: l.ageDays,
859. designQueue: isLineDesignQueue(l),
860. }
861. })
862. // Oldest first. The top of this list is what is actually rotting.
863. .sort((a, b) => (b.ageDays ?? -1) - (a.ageDays ?? -1))
864. }
866. /** The same queue, grouped under the person holding it. Unassigned last. */
867. export function orderQueueByDesigner(lines: OrderLine[]): {
868. designer: string | null
869. rows: OrderQueueRow[]
870. }[] {
871. const rows = orderQueue(lines)
872. const by = new Map<string, OrderQueueRow[]>()
873. for (const r of rows) {
874. const key = r.designer ?? '\u{10FFFF}unassigned'
875. by.set(key, [...(by.get(key) ?? []), r])
876. }
877. return [...by.entries()]
878. .map(([key, list]) => ({
879. designer: key.startsWith('\u{10FFFF}') ? null : key,
880. rows: list,
881. }))
882. .sort((a, b) => {
883. if (a.designer === null) return 1
884. if (b.designer === null) return -1
885. return b.rows.length - a.rows.length
886. })
887. }
889. /**
890. * Open to-dos per person, using Meridian's review-gate rule rather than raw overdue.
891. *
892. * Not raw `overdue`, because nothing may be marked complete outside a Monday or Friday
893. * review, by policy. So raw days-overdue inflates every weekend and resets every
894. * Monday, which trains people to ignore the number. `isActuallyLate` means
895. * overdue and at least one review has passed since it came due.
896. *
897. * And the thing that must reach the briefing prompt: an open to-do does not mean
898. * unfinished work. It may be done and waiting for sign-off. Any sentence written
899. * from this data has to survive that being true.
900. */
901. export interface TodoLoad {
902. name: string
903. open: number
904. late: number
905. oldestGatesMissed: number
906. }
908. export function todoLoad(todos: Todo[], now = new Date()): TodoLoad[] {
909. const by = new Map<string, Todo[]>()
910. for (const t of todos) {
911. // Roster-resolved, not name-matched. Ninety spells people differently from
912. // config ("Samuel Whitaker" vs "Sam Whitaker"), so an equality join would
913. // drop people to zero without saying so. Unmapped owners keep their
914. // Ninety spelling here and are reported via dataHealth.unmappedTodoOwners.
915. const key = personFromNinety(t.owner.id, t.owner.name)?.name ?? t.owner.name
916. by.set(key, [...(by.get(key) ?? []), t])
917. }
918. return [...by.entries()]
919. .map(([name, list]) => ({
920. name,
921. open: list.length,
922. late: list.filter((t) => isActuallyLate(t.dueDate, now)).length,
923. oldestGatesMissed: list.reduce((m, t) => Math.max(m, reviewGatesMissed(t.dueDate, now)), 0),
924. }))
925. .sort((a, b) => b.late - a.late || b.open - a.open)
926. }
928. export function agedLeads(leads: Lead[], now = new Date()): (Lead & { ageDays: number })[] {
929. return leads
930. .filter((l) => !l.noise && l.createdAt)
931. .map((l) => ({
932. ...l,
933. ageDays: Math.floor((now.getTime() - Date.parse(l.createdAt!)) / 86_400_000),
934. }))
935. .sort((a, b) => b.ageDays - a.ageDays)
936. }