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

package/src/modules/staff/api/timesheets/time-entries/[id]/duplicate/route.ts

@@ -0,0 +1,306 @@
+/**
+ * US-D6 — "repeat yesterday", for one entry.
+ *
+ * The row action on screen 10 and the per-row copy button on screen 1 both land
+ * here. The route is deliberately thin: T4.2 already put the whole copy in the
+ * `staff.timesheets.time_entries.duplicate` command, which resolves the SOURCE,
+ * runs it past the lock gate and then delegates the write to the create command
+ * so the copy inherits ownership enforcement, project access, the billable and
+ * currency defaults, rounding (D-7), tag syncing and the audit entry unchanged.
+ * Nothing here re-implements any of that.
+ *
+ * Two things the route owns that the command cannot:
+ *
+ *  1. **Existence is decided by the caller's project access, not by the row.** The
+ *     source is looked up through the same intersection the list route applies —
+ *     entries on projects the caller belongs to, plus their own project-less
+ *     entries — and anything outside it answers `404`, never `403`. A `403` on a
+ *     project the caller cannot see would confirm the entry exists and name the
+ *     project it belongs to.
+ *  2. **`date` and `durationMinutes` overrides.** US-D6 ends with "I adjust the
+ *     duration and the date", so both travel with the copy request instead of
+ *     costing a follow-up PUT that would briefly show the wrong duration.
+ *
+ * `tagIds` is passed in by the caller rather than read off the junction: the
+ * command writes tags only through the tag commands and never touches
+ * `staff_time_entry_tags`, and the client already holds the source's `tags[]`
+ * from the list response.
+ */
+
+import { NextResponse } from 'next/server'
+import { resolveFeatureAccess } from '../../../../../lib/time-tracking/featureAccess'
+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, forbidden, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { runRouteMutationGuards } from '@open-mercato/shared/lib/crud/route-mutation-guard'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { emitStaffEvent } from '../../../../../events'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import type { ModuleConfigService } from '@open-mercato/core/modules/configs/lib/module-config-service'
+import { StaffTimeEntry } from '../../../../../data/entities'
+import { staffTimeEntryCommandIds } from '../../../../../commands/timesheets-entries'
+import { resolveProjectAccess, type ProjectAccess } from '../../../../../lib/time-tracking/access'
+import { readTimeTrackingSettings } from '../../../../../lib/time-tracking/settings'
+import { STAFF_TIME_TRACKING_RESOURCE_KINDS } from '../../../../guards'
+import { runTimesheetInterceptors } from '../../../_shared/withTimesheetInterceptors'
+
+const logger = createLogger('staff').child({ component: 'api/timesheets/time-entries/duplicate' })
+
+const MANAGE_OWN_FEATURE = 'staff.timesheets.manage_own'
+const RESOURCE_KIND = STAFF_TIME_TRACKING_RESOURCE_KINDS.timeEntry
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: [MANAGE_OWN_FEATURE] },
+}
+
+const duplicateRequestSchema = z.object({
+  date: z.coerce.date().optional(),
+  durationMinutes: z.number().int().min(0).max(1440).optional(),
+  tagIds: z.array(z.string().uuid()).max(50).optional(),
+})
+
+const duplicateResponseSchema = z.object({
+  id: z.string().uuid(),
+  sourceId: z.string().uuid(),
+})
+
+const lockedConflictSchema = z.object({
+  code: z.literal('time_entry_locked'),
+  error: z.string(),
+  lockedReportId: z.string().uuid().nullable(),
+  lockedEntryIds: z.array(z.string().uuid()),
+  lockedReportIds: z.array(z.string().uuid()),
+})
+
+type ContainerLike = { resolve: (name: string) => unknown }
+
+function extractEntryIdFromUrl(request?: Request): string | null {
+  if (!request?.url) return null
+  try {
+    const url = new URL(request.url)
+    const match = url.pathname.match(/\/time-entries\/([^/]+)\/duplicate/)
+    return match?.[1] ?? null
+  } catch {
+    return null
+  }
+}
+
+async function resolveAssignmentGraceDays(container: ContainerLike, tenantId: string): Promise<number | null> {
+  try {
+    const configService = container.resolve('moduleConfigService') as ModuleConfigService
+    const settings = await readTimeTrackingSettings(configService, { tenantId })
+    return settings.access.assignmentGraceDays
+  } catch {
+    // Fail safe to the documented default rather than widening the window.
+    return null
+  }
+}
+
+async function loadProjectAccess(
+  container: ContainerLike,
+  userId: string | null,
+  tenantId: string,
+  organizationId: string,
+  grantedFeatures: readonly string[],
+): Promise<ProjectAccess> {
+  const em = container.resolve('em') as EntityManager
+  return resolveProjectAccess({
+    em: em.fork(),
+    userId,
+    tenantId,
+    organizationId,
+    userFeatures: grantedFeatures,
+    assignmentGraceDays: await resolveAssignmentGraceDays(container, tenantId),
+  })
+}
+
+/**
+ * The per-row form of the list route's `$or` intersection: an entry on a project
+ * is visible to the members of that project, and a project-less entry is visible
+ * only to the member who logged it.
+ */
+function isTimeEntryVisible(
+  entry: { staffMemberId: string; timeProjectId?: string | null },
+  access: ProjectAccess,
+): boolean {
+  if (access.canManageAll) return true
+  const projectId = entry.timeProjectId ?? null
+  if (projectId) return access.projectIds.includes(projectId)
+  return access.staffMemberId !== null && access.staffMemberId === entry.staffMemberId
+}
+
+export async function POST(req: Request) {
+  try {
+    const container = await createRequestContainer()
+    const auth = await getAuthFromRequest(req)
+    const { translate } = await resolveTranslations()
+    if (!auth) {
+      throw new CrudHttpError(401, { error: translate('staff.errors.unauthorized', 'Unauthorized') })
+    }
+
+    const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    const tenantId = scope?.tenantId ?? auth.tenantId ?? null
+    const organizationId = scope?.selectedId ?? auth.orgId ?? null
+    if (!tenantId || !organizationId) {
+      throw new CrudHttpError(400, {
+        error: translate('staff.errors.missingScope', 'Missing tenant or organization scope.'),
+      })
+    }
+
+    const timeEntryId = extractEntryIdFromUrl(req)
+    if (!timeEntryId) {
+      throw new CrudHttpError(400, {
+        error: translate('staff.timesheets.errors.missingEntryId', 'Missing entry ID.'),
+      })
+    }
+
+    const actorId = auth.sub ?? ''
+    // One lookup through the module's single RBAC authority: the decision is
+    // checked unconditionally and fails closed, and the grant list the plumbing
+    // takes comes from the same answer instead of a second, nullable read.
+    const manageOwn = await resolveFeatureAccess(container, actorId, [MANAGE_OWN_FEATURE], { tenantId, organizationId })
+    if (!manageOwn.allowed) {
+      throw forbidden(translate('staff.errors.forbidden', 'Forbidden'))
+    }
+    const grantedFeatures = manageOwn.grantedFeatures
+
+    const interceptors = await runTimesheetInterceptors({
+      request: req,
+      method: 'POST',
+      scope: { container, userId: actorId, tenantId, organizationId, userFeatures: grantedFeatures },
+      body: await readJsonSafe<Record<string, unknown>>(req, {}),
+    })
+    if (!interceptors.ok) return interceptors.response
+    const { session } = interceptors
+
+    const parsed = duplicateRequestSchema.parse(session.body)
+
+    // The source is resolved here, before the command, purely so an entry the
+    // caller cannot see answers 404 instead of the command's 403 — which would
+    // confirm the entry exists and name the project that hides it.
+    const em = (container.resolve('em') as EntityManager).fork()
+    const source = await findOneWithDecryption(
+      em,
+      StaffTimeEntry,
+      { id: timeEntryId, tenantId, organizationId, deletedAt: null },
+      {},
+      { tenantId, organizationId },
+    )
+    const access = await loadProjectAccess(container, actorId || null, tenantId, organizationId, grantedFeatures)
+    if (!source || !isTimeEntryVisible(source, access)) {
+      throw new CrudHttpError(404, {
+        error: translate('staff.timesheets.errors.entryNotFound', 'Time entry not found, deleted, or not owned by you.'),
+      })
+    }
+
+    const guardResult = await runRouteMutationGuards({
+      container,
+      req,
+      auth: {
+        userId: actorId,
+        tenantId,
+        organizationId,
+        userFeatures: grantedFeatures,
+      },
+      input: {
+        resourceKind: RESOURCE_KIND,
+        resourceId: timeEntryId,
+        operation: 'create',
+        mutationPayload: parsed,
+      },
+    })
+    if (!guardResult.ok) return guardResult.response
+
+    const effective = guardResult.modifiedPayload
+      ? duplicateRequestSchema.parse({ ...parsed, ...guardResult.modifiedPayload })
+      : parsed
+
+    const ctx: CommandRuntimeContext = {
+      container,
+      auth,
+      organizationScope: scope,
+      selectedOrganizationId: scope?.selectedId ?? auth.orgId ?? null,
+      organizationIds: scope?.filterIds ?? (auth.orgId ? [auth.orgId] : null),
+      request: req,
+    }
+
+    const commandBus = container.resolve('commandBus') as CommandBus
+    const { result } = await commandBus.execute<unknown, { timeEntryId: string }>(
+      staffTimeEntryCommandIds.duplicate,
+      { input: { ...effective, id: timeEntryId }, ctx },
+    )
+
+    await guardResult.runAfterSuccess()
+
+    if (result?.timeEntryId) {
+      void emitStaffEvent('staff.timesheets.time_entry.copied', {
+        id: result.timeEntryId,
+        sourceId: timeEntryId,
+        tenantId,
+        organizationId,
+      }, { persistent: true }).catch((err) => {
+        logger.error('staff.timesheets emit time_entry.copied failed', { err })
+      })
+    }
+
+    return session.respond(201, { id: result?.timeEntryId ?? null, sourceId: timeEntryId })
+  } 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.time-entries.duplicate failed', { err })
+    return NextResponse.json(
+      { error: translate('staff.errors.internal', 'Internal server error') },
+      { status: 500 },
+    )
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Duplicate a time entry',
+  methods: {
+    POST: {
+      summary: 'Duplicate a time entry',
+      description:
+        'US-D6. Copies an existing time entry, carrying its task, project, description, billable flag and rate override across. `date` and `durationMinutes` override the copy without a second request; `tagIds` sets the copy tag set (the caller passes the source tags it already holds from the list response). The copy is written through the create command, so ownership, project access, the billable and currency defaults, and the tenant rounding rule apply to it exactly as they do to a hand-made entry. A source locked into a closed report is refused with 409 `time_entry_locked`; a source the caller cannot see answers 404.',
+      requestBody: {
+        contentType: 'application/json',
+        schema: duplicateRequestSchema,
+      },
+      responses: [
+        { status: 201, description: 'Copy created', schema: duplicateResponseSchema },
+      ],
+      errors: [
+        { status: 400, description: 'Invalid body or missing scope' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'Missing staff.timesheets.manage_own' },
+        { status: 404, description: 'Time entry not found, deleted, or outside the caller project access' },
+        {
+          status: 409,
+          description: 'The source entry is locked into a closed report; nothing was copied',
+          schema: lockedConflictSchema,
+        },
+      ],
+    },
+  },
+}

