feat(ai): Phase 1 — provider configuration, installer step, admin + company settings

Foundation for the AI chatbot + text generation feature. Phase 1 is infrastructure only: driver plumbing, configuration storage with encrypted API keys, global vs per-company resolution, admin + company UI pages, and an optional installer wizard step. The chat assistant and text-generation WYSIWYG integration come in later phases.

**Driver plumbing (app/Support/Ai/)** — AiDriver abstract, AiDriverFactory, AiException, AiChatResponse DTO, OpenRouterDriver concrete implementation. OpenRouter is the OpenAI-compatible aggregator that unlocks hundreds of models behind one API key and one request shape — ideal as the default v1 driver. Drivers are extensible the same way exchange rate drivers are: the module Registry's generic registerDriver('ai', ...) machinery plus a typed Registry::registerAiDriver() convenience wrapper (shipped in the upstream invoiceshelf/modules package in a paired commit).

**AiConfigurationService** — mirrors MailConfigurationService shape but with one deliberate deviation: API keys are encrypted at the service layer via Crypt::encryptString before persistence. OpenRouter bearer tokens have much bigger blast radius than SMTP passwords. Same settings / company_settings tables, same global-vs-per-company pattern, same use_custom_ai_config override toggle. Resolution order: global ai_enabled must be YES, then the company either overrides via use_custom_ai_config=YES (and can opt out with ai_enabled=NO inside the override) or inherits the global config.

**Controllers** — Admin/Settings/AiConfigurationController (global CRUD + driver list + test connection), Company/Settings/CompanyAiConfigurationController (per-company override + test), Setup/AiConfigurationController (installer wizard step, skippable with explicit ai_enabled=NO). API key is always masked as '********' in GET responses — the frontend submits the placeholder back on save and the backend preserves the stored value.

**Installer wizard** — new optional step 7 'AI' between Mail and Account. Default OFF with a Skip button. MailView.vue now routes to installation.ai instead of installation.account; installation.ai then routes to installation.account. Step order comment updated in routes.ts.

**Admin + Company settings pages** — AdminAiConfigView (no toggle, always global) and AiConfigView (with use_custom_ai_config BaseSwitchSection that auto-saves OFF). Both share AiConfigurationForm which renders the driver selector, API key input with show/hide, driver-specific config_fields (base_url for OpenRouter), and per-role enable toggles with free-text model inputs backed by a datalist of suggested models from driver metadata.

**Bootstrap endpoint** — adds an ai block to the response: { enabled, chat_enabled, text_generation_enabled }. All three are booleans resolved through AiConfigurationService::resolveForCompany(). Never leaks the API key. Frontend feature flags read from bootstrapData.ai to decide whether to show Phase 2/3 UI.

**Bouncer ability** 'manage ai config' added to SettingsPolicy, gated on isSuperAdmin() (same pattern as manage email config, manage pdf config).

**Tests** (22 new) — Unit: AiDriverFactory resolves built-in + Registry-contributed drivers, rejects unknown, merges availableDrivers. AiConfigurationService: encryption round-trip, resolution order (3 cases: global off, inherit global, override with company key, override with opt-out), makeDriver null/instance cases, listDrivers metadata. Feature: admin save + read with api key masking, preserve-on-placeholder behavior, company toggle ON/OFF semantics, bootstrap ai flags reflect resolution, company opt-out path.

372 tests pass (was 350, +22). Pint clean. npm run build clean. Phase 2 (chat assistant + tool calling) and Phase 3 (WYSIWYG text generation popup) are separate follow-up commits — this one is the foundation only.

resources/scripts/features/admin/views/AdminSettingsView.vue

@@ -73,6 +73,11 @@ const menuItems = computed<SettingsMenuItem[]>(() => [
     link: '/admin/administration/settings/mail-configuration',
     icon: 'EnvelopeIcon',
   },
+  {
+    title: t('settings.menu_title.ai_configuration'),
+    link: '/admin/administration/settings/ai-configuration',
+    icon: 'SparklesIcon',
+  },
   {
     title: t('settings.menu_title.pdf_generation'),
     link: '/admin/administration/settings/pdf-generation',

resources/scripts/features/admin/views/settings/AdminAiConfigView.vue

@@ -0,0 +1,107 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { useNotificationStore } from '@/scripts/stores/notification.store'
+import { aiService } from '@/scripts/api/services/ai.service'
+import type { AiConfig, AiDriverOption, AiTestPayload } from '@/scripts/types/ai-config'
+import { getErrorTranslationKey, handleApiError } from '@/scripts/utils/error-handling'
+import AiConfigurationForm from '@/scripts/features/company/settings/components/AiConfigurationForm.vue'
+
+const { t } = useI18n()
+const notificationStore = useNotificationStore()
+
+const isSaving = ref(false)
+const isTesting = ref(false)
+const isFetchingInitialData = ref(false)
+const configData = ref<AiConfig | null>(null)
+const drivers = ref<AiDriverOption[]>([])
+
+loadData()
+
+async function loadData(): Promise<void> {
+  isFetchingInitialData.value = true
+  try {
+    const [driversResponse, configResponse] = await Promise.all([
+      aiService.getDrivers(),
+      aiService.getGlobalConfig(),
+    ])
+    drivers.value = driversResponse.ai_drivers
+    configData.value = configResponse
+  } catch (error: unknown) {
+    const normalizedError = handleApiError(error)
+    notificationStore.showNotification({
+      type: 'error',
+      message: getErrorTranslationKey(normalizedError.message) ?? normalizedError.message,
+    })
+  } finally {
+    isFetchingInitialData.value = false
+  }
+}
+
+async function saveConfig(value: AiConfig): Promise<void> {
+  isSaving.value = true
+  try {
+    const response = await aiService.saveGlobalConfig(value)
+    if (response.success) {
+      notificationStore.showNotification({
+        type: 'success',
+        message: 'settings.ai.saved',
+      })
+      configData.value = { ...value }
+    }
+  } catch (error: unknown) {
+    const normalizedError = handleApiError(error)
+    notificationStore.showNotification({
+      type: 'error',
+      message: getErrorTranslationKey(normalizedError.message) ?? normalizedError.message,
+    })
+  } finally {
+    isSaving.value = false
+  }
+}
+
+async function testConnection(payload: AiTestPayload): Promise<void> {
+  isTesting.value = true
+  try {
+    const response = await aiService.testGlobalConnection(payload)
+    if (response.success) {
+      notificationStore.showNotification({
+        type: 'success',
+        message: 'settings.ai.test_success',
+      })
+    } else if (response.error) {
+      notificationStore.showNotification({
+        type: 'error',
+        message: t('settings.ai.errors.' + response.error, { error: response.message ?? '' }),
+      })
+    }
+  } catch (error: unknown) {
+    const normalizedError = handleApiError(error)
+    notificationStore.showNotification({
+      type: 'error',
+      message: getErrorTranslationKey(normalizedError.message) ?? normalizedError.message,
+    })
+  } finally {
+    isTesting.value = false
+  }
+}
+</script>
+
+<template>
+  <BaseSettingCard
+    :title="$t('settings.ai.title')"
+    :description="$t('settings.ai.description')"
+  >
+    <div v-if="configData" class="mt-14">
+      <AiConfigurationForm
+        :config-data="configData"
+        :drivers="drivers"
+        :is-saving="isSaving"
+        :is-testing="isTesting"
+        :is-fetching-initial-data="isFetchingInitialData"
+        @submit-data="saveConfig"
+        @test-connection="testConnection"
+      />
+    </div>
+  </BaseSettingCard>
+</template>