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

package/src/modules/staff/api/timesheets/time-projects/[id]/change-currency/route.ts

@@ -0,0 +1,246 @@
+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 { 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 { 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 { emitStaffEvent } from '../../../../../events'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { staffTimeProjectChangeCurrencySchema } 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 {
+  staffTimeProjectChangeCurrencyCommandId,
+  type StaffTimeProjectChangeCurrencyCommandInput,
+  type StaffTimeProjectChangeCurrencyResult,
+} from '../../../../../commands/timesheets-projects'
+
+const logger = createLogger('staff').child({ component: 'api/timesheets/time-projects/change-currency' })
+
+const MANAGE_FEATURE = 'staff.timesheets.projects.manage'
+const RESOURCE_KIND = STAFF_TIME_TRACKING_RESOURCE_KINDS.timeProject
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: [MANAGE_FEATURE] },
+}
+
+function extractProjectIdFromUrl(request?: Request): string | null {
+  if (!request?.url) return null
+  try {
+    const url = new URL(request.url)
+    const match = url.pathname.match(/\/time-projects\/([^/]+)\/change-currency/)
+    return match?.[1] ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * D-3: relabels a project's currency without converting a single historical
+ * amount. The `acknowledged: true` literal in the body is deliberate friction —
+ * the client must have shown the non-conversion warning — and the request is
+ * refused with `409 project_has_locked_entries` while any of the project's
+ * entries is frozen inside a closed report.
+ */
+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 timeProjectId = extractProjectIdFromUrl(req)
+    if (!timeProjectId) {
+      throw new CrudHttpError(400, {
+        error: translate('staff.timesheets.errors.projectRequired', 'Time project id is required.'),
+      })
+    }
+
+    const actorId = auth.sub ?? ''
+    // One lookup through the module's single RBAC authority, answering both
+    // questions this route asks: may the caller manage projects, 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(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 },
+      body: await readJsonSafe<Record<string, unknown>>(req, {}),
+    })
+    if (!interceptors.ok) return interceptors.response
+    const { session } = interceptors
+
+    const parsed = staffTimeProjectChangeCurrencySchema.parse(session.body)
+
+    const guardResult = await runRouteMutationGuards({
+      container,
+      req,
+      auth: {
+        userId: actorId,
+        tenantId,
+        organizationId,
+        userFeatures: grantedFeatures,
+      },
+      input: {
+        resourceKind: RESOURCE_KIND,
+        resourceId: timeProjectId,
+        operation: 'update',
+        mutationPayload: parsed,
+      },
+    })
+    if (!guardResult.ok) return guardResult.response
+
+    const effective = guardResult.modifiedPayload
+      ? staffTimeProjectChangeCurrencySchema.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, logEntry } = await commandBus.execute<
+      StaffTimeProjectChangeCurrencyCommandInput,
+      StaffTimeProjectChangeCurrencyResult
+    >(staffTimeProjectChangeCurrencyCommandId, {
+      input: { ...effective, id: timeProjectId },
+      ctx,
+    })
+
+    await guardResult.runAfterSuccess()
+
+    void emitStaffEvent('staff.timesheets.time_project.currency_changed', {
+      id: result?.timeProjectId ?? timeProjectId,
+      tenantId,
+      organizationId,
+      currencyCode: result?.currencyCode ?? effective.currencyCode,
+      previousCurrencyCode: result?.previousCurrencyCode ?? null,
+      converted: false,
+    }, { persistent: true }).catch((err) => {
+      logger.error('staff.timesheets emit time_project.currency_changed failed', { err })
+    })
+
+    const response = await session.respond(200, {
+      id: result?.timeProjectId ?? timeProjectId,
+      currencyCode: result?.currencyCode ?? effective.currencyCode,
+      previousCurrencyCode: result?.previousCurrencyCode ?? null,
+      converted: false,
+    })
+    if (logEntry?.undoToken && logEntry?.id && logEntry?.commandId) {
+      response.headers.set(
+        'x-om-operation',
+        serializeOperationMetadata({
+          id: logEntry.id,
+          undoToken: logEntry.undoToken,
+          commandId: logEntry.commandId,
+          actionLabel: logEntry.actionLabel ?? null,
+          resourceKind: logEntry.resourceKind ?? RESOURCE_KIND,
+          resourceId: logEntry.resourceId ?? timeProjectId,
+          executedAt: logEntry.createdAt instanceof Date ? logEntry.createdAt.toISOString() : undefined,
+        }),
+      )
+    }
+    return response
+  } catch (err) {
+    if (isCrudHttpError(err)) {
+      return NextResponse.json(err.body, { status: err.status })
+    }
+    const interceptorRejection = getCommandInterceptorHttpRejection(err)
+    if (interceptorRejection) {
+      return NextResponse.json(interceptorRejection.body, { status: interceptorRejection.status })
+    }
+    const { translate } = await resolveTranslations()
+    if (err instanceof z.ZodError) {
+      return NextResponse.json(
+        { error: translate('staff.errors.invalid_request', 'Invalid request'), details: err.issues },
+        { status: 400 },
+      )
+    }
+    logger.error('staff.timesheets.time-projects.change-currency failed', { err })
+    return NextResponse.json(
+      { error: translate('staff.errors.internal', 'Internal server error') },
+      { status: 500 },
+    )
+  }
+}
+
+const blockingReportSchema = z.object({
+  id: z.string().uuid(),
+  reference: z.string().nullable(),
+  title: z.string().nullable(),
+})
+
+const changeCurrencyResponseSchema = z.object({
+  id: z.string().uuid(),
+  currencyCode: z.string(),
+  previousCurrencyCode: z.string().nullable(),
+  converted: z.literal(false),
+})
+
+const lockedConflictSchema = z.object({
+  code: z.literal('project_has_locked_entries'),
+  error: z.string(),
+  lockedEntryCount: z.number().int(),
+  lockedReports: z.array(blockingReportSchema),
+})
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Staff',
+  summary: 'Change a time project currency',
+  methods: {
+    POST: {
+      summary: 'Change a time project currency',
+      description:
+        'Relabels the project currency without converting any historical amount. Requires an explicit `acknowledged: true` and is refused while any of the project entries is locked into a closed report.',
+      requestBody: {
+        contentType: 'application/json',
+        schema: staffTimeProjectChangeCurrencySchema,
+      },
+      responses: [
+        { status: 200, description: 'Currency relabelled', schema: changeCurrencyResponseSchema },
+      ],
+      errors: [
+        { status: 400, description: 'Invalid body, or the change was not acknowledged' },
+        { status: 401, description: 'Unauthorized' },
+        { status: 403, description: 'Missing staff.timesheets.projects.manage' },
+        { status: 404, description: 'Time project not found' },
+        {
+          status: 409,
+          description: 'Project has entries locked into a closed report',
+          schema: lockedConflictSchema,
+        },
+      ],
+    },
+  },
+}

