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

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

@@ -0,0 +1,146 @@
+/**
+ * Report numbering — the `RAP-2026-0042` printed on the sheet header of screen 14.
+ *
+ * The number is a billing document identifier: it is quoted on a PDF a client
+ * keeps, so it is allocated once, frozen, and **never reused**. Two consequences
+ * follow and are both enforced here:
+ *
+ *  1. **The highest number ever handed out wins, deleted reports included.** The
+ *     unique index only covers live rows, so a soft-deleted `RAP-2026-0042` would
+ *     otherwise let the next report take that number — and the client holding the
+ *     first PDF would find a different report behind it.
+ *  2. **Allocation races are settled by the database, not by a pre-read.** Reading
+ *     `MAX(sequence)` up front only narrows the window; two people generating a
+ *     report at the same moment would still both compute `0042`. The partial
+ *     unique index on `(organization_id, tenant_id, reference) WHERE deleted_at IS
+ *     NULL` makes the loser's insert fail, and the loser retries the whole
+ *     transaction against a max that now includes the winner's row. This is the
+ *     same shape `lib/timesheets-tasks/taskReference.ts` uses for `TT-142`.
+ *
+ * The year in the reference is the year the report is **issued**, not the year its
+ * period covers: a report generated in January for December's work is a January
+ * document, and its sequence belongs to the new year's run. The sheet prints the
+ * issue date beside the reference, so the two always agree.
+ */
+
+import { isUniqueViolation } from '@open-mercato/shared/lib/crud/errors'
+
+export const REPORT_REFERENCE_PREFIX = 'RAP'
+
+export const FIRST_REPORT_SEQUENCE_NUMBER = 1
+
+/** Width of the zero-padded run, matching the mockup's `RAP-2026-0042`. */
+export const REPORT_SEQUENCE_PAD = 4
+
+/**
+ * Attempts before the conflict is surfaced. Each retry costs one aborted
+ * transaction; an organization would need this many simultaneous generations
+ * landing on the same number for the last one to give up.
+ */
+export const REPORT_REFERENCE_MAX_ATTEMPTS = 5
+
+export type ReportReferenceAllocation = {
+  sequenceNumber: number
+  reference: string
+}
+
+export function reportReferenceYear(issuedAt: Date | null | undefined): number {
+  if (!(issuedAt instanceof Date) || Number.isNaN(issuedAt.getTime())) {
+    return new Date().getFullYear()
+  }
+  return issuedAt.getFullYear()
+}
+
+export function reportReferencePrefix(year: number): string {
+  return `${REPORT_REFERENCE_PREFIX}-${year}-`
+}
+
+export function formatReportReference(year: number, sequenceNumber: number): string {
+  const padded = String(Math.max(FIRST_REPORT_SEQUENCE_NUMBER, sequenceNumber)).padStart(
+    REPORT_SEQUENCE_PAD,
+    '0',
+  )
+  return `${reportReferencePrefix(year)}${padded}`
+}
+
+/**
+ * Reads the run number back out of a stored reference. Returns `null` for
+ * anything that is not this year's series, so a hand-edited or legacy reference
+ * can never inflate the next allocation.
+ */
+export function parseReportSequenceNumber(reference: unknown, year: number): number | null {
+  if (typeof reference !== 'string') return null
+  const prefix = reportReferencePrefix(year)
+  if (!reference.startsWith(prefix)) return null
+  const tail = reference.slice(prefix.length)
+  if (!/^\d+$/.test(tail)) return null
+  const parsed = Number.parseInt(tail, 10)
+  if (!Number.isFinite(parsed) || parsed < FIRST_REPORT_SEQUENCE_NUMBER) return null
+  return parsed
+}
+
+export function highestReportSequenceNumber(references: readonly unknown[], year: number): number {
+  let highest = 0
+  for (const reference of references) {
+    const parsed = parseReportSequenceNumber(reference, year)
+    if (parsed !== null && parsed > highest) highest = parsed
+  }
+  return highest
+}
+
+export function nextReportSequenceNumber(highestSequenceNumber: number | null | undefined): number {
+  if (typeof highestSequenceNumber !== 'number' || !Number.isFinite(highestSequenceNumber)) {
+    return FIRST_REPORT_SEQUENCE_NUMBER
+  }
+  const next = Math.floor(highestSequenceNumber) + 1
+  return next < FIRST_REPORT_SEQUENCE_NUMBER ? FIRST_REPORT_SEQUENCE_NUMBER : next
+}
+
+/**
+ * The candidate one attempt writes. A plain function of what that attempt read
+ * inside its own transaction, so nothing is carried between attempts.
+ */
+export function allocateReportReference(
+  year: number,
+  highestSequenceNumber: number | null | undefined,
+): ReportReferenceAllocation {
+  const sequenceNumber = nextReportSequenceNumber(highestSequenceNumber)
+  return { sequenceNumber, reference: formatReportReference(year, sequenceNumber) }
+}
+
+export function isReportReferenceConflict(err: unknown): boolean {
+  return isUniqueViolation(err)
+}
+
+export type ReportReferenceRetryOptions = {
+  maxAttempts?: number
+  isConflict?: (err: unknown) => boolean
+}
+
+/**
+ * Runs the create attempt until it wins the number or the budget runs out.
+ *
+ * `runAttempt` MUST re-read the organization's highest reference inside its own
+ * transaction — that is the whole point of retrying rather than pre-reading. A
+ * non-conflict error is rethrown immediately: only a lost race is worth
+ * repeating.
+ */
+export async function withReportReferenceRetry<T>(
+  runAttempt: (attempt: number) => Promise<T>,
+  options: ReportReferenceRetryOptions = {},
+): Promise<T> {
+  const maxAttempts = Math.max(1, options.maxAttempts ?? REPORT_REFERENCE_MAX_ATTEMPTS)
+  const isConflict = options.isConflict ?? isReportReferenceConflict
+  let lastError: unknown = null
+
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    try {
+      return await runAttempt(attempt)
+    } catch (err) {
+      if (!isConflict(err)) throw err
+      lastError = err
+    }
+  }
+
+  throw lastError
+}

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

