feat(dimensions): PR2 registry — CRUD API, register UI, settings toggle, SIE export on the new registry (#858)

* feat(dimensions): PR2 registry — CRUD API, register UI, settings toggle, SIE export on the new registry Phase 2 of dev_docs/dimensions_implementation_plan.md. Companies with dimensions_enabled=false (default) see zero change. API: - Dashboard CRUD: GET /api/dimensions (lazy-seeds system dims 1/6 via the ensure_company_dimensions RPC), PATCH /api/dimensions/[id] (is_system rename blocked), POST/PATCH/DELETE values (code immutable after creation; strict Fortnox code format ^[A-Za-z0-9ÅÄÖåäö_+\-]{1,20}$ at the API layer; retention-trigger deletes surface the Swedish "arkivera istället" message as 409 DIMENSION_VALUE_REFERENCED). - POST /api/dimensions/import-existing — scans journal_entry_lines.dimensions for unregistered codes and mints inactive placeholder registry rows. - v1 public API: GET dimensions + POST values (Idempotency-Key, dry-run), registered in the OpenAPI spec (102→104 endpoints). - dimensions_enabled boolean on company_settings (new migration, UI-visibility only, never correctness-bearing) exposed through the existing settings read/update path. SIE export (lib/reports/sie-export.ts): - Reads the new dimensions/dimension_values registry; legacy cost_centers/projects tables now have zero readers (drop migration next). - Fixes the latent Visma-rejection bug: #OBJEKT now declared for INACTIVE values referenced by lines. - Generic-N: #DIM/#UNDERDIM loop sorted by sie_dim_no; #TRANS object lists serialize from the line JSONB map (sorted, '01'→'1' collapse); orphan codes/dims synthesize declarations from the SIE reserved-number seed — every referenced (dim, code) pair is guaranteed declared. UI: - /dimensions register (Register-recipe): tabs per dimension, search, sortable table, value dialog (code immutable on edit, projekt dates on dim 6), archive-not-delete affordances. - DimensionCombobox shipped (mounts in the tagging PR). - Settings toggle "Aktivera kostnadsställen & projekt" — toggle-on runs the import-existing scan and links to the register. - Nav row in redovisning, rendered only when dimensions_enabled (same mechanism as pays_salaries). - dimensions.* i18n namespace (51 keys, sv/en parity). - Sandbox seed: demo dims + values, revenue line tagged {"1":"BUTIK","6":"P001"}. Verified: 6328/6328 unit tests, guard + coverage gate green, tsc parity with main (210=210), production build passes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(dimensions): PR2 review round — atomic archived-create, UNDERDIM ordering, import robustness, date semantics - POST values accepts is_active so "create as archived" is atomic; the UI's fragile create-then-PATCH fallback is deleted (PR Agent finding 1). - DimensionCombobox blur revert reads the committed value/values through refs so a selection landing inside the 150ms window always wins (finding 2). - import-existing sanitizes candidate codes like the PR1 backfill and upserts with ignoreDuplicates — one bad/duplicate code can no longer abort the batch; created counted from returned rows (finding 3). - SIE export emits all root #DIM before any #UNDERDIM so a parent always precedes a lower-numbered child (SIE4 declaration order — Swedish review); synthesized placeholder declarations now log one structured warning (BFNAR 2013:2 behandlingshistorik) + defence-in-depth comment. - Value dates rejected (400 DIMENSION_VALUE_DATES_NOT_ALLOWED) when the parent dimension is flow-period (resets_annually=true); explicit null still clears (Swedish review). - Sandbox seed logs seeded dimension codes; GET /api/dimensions documents the deliberate absence of dimensions_enabled gating (UI-visibility flag, not a security boundary — compliance-swarm V8.2.1 rejected by design). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 12:26:42 +02:00
parent 8cc2efb083
commit 8bb49c07a2
35 changed files with 3981 additions and 100 deletions
@@ -0,0 +1,166 @@
+/**
+ * POST /api/v1/companies/{companyId}/dimensions/{id}/values
+ *
+ * Create a dimension value (SIE #OBJEKT). Idempotent (mandatory
+ * Idempotency-Key), dry-runnable. Codes follow the strict Fortnox format
+ * (^[A-Za-z0-9ÅÄÖåäö_+\-]{1,20}$) for user-created values; the DB CHECK is
+ * looser by design so legacy free-text codes survive imports. `code` is
+ * immutable after creation.
+ */
+import { z } from 'zod'
+import { created } from '@/lib/api/v1/response'
+import { dryRunPreview } from '@/lib/api/v1/dry-run'
+import { registerEndpoint, dataEnvelope } from '@/lib/api/v1/registry'
+import { withApiV1 } from '@/lib/api/v1/with-api-v1'
+import { v1ErrorResponse, v1ErrorResponseFromCode } from '@/lib/api/v1/errors'
+import { CreateDimensionValueSchema } from '@/lib/api/schemas'
+
+const DimensionValueCreated = z.object({
+  id: z.string().uuid().nullable(),
+  dimension_id: z.string().uuid(),
+  code: z.string(),
+  name: z.string(),
+  is_active: z.boolean(),
+  start_date: z.string().nullable(),
+  end_date: z.string().nullable(),
+  created_at: z.string().nullable(),
+})
+
+registerEndpoint({
+  operation: 'dimensions.values.create',
+  method: 'POST',
+  path: '/api/v1/companies/:companyId/dimensions/:id/values',
+  summary: 'Create a dimension value (kostnadsställe/projekt code).',
+  description:
+    'Registers a new value (SIE #OBJEKT) under a dimension — e.g. a new project code under dimension 6. Requires Idempotency-Key (UUID). Supports ?dry_run=true to validate the code format without committing. The `:id` path segment is the dimension row id (from GET …/dimensions), not the sie_dim_no. Duplicate codes within the dimension return 409 DIMENSION_VALUE_DUPLICATE_CODE.',
+  useWhen:
+    'A voucher or invoice references a cost centre / project code that does not exist yet and the user has confirmed it should be created.',
+  doNotUseFor:
+    'Renaming or archiving an existing value (dashboard register in v1). Tagging lines — pass the dimensions map on the journal-entry line instead.',
+  pitfalls: [
+    'Idempotency-Key is mandatory — calls without it return 400 VALIDATION_ERROR.',
+    'The :id segment is the dimension UUID, not the SIE dimension number.',
+    'Codes are limited to the strict Fortnox charset (A–Ö, digits, _, +, -; max 20 chars) even though historical imported codes may be looser.',
+    'code is immutable after creation — there is no rename in v1; create the correct code and archive the wrong one.',
+  ],
+  example: {
+    request: { code: 'P001', name: 'Villa Almgren tak' },
+    response: {
+      data: {
+        id: '0e9c…',
+        dimension_id: 'a8f1…',
+        code: 'P001',
+        name: 'Villa Almgren tak',
+        is_active: true,
+        start_date: null,
+        end_date: null,
+        created_at: '2026-07-02T12:00:00Z',
+      },
+      meta: { request_id: 'req_…', api_version: '2026-05-12' },
+    },
+  },
+  scope: 'bookkeeping:write',
+  risk: 'low',
+  idempotent: true,
+  reversible: true,
+  dryRunSupported: true,
+  request: { body: CreateDimensionValueSchema },
+  response: { success: dataEnvelope(DimensionValueCreated) },
+})
+
+export const POST = withApiV1<{ params: Promise<{ companyId: string; id: string }> }>(
+  'dimensions.values.create',
+  async (request, ctx, { params }) => {
+    const { id } = await params
+
+    if (!z.string().uuid().safeParse(id).success) {
+      return v1ErrorResponseFromCode('VALIDATION_ERROR', ctx.log, {
+        requestId: ctx.requestId,
+        details: { field: 'id', message: 'Dimension id must be a UUID.' },
+      })
+    }
+
+    let rawBody: unknown
+    try {
+      rawBody = await request.json()
+    } catch {
+      return v1ErrorResponseFromCode('VALIDATION_ERROR', ctx.log, {
+        requestId: ctx.requestId,
+        details: { field: 'body', message: 'Body is not valid JSON.' },
+      })
+    }
+
+    const parsed = CreateDimensionValueSchema.safeParse(rawBody)
+    if (!parsed.success) {
+      return v1ErrorResponseFromCode('VALIDATION_ERROR', ctx.log, {
+        requestId: ctx.requestId,
+        details: {
+          issues: parsed.error.issues.map((i) => ({
+            field: i.path.join('.'),
+            message: i.message,
+          })),
+        },
+      })
+    }
+    const body = parsed.data
+
+    // The dimension must exist and belong to the company in the URL.
+    const { data: dimension, error: dimError } = await ctx.supabase
+      .from('dimensions')
+      .select('id')
+      .eq('id', id)
+      .eq('company_id', ctx.companyId!)
+      .maybeSingle()
+    if (dimError) {
+      return v1ErrorResponse(dimError, ctx.log, { requestId: ctx.requestId })
+    }
+    if (!dimension) {
+      return v1ErrorResponseFromCode('DIMENSION_NOT_FOUND', ctx.log, {
+        requestId: ctx.requestId,
+        details: { dimension_id: id },
+      })
+    }
+
+    if (ctx.dryRun) {
+      return dryRunPreview(
+        {
+          id: null,
+          dimension_id: id,
+          code: body.code,
+          name: body.name,
+          is_active: true,
+          start_date: body.start_date ?? null,
+          end_date: body.end_date ?? null,
+          created_at: null,
+        },
+        { requestId: ctx.requestId, log: ctx.log },
+      )
+    }
+
+    const { data, error } = await ctx.supabase
+      .from('dimension_values')
+      .insert({
+        company_id: ctx.companyId!,
+        dimension_id: id,
+        code: body.code,
+        name: body.name,
+        start_date: body.start_date ?? null,
+        end_date: body.end_date ?? null,
+      })
+      .select('id, dimension_id, code, name, is_active, start_date, end_date, created_at')
+      .single()
+
+    if (error) {
+      if (error.code === '23505') {
+        return v1ErrorResponseFromCode('DIMENSION_VALUE_DUPLICATE_CODE', ctx.log, {
+          requestId: ctx.requestId,
+          details: { code: body.code },
+        })
+      }
+      return v1ErrorResponse(error, ctx.log, { requestId: ctx.requestId })
+    }
+
+    return created(data, { requestId: ctx.requestId })
+  },
+  { requireIdempotencyKey: true },
+)
@@ -0,0 +1,327 @@
+/**
+ * Integration tests for the v1 dimensions surface (dimensions PR2):
+ *   GET  /api/v1/companies/:companyId/dimensions
+ *   POST /api/v1/companies/:companyId/dimensions/:id/values
+ *
+ * Mirrors the suppliers/accounts test pattern: a Proxy-backed Supabase mock
+ * returns whatever the route awaits, keyed by table name (plus an `rpc` key
+ * for ensure_company_dimensions).
+ */
+import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
+
+beforeAll(() => {
+  if (process.env.NODE_ENV !== 'test') throw new Error('NODE_ENV=test required')
+  process.env.NEXT_PUBLIC_SUPABASE_URL ||= 'http://localhost:54321'
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY ||= 'test-anon-key'
+})
+
+vi.mock('@/lib/auth/api-keys', async () => {
+  const actual = await vi.importActual<typeof import('@/lib/auth/api-keys')>('@/lib/auth/api-keys')
+  return { ...actual, validateApiKey: vi.fn(), createServiceClientNoCookies: vi.fn() }
+})
+vi.mock('@supabase/supabase-js', async () => {
+  const actual = await vi.importActual<typeof import('@supabase/supabase-js')>('@supabase/supabase-js')
+  return { ...actual, createClient: vi.fn().mockReturnValue({}) }
+})
+
+import { validateApiKey, createServiceClientNoCookies } from '@/lib/auth/api-keys'
+import { GET as listDimensions } from '../route'
+import { POST as createValue } from '../[id]/values/route'
+
+const mockValidate = validateApiKey as ReturnType<typeof vi.fn>
+const mockServiceClient = createServiceClientNoCookies as ReturnType<typeof vi.fn>
+
+interface TableResp {
+  data?: unknown
+  error?: unknown
+}
+
+/**
+ * Per-table queue mock: TableResp[] consumes one entry per await, then sticks
+ * on the last entry. The special key `rpc` answers `supabase.rpc(...)` calls.
+ */
+function makeFlexibleSupabase(byTable: Record<string, TableResp | TableResp[]>) {
+  const queues = new Map<string, TableResp[]>()
+  for (const [t, val] of Object.entries(byTable)) {
+    queues.set(t, Array.isArray(val) ? [...val] : [val])
+  }
+  const buildChain = (key: string): unknown => {
+    const handler: ProxyHandler<object> = {
+      get(_target, prop) {
+        if (prop === 'then') {
+          return (resolve: (v: unknown) => void) => {
+            const q = queues.get(key)
+            const next = q && q.length > 1 ? q.shift()! : (q?.[0] ?? { data: null, error: null })
+            resolve(next)
+          }
+        }
+        return (..._args: unknown[]) => buildChain(key)
+      },
+    }
+    return new Proxy({}, handler)
+  }
+  return {
+    from: vi.fn((table: string) => buildChain(table)),
+    rpc: vi.fn(() => buildChain('rpc')),
+  }
+}
+
+const COMPANY_ID = 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa'
+const DIMENSION_ID = 'bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb'
+
+function makeRequest(url: string, init?: RequestInit): Request {
+  return new Request(url, {
+    ...init,
+    headers: {
+      Authorization: 'Bearer test-fixture-not-a-real-key',
+      'Idempotency-Key': 'c1aaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+      ...(init?.headers ?? {}),
+    },
+  })
+}
+
+const SAMPLE_DIMS = [
+  {
+    id: DIMENSION_ID,
+    sie_dim_no: 1,
+    name: 'Kostnadsställe',
+    resets_annually: true,
+    is_system: true,
+    is_active: true,
+    sort_order: 10,
+  },
+  {
+    id: 'cccccccc-cccc-4ccc-8ccc-cccccccccccc',
+    sie_dim_no: 6,
+    name: 'Projekt',
+    resets_annually: false,
+    is_system: true,
+    is_active: true,
+    sort_order: 20,
+  },
+]
+
+const SAMPLE_VALUE = {
+  id: 'dddddddd-dddd-4ddd-8ddd-dddddddddddd',
+  dimension_id: DIMENSION_ID,
+  code: 'BUTIK',
+  name: 'Butiken',
+  is_active: true,
+  start_date: null,
+  end_date: null,
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mockValidate.mockResolvedValue({
+    userId: 'user-1',
+    companyId: COMPANY_ID,
+    apiKeyId: 'ak_1',
+    apiKeyName: 'CI key',
+    scopes: ['reports:read', 'bookkeeping:write'],
+    mode: 'live',
+  })
+})
+
+describe('GET /api/v1/companies/:companyId/dimensions', () => {
+  it('ensures system dims and returns the registry with nested values', async () => {
+    const client = makeFlexibleSupabase({
+      company_members: { data: { company_id: COMPANY_ID, role: 'owner' }, error: null },
+      rpc: { data: null, error: null },
+      dimensions: { data: SAMPLE_DIMS, error: null },
+      dimension_values: { data: [SAMPLE_VALUE], error: null },
+    })
+    mockServiceClient.mockReturnValue(client)
+
+    const res = await listDimensions(
+      makeRequest(`https://x.test/api/v1/companies/${COMPANY_ID}/dimensions`),
+      { params: Promise.resolve({ companyId: COMPANY_ID }) },
+    )
+
+    expect(res.status).toBe(200)
+    expect(client.rpc).toHaveBeenCalledWith('ensure_company_dimensions', {
+      p_company_id: COMPANY_ID,
+    })
+    const body = await res.json()
+    expect(body.data.dimensions).toHaveLength(2)
+    expect(body.data.dimensions[0].sie_dim_no).toBe(1)
+    expect(body.data.dimensions[0].values).toEqual([
+      {
+        id: SAMPLE_VALUE.id,
+        code: 'BUTIK',
+        name: 'Butiken',
+        is_active: true,
+        start_date: null,
+        end_date: null,
+      },
+    ])
+    expect(body.data.dimensions[1].values).toEqual([])
+  })
+
+  it('rejects keys without reports:read scope (403)', async () => {
+    mockValidate.mockResolvedValue({
+      userId: 'user-1',
+      companyId: COMPANY_ID,
+      scopes: ['invoices:read'],
+      mode: 'live',
+    })
+    mockServiceClient.mockReturnValue(makeFlexibleSupabase({}))
+
+    const res = await listDimensions(
+      makeRequest(`https://x.test/api/v1/companies/${COMPANY_ID}/dimensions`),
+      { params: Promise.resolve({ companyId: COMPANY_ID }) },
+    )
+
+    expect(res.status).toBe(403)
+  })
+})
+
+describe('POST /api/v1/companies/:companyId/dimensions/:id/values', () => {
+  const url = `https://x.test/api/v1/companies/${COMPANY_ID}/dimensions/${DIMENSION_ID}/values`
+  const detailParams = { params: Promise.resolve({ companyId: COMPANY_ID, id: DIMENSION_ID }) }
+
+  it('creates a value (201, happy path)', async () => {
+    mockServiceClient.mockReturnValue(
+      makeFlexibleSupabase({
+        company_members: { data: { company_id: COMPANY_ID, role: 'owner' }, error: null },
+        dimensions: { data: { id: DIMENSION_ID }, error: null },
+        dimension_values: { data: { ...SAMPLE_VALUE, created_at: '2026-07-02T12:00:00Z' }, error: null },
+        idempotency_keys: { data: null, error: null },
+      }),
+    )
+
+    const res = await createValue(
+      makeRequest(url, {
+        method: 'POST',
+        body: JSON.stringify({ code: 'BUTIK', name: 'Butiken' }),
+      }),
+      detailParams,
+    )
+
+    expect(res.status).toBe(201)
+    const body = await res.json()
+    expect(body.data.code).toBe('BUTIK')
+  })
+
+  it('returns 400 when Idempotency-Key is missing', async () => {
+    mockServiceClient.mockReturnValue(
+      makeFlexibleSupabase({
+        company_members: { data: { company_id: COMPANY_ID, role: 'owner' }, error: null },
+      }),
+    )
+
+    const req = new Request(url, {
+      method: 'POST',
+      headers: { Authorization: 'Bearer test' },
+      body: JSON.stringify({ code: 'BUTIK', name: 'Butiken' }),
+    })
+    const res = await createValue(req, detailParams)
+
+    expect(res.status).toBe(400)
+  })
+
+  it('rejects a non-Fortnox code with 400 VALIDATION_ERROR', async () => {
+    mockServiceClient.mockReturnValue(
+      makeFlexibleSupabase({
+        company_members: { data: { company_id: COMPANY_ID, role: 'owner' }, error: null },
+        idempotency_keys: { data: null, error: null },
+      }),
+    )
+
+    const res = await createValue(
+      makeRequest(url, {
+        method: 'POST',
+        body: JSON.stringify({ code: 'BAD CODE!', name: 'x' }),
+      }),
+      detailParams,
+    )
+
+    expect(res.status).toBe(400)
+    const body = await res.json()
+    expect(body.error.code).toBe('VALIDATION_ERROR')
+  })
+
+  it('returns 404 DIMENSION_NOT_FOUND for a dimension outside the company', async () => {
+    mockServiceClient.mockReturnValue(
+      makeFlexibleSupabase({
+        company_members: { data: { company_id: COMPANY_ID, role: 'owner' }, error: null },
+        dimensions: { data: null, error: null },
+        idempotency_keys: { data: null, error: null },
+      }),
+    )
+
+    const res = await createValue(
+      makeRequest(url, {
+        method: 'POST',
+        body: JSON.stringify({ code: 'BUTIK', name: 'Butiken' }),
+      }),
+      detailParams,
+    )
+
+    expect(res.status).toBe(404)
+    const body = await res.json()
+    expect(body.error.code).toBe('DIMENSION_NOT_FOUND')
+  })
+
+  it('returns 409 DIMENSION_VALUE_DUPLICATE_CODE on a 23505', async () => {
+    mockServiceClient.mockReturnValue(
+      makeFlexibleSupabase({
+        company_members: { data: { company_id: COMPANY_ID, role: 'owner' }, error: null },
+        dimensions: { data: { id: DIMENSION_ID }, error: null },
+        dimension_values: { data: null, error: { code: '23505', message: 'duplicate' } },
+        idempotency_keys: { data: null, error: null },
+      }),
+    )
+
+    const res = await createValue(
+      makeRequest(url, {
+        method: 'POST',
+        body: JSON.stringify({ code: 'BUTIK', name: 'Butiken' }),
+      }),
+      detailParams,
+    )
+
+    expect(res.status).toBe(409)
+    const body = await res.json()
+    expect(body.error.code).toBe('DIMENSION_VALUE_DUPLICATE_CODE')
+  })
+
+  it('returns a dry-run preview without inserting when ?dry_run=true', async () => {
+    const fromSpy = vi.fn()
+    mockServiceClient.mockReturnValue({
+      from: (table: string) => {
+        fromSpy(table)
+        return new Proxy({}, {
+          get(_t, prop) {
+            if (prop === 'then') {
+              const data =
+                table === 'company_members'
+                  ? { company_id: COMPANY_ID, role: 'owner' }
+                  : table === 'dimensions'
+                    ? { id: DIMENSION_ID }
+                    : null
+              return (resolve: (v: unknown) => void) => resolve({ data, error: null })
+            }
+            return () => new Proxy({}, this!)
+          },
+        })
+      },
+      rpc: vi.fn(),
+    })
+
+    const res = await createValue(
+      makeRequest(`${url}?dry_run=true`, {
+        method: 'POST',
+        body: JSON.stringify({ code: 'P001', name: 'Villa Almgren tak' }),
+      }),
+      detailParams,
+    )
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('X-Dry-Run')).toBe('true')
+    expect(fromSpy).not.toHaveBeenCalledWith('dimension_values')
+    const body = await res.json()
+    expect(body.data.dry_run).toBe(true)
+    expect(body.data.preview.code).toBe('P001')
+  })
+})
@@ -0,0 +1,149 @@
+/**
+ * GET /api/v1/companies/{companyId}/dimensions
+ *
+ * List the dimension registry (SIE #DIM) with nested values (#OBJEKT).
+ * Ensures the system dims (1 = Kostnadsställe, 6 = Projekt) exist via the
+ * ensure_company_dimensions RPC before reading — lazy seeding, so the list is
+ * never empty even for companies that have not touched dimensions.
+ */
+import { z } from 'zod'
+import { ok } from '@/lib/api/v1/response'
+import { registerEndpoint, dataEnvelope } from '@/lib/api/v1/registry'
+import { withApiV1 } from '@/lib/api/v1/with-api-v1'
+import { v1ErrorResponse } from '@/lib/api/v1/errors'
+
+const DimensionValue = z.object({
+  id: z.string().uuid(),
+  code: z.string(),
+  name: z.string(),
+  is_active: z.boolean(),
+  start_date: z.string().nullable(),
+  end_date: z.string().nullable(),
+})
+
+const Dimension = z.object({
+  id: z.string().uuid(),
+  sie_dim_no: z.number().int().min(1),
+  name: z.string(),
+  resets_annually: z.boolean(),
+  is_system: z.boolean(),
+  is_active: z.boolean(),
+  sort_order: z.number().int(),
+  values: z.array(DimensionValue),
+})
+
+const DimensionsResponse = dataEnvelope(z.object({ dimensions: z.array(Dimension) }))
+
+registerEndpoint({
+  operation: 'dimensions.list',
+  method: 'GET',
+  path: '/api/v1/companies/:companyId/dimensions',
+  summary: 'List dimensions (kostnadsställe/projekt) with their values.',
+  description:
+    'Returns the company\'s dimension registry — SIE #DIM entries keyed by sie_dim_no (1 = Kostnadsställe, 6 = Projekt; both always exist) — with the registered values (#OBJEKT) nested under each dimension. Dimensions are ordered by sort_order, values by code. Line-level tags on journal entries reference these values as {"<sie_dim_no>":"<code>"} in the `dimensions` map.',
+  useWhen:
+    'You need the valid dimension value codes before tagging journal-entry lines with a cost centre or project, or you are rendering a dimension picker.',
+  doNotUseFor:
+    'Filtering reports (pass the dimension filter to the report endpoints once available) or reading which lines carry a tag (read the journal entries themselves).',
+  pitfalls: [
+    'Dimension value codes are STRINGS and case-sensitive — "P001", not 1.',
+    'sie_dim_no is the key used in journal_entry_lines.dimensions, NOT the dimension row id.',
+    'is_active=false values are historical (archived) — do not tag new lines with them.',
+    'resets_annually=true (dim 1) means balances reset each fiscal year; dim 6 (projekt) accumulates across years.',
+  ],
+  example: {
+    response: {
+      data: {
+        dimensions: [
+          {
+            id: '0e9c…',
+            sie_dim_no: 1,
+            name: 'Kostnadsställe',
+            resets_annually: true,
+            is_system: true,
+            is_active: true,
+            sort_order: 10,
+            values: [
+              {
+                id: 'a8f1…',
+                code: 'BUTIK',
+                name: 'Butiken',
+                is_active: true,
+                start_date: null,
+                end_date: null,
+              },
+            ],
+          },
+        ],
+      },
+      meta: { request_id: 'req_…', api_version: '2026-05-12' },
+    },
+  },
+  scope: 'reports:read',
+  risk: 'low',
+  idempotent: true,
+  reversible: false,
+  dryRunSupported: false,
+  response: { success: DimensionsResponse },
+})
+
+interface DimensionValueRow {
+  id: string
+  dimension_id: string
+  code: string
+  name: string
+  is_active: boolean
+  start_date: string | null
+  end_date: string | null
+}
+
+export const GET = withApiV1<{ params: Promise<{ companyId: string }> }>(
+  'dimensions.list',
+  async (_request, ctx) => {
+    const { error: ensureError } = await ctx.supabase.rpc('ensure_company_dimensions', {
+      p_company_id: ctx.companyId!,
+    })
+    if (ensureError) {
+      return v1ErrorResponse(ensureError, ctx.log, { requestId: ctx.requestId })
+    }
+
+    const { data: dims, error: dimsError } = await ctx.supabase
+      .from('dimensions')
+      .select('id, sie_dim_no, name, resets_annually, is_system, is_active, sort_order')
+      .eq('company_id', ctx.companyId!)
+      .order('sort_order', { ascending: true })
+      .order('sie_dim_no', { ascending: true })
+    if (dimsError) {
+      return v1ErrorResponse(dimsError, ctx.log, { requestId: ctx.requestId })
+    }
+
+    const { data: values, error: valuesError } = await ctx.supabase
+      .from('dimension_values')
+      .select('id, dimension_id, code, name, is_active, start_date, end_date')
+      .eq('company_id', ctx.companyId!)
+      .order('code', { ascending: true })
+    if (valuesError) {
+      return v1ErrorResponse(valuesError, ctx.log, { requestId: ctx.requestId })
+    }
+
+    const valuesByDimension = new Map<string, Omit<DimensionValueRow, 'dimension_id'>[]>()
+    for (const v of ((values ?? []) as DimensionValueRow[])) {
+      const bucket = valuesByDimension.get(v.dimension_id) ?? []
+      bucket.push({
+        id: v.id,
+        code: v.code,
+        name: v.name,
+        is_active: v.is_active,
+        start_date: v.start_date,
+        end_date: v.end_date,
+      })
+      valuesByDimension.set(v.dimension_id, bucket)
+    }
+
+    const dimensions = ((dims ?? []) as Array<Record<string, unknown> & { id: string }>).map(
+      (d) => ({ ...d, values: valuesByDimension.get(d.id) ?? [] }),
+    )
+
+    return ok({ dimensions }, { requestId: ctx.requestId })
+  },
+)