package/src/modules/staff/api/timesheets/time-projects/[id]/employees/route.ts

@@ -1,10 +1,13 @@
 import { z } from 'zod'
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { staffTimeProjectMemberCrudEvents } from '../../../../../lib/crud'
+import { emitStaffEvent } from '../../../../../events'
+import { createLogger } from '@open-mercato/shared/lib/logger'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { StaffTimeProjectMember } from '../../../../../data/entities'
-import { staffTimeProjectMemberAssignSchema } from '../../../../../data/validators'
+import { staffTimeProjectMemberAssignSchema, staffTimeProjectMemberUpdateSchema } from '../../../../../data/validators'
 import { createStaffCrudOpenApi, createPagedListResponseSchema, defaultOkResponseSchema } from '../../../../openapi'
 
 function extractProjectIdFromUrl(request?: Request): string | null {
@@ -36,6 +39,7 @@ const F = {
 const routeMetadata = {
   GET: { requireAuth: true, requireFeatures: ['staff.timesheets.projects.view'] },
   POST: { requireAuth: true, requireFeatures: ['staff.timesheets.projects.manage'] },
+  PUT: { requireAuth: true, requireFeatures: ['staff.timesheets.projects.manage'] },
   DELETE: { requireAuth: true, requireFeatures: ['staff.timesheets.projects.manage'] },
 }
 
@@ -54,6 +58,14 @@ const listSchema = z
   })
   .passthrough()
 
