@open-mercato/core 0.7.1-develop.7178.1.ab93fbaf4e → 0.7.1-develop.7180.1.9717fbbb43

package/src/modules/staff/lib/timesheets-reports/reportExport.ts

@@ -0,0 +1,373 @@
+/**
+ * Turning a computed report into the three deliverables of US-G4.
+ *
+ * Screen 14 note 3 sets the split: **PDF mirrors the sheet** the client is
+ * shown — the same groups, the same rolled-up lines, the same grand total — and
+ * **CSV/XLSX add the raw columns** (date, person, description) an accounts
+ * department reconciles against. All three honour the current grouping, the
+ * filters, the rounding and the currency, because all three are built from the
+ * same `ReportSheet` the screen rendered.
+ *
+ * No format locks anything (screen 14 note 5). Exporting appends an `exported`
+ * event and nothing else.
+ */
+
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { serializeExport, type PreparedExport } from '@open-mercato/shared/lib/crud/exporters'
+import { buildPdf, PDF_CONTENT_TYPE, type PdfLine } from './pdf'
+import { buildXlsx, XLSX_CONTENT_TYPE } from './xlsx'
+import { formatReportMinutes, type ReportGroup, type ReportLine } from './reportTotals'
+import type { ReportRow } from './reportRows'
+import {
+  getReportExportFormat,
+  registerBuiltInReportExportFormat,
+  reportExportFormatIds,
+  type ReportExportFormat,
+} from './reportExportFormats'
+
+const logger = createLogger('staff').child({ component: 'timesheets-reports/reportExport' })
+
+export type { ReportExportFormat }
+
+/**
+ * EP-35: the accepted set is the registry, not a literal union, so a contributed
+ * format is accepted here and documented by the route's OpenAPI enum without
+ * either being edited.
+ */
+export function normalizeReportExportFormat(value: unknown): ReportExportFormat | null {
+  if (typeof value !== 'string') return null
+  return getReportExportFormat(value) ? value : null
+}
+
+export function supportedReportExportFormats(): string[] {
+  return reportExportFormatIds()
+}
+
+export type ReportExportLabels = {
+  documentTitle: string
+  issuedBy: string
+  reference: string
+  period: string
+  line: string
+  time: string
+  rate: string
+  amount: string
+  total: string
+  totalHint: string
+  nonbillable: string
+  overrideBadge: string
+  date: string
+  project: string
+  task: string
+  person: string
+  description: string
+  billable: string
+  yes: string
+  no: string
+  rawMinutes: string
+  roundedMinutes: string
+}
+
+export type ReportExportInput = {
+  reference: string
+  title: string
+  customerName: string
+  periodLabel: string
+  issuedByLabel: string | null
+  issuedAtLabel: string | null
+  currencyCode: string | null
+  showRates: boolean
+  groups: readonly ReportGroup[]
+  rows: readonly ReportRow[]
+  totals: { billableMinutes: number; nonbillableMinutes: number; totalAmount: number }
+  roundingLabel: string
+  labels: ReportExportLabels
+}
+
+export type SerializedReportExport = {
+  body: Buffer
+  contentType: string
+  filename: string
+}
+
+function formatAmount(value: number | null | undefined, currencyCode: string | null): string {
+  if (value === null || value === undefined) return '—'
+  const fixed = value.toFixed(2)
+  return currencyCode ? `${fixed} ${currencyCode}` : fixed
+}
+
+const COLUMN_LABEL_X = 42
+const COLUMN_TIME_X = 400
+const COLUMN_RATE_X = 470
+const COLUMN_AMOUNT_X = 553
+
+/** Recursion is one level deep by construction (D-2), but written generally. */
+function pdfLinesForLine(
+  line: ReportLine,
+  depth: number,
+  isNonBillable: boolean,
+  showRates: boolean,
+  currencyCode: string | null,
+  labels: ReportExportLabels,
+): PdfLine[] {
+  const label = line.hasOverride ? `${line.label} (${labels.overrideBadge})` : line.label
+  const cells = [
+    { text: `${'    '.repeat(depth)}${label}`, x: COLUMN_LABEL_X, muted: depth > 0 },
+    { text: formatReportMinutes(line.minutes), x: COLUMN_TIME_X, align: 'right' as const },
+  ]
+  if (showRates) {
+    cells.push({
+      text: isNonBillable ? '—' : formatAmount(line.rate, null),
+      x: COLUMN_RATE_X,
+      align: 'right' as const,
+    })
+  }
+  cells.push({
+    text: isNonBillable ? '—' : formatAmount(line.amount, null),
+    x: COLUMN_AMOUNT_X,
+    align: 'right' as const,
+  })
+
+  return [
+    { kind: 'cells', cells },
+    ...line.children.flatMap((child) =>
+      pdfLinesForLine(child, depth + 1, isNonBillable, showRates, currencyCode, labels),
+    ),
+  ]
+}
+
+/** The PDF mirrors the on-screen sheet, group for group and line for line. */
+export function buildReportPdfLines(input: ReportExportInput): PdfLine[] {
+  const { labels } = input
+  const lines: PdfLine[] = [
+    {
+      kind: 'cells',
+      cells: [{ text: labels.documentTitle, x: COLUMN_LABEL_X, size: 8, muted: true }],
+    },
+    { kind: 'cells', cells: [{ text: input.customerName, x: COLUMN_LABEL_X, size: 15, bold: true }] },
+    { kind: 'cells', cells: [{ text: input.periodLabel, x: COLUMN_LABEL_X, muted: true }] },
+    {
+      kind: 'cells',
+      cells: [
+        {
+          text: `${labels.reference}: ${input.reference}`,
+          x: COLUMN_AMOUNT_X,
+          align: 'right',
+          muted: true,
+        },
+      ],
+    },
+  ]
+  if (input.issuedByLabel) {
+    lines.push({
+      kind: 'cells',
+      cells: [
+        {
+          text: `${labels.issuedBy}: ${input.issuedByLabel}${input.issuedAtLabel ? ` · ${input.issuedAtLabel}` : ''}`,
+          x: COLUMN_AMOUNT_X,
+          align: 'right',
+          muted: true,
+        },
+      ],
+    })
+  }
+  lines.push({ kind: 'space', height: 10 }, { kind: 'rule' })
+
+  for (const group of input.groups) {
+    const isNonBillable = group.kind === 'nonbillable'
+    lines.push({
+      kind: 'cells',
+      cells: [
+        { text: group.label, x: COLUMN_LABEL_X, bold: true },
+        { text: formatReportMinutes(group.minutes), x: COLUMN_TIME_X, align: 'right', bold: true },
+        {
+          text: formatAmount(isNonBillable ? 0 : group.amount, input.currencyCode),
+          x: COLUMN_AMOUNT_X,
+          align: 'right',
+          bold: true,
+        },
+      ],
+    })
+    if (input.showRates && !isNonBillable && group.rate !== null) {
+      lines.push({
+        kind: 'cells',
+        cells: [{ text: `${formatAmount(group.rate, input.currencyCode)}/h`, x: COLUMN_LABEL_X, muted: true, size: 8 }],
+      })
+    }
+
+    const header = [
+      { text: labels.line, x: COLUMN_LABEL_X, size: 8, muted: true },
+      { text: labels.time, x: COLUMN_TIME_X, align: 'right' as const, size: 8, muted: true },
+    ]
+    if (input.showRates) {
+      header.push({ text: labels.rate, x: COLUMN_RATE_X, align: 'right' as const, size: 8, muted: true })
+    }
+    header.push({ text: labels.amount, x: COLUMN_AMOUNT_X, align: 'right' as const, size: 8, muted: true })
+    lines.push({ kind: 'cells', cells: header })
+
+    for (const line of group.lines) {
+      lines.push(
+        ...pdfLinesForLine(line, 0, isNonBillable, input.showRates, input.currencyCode, labels),
+      )
+    }
+    lines.push({ kind: 'space', height: 8 }, { kind: 'rule' })
+  }
+
+  lines.push(
+    {
+      kind: 'cells',
+      cells: [
+        { text: labels.total, x: COLUMN_LABEL_X, bold: true, size: 11 },
+        {
+          text: formatAmount(input.totals.totalAmount, input.currencyCode),
+          x: COLUMN_AMOUNT_X,
+          align: 'right',
+          bold: true,
+          size: 11,
+        },
+      ],
+    },
+    {
+      kind: 'cells',
+      cells: [
+        {
+          text: labels.totalHint
+            .replace('{billable}', formatReportMinutes(input.totals.billableMinutes))
+            .replace('{nonbillable}', formatReportMinutes(input.totals.nonbillableMinutes))
+            .replace('{rounding}', input.roundingLabel),
+          x: COLUMN_LABEL_X,
+          size: 8,
+          muted: true,
+        },
+      ],
+    },
+  )
+
+  return lines
+}
+
+/**
+ * The raw table. `rawMinutes` sits beside `roundedMinutes` on purpose: the
+ * difference between them IS the rounding, and an accountant asking why an
+ * amount is what it is should be able to see it rather than derive it.
+ */
+export function buildReportTable(input: ReportExportInput): PreparedExport {
+  const { labels } = input
+  const columns = [
+    { field: 'date', header: labels.date },
+    { field: 'project', header: labels.project },
+    { field: 'task', header: labels.task },
+    { field: 'person', header: labels.person },
+    { field: 'description', header: labels.description },
+    { field: 'rawMinutes', header: labels.rawMinutes },
+    { field: 'roundedMinutes', header: labels.roundedMinutes },
+    { field: 'hours', header: labels.time },
+    { field: 'billable', header: labels.billable },
+    ...(input.showRates ? [{ field: 'rate', header: labels.rate }] : []),
+    { field: 'amount', header: labels.amount },
+  ]
+
+  const rows = input.rows.map((row) => {
+    const record: Record<string, unknown> = {
+      date: row.date,
+      project: row.projectName,
+      task: row.taskLabel,
+      person: row.personLabel,
+      description: row.description,
+      rawMinutes: row.rawMinutes,
+      roundedMinutes: row.minutes,
+      hours: row.hours,
+      billable: row.isBillable ? labels.yes : labels.no,
+      amount: row.amount === null ? '' : row.amount.toFixed(2),
+    }
+    if (input.showRates) record.rate = row.rate === null ? '' : row.rate.toFixed(2)
+    return record
+  })
+
+  return { columns, rows }
+}
+
+function exportBaseName(input: ReportExportInput): string {
+  return input.reference || 'report'
+}
+
+registerBuiltInReportExportFormat({
+  id: 'pdf',
+  labelKey: 'staff.time_tracking.reports.export.format.pdf',
+  mimeType: PDF_CONTENT_TYPE,
+  extension: 'pdf',
+  serialize: (input) => ({
+    body: buildPdf({ title: input.title, lines: buildReportPdfLines(input) }),
+    contentType: PDF_CONTENT_TYPE,
+    filename: `${exportBaseName(input)}.pdf`,
+  }),
+})
+
+registerBuiltInReportExportFormat({
+  id: 'csv',
+  labelKey: 'staff.time_tracking.reports.export.format.csv',
+  mimeType: 'text/csv',
+  extension: 'csv',
+  serialize: (input) => {
+    const serialized = serializeExport(buildReportTable(input), 'csv')
+    return {
+      // The BOM is what makes Excel open a UTF-8 CSV with Polish names intact
+      // instead of mojibake; every other consumer ignores it.
+      body: Buffer.concat([Buffer.from('', 'utf8'), Buffer.from(serialized.body, 'utf8')]),
+      contentType: serialized.contentType,
+      filename: `${exportBaseName(input)}.csv`,
+    }
+  },
+})
+
+registerBuiltInReportExportFormat({
+  id: 'xlsx',
+  labelKey: 'staff.time_tracking.reports.export.format.xlsx',
+  mimeType: XLSX_CONTENT_TYPE,
+  extension: 'xlsx',
+  serialize: (input) => {
+    const table = buildReportTable(input)
+    const rows = [
+      table.columns.map((column) => column.header),
+      ...table.rows.map((row) =>
+        table.columns.map((column) => {
+          const value = row[column.field]
+          if (column.field === 'rate' || column.field === 'amount') {
+            const parsed = typeof value === 'string' && value.length > 0 ? Number.parseFloat(value) : null
+            return parsed !== null && Number.isFinite(parsed) ? parsed : ''
+          }
+          return typeof value === 'number' ? value : value === null || value === undefined ? '' : String(value)
+        }),
+      ),
+    ]
+    return {
+      body: buildXlsx({ name: exportBaseName(input).slice(0, 31), rows }),
+      contentType: XLSX_CONTENT_TYPE,
+      filename: `${exportBaseName(input)}.xlsx`,
+    }
+  },
+})
+
+/**
+ * A contributed `serialize` is the one strategy whose failure cannot be absorbed:
+ * the caller asked for a named format and every fallback would answer with bytes of
+ * a different type under the requested filename and MIME. So the throw propagates —
+ * but it is caught and re-raised as an internal error naming the format, so the one
+ * request fails with something diagnosable instead of a stack trace from a third
+ * party's serializer.
+ */
+export function serializeReportExport(
+  format: ReportExportFormat,
+  input: ReportExportInput,
+): SerializedReportExport {
+  const definition = getReportExportFormat(format)
+  if (!definition) {
+    throw new Error(`[internal] unknown report export format: ${String(format)}`)
+  }
+  try {
+    return definition.serialize(input)
+  } catch (err) {
+    logger.error('a report export format failed to serialize', { format: definition.id, err })
+    throw new Error(`[internal] report export format ${definition.id} failed to serialize`)
+  }
+}

