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

package/src/modules/staff/api/timesheets/settings/reapply-rounding/route.ts

@@ -0,0 +1,205 @@
+/**
+ * `POST /api/staff/timesheets/settings/reapply-rounding` — screen 16 note 3 (T7.3).
+ *
+ * The mockup draws retroactive rounding as a switch. It is implemented as an
+ * **action**, because the two are not the same promise: a switch that rewrites
+ * `rounded_minutes` across a tenant's history when the settings form is saved
+ * changes invoiced amounts as a side effect of an unrelated save. This endpoint
+ * makes it something a person does, once, on purpose, with a progress bar and a
+ * final count.
+ *
+ * It enqueues; it does not do the work. Restating a tenant's entries is exactly the
+ * long-running job the progress module exists for, so the response is a `202` with
+ * a `progressJobId` that the top bar picks up on its own.
+ *
+ * Locked entries are never touched — the candidate query excludes them and the
+ * command excludes them again, independently.
+ */
+
+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 { authorizeFeatures } from '@open-mercato/shared/security/featurePolicy'
+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 type { ProgressService } from '../../../../../progress/lib/progressService'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { STAFF_TIME_TRACKING_RESOURCE_KINDS } from '../../../guards'
+import { runTimesheetInterceptors } from '../../_shared/withTimesheetInterceptors'
+import {
+  STAFF_TIME_REAPPLY_ROUNDING_JOB_TYPE,
+  STAFF_TIME_REAPPLY_ROUNDING_QUEUE,
+  countReapplyRoundingCandidates,
+  getStaffQueue,
+  type ReapplyRoundingScope,
+} from '../../../../lib/time-tracking/reapplyRounding'
+
+const logger = createLogger('staff').child({ component: 'api/timesheets/settings/reapply-rounding' })
+
+const MANAGE_FEATURE = 'staff.timesheets.settings.manage'
+const RESOURCE_KIND = STAFF_TIME_TRACKING_RESOURCE_KINDS.settings
+const RESOURCE_ID = 'time_tracking'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: [MANAGE_FEATURE] },
+}
+
+const responseSchema = z.object({
+  ok: z.boolean(),
+  progressJobId: z.string().uuid().nullable(),
+  /** Entries eligible for restatement — locked ones are not among them. */
+  candidateCount: z.number().int(),
+})
+
+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 organizationScope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+    const tenantId = organizationScope?.tenantId ?? auth.tenantId ?? null
+    if (!tenantId) {
+      throw new CrudHttpError(400, {
+        error: translate('staff.errors.missingScope', 'Missing tenant or organization scope.'),
+      })
+    }
+
+    const actorId = typeof auth.sub === 'string' && auth.sub.trim().length > 0 ? auth.sub : 'system'
+    const organizationId = organizationScope?.selectedId ?? auth.orgId ?? null
+
+    // 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 access = await resolveFeatureAccess(container, actorId, [MANAGE_FEATURE], { tenantId, organizationId })
+    if (!access.allowed) {
+      throw forbidden(translate('staff.errors.forbidden', 'Forbidden'))
+    }
+    const grantedFeatures = access.grantedFeatures
+
+    const interceptors = await runTimesheetInterceptors({
+      request: req,
+      method: 'POST',
+      scope: {
+        container,
+        userId: actorId,
+        tenantId,
+        organizationId,
+        userFeatures: grantedFeatures,
+        tenantGlobal: true,
+      },
+      body: await readJsonSafe<Record<string, unknown>>(req, {}),
+    })
+    if (!interceptors.ok) return interceptors.response
+    const { session } = interceptors
+
+    const guardResult = await runRouteMutationGuards({
+      container,
+      req,
+      auth: {
+        userId: actorId,
+        tenantId,
+        organizationId,
+        userFeatures: grantedFeatures,
+      },
+      input: {
+        resourceKind: RESOURCE_KIND,
+        resourceId: RESOURCE_ID,
+        operation: 'update',
+        mutationPayload: { action: 'reapply-rounding' },
+      },
+    })
+    if (!guardResult.ok) return guardResult.response
+
+    const scope: ReapplyRoundingScope = {
+      tenantId,
+      // `filterIds === null` means the caller may act across every organization of
+      // the tenant, which is what a tenant-global rule is about; anything narrower
+      // restates only what the caller can already see.
+      organizationIds: organizationScope?.filterIds ?? (organizationId ? [organizationId] : null),
+      userId: actorId,
+    }
+
+    const em = container.resolve('em') as EntityManager
+    const candidateCount = await countReapplyRoundingCandidates(em.fork(), scope)
+    if (candidateCount === 0) {
+      // Nothing to restate: no job, no progress bar, no queue traffic. The caller
+      // gets an honest zero rather than a job that completes instantly.
+      await guardResult.runAfterSuccess()
+      return session.respond(200, responseSchema.parse({ ok: true, progressJobId: null, candidateCount: 0 }))
+    }
+
+    const progressService = container.resolve('progressService') as ProgressService
+    const progressJob = await progressService.createJob(
+      {
+        jobType: STAFF_TIME_REAPPLY_ROUNDING_JOB_TYPE,
+        name: translate('staff.time_tracking.settings.retro.jobName', 'Reapply rounding to existing entries'),
+        description: translate(
+          'staff.time_tracking.settings.retro.jobDescription',
+          'Recomputing rounded time on existing entries. Locked entries are not changed.',
+        ),
+        totalCount: candidateCount,
+        cancellable: true,
+        meta: { source: 'staff.timesheets.settings.reapply-rounding' },
+      },
+      { tenantId, organizationId, userId: actorId },
+    )
+
+    const queue = getStaffQueue(STAFF_TIME_REAPPLY_ROUNDING_QUEUE)
+    await queue.enqueue({ progressJobId: progressJob.id, scope })
+
+    await guardResult.runAfterSuccess()
+
+    void emitStaffEvent('staff.timesheets.time_tracking.rounding_reapplied', {
+      tenantId,
+      organizationId,
+      progressJobId: progressJob.id,
+      candidateCount,
+    }, { persistent: true }).catch((err) => {
+      logger.error('staff.timesheets emit time_tracking.rounding_reapplied failed', { err })
+    })
+
+    return session.respond(202, responseSchema.parse({ ok: true, progressJobId: progressJob.id, candidateCount }))
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    logger.error('staff.timesheets.settings.reapply-rounding failed', { err })
+    const { translate } = await resolveTranslations()
+    return NextResponse.json(
+      { error: translate('staff.errors.internal', 'Internal server error') },
+      { status: 500 },
+    )
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Reapply the rounding rule to existing entries',
+  methods: {
+    POST: {
+      summary: 'Queue a retroactive rounding job',
+      description:
+        'Enqueues a `ProgressJob` that recomputes `rounded_minutes` on existing time entries under the tenant’s current rounding rule. Entries locked into a closed report are excluded — a billed amount is never restated. Returns `202` with `progressJobId`, or `200` with a null job id when there is nothing to restate.',
+      responses: [
+        { status: 200, description: 'Nothing to restate', schema: responseSchema },
+        { status: 202, description: 'Job queued', schema: responseSchema },
+        { status: 400, description: 'Missing scope', schema: z.object({ error: z.string() }) },
+        { status: 401, description: 'Unauthorized', schema: z.object({ error: z.string() }) },
+        { status: 403, description: 'Missing staff.timesheets.settings.manage' },
+        { status: 500, description: 'Queueing failure', schema: z.object({ error: z.string() }) },
+      ],
+    },
+  },
+}

