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

package/src/modules/staff/api/timesheets/reports/[id]/close/route.ts

@@ -0,0 +1,203 @@
+/**
+ * `POST /api/staff/timesheets/reports/[id]/close` — US-G3, screen 14's primary
+ * action.
+ *
+ * Gated on `staff.timesheets.lock`, the feature that already existed for exactly
+ * this ("Lock time periods"), rather than on a new one. Exporting a PDF does NOT
+ * come through here: screen 14 note 5 makes closing the only thing that freezes,
+ * so a download can never silently lock a team's timesheet.
+ *
+ * The whole freeze is one transaction inside the command. This file's job is
+ * auth, scope, the mutation guard and turning the command's refusals into the
+ * bodies the screen can act on.
+ */
+
+import { NextResponse } from 'next/server'
+import { resolveFeatureAccess } from '../../../../../lib/time-tracking/featureAccess'
+import { z } from 'zod'
+import { forbidden, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { runRouteMutationGuards } from '@open-mercato/shared/lib/crud/route-mutation-guard'
+import { authorizeFeatures } from '@open-mercato/shared/security/featurePolicy'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { STAFF_TIME_TRACKING_RESOURCE_KINDS } from '../../../../guards'
+import { runTimesheetInterceptors } from '../../../_shared/withTimesheetInterceptors'
+import {
+  staffTimeReportCommandIds,
+  type StaffTimeReportCloseResult,
+} from '../../../../../commands/timesheets-reports'
+import { resolveReportRequestContext } from '../../shared'
+import {
+  evaluateReportClosePolicies,
+  notifyReportClosed,
+} from '../../../../../lib/timesheets-reports/reportApprovalPolicies'
+
+const logger = createLogger('staff').child({ component: 'api/timesheets/reports/close' })
+
+const LOCK_FEATURE = 'staff.timesheets.lock'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: [LOCK_FEATURE] },
+}
+
+export async function POST(req: Request) {
+  try {
+    const context = await resolveReportRequestContext(req, { segment: 'close' })
+    const { container, auth, organizationScope, tenantId, organizationId, reportId, translate, grantedFeatures } =
+      context
+
+    // Checked unconditionally. The `grantedFeatures &&` this replaces turned the
+    // check off whenever the grant read failed — harmless here only because the
+    // route metadata happens to require the same feature, which is exactly the
+    // shape that leaked rates on the report routes where no such backstop existed.
+    if (!(await resolveFeatureAccess(container, auth.sub ?? null, [LOCK_FEATURE], { tenantId, organizationId })).allowed) {
+      throw forbidden(translate('staff.errors.forbidden', 'Forbidden'))
+    }
+
+    // EP-41 runs strictly AFTER the ACL gate above and can only refuse. A policy
+    // never grants, so nothing here can open a report a caller has no feature for.
+    const approvalContext = {
+      tenantId,
+      organizationId,
+      reportId,
+      actorUserId: typeof auth.sub === 'string' ? auth.sub : null,
+      actorFeatures: grantedFeatures,
+      status: 'draft',
+    }
+    const refusal = evaluateReportClosePolicies(approvalContext)
+    if (refusal) {
+      throw forbidden(translate(refusal.messageKey, translate('staff.errors.forbidden', 'Forbidden')))
+    }
+
+    const interceptors = await runTimesheetInterceptors({
+      request: req,
+      method: 'POST',
+      scope: { container, userId: auth.sub, tenantId, organizationId, userFeatures: grantedFeatures },
+    })
+    if (!interceptors.ok) return interceptors.response
+    const { session } = interceptors
+
+    const guardResult = await runRouteMutationGuards({
+      container,
+      req,
+      auth: {
+        userId: auth.sub ?? '',
+        tenantId,
+        organizationId,
+        userFeatures: grantedFeatures,
+      },
+      input: {
+        resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeReport,
+        resourceId: reportId,
+        operation: 'update',
+        mutationPayload: { id: reportId },
+      },
+    })
+    if (!guardResult.ok) return guardResult.response
+
+    const ctx: CommandRuntimeContext = {
+      container,
+      auth,
+      organizationScope,
+      selectedOrganizationId: organizationScope?.selectedId ?? auth.orgId ?? null,
+      organizationIds: organizationScope?.filterIds ?? (auth.orgId ? [auth.orgId] : null),
+      request: req,
+    }
+
+    const commandBus = container.resolve('commandBus') as CommandBus
+    const { result, logEntry } = await commandBus.execute<{ id: string }, StaffTimeReportCloseResult>(
+      staffTimeReportCommandIds.close,
+      { input: { id: reportId }, ctx },
+    )
+
+    await guardResult.runAfterSuccess()
+
+    for (const failure of await notifyReportClosed({ ...approvalContext, status: 'closed' })) {
+      logger.error('staff.timesheets.reports.close approval hook failed', {
+        policyId: failure.policyId,
+        err: failure.error,
+      })
+    }
+
+    const response = await session.respond(200, {
+      id: result?.reportId ?? reportId,
+      status: 'closed',
+      lockedEntryCount: result?.lockedEntryCount ?? 0,
+      totalAmount: result?.totalAmount ?? 0,
+      totalBillableMinutes: result?.totalBillableMinutes ?? 0,
+      totalNonbillableMinutes: result?.totalNonbillableMinutes ?? 0,
+    })
+    if (logEntry?.id && logEntry?.commandId) {
+      response.headers.set(
+        'x-om-operation',
+        serializeOperationMetadata({
+          id: logEntry.id,
+          // Explicitly no undo token: unwinding a billing freeze is the unlock
+          // endpoint, which demands a reason and its own feature. A one-click
+          // undo bar over a closed invoice is exactly what US-G3 forbids.
+          undoToken: '',
+          commandId: logEntry.commandId,
+          actionLabel: logEntry.actionLabel ?? null,
+          resourceKind: logEntry.resourceKind ?? STAFF_TIME_TRACKING_RESOURCE_KINDS.timeReport,
+          resourceId: logEntry.resourceId ?? reportId,
+          executedAt: logEntry.createdAt instanceof Date ? logEntry.createdAt.toISOString() : undefined,
+        }),
+      )
+    }
+    return response
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    const interceptorRejection = getCommandInterceptorHttpRejection(err)
+    if (interceptorRejection) {
+      return NextResponse.json(interceptorRejection.body, { status: interceptorRejection.status })
+    }
+    const { translate } = await resolveTranslations()
+    if (err instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: translate('staff.errors.invalid_request', 'Invalid request'), details: err.issues },
+        { status: 400 },
+      )
+    }
+    logger.error('staff.timesheets.reports.close failed', { err })
+    return NextResponse.json(
+      { error: translate('staff.errors.internal', 'Internal server error') },
+      { status: 500 },
+    )
+  }
+}
+
+const closeResponseSchema = z.object({
+  id: z.string().uuid(),
+  status: z.literal('closed'),
+  lockedEntryCount: z.number().int(),
+  totalAmount: z.number(),
+  totalBillableMinutes: z.number().int(),
+  totalNonbillableMinutes: z.number().int(),
+})
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Close and lock a customer report',
+  methods: {
+    POST: {
+      summary: 'Close and lock a customer report',
+      description:
+        'Freezes the report: writes one staff_time_report_entries snapshot per covered entry (raw minutes, rounded minutes, rate, currency, amount, billable), stamps locked_report_id / locked_at on entries that are not already locked by an earlier report, freezes the report totals and appends a `closed` event — all in one transaction. Exporting never locks; this endpoint is the only thing that does.',
+      responses: [{ status: 200, description: 'Report closed', schema: closeResponseSchema }],
+      errors: [
+        { status: 400, description: 'Missing report id or scope' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'Missing staff.timesheets.lock, or refused by a registered report approval policy' },
+        { status: 404, description: 'Report not found or not accessible' },
+        { status: 409, description: 'Report is already closed (report_closed)' },
+        { status: 422, description: 'Report covers no entries (report_empty)' },
+      ],
+    },
+  },
+}

