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

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

@@ -0,0 +1,207 @@
+/**
+ * A minimal, dependency-free single-sheet XLSX writer.
+ *
+ * US-G4 asks for CSV *and* XLSX because back-offices differ: CSV is what an
+ * import script wants, XLSX is what an accountant opens. The repository has no
+ * spreadsheet library and adding a production dependency is an "ask first"
+ * change, so this writes the format directly — an XLSX file is a ZIP of five
+ * small XML parts, and Node ships both DEFLATE (`node:zlib`) and everything else
+ * needed.
+ *
+ * Numbers are written as numbers (`<v>`), not as text, so a column of amounts
+ * sums in Excel rather than needing a re-type. Strings go in as inline strings
+ * rather than through a shared-strings table: it costs a few bytes on repeated
+ * values and removes an entire index that could go out of sync.
+ */
+
+import { deflateRawSync } from 'node:zlib'
+
+export type XlsxCell = string | number | null | undefined
+
+export type XlsxSheet = {
+  name: string
+  rows: XlsxCell[][]
+}
+
+const CRC_TABLE = (() => {
+  const table = new Int32Array(256)
+  for (let index = 0; index < 256; index += 1) {
+    let value = index
+    for (let bit = 0; bit < 8; bit += 1) {
+      value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1
+    }
+    table[index] = value
+  }
+  return table
+})()
+
+function crc32(data: Buffer): number {
+  let crc = -1
+  for (let index = 0; index < data.length; index += 1) {
+    crc = (crc >>> 8) ^ CRC_TABLE[(crc ^ data[index]) & 0xff]
+  }
+  return (crc ^ -1) >>> 0
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+    // Excel refuses a file containing raw control characters.
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, '')
+}
+
+/** `0 -> A`, `26 -> AA`. Spreadsheet columns are bijective base-26. */
+export function columnName(index: number): string {
+  let name = ''
+  let remaining = index + 1
+  while (remaining > 0) {
+    const rest = (remaining - 1) % 26
+    name = String.fromCharCode(65 + rest) + name
+    remaining = Math.floor((remaining - 1) / 26)
+  }
+  return name
+}
+
+function cellXml(value: XlsxCell, reference: string): string {
+  if (value === null || value === undefined || value === '') return ''
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return `<c r="${reference}"><v>${value}</v></c>`
+  }
+  return `<c r="${reference}" t="inlineStr"><is><t xml:space="preserve">${escapeXml(String(value))}</t></is></c>`
+}
+
+export function buildSheetXml(sheet: XlsxSheet): string {
+  const rows = sheet.rows
+    .map((row, rowIndex) => {
+      const cells = row.map((value, columnIndex) => cellXml(value, `${columnName(columnIndex)}${rowIndex + 1}`)).join('')
+      return `<row r="${rowIndex + 1}">${cells}</row>`
+    })
+    .join('')
+  return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"><sheetData>${rows}</sheetData></worksheet>`
+}
+
+type ZipEntry = { name: string; data: Buffer }
+
+function zipEntries(entries: readonly ZipEntry[]): Buffer {
+  const locals: Buffer[] = []
+  const centrals: Buffer[] = []
+  let offset = 0
+
+  for (const entry of entries) {
+    const nameBuffer = Buffer.from(entry.name, 'utf8')
+    const compressed = deflateRawSync(entry.data)
+    const crc = crc32(entry.data)
+
+    const local = Buffer.alloc(30 + nameBuffer.length)
+    local.writeUInt32LE(0x04034b50, 0)
+    local.writeUInt16LE(20, 4)
+    // Bit 11 marks the filename as UTF-8; all names here are ASCII, but the flag
+    // costs nothing and keeps the file honest if one ever is not.
+    local.writeUInt16LE(0x0800, 6)
+    local.writeUInt16LE(8, 8)
+    local.writeUInt16LE(0, 10)
+    local.writeUInt16LE(0, 12)
+    local.writeUInt32LE(crc, 14)
+    local.writeUInt32LE(compressed.length, 18)
+    local.writeUInt32LE(entry.data.length, 22)
+    local.writeUInt16LE(nameBuffer.length, 26)
+    local.writeUInt16LE(0, 28)
+    nameBuffer.copy(local, 30)
+
+    const central = Buffer.alloc(46 + nameBuffer.length)
+    central.writeUInt32LE(0x02014b50, 0)
+    central.writeUInt16LE(20, 4)
+    central.writeUInt16LE(20, 6)
+    central.writeUInt16LE(0x0800, 8)
+    central.writeUInt16LE(8, 10)
+    central.writeUInt16LE(0, 12)
+    central.writeUInt16LE(0, 14)
+    central.writeUInt32LE(crc, 16)
+    central.writeUInt32LE(compressed.length, 20)
+    central.writeUInt32LE(entry.data.length, 24)
+    central.writeUInt16LE(nameBuffer.length, 28)
+    central.writeUInt16LE(0, 30)
+    central.writeUInt16LE(0, 32)
+    central.writeUInt16LE(0, 34)
+    central.writeUInt16LE(0, 36)
+    central.writeUInt32LE(0, 38)
+    central.writeUInt32LE(offset, 42)
+    nameBuffer.copy(central, 46)
+
+    locals.push(local, compressed)
+    centrals.push(central)
+    offset += local.length + compressed.length
+  }
+
+  const centralDirectory = Buffer.concat(centrals)
+  const end = Buffer.alloc(22)
+  end.writeUInt32LE(0x06054b50, 0)
+  end.writeUInt16LE(0, 4)
+  end.writeUInt16LE(0, 6)
+  end.writeUInt16LE(entries.length, 8)
+  end.writeUInt16LE(entries.length, 10)
+  end.writeUInt32LE(centralDirectory.length, 12)
+  end.writeUInt32LE(offset, 16)
+  end.writeUInt16LE(0, 20)
+
+  return Buffer.concat([...locals, centralDirectory, end])
+}
+
+export const XLSX_CONTENT_TYPE =
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+
+export function buildXlsx(sheet: XlsxSheet): Buffer {
+  const safeName = escapeXml(sheet.name.slice(0, 31) || 'Sheet1')
+  const parts: ZipEntry[] = [
+    {
+      name: '[Content_Types].xml',
+      data: Buffer.from(
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+          '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">' +
+          '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>' +
+          '<Default Extension="xml" ContentType="application/xml"/>' +
+          '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>' +
+          '<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>' +
+          '</Types>',
+        'utf8',
+      ),
+    },
+    {
+      name: '_rels/.rels',
+      data: Buffer.from(
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+          '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+          '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>' +
+          '</Relationships>',
+        'utf8',
+      ),
+    },
+    {
+      name: 'xl/workbook.xml',
+      data: Buffer.from(
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+          '<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">' +
+          `<sheets><sheet name="${safeName}" sheetId="1" r:id="rId1"/></sheets>` +
+          '</workbook>',
+        'utf8',
+      ),
+    },
+    {
+      name: 'xl/_rels/workbook.xml.rels',
+      data: Buffer.from(
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+          '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+          '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>' +
+          '</Relationships>',
+        'utf8',
+      ),
+    },
+    { name: 'xl/worksheets/sheet1.xml', data: Buffer.from(buildSheetXml(sheet), 'utf8') },
+  ]
+
+  return zipEntries(parts)
+}

