@open-mercato/core 0.6.2-develop.3330.1.8ad2b3b84c → 0.6.2-develop.3363.1.e23f7084bd

package/src/modules/integrations/backend/integrations/[id]/page.tsx

@@ -132,6 +132,27 @@ type HealthCheckResponse = {
   latencyMs: number | null
 }
 
+type DataSyncRunDetail = {
+  id: string
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+  progressJobId?: string | null
+  createdCount?: number
+  updatedCount?: number
+  skippedCount?: number
+  failedCount?: number
+  progressJob?: {
+    progressPercent?: number | null
+    processedCount?: number | null
+    totalCount?: number | null
+  } | null
+}
+
+const LOG_LEVEL_STYLES: Record<string, string> = {
+  info: 'bg-blue-100 text-blue-800',
+  warn: 'bg-yellow-100 text-yellow-800',
+  error: 'bg-red-100 text-red-800',
+}
+
 const HEALTH_STATUS_STYLES: Record<string, string> = {
   healthy: 'bg-green-100 text-green-800',
   degraded: 'bg-yellow-100 text-yellow-800',
@@ -146,6 +167,74 @@ const HEALTH_STATUS_ICONS: Record<string, React.ElementType> = {
   unconfigured: AlertTriangle,
 }
 
+function formatRunStatusLabel(status: DataSyncRunDetail['status'], t: ReturnType<typeof useT>): string {
+  switch (status) {
+    case 'pending':
+      return t('integrations.detail.runActivity.status.pending', 'Pending')
+    case 'running':
+      return t('integrations.detail.runActivity.status.running', 'Running')
+    case 'completed':
+      return t('integrations.detail.runActivity.status.completed', 'Completed')
+    case 'failed':
+      return t('integrations.detail.runActivity.status.failed', 'Failed')
+    case 'cancelled':
+      return t('integrations.detail.runActivity.status.cancelled', 'Cancelled')
+    default:
+      return status
+  }
+}
+
+function RunActivityStrip({
+  run,
+  refreshedAt,
+  isRefreshing,
+  onRefresh,
+  t,
+}: {
+  run: DataSyncRunDetail | null
+  refreshedAt: string | null
+  isRefreshing: boolean
+  onRefresh: () => void
+  t: ReturnType<typeof useT>
+}) {
+  if (!run) return null
+
+  const progress = typeof run.progressJob?.progressPercent === 'number' ? run.progressJob.progressPercent : 0
+  const processed = typeof run.progressJob?.processedCount === 'number' ? run.progressJob.processedCount : 0
+  const total = typeof run.progressJob?.totalCount === 'number' ? run.progressJob.totalCount : null
+  const statusClass = run.status === 'completed'
+    ? 'border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300'
+    : run.status === 'failed'
+      ? 'border-red-500/30 bg-red-500/10 text-red-700 dark:text-red-300'
+      : run.status === 'cancelled'
+        ? 'border-zinc-500/30 bg-zinc-500/10 text-zinc-700 dark:text-zinc-300'
+        : 'border-blue-500/30 bg-blue-500/10 text-blue-700 dark:text-blue-300'
+
+  return (
+    <div className="flex flex-wrap items-center gap-3 rounded-lg border bg-muted/20 px-4 py-3 text-sm">
+      <Badge variant="outline" className={cn('gap-1.5', statusClass)}>
+        <RefreshCw className={cn('h-3.5 w-3.5', run.status === 'running' ? 'animate-spin' : '')} />
+        {formatRunStatusLabel(run.status, t)}
+      </Badge>
+      <span className="text-muted-foreground">
+        {t('integrations.detail.runActivity.processed', 'Processed')}: <span className="font-medium text-foreground">{processed}{total !== null ? ` / ${total}` : ''}</span>
+      </span>
+      <span className="text-muted-foreground">
+        {t('integrations.detail.runActivity.progress', 'Progress')}: <span className="font-medium text-foreground">{progress}%</span>
+      </span>
+      {refreshedAt ? (
+        <span className="text-muted-foreground">
+          {t('integrations.detail.runActivity.lastRefreshed', 'Last refreshed')}: {new Date(refreshedAt).toLocaleTimeString()}
+        </span>
+      ) : null}
+      <Button type="button" variant="outline" size="sm" className="ml-auto" onClick={onRefresh} disabled={isRefreshing}>
+        {isRefreshing ? <Spinner className="mr-2 h-4 w-4" /> : <RefreshCw className="mr-2 h-4 w-4" />}
+        {t('integrations.detail.runActivity.refresh', 'Refresh')}
+      </Button>
+    </div>
+  )
+}
+
 function DetailLogSparkline({ counts, className }: { counts: number[]; className?: string }) {
   const max = Math.max(1, ...counts)
   const w = 120
@@ -337,6 +426,9 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
   const [isCheckingHealth, setIsCheckingHealth] = React.useState(false)
   const [isTogglingState, setIsTogglingState] = React.useState(false)
   const [latestHealthResult, setLatestHealthResult] = React.useState<HealthCheckResponse | null>(null)
+  const [activeRunDetail, setActiveRunDetail] = React.useState<DataSyncRunDetail | null>(null)
+  const [activeRunRefreshedAt, setActiveRunRefreshedAt] = React.useState<string | null>(null)
+  const [isRefreshingRunActivity, setIsRefreshingRunActivity] = React.useState(false)
   const [activeTab, setActiveTab] = React.useState<IntegrationDetailTab>('credentials')
 
   const credentialsFormId = React.useId()
@@ -427,6 +519,35 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
   const refreshLogs = React.useCallback(async () => {
     await loadLogs()
   }, [loadLogs])
+  const refreshHealthSnapshot = React.useCallback(async () => {
+    await loadDetail()
+  }, [loadDetail])
+  const runIdFromUrl = searchParams?.get('runId') ?? null
+  const refreshRunActivity = React.useCallback(async (options?: { showLoading?: boolean }) => {
+    if (!runIdFromUrl) {
+      setActiveRunDetail(null)
+      setActiveRunRefreshedAt(null)
+      return null
+    }
+    if (options?.showLoading) setIsRefreshingRunActivity(true)
+    try {
+      const call = await apiCall<DataSyncRunDetail>(
+        `/api/data_sync/runs/${encodeURIComponent(runIdFromUrl)}`,
+        undefined,
+        { fallback: null },
+      )
+      await loadLogs()
+      await loadDetail()
+      if (call.ok && call.result) {
+        setActiveRunDetail(call.result)
+        setActiveRunRefreshedAt(new Date().toISOString())
+        return call.result
+      }
+      return null
+    } finally {
+      if (options?.showLoading) setIsRefreshingRunActivity(false)
+    }
+  }, [loadDetail, loadLogs, runIdFromUrl])
   const injectionContext = React.useMemo(
     () => ({
       formId: mutationContextId,
@@ -443,6 +564,7 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
       setActiveTab,
       refreshDetail,
       refreshLogs,
+      refreshHealthSnapshot,
       retryLastMutation,
     }),
     [
@@ -454,6 +576,7 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
       latestHealthResult,
       mutationContextId,
       refreshDetail,
+      refreshHealthSnapshot,
       refreshLogs,
       retryLastMutation,
     ],
@@ -732,10 +855,21 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
     })
   ) as z.ZodType<Record<string, unknown>>, [editableCredentialFields, t])
   const latestHealthLog = React.useMemo(() => logs.find(isHealthLog) ?? null, [logs])