package/src/modules/staff/lib/timesheets-reports/reportExportFormats.ts

@@ -0,0 +1,71 @@
+/**
+ * EP-35 — the report export format registry.
+ *
+ * It lives beside `reportExport.ts` rather than inside it because the built-in
+ * `pdf`/`csv`/`xlsx` serializers ARE that file: keeping the registry here lets
+ * `reportExport.ts` register into it at module load without an import cycle.
+ *
+ * Every consumer of the format list — `normalizeReportExportFormat`, the export
+ * route's OpenAPI query enum, the 400 body listing the accepted formats — reads
+ * this registry, so a contributed format is accepted and documented without
+ * touching either file.
+ */
+
+import { extensionPoints } from '@open-mercato/core/modules/staff/extension-points'
+import { createStrategyRegistry, BUILT_IN_STRATEGY_PRIORITY } from '../time-tracking/registries/registry'
+import type { ReportExportInput, SerializedReportExport } from './reportExport'
+
+export const BUILT_IN_REPORT_EXPORT_FORMAT_IDS = ['pdf', 'csv', 'xlsx'] as const
+
+export type BuiltInReportExportFormat = (typeof BUILT_IN_REPORT_EXPORT_FORMAT_IDS)[number]
+
+/**
+ * Widened from the original `'pdf' | 'csv' | 'xlsx'` union so a contributed id
+ * is assignable. The union arm keeps the three built-ins as completions.
+ */
+export type ReportExportFormat = BuiltInReportExportFormat | (string & {})
+
+export type ReportExportFormatDefinition = {
+  id: string
+  labelKey: string
+  mimeType: string
+  extension: string
+  priority?: number
+  serialize(input: ReportExportInput): SerializedReportExport
+}
+
+export const REPORT_EXPORT_FORMAT_REGISTRY_ID = extensionPoints.hosts.reportExportFormatRegistry.spotId
+
+const registry = createStrategyRegistry<ReportExportFormatDefinition>(REPORT_EXPORT_FORMAT_REGISTRY_ID)
+
+export function registerReportExportFormat(format: ReportExportFormatDefinition): () => void {
+  return registry.register(format)
+}
+
+/**
+ * The three formats the module ships. They register at the built-in priority so
+ * `listReportExportFormats()` orders any contribution ahead of them.
+ */
+export function registerBuiltInReportExportFormat(
+  format: Omit<ReportExportFormatDefinition, 'priority'>,
+): () => void {
+  registry.registerBuiltIn({ ...format, priority: BUILT_IN_STRATEGY_PRIORITY })
+  return () => {}
+}
+
+export function listReportExportFormats(): ReportExportFormatDefinition[] {
+  return registry.list()
+}
+
+/** Built-ins first, in the order the module shipped them, then contributions. */
+export function reportExportFormatIds(): string[] {
+  const builtIn = BUILT_IN_REPORT_EXPORT_FORMAT_IDS.filter((id) => registry.has(id))
+  const contributed = registry.ids().filter((id) => !builtIn.includes(id as BuiltInReportExportFormat))
+  return [...builtIn, ...contributed]
+}
+
+export function getReportExportFormat(
+  id: string | null | undefined,
+): ReportExportFormatDefinition | null {
+  return registry.get(id)
+}