package/src/modules/staff/api/timesheets/reports/[id]/export/route.ts

@@ -0,0 +1,315 @@
+/**
+ * `GET /api/staff/timesheets/reports/[id]/export?format=pdf|csv|xlsx` — US-G4.
+ *
+ * Two rules from screen 14:
+ *
+ *  - **Note 3.** The export inherits the current grouping, filters, rounding and
+ *    currency, because it is produced from the same `buildReportSheet` the page
+ *    rendered. PDF mirrors that sheet; CSV and XLSX add the raw accounting
+ *    columns (date, person, description, raw vs rounded minutes).
+ *  - **Note 5.** Exporting NEVER locks. The only write here is an append-only
+ *    `exported` report event, which is what lets the unlock dialog say "the PDF
+ *    was downloaded on the 20th" before someone restates a billed hour.
+ *
+ * The event is appended after the file is built, so a failed render leaves no
+ * trace of an export that never happened; a failed event write is logged and
+ * does not deny the caller their file.
+ */
+
+import { NextResponse } from 'next/server'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { emitStaffEvent } from '../../../../../events'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { StaffTimeReport, StaffTimeReportEvent } from '../../../../../data/entities'
+import { loadReportProjectIds } from '../../../../../commands/timesheets-reports'
+import { buildReportSheet } from '../../../../../lib/timesheets-reports/buildReportSheet'
+import { buildReportRows } from '../../../../../lib/timesheets-reports/reportRows'
+import {
+  normalizeReportExportFormat,
+  serializeReportExport,
+  supportedReportExportFormats,
+  type ReportExportLabels,
+} from '../../../../../lib/timesheets-reports/reportExport'
+import {
+  hasReportGrouping,
+  reportGroupingIds,
+  type ReportGrouping,
+} from '../../../../../lib/timesheets-reports/reportGroupings'
+import { z } from 'zod'
+import { resolveReportRequestContext, reportSheetLabels, type Translate } from '../../shared'
+import {
+  readSearchParamsRecord,
+  runTimesheetInterceptors,
+} from '../../../_shared/withTimesheetInterceptors'
+
+const logger = createLogger('staff').child({ component: 'api/timesheets/reports/export' })
+
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['staff.timesheets.reports.view'] },
+}
+
+/**
+ * EP-35 / EP-36: both accepted sets come from their registries, so a contributed
+ * format or grouping is accepted here without this file being edited.
+ */
+function readQuery(params: URLSearchParams): { format: string | null; grouping: ReportGrouping | undefined } {
+  const grouping = params.get('grouping')
+  return {
+    format: params.get('format'),
+    grouping: hasReportGrouping(grouping) ? (grouping as ReportGrouping) : undefined,
+  }
+}
+
+/**
+ * Read lazily rather than frozen at module load: a module registering a format
+ * after this route file is first imported must still appear in the published
+ * schema.
+ */
+function exportQuerySchema(): z.ZodTypeAny {
+  return z.object({
+    format: z.enum(supportedReportExportFormats() as [string, ...string[]]),
+    grouping: z.enum(reportGroupingIds() as [string, ...string[]]).optional(),
+  })
+}
+
+function exportLabels(translate: Translate): ReportExportLabels {
+  return {
+    documentTitle: translate('staff.time_tracking.reports.sheet.overline', 'Time and cost statement'),
+    issuedBy: translate('staff.time_tracking.reports.sheet.issuedBy', 'Issued by'),
+    reference: translate('staff.time_tracking.reports.sheet.reference', 'Reference'),
+    period: translate('staff.time_tracking.reports.sheet.period', 'Period'),
+    line: translate('staff.time_tracking.reports.sheet.lineLabel', 'Line'),
+    time: translate('staff.time_tracking.reports.sheet.time', 'Time'),
+    rate: translate('staff.time_tracking.reports.sheet.rate', 'Rate'),
+    amount: translate('staff.time_tracking.reports.sheet.amount', 'Amount'),
+    total: translate('staff.time_tracking.reports.sheet.total', 'Total to invoice'),
+    totalHint: translate(
+      'staff.time_tracking.reports.sheet.totalHint',
+      '{billable} billable · {nonbillable} non-billable · {rounding}',
+    ),
+    nonbillable: translate('staff.time_tracking.reports.sheet.nonbillable', 'Non-billable time'),
+    overrideBadge: translate('staff.time_tracking.reports.sheet.overrideBadge', 'agreed rate'),
+    date: translate('staff.time_tracking.reports.export.date', 'Date'),
+    project: translate('staff.time_tracking.reports.export.project', 'Project'),
+    task: translate('staff.time_tracking.reports.export.task', 'Task'),
+    person: translate('staff.time_tracking.reports.export.person', 'Person'),
+    description: translate('staff.time_tracking.reports.export.description', 'Description'),
+    billable: translate('staff.time_tracking.reports.export.billable', 'Billable'),
+    yes: translate('staff.time_tracking.reports.export.yes', 'Yes'),
+    no: translate('staff.time_tracking.reports.export.no', 'No'),
+    rawMinutes: translate('staff.time_tracking.reports.export.rawMinutes', 'Raw minutes'),
+    roundedMinutes: translate('staff.time_tracking.reports.export.roundedMinutes', 'Rounded minutes'),
+  }
+}
+
+function roundingLabel(translate: Translate, unitMinutes: number, direction: string): string {
+  if (!unitMinutes) return translate('staff.time_tracking.reports.rounding.off', 'no rounding')
+  const directionLabel =
+    direction === 'nearest'
+      ? translate('staff.time_tracking.reports.rounding.nearest', 'to the nearest')
+      : translate('staff.time_tracking.reports.rounding.up', 'always up')
+  return translate('staff.time_tracking.reports.rounding.rule', 'rounding {minutes} min, {direction}')
+    .replace('{minutes}', String(unitMinutes))
+    .replace('{direction}', directionLabel)
+}
+
+function readCustomerName(snapshot: Record<string, unknown> | null | undefined, fallback: string): string {
+  if (!snapshot) return fallback
+  for (const key of ['name', 'displayName', 'display_name', 'legalName', 'legal_name']) {
+    const value = snapshot[key]
+    if (typeof value === 'string' && value.trim().length > 0) return value.trim()
+  }
+  return fallback
+}
+
+export async function GET(req: Request) {
+  try {
+    const context = await resolveReportRequestContext(req, { segment: 'export' })
+    // `canSeeMoney` comes from the shared context and is never re-derived here:
+    // the previous `grantedFeatures === null || authorize(...)` opened the money
+    // fields whenever the grant read failed, and this route requires only
+    // `reports.view`, so nothing else stood in the way.
+    const { container, auth, tenantId, organizationId, reportId, translate, canSeeMoney, grantedFeatures } =
+      context
+
+    const interceptors = await runTimesheetInterceptors({
+      request: req,
+      method: 'GET',
+      scope: { container, userId: auth.sub, tenantId, organizationId, userFeatures: grantedFeatures },
+      query: readSearchParamsRecord(req.url),
+    })
+    if (!interceptors.ok) return interceptors.response
+    const { session } = interceptors
+
+    const { format: rawFormat, grouping } = readQuery(session.searchParams)
+    const format = normalizeReportExportFormat(rawFormat)
+    if (!format) {
+      throw new CrudHttpError(400, {
+        error: translate(
+          'staff.time_tracking.reports.errors.unsupportedFormat',
+          'Supported export formats are pdf, csv and xlsx.',
+        ),
+        supportedFormats: supportedReportExportFormats(),
+      })
+    }
+
+    const em = (container.resolve('em') as EntityManager).fork()
+    const report = await em.findOne(StaffTimeReport, {
+      id: reportId,
+      tenantId,
+      organizationId,
+      deletedAt: null,
+    })
+    if (!report) {
+      throw new CrudHttpError(404, {
+        error: translate('staff.time_tracking.reports.errors.notFound', 'Report not found or not accessible.'),
+      })
+    }
+
+    const timeProjectIds = await loadReportProjectIds(em, report.id, { tenantId, organizationId })
+    const labels = reportSheetLabels(translate)
+    const sheet = await buildReportSheet({
+      em,
+      scope: { tenantId, organizationId },
+      report,
+      timeProjectIds,
+      labels,
+      grouping,
+    })
+    const rows = buildReportRows({
+      entries: sheet.entries,
+      projects: sheet.projects,
+      directory: sheet.directory,
+      labels,
+    })
+
+    const periodFrom = report.periodFrom instanceof Date ? report.periodFrom.toISOString().slice(0, 10) : ''
+    const periodTo = report.periodTo instanceof Date ? report.periodTo.toISOString().slice(0, 10) : ''
+
+    const file = serializeReportExport(format, {
+      reference: report.reference,
+      title: report.title,
+      customerName: readCustomerName(report.customerSnapshot, report.title),
+      periodLabel: `${periodFrom} – ${periodTo}`,
+      issuedByLabel: null,
+      issuedAtLabel: report.closedAt ? report.closedAt.toISOString().slice(0, 10) : null,
+      currencyCode: sheet.currencyCode,
+      showRates: (report.showRates ?? true) && canSeeMoney,
+      groups: sheet.totals.groups,
+      rows: canSeeMoney ? rows : rows.map((row) => ({ ...row, rate: null, amount: null })),
+      totals: {
+        billableMinutes: sheet.totals.billableMinutes,
+        nonbillableMinutes: sheet.totals.nonbillableMinutes,
+        totalAmount: canSeeMoney ? sheet.totals.totalAmount : 0,
+      },
+      roundingLabel: roundingLabel(
+        translate,
+        report.roundingUnitMinutes ?? 0,
+        report.roundingDirection ?? 'up',
+      ),
+      labels: exportLabels(translate),
+    })
+
+    // Append-only audit. Never a lock — screen 14 note 5.
+    try {
+      const eventEm = (container.resolve('em') as EntityManager).fork()
+      eventEm.persist(
+        eventEm.create(StaffTimeReportEvent, {
+          tenantId,
+          organizationId,
+          reportId: report.id,
+          eventType: 'exported',
+          reason: null,
+          actorUserId: typeof auth.sub === 'string' ? auth.sub : null,
+          metadata: { format, grouping: sheet.grouping, rowCount: rows.length },
+          createdAt: new Date(),
+        }),
+      )
+      await eventEm.flush()
+    } catch (err) {
+      // The caller already has a correct file; refusing it because the audit row
+      // failed would be the wrong trade.
+      logger.error('staff.timesheets.reports.export audit event failed', { err })
+    }
+
+    void emitStaffEvent('staff.timesheets.time_report.exported', {
+      id: report.id,
+      tenantId,
+      organizationId,
+      reference: report.reference,
+      format,
+      grouping: sheet.grouping,
+      rowCount: rows.length,
+    }, { persistent: true }).catch((err) => {
+      logger.error('staff.timesheets emit time_report.exported failed', { err })
+    })
+
+    // The after-pass cannot rewrite an export's bytes, so what it shapes is the
+    // file's descriptor: an interceptor may rename the download or restate its
+    // media type, and a failing one replaces the file with its own error.
+    const intercepted = await session.respondWithDescriptor({
+      reportId: report.id,
+      reference: report.reference,
+      format,
+      grouping: sheet.grouping,
+      rowCount: rows.length,
+      filename: file.filename,
+      contentType: file.contentType,
+    })
+    if (!intercepted.ok) return intercepted.response
+
+    const filename =
+      typeof intercepted.descriptor.filename === 'string' && intercepted.descriptor.filename.trim().length > 0
+        ? intercepted.descriptor.filename.trim()
+        : file.filename
+    const contentType =
+      typeof intercepted.descriptor.contentType === 'string' && intercepted.descriptor.contentType.trim().length > 0
+        ? intercepted.descriptor.contentType.trim()
+        : file.contentType
+
+    return new NextResponse(new Uint8Array(file.body), {
+      status: 200,
+      headers: {
+        'content-type': contentType,
+        'content-disposition': `attachment; filename="${filename}"`,
+        'cache-control': 'no-store',
+      },
+    })
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    const { translate } = await resolveTranslations()
+    logger.error('staff.timesheets.reports.export failed', { err })
+    return NextResponse.json(
+      { error: translate('staff.errors.internal', 'Internal server error') },
+      { status: 500 },
+    )
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Export a customer report',
+  methods: {
+    GET: {
+      summary: 'Export a customer report',
+      get query() {
+        return exportQuerySchema()
+      },
+      description:
+        'Renders the report as `pdf` (mirrors the on-screen sheet, client-facing), `csv` or `xlsx` (raw accounting columns: date, project, task, person, description, raw and rounded minutes, billable, rate, amount). Honours the report grouping — overridable per request with `?grouping=` — plus its filters, rounding and currency. Appends an `exported` report event; exporting never locks entries. Rates and amounts are omitted for a caller without staff.timesheets.rates.view.',
+      responses: [{ status: 200, description: 'The rendered report file' }],
+      errors: [
+        { status: 400, description: 'Unsupported format' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'Missing staff.timesheets.reports.view' },
+        { status: 404, description: 'Report not found or not accessible' },
+      ],
+    },
+  },
+}