+  const latestOperationalLog = React.useMemo(
+    () => logs.find((log) => (
+      typeof log.payload?.operationalStatus === 'string'
+      || typeof log.payload?.summary === 'string'
+    )) ?? null,
+    [logs],
+  )
   const healthMessage =
     latestHealthResult?.message ??
-    (typeof latestHealthLog?.payload?.message === 'string' ? latestHealthLog.payload.message : null)
-  const healthDetailsSource = latestHealthResult?.details ?? extractHealthDetails(latestHealthLog?.payload)
+    (typeof latestHealthLog?.payload?.message === 'string'
+      ? latestHealthLog.payload.message
+      : typeof latestOperationalLog?.payload?.summary === 'string'
+        ? latestOperationalLog.payload.summary
+        : null)
+  const healthDetailsSource = latestHealthResult?.details ?? extractHealthDetails(latestHealthLog?.payload ?? latestOperationalLog?.payload)
   const healthDetails = latestHealthLog?.code
     ? { ...healthDetailsSource, code: latestHealthLog.code }
     : healthDetailsSource
@@ -811,8 +945,43 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
     setActiveTab(nextTab)
     if (!currentIntegrationId) return
     const basePath = `/backend/integrations/${encodeURIComponent(currentIntegrationId)}`
-    router.replace(nextTab === 'credentials' ? basePath : `${basePath}?tab=${encodeURIComponent(nextTab)}`)
-  }, [resolveCurrentIntegrationId, router, visibleTabIds])
+    const params = new URLSearchParams(searchParams?.toString() ?? '')
+    if (nextTab === 'credentials') params.delete('tab')
+    else params.set('tab', nextTab)
+    const query = params.toString()
+    router.replace(query ? `${basePath}?${query}` : basePath)
+  }, [resolveCurrentIntegrationId, router, searchParams, visibleTabIds])
+
+  React.useEffect(() => {
+    if (!runIdFromUrl) {
+      setActiveRunDetail(null)
+      setActiveRunRefreshedAt(null)
+      return
+    }
+    if (activeTab !== 'logs' && activeTab !== 'health') return
+
+    let cancelled = false
+    let timeoutId: ReturnType<typeof setTimeout> | null = null
+
+    const poll = async () => {
+      const detail = await refreshRunActivity()
+      if (cancelled) return
+
+      const status = detail?.status ?? null
+      if (status === 'pending' || status === 'running') {
+        timeoutId = setTimeout(() => {
+          void poll()
+        }, 4_000)
+      }
+    }
+
+    void poll()
+
+    return () => {
+      cancelled = true
+      if (timeoutId) clearTimeout(timeoutId)
+    }
+  }, [activeTab, refreshRunActivity, runIdFromUrl])
 
   if (isLoading) return <Page><PageBody><LoadingMessage label={t('integrations.detail.title')} /></PageBody></Page>
   if (error || !detail || !resolvedIntegration || !resolvedState) {
@@ -1110,20 +1279,39 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
 
           {showHealthTab ? (
             <TabsContent value="health" className="mt-0 space-y-4">
+              <RunActivityStrip
+                run={activeRunDetail}
+                refreshedAt={activeRunRefreshedAt}
+                isRefreshing={isRefreshingRunActivity}
+                onRefresh={() => void refreshRunActivity({ showLoading: true })}
+                t={t}
+              />
               <Card className="gap-4 py-4">
                 <CardHeader className="px-5">
                   <div className="flex items-center justify-between">
                     <CardTitle>{t('integrations.detail.health.title')}</CardTitle>
-                    <Button
-                      type="button"
-                      variant="outline"
-                      size="sm"
-                      onClick={() => void handleHealthCheck()}
-                      disabled={isCheckingHealth}
-                    >
-                      {isCheckingHealth ? <Spinner className="mr-2 h-4 w-4" /> : <Zap className="mr-2 h-4 w-4" />}
-                      {isCheckingHealth ? t('integrations.detail.health.checking') : t('integrations.detail.health.check')}
-                    </Button>
+                    <div className="flex flex-wrap items-center gap-2">
+                      <Button
+                        type="button"
+                        variant="outline"
+                        size="sm"
+                        onClick={() => void refreshRunActivity({ showLoading: true })}
+                        disabled={isRefreshingRunActivity || !runIdFromUrl}
+                      >
+                        {isRefreshingRunActivity ? <Spinner className="mr-2 h-4 w-4" /> : <RefreshCw className="mr-2 h-4 w-4" />}
+                        {t('integrations.detail.runActivity.refresh', 'Refresh')}
+                      </Button>
+                      <Button
+                        type="button"
+                        variant="outline"
+                        size="sm"
+                        onClick={() => void handleHealthCheck()}
+                        disabled={isCheckingHealth}
+                      >
+                        {isCheckingHealth ? <Spinner className="mr-2 h-4 w-4" /> : <Zap className="mr-2 h-4 w-4" />}
+                        {isCheckingHealth ? t('integrations.detail.health.checking') : t('integrations.detail.health.check')}
+                      </Button>
+                    </div>
                   </div>
                 </CardHeader>
                 <CardContent className="space-y-3 px-5">
@@ -1183,7 +1371,14 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
 
           {showLogsTab ? (
             <TabsContent value="logs" className="mt-0 space-y-4">
-            <div className="flex items-center gap-3">
+            <RunActivityStrip
+              run={activeRunDetail}
+              refreshedAt={activeRunRefreshedAt}
+              isRefreshing={isRefreshingRunActivity}
+              onRefresh={() => void refreshRunActivity({ showLoading: true })}
+              t={t}
+            />
+            <div className="flex flex-wrap items-center gap-3">
               <div className="inline-flex">
                 <Select
                   value={logLevel || undefined}
@@ -1199,6 +1394,16 @@ export default function IntegrationDetailPage({ params }: IntegrationDetailPageP
                   </SelectContent>
                 </Select>
               </div>
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={() => void refreshRunActivity({ showLoading: true })}
+                disabled={isRefreshingRunActivity || !runIdFromUrl}
+              >
+                {isRefreshingRunActivity ? <Spinner className="mr-2 h-4 w-4" /> : <RefreshCw className="mr-2 h-4 w-4" />}
+                {t('integrations.detail.runActivity.refresh', 'Refresh')}
+              </Button>
             </div>
             {isLoadingLogs ? (
               <div className="flex justify-center py-8"><Spinner /></div>

package/src/modules/integrations/i18n/de.json

@@ -126,6 +126,15 @@
   "integrations.detail.logs.level.info": "Info",
   "integrations.detail.logs.level.warn": "Warnung",
   "integrations.detail.logs.title": "Betriebsprotokolle",
+  "integrations.detail.runActivity.lastRefreshed": "Zuletzt aktualisiert",
+  "integrations.detail.runActivity.processed": "Verarbeitet",
+  "integrations.detail.runActivity.progress": "Fortschritt",
+  "integrations.detail.runActivity.refresh": "Aktualisieren",
+  "integrations.detail.runActivity.status.cancelled": "Abgebrochen",
+  "integrations.detail.runActivity.status.completed": "Abgeschlossen",
+  "integrations.detail.runActivity.status.failed": "Fehlgeschlagen",
+  "integrations.detail.runActivity.status.pending": "Ausstehend",
+  "integrations.detail.runActivity.status.running": "Läuft",
   "integrations.detail.state.disabled": "Disabled",
   "integrations.detail.state.enabled": "Enabled",
   "integrations.detail.state.label": "State",

package/src/modules/integrations/i18n/en.json

@@ -126,6 +126,15 @@
   "integrations.detail.logs.level.info": "Info",
   "integrations.detail.logs.level.warn": "Warning",
   "integrations.detail.logs.title": "Operation Logs",
+  "integrations.detail.runActivity.lastRefreshed": "Last refreshed",
+  "integrations.detail.runActivity.processed": "Processed",
+  "integrations.detail.runActivity.progress": "Progress",
+  "integrations.detail.runActivity.refresh": "Refresh",
+  "integrations.detail.runActivity.status.cancelled": "Cancelled",
+  "integrations.detail.runActivity.status.completed": "Completed",
+  "integrations.detail.runActivity.status.failed": "Failed",
+  "integrations.detail.runActivity.status.pending": "Pending",
+  "integrations.detail.runActivity.status.running": "Running",
   "integrations.detail.state.disabled": "Disabled",
   "integrations.detail.state.enabled": "Enabled",
   "integrations.detail.state.label": "State",

package/src/modules/integrations/i18n/es.json

@@ -126,6 +126,15 @@
   "integrations.detail.logs.level.info": "Info",
   "integrations.detail.logs.level.warn": "Advertencia",
   "integrations.detail.logs.title": "Registros de operación",
+  "integrations.detail.runActivity.lastRefreshed": "Última actualización",
+  "integrations.detail.runActivity.processed": "Procesados",
+  "integrations.detail.runActivity.progress": "Progreso",
+  "integrations.detail.runActivity.refresh": "Actualizar",
+  "integrations.detail.runActivity.status.cancelled": "Cancelado",
+  "integrations.detail.runActivity.status.completed": "Completado",
+  "integrations.detail.runActivity.status.failed": "Fallido",
+  "integrations.detail.runActivity.status.pending": "Pendiente",
+  "integrations.detail.runActivity.status.running": "En curso",
   "integrations.detail.state.disabled": "Disabled",
   "integrations.detail.state.enabled": "Enabled",
   "integrations.detail.state.label": "State",

package/src/modules/integrations/i18n/pl.json

@@ -126,6 +126,15 @@
   "integrations.detail.logs.level.info": "Info",
   "integrations.detail.logs.level.warn": "Ostrzeżenie",
   "integrations.detail.logs.title": "Logi operacji",
+  "integrations.detail.runActivity.lastRefreshed": "Ostatnio odświeżono",
+  "integrations.detail.runActivity.processed": "Przetworzone",
+  "integrations.detail.runActivity.progress": "Postęp",
+  "integrations.detail.runActivity.refresh": "Odśwież",
+  "integrations.detail.runActivity.status.cancelled": "Anulowany",
+  "integrations.detail.runActivity.status.completed": "Zakończony",
+  "integrations.detail.runActivity.status.failed": "Nieudany",
+  "integrations.detail.runActivity.status.pending": "Oczekuje",
+  "integrations.detail.runActivity.status.running": "Trwa",
   "integrations.detail.state.disabled": "Disabled",
   "integrations.detail.state.enabled": "Enabled",
   "integrations.detail.state.label": "State",

package/src/modules/sync_excel/acl.ts

@@ -0,0 +1,6 @@
+export const features = [
+  { id: 'sync_excel.view', title: 'View sync_excel uploads and previews', module: 'sync_excel' },
+  { id: 'sync_excel.run', title: 'Upload CSV files and prepare imports', module: 'sync_excel' },
+]
+
+export default features

package/src/modules/sync_excel/api/import/route.ts

@@ -0,0 +1,182 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { z } from 'zod'
+import type { ProgressService } from '@open-mercato/core/modules/progress/lib/progressService'
+import type { SyncRunService } from '@open-mercato/core/modules/data_sync/lib/sync-run-service'
+import { startDataSyncRun } from '@open-mercato/core/modules/data_sync/lib/start-run'
+import { SyncMapping } from '@open-mercato/core/modules/data_sync/data/entities'
+import type { CredentialsService } from '@open-mercato/core/modules/integrations/lib/credentials-service'
+import type { IntegrationStateService } from '@open-mercato/core/modules/integrations/lib/state-service'
+import { SyncExcelUpload } from '../../data/entities'
+import { Attachment } from '../../../attachments/data/entities'
+import { createCursor } from '../../lib/adapters/customers'
+import {
+  syncExcelImportRequestSchema,
+  syncExcelImportResponseSchema,
+} from '../../data/validators'
+import { resolveSyncExcelConcreteScope } from '../../lib/scope'
+
+export const metadata = {
+  POST: { requireAuth: true, requireFeatures: ['sync_excel.run'] },
+}
+
+const errorSchema = z.object({
+  error: z.string(),
+})
+
+export const openApi = {
+  tags: ['SyncExcel'],
+  summary: 'Start a CSV import run for a stored sync_excel upload',
+  methods: {
+    POST: {
+      summary: 'Start CSV import',
+      responses: [
+        { status: 201, description: 'Import run started', schema: syncExcelImportResponseSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 404, description: 'Upload not found', schema: errorSchema },
+        { status: 409, description: 'Import overlap detected', schema: errorSchema },
+        { status: 422, description: 'Invalid import payload', schema: errorSchema },
+      ],
+    },
+  },
+}
+
+export async function POST(request: Request) {
+  const auth = await getAuthFromRequest(request)
+  if (!auth?.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const payload = await readJsonSafe(request)
+  const parsedPayload = syncExcelImportRequestSchema.safeParse(payload)
+  if (!parsedPayload.success) {
+    return NextResponse.json({ error: 'Invalid import payload.' }, { status: 422 })
+  }
+
+  const container = await createRequestContainer()
+  const em = container.resolve('em') as EntityManager
+  const syncRunService = container.resolve('dataSyncRunService') as SyncRunService
+  const progressService = container.resolve('progressService') as ProgressService
+  const credentialsService = container.resolve('integrationCredentialsService') as CredentialsService
+  const integrationStateService = container.resolve('integrationStateService') as IntegrationStateService
+  const scopeResult = await resolveSyncExcelConcreteScope({ auth, container, request })
+  if (!scopeResult.ok) {
+    return NextResponse.json({ error: scopeResult.error }, { status: scopeResult.status })
+  }
+  const { scope } = scopeResult
+
+  const upload = await findOneWithDecryption(
+    em,
+    SyncExcelUpload,
+    {
+      id: parsedPayload.data.uploadId,
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+    },
+    undefined,
+    scope,
+  )
+
+  if (!upload) {
+    return NextResponse.json({ error: 'Upload preview not found.' }, { status: 404 })
+  }
+
+  const attachment = await findOneWithDecryption(
+    em,
+    Attachment,
+    {
+      id: upload.attachmentId,
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+    },
+    undefined,
+    scope,
+  )
+
+  if (!attachment) {
+    return NextResponse.json({ error: 'Upload attachment not found.' }, { status: 404 })
+  }
+
+  if (upload.entityType !== parsedPayload.data.entityType) {
+    return NextResponse.json({ error: 'Upload entity type does not match requested import target.' }, { status: 422 })
+  }
+
+  if (parsedPayload.data.mapping.entityType !== parsedPayload.data.entityType) {
+    return NextResponse.json({ error: 'Mapping entity type does not match requested import target.' }, { status: 422 })
+  }
+
+  const overlap = await syncRunService.findRunningOverlap('sync_excel', parsedPayload.data.entityType, 'import', scope)
+  if (overlap) {
+    return NextResponse.json({ error: 'A sync_excel import is already in progress for this entity type.' }, { status: 409 })
+  }
+
+  const existingMapping = await findOneWithDecryption(
+    em,
+    SyncMapping,
+    {
+      integrationId: 'sync_excel',
+      entityType: parsedPayload.data.entityType,
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+    },
+    undefined,
+    scope,
+  )
+
+  if (existingMapping) {
+    existingMapping.mapping = parsedPayload.data.mapping
+  } else {
+    em.persist(em.create(SyncMapping, {
+      integrationId: 'sync_excel',
+      entityType: parsedPayload.data.entityType,
+      mapping: parsedPayload.data.mapping,
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+    }))
+  }
+
+  await credentialsService.save('sync_excel', {}, scope)
+  await integrationStateService.upsert('sync_excel', { isEnabled: true }, scope)
+  await em.flush()
+
+  const { run, progressJob } = await startDataSyncRun({
+    syncRunService,
+    progressService,
+    scope: {
+      ...scope,
+      userId: auth.sub,
+    },
+    input: {
+      integrationId: 'sync_excel',
+      entityType: parsedPayload.data.entityType,
+      direction: 'import',
+      cursor: createCursor(upload.id, 0),
+      triggeredBy: auth.sub,
+      batchSize: parsedPayload.data.batchSize ?? 100,
+      progressJob: {
+        jobType: 'sync_excel:import',
+        name: `CSV import — ${parsedPayload.data.entityType}`,
+        description: upload.filename,
+        meta: {
+          integrationId: 'sync_excel',
+          uploadId: upload.id,
+          hiddenFromTopBar: false,
+        },
+      },
+    },
+  })
+
+  upload.syncRunId = run.id
+  upload.status = 'importing'
+  await em.flush()
+
+  return NextResponse.json(syncExcelImportResponseSchema.parse({
+    runId: run.id,
+    progressJobId: progressJob?.id ?? null,
+    status: run.status,
+  }), { status: 201 })
+}

package/src/modules/sync_excel/api/preview/route.ts

@@ -0,0 +1,89 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { NextResponse } from 'next/server'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { z } from 'zod'
+import { syncExcelPreviewQuerySchema, syncExcelUploadResponseSchema } from '../../data/validators'
+import { SyncExcelUpload } from '../../data/entities'
+import { buildSuggestedMapping } from '../../lib/mapping'
+import { resolveSyncExcelConcreteScope } from '../../lib/scope'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['sync_excel.view'] },
+}
+
+const errorSchema = z.object({
+  error: z.string(),
+})
+
+export const openApi = {
+  tags: ['SyncExcel'],
+  summary: 'Fetch stored preview for a sync_excel upload',
+  methods: {
+    GET: {
+      summary: 'Fetch upload preview',
+      responses: [
+        { status: 200, description: 'Stored upload preview', schema: syncExcelUploadResponseSchema },
+        { status: 401, description: 'Unauthorized', schema: errorSchema },
+        { status: 422, description: 'Invalid query', schema: errorSchema },
+        { status: 404, description: 'Upload preview not found', schema: errorSchema },
+      ],
+    },
+  },
+}
+
+export async function GET(request: Request) {
+  const auth = await getAuthFromRequest(request)
+  if (!auth?.tenantId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const url = new URL(request.url)
+  const parsedQuery = syncExcelPreviewQuerySchema.safeParse({
+    uploadId: url.searchParams.get('uploadId'),
+    entityType: url.searchParams.get('entityType') ?? undefined,
+  })
+
+  if (!parsedQuery.success) {
+    return NextResponse.json({ error: 'Invalid query' }, { status: 422 })
+  }
+
+  const container = await createRequestContainer()
+  const scopeResult = await resolveSyncExcelConcreteScope({ auth, container, request })
+  if (!scopeResult.ok) {
+    return NextResponse.json({ error: scopeResult.error }, { status: scopeResult.status })
+  }
+  const { scope } = scopeResult
+  const em = container.resolve('em') as EntityManager
+  const upload = await findOneWithDecryption(
+    em,
+    SyncExcelUpload,
+    {
+      id: parsedQuery.data.uploadId,
+      organizationId: scope.organizationId,
+      tenantId: scope.tenantId,
+    },
+    undefined,
+    scope,
+  )
+
+  if (!upload) {
+    return NextResponse.json({ error: 'Upload preview not found.' }, { status: 404 })
+  }
+
+  const entityType = parsedQuery.data.entityType ?? upload.entityType
+  const suggestedMapping = buildSuggestedMapping(entityType, upload.headers)
+
+  return NextResponse.json(syncExcelUploadResponseSchema.parse({
+    uploadId: upload.id,
+    filename: upload.filename,
+    mimeType: upload.mimeType,
+    fileSize: upload.fileSize,
+    entityType,
+    headers: upload.headers,
+    sampleRows: upload.sampleRows,
+    totalRows: upload.totalRows,
+    suggestedMapping,
+  }))
+}