package/src/modules/staff/api/timesheets/settings/rounding-impact/route.ts

@@ -0,0 +1,226 @@
+/**
+ * `GET /api/staff/timesheets/settings/rounding-impact` — screen 16's 90-day preview (T7.2).
+ *
+ * Rounding is the one setting on that screen that moves money, and its effect is
+ * invisible until an invoice goes out. This route answers "what would the last 90
+ * days have billed under the rule I am about to save" before the Save button is
+ * pressed, so changing it stops being a blind shot at client amounts.
+ *
+ * Three deliberate properties:
+ *
+ *  * **Locked entries are excluded.** An entry frozen into a closed report cannot
+ *    be restated, so counting it in the projection would promise a change that the
+ *    retro-rounding job would then refuse to make. They are counted separately and
+ *    returned as `lockedEntryCount`, which is what lets the screen say "closed
+ *    reports stay as they are" from data rather than as boilerplate.
+ *  * **The projection is per entry** (D-7) — the database groups identical
+ *    durations and `projectRoundingImpact` rounds each distinct duration once,
+ *    through the same `roundMinutes` the write path uses.
+ *  * **The candidate rule comes from the query string**, defaulting to what is
+ *    stored, so the card recomputes as the toggles move without saving anything.
+ */
+
+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 } 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 type { ModuleConfigService } from '@open-mercato/core/modules/configs/lib/module-config-service'
+import { readTimeTrackingSettings } from '../../../../lib/time-tracking/settings'
+import type { RoundingDirection, RoundingSettings, RoundingUnitMinutes } from '../../../../lib/time-tracking/rounding'
+import { projectRoundingImpact, type DurationBucket } from '../../../../lib/time-tracking/roundingImpact'
+import { buildSqlInClause } from '../../../../lib/time-tracking/sqlInClause'
+
+const logger = createLogger('staff').child({ component: 'api/timesheets/settings/rounding-impact' })
+
+const MANAGE_FEATURE = 'staff.timesheets.settings.manage'
+
+export const DEFAULT_IMPACT_WINDOW_DAYS = 90
+const MAX_IMPACT_WINDOW_DAYS = 365
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: [MANAGE_FEATURE] },
+}
+
+const querySchema = z.object({
+  unitMinutes: z.coerce.number().optional(),
+  direction: z.enum(['up', 'nearest']).optional(),
+  windowDays: z.coerce.number().int().min(1).max(MAX_IMPACT_WINDOW_DAYS).optional(),
+})
+
+const impactSchema = z.object({
+  entryCount: z.number().int(),
+  rawMinutes: z.number().int(),
+  roundedMinutes: z.number().int(),
+  deltaMinutes: z.number().int(),
+})
+
+const responseSchema = z.object({
+  windowDays: z.number().int(),
+  from: z.string(),
+  to: z.string(),
+  rounding: z.object({
+    unitMinutes: z.union([z.literal(0), z.literal(5), z.literal(10), z.literal(15)]),
+    direction: z.enum(['up', 'nearest']),
+  }),
+  /** The projection under the requested (or stored) rule, locked entries excluded. */
+  projected: impactSchema,
+  /** The same window under the rule currently stored, so the screen can show the move. */
+  current: impactSchema,
+  /** Entries in the window that a rounding change can never restate. */
+  lockedEntryCount: z.number().int(),
+})
+
+const ROUNDING_UNITS: readonly number[] = [0, 5, 10, 15]
+
+type BucketRow = {
+  duration_minutes: string | number | null
+  entry_count: string | number | null
+}
+
+type LockedRow = {
+  locked_count: string | number | null
+}
+
+function toDateOnlyString(value: Date): string {
+  return value.toISOString().slice(0, 10)
+}
+
+export async function GET(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
+    if (!tenantId) {
+      throw new CrudHttpError(400, {
+        error: translate('staff.errors.missingScope', 'Missing tenant or organization scope.'),
+      })
+    }
+
+    const url = new URL(req.url)
+    const parsedQuery = querySchema.safeParse(Object.fromEntries(url.searchParams.entries()))
+    if (!parsedQuery.success) {
+      throw new CrudHttpError(400, {
+        error: translate('staff.errors.invalid_request', 'Invalid request'),
+        details: parsedQuery.error.issues,
+      })
+    }
+
+    const configService = container.resolve('moduleConfigService') as ModuleConfigService
+    const stored = await readTimeTrackingSettings(configService, { tenantId })
+
+    const requestedUnit = parsedQuery.data.unitMinutes
+    const candidate: RoundingSettings = {
+      unitMinutes:
+        typeof requestedUnit === 'number' && ROUNDING_UNITS.includes(requestedUnit)
+          ? (requestedUnit as RoundingUnitMinutes)
+          : stored.rounding.unitMinutes,
+      direction: (parsedQuery.data.direction ?? stored.rounding.direction) as RoundingDirection,
+    }
+
+    const windowDays = parsedQuery.data.windowDays ?? DEFAULT_IMPACT_WINDOW_DAYS
+    const to = new Date()
+    const from = new Date(to.getTime() - (windowDays - 1) * 24 * 60 * 60 * 1000)
+    const fromDate = toDateOnlyString(from)
+    const toDate = toDateOnlyString(to)
+
+    // Organizations narrow the same way every other read in the module does; a null
+    // filter list means "every organization of this tenant", which is what a
+    // tenant-global setting is asking about.
+    const organizationIds = scope?.filterIds ?? null
+    const orgIn = organizationIds ? buildSqlInClause('organization_id', organizationIds) : null
+    const orgClause = orgIn ? ` AND ${orgIn.sql}` : ''
+    const orgParams = orgIn ? orgIn.params : []
+
+    const em = container.resolve('em') as EntityManager
+    const connection = em.getConnection()
+
+    const bucketRows = (await connection.execute(
+      `
+        SELECT duration_minutes, COUNT(*)::bigint AS entry_count
+        FROM staff_time_entries
+        WHERE tenant_id = ?
+          AND deleted_at IS NULL
+          AND locked_report_id IS NULL
+          AND date >= ?::date
+          AND date <= ?::date${orgClause}
+        GROUP BY duration_minutes
+      `,
+      [tenantId, fromDate, toDate, ...orgParams],
+    )) as BucketRow[]
+
+    const lockedRows = (await connection.execute(
+      `
+        SELECT COUNT(*)::bigint AS locked_count
+        FROM staff_time_entries
+        WHERE tenant_id = ?
+          AND deleted_at IS NULL
+          AND locked_report_id IS NOT NULL
+          AND date >= ?::date
+          AND date <= ?::date${orgClause}
+      `,
+      [tenantId, fromDate, toDate, ...orgParams],
+    )) as LockedRow[]
+
+    const buckets: DurationBucket[] = (bucketRows ?? []).map((row) => ({
+      durationMinutes: Number(row.duration_minutes ?? 0),
+      entryCount: Number(row.entry_count ?? 0),
+    }))
+
+    const lockedRaw = Number(lockedRows?.[0]?.locked_count ?? 0)
+
+    return NextResponse.json(
+      {
+        windowDays,
+        from: fromDate,
+        to: toDate,
+        rounding: candidate,
+        projected: projectRoundingImpact(buckets, candidate),
+        current: projectRoundingImpact(buckets, stored.rounding),
+        lockedEntryCount: Number.isFinite(lockedRaw) ? lockedRaw : 0,
+      },
+      { status: 200 },
+    )
+  } catch (err) {
+    if (err instanceof CrudHttpError) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    logger.error('staff.timesheets.settings.rounding-impact failed', { err })
+    const { translate } = await resolveTranslations()
+    return NextResponse.json(
+      { error: translate('staff.errors.internal', 'Internal server error') },
+      { status: 500 },
+    )
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Rounding impact preview',
+  methods: {
+    GET: {
+      summary: 'Project the billing impact of a rounding rule over a recent window',
+      description:
+        'Answers what the last `windowDays` (default 90) would have billed under a candidate rounding rule, before it is saved. Entries already locked into a closed report are excluded from the projection — they cannot be restated — and reported separately as `lockedEntryCount`. Rounding is applied per entry (D-7) through the same helper the write path uses.',
+      query: querySchema,
+      responses: [
+        { status: 200, description: 'Rounding impact projection', schema: responseSchema },
+        { status: 400, description: 'Invalid request or missing scope', schema: z.object({ error: z.string() }) },
+        { status: 401, description: 'Unauthorized', schema: z.object({ error: z.string() }) },
+        { status: 403, description: 'Missing staff.timesheets.settings.manage' },
+        { status: 500, description: 'Projection failure', schema: z.object({ error: z.string() }) },
+      ],
+    },
+  },
+}

