@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]/sheet/route.ts

@@ -0,0 +1,220 @@
+/**
+ * `GET /api/staff/timesheets/reports/[id]/sheet` — everything screens 14 and 15
+ * render: the report header, the grouped sheet, the raw entry rows and the
+ * close/unlock/export history.
+ *
+ * It is a separate route from the CRUD detail because the sheet is COMPUTED. A
+ * draft is computed live (and therefore moves when an entry is edited); a closed
+ * report is rebuilt from its own freeze records, so a later rounding change
+ * cannot restate an invoice the client already has (risk R1). One endpoint
+ * answering both keeps the page from having to know which case it is in.
+ *
+ * `?grouping=` re-groups the same numbers without persisting the choice, which
+ * is what lets screen 14 flip between task / person / day and still print the
+ * same grand total (D-7).
+ */
+
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+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 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 { hasReportGrouping, type ReportGrouping } from '../../../../../lib/timesheets-reports/reportGroupings'
+import { resolveReportRequestContext, reportSheetLabels, MAX_SHEET_ROWS } from '../../shared'
+import {
+  readSearchParamsRecord,
+  runTimesheetInterceptors,
+} from '../../../_shared/withTimesheetInterceptors'
+
+const logger = createLogger('staff').child({ component: 'api/timesheets/reports/sheet' })
+
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['staff.timesheets.reports.view'] },
+}
+
+/** EP-36: the accepted set is the grouping registry, not a literal union. */
+function readGrouping(params: URLSearchParams): ReportGrouping | undefined {
+  const value = params.get('grouping')
+  return hasReportGrouping(value) ? (value as ReportGrouping) : undefined
+}
+
+export async function GET(req: Request) {
+  try {
+    const context = await resolveReportRequestContext(req, { segment: 'sheet' })
+    // See the note in the export route: this decision is made once, fail-closed,
+    // in `buildReportRequestContext`.
+    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 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: readGrouping(session.searchParams),
+    })
+
+    const rows = buildReportRows({
+      entries: sheet.entries,
+      projects: sheet.projects,
+      directory: sheet.directory,
+      labels,
+    })
+
+    const events = await em.find(
+      StaffTimeReportEvent,
+      { reportId: report.id, tenantId, organizationId },
+      { orderBy: { createdAt: 'desc' } },
+    )
+
+    return session.respond(200, {
+      report: {
+        id: report.id,
+        reference: report.reference,
+        title: report.title,
+        status: report.status,
+        customerId: report.customerId,
+        customerSnapshot: report.customerSnapshot ?? null,
+        periodKind: report.periodKind,
+        periodFrom: report.periodFrom instanceof Date ? report.periodFrom.toISOString().slice(0, 10) : null,
+        periodTo: report.periodTo instanceof Date ? report.periodTo.toISOString().slice(0, 10) : null,
+        currencyCode: sheet.currencyCode,
+        grouping: sheet.grouping,
+        nonbillableMode: sheet.nonbillableMode,
+        includeAlreadyReported: report.includeAlreadyReported ?? false,
+        showRates: (report.showRates ?? true) && canSeeMoney,
+        roundingUnitMinutes: report.roundingUnitMinutes ?? 0,
+        roundingDirection: report.roundingDirection ?? 'up',
+        closedAt: report.closedAt ? report.closedAt.toISOString() : null,
+        closedByUserId: report.closedByUserId ?? null,
+        createdByUserId: report.createdByUserId ?? null,
+        createdAt: report.createdAt ? report.createdAt.toISOString() : null,
+        updatedAt: report.updatedAt ? report.updatedAt.toISOString() : null,
+        timeProjectIds,
+      },
+      groups: canSeeMoney ? sheet.totals.groups : stripAmounts(sheet.totals.groups),
+      totals: {
+        entryCount: sheet.totals.entryCount,
+        billableMinutes: sheet.totals.billableMinutes,
+        nonbillableMinutes: sheet.totals.nonbillableMinutes,
+        totalAmount: canSeeMoney ? sheet.totals.totalAmount : null,
+      },
+      alreadyReportedCount: sheet.totals.alreadyReportedCount,
+      alreadyReportedMinutes: sheet.totals.alreadyReportedMinutes,
+      alreadyReportedIn: sheet.totals.alreadyReportedIn,
+      rows: rows.slice(0, MAX_SHEET_ROWS).map((row) => ({
+        ...row,
+        rate: canSeeMoney ? row.rate : null,
+        amount: canSeeMoney ? row.amount : null,
+      })),
+      rowCount: rows.length,
+      rowsTruncated: rows.length > MAX_SHEET_ROWS,
+      events: events.map((event) => ({
+        id: event.id,
+        eventType: event.eventType,
+        reason: event.reason ?? null,
+        actorUserId: event.actorUserId ?? null,
+        metadata: event.metadata ?? null,
+        createdAt: event.createdAt ? event.createdAt.toISOString() : null,
+      })),
+    })
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    const { translate } = await resolveTranslations()
+    logger.error('staff.timesheets.reports.sheet failed', { err })
+    return NextResponse.json(
+      { error: translate('staff.errors.internal', 'Internal server error') },
+      { status: 500 },
+    )
+  }
+}
+
+type SheetGroups = Awaited<ReturnType<typeof buildReportSheet>>['totals']['groups']
+
+/** Money is absent, not zeroed, for a caller without `rates.view`. */
+function stripAmounts(groups: SheetGroups): SheetGroups {
+  return groups.map((group) => ({
+    ...group,
+    rate: null,
+    amount: 0,
+    lines: group.lines.map(function strip(line): SheetGroups[number]['lines'][number] {
+      return { ...line, rate: null, amount: 0, children: line.children.map(strip) }
+    }),
+  }))
+}
+
+const sheetResponseSchema = z.object({
+  report: z.object({
+    id: z.string().uuid(),
+    reference: z.string(),
+    title: z.string(),
+    status: z.enum(['draft', 'closed']),
+    currencyCode: z.string().nullable(),
+    periodFrom: z.string().nullable(),
+    periodTo: z.string().nullable(),
+    showRates: z.boolean(),
+  }),
+  totals: z.object({
+    entryCount: z.number().int(),
+    billableMinutes: z.number().int(),
+    nonbillableMinutes: z.number().int(),
+    totalAmount: z.number().nullable(),
+  }),
+  rowCount: z.number().int(),
+  rowsTruncated: z.boolean(),
+})
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Read a customer report sheet',
+  methods: {
+    GET: {
+      summary: 'Read a customer report sheet',
+      description:
+        'Returns the report header, the grouped sheet, the raw entry rows and the close/unlock/export history. A draft is computed live; a closed report is rebuilt from its own frozen snapshots so a later rounding or rate change cannot restate it. `?grouping=project_task|project_person|project_day` re-groups the same numbers without persisting the choice — the grand total is invariant under it (D-7). Amounts are omitted for a caller without staff.timesheets.rates.view.',
+      responses: [{ status: 200, description: 'Report sheet', schema: sheetResponseSchema }],
+      errors: [
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'Missing staff.timesheets.reports.view' },
+        { status: 404, description: 'Report not found or not accessible' },
+      ],
+    },
+  },
+}

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