+const logger = createLogger('staff').child({ component: 'api/timesheets/time-projects/employees' })
+
+function readMemberId(result: unknown): string | null {
+  if (!result || typeof result !== 'object') return null
+  const value = (result as { timeProjectMemberId?: unknown }).timeProjectMemberId
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
+
 const crud = makeCrudRoute({
   metadata: routeMetadata,
   orm: {
@@ -63,6 +75,7 @@ const crud = makeCrudRoute({
     tenantField: 'tenantId',
     softDeleteField: 'deletedAt',
   },
+  events: staffTimeProjectMemberCrudEvents,
   indexer: { entityType: 'staff:staff_time_project_member' },
   list: {
     schema: listSchema,
@@ -107,9 +120,50 @@ const crud = makeCrudRoute({
         const body = { ...raw, timeProjectId: raw?.timeProjectId ?? projectId }
         return parseScopedCommandInput(staffTimeProjectMemberAssignSchema, body, ctx, translate)
       },
-      response: ({ result }) => ({ id: result?.timeProjectMemberId ?? null }),
+      // The assignment IS the grant: `timeTrackingAccessResolver` reads exactly this
+      // table, so a module wiring an approval workflow onto `access-requests` learns
+      // the outcome here rather than by polling the membership list.
+      response: ({ result, ctx }) => {
+        const timeProjectMemberId = readMemberId(result)
+        if (timeProjectMemberId) {
+          void emitStaffEvent('staff.timesheets.time_project_access.granted', {
+            id: timeProjectMemberId,
+            tenantId: ctx.auth?.tenantId ?? null,
+            organizationId: ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
+          }, { persistent: true }).catch((err) => {
+            logger.error('staff.timesheets emit time_project_access.granted failed', { err })
+          })
+        }
+        return { id: timeProjectMemberId }
+      },
       status: 201,
     },
+    // Re-dating an assignment (D-12) is an update of the existing row, not a
+    // replacement pair, so the audit trail reads as a change to
+    // `assignedEndDate`. `timeProjectId` comes from the URL, never from the
+    // body: the command uses it to refuse a membership id belonging to another
+    // project. Guard wiring, tenant/org scoping and the optimistic-lock header
+    // come from `makeCrudRoute`'s command path — this route MUST NOT hand-roll
+    // them (see `runRouteMutationGuards` for the non-factory equivalent).
+    update: {
+      commandId: 'staff.timesheets.time_project_members.update',
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations()
+        const id =
+          raw?.id ??
+          (ctx.request ? new URL(ctx.request.url).searchParams.get('id') : null)
+        if (!id) {
+          throw new CrudHttpError(400, {
+            error: translate('staff.timesheets.errors.memberRequired', 'Time project member id is required.'),
+          })
+        }
+        const parsed = staffTimeProjectMemberUpdateSchema.parse({ ...raw, id })
+        const projectId = extractProjectIdFromUrl(ctx?.request)
+        return projectId ? { ...parsed, timeProjectId: projectId } : parsed
+      },
+      response: ({ result }) => ({ id: result?.timeProjectMemberId ?? null }),
+    },
     delete: {
       commandId: 'staff.timesheets.time_project_members.unassign',
       schema: rawBodySchema,
@@ -134,6 +188,7 @@ const crud = makeCrudRoute({
 
 export const GET = crud.GET
 export const POST = crud.POST
+export const PUT = crud.PUT
 export const DELETE = crud.DELETE
 
 const projectMemberListItemSchema = z.object({
@@ -159,6 +214,11 @@ export const openApi = createStaffCrudOpenApi({
     schema: staffTimeProjectMemberAssignSchema,
     description: 'Assigns an employee to a time project.',
   },
+  update: {
+    schema: staffTimeProjectMemberUpdateSchema,
+    responseSchema: z.object({ id: z.string().uuid().nullable() }),
+    description: 'Updates an existing assignment (role, status, assignment end date) without unassigning the employee.',
+  },
   del: {
     schema: z.object({ id: z.string().uuid() }),
     responseSchema: defaultOkResponseSchema,