package/src/modules/staff/lib/timesheets-reports/reportGroupings.ts

@@ -0,0 +1,153 @@
+/**
+ * EP-36 — the report grouping strategy registry.
+ *
+ * A grouping decides two things and nothing else: which line an entry lands on
+ * (`groupOf`, which may name a parent line so D-2's inclusive task rollup keeps
+ * working) and how the finished lines are ordered (`sort`). Labelling is a third
+ * concern the strategy owns because only it knows which directory to look the
+ * key up in.
+ *
+ * The three built-ins reproduce `reportTotals.ts`'s original `lineKeyFor` /
+ * `labelFor` / line sort exactly. The registry lives in its own file so
+ * `reportTotals.ts` can register into it at module load without an import cycle.
+ */
+
+import { extensionPoints } from '@open-mercato/core/modules/staff/extension-points'
+import { createStrategyRegistry, BUILT_IN_STRATEGY_PRIORITY } from '../time-tracking/registries/registry'
+import type { ReportDirectory, ReportInputEntry, ReportLine } from './reportTotals'
+
+export const BUILT_IN_REPORT_GROUPING_IDS = ['project_task', 'project_person', 'project_day'] as const
+
+export type BuiltInReportGrouping = (typeof BUILT_IN_REPORT_GROUPING_IDS)[number]
+
+/**
+ * Widened from the original three-way union so a contributed grouping id is
+ * assignable. The union arm keeps the built-ins as completions.
+ */
+export type ReportGrouping = BuiltInReportGrouping | (string & {})
+
+export type ReportGroupingFallbackLabels = {
+  unassignedTask: string
+  unassignedPerson: string
+  nonbillableGroup: string
+}
+
+export type ReportGroupingLabelContext = {
+  directory: ReportDirectory
+  fallbacks: ReportGroupingFallbackLabels
+}
+
+export type ReportGroupingKey = {
+  key: string
+  parentKey: string | null
+}
+
+export type ReportGroupingStrategy = {
+  id: string
+  labelKey: string
+  priority?: number
+  groupOf(entry: ReportInputEntry): ReportGroupingKey
+  labelOf(key: string, ctx: ReportGroupingLabelContext): string
+  sort(left: ReportLine, right: ReportLine): number
+}
+
+export const REPORT_GROUPING_REGISTRY_ID = extensionPoints.hosts.reportGroupingRegistry.spotId
+
+const registry = createStrategyRegistry<ReportGroupingStrategy>(REPORT_GROUPING_REGISTRY_ID)
+
+export function registerReportGrouping(grouping: ReportGroupingStrategy): () => void {
+  return registry.register(grouping)
+}
+
+export function listReportGroupings(): ReportGroupingStrategy[] {
+  return registry.list()
+}
+
+export function getReportGrouping(id: string | null | undefined): ReportGroupingStrategy | null {
+  return registry.get(id)
+}
+
+export function hasReportGrouping(id: string | null | undefined): boolean {
+  return registry.has(id)
+}
+
+/** Identity, not membership of `BUILT_IN_REPORT_GROUPING_IDS` — a contribution cannot claim one. */
+export function isBuiltInReportGrouping(id: string | null | undefined): boolean {
+  return registry.isBuiltIn(id)
+}
+
+/** Built-ins first, in the order the module shipped them, then contributions. */
+export function reportGroupingIds(): string[] {
+  const builtIn = BUILT_IN_REPORT_GROUPING_IDS.filter((id) => registry.has(id))
+  const contributed = registry.ids().filter((id) => !builtIn.includes(id as BuiltInReportGrouping))
+  return [...builtIn, ...contributed]
+}
+
+export const DEFAULT_REPORT_GROUPING: BuiltInReportGrouping = 'project_task'
+
+/**
+ * The grouping a report was stored with, coerced back to something the registry
+ * can serve. An id whose contributing module has since been removed falls back
+ * to the module default rather than producing an ungrouped sheet.
+ */
+export function normalizeReportGrouping(value: unknown): ReportGrouping {
+  if (typeof value === 'string' && registry.has(value)) return value
+  return DEFAULT_REPORT_GROUPING
+}
+
+/**
+ * The line key an entry with nothing to group by lands on. It is part of the
+ * grouping contract rather than a `reportTotals` private, because a contributed
+ * grouping has to be able to produce the same "unassigned" bucket.
+ */
+export const UNASSIGNED_LINE_KEY = '__unassigned__'
+
+/** The line ordering every built-in grouping shares: longest first, then by label. */
+function sortByMinutesThenLabel(left: ReportLine, right: ReportLine): number {
+  return right.minutes - left.minutes || left.label.localeCompare(right.label)
+}
+
+function taskLineKey(entry: ReportInputEntry): ReportGroupingKey {
+  const rootId = entry.rootTaskId ?? entry.taskId ?? null
+  const taskId = entry.taskId ?? null
+  if (!rootId) return { key: UNASSIGNED_LINE_KEY, parentKey: null }
+  // D-2: a child's time lands on the parent's line and is expandable underneath.
+  if (taskId && taskId !== rootId) return { key: taskId, parentKey: rootId }
+  return { key: rootId, parentKey: null }
+}
+
+function registerBuiltInReportGrouping(
+  grouping: Omit<ReportGroupingStrategy, 'priority'>,
+): ReportGroupingStrategy {
+  return registry.registerBuiltIn({ ...grouping, priority: BUILT_IN_STRATEGY_PRIORITY })
+}
+
+registerBuiltInReportGrouping({
+  id: 'project_task',
+  labelKey: 'staff.time_tracking.reports.grouping.project_task',
+  groupOf: taskLineKey,
+  labelOf: (key, ctx) =>
+    key === UNASSIGNED_LINE_KEY
+      ? ctx.fallbacks.unassignedTask
+      : ctx.directory.taskLabelById[key] ?? ctx.fallbacks.unassignedTask,
+  sort: sortByMinutesThenLabel,
+})
+
+registerBuiltInReportGrouping({
+  id: 'project_person',
+  labelKey: 'staff.time_tracking.reports.grouping.project_person',
+  groupOf: (entry) => ({ key: entry.staffMemberId ?? UNASSIGNED_LINE_KEY, parentKey: null }),
+  labelOf: (key, ctx) =>
+    key === UNASSIGNED_LINE_KEY
+      ? ctx.fallbacks.unassignedPerson
+      : ctx.directory.personLabelById[key] ?? ctx.fallbacks.unassignedPerson,
+  sort: sortByMinutesThenLabel,
+})
+
+registerBuiltInReportGrouping({
+  id: 'project_day',
+  labelKey: 'staff.time_tracking.reports.grouping.project_day',
+  groupOf: (entry) => ({ key: entry.date || UNASSIGNED_LINE_KEY, parentKey: null }),
+  labelOf: (key, ctx) => (key === UNASSIGNED_LINE_KEY ? ctx.fallbacks.unassignedTask : key),
+  sort: sortByMinutesThenLabel,
+})

package/src/modules/staff/lib/timesheets-reports/reportLabels.ts

@@ -0,0 +1,23 @@
+/**
+ * The three fallback labels a report sheet needs when a line has nothing to name
+ * itself with. They live here rather than in a route because the close command,
+ * the preview, the sheet and the exports must all use the same ones — a freeze
+ * record labelled "No task" and a PDF labelled "Unassigned" would be the same
+ * line reading differently in two places a client can compare.
+ */
+
+export type ReportLabelTranslate = (key: string, fallback: string) => string
+
+export type ReportSheetLabels = {
+  unassignedTask: string
+  unassignedPerson: string
+  nonbillableGroup: string
+}
+
+export function reportSheetLabels(translate: ReportLabelTranslate): ReportSheetLabels {
+  return {
+    unassignedTask: translate('staff.time_tracking.reports.sheet.noTask', 'No task'),
+    unassignedPerson: translate('staff.time_tracking.reports.sheet.noPerson', 'Unassigned'),
+    nonbillableGroup: translate('staff.time_tracking.reports.sheet.nonbillable', 'Non-billable time'),
+  }
+}