@@ -0,0 +1,208 @@
+/**
+ * `POST /api/staff/timesheets/reports/[id]/unlock` — screen 15.
+ *
+ * Gated on `staff.timesheets.reports.unlock`, deliberately a DIFFERENT feature
+ * from `staff.timesheets.lock`. Screen 15 note 4 asked who may unlock and
+ * observed that §10 leaves nobody "above" a Team Leader; the answer is a
+ * separate grant that can be withheld from a Team Leader who should not restate
+ * billed time, rather than an admin role the requirements reject.
+ *
+ * The reason is mandatory at the schema level and is written verbatim into the
+ * `unlocked` report event beside the actor and the timestamp, which is what
+ * makes this the "explicit, audited action" US-G3 asks for rather than a confirm
+ * dialog.
+ */
+
+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 { staffTimeReportUnlockSchema } from '../../../../../data/validators'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { STAFF_TIME_TRACKING_RESOURCE_KINDS } from '../../../../guards'
+import { runTimesheetInterceptors } from '../../../_shared/withTimesheetInterceptors'
+import {
+  staffTimeReportCommandIds,
+  type StaffTimeReportUnlockResult,
+} from '../../../../../commands/timesheets-reports'
+import { resolveReportRequestContext } from '../../shared'
+import { evaluateReportUnlockPolicies } from '../../../../../lib/timesheets-reports/reportApprovalPolicies'
+
+const logger = createLogger('staff').child({ component: 'api/timesheets/reports/unlock' })
+
+const UNLOCK_FEATURE = 'staff.timesheets.reports.unlock'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: [UNLOCK_FEATURE] },
+}
+
+const bodySchema = z.object({ reason: z.string().trim().min(1).max(2000) })
+
+export async function POST(req: Request) {
+  try {
+    const context = await resolveReportRequestContext(req, { segment: 'unlock' })
+    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, [UNLOCK_FEATURE], { tenantId, organizationId })).allowed) {
+      throw forbidden(translate('staff.errors.forbidden', 'Forbidden'))
+    }
+
+    const interceptors = await runTimesheetInterceptors({
+      request: req,
+      method: 'POST',
+      scope: { container, userId: auth.sub, tenantId, organizationId, userFeatures: grantedFeatures },
+      body: await readJsonSafe<Record<string, unknown>>(req, {}),
+    })
+    if (!interceptors.ok) return interceptors.response
+    const { session } = interceptors
+
+    const parsed = bodySchema.parse(session.body)
+
+    // EP-41 runs strictly AFTER the ACL gate above and can only refuse. A
+    // four-eyes or accounting-period policy narrows who may unlock; nothing here
+    // widens it past staff.timesheets.reports.unlock.
+    const refusal = evaluateReportUnlockPolicies({
+      tenantId,
+      organizationId,
+      reportId,
+      actorUserId: typeof auth.sub === 'string' ? auth.sub : null,
+      actorFeatures: grantedFeatures,
+      status: 'closed',
+      reason: parsed.reason,
+    })
+    if (refusal) {
+      throw forbidden(translate(refusal.messageKey, translate('staff.errors.forbidden', 'Forbidden')))
+    }
+
+    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: parsed,
+      },
+    })
+    if (!guardResult.ok) return guardResult.response
+
+    const effective = guardResult.modifiedPayload
+      ? bodySchema.parse({ ...parsed, ...guardResult.modifiedPayload })
+      : parsed
+
+    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; reason: string },
+      StaffTimeReportUnlockResult
+    >(staffTimeReportCommandIds.unlock, {
+      input: { id: reportId, reason: effective.reason },
+      ctx,
+    })
+
+    await guardResult.runAfterSuccess()
+
+    const response = await session.respond(200, {
+      id: result?.reportId ?? reportId,
+      status: 'draft',
+      unlockedEntryCount: result?.unlockedEntryCount ?? 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.
+          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.time_tracking.reports.errors.reasonRequired',
+            'An unlock reason is required.',
+          ),
+          details: err.issues,
+        },
+        { status: 400 },
+      )
+    }
+    logger.error('staff.timesheets.reports.unlock failed', { err })
+    return NextResponse.json(
+      { error: translate('staff.errors.internal', 'Internal server error') },
+      { status: 500 },
+    )
+  }
+}
+
+const unlockResponseSchema = z.object({
+  id: z.string().uuid(),
+  status: z.literal('draft'),
+  unlockedEntryCount: z.number().int(),
+})
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Unlock a closed customer report',
+  methods: {
+    POST: {
+      summary: 'Unlock a closed customer report',
+      description:
+        'Clears locked_report_id / locked_at on every entry this report froze, removes its freeze records so a previously billed hour stops being counted as already reported, returns the report to draft and appends an `unlocked` event carrying the reason, the actor and the totals that were frozen. The reason is mandatory. Requires staff.timesheets.reports.unlock, which is deliberately separate from staff.timesheets.lock.',
+      requestBody: { contentType: 'application/json', schema: staffTimeReportUnlockSchema.pick({ reason: true }) },
+      responses: [{ status: 200, description: 'Report unlocked', schema: unlockResponseSchema }],
+      errors: [
+        { status: 400, description: 'Missing or empty reason' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'Missing staff.timesheets.reports.unlock, or refused by a registered report approval policy' },
+        { status: 404, description: 'Report not found or not accessible' },
+        { status: 409, description: 'Report is not closed (report_not_closed)' },
+      ],
+    },
+  },
+}