package/src/modules/staff/api/timesheets/time-entries/[id]/segments/[segmentId]/route.ts

@@ -12,12 +12,17 @@ import { LockMode } from '@mikro-orm/core'
 import { StaffTimeEntry, StaffTimeEntrySegment } from '../../../../../../data/entities'
 import { staffTimeEntrySegmentUpdateSchema } from '../../../../../../data/validators'
 import { getStaffMemberByUserId } from '../../../../../../lib/staffMemberResolver'
+import { emitStaffEvent } from '../../../../../../events'
+import { runTimesheetInterceptors } from '../../../../_shared/withTimesheetInterceptors'
+import { createLogger } from '@open-mercato/shared/lib/logger'
 import {
-  resolveUserFeatures,
+  STAFF_TIME_TRACKING_RESOURCE_KINDS,
   runStaffMutationGuardAfterSuccess,
   runStaffMutationGuards,
 } from '../../../../../guards'
 
+const logger = createLogger('staff').child({ component: 'api/timesheets/time-entries/segments' })
+
 const routeMetadata = {
   PATCH: { requireAuth: true, requireFeatures: ['staff.timesheets.manage_own'] },
 }
@@ -52,11 +57,6 @@ export async function PATCH(req: Request) {
     return NextResponse.json({ error: 'Invalid payload' }, { status: 400 })
   }
 