package/src/modules/staff/lib/timesheets-tasks/computeTaskRollups.ts

@@ -0,0 +1,238 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { loggedMinutes, type RollupEntry, type RollupTask, type TaskRollup } from '../time-tracking/rollup'
+
+/**
+ * Per-task hours for the board, the drawer and the subtask checklist.
+ *
+ * D-2 fixes one rule for every surface: a parent always shows the inclusive rollup,
+ * `own entries + Σ children's entries`. The arithmetic itself belongs to
+ * `lib/time-tracking/rollup.ts` and is not repeated here — this module's job is to
+ * hand that helper a complete, access-scoped picture of the page in a single round
+ * trip.
+ *
+ * Two properties matter and are easy to get wrong:
+ *
+ *  1. **Off-page children still count.** The board asks for top-level cards only, so
+ *     a parent's children are, by construction, absent from the page. Rolling up only
+ *     the children that happen to share the page would make a card's hours depend on
+ *     the current filter — indistinguishable from flakiness. The query therefore
+ *     widens from the page's ids to `id IN (page) OR parent_task_id IN (page)`.
+ *  2. **One aggregate for the whole page.** A 100-card board must not issue 100
+ *     queries; minutes come back pre-summed per (task, entry project) group, exactly
+ *     as the project aggregates do.
+ *
+ * Raw `duration_minutes` is what feeds these numbers. Rounded minutes exist only for
+ * money and stay inside `cost.ts` (D-7).
+ */
+
+export type TaskRollupTaskRow = {
+  id: string
+  parentTaskId?: string | null
+  timeProjectId?: string | null
+  /** The task sits in a column flagged `is_done` — the only definition of a done subtask (D-2). */
+  isDone?: boolean | null
+  deletedAt?: Date | string | null
+}
+
+/** Entry minutes pre-summed by the database, one group per (task, entry project). */
+export type TaskRollupEntryGroup = {
+  taskId: string
+  timeProjectId?: string | null
+  minutes: number
+  deletedAt?: Date | string | null
+}
+
+export type TaskRollupInput = {
+  /** The page's task ids — already filtered to what the caller may see. */
+  taskIds: readonly string[]
+  /** The page's tasks plus every child of them, on-page or not. */
+  tasks: readonly TaskRollupTaskRow[]
+  entryGroups: readonly TaskRollupEntryGroup[]
+}
+
+export type { TaskRollup }
+
+/**
+ * The rollup as the API publishes it: the minutes contract of
+ * `lib/time-tracking/rollup.ts` plus the done tally of the same children
+ * `childCount` counts.
+ *
+ * `doneChildCount` exists so a surface can render `3/5` from the row it already
+ * has. Without it the only way to say how many subtasks are finished is to fetch
+ * a page of children and count them, which turns opening a task into a second
+ * round trip for a number this aggregate already knows.
+ */
+export type TaskPageRollup = TaskRollup & { doneChildCount: number }
+
+export const EMPTY_TASK_ROLLUP: TaskPageRollup = {
+  ownMinutes: 0,
+  loggedMinutes: 0,
+  childCount: 0,
+  doneChildCount: 0,
+}
+
+function toMinutes(value: string | number | null | undefined): number {
+  if (value === null || value === undefined) return 0
+  const parsed = typeof value === 'number' ? value : Number(value)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+/**
+ * The projects the caller provably sees on this page.
+ *
+ * The list route has already intersected the page with `resolveProjectAccess`, so the
+ * projects of the page's own tasks are an authoritative allow-list. An entry pointing
+ * at any other project is dropped rather than trusted: nothing here can prove the
+ * caller may see it, and a rollup is a client-facing number.
+ */
+function allowedProjectIds(input: TaskRollupInput): Set<string> {
+  const pageIds = new Set(input.taskIds)
+  const allowed = new Set<string>()
+  for (const task of input.tasks) {
+    if (!pageIds.has(task.id) || task.deletedAt) continue
+    if (task.timeProjectId) allowed.add(task.timeProjectId)
+  }
+  return allowed
+}
+
+/**
+ * How many of a task's live children sit in a done column.
+ *
+ * The child set is derived exactly as `loggedMinutes` derives it — same parent
+ * test, same soft-delete exclusion, same self-reference guard — so a subtask can
+ * never be done without also being counted, which is the only way `3/5` can read
+ * as `3/4`.
+ */
+function countDoneChildren(
+  taskId: string,
+  allTasks: readonly RollupTask[],
+  doneByTaskId: ReadonlyMap<string, boolean>,
+): number {
+  let done = 0
+  for (const candidate of allTasks) {
+    if (candidate.parentTaskId !== taskId || candidate.id === taskId || candidate.deletedAt) continue
+    if (doneByTaskId.get(candidate.id) === true) done += 1
+  }
+  return done
+}
+
+export function summarizeTaskRollups(input: TaskRollupInput): Map<string, TaskPageRollup> {
+  const allowed = allowedProjectIds(input)
+
+  // The grouped query returns one row per (task, entry project), so a task with
+  // entries in two projects arrives twice. Deduplicating is not cosmetic: a repeated
+  // child row would be counted twice by `childCount`.
+  const taskById = new Map<string, RollupTask>()
+  const doneByTaskId = new Map<string, boolean>()
+  for (const task of input.tasks) {
+    if (taskById.has(task.id)) continue
+    taskById.set(task.id, { id: task.id, parentTaskId: task.parentTaskId ?? null, deletedAt: task.deletedAt ?? null })
+    doneByTaskId.set(task.id, task.isDone === true)
+  }
+  const allTasks = [...taskById.values()]
+
+  const entriesByTaskId = new Map<string, RollupEntry[]>()
+  for (const group of input.entryGroups) {
+    if (group.timeProjectId && !allowed.has(group.timeProjectId)) continue
+    const bucket = entriesByTaskId.get(group.taskId) ?? []
+    bucket.push({ durationMinutes: toMinutes(group.minutes), deletedAt: group.deletedAt ?? null })
+    entriesByTaskId.set(group.taskId, bucket)
+  }
+
+  const result = new Map<string, TaskPageRollup>()
+  for (const taskId of input.taskIds) {
+    const task = taskById.get(taskId) ?? { id: taskId, parentTaskId: null }
+    result.set(taskId, {
+      ...loggedMinutes(task, allTasks, entriesByTaskId),
+      doneChildCount: countDoneChildren(taskId, allTasks, doneByTaskId),
+    })
+  }
+  return result
+}
+
+export type TaskRollupScope = {
+  em: EntityManager
+  tenantId: string
+  organizationId: string
+  taskIds: readonly string[]
+}
+
+type TaskRollupRow = {
+  task_id: string
+  parent_task_id: string | null
+  task_project_id: string | null
+  task_is_done: boolean | string | null
+  entry_project_id: string | null
+  minutes: string | number | null
+}
+
+function toDoneFlag(value: boolean | string | null | undefined): boolean {
+  if (typeof value === 'boolean') return value
+  return value === 't' || value === 'true'
+}
+
+/**
+ * One grouped aggregate per page.
+ *
+ * The `OR` in the predicate is served by two indexes — the task primary key for the
+ * page's own ids and `staff_time_tasks_parent_idx` for their children — so widening
+ * to off-page children costs no extra round trip.
+ */
+export async function computeTaskRollups(scope: TaskRollupScope): Promise<Map<string, TaskPageRollup>> {
+  const taskIds = [...new Set(scope.taskIds)].filter((id) => typeof id === 'string' && id.length > 0)
+  if (taskIds.length === 0) return new Map<string, TaskPageRollup>()
+
+  const placeholders = taskIds.map(() => '?').join(', ')
+  const params: unknown[] = [scope.tenantId, scope.organizationId, ...taskIds, ...taskIds]
+
+  // The status join is what makes `doneChildCount` free: done-ness is a property
+  // of the column a task sits in (D-2), and the aggregate already walks every
+  // child of the page.
+  const sql = `
+    SELECT
+      t.id AS task_id,
+      t.parent_task_id,
+      t.time_project_id AS task_project_id,
+      COALESCE(s.is_done, false) AS task_is_done,
+      e.time_project_id AS entry_project_id,
+      COALESCE(SUM(e.duration_minutes), 0)::bigint AS minutes
+    FROM staff_time_tasks t
+    LEFT JOIN staff_time_task_statuses s
+      ON s.id = t.task_status_id
+     AND s.tenant_id = t.tenant_id
+     AND s.organization_id = t.organization_id
+     AND s.deleted_at IS NULL
+    LEFT JOIN staff_time_entries e
+      ON e.task_id = t.id
+     AND e.tenant_id = t.tenant_id
+     AND e.organization_id = t.organization_id
+     AND e.deleted_at IS NULL
+    WHERE t.tenant_id = ?
+      AND t.organization_id = ?
+      AND t.deleted_at IS NULL
+      AND (t.id IN (${placeholders}) OR t.parent_task_id IN (${placeholders}))
+    GROUP BY 1, 2, 3, 4, 5
+  `
+
+  const rows = (await scope.em.getConnection().execute(sql, params)) as TaskRollupRow[]
+
+  const tasks: TaskRollupTaskRow[] = []
+  const entryGroups: TaskRollupEntryGroup[] = []
+  for (const row of rows) {
+    tasks.push({
+      id: row.task_id,
+      parentTaskId: row.parent_task_id,
+      timeProjectId: row.task_project_id,
+      isDone: toDoneFlag(row.task_is_done),
+      deletedAt: null,
+    })
+    entryGroups.push({
+      taskId: row.task_id,
+      timeProjectId: row.entry_project_id,
+      minutes: toMinutes(row.minutes),
+      deletedAt: null,
+    })
+  }
+
+  return summarizeTaskRollups({ taskIds, tasks, entryGroups })
+}

package/src/modules/staff/lib/timesheets-tasks/defaultStatusTemplate.ts

@@ -0,0 +1,90 @@
+/**
+ * The tenant default Kanban template a project is seeded with (D-1).
+ *
+ * D-1 makes columns per-project so an audit project and a migration project can
+ * look nothing alike, which only works if every project starts from something
+ * usable — there is no board without columns, and no UI that repairs an empty
+ * one. This template is that starting point: the four columns screen 6 draws,
+ * with the entry point (`isDefault`) and the terminal column (`isDone`) already
+ * marked so a task can be created and closed the moment the project exists.
+ *
+ * Labels are i18n keys with an English fallback, resolved through the same
+ * `translate(key, fallback)` seam the rest of the module uses, so a Polish tenant
+ * gets the mockup's "W toku" rather than a hardcoded English string. Colours are
+ * DS chart token keys from `PROJECT_COLOR_KEYS`, never raw hex — the board reads
+ * the key back through `resolveProjectColorHex` to paint `kcol-accent`.
+ */
+
+import type { ProjectColorKey } from '../timesheets-ui/colors'
+import { STATUS_POSITION_GAP } from './statusPositions'
+
+export type DefaultTaskStatusTemplateEntry = {
+  slug: string
+  labelKey: string
+  defaultLabel: string
+  color: ProjectColorKey
+  isDefault: boolean
+  isDone: boolean
+}
+
+export const DEFAULT_TASK_STATUS_TEMPLATE: readonly DefaultTaskStatusTemplateEntry[] = [
+  {
+    slug: 'backlog',
+    labelKey: 'staff.time_tracking.taskStatuses.defaults.backlog',
+    defaultLabel: 'Backlog',
+    color: 'indigo',
+    isDefault: true,
+    isDone: false,
+  },
+  {
+    slug: 'in-progress',
+    labelKey: 'staff.time_tracking.taskStatuses.defaults.inProgress',
+    defaultLabel: 'In progress',
+    color: 'blue',
+    isDefault: false,
+    isDone: false,
+  },
+  {
+    slug: 'in-review',
+    labelKey: 'staff.time_tracking.taskStatuses.defaults.inReview',
+    defaultLabel: 'In review',
+    color: 'orange',
+    isDefault: false,
+    isDone: false,
+  },
+  {
+    slug: 'done',
+    labelKey: 'staff.time_tracking.taskStatuses.defaults.done',
+    defaultLabel: 'Done',
+    color: 'emerald',
+    isDefault: false,
+    isDone: true,
+  },
+] as const
+
+export type DefaultTaskStatusRow = {
+  slug: string
+  name: string
+  color: ProjectColorKey
+  position: number
+  isDefault: boolean
+  isDone: boolean
+}
+
+export type TaskStatusLabelTranslate = (key: string, fallback: string) => string
+
+/**
+ * Materialises the template into insertable rows: localized names and positions
+ * already on the gap grid, so the first drag on a fresh board is a single-row
+ * write rather than an immediate compaction.
+ */
+export function buildDefaultTaskStatusRows(translate: TaskStatusLabelTranslate): DefaultTaskStatusRow[] {
+  return DEFAULT_TASK_STATUS_TEMPLATE.map((entry, index) => ({
+    slug: entry.slug,
+    name: translate(entry.labelKey, entry.defaultLabel),
+    color: entry.color,
+    position: (index + 1) * STATUS_POSITION_GAP,
+    isDefault: entry.isDefault,
+    isDone: entry.isDone,
+  }))
+}

package/src/modules/staff/lib/timesheets-tasks/seedProjectStatuses.ts

@@ -0,0 +1,43 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { StaffTimeTaskStatus } from '../../data/entities'
+import { buildDefaultTaskStatusRows, type TaskStatusLabelTranslate } from './defaultStatusTemplate'
+
+export type SeedProjectTaskStatusesScope = {
+  tenantId: string
+  organizationId: string
+  timeProjectId: string
+}
+
+/**
+ * Materialises the default template onto a freshly created project.
+ *
+ * Persist-only, deliberately: it issues no query and never flushes, so the caller
+ * can run it as a mutation phase of the same transaction that inserted the
+ * project. That is the whole point — a project that exists without columns is a
+ * board nothing can be filed on, and there is no UI that repairs one.
+ */
+export function seedProjectTaskStatuses(
+  em: EntityManager,
+  scope: SeedProjectTaskStatusesScope,
+  translate: TaskStatusLabelTranslate,
+): StaffTimeTaskStatus[] {
+  const now = new Date()
+  return buildDefaultTaskStatusRows(translate).map((row) => {
+    const status = em.create(StaffTimeTaskStatus, {
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+      timeProjectId: scope.timeProjectId,
+      name: row.name,
+      slug: row.slug,
+      color: row.color,
+      position: row.position,
+      isDefault: row.isDefault,
+      isDone: row.isDone,
+      createdAt: now,
+      updatedAt: now,
+      deletedAt: null,
+    })
+    em.persist(status)
+    return status
+  })
+}