@@ -0,0 +1,89 @@
+/**
+ * The raw, one-line-per-entry view of a report.
+ *
+ * Screen 14 note 3: the PDF mirrors the grouped sheet, while CSV and XLSX add
+ * the raw columns accounting actually needs — date, person, description — which
+ * the grouped sheet deliberately does not print for a client. Screen 15's
+ * "locked entries" table reads the same rows.
+ *
+ * Amounts come from `resolveEntryValues`, the same function the grouped sheet
+ * and the freeze records use, so an accountant reconciling the CSV against the
+ * PDF total never finds a discrepancy.
+ */
+
+import { formatReportMinutes, resolveEntryValues, sumAmounts } from './reportTotals'
+import type { ReportDirectory, ReportInputEntry, ReportInputProject } from './reportTotals'
+
+export type ReportRow = {
+  entryId: string
+  date: string
+  projectId: string
+  projectName: string
+  taskLabel: string
+  personLabel: string
+  description: string
+  rawMinutes: number
+  minutes: number
+  hours: string
+  isBillable: boolean
+  rate: number | null
+  amount: number | null
+  hasOverride: boolean
+  isFrozen: boolean
+}
+
+export type BuildReportRowsInput = {
+  entries: readonly ReportInputEntry[]
+  projects: readonly ReportInputProject[]
+  directory: ReportDirectory
+  labels: { unassignedTask: string; unassignedPerson: string }
+}
+
+export function buildReportRows(input: BuildReportRowsInput): ReportRow[] {
+  const projectById = new Map(input.projects.map((project) => [project.id, project]))
+  const rows = input.entries.map((entry) => {
+    const project = projectById.get(entry.timeProjectId) ?? null
+    const values = resolveEntryValues(entry, project)
+    const taskId = entry.taskId ?? null
+    return {
+      entryId: entry.id,
+      date: entry.date,
+      projectId: entry.timeProjectId,
+      projectName: project?.name ?? entry.timeProjectId,
+      taskLabel: (taskId ? input.directory.taskLabelById[taskId] : null) ?? input.labels.unassignedTask,
+      personLabel:
+        (entry.staffMemberId ? input.directory.personLabelById[entry.staffMemberId] : null) ??
+        input.labels.unassignedPerson,
+      description: entry.description ?? '',
+      rawMinutes: values.rawMinutes,
+      minutes: values.minutes,
+      hours: formatReportMinutes(values.minutes),
+      isBillable: values.isBillable,
+      rate: values.rate,
+      amount: values.amount,
+      hasOverride: values.hasOverride,
+      isFrozen: values.isFrozen,
+    } satisfies ReportRow
+  })
+
+  rows.sort(
+    (left, right) =>
+      left.date.localeCompare(right.date) ||
+      left.projectName.localeCompare(right.projectName) ||
+      left.taskLabel.localeCompare(right.taskLabel),
+  )
+  return rows
+}
+
+/**
+ * The rows' amounts add up to the report's grand total by construction — same
+ * per-entry values, summed in integer cents. Exposed so the export and the
+ * screen can assert it rather than assume it.
+ */
+export function sumReportRowAmounts(rows: readonly ReportRow[]): number {
+  return sumAmounts(rows.map((row) => row.amount))
+}
+
+export function sumReportRowMinutes(rows: readonly ReportRow[], billable: boolean): number {
+  return rows.reduce((total, row) => (row.isBillable === billable ? total + row.minutes : total), 0)
+}

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