-  const parsed = staffTimeEntrySegmentUpdateSchema.safeParse({ ...rawBody, id: ids.segmentId })
-  if (!parsed.success) {
-    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 400 })
-  }
-
   const container = await createRequestContainer()
   const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
   const tenantId = scope?.tenantId ?? auth.tenantId ?? null
@@ -65,6 +65,20 @@ export async function PATCH(req: Request) {
     return NextResponse.json({ error: 'Missing tenant or organization scope.' }, { status: 400 })
   }
 
+  const interceptors = await runTimesheetInterceptors({
+    request: req,
+    method: 'PATCH',
+    scope: { container, userId: auth.sub, tenantId, organizationId },
+    body: rawBody,
+  })
+  if (!interceptors.ok) return interceptors.response
+  const { session } = interceptors
+
+  const parsed = staffTimeEntrySegmentUpdateSchema.safeParse({ ...session.body, id: ids.segmentId })
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Invalid payload', details: parsed.error.flatten() }, { status: 400 })
+  }
+
   const em = (container.resolve('em') as EntityManager).fork()
   const scopeCtx = { tenantId, organizationId }
 
@@ -96,14 +110,13 @@ export async function PATCH(req: Request) {
       tenantId,
       organizationId,
       userId: auth.sub ?? '',
-      resourceKind: 'staff.timesheets.time_entry_segment',
+      resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeEntrySegment,
       resourceId: segment.id,
       operation: 'update',
       requestMethod: req.method,
       requestHeaders: req.headers,
       mutationPayload: parsed.data as unknown as Record<string, unknown>,
     },
