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

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

@@ -0,0 +1,125 @@
+/**
+ * The sheet of screen 14, built once and reused by the detail page, the exports
+ * and the close command.
+ *
+ * The one rule that matters here is the difference between a draft and a closed
+ * report:
+ *
+ *  - a **draft** is computed live, so it moves when an entry is edited or the
+ *    rounding rule changes — by design, and screen 16 says so;
+ *  - a **closed** report renders exactly what it froze. Its lines come from the
+ *    `staff_time_report_entries` snapshots, so a later rounding change, a rate
+ *    change or an unlocked-and-edited entry cannot restate an invoice a client
+ *    already holds (risk R1).
+ *
+ * Both paths go through the same `computeReportTotals`, which is what keeps the
+ * preview, the sheet and the freeze records arithmetically identical.
+ */
+
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { StaffTimeReport } from '../../data/entities'
+import { loadReportData, type ReportDataScope } from './loadReportData'
+import { normalizeReportGrouping } from './reportGroupings'
+import {
+  computeReportTotals,
+  resolveReportCurrency,
+  type ReportDirectory,
+  type ReportGrouping,
+  type ReportInputEntry,
+  type ReportInputProject,
+  type ReportNonBillableMode,
+  type ReportTotals,
+} from './reportTotals'
+
+export type ReportSheetLabels = {
+  unassignedTask: string
+  unassignedPerson: string
+  nonbillableGroup: string
+}
+
+export type BuildReportSheetInput = {
+  em: EntityManager
+  scope: ReportDataScope
+  report: StaffTimeReport
+  timeProjectIds: readonly string[]
+  labels: ReportSheetLabels
+  /** Overrides the report's stored grouping, for an export that re-groups. */
+  grouping?: ReportGrouping
+}
+
+export type ReportSheet = {
+  totals: ReportTotals
+  entries: ReportInputEntry[]
+  projects: ReportInputProject[]
+  directory: ReportDirectory
+  currencyCode: string | null
+  grouping: ReportGrouping
+  nonbillableMode: ReportNonBillableMode
+  isClosed: boolean
+}
+
+function toDate(value: Date | string | null | undefined, fallback: Date): Date {
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value
+  if (typeof value === 'string') {
+    const parsed = new Date(value)
+    if (!Number.isNaN(parsed.getTime())) return parsed
+  }
+  return fallback
+}
+
+export async function buildReportSheet(input: BuildReportSheetInput): Promise<ReportSheet> {
+  const { em, scope, report, labels } = input
+  const isClosed = report.status === 'closed'
+  const grouping = normalizeReportGrouping(input.grouping ?? report.grouping)
+  const nonbillableMode = report.nonbillableMode as ReportNonBillableMode
+
+  const data = await loadReportData({
+    em,
+    scope,
+    timeProjectIds: input.timeProjectIds,
+    periodFrom: toDate(report.periodFrom, new Date(0)),
+    periodTo: toDate(report.periodTo, new Date()),
+  })
+
+  // A closed report shows only what it froze. An entry logged into the period
+  // AFTER the report closed is genuinely new work and belongs to the next
+  // report — screen 15 note 2 is explicit that the lock covers entries, not
+  // tasks, so logging more time on the same task must stay possible.
+  const entries = isClosed
+    ? data.entries.filter((entry) => entry.frozen?.reportId === report.id)
+    : data.entries
+
+  const totals = computeReportTotals({
+    entries,
+    projects: data.projects,
+    directory: data.directory,
+    options: {
+      grouping,
+      nonbillableMode,
+      includeAlreadyReported: report.includeAlreadyReported ?? false,
+    },
+    currentReportId: report.id,
+    labels,
+  })
+
+  const currency = resolveReportCurrency(
+    data.projects.map((project) => ({
+      id: project.id,
+      name: project.name,
+      currencyCode: project.currencyCode,
+    })),
+  )
+
+  return {
+    totals,
+    entries,
+    projects: data.projects,
+    directory: data.directory,
+    // A closed report keeps the currency it was closed with, even if a project
+    // has since been relabelled (risk R11).
+    currencyCode: isClosed ? report.currencyCode : currency.ok ? currency.currencyCode : report.currencyCode,
+    grouping,
+    nonbillableMode,
+    isClosed,
+  }
+}

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

