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

package/src/modules/staff/ai-tools/types.ts

@@ -0,0 +1,82 @@
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { AiToolExecutionContext } from '@open-mercato/ai-assistant/modules/ai_assistant/lib/ai-api-operation-runner'
+import { getStaffMemberByUserId } from '../lib/staffMemberResolver'
+
+/**
+ * EP-49. Shared context helpers for the time-tracking AI tool pack.
+ *
+ * Every tool in the pack is API-backed: it re-uses a documented
+ * `/api/staff/timesheets/*` route through `createAiApiOperationRunner`, which
+ * resolves the route from the generated manifest, refuses a mutation route whose
+ * `requiredFeatures` are not covered by the tool's own, and invokes the handler
+ * in process with the caller's identity. So the tools inherit — rather than
+ * restate — the project-access intersection, the money gate, the mutation guards,
+ * the interceptors and the commands' audit and undo. Nothing here writes a time
+ * entry itself.
+ */
+
+export type StaffToolScope = {
+  tenantId: string
+  organizationId: string
+  staffMemberId: string
+}
+
+export function assertTenantScope(ctx: AiToolExecutionContext): {
+  tenantId: string
+  organizationId: string
+} {
+  if (!ctx.tenantId) throw new Error('[internal] Tenant context is required for staff.* tools')
+  if (!ctx.organizationId) {
+    throw new Error('[internal] Organization context is required for staff.* tools')
+  }
+  return { tenantId: ctx.tenantId, organizationId: ctx.organizationId }
+}
+
+/**
+ * The pack is written for "log MY time": every tool acts as the caller's own
+ * staff member and none of them accepts a `staffMemberId` from the model. A user
+ * with no staff profile is refused rather than defaulted to somebody else.
+ */
+export async function resolveStaffToolScope(ctx: AiToolExecutionContext): Promise<StaffToolScope> {
+  const { tenantId, organizationId } = assertTenantScope(ctx)
+  if (!ctx.userId) throw new Error('[internal] User context is required for staff.* tools')
+  const container = ctx.container as AwilixContainer
+  const em = (container.resolve('em') as EntityManager).fork()
+  const member = await getStaffMemberByUserId(em, ctx.userId, tenantId, organizationId)
+  if (!member) {
+    throw new Error('The signed-in user has no staff profile, so time cannot be logged for them.')
+  }
+  return { tenantId, organizationId, staffMemberId: member.id }
+}
+
+export function toIsoDate(value: unknown): string | null {
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) return null
+    return value.toISOString().slice(0, 10)
+  }
+  if (typeof value === 'string' && value.trim().length > 0) return value.trim().slice(0, 10)
+  return null
+}
+
+export function toMinutes(value: unknown): number {
+  const parsed = typeof value === 'number' ? value : Number(value ?? 0)
+  return Number.isFinite(parsed) ? Math.trunc(parsed) : 0
+}
+
+/** Inclusive `yyyy-mm-dd` walk; caps at a year so a bad range cannot build an unbounded array. */
+export function enumerateDates(from: string, to: string): string[] {
+  const start = Date.parse(`${from}T00:00:00Z`)
+  const end = Date.parse(`${to}T00:00:00Z`)
+  if (!Number.isFinite(start) || !Number.isFinite(end) || end < start) return []
+  const dates: string[] = []
+  for (let cursor = start; cursor <= end && dates.length < 366; cursor += 86_400_000) {
+    dates.push(new Date(cursor).toISOString().slice(0, 10))
+  }
+  return dates
+}
+
+export function isWeekend(date: string): boolean {
+  const day = new Date(`${date}T00:00:00Z`).getUTCDay()
+  return day === 0 || day === 6
+}

package/src/modules/staff/ai-tools.ts