-    resolveUserFeatures(auth),
   )
   if (!guardResult.ok) {
     return NextResponse.json(
@@ -166,7 +179,7 @@ export async function PATCH(req: Request) {
       tenantId,
       organizationId,
       userId: auth.sub ?? '',
-      resourceKind: 'staff.timesheets.time_entry_segment',
+      resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeEntrySegment,
       resourceId: updatedSegment.id,
       operation: 'update',
       requestMethod: req.method,
@@ -174,7 +187,16 @@ export async function PATCH(req: Request) {
     })
   }
 
-  return NextResponse.json({
+  void emitStaffEvent('staff.timesheets.time_entry_segment.updated', {
+    id: updatedSegment.id,
+    timeEntryId: updatedSegment.timeEntryId,
+    tenantId,
+    organizationId,
+  }, { persistent: true }).catch((err) => {
+    logger.error('staff.timesheets emit time_entry_segment.updated failed', { err })
+  })
+
+  return session.respond(200, {
     ok: true,
     item: {
       id: updatedSegment.id,

package/src/modules/staff/api/timesheets/time-entries/[id]/segments/route.ts

@@ -15,11 +15,13 @@ import { StaffTimeEntry, StaffTimeEntrySegment } from '../../../../../data/entit
 import { staffTimeEntrySegmentCreateSchema } from '../../../../../data/validators'
 import { getStaffMemberByUserId } from '../../../../../lib/staffMemberResolver'
 import {
-  resolveUserFeatures,
+  STAFF_TIME_TRACKING_RESOURCE_KINDS,
   runStaffMutationGuardAfterSuccess,
   runStaffMutationGuards,
 } from '../../../../guards'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { emitStaffEvent } from '../../../../../events'
+import { runTimesheetInterceptors } from '../../../_shared/withTimesheetInterceptors'
 
 const logger = createLogger('staff')
 
@@ -76,10 +78,18 @@ export async function POST(req: Request) {
       throw new CrudHttpError(403, { error: translate('staff.timesheets.errors.notOwner', 'You can only manage your own time entries.') })
     }
 
-    const body = await readJsonSafe(req, {})
+    const interceptors = await runTimesheetInterceptors({
+      request: req,
+      method: 'POST',
+      scope: { container, userId: auth.sub, tenantId, organizationId },
+      body: await readJsonSafe<Record<string, unknown>>(req, {}),
+    })
+    if (!interceptors.ok) return interceptors.response
+    const { session } = interceptors
+
     const input = parseScopedCommandInput(
       staffTimeEntrySegmentCreateSchema,
-      { ...body, timeEntryId: entryId },
+      { ...session.body, timeEntryId: entryId },
       {
         container,
         auth,
@@ -97,14 +107,13 @@ export async function POST(req: Request) {
         tenantId,
         organizationId,
         userId: auth.sub ?? '',
-        resourceKind: 'staff.timesheets.time_entry_segment',
+        resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeEntrySegment,
         resourceId: entry.id,
         operation: 'create',
         requestMethod: req.method,
         requestHeaders: req.headers,
         mutationPayload: input as unknown as Record<string, unknown>,
       },
-      resolveUserFeatures(auth),
     )
     if (!guardResult.ok) {
       return NextResponse.json(
@@ -148,7 +157,7 @@ export async function POST(req: Request) {
         tenantId,
         organizationId,
         userId: auth.sub ?? '',
-        resourceKind: 'staff.timesheets.time_entry_segment',
+        resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeEntrySegment,
         resourceId: segment.id,
         operation: 'create',
         requestMethod: req.method,
@@ -156,17 +165,23 @@ export async function POST(req: Request) {
       })
     }
 
-    return NextResponse.json(
-      {
-        id: segment.id,
-        timeEntryId: segment.timeEntryId,
-        startedAt: segment.startedAt,
-        endedAt: segment.endedAt ?? null,
-        segmentType: segment.segmentType,
-        createdAt: segment.createdAt,
-      },
-      { status: 201 },
-    )
+    void emitStaffEvent('staff.timesheets.time_entry_segment.created', {
+      id: segment.id,
+      timeEntryId: segment.timeEntryId,
+      tenantId,
+      organizationId,
+    }, { persistent: true }).catch((err) => {
+      logger.error('staff.timesheets emit time_entry_segment.created failed', { err })
+    })
+
+    return session.respond(201, {
+      id: segment.id,
+      timeEntryId: segment.timeEntryId,
+      startedAt: segment.startedAt,
+      endedAt: segment.endedAt ?? null,
+      segmentType: segment.segmentType,
+      createdAt: segment.createdAt,
+    })
   } catch (err) {
     if (err instanceof CrudHttpError) {
       return NextResponse.json(err.body, { status: err.status })

package/src/modules/staff/api/timesheets/time-entries/[id]/timer-start/route.ts

@@ -10,14 +10,16 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import { LockMode } from '@mikro-orm/core'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { StaffTimeEntry, StaffTimeEntrySegment } from '../../../../../data/entities'
+import { assertTimeEntryUnlocked } from '../../../../../commands/timesheets-entries'
 import { getStaffMemberByUserId } from '../../../../../lib/staffMemberResolver'
 import {
-  resolveUserFeatures,
+  STAFF_TIME_TRACKING_RESOURCE_KINDS,
   runStaffMutationGuardAfterSuccess,
   runStaffMutationGuards,
 } from '../../../../guards'
 import { emitStaffEvent } from '../../../../../events'
 import { invalidateStaffTimeEntryCache } from '../../../../../lib/timesheets/timeEntryCacheInvalidation'
+import { runTimesheetInterceptors } from '../../../_shared/withTimesheetInterceptors'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('staff')
@@ -51,6 +53,14 @@ export async function POST(req: Request) {
       throw new CrudHttpError(400, { error: translate('staff.errors.missingScope', 'Missing tenant or organization scope.') })
     }
 
+    const interceptors = await runTimesheetInterceptors({
+      request: req,
+      method: 'POST',
+      scope: { container, userId: auth.sub, tenantId, organizationId },
+    })
+    if (!interceptors.ok) return interceptors.response
+    const { session } = interceptors
+
     const em = (container.resolve('em') as EntityManager).fork()
     const scopeCtx = { tenantId, organizationId }
 
@@ -75,6 +85,10 @@ export async function POST(req: Request) {
       throw new CrudHttpError(403, { error: translate('staff.timesheets.errors.notOwner', 'You can only manage your own time entries.') })
     }
 
+    // Running a timer on a frozen entry is only ever the first half of changing
+    // its duration, so it is refused at the same gate the entries command uses.
+    assertTimeEntryUnlocked(entry, translate)
+
     if (entry.startedAt) {
       return NextResponse.json(
         { error: translate('staff.timesheets.errors.timerAlreadyStarted', 'Timer is already started for this entry.') },
@@ -88,13 +102,12 @@ export async function POST(req: Request) {
         tenantId,
         organizationId,
         userId: auth.sub ?? '',
-        resourceKind: 'staff.timesheets.time_entry',
+        resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeEntry,
         resourceId: entry.id,
         operation: 'update',
         requestMethod: req.method,
         requestHeaders: req.headers,
       },
-      resolveUserFeatures(auth),
     )
     if (!guardResult.ok) {
       return NextResponse.json(
@@ -118,6 +131,9 @@ export async function POST(req: Request) {
       if (!lockedEntry) {
         throw new CrudHttpError(404, { error: translate('staff.timesheets.errors.entryNotFound', 'Time entry not found.') })
       }
+      // Re-checked under the row lock: a report close committed between the
+      // pre-flight read and this transaction would otherwise slip through.
+      assertTimeEntryUnlocked(lockedEntry, translate)
       if (lockedEntry.startedAt) {
         throw new CrudHttpError(409, {
           error: translate('staff.timesheets.errors.timerAlreadyStarted', 'Timer is already started for this entry.'),
@@ -193,7 +209,7 @@ export async function POST(req: Request) {
         tenantId,
         organizationId,
         userId: auth.sub ?? '',
-        resourceKind: 'staff.timesheets.time_entry',
+        resourceKind: STAFF_TIME_TRACKING_RESOURCE_KINDS.timeEntry,
         resourceId: entry.id,
         operation: 'update',
         requestMethod: req.method,
@@ -201,7 +217,7 @@ export async function POST(req: Request) {
       })
     }
 
-    return NextResponse.json({ ok: true }, { status: 200 })
+    return session.respond(200, { ok: true })
   } catch (err) {
     if (err instanceof CrudHttpError) {
       return NextResponse.json(err.body, { status: err.status })
@@ -225,7 +241,12 @@ export const openApi: OpenApiRouteDoc = {
       responses: [
         { status: 200, description: 'Timer started', schema: z.object({ ok: z.literal(true) }) },
         { status: 404, description: 'Time entry not found', schema: z.object({ error: z.string() }) },
-        { status: 409, description: 'Timer already started, or another timer is already running for this staff member', schema: z.object({ error: z.string() }) },
+        {
+          status: 409,
+          description:
+            'Timer already started, another timer is already running for this staff member, or the entry is locked in a closed report (code time_entry_locked)',
+          schema: z.object({ error: z.string(), code: z.string().optional(), lockedReportId: z.string().uuid().nullable().optional() }),
+        },
         { status: 401, description: 'Unauthorized', schema: z.object({ error: z.string() }) },
       ],
     },