@open-mercato/core 0.6.8-develop.6998.1.d2bc46c56c → 0.6.8-develop.7001.1.03608ab252

package/src/modules/warranty_claims/api/stats/route.ts

@@ -0,0 +1,306 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { sql, type SelectQueryBuilder } from 'kysely'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { resolveOrganizationScopeForRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { resolveEffectiveWarrantyClaimSettings } from '../../lib/settings'
+import { SLA_EXCLUDED_STATUSES } from '../../lib/deskFilters'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('warranty_claims')
+
+type NumericAggregateValue = string | number | bigint | null
+
+type WarrantyClaimsStatsTable = {
+  id: string
+  organization_id: string
+  tenant_id: string
+  status: string
+  deleted_at: Date | null
+  sla_due_at: Date | null
+  sla_paused_at: Date | null
+  assignee_user_id: string | null
+  submitted_at: Date | null
+  resolved_at: Date | null
+  total_approved_amount: string | number | null
+  total_recovered_amount: string | number | null
+  currency_code: string | null
+}
+
+type WarrantyClaimsStatsDb = {
+  warranty_claims: WarrantyClaimsStatsTable
+}
+
+type StatsRouteContext = {
+  tenantId: string
+  organizationIds: string[]
+  userId: string | null
+  em: EntityManager
+}
+
+const querySchema = z.object({}).strict()
+
+const OPEN_STATUSES = [
+  'submitted',
+  'in_review',
+  'info_requested',
+  'approved',
+  'awaiting_return',
+  'received',
+  'inspecting',
+]
+
+const RESOLUTION_STATUSES = ['resolved', 'closed']
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000
+
+const recoveredByCurrencySchema = z.object({
+  currencyCode: z.string().nullable(),
+  total: z.number(),
+})
+
+const resultSchema = z.object({
+  openByStatus: z.record(z.string(), z.number().int().nonnegative()),
+  overdue: z.number().int().nonnegative(),
+  slaAtRisk: z.number().int().nonnegative(),
+  assignedToMe: z.number().int().nonnegative(),
+  resolvedLast30d: z.number().int().nonnegative(),
+  avgResolutionDays: z.number().nullable(),
+  approvalRatePct: z.number().nullable(),
+  recoveredLast30dByCurrency: z.array(recoveredByCurrencySchema),
+  slaAtRiskThresholdPct: z.number().int().min(1).max(100),
+})
+
+const responseSchema = z.object({
+  ok: z.literal(true),
+  result: resultSchema,
+})
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['warranty_claims.claim.view'] },
+}
+
+function parseNumeric(value: NumericAggregateValue | undefined): number {
+  if (value === undefined || value === null) return 0
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+function applyOrganizationScope<O>(
+  query: SelectQueryBuilder<WarrantyClaimsStatsDb, 'warranty_claims', O>,
+  organizationIds: string[],
+): SelectQueryBuilder<WarrantyClaimsStatsDb, 'warranty_claims', O> {
+  if (organizationIds.length === 1) {
+    return query.where('organization_id', '=', organizationIds[0])
+  }
+  return query.where('organization_id', 'in', organizationIds)
+}
+
+function baseClaimsQuery<O>(
+  query: SelectQueryBuilder<WarrantyClaimsStatsDb, 'warranty_claims', O>,
+  context: StatsRouteContext,
+): SelectQueryBuilder<WarrantyClaimsStatsDb, 'warranty_claims', O> {
+  return applyOrganizationScope(
+    query
+      .where('tenant_id', '=', context.tenantId)
+      .where('deleted_at', 'is', null),
+    context.organizationIds,
+  )
+}
+
+async function resolveStatsContext(req: Request): Promise<StatsRouteContext> {
+  const container = await createRequestContainer()
+  const auth = await getAuthFromRequest(req)
+  const { translate } = await resolveTranslations()
+  if (!auth || !auth.tenantId) {
+    throw new CrudHttpError(401, { error: translate('warranty_claims.errors.unauthorized', 'Unauthorized') })
+  }
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+  const organizationIds = Array.isArray(scope?.filterIds) && scope.filterIds.length > 0
+    ? scope.filterIds
+    : auth.orgId
+      ? [auth.orgId]
+      : []
+  if (organizationIds.length === 0) {
+    throw new CrudHttpError(400, { error: translate('warranty_claims.errors.organization_required', 'Organization context is required') })
+  }
+  return {
+    tenantId: auth.tenantId,
+    organizationIds,
+    userId: typeof auth.sub === 'string' ? auth.sub : null,
+    em: (container.resolve('em') as EntityManager).fork(),
+  }
+}
+
+export async function GET(req: Request) {
+  try {
+    const url = new URL(req.url)
+    querySchema.parse(Object.fromEntries(url.searchParams))
+    const context = await resolveStatsContext(req)
+    const db = context.em.getKysely<WarrantyClaimsStatsDb>()
+    const now = new Date()
+    const thirtyDaysAgo = new Date(now.getTime() - THIRTY_DAYS_MS)
+    const effectiveSettings = await resolveEffectiveWarrantyClaimSettings(context.em, {
+      tenantId: context.tenantId,
+      organizationId: context.organizationIds[0] ?? null,
+    })
+
+    const openRows = await baseClaimsQuery(
+      db
+        .selectFrom('warranty_claims')
+        .select(['status', sql<NumericAggregateValue>`count(*)`.as('count')])
+        .where('status', 'in', OPEN_STATUSES)
+        .groupBy('status'),
+      context,
+    ).execute()
+    const openByStatus: Record<string, number> = Object.fromEntries(OPEN_STATUSES.map((status) => [status, 0]))
+    for (const row of openRows) {
+      openByStatus[row.status] = Math.trunc(parseNumeric(row.count))
+    }
+
+    const overdueRow = await baseClaimsQuery(
+      db
+        .selectFrom('warranty_claims')
+        .select(sql<NumericAggregateValue>`count(*)`.as('count'))
+        .where('sla_due_at', '<', now)
+        .where('sla_paused_at', 'is', null)
+        .where('status', 'not in', [...SLA_EXCLUDED_STATUSES]),
+      context,
+    ).executeTakeFirst()
+    const overdue = Math.trunc(parseNumeric(overdueRow?.count))
+
+    const atRiskRow = await baseClaimsQuery(
+      db
+        .selectFrom('warranty_claims')
+        .select(sql<NumericAggregateValue>`count(*)`.as('count'))
+        .where('sla_due_at', '>', now)
+        .where('sla_paused_at', 'is', null)
+        .where('status', 'not in', [...SLA_EXCLUDED_STATUSES])
+        .where('submitted_at', 'is not', null)
+        .where(sql<boolean>`sla_due_at > submitted_at`)
+        .where(sql<boolean>`extract(epoch from (${now}::timestamptz - submitted_at)) * 100 >= extract(epoch from (sla_due_at - submitted_at)) * ${effectiveSettings.slaAtRiskThresholdPct}`),
+      context,
+    ).executeTakeFirst()
+    const slaAtRisk = Math.trunc(parseNumeric(atRiskRow?.count))
+
+    let assignedToMe = 0
+    if (context.userId) {
+      const assignedRow = await baseClaimsQuery(
+        db
+          .selectFrom('warranty_claims')
+          .select(sql<NumericAggregateValue>`count(*)`.as('count'))
+          .where('status', 'in', OPEN_STATUSES)
+          .where('assignee_user_id', '=', context.userId),
+        context,
+      ).executeTakeFirst()
+      assignedToMe = Math.trunc(parseNumeric(assignedRow?.count))
+    }
+
+    const resolvedRow = await baseClaimsQuery(
+      db
+        .selectFrom('warranty_claims')
+        .select(sql<NumericAggregateValue>`count(*)`.as('count'))
+        .where('resolved_at', '>=', thirtyDaysAgo),
+      context,
+    ).executeTakeFirst()
+    const resolvedLast30d = Math.trunc(parseNumeric(resolvedRow?.count))
+
+    const avgRow = await baseClaimsQuery(
+      db
+        .selectFrom('warranty_claims')
+        .select(sql<NumericAggregateValue>`avg(extract(epoch from (resolved_at - submitted_at)) / 86400.0)`.as('avgDays'))
+        .where('resolved_at', '>=', thirtyDaysAgo)
+        .where('submitted_at', 'is not', null),
+      context,
+    ).executeTakeFirst()
+    const avgValue = avgRow?.avgDays
+    const avgResolutionDays = avgValue === undefined || avgValue === null
+      ? null
+      : Number(parseNumeric(avgValue).toFixed(1))
+
+    const approvalRow = await baseClaimsQuery(
+      db
+        .selectFrom('warranty_claims')
+        .select([
+          sql<NumericAggregateValue>`count(*)`.as('total'),
+          sql<NumericAggregateValue>`count(*) filter (where total_approved_amount > 0)`.as('approved'),
+        ])
+        .where('status', 'in', RESOLUTION_STATUSES)
+        .where('resolved_at', '>=', thirtyDaysAgo),
+      context,
+    ).executeTakeFirst()
+    const approvalTotal = parseNumeric(approvalRow?.total)
+    const approvalApproved = parseNumeric(approvalRow?.approved)
+    const approvalRatePct = approvalTotal > 0 ? Math.round((approvalApproved / approvalTotal) * 100) : null
+
+    const recoveredRows = await baseClaimsQuery(
+      db
+        .selectFrom('warranty_claims')
+        .select([
+          'currency_code as currencyCode',
+          sql<NumericAggregateValue>`coalesce(sum(total_recovered_amount), 0)`.as('total'),
+        ])
+        .where('status', 'in', RESOLUTION_STATUSES)
+        .where('resolved_at', '>=', thirtyDaysAgo)
+        .where('total_recovered_amount', '>', 0)
+        .groupBy('currency_code'),
+      context,
+    ).execute()
+    // `group by` returns rows in an unspecified order, so consumers that render a
+    // single bucket would otherwise show an arbitrary currency. Sort largest-first
+    // with the code as a tiebreak so the response is deterministic.
+    const recoveredLast30dByCurrency = recoveredRows
+      .map((row) => ({
+        currencyCode: row.currencyCode ?? null,
+        total: Number(parseNumeric(row.total).toFixed(2)),
+      }))
+      .sort((left, right) =>
+        right.total - left.total
+        || (left.currencyCode ?? '').localeCompare(right.currencyCode ?? ''))
+
+    return NextResponse.json({
+      ok: true,
+      result: {
+        openByStatus,
+        overdue,
+        slaAtRisk,
+        assignedToMe,
+        resolvedLast30d,
+        avgResolutionDays,
+        approvalRatePct,
+        recoveredLast30dByCurrency,
+        slaAtRiskThresholdPct: effectiveSettings.slaAtRiskThresholdPct,
+      },
+    })
+  } catch (err) {
+    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('warranty_claims.errors.invalidInput', 'Invalid input') }, { status: 400 })
+    }
+    logger.error('warranty_claims.stats.get failed', { err })
+    return NextResponse.json({ error: translate('warranty_claims.errors.load_failed', 'Failed to load warranty claim data') }, { status: 500 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Warranty Claims',
+  summary: 'Warranty claim statistics',
+  methods: {
+    GET: {
+      summary: 'Get warranty claim queue and resolution statistics',
+      query: querySchema,
+      responses: [
+        {
+          status: 200,
+          description: 'Warranty claim statistics',
+          schema: responseSchema,
+        },
+      ],
+    },
+  },
+}

package/src/modules/warranty_claims/api/submit/route.ts

@@ -0,0 +1,146 @@
+import { NextResponse } from 'next/server'
+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 type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { runRouteMutationGuards, type RouteMutationGuardResult } from '@open-mercato/shared/lib/crud/route-mutation-guard'
+import { withScopedPayload } from '@open-mercato/shared/lib/api/scoped'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { WARRANTY_CLAIM_RESOURCE_KIND } from '../../commands/shared'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('warranty_claims')
+
+// Scope is derived from the authenticated principal, never accepted from the body —
+// mirroring the sibling transition/assign routes. `withScopedPayload` prefers a
+// caller-supplied tenantId/organizationId over the actor's context, so admitting them
+// here would let the request choose its own scope.
+const submitSchema = z
+  .object({
+    id: z.string().uuid(),
+  })
+  .strict()
+
+type SubmitInput = z.infer<typeof submitSchema>
+
+type ActionRouteContext = {
+  ctx: CommandRuntimeContext
+  tenantId: string
+  organizationId: string
+  translate: (key: string, fallback?: string) => string
+}
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['warranty_claims.claim.manage'] },
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+async function resolveActionContext(req: Request): Promise<ActionRouteContext> {
+  const container = await createRequestContainer()
+  const auth = await getAuthFromRequest(req)
+  const { translate } = await resolveTranslations()
+  if (!auth || !auth.tenantId) {
+    throw new CrudHttpError(401, { error: translate('warranty_claims.errors.unauthorized', 'Unauthorized') })
+  }
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+  const organizationId = scope?.selectedId ?? auth.orgId ?? null
+  if (!organizationId) {
+    throw new CrudHttpError(400, { error: translate('warranty_claims.errors.organization_required', 'Organization context is required') })
+  }
+  return {
+    ctx: {
+      container,
+      auth,
+      organizationScope: scope,
+      selectedOrganizationId: organizationId,
+      organizationIds: scope?.filterIds ?? (auth.orgId ? [auth.orgId] : null),
+      request: req,
+    },
+    tenantId: auth.tenantId,
+    organizationId,
+    translate,
+  }
+}
+
+async function runGuard(
+  req: Request,
+  context: ActionRouteContext,
+  input: SubmitInput,
+): Promise<RouteMutationGuardResult> {
+  const userId = context.ctx.auth?.sub
+  if (!userId) {
+    throw new CrudHttpError(401, { error: context.translate('warranty_claims.errors.unauthorized', 'Unauthorized') })
+  }
+  return runRouteMutationGuards({
+    container: context.ctx.container,
+    req,
+    auth: {
+      userId,
+      tenantId: context.tenantId,
+      organizationId: context.organizationId,
+    },
+    input: {
+      resourceKind: WARRANTY_CLAIM_RESOURCE_KIND,
+      resourceId: input.id,
+      operation: 'custom',
+      mutationPayload: { ...input },
+    },
+  })
+}
+
+export async function POST(req: Request) {
+  try {
+    const context = await resolveActionContext(req)
+    const payload = toRecord(await readJsonSafe(req, {}))
+    const scopedPayload = toRecord(withScopedPayload(payload, context.ctx, context.translate))
+    const input = submitSchema.parse({ id: scopedPayload.id })
+    const guarded = await runGuard(req, context, input)
+    if (!guarded.ok) {
+      return guarded.response
+    }
+    const commandInput = guarded.modifiedPayload ? submitSchema.parse(guarded.modifiedPayload) : input
+
+    const commandBus = context.ctx.container.resolve('commandBus') as CommandBus
+    const { result } = await commandBus.execute<SubmitInput, { claimId: string }>(
+      'warranty_claims.claim.submit',
+      { input: commandInput, ctx: context.ctx },
+    )
+
+    await guarded.runAfterSuccess()
+
+    return NextResponse.json({ ok: true, claimId: result?.claimId ?? commandInput.id })
+  } catch (err) {
+    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('warranty_claims.errors.invalidInput', 'Invalid input') }, { status: 400 })
+    }
+    logger.error('warranty_claims.submit.post failed', { err })
+    return NextResponse.json({ error: translate('warranty_claims.errors.save_failed', 'Failed to save warranty claim') }, { status: 400 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Warranty Claims',
+  summary: 'Submit warranty claim',
+  methods: {
+    POST: {
+      summary: 'Submit a draft claim',
+      requestBody: { contentType: 'application/json', schema: submitSchema },
+      responses: [
+        {
+          status: 200,
+          description: 'Claim submitted',
+          schema: z.object({ ok: z.boolean(), claimId: z.string().uuid() }),
+        },
+      ],
+    },
+  },
+}

package/src/modules/warranty_claims/api/transition/route.ts

@@ -0,0 +1,144 @@
+import { NextResponse } from 'next/server'
+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 type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { CrudHttpError, isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { runRouteMutationGuards, type RouteMutationGuardResult } from '@open-mercato/shared/lib/crud/route-mutation-guard'
+import { withScopedPayload } from '@open-mercato/shared/lib/api/scoped'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { transitionClaimInputSchema, type TransitionClaimInput } from '../../data/validators'
+import { WARRANTY_CLAIM_RESOURCE_KIND } from '../../commands/shared'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('warranty_claims')
+
+type ActionRouteContext = {
+  ctx: CommandRuntimeContext
+  tenantId: string
+  organizationId: string
+  translate: (key: string, fallback?: string) => string
+}
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['warranty_claims.claim.manage'] },
+}
+
+function toRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+async function resolveActionContext(req: Request): Promise<ActionRouteContext> {
+  const container = await createRequestContainer()
+  const auth = await getAuthFromRequest(req)
+  const { translate } = await resolveTranslations()
+  if (!auth || !auth.tenantId) {
+    throw new CrudHttpError(401, { error: translate('warranty_claims.errors.unauthorized', 'Unauthorized') })
+  }
+  const scope = await resolveOrganizationScopeForRequest({ container, auth, request: req })
+  const organizationId = scope?.selectedId ?? auth.orgId ?? null
+  if (!organizationId) {
+    throw new CrudHttpError(400, { error: translate('warranty_claims.errors.organization_required', 'Organization context is required') })
+  }
+  return {
+    ctx: {
+      container,
+      auth,
+      organizationScope: scope,
+      selectedOrganizationId: organizationId,
+      organizationIds: scope?.filterIds ?? (auth.orgId ? [auth.orgId] : null),
+      request: req,
+    },
+    tenantId: auth.tenantId,
+    organizationId,
+    translate,
+  }
+}
+
+function toTransitionInput(scopedPayload: Record<string, unknown>): TransitionClaimInput {
+  return transitionClaimInputSchema.parse({
+    id: scopedPayload.id,
+    toStatus: scopedPayload.toStatus,
+    rejectionReasonCode: scopedPayload.rejectionReasonCode,
+    resolutionSummary: scopedPayload.resolutionSummary,
+  })
+}
+
+async function runGuard(
+  req: Request,
+  context: ActionRouteContext,
+  input: TransitionClaimInput,
+): Promise<RouteMutationGuardResult> {
+  const userId = context.ctx.auth?.sub
+  if (!userId) {
+    throw new CrudHttpError(401, { error: context.translate('warranty_claims.errors.unauthorized', 'Unauthorized') })
+  }
+  return runRouteMutationGuards({
+    container: context.ctx.container,
+    req,
+    auth: {
+      userId,
+      tenantId: context.tenantId,
+      organizationId: context.organizationId,
+    },
+    input: {
+      resourceKind: WARRANTY_CLAIM_RESOURCE_KIND,
+      resourceId: input.id,
+      operation: 'custom',
+      mutationPayload: { ...input },
+    },
+  })
+}
+
+export async function POST(req: Request) {
+  try {
+    const context = await resolveActionContext(req)
+    const payload = toRecord(await readJsonSafe(req, {}))
+    const scopedPayload = withScopedPayload(payload, context.ctx, context.translate)
+    const input = toTransitionInput(scopedPayload)
+    const guarded = await runGuard(req, context, input)
+    if (!guarded.ok) {
+      return guarded.response
+    }
+    const commandInput = guarded.modifiedPayload ? toTransitionInput(guarded.modifiedPayload) : input
+
+    const commandBus = context.ctx.container.resolve('commandBus') as CommandBus
+    const { result } = await commandBus.execute<TransitionClaimInput, { claimId: string }>(
+      'warranty_claims.claim.transition',
+      { input: commandInput, ctx: context.ctx },
+    )
+
+    await guarded.runAfterSuccess()
+
+    return NextResponse.json({ ok: true, claimId: result?.claimId ?? commandInput.id })
+  } catch (err) {
+    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('warranty_claims.errors.invalidInput', 'Invalid input') }, { status: 400 })
+    }
+    logger.error('warranty_claims.transition.post failed', { err })
+    return NextResponse.json({ error: translate('warranty_claims.errors.save_failed', 'Failed to save warranty claim') }, { status: 400 })
+  }
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Warranty Claims',
+  summary: 'Transition warranty claim',
+  methods: {
+    POST: {
+      summary: 'Move a claim through the lifecycle',
+      requestBody: { contentType: 'application/json', schema: transitionClaimInputSchema },
+      responses: [
+        {
+          status: 200,
+          description: 'Claim transitioned',
+          schema: z.object({ ok: z.boolean(), claimId: z.string().uuid() }),
+        },
+      ],
+    },
+  },
+}