@@ -0,0 +1,196 @@
+/**
+ * Client-side parsing for `GET .../reports/[id]/sheet`.
+ *
+ * Defensive for the same reason `reportConfigData` is: these numbers are printed
+ * on a document a client can dispute, so a shape surprise must yield a visibly
+ * empty sheet rather than a plausible wrong figure.
+ */
+
+import { parseReportPreview, readNumber, type PreviewGroup } from './reportConfigData'
+
+export type ReportEventType = 'closed' | 'unlocked' | 'exported'
+
+export type ReportHistoryEvent = {
+  id: string
+  eventType: ReportEventType
+  reason: string | null
+  actorUserId: string | null
+  metadata: Record<string, unknown> | null
+  createdAt: string | null
+}
+
+export type ReportSheetRow = {
+  entryId: string
+  date: string
+  projectName: string
+  taskLabel: string
+  personLabel: string
+  description: string
+  minutes: number
+  rawMinutes: number
+  hours: string
+  isBillable: boolean
+  rate: number | null
+  amount: number | null
+  hasOverride: boolean
+}
+
+export type ReportSheetHeader = {
+  id: string
+  reference: string
+  title: string
+  status: 'draft' | 'closed'
+  customerId: string | null
+  customerName: string | null
+  periodFrom: string | null
+  periodTo: string | null
+  currencyCode: string | null
+  grouping: 'project_task' | 'project_person' | 'project_day'
+  nonbillableMode: 'separate' | 'exclude'
+  includeAlreadyReported: boolean
+  showRates: boolean
+  roundingUnitMinutes: number
+  roundingDirection: string
+  closedAt: string | null
+  closedByUserId: string | null
+  timeProjectIds: string[]
+}
+
+export type ReportSheetPayload = {
+  report: ReportSheetHeader
+  groups: PreviewGroup[]
+  totals: {
+    entryCount: number
+    billableMinutes: number
+    nonbillableMinutes: number
+    totalAmount: number | null
+  }
+  alreadyReportedCount: number
+  alreadyReportedMinutes: number
+  rows: ReportSheetRow[]
+  rowCount: number
+  rowsTruncated: boolean
+  events: ReportHistoryEvent[]
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null
+}
+
+/** D-9: the customer name comes from the report's own snapshot, never a join. */
+export function readCustomerName(snapshot: unknown): string | null {
+  if (!snapshot || typeof snapshot !== 'object') return null
+  const row = snapshot as Record<string, unknown>
+  for (const key of ['name', 'displayName', 'display_name', 'legalName', 'legal_name']) {
+    const value = readString(row[key])
+    if (value) return value
+  }
+  return null
+}
+
+export function parseReportSheet(payload: unknown): ReportSheetPayload | null {
+  if (!payload || typeof payload !== 'object') return null
+  const row = payload as Record<string, unknown>
+  const reportRaw = row.report
+  if (!reportRaw || typeof reportRaw !== 'object') return null
+  const report = reportRaw as Record<string, unknown>
+  const id = readString(report.id)
+  if (!id) return null
+
+  // The grouped sheet has exactly the preview's shape, so it goes through the
+  // same parser — one place decides what a malformed group means.
+  const preview = parseReportPreview({
+    currencyCode: report.currencyCode,
+    grouping: report.grouping,
+    nonbillableMode: report.nonbillableMode,
+    includeAlreadyReported: report.includeAlreadyReported,
+    showRates: report.showRates,
+    projects: [],
+    groups: row.groups,
+    totals: row.totals,
+    alreadyReportedCount: row.alreadyReportedCount,
+    alreadyReportedMinutes: row.alreadyReportedMinutes,
+    alreadyReportedIn: row.alreadyReportedIn,
+    rounding: { unitMinutes: report.roundingUnitMinutes, direction: report.roundingDirection },
+  })
+  if (!preview) return null
+
+  return {
+    report: {
+      id,
+      reference: readString(report.reference) ?? '',
+      title: readString(report.title) ?? '',
+      status: report.status === 'closed' ? 'closed' : 'draft',
+      customerId: readString(report.customerId),
+      customerName: readCustomerName(report.customerSnapshot),
+      periodFrom: readString(report.periodFrom),
+      periodTo: readString(report.periodTo),
+      currencyCode: preview.currencyCode,
+      grouping: preview.grouping,
+      nonbillableMode: preview.nonbillableMode,
+      includeAlreadyReported: preview.includeAlreadyReported,
+      showRates: preview.showRates,
+      roundingUnitMinutes: preview.rounding.unitMinutes,
+      roundingDirection: preview.rounding.direction,
+      closedAt: readString(report.closedAt),
+      closedByUserId: readString(report.closedByUserId),
+      timeProjectIds: Array.isArray(report.timeProjectIds)
+        ? report.timeProjectIds.filter((value): value is string => typeof value === 'string')
+        : [],
+    },
+    groups: preview.groups,
+    totals: preview.totals,
+    alreadyReportedCount: preview.alreadyReportedCount,
+    alreadyReportedMinutes: preview.alreadyReportedMinutes,
+    rows: Array.isArray(row.rows)
+      ? row.rows
+          .map((entry) => {
+            if (!entry || typeof entry !== 'object') return null
+            const source = entry as Record<string, unknown>
+            const entryId = readString(source.entryId)
+            if (!entryId) return null
+            return {
+              entryId,
+              date: readString(source.date) ?? '',
+              projectName: readString(source.projectName) ?? '',
+              taskLabel: readString(source.taskLabel) ?? '',
+              personLabel: readString(source.personLabel) ?? '',
+              description: readString(source.description) ?? '',
+              minutes: readNumber(source.minutes) ?? 0,
+              rawMinutes: readNumber(source.rawMinutes) ?? 0,
+              hours: readString(source.hours) ?? '',
+              isBillable: source.isBillable !== false,
+              rate: readNumber(source.rate),
+              amount: readNumber(source.amount),
+              hasOverride: source.hasOverride === true,
+            } satisfies ReportSheetRow
+          })
+          .filter((entry): entry is ReportSheetRow => entry !== null)
+      : [],
+    rowCount: readNumber(row.rowCount) ?? 0,
+    rowsTruncated: row.rowsTruncated === true,
+    events: Array.isArray(row.events)
+      ? row.events
+          .map((entry) => {
+            if (!entry || typeof entry !== 'object') return null
+            const source = entry as Record<string, unknown>
+            const eventId = readString(source.id)
+            const eventType = source.eventType
+            if (!eventId) return null
+            if (eventType !== 'closed' && eventType !== 'unlocked' && eventType !== 'exported') return null
+            return {
+              id: eventId,
+              eventType,
+              reason: readString(source.reason),
+              actorUserId: readString(source.actorUserId),
+              metadata:
+                source.metadata && typeof source.metadata === 'object'
+                  ? (source.metadata as Record<string, unknown>)
+                  : null,
+              createdAt: readString(source.createdAt),
+            } satisfies ReportHistoryEvent
+          })
+          .filter((entry): entry is ReportHistoryEvent => entry !== null)
+      : [],
+  }
+}