@@ -0,0 +1,251 @@
+/**
+ * The one read that feeds every report surface: the live preview of screen 13,
+ * the sheet of screen 14, the close command's freeze records and the exports.
+ *
+ * It is deliberately a single loader rather than one query per surface, because
+ * a preview that counts different hours from the sheet it generates — or from
+ * the snapshot the close writes — is the failure mode this whole phase exists to
+ * prevent. Everything downstream consumes the same `ReportInputEntry[]`.
+ *
+ * Scoping is not optional here: every query carries `tenantId` and
+ * `organizationId`, and the project ids are expected to have been narrowed by
+ * `resolveProjectAccess` before they arrive.
+ */
+
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import {
+  StaffTeamMember,
+  StaffTimeEntry,
+  StaffTimeProject,
+  StaffTimeReport,
+  StaffTimeReportEntry,
+  StaffTimeTask,
+} from '../../data/entities'
+import type { FrozenEntryValues, ReportDirectory, ReportInputEntry, ReportInputProject } from './reportTotals'
+
+export type ReportDataScope = {
+  tenantId: string
+  organizationId: string
+}
+
+export type LoadReportDataInput = {
+  em: EntityManager
+  scope: ReportDataScope
+  timeProjectIds: readonly string[]
+  periodFrom: Date
+  periodTo: Date
+}
+
+export type ReportData = {
+  projects: ReportInputProject[]
+  entries: ReportInputEntry[]
+  directory: ReportDirectory
+  /** Raw project rows, kept so callers can assert currency without a second read. */
+  projectRows: StaffTimeProject[]
+}
+
+function toNumberOrNull(value: unknown): number | null {
+  if (value === null || value === undefined) return null
+  const parsed = typeof value === 'number' ? value : Number.parseFloat(String(value))
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+function toIsoDate(value: Date | string | null | undefined): string {
+  if (!value) return ''
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return ''
+    const year = value.getFullYear()
+    const month = String(value.getMonth() + 1).padStart(2, '0')
+    const day = String(value.getDate()).padStart(2, '0')
+    return `${year}-${month}-${day}`
+  }
+  return String(value).slice(0, 10)
+}
+
+/**
+ * D-2 caps nesting at one level, so a task's root is either itself or its
+ * parent. The fallback to the task's own id keeps a line visible even if a
+ * parent row has since been hard-removed.
+ */
+function resolveRootTaskId(taskId: string | null, parentById: ReadonlyMap<string, string | null>): string | null {
+  if (!taskId) return null
+  const parent = parentById.get(taskId)
+  if (!parent) return taskId
+  return parent
+}
+
+export async function loadReportData(input: LoadReportDataInput): Promise<ReportData> {
+  const { em, scope, periodFrom, periodTo } = input
+  const projectIds = Array.from(new Set(input.timeProjectIds.filter((id) => typeof id === 'string' && id.length > 0)))
+  if (projectIds.length === 0) {
+    return {
+      projects: [],
+      entries: [],
+      directory: { taskLabelById: {}, personLabelById: {} },
+      projectRows: [],
+    }
+  }
+
+  const projectRows = await em.find(StaffTimeProject, {
+    id: { $in: projectIds },
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    deletedAt: null,
+  })
+
+  const entryRows = await em.find(StaffTimeEntry, {
+    timeProjectId: { $in: projectIds },
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    deletedAt: null,
+    date: { $gte: periodFrom, $lte: periodTo },
+  })
+
+  const taskIds = Array.from(
+    new Set(entryRows.map((entry) => entry.taskId).filter((id): id is string => typeof id === 'string' && id.length > 0)),
+  )
+  const taskRows =
+    taskIds.length > 0
+      ? await em.find(StaffTimeTask, {
+          id: { $in: taskIds },
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId,
+        })
+      : []
+
+  // A child task's parent is not necessarily among the entries' tasks, so the
+  // parents are fetched in a second pass to give the rolled-up line its label.
+  const parentIds = Array.from(
+    new Set(
+      taskRows
+        .map((task) => task.parentTaskId)
+        .filter((id): id is string => typeof id === 'string' && id.length > 0 && !taskIds.includes(id)),
+    ),
+  )
+  const parentRows =
+    parentIds.length > 0
+      ? await em.find(StaffTimeTask, {
+          id: { $in: parentIds },
+          tenantId: scope.tenantId,
+          organizationId: scope.organizationId,
+        })
+      : []
+
+  const parentById = new Map<string, string | null>()
+  const taskLabelById: Record<string, string> = {}
+  for (const task of [...taskRows, ...parentRows]) {
+    parentById.set(task.id, task.parentTaskId ?? null)
+    taskLabelById[task.id] = task.title
+  }
+
+  const staffMemberIds = Array.from(
+    new Set(
+      entryRows
+        .map((entry) => entry.staffMemberId)
+        .filter((id): id is string => typeof id === 'string' && id.length > 0),
+    ),
+  )
+  const memberRows =
+    staffMemberIds.length > 0
+      ? await findWithDecryption(
+          em,
+          StaffTeamMember,
+          {
+            id: { $in: staffMemberIds },
+            tenantId: scope.tenantId,
+            organizationId: scope.organizationId,
+          },
+          {},
+          scope,
+        )
+      : []
+  const personLabelById: Record<string, string> = {}
+  for (const member of memberRows) personLabelById[member.id] = member.displayName
+
+  const frozenByEntryId = await loadFrozenValues(
+    em,
+    scope,
+    entryRows.map((entry) => entry.id),
+  )
+
+  const entries: ReportInputEntry[] = entryRows.map((entry) => ({
+    id: entry.id,
+    timeProjectId: entry.timeProjectId ?? '',
+    taskId: entry.taskId ?? null,
+    rootTaskId: resolveRootTaskId(entry.taskId ?? null, parentById),
+    staffMemberId: entry.staffMemberId ?? null,
+    date: toIsoDate(entry.date),
+    durationMinutes: entry.durationMinutes ?? 0,
+    roundedMinutes: entry.roundedMinutes ?? null,
+    isBillable: entry.isBillable ?? true,
+    rateOverrideAmount: toNumberOrNull(entry.rateOverrideAmount),
+    description: entry.notes ?? null,
+    frozen: frozenByEntryId.get(entry.id) ?? null,
+  }))
+
+  const projects: ReportInputProject[] = projectRows.map((project) => ({
+    id: project.id,
+    name: project.name,
+    hourlyRate: toNumberOrNull(project.hourlyRate),
+    currencyCode: project.currencyCode ?? null,
+  }))
+
+  return {
+    projects,
+    entries,
+    directory: { taskLabelById, personLabelById },
+    projectRows,
+  }
+}
+
+/**
+ * D-5's indexed lookup. `staff_time_report_entries` is authoritative for "has
+ * this hour been billed already?", and only rows belonging to a **closed**
+ * report count: a freeze record left behind by a report that has since been
+ * unlocked must not keep an hour out of the next invoice.
+ */
+export async function loadFrozenValues(
+  em: EntityManager,
+  scope: ReportDataScope,
+  timeEntryIds: readonly string[],
+): Promise<Map<string, FrozenEntryValues>> {
+  const ids = Array.from(new Set(timeEntryIds.filter((id) => typeof id === 'string' && id.length > 0)))
+  const result = new Map<string, FrozenEntryValues>()
+  if (ids.length === 0) return result
+
+  const rows = await em.find(StaffTimeReportEntry, {
+    timeEntryId: { $in: ids },
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+  })
+  if (rows.length === 0) return result
+
+  const reportIds = Array.from(new Set(rows.map((row) => row.reportId)))
+  const reports = await em.find(StaffTimeReport, {
+    id: { $in: reportIds },
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    status: 'closed',
+    deletedAt: null,
+  })
+  const reportById = new Map(reports.map((report) => [report.id, report]))
+
+  for (const row of rows) {
+    const report = reportById.get(row.reportId)
+    if (!report) continue
+    result.set(row.timeEntryId, {
+      reportId: report.id,
+      reference: report.reference ?? null,
+      title: report.title ?? null,
+      rawMinutes: row.frozenRawMinutes ?? 0,
+      roundedMinutes: row.frozenRoundedMinutes ?? 0,
+      rateAmount: toNumberOrNull(row.frozenRateAmount),
+      currencyCode: row.frozenCurrencyCode ?? null,
+      amount: toNumberOrNull(row.frozenAmount),
+      isBillable: row.frozenIsBillable ?? true,
+    })
+  }
+
+  return result
+}

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