package/src/modules/staff/api/timesheets/settings/route.ts

@@ -0,0 +1,242 @@
+import { NextResponse } from 'next/server'
+import { resolveFeatureAccess } from '../../../lib/time-tracking/featureAccess'
+import { z } from 'zod'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+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 { createLogger } from '@open-mercato/shared/lib/logger'
+import { emitStaffEvent } from '../../../events'
+import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import type { ModuleConfigService } from '@open-mercato/core/modules/configs/lib/module-config-service'
+import { buildTimeTrackingSettingsSchema } from '../../../lib/time-tracking/settingKeys'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { STAFF_TIME_TRACKING_RESOURCE_KINDS } from '../../guards'
+import {
+  readSearchParamsRecord,
+  runTimesheetInterceptors,
+} from '../_shared/withTimesheetInterceptors'
+import {
+  readTimeTrackingSettings,
+  writeTimeTrackingSettings,
+  type TimeTrackingSettings,
+} from '../../../lib/time-tracking/settings'
+
+const logger = createLogger('staff').child({ component: 'api/timesheets/settings' })
+
+const VIEW_FEATURE = 'staff.timesheets.view'
+const MANAGE_FEATURE = 'staff.timesheets.settings.manage'
+const RESOURCE_KIND = STAFF_TIME_TRACKING_RESOURCE_KINDS.settings
+const RESOURCE_ID = 'time_tracking'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: [VIEW_FEATURE] },
+  PUT: { requireAuth: true, requireFeatures: [MANAGE_FEATURE] },
+}
+
+/**
+ * EP-42 — derived from the setting-key registry, so a contributed key is published in
+ * the OpenAPI response shape instead of being invisible to it. Rebuilt per read for the
+ * same reason the request schema is: a key may be registered after this module loads.
+ */
+function settingsResponseSchema(): z.ZodTypeAny {
+  return buildTimeTrackingSettingsSchema()
+}
+
+type SettingsContext = {
+  container: Awaited<ReturnType<typeof createRequestContainer>>
+  tenantId: string
+  organizationId: string | null
+  actorId: string
+  translate: (key: string, fallback?: string) => string
+}
+
+async function resolveSettingsContext(req: Request): Promise<SettingsContext> {
+  const container = await createRequestContainer()
+  const auth = await getAuthFromRequest(req)
+  const { translate } = await resolveTranslations()
+  if (!auth || !auth.tenantId) {
+    throw new CrudHttpError(401, { error: translate('staff.errors.unauthorized', 'Unauthorized') })
+  }
+  const actorId =
+    (typeof auth.sub === 'string' && auth.sub.trim().length > 0 && auth.sub) ||
+    (typeof auth.userId === 'string' && auth.userId.trim().length > 0 && auth.userId) ||
+    (typeof auth.keyId === 'string' && auth.keyId.trim().length > 0 && auth.keyId) ||
+    'system'
+  return {
+    container,
+    tenantId: auth.tenantId,
+    organizationId: auth.orgId ?? null,
+    actorId,
+    translate,
+  }
+}
+
+function resolveConfigService(context: SettingsContext): ModuleConfigService {
+  return context.container.resolve('moduleConfigService') as ModuleConfigService
+}
+
+async function GET(req: Request) {
+  try {
+    const context = await resolveSettingsContext(req)
+    const interceptors = await runTimesheetInterceptors({
+      request: req,
+      method: 'GET',
+      scope: {
+        container: context.container,
+        userId: context.actorId,
+        tenantId: context.tenantId,
+        organizationId: context.organizationId,
+        tenantGlobal: true,
+      },
+      query: readSearchParamsRecord(req.url),
+    })
+    if (!interceptors.ok) return interceptors.response
+
+    const settings = await readTimeTrackingSettings(resolveConfigService(context), {
+      tenantId: context.tenantId,
+    })
+    return interceptors.session.respond(200, settings)
+  } catch (err) {
+    return errorResponse(err, 'staff.timesheets.settings.GET failed')
+  }
+}
+
+async function PUT(req: Request) {
+  try {
+    const context = await resolveSettingsContext(req)
+    // One lookup through the module's single RBAC authority, answering both
+    // questions this route asks: may the caller manage settings, and what grant
+    // list do the interceptors and the mutation-guard registry gate on. The
+    // decision is checked unconditionally and fails closed; the list is plumbing
+    // and is empty — never absent — when RBAC could not produce it.
+    const access = await resolveFeatureAccess(context.container, context.actorId || null, [MANAGE_FEATURE], {
+      tenantId: context.tenantId,
+      organizationId: context.organizationId,
+    })
+    if (!access.allowed) {
+      throw forbidden(context.translate('staff.errors.forbidden', 'Forbidden'))
+    }
+    const grantedFeatures = access.grantedFeatures
+
+    const interceptors = await runTimesheetInterceptors({
+      request: req,
+      method: 'PUT',
+      scope: {
+        container: context.container,
+        userId: context.actorId,
+        tenantId: context.tenantId,
+        organizationId: context.organizationId,
+        userFeatures: grantedFeatures,
+        tenantGlobal: true,
+      },
+      body: await readJsonSafe<Record<string, unknown>>(req, {}),
+    })
+    if (!interceptors.ok) return interceptors.response
+    const { session } = interceptors
+
+    const settingsSchema = buildTimeTrackingSettingsSchema()
+    const parsed = settingsSchema.parse(session.body)
+
+    const guardResult = await runRouteMutationGuards({
+      container: context.container,
+      req,
+      auth: {
+        userId: context.actorId,
+        tenantId: context.tenantId,
+        organizationId: context.organizationId,
+        userFeatures: grantedFeatures,
+      },
+      input: {
+        resourceKind: RESOURCE_KIND,
+        resourceId: RESOURCE_ID,
+        operation: 'update',
+        mutationPayload: parsed,
+      },
+    })
+    if (!guardResult.ok) return guardResult.response
+
+    const effective = guardResult.modifiedPayload
+      ? settingsSchema.parse({ ...parsed, ...guardResult.modifiedPayload })
+      : parsed
+
+    const settings: TimeTrackingSettings = await writeTimeTrackingSettings(
+      resolveConfigService(context),
+      { tenantId: context.tenantId },
+      effective,
+    )
+
+    await guardResult.runAfterSuccess()
+
+    void emitStaffEvent('staff.timesheets.time_tracking.settings_updated', {
+      tenantId: context.tenantId,
+      organizationId: context.organizationId,
+      settings,
+    }, { persistent: true }).catch((err) => {
+      logger.error('staff.timesheets emit time_tracking.settings_updated failed', { err })
+    })
+
+    return session.respond(200, settings)
+  } catch (err) {
+    return errorResponse(err, 'staff.timesheets.settings.PUT failed')
+  }
+}
+
+async function errorResponse(err: unknown, message: string) {
+  if (isCrudHttpError(err)) {
+    return NextResponse.json(err.body, { status: err.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(message, { err })
+  return NextResponse.json(
+    { error: translate('staff.errors.internal', 'Internal server error') },
+    { status: 500 },
+  )
+}
+
+const getDoc: OpenApiMethodDoc = {
+  summary: 'Read time tracking settings',
+  tags: ['Staff'],
+  get responses() {
+    return [
+      { status: 200, description: 'Tenant time tracking settings', schema: settingsResponseSchema() },
+      { status: 401, description: 'Unauthorized', schema: z.object({ error: z.string() }) },
+    ]
+  },
+}
+
+const putDoc: OpenApiMethodDoc = {
+  summary: 'Update time tracking settings',
+  tags: ['Staff'],
+  get requestBody() {
+    return { schema: buildTimeTrackingSettingsSchema() }
+  },
+  get responses() {
+    return [
+      { status: 200, description: 'Updated time tracking settings', schema: settingsResponseSchema() },
+    ]
+  },
+  errors: [
+    { status: 400, description: 'Invalid request body' },
+    { status: 401, description: 'Unauthorized' },
+    { status: 403, description: 'Missing staff.timesheets.settings.manage' },
+  ],
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Time tracking module settings',
+  methods: {
+    GET: getDoc,
+    PUT: putDoc,
+  },
+}
+
+export { GET, PUT }