feat(import/export): article import + register export (xlsx/csv) (#750)

* feat(import/export): article import + register export (xlsx/csv)

Add CSV/Excel import for the article register (artiklar), mirroring the
existing customer/supplier import pipeline, plus Excel + CSV export for
articles, customers and suppliers.

Import (lib/import/articles + app/api/import/articles):
- Column auto-detection tuned to Fortnox/Visma/Bokio export headers,
  Swedish-decimal price parsing, VAT snapped to {0,6,12,25}, type/unit
  normalization.
- Dedup by article number then name; 23505 soft-skip; auto-number
  backfill; revenue-account override kept only when active, otherwise
  dropped with a warning (never mutates the chart of accounts).
- New "Artiklar" flow in the /import hub.

Export (app/api/export/* + lib/export/register-export):
- Read-only xlsx (default) / csv (?format=csv, UTF-8 BOM) downloads.
- Headers chosen so files round-trip back through the importer.
- "Exportera" menu added to the articles, customers and suppliers pages.

Refs #746. Direct Fortnox/Visma API article fetch tracked in #749.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(import/export): address PR review — lint ratchet + export hardening

- xlsx-export: keep `SheetSpec<any>` on the eslint-disabled line (fixes the
  core-only lint ratchet regression: no-explicit-any 16 -> 15) and define
  UTF8_BOM as an explicit `` escape instead of a raw BOM character.
- export routes (articles/customers/suppliers): move the data queries inside
  the try/catch, add `Cache-Control: no-store`, and emit a `register exported`
  audit log line (entity, format, rowCount).
- articles parse route: validate `column_overrides` against a Zod schema before
  trusting it to drive the parser.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(import): drop öre-round pattern on article column-detector confidence

The confidence score is a 0-1 heuristic, not money, and is only compared
against the 0.8 skip-mapping threshold. Removing the Math.round(x*100)/100
form clears the core-only antipattern ratchet (naive-ore-round 660 -> 659).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(import): flag adjusted VAT rows in the article import edit step

Surface VAT snapping/defaulting per row, not just as a file-level warning:
the parser sets `vat_rate_adjusted`, the edit step highlights those rows'
VAT selector and shows a count banner, and confirming a rate clears the flag.
Addresses the Swedish-compliance review note that silent snapping could
otherwise store a wrong VAT rate at scale.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app/api/import/articles/__tests__/execute.test.ts

@@ -0,0 +1,182 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import {
+  createMockRequest,
+  parseJsonResponse,
+  createQueuedMockSupabase,
+} from '@/tests/helpers'
+
+const { supabase: mockSupabase, enqueue, reset } = createQueuedMockSupabase()
+
+vi.mock('@/lib/supabase/server', () => ({
+  createClient: () => Promise.resolve(mockSupabase),
+}))
+
+vi.mock('@/lib/init', () => ({ ensureInitialized: vi.fn() }))
+
+vi.mock('@/lib/auth/require-write', () => ({
+  requireWritePermission: vi.fn().mockResolvedValue({ ok: true }),
+}))
+
+vi.mock('@/lib/company/context', () => ({
+  requireCompanyId: vi.fn().mockResolvedValue('company-1'),
+  getActiveCompanyId: vi.fn().mockResolvedValue('company-1'),
+}))
+
+const mockEmit = vi.fn().mockResolvedValue(undefined)
+vi.mock('@/lib/events', () => ({ eventBus: { emit: (...a: unknown[]) => mockEmit(...a) } }))
+
+const mockFetchAllRows = vi.fn()
+vi.mock('@/lib/supabase/fetch-all', () => ({
+  fetchAllRows: (...a: unknown[]) => mockFetchAllRows(...a),
+}))
+
+const mockEnsureArticleNumber = vi.fn().mockResolvedValue('AUTO-1')
+vi.mock('@/lib/articles/ensure-article-number', () => ({
+  ensureArticleNumber: (...a: unknown[]) => mockEnsureArticleNumber(...a),
+}))
+
+const mockCheckRevenueAccount = vi.fn().mockResolvedValue('ok')
+vi.mock('@/lib/articles/validate-revenue-account', () => ({
+  checkRevenueAccount: (...a: unknown[]) => mockCheckRevenueAccount(...a),
+}))
+
+import { POST } from '../execute/route'
+
+const mockUser = { id: 'user-1', email: 'test@test.se' }
+
+function row(overrides: Record<string, unknown> = {}) {
+  return {
+    row_index: 2,
+    name: 'Konsulttimme',
+    name_en: null,
+    article_number: null,
+    type: 'tjanst',
+    unit: 'tim',
+    price_excl_vat: 950,
+    vat_rate: 25,
+    revenue_account: null,
+    cost_price: null,
+    ean: null,
+    housework_type: null,
+    notes: null,
+    ...overrides,
+  }
+}
+
+function makeRequest(body: unknown) {
+  return createMockRequest('/api/import/articles/execute', { method: 'POST', body })
+}
+
+describe('POST /api/import/articles/execute', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    reset()
+    mockSupabase.auth.getUser.mockResolvedValue({ data: { user: mockUser } })
+    mockFetchAllRows.mockResolvedValue([])
+    mockCheckRevenueAccount.mockResolvedValue('ok')
+    mockEnsureArticleNumber.mockResolvedValue('AUTO-1')
+  })
+
+  it('returns 401 for unauthenticated requests', async () => {
+    mockSupabase.auth.getUser.mockResolvedValue({ data: { user: null } })
+    const res = await POST(makeRequest({ rows: [row()], update_duplicates: false }))
+    const { status } = await parseJsonResponse(res)
+    expect(status).toBe(401)
+  })
+
+  it('returns 400 for an empty rows array', async () => {
+    const res = await POST(makeRequest({ rows: [], update_duplicates: false }))
+    const { status } = await parseJsonResponse(res)
+    expect(status).toBe(400)
+  })
+
+  it('creates new articles and emits article.created', async () => {
+    enqueue({ data: { id: 'a1', name: 'Konsulttimme', article_number: null } })
+    enqueue({ data: { id: 'a2', name: 'Skruv', article_number: 'A-200' } })
+
+    const res = await POST(makeRequest({
+      rows: [row(), row({ row_index: 3, name: 'Skruv', article_number: 'A-200', type: 'vara' })],
+      update_duplicates: false,
+    }))
+    const { status, body } = await parseJsonResponse(res)
+
+    expect(status).toBe(200)
+    expect(body.data.created).toBe(2)
+    expect(body.data.failed).toBe(0)
+    expect(mockEmit).toHaveBeenCalledTimes(2)
+    // The numberless row gets auto-numbered; the one with A-200 does not.
+    expect(mockEnsureArticleNumber).toHaveBeenCalledTimes(1)
+  })
+
+  it('skips a duplicate matched by article number when update_duplicates is false', async () => {
+    mockFetchAllRows.mockResolvedValue([{ id: 'x', name: 'Existing', article_number: 'A-1' }])
+
+    const res = await POST(makeRequest({
+      rows: [row({ article_number: 'A-1' })],
+      update_duplicates: false,
+    }))
+    const { status, body } = await parseJsonResponse(res)
+
+    expect(status).toBe(200)
+    expect(body.data.skipped).toBe(1)
+    expect(body.data.created).toBe(0)
+  })
+
+  it('updates a duplicate matched by article number when update_duplicates is true', async () => {
+    mockFetchAllRows.mockResolvedValue([{ id: 'x', name: 'Old', article_number: 'A-1' }])
+    enqueue({ data: { id: 'x', name: 'New name', article_number: 'A-1' } })
+
+    const res = await POST(makeRequest({
+      rows: [row({ article_number: 'A-1', name: 'New name' })],
+      update_duplicates: true,
+    }))
+    const { status, body } = await parseJsonResponse(res)
+
+    expect(status).toBe(200)
+    expect(body.data.updated).toBe(1)
+    expect(body.data.created).toBe(0)
+  })
+
+  it('matches a duplicate by name (case-insensitive)', async () => {
+    mockFetchAllRows.mockResolvedValue([{ id: 'x', name: 'Konsulttimme', article_number: null }])
+
+    const res = await POST(makeRequest({
+      rows: [row({ name: 'KONSULTTIMME' })],
+      update_duplicates: false,
+    }))
+    const { status, body } = await parseJsonResponse(res)
+
+    expect(status).toBe(200)
+    expect(body.data.skipped).toBe(1)
+  })
+
+  it('treats a 23505 unique violation as a soft skip', async () => {
+    enqueue({ data: null, error: { code: '23505', message: 'duplicate key' } })
+
+    const res = await POST(makeRequest({
+      rows: [row({ article_number: 'A-DUP' })],
+      update_duplicates: false,
+    }))
+    const { status, body } = await parseJsonResponse(res)
+
+    expect(status).toBe(200)
+    expect(body.data.skipped).toBe(1)
+    expect(body.data.failed).toBe(0)
+  })
+
+  it('drops an inactive/unknown revenue account and records a warning', async () => {
+    mockCheckRevenueAccount.mockResolvedValue('activatable')
+    enqueue({ data: { id: 'a1', name: 'Konsulttimme', article_number: 'A-1' } })
+
+    const res = await POST(makeRequest({
+      rows: [row({ article_number: 'A-1', revenue_account: '3999' })],
+      update_duplicates: false,
+    }))
+    const { status, body } = await parseJsonResponse(res)
+
+    expect(status).toBe(200)
+    expect(body.data.created).toBe(1)
+    expect(body.data.warnings.length).toBeGreaterThan(0)
+    expect(body.data.warnings[0]).toContain('3999')
+  })
+})

app/api/import/articles/execute/route.ts

@@ -0,0 +1,233 @@
+import { NextResponse } from 'next/server'
+import { ensureInitialized } from '@/lib/init'
+import { eventBus } from '@/lib/events'
+import { validateBody } from '@/lib/api/validate'
+import { ArticleImportExecuteSchema } from '@/lib/api/schemas'
+import { fetchAllRows } from '@/lib/supabase/fetch-all'
+import { withRouteContext } from '@/lib/api/with-route-context'
+import { errorResponseFromCode } from '@/lib/errors/get-structured-error'
+import { ensureArticleNumber } from '@/lib/articles/ensure-article-number'
+import { checkRevenueAccount, type RevenueAccountStatus } from '@/lib/articles/validate-revenue-account'
+import type { Article } from '@/types'
+import type { ArticleImportExecuteResult } from '@/lib/import/articles/types'
+
+ensureInitialized()
+
+interface ExistingArticle {
+  id: string
+  name: string
+  article_number: string | null
+}
+
+function nameKey(value: string | null): string | null {
+  if (!value) return null
+  return value.trim().toLowerCase() || null
+}
+
+/**
+ * POST /api/import/articles/execute
+ *
+ * Imports validated article rows. Duplicates (matched by article number, then
+ * by name) are either updated (merge — only non-empty fields overwrite) or
+ * skipped based on `update_duplicates`. An optional BAS revenue-account override
+ * is kept only when it is an active class-3 account; unknown/inactive accounts
+ * are dropped (with a warning) rather than mutating the chart of accounts.
+ */
+export const POST = withRouteContext(
+  'register_import.articles.execute',
+  async (request, ctx) => {
+    const { user, supabase, companyId, log, requestId } = ctx
+
+    const result = await validateBody(request, ArticleImportExecuteSchema, {
+      log,
+      operation: 'register_import.articles.execute',
+    })
+    if (!result.success) return result.response
+
+    const { rows, update_duplicates } = result.data
+    const opLog = log.child({ rowCount: rows.length, updateDuplicates: update_duplicates })
+
+    if (rows.length === 0) {
+      return errorResponseFromCode('REG_IMPORT_NO_ROWS', opLog, { requestId })
+    }
+
+    try {
+      const existingRaw = await fetchAllRows(({ from, to }) =>
+        supabase
+          .from('articles')
+          .select('id, name, article_number')
+          .eq('company_id', companyId)
+          .range(from, to),
+      )
+      const existing = existingRaw as unknown as ExistingArticle[]
+
+      const byNumber = new Map<string, ExistingArticle>()
+      const byName = new Map<string, ExistingArticle>()
+      for (const a of existing) {
+        if (a.article_number) byNumber.set(a.article_number, a)
+        const nk = nameKey(a.name)
+        if (nk && !byName.has(nk)) byName.set(nk, a)
+      }
+
+      // Revenue-account validation is cached per distinct account so a large
+      // import doesn't re-query the chart for every row.
+      const accountStatusCache = new Map<string, RevenueAccountStatus>()
+      const droppedAccounts = new Set<string>()
+      const warnings: string[] = []
+      const resolveRevenueAccount = async (acc: string | null): Promise<string | null> => {
+        if (!acc) return null
+        let status = accountStatusCache.get(acc)
+        if (!status) {
+          status = await checkRevenueAccount(supabase, companyId!, acc)
+          accountStatusCache.set(acc, status)
+        }
+        if (status === 'ok') return acc
+        if (!droppedAccounts.has(acc)) {
+          droppedAccounts.add(acc)
+          warnings.push(
+            status === 'activatable'
+              ? `Försäljningskonto ${acc} är inte aktiverat i kontoplanen — artiklar importerades utan kontoöverstyrning.`
+              : `Försäljningskonto ${acc} är ogiltigt — ignorerades.`,
+          )
+        }
+        return null
+      }
+
+      const created: Article[] = []
+      const updated: Article[] = []
+      let skipped = 0
+      const errors: { row_index: number; name: string; reason: string }[] = []
+
+      for (const row of rows) {
+        const nk = nameKey(row.name)
+        const match =
+          (row.article_number ? byNumber.get(row.article_number) : undefined) ??
+          (nk ? byName.get(nk) : undefined) ??
+          null
+
+        const revenueAccount = await resolveRevenueAccount(row.revenue_account)
+
+        if (match) {
+          if (!update_duplicates) {
+            skipped++
+            continue
+          }
+
+          // Merge mode: overwrite only fields the file clearly carries a value
+          // for. type/unit/vat_rate carry parser defaults that can't be told
+          // apart from "absent", so they are left untouched to avoid clobbering.
+          const merged: Record<string, unknown> = {}
+          if (row.name) merged.name = row.name
+          if (row.name_en) merged.name_en = row.name_en
+          if (row.price_excl_vat > 0) merged.price_excl_vat = row.price_excl_vat
+          if (row.cost_price !== null) merged.cost_price = row.cost_price
+          if (row.ean) merged.ean = row.ean
+          if (row.housework_type) merged.housework_type = row.housework_type
+          if (row.notes) merged.notes = row.notes
+          if (revenueAccount) merged.revenue_account = revenueAccount
+
+          if (Object.keys(merged).length === 0) {
+            skipped++
+            continue
+          }
+
+          const { data, error } = await supabase
+            .from('articles')
+            .update(merged)
+            .eq('id', match.id)
+            .eq('company_id', companyId)
+            .select()
+            .single()
+
+          if (error) {
+            errors.push({ row_index: row.row_index, name: row.name, reason: error.message })
+            continue
+          }
+          if (data) updated.push(data as Article)
+          continue
+        }
+
+        // No match — create.
+        const { data, error } = await supabase
+          .from('articles')
+          .insert({
+            user_id: user.id,
+            company_id: companyId,
+            name: row.name,
+            name_en: row.name_en,
+            type: row.type,
+            unit: row.unit || 'st',
+            price_excl_vat: row.price_excl_vat,
+            vat_rate: row.vat_rate,
+            revenue_account: revenueAccount,
+            cost_price: row.cost_price,
+            ean: row.ean,
+            housework_type: row.housework_type,
+            notes: row.notes,
+            article_number: row.article_number,
+          })
+          .select()
+          .single()
+
+        if (error) {
+          // Unique violation on (company_id, article_number) — treat as a soft
+          // skip (manual number collided with an existing or in-batch article).
+          if (error.code === '23505') {
+            skipped++
+            continue
+          }
+          errors.push({ row_index: row.row_index, name: row.name, reason: error.message })
+          continue
+        }
+
+        if (data) {
+          // Auto-number when the file didn't supply one. Non-fatal: an
+          // unnumbered article is still usable and can be numbered later.
+          if (!data.article_number) {
+            try {
+              data.article_number = await ensureArticleNumber(supabase, companyId!, data.id)
+            } catch (err) {
+              opLog.warn('article number assignment failed', err as Error, { articleId: data.id })
+            }
+          }
+          created.push(data as Article)
+          // Track newly inserted number + name so later rows in the same batch
+          // dedup against them too.
+          const newArticle = data as ExistingArticle
+          if (newArticle.article_number) byNumber.set(newArticle.article_number, newArticle)
+          const nk = nameKey(newArticle.name)
+          if (nk && !byName.has(nk)) byName.set(nk, newArticle)
+        }
+      }
+
+      // Emit events for downstream listeners (non-blocking).
+      for (const a of created) {
+        await eventBus.emit({
+          type: 'article.created',
+          payload: { article: a, companyId: companyId!, userId: user.id },
+        })
+      }
+
+      const response: ArticleImportExecuteResult = {
+        success: errors.length === 0,
+        created: created.length,
+        updated: updated.length,
+        skipped,
+        failed: errors.length,
+        errors,
+        warnings,
+      }
+
+      opLog.info('article import complete', response)
+
+      return NextResponse.json({ data: response })
+    } catch (err) {
+      opLog.error('article import execute failed', err as Error)
+      return errorResponseFromCode('REG_IMPORT_EXECUTE_FAILED', opLog, {
+        requestId,
+        details: { reason: err instanceof Error ? err.message : 'unknown' },
+      })
+    }
+  },
+  { requireWrite: true },
+)

app/api/import/articles/parse/route.ts

@@ -0,0 +1,134 @@
+import { NextResponse } from 'next/server'
+import { parseArticlesFile } from '@/lib/import/articles/parser'
+import { fetchAllRows } from '@/lib/supabase/fetch-all'
+import { withRouteContext } from '@/lib/api/with-route-context'
+import { errorResponseFromCode } from '@/lib/errors/get-structured-error'
+import { ArticleColumnOverridesSchema } from '@/lib/api/schemas'
+import type {
+  AnnotatedArticleRow,
+  ArticleImportParseResult,
+  DetectedArticleColumns,
+} from '@/lib/import/articles/types'
+
+const ALLOWED_EXTENSIONS = ['.xlsx', '.xls', '.csv', '.ods']
+const MAX_FILE_SIZE = 10 * 1024 * 1024 // 10 MB
+
+/** Lowercased dedup key for matching an article by name. */
+function nameKey(value: string | null): string | null {
+  if (!value) return null
+  return value.trim().toLowerCase() || null
+}
+
+/**
+ * POST /api/import/articles/parse
+ *
+ * Accepts an Excel/CSV file via FormData, auto-detects columns, parses rows,
+ * and annotates each row with any duplicate-match against existing articles
+ * (by article number first, then by name).
+ */
+export const POST = withRouteContext(
+  'register_import.articles.parse',
+  async (request, ctx) => {
+    const { supabase, companyId, log, requestId } = ctx
+
+    const formData = await request.formData()
+    const file = formData.get('file') as File | null
+    const columnOverridesRaw = formData.get('column_overrides') as string | null
+
+    if (!file) {
+      return errorResponseFromCode('REG_IMPORT_NO_FILE', log, { requestId })
+    }
+
+    if (file.size > MAX_FILE_SIZE) {
+      return errorResponseFromCode('REG_IMPORT_FILE_TOO_LARGE', log, {
+        requestId,
+        details: { sizeMb: +(file.size / 1024 / 1024).toFixed(1) },
+      })
+    }
+
+    const ext = '.' + file.name.split('.').pop()?.toLowerCase()
+    if (!ALLOWED_EXTENSIONS.includes(ext)) {
+      return errorResponseFromCode('REG_IMPORT_INVALID_FORMAT', log, {
+        requestId,
+        details: { extension: ext, allowed: ALLOWED_EXTENSIONS },
+      })
+    }
+
+    const opLog = log.child({ filename: file.name, sizeBytes: file.size })
+
+    let columnOverrides: DetectedArticleColumns | undefined
+    if (columnOverridesRaw) {
+      let raw: unknown
+      try {
+        raw = JSON.parse(columnOverridesRaw)
+      } catch {
+        return errorResponseFromCode('REG_IMPORT_INVALID_COLUMN_OVERRIDES', opLog, { requestId })
+      }
+      // Validate shape/indices before trusting it to drive the parser.
+      const parsed = ArticleColumnOverridesSchema.safeParse(raw)
+      if (!parsed.success) {
+        return errorResponseFromCode('REG_IMPORT_INVALID_COLUMN_OVERRIDES', opLog, { requestId })
+      }
+      columnOverrides = parsed.data
+    }
+
+    try {
+      const buffer = await file.arrayBuffer()
+      const parsed = parseArticlesFile(buffer, file.name, columnOverrides)
+
+      // Fetch existing articles for duplicate detection.
+      const existing = await fetchAllRows(({ from, to }) =>
+        supabase
+          .from('articles')
+          .select('id, name, article_number')
+          .eq('company_id', companyId)
+          .range(from, to),
+      )
+
+      const byNumber = new Map<string, { id: string; name: string }>()
+      const byName = new Map<string, { id: string; name: string }>()
+      for (const a of existing) {
+        if (a.article_number) byNumber.set(String(a.article_number), { id: a.id, name: a.name })
+        const nk = nameKey(a.name)
+        if (nk && !byName.has(nk)) byName.set(nk, { id: a.id, name: a.name })
+      }
+
+      let duplicateCount = 0
+      const annotated: AnnotatedArticleRow[] = parsed.rows.map((r) => {
+        let match: AnnotatedArticleRow['duplicate_match'] = null
+        if (r.article_number && byNumber.has(r.article_number)) {
+          const e = byNumber.get(r.article_number)!
+          match = { article_id: e.id, matched_by: 'article_number', existing_name: e.name }
+        } else {
+          const nk = nameKey(r.name)
+          if (nk && byName.has(nk)) {
+            const e = byName.get(nk)!
+            match = { article_id: e.id, matched_by: 'name', existing_name: e.name }
+          }
+        }
+        if (match) duplicateCount++
+        return { ...r, duplicate_match: match }
+      })
+
+      const result: ArticleImportParseResult = {
+        filename: parsed.filename,
+        sheet_name: parsed.sheet_name,
+        total_rows: annotated.length,
+        detected_columns: parsed.detected_columns,
+        headers: parsed.headers,
+        preview_rows: parsed.preview_rows,
+        rows: annotated,
+        duplicate_count: duplicateCount,
+        warnings: parsed.warnings,
+      }
+
+      return NextResponse.json({ data: result })
+    } catch (err) {
+      opLog.error('article import parse failed', err as Error)
+      return errorResponseFromCode('REG_IMPORT_PARSE_FAILED', opLog, {
+        requestId,
+        details: { reason: err instanceof Error ? err.message : 'unknown' },
+      })
+    }
+  },
+)