@@ -0,0 +1,263 @@
+/**
+ * A minimal, dependency-free PDF writer — just enough to print the report sheet
+ * of screen 14 as the client-facing document US-G4 asks for.
+ *
+ * The repository has no PDF library and adding a production dependency is an
+ * "ask first" change, so this emits PDF 1.4 directly: a catalog, a pages tree,
+ * two base-14 fonts and one content stream per page. Nothing here is a general
+ * PDF toolkit; it lays out left-aligned and right-aligned text runs on a fixed
+ * grid, which is exactly what a table of hours and amounts needs.
+ *
+ * **Polish text is the reason for the encoding work.** The mockups are Polish
+ * and a report is a client-facing document, so `ą ć ę ł ń ś ź ż` must survive.
+ * WinAnsiEncoding covers `ó`/`Ó` and nothing else Polish, so the remaining
+ * sixteen glyphs are mapped into unused low code points through a `/Differences`
+ * array using their standard Adobe glyph names. A character with no mapping is
+ * rendered as `?` rather than being dropped, so a missing glyph is visible
+ * rather than silently changing a name.
+ */
+
+export type PdfTextAlign = 'left' | 'right'
+
+export type PdfCell = {
+  text: string
+  x: number
+  align?: PdfTextAlign
+  bold?: boolean
+  size?: number
+  /** Grey for hints and secondary text; black otherwise. */
+  muted?: boolean
+}
+
+export type PdfLine =
+  | { kind: 'cells'; cells: PdfCell[] }
+  | { kind: 'rule' }
+  | { kind: 'space'; height: number }
+
+export type PdfDocumentInput = {
+  title: string
+  lines: PdfLine[]
+}
+
+export const PDF_CONTENT_TYPE = 'application/pdf'
+
+const PAGE_WIDTH = 595.28
+const PAGE_HEIGHT = 841.89
+const MARGIN_X = 42
+const MARGIN_TOP = 56
+const MARGIN_BOTTOM = 48
+const LINE_HEIGHT = 14
+const DEFAULT_SIZE = 9
+
+/**
+ * Glyphs Polish needs that WinAnsiEncoding does not carry, parked in unused
+ * low code points and declared through /Differences.
+ */
+const DIFFERENCE_GLYPHS: Array<[string, number, string]> = [
+  ['ą', 1, 'aogonek'],
+  ['ć', 2, 'cacute'],
+  ['ę', 3, 'eogonek'],
+  ['ł', 4, 'lslash'],
+  ['ń', 5, 'nacute'],
+  ['ś', 6, 'sacute'],
+  ['ź', 7, 'zacute'],
+  ['ż', 8, 'zdotaccent'],
+  ['Ą', 9, 'Aogonek'],
+  ['Ć', 10, 'Cacute'],
+  ['Ę', 11, 'Eogonek'],
+  ['Ł', 12, 'Lslash'],
+  ['Ń', 13, 'Nacute'],
+  ['Ś', 14, 'Sacute'],
+  ['Ź', 15, 'Zacute'],
+  ['Ż', 16, 'Zdotaccent'],
+]
+
+/** Characters WinAnsiEncoding already carries at a code above ASCII. */
+const WIN_ANSI_EXTRAS: Record<string, number> = {
+  'ó': 0xf3,
+  'Ó': 0xd3,
+  'é': 0xe9,
+  'è': 0xe8,
+  'ä': 0xe4,
+  'ö': 0xf6,
+  'ü': 0xfc,
+  'ß': 0xdf,
+  'á': 0xe1,
+  'í': 0xed,
+  'ñ': 0xf1,
+  'ú': 0xfa,
+  '–': 0x96,
+  '—': 0x97,
+  '·': 0xb7,
+  '€': 0x80,
+  '„': 0x84,
+  '”': 0x94,
+  '’': 0x92,
+  '‘': 0x91,
+  '…': 0x85,
+  '°': 0xb0,
+  '×': 0xd7,
+}
+
+const ENCODING_MAP: Map<string, number> = (() => {
+  const map = new Map<string, number>()
+  for (let code = 32; code <= 126; code += 1) map.set(String.fromCharCode(code), code)
+  for (const [char, code] of Object.entries(WIN_ANSI_EXTRAS)) map.set(char, code)
+  for (const [char, code] of DIFFERENCE_GLYPHS) map.set(char, code)
+  return map
+})()
+
+export function encodePdfText(value: string): string {
+  let out = ''
+  for (const char of value) {
+    const code = ENCODING_MAP.get(char) ?? 0x3f
+    const byte = String.fromCharCode(code)
+    if (byte === '(' || byte === ')' || byte === '\\') out += `\\${byte}`
+    else out += byte
+  }
+  return out
+}
+
+/**
+ * Helvetica advance widths (1/1000 em) for the printable ASCII range, used to
+ * right-align the money and hours columns. Characters outside the table fall
+ * back to the average width, which is close enough for the accented letters and
+ * only ever shifts a right-aligned label by a hair.
+ */
+const HELVETICA_WIDTHS: Record<string, number> = (() => {
+  const widths: Record<string, number> = {}
+  const groups: Array<[number, string]> = [
+    [278, ' !I|jltfi.,:;\'`'],
+    [355, '"'],
+    [556, '#$0123456789+<=>~'],
+    [889, '%'],
+    [667, '&BCDEHKNRSUVXY'],
+    [333, '()[]{}/\\*-r'],
+    [584, '^'],
+    [500, '?_'],
+    [1015, '@'],
+    [722, 'ADGHOQ'],
+    [611, 'FPZ'],
+    [944, 'M'],
+    [778, 'W'],
+    [556, 'abcdeghknopqsu'],
+    [222, 'i'],
+    [500, 'yvz'],
+    [833, 'm'],
+    [722, 'w'],
+    [333, 'JLT'],
+  ]
+  for (const [width, chars] of groups) {
+    for (const char of chars) widths[char] = width
+  }
+  return widths
+})()
+
+export function measureText(text: string, size: number, bold: boolean): number {
+  let units = 0
+  for (const char of text) units += HELVETICA_WIDTHS[char] ?? 556
+  // Helvetica-Bold runs a touch wider; a flat factor is accurate enough for
+  // right-aligning a column and avoids shipping a second width table.
+  const factor = bold ? 1.03 : 1
+  return (units / 1000) * size * factor
+}
+
+type PageContent = string[]
+
+function buildPages(input: PdfDocumentInput): PageContent[] {
+  const pages: PageContent[] = []
+  let current: PageContent = []
+  let y = PAGE_HEIGHT - MARGIN_TOP
+
+  const pushPage = () => {
+    if (current.length > 0) pages.push(current)
+    current = []
+    y = PAGE_HEIGHT - MARGIN_TOP
+  }
+
+  for (const line of input.lines) {
+    const height = line.kind === 'space' ? line.height : LINE_HEIGHT
+    if (y - height < MARGIN_BOTTOM) pushPage()
+
+    if (line.kind === 'space') {
+      y -= line.height
+      continue
+    }
+    if (line.kind === 'rule') {
+      current.push(
+        `0.8 0.8 0.8 RG 0.5 w ${MARGIN_X} ${(y - 4).toFixed(2)} m ${(PAGE_WIDTH - MARGIN_X).toFixed(2)} ${(y - 4).toFixed(2)} l S`,
+      )
+      y -= LINE_HEIGHT
+      continue
+    }
+
+    for (const cell of line.cells) {
+      const size = cell.size ?? DEFAULT_SIZE
+      const font = cell.bold ? '/F2' : '/F1'
+      const width = measureText(cell.text, size, cell.bold === true)
+      const x = cell.align === 'right' ? cell.x - width : cell.x
+      const colour = cell.muted ? '0.45 0.45 0.45 rg' : '0 0 0 rg'
+      current.push(
+        `BT ${colour} ${font} ${size} Tf 1 0 0 1 ${x.toFixed(2)} ${y.toFixed(2)} Tm (${encodePdfText(cell.text)}) Tj ET`,
+      )
+    }
+    y -= LINE_HEIGHT
+  }
+
+  pushPage()
+  return pages.length > 0 ? pages : [[]]
+}
+
+export function buildPdf(input: PdfDocumentInput): Buffer {
+  const pages = buildPages(input)
+  const objects: string[] = []
+
+  const differences = DIFFERENCE_GLYPHS.map(([, code, glyph]) => `${code} /${glyph}`).join(' ')
+  const pageObjectStart = 6
+  const pageIds = pages.map((_, index) => pageObjectStart + index * 2)
+
+  objects[1] = '<< /Type /Catalog /Pages 2 0 R >>'
+  objects[2] = `<< /Type /Pages /Kids [${pageIds.map((id) => `${id} 0 R`).join(' ')}] /Count ${pages.length} >>`
+  objects[3] = '<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding 5 0 R >>'
+  objects[4] = '<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica-Bold /Encoding 5 0 R >>'
+  objects[5] = `<< /Type /Encoding /BaseEncoding /WinAnsiEncoding /Differences [${differences}] >>`
+
+  pages.forEach((content, index) => {
+    const pageId = pageIds[index]
+    const contentId = pageId + 1
+    const stream = content.join('\n')
+    objects[pageId] =
+      `<< /Type /Page /Parent 2 0 R /MediaBox [0 0 ${PAGE_WIDTH} ${PAGE_HEIGHT}] ` +
+      `/Resources << /Font << /F1 3 0 R /F2 4 0 R >> >> /Contents ${contentId} 0 R >>`
+    objects[contentId] = `<< /Length ${Buffer.byteLength(stream, 'latin1')} >>\nstream\n${stream}\nendstream`
+  })
+
+  const chunks: Buffer[] = [Buffer.from('%PDF-1.4\n', 'latin1')]
+  let offset = chunks[0].length
+  const offsets: number[] = []
+
+  for (let id = 1; id < objects.length; id += 1) {
+    const body = objects[id]
+    if (body === undefined) continue
+    offsets[id] = offset
+    const chunk = Buffer.from(`${id} 0 obj\n${body}\nendobj\n`, 'latin1')
+    chunks.push(chunk)
+    offset += chunk.length
+  }
+
+  const maxId = objects.length
+  const xrefOffset = offset
+  const xrefRows = ['0000000000 65535 f \n']
+  for (let id = 1; id < maxId; id += 1) {
+    const at = offsets[id]
+    xrefRows.push(at === undefined ? '0000000000 65535 f \n' : `${String(at).padStart(10, '0')} 00000 n \n`)
+  }
+  chunks.push(
+    Buffer.from(
+      `xref\n0 ${maxId}\n${xrefRows.join('')}trailer\n<< /Size ${maxId} /Root 1 0 R >>\nstartxref\n${xrefOffset}\n%%EOF\n`,
+      'latin1',
+    ),
+  )
+
+  return Buffer.concat(chunks)
+}