@@ -0,0 +1,13 @@
+import type { AiToolDefinition } from '@open-mercato/ai-assistant/modules/ai_assistant/lib/types'
+import timeTrackingAiTools from './ai-tools/time-tracking-pack'
+
+/**
+ * EP-49. The module's AI tool registry.
+ *
+ * The generator discovers `ai-tools.ts` at the module root only, so a pack living
+ * in `ai-tools/` reaches the runtime through this aggregator — the customers
+ * idiom.
+ */
+export const aiTools: AiToolDefinition[] = [...timeTrackingAiTools]
+
+export default aiTools

package/src/modules/staff/analytics.ts

@@ -1,5 +1,35 @@
 import type { AnalyticsModuleConfig } from '@open-mercato/shared/modules/analytics'
 
+/**
+ * EP-47. Four time-tracking entities are aggregatable from a dashboard widget.
+ *
+ * Two rules shape every mapping below.
+ *
+ * **Money is absent, never blanked.** `staff_time_entries.rate_override_amount`,
+ * `staff_time_projects.hourly_rate` / `budget_value` and
+ * `staff_time_reports.total_amount` are deliberately NOT mapped. An
+ * `AnalyticsEntityConfig` carries a single `requiredFeatures` list for the whole
+ * entity, so there is no shape in which a money column is gated on
+ * `staff.timesheets.rates.view` while the rest of the entity stays readable by a
+ * plain viewer — and mapping it under the weaker gate would hand every dashboard
+ * author the customer's rates. The minute columns carry the same analysis
+ * without the disclosure.
+ *
+ * **Custom fields are not dimensions and cannot be.** `AnalyticsFieldMapping` is
+ * `{ dbColumn, type }` and the aggregation builder emits `dbColumn` as a bare
+ * identifier against `entityConfig.tableName` (`dashboards/lib/aggregations.ts`),
+ * so a mapping can only ever name a real column on that one table. The custom
+ * fields EP-43 declared are EAV rows in the `entities` module's tables, reachable
+ * by neither a join nor the jsonb-path form (which needs the values to live in a
+ * jsonb column on the row itself). The point is moot in any case while the
+ * command-backed write path drops `cf_*` on the way in — see the module
+ * `AGENTS.md` § Time-tracking custom fields.
+ *
+ * `is_billable` and `billable_by_default` are declared `text` because
+ * `AnalyticsFieldType` has no boolean member; the type is read for exactly one
+ * decision — whether a group-by column gets a `date_trunc` — so a boolean column
+ * grouped as `text` is emitted verbatim and labelled by its own value.
+ */
 export const analyticsConfig: AnalyticsModuleConfig = {
   entities: [
     {
@@ -13,14 +43,97 @@ export const analyticsConfig: AnalyticsModuleConfig = {
       fieldMappings: {
         id: { dbColumn: 'id', type: 'uuid' },
         durationMinutes: { dbColumn: 'duration_minutes', type: 'numeric' },
+        roundedMinutes: { dbColumn: 'rounded_minutes', type: 'numeric' },
         date: { dbColumn: 'date', type: 'timestamp' },
         timeProjectId: { dbColumn: 'time_project_id', type: 'uuid' },
         staffMemberId: { dbColumn: 'staff_member_id', type: 'uuid' },
+        taskId: { dbColumn: 'task_id', type: 'uuid' },
+        customerId: { dbColumn: 'customer_id', type: 'uuid' },
+        isBillable: { dbColumn: 'is_billable', type: 'text' },
+        lockedReportId: { dbColumn: 'locked_report_id', type: 'uuid' },
         source: { dbColumn: 'source', type: 'text' },
       },
       labelResolvers: {
         timeProjectId: { table: 'staff_time_projects', idColumn: 'id', labelColumn: 'name' },
         staffMemberId: { table: 'staff_team_members', idColumn: 'id', labelColumn: 'display_name' },
+        taskId: { table: 'staff_time_tasks', idColumn: 'id', labelColumn: 'title' },
+        customerId: { table: 'customer_entities', idColumn: 'id', labelColumn: 'display_name' },
+        lockedReportId: { table: 'staff_time_reports', idColumn: 'id', labelColumn: 'reference' },
+      },
+    },
+    {
+      entityId: 'staff:staff_time_tasks',
+      requiredFeatures: ['staff.timesheets.tasks.view'],
+      entityConfig: {
+        tableName: 'staff_time_tasks',
+        dateField: 'created_at',
+        defaultScopeFields: ['tenant_id', 'organization_id'],
+      },
+      fieldMappings: {
+        id: { dbColumn: 'id', type: 'uuid' },
+        reference: { dbColumn: 'reference', type: 'text' },
+        timeProjectId: { dbColumn: 'time_project_id', type: 'uuid' },
+        parentTaskId: { dbColumn: 'parent_task_id', type: 'uuid' },
+        taskStatusId: { dbColumn: 'task_status_id', type: 'uuid' },
+        assigneeStaffMemberId: { dbColumn: 'assignee_staff_member_id', type: 'uuid' },
+        createdAt: { dbColumn: 'created_at', type: 'timestamp' },
+        closedAt: { dbColumn: 'closed_at', type: 'timestamp' },
+      },
+      labelResolvers: {
+        timeProjectId: { table: 'staff_time_projects', idColumn: 'id', labelColumn: 'name' },
+        taskStatusId: { table: 'staff_time_task_statuses', idColumn: 'id', labelColumn: 'name' },
+        assigneeStaffMemberId: { table: 'staff_team_members', idColumn: 'id', labelColumn: 'display_name' },
+        parentTaskId: { table: 'staff_time_tasks', idColumn: 'id', labelColumn: 'title' },
+      },
+    },
+    {
+      entityId: 'staff:staff_time_projects',
+      requiredFeatures: ['staff.timesheets.projects.view'],
+      entityConfig: {
+        tableName: 'staff_time_projects',
+        dateField: 'created_at',
+        defaultScopeFields: ['tenant_id', 'organization_id'],
+      },
+      fieldMappings: {
+        id: { dbColumn: 'id', type: 'uuid' },
+        code: { dbColumn: 'code', type: 'text' },
+        customerId: { dbColumn: 'customer_id', type: 'uuid' },
+        projectType: { dbColumn: 'project_type', type: 'text' },
+        status: { dbColumn: 'status', type: 'text' },
+        ownerUserId: { dbColumn: 'owner_user_id', type: 'uuid' },
+        costCenter: { dbColumn: 'cost_center', type: 'text' },
+        budgetKind: { dbColumn: 'budget_kind', type: 'text' },
+        billableByDefault: { dbColumn: 'billable_by_default', type: 'text' },
+        startDate: { dbColumn: 'start_date', type: 'timestamp' },
+        createdAt: { dbColumn: 'created_at', type: 'timestamp' },
+      },
+      labelResolvers: {
+        customerId: { table: 'customer_entities', idColumn: 'id', labelColumn: 'display_name' },
+      },
+    },
+    {
+      entityId: 'staff:staff_time_reports',
+      requiredFeatures: ['staff.timesheets.reports.view'],
+      entityConfig: {
+        tableName: 'staff_time_reports',
+        dateField: 'period_from',
+        defaultScopeFields: ['tenant_id', 'organization_id'],
+      },
+      fieldMappings: {
+        id: { dbColumn: 'id', type: 'uuid' },
+        reference: { dbColumn: 'reference', type: 'text' },
+        customerId: { dbColumn: 'customer_id', type: 'uuid' },
+        status: { dbColumn: 'status', type: 'text' },
+        periodKind: { dbColumn: 'period_kind', type: 'text' },
+        periodFrom: { dbColumn: 'period_from', type: 'timestamp' },
+        periodTo: { dbColumn: 'period_to', type: 'timestamp' },
+        grouping: { dbColumn: 'grouping', type: 'text' },
+        totalBillableMinutes: { dbColumn: 'total_billable_minutes', type: 'numeric' },
+        totalNonbillableMinutes: { dbColumn: 'total_nonbillable_minutes', type: 'numeric' },
+        closedAt: { dbColumn: 'closed_at', type: 'timestamp' },
+      },
+      labelResolvers: {
+        customerId: { table: 'customer_entities', idColumn: 'id', labelColumn: 'display_name' },
       },
     },
   ],

package/src/modules/staff/api/guards.ts

@@ -5,22 +5,96 @@ import {
   type MutationGuard,
   type MutationGuardInput,
 } from '@open-mercato/shared/lib/crud/mutation-guard-registry'
+import { getAllMutationGuardInstances } from '@open-mercato/shared/lib/crud/mutation-guard-store'
+import { resolveFeatureAccess } from '../lib/time-tracking/featureAccess'
 
 type GuardAfterCallback = {
   guard: MutationGuard
   metadata: Record<string, unknown> | null
 }
 
+/**
+ * @deprecated `AuthContext` has no `features` field, so this always answered `[]` —
+ * which silently filtered out every registered guard declaring `features`, leaving
+ * feature-gated guards enforced on the `makeCrudRoute` resources (the factory
+ * resolves real grants) and skipped on every hand-rolled write route.
+ * `runStaffMutationGuards` now resolves the caller's grants itself through
+ * `resolveFeatureAccess`; pass nothing. Kept as an exported symbol for one release.
+ */
 export function resolveUserFeatures(auth: unknown): string[] {
   const features = (auth as { features?: unknown })?.features
   if (!Array.isArray(features)) return []
   return features.filter((value): value is string => typeof value === 'string')
 }
 
+/**
+ * The `resourceKind` every hand-rolled time-tracking write route passes into the
+ * mutation-guard contract, published as one map so a guard author can target a route
+ * without reading it.
+ *
+ * These strings are what `MutationGuardInput.resourceKind` carries; they are NOT the
+ * CRUD factory's cache/audit resource tag, which the factory derives on its own from
+ * each route's `events` config. A guard that filters on `resourceKind` matches against
+ * the values below on the custom routes and against the factory-derived tag on the
+ * eight `makeCrudRoute` resources.
+ *
+ * `staff.timesheets.time_task` and `staff.timesheets.time_report` are re-exported from
+ * the command modules that also feed them to `enforceCommandOptimisticLockWithGuards`
+ * (`STAFF_TIME_TASK_RESOURCE_KIND`, `STAFF_TIME_REPORT_RESOURCE_KIND`); the unit test
+ * pins both copies to the same string so they cannot drift.
+ */
+export const STAFF_TIME_TRACKING_RESOURCE_KINDS = {
+  /** `time-entries/{bulk,copy-day,start-timer}`, `time-entries/[id]/{duplicate,timer-start,timer-stop}` */
+  timeEntry: 'staff.timesheets.time_entry',
+  /** `time-entries/[id]/segments`, `time-entries/[id]/segments/[segmentId]` */
+  timeEntrySegment: 'staff.timesheets.time_entry_segment',
+  /** `tasks/[id]/status` */
+  timeTask: 'staff.timesheets.time_task',
+  /** `tasks/[id]/comments` */
+  timeTaskComment: 'staff.timesheets.task_comment',
+  /** `time-projects/[id]/change-currency` */
+  timeProject: 'staff.timesheets.time_project',
+  /** `my-projects/[projectId]` */
+  timeProjectMember: 'staff.timesheets.time_project_member',
+  /** `reports/[id]/close`, `reports/[id]/unlock` */
+  timeReport: 'staff.timesheets.time_report',
+  /** `tags/entry-assignments` */
+  entryTag: 'staff.timesheets.entry_tag',
+  /** `tags/task-assignments` */
+  taskTag: 'staff.timesheets.task_tag',
+  /** `settings`, `settings/reapply-rounding` */
+  settings: 'staff.timesheets.settings',
+  /** `access-requests` */
+  accessRequest: 'staff.timesheets.access_request',
+} as const
+
+export type StaffTimeTrackingResourceKind =
+  typeof STAFF_TIME_TRACKING_RESOURCE_KINDS[keyof typeof STAFF_TIME_TRACKING_RESOURCE_KINDS]
+
+/**
+ * Runs the same guard set as `makeCrudRoute`: every guard a module registered through
+ * `data/guards.ts` (`getAllMutationGuardInstances()`) plus the bridged legacy DI
+ * service. Mirrors `collectAndRunGuards()` in the CRUD factory; bridging only the
+ * legacy service — as this did originally — left registry guards unenforced on every
+ * hand-rolled time-tracking write route.
+ *
+ * **The grant list is resolved here, not passed in.** `runMutationGuards` drops any
+ * guard whose `features` the caller does not hold, so an empty list silently disables
+ * every feature-gated guard — a third-party `record_locks.enforce` guard fired on the
+ * `makeCrudRoute` resources (the factory asks RBAC) and was skipped on `/bulk`, the
+ * timer transitions, segments, tag assignments and report close/unlock. Callers used
+ * to supply `resolveUserFeatures(auth)`, which read a field `AuthContext` does not
+ * have and therefore always returned `[]`. The lookup now goes through
+ * `resolveFeatureAccess`, the module's one RBAC authority, which fails closed and
+ * logs rather than failing silently.
+ *
+ * `extraFeatures` is additive and exists only for a caller that already holds a
+ * resolved grant list; it is never the sole source.
+ */
 export async function runStaffMutationGuards(
   container: AwilixContainer,
   input: MutationGuardInput,
-  userFeatures: string[],
+  extraFeatures: readonly string[] = [],
 ): Promise<{
   ok: boolean
   errorBody?: Record<string, unknown>
@@ -28,12 +102,20 @@ export async function runStaffMutationGuards(
   modifiedPayload?: Record<string, unknown>
   afterSuccessCallbacks: GuardAfterCallback[]
 }> {
+  const allGuards: MutationGuard[] = [...getAllMutationGuardInstances()]
   const legacyGuard = bridgeLegacyGuard(container)
-  if (!legacyGuard) {
+  if (legacyGuard) allGuards.push(legacyGuard)
+  if (!allGuards.length) {
     return { ok: true, afterSuccessCallbacks: [] }
   }
 
-  return runMutationGuards([legacyGuard], input, { userFeatures })
+  const { grantedFeatures } = await resolveFeatureAccess(container, input.userId ?? null, [], {
+    tenantId: input.tenantId ?? null,
+    organizationId: input.organizationId ?? null,
+  })
+  const userFeatures = Array.from(new Set([...grantedFeatures, ...extraFeatures]))
+
+  return runMutationGuards(allGuards, input, { userFeatures })
 }
 
 export async function runStaffMutationGuardAfterSuccess(

package/src/modules/staff/api/leave-requests/accept/route.ts

@@ -11,7 +11,6 @@ import { parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { staffLeaveRequestDecisionSchema, type StaffLeaveRequestDecisionInput } from '../../../data/validators'
 import {
-  resolveUserFeatures,
   runStaffMutationGuardAfterSuccess,
   runStaffMutationGuards,
 } from '../../guards'
@@ -65,7 +64,6 @@ export async function POST(req: Request) {
         requestHeaders: req.headers,
         mutationPayload: input,
       },
-      resolveUserFeatures(auth),
     )
     if (!guardResult.ok) {
       return NextResponse.json(

package/src/modules/staff/api/leave-requests/reject/route.ts

@@ -11,7 +11,6 @@ import { parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { staffLeaveRequestDecisionSchema, type StaffLeaveRequestDecisionInput } from '../../../data/validators'
 import {
-  resolveUserFeatures,
   runStaffMutationGuardAfterSuccess,
   runStaffMutationGuards,
 } from '../../guards'
@@ -65,7 +64,6 @@ export async function POST(req: Request) {
         requestHeaders: req.headers,
         mutationPayload: input,
       },
-      resolveUserFeatures(auth),
     )
     if (!guardResult.ok) {
       return NextResponse.json(

package/src/modules/staff/api/portal/time-reports/[id]/route.ts

@@ -0,0 +1,182 @@
+/**
+ * `GET /api/staff/portal/time-reports/{id}` — EP-50.
+ *
+ * The ownership check is the list route's, unchanged and re-applied here rather
+ * than inherited from it: the id in the path is caller-supplied, so the row it
+ * names is loaded WITH `tenant_id`, `organization_id`, `customer_id`,
+ * `status = 'closed'` and `deleted_at IS NULL` in the same WHERE clause, never
+ * loaded first and checked after. A report belonging to another customer of the
+ * same organization is a `404`, not a `403` — the portal must not confirm that
+ * somebody else's report exists.
+ *
+ * The per-project breakdown reads the FROZEN minutes on `staff_time_report_entries`,
+ * which is what the close wrote and what the client was told. It carries no
+ * `frozen_rate_amount` and no `frozen_amount`; see the list route's header for why
+ * money is structurally absent from this surface rather than conditionally hidden.
+ */
+
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { portalOwnedReportClause } from '../../../../lib/time-tracking/portalReports'
+import { resolvePortalScope, toIsoDate, toMinutes } from '../route'
+
+const logger = createLogger('staff').child({ component: 'api/portal/time-reports/[id]' })
+
+export const metadata: { path?: string; requireAuth?: boolean } = { requireAuth: false }
+
+const paramsSchema = z.object({ id: z.string().uuid() })
+
+const errorResponseSchema = z.object({ ok: z.literal(false), error: z.string() })
+
+const projectLineSchema = z.object({
+  timeProjectId: z.string().nullable(),
+  projectName: z.string().nullable(),
+  billableMinutes: z.number().int(),
+  nonbillableMinutes: z.number().int(),
+})
+
+const detailResponseSchema = z.object({
+  id: z.string().uuid(),
+  reference: z.string(),
+  title: z.string(),
+  periodFrom: z.string(),
+  periodTo: z.string(),
+  closedAt: z.string().nullable(),
+  totalBillableMinutes: z.number().int(),
+  totalNonbillableMinutes: z.number().int(),
+  projects: z.array(projectLineSchema),
+})
+
+type ReportRow = {
+  id: string
+  reference: string
+  title: string
+  period_from: Date | string
+  period_to: Date | string
+  closed_at: Date | string | null
+  total_billable_minutes: number | string | null
+  total_nonbillable_minutes: number | string | null
+}
+
+type ProjectRow = {
+  time_project_id: string | null
+  project_name: string | null
+  billable_minutes: number | string | null
+  nonbillable_minutes: number | string | null
+}
+
+function readReportId(req: Request): string | null {
+  const segments = new URL(req.url).pathname.split('/').filter(Boolean)
+  const last = segments[segments.length - 1]
+  const parsed = paramsSchema.safeParse({ id: last })
+  return parsed.success ? parsed.data.id : null
+}
+
+export async function GET(req: Request) {
+  try {
+    const scopeOrResponse = await resolvePortalScope(req)
+    if (scopeOrResponse instanceof Response) return scopeOrResponse
+    const scope = scopeOrResponse
+
+    const reportId = readReportId(req)
+    if (!reportId) {
+      return NextResponse.json({ ok: false, error: 'staff.errors.invalidInput' }, { status: 400 })
+    }
+
+    const connection = scope.em.getConnection()
+    const owned = portalOwnedReportClause(scope)
+    const rows = (await connection.execute(
+      `
+        SELECT id, reference, title, period_from, period_to, closed_at,
+               total_billable_minutes, total_nonbillable_minutes
+        FROM staff_time_reports
+        WHERE ${owned.sql} AND id = ?
+        LIMIT 1
+      `,
+      [...owned.params, reportId],
+    )) as ReportRow[]
+
+    const report = rows?.[0]
+    if (!report) {
+      return NextResponse.json({ ok: false, error: 'staff.errors.notFound' }, { status: 404 })
+    }
+
+    const periodFrom = toIsoDate(report.period_from)
+    const periodTo = toIsoDate(report.period_to)
+    if (!periodFrom || !periodTo) {
+      return NextResponse.json({ ok: false, error: 'staff.errors.notFound' }, { status: 404 })
+    }
+
+    const projectRows = (await connection.execute(
+      `
+        SELECT entry.time_project_id AS time_project_id,
+               project.name AS project_name,
+               COALESCE(SUM(CASE WHEN line.frozen_is_billable THEN line.frozen_rounded_minutes ELSE 0 END), 0) AS billable_minutes,
+               COALESCE(SUM(CASE WHEN line.frozen_is_billable THEN 0 ELSE line.frozen_rounded_minutes END), 0) AS nonbillable_minutes
+        FROM staff_time_report_entries line
+        JOIN staff_time_entries entry
+          ON entry.id = line.time_entry_id
+         AND entry.tenant_id = line.tenant_id
+         AND entry.organization_id = line.organization_id
+        LEFT JOIN staff_time_projects project
+          ON project.id = entry.time_project_id
+         AND project.tenant_id = line.tenant_id
+         AND project.organization_id = line.organization_id
+        WHERE line.report_id = ?
+          AND line.tenant_id = ?
+          AND line.organization_id = ?
+        GROUP BY entry.time_project_id, project.name
+        ORDER BY project.name ASC NULLS LAST
+      `,
+      [report.id, scope.tenantId, scope.organizationId],
+    )) as ProjectRow[]
+
+    return NextResponse.json(
+      detailResponseSchema.parse({
+        id: report.id,
+        reference: report.reference,
+        title: report.title,
+        periodFrom,
+        periodTo,
+        closedAt:
+          report.closed_at instanceof Date
+            ? report.closed_at.toISOString()
+            : typeof report.closed_at === 'string' && report.closed_at.trim().length > 0
+              ? report.closed_at
+              : null,
+        totalBillableMinutes: toMinutes(report.total_billable_minutes),
+        totalNonbillableMinutes: toMinutes(report.total_nonbillable_minutes),
+        projects: projectRows.map((row) => ({
+          timeProjectId: row.time_project_id ?? null,
+          projectName: row.project_name ?? null,
+          billableMinutes: toMinutes(row.billable_minutes),
+          nonbillableMinutes: toMinutes(row.nonbillable_minutes),
+        })),
+      }),
+    )
+  } catch (err) {
+    logger.error('staff portal time-report detail failed', { err })
+    return NextResponse.json({ ok: false, error: 'staff.errors.internal' }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff Portal',
+  pathParams: paramsSchema,
+  methods: {
+    GET: {
+      summary: 'Read one closed time report belonging to the signed-in customer',
+      description:
+        'Loads the report by id **together with** the tenant, organization, customer and closed-status predicates, so a report belonging to another customer of the same organization answers 404. Returns the frozen minute totals per project; no rate, cost, amount or currency is present in the response.',
+      pathParams: paramsSchema,
+      responses: [{ status: 200, description: 'The report', schema: detailResponseSchema }],
+      errors: [
+        { status: 401, description: 'Not signed in to the portal', schema: errorResponseSchema },
+        { status: 403, description: 'The portal account is not linked to a customer', schema: errorResponseSchema },
+        { status: 404, description: 'No closed report with that id belongs to this customer', schema: errorResponseSchema },
+      ],
+    },
+  },
+}