feat(front) : page répertoire clients + datatable

- Page /clients (route à plat) : MalioDataTable 6 colonnes (contact, téléphone
  formaté, codes catégories, badges sites), toggle « Voir les archivés » (état
  local), boutons Ajouter (manage) / Exporter (view, download xlsx), clic ligne
  vers le détail, empty state.
- Composable useClientsRepository (wrapper de usePaginatedList) + util
  formatPhoneFR + clé i18n showArchived.
- Contrat back : la liste client:read expose désormais les codes catégories
  (category:read) et les sites agrégés des adresses (site:read + Client::getSites) ;
  jointures anti N+1 dans createListQueryBuilder. Tests back + front.

frontend/modules/commercial/composables/__tests__/useClientsRepository.spec.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import type { HydraCollection } from '~/shared/utils/api'
+import type { Client } from '../useClientsRepository'
+
+// `useApi` est un auto-import Nuxt : on le stubbe globalement pour intercepter
+// les appels declenches par usePaginatedList (que useClientsRepository enveloppe)
+// et controler les reponses. Meme pattern que useCategoriesAdmin.spec.ts.
+const mockGet = vi.hoisted(() => vi.fn())
+vi.stubGlobal('useApi', () => ({
+    get: mockGet,
+    post: vi.fn(),
+    put: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+}))
+
+// Import APRES le stub pour que useApi soit bien resolu au top-level du module.
+const { useClientsRepository } = await import('../useClientsRepository')
+
+/** Envelope Hydra minimale (la liste reelle des membres importe peu ici). */
+function makeHydra(total: number): HydraCollection<Client> {
+    return { totalItems: total, member: [] }
+}
+
+describe('useClientsRepository', () => {
+    beforeEach(() => {
+        mockGet.mockReset()
+        // 25 items → 3 pages a 10/page : permet de tester la navigation page 2.
+        mockGet.mockResolvedValue(makeHydra(25))
+    })
+
+    it('charge /clients sans includeArchived par defaut (clients actifs)', async () => {
+        const repo = useClientsRepository()
+        await repo.fetch()
+
+        expect(repo.includeArchived.value).toBe(false)
+        expect(mockGet).toHaveBeenLastCalledWith(
+            '/clients',
+            { page: 1, itemsPerPage: 10 },
+            expect.objectContaining({ toast: false }),
+        )
+    })
+
+    it('pousse le filtre serveur includeArchived=true quand le toggle est actif', async () => {
+        const repo = useClientsRepository()
+        await repo.fetch()
+        await repo.setIncludeArchived(true)
+
+        expect(repo.includeArchived.value).toBe(true)
+        expect(mockGet).toHaveBeenLastCalledWith(
+            '/clients',
+            { includeArchived: true, page: 1, itemsPerPage: 10 },
+            expect.objectContaining({ toast: false }),
+        )
+    })
+
+    it('retombe en page 1 lorsqu on bascule le toggle archives', async () => {
+        const repo = useClientsRepository()
+        await repo.fetch()
+        await repo.goToPage(2)
+        expect(repo.currentPage.value).toBe(2)
+
+        await repo.setIncludeArchived(true)
+        expect(repo.currentPage.value).toBe(1)
+    })
+
+    it('retire le filtre (query propre) quand le toggle repasse a false', async () => {
+        const repo = useClientsRepository()
+        await repo.setIncludeArchived(true)
+        await repo.setIncludeArchived(false)
+
+        expect(repo.includeArchived.value).toBe(false)
+        expect(mockGet).toHaveBeenLastCalledWith(
+            '/clients',
+            { page: 1, itemsPerPage: 10 },
+            expect.objectContaining({ toast: false }),
+        )
+    })
+})

frontend/modules/commercial/composables/useClientsRepository.ts

@@ -0,0 +1,82 @@
+import { ref } from 'vue'
+import { usePaginatedList } from '~/shared/composables/usePaginatedList'
+
+/**
+ * Site Starseed rattache a une adresse du client, tel qu'embarque en LISTE
+ * (groupe site:read) pour la colonne « Site(s) » du Repertoire (badges colores).
+ */
+export interface ClientSite {
+    id: number
+    name: string
+    color: string
+}
+
+/**
+ * Categorie rattachee au client, embarquee en LISTE (groupe category:read).
+ * Seul le `code` (stable, MAJUSCULE — ERP-78) est affiche dans la colonne
+ * « Catégories ». Les autres champs sont presents mais non utilises ici.
+ */
+export interface ClientCategory {
+    code: string
+    name?: string
+}
+
+/**
+ * Vue MINIMALE d'un client pour le Repertoire (datatable). Volontairement
+ * partielle : seuls les champs des colonnes + l'id (navigation) sont types ici.
+ * Le detail complet (onglets) est hors perimetre de cet ecran (ERP-62).
+ */
+export interface Client {
+    id: number
+    companyName: string
+    firstName: string | null
+    lastName: string | null
+    phonePrimary: string | null
+    email: string | null
+    categories: ClientCategory[]
+    sites: ClientSite[]
+    isArchived: boolean
+}
+
+/**
+ * Repertoire clients (ERP-62) — simple enveloppe de `usePaginatedList<Client>`
+ * sur la ressource `/clients` (RG-13 : pagination serveur obligatoire ; jamais
+ * de chargement integral en memoire).
+ *
+ * N'ajoute qu'un seul comportement metier : le toggle « Voir les archivés ».
+ * Desactive par defaut (la liste n'expose que les clients actifs — RG-1.24).
+ * Active, il pousse le filtre serveur `?includeArchived=true` (consomme par le
+ * ClientProvider, RG-1.25) et — garantie de `usePaginatedList` — retombe en
+ * page 1.
+ *
+ * Volontairement PAR INSTANCE (pas de singleton module-level) : l'etat tableau
+ * est propre a l'ecran Repertoire et meurt avec lui, comme tout consommateur de
+ * `usePaginatedList` (cf. sites.vue / categories.vue). Aucun reset au logout a
+ * gerer.
+ */
+export function useClientsRepository() {
+    // Etat local du toggle « Voir les archivés » — JAMAIS reflete dans l'URL
+    // (regle ABSOLUE n°6).
+    const includeArchived = ref(false)
+
+    const list = usePaginatedList<Client>({ url: '/clients' })
+
+    /**
+     * Bascule l'inclusion des clients archives et relance la liste. La remise
+     * en page 1 est assuree par `setFilters` (usePaginatedList). Quand le toggle
+     * repasse a false, on RETIRE le filtre (valeur `undefined`) plutot que
+     * d'envoyer `includeArchived=false`, pour une query propre.
+     */
+    async function setIncludeArchived(value: boolean): Promise<void> {
+        includeArchived.value = value
+        await list.setFilters(
+            value ? { includeArchived: true } : { includeArchived: undefined },
+        )
+    }
+
+    return {
+        ...list,
+        includeArchived,
+        setIncludeArchived,
+    }
+}

frontend/modules/commercial/pages/clients/index.vue

@@ -0,0 +1,211 @@
+<template>
+    <div>
+        <PageHeader>
+            {{ t('commercial.clients.title') }}
+            <template #actions>
+                <MalioButton
+                    v-if="canView"
+                    variant="secondary"
+                    :label="t('commercial.clients.export')"
+                    icon-name="mdi:file-export-outline"
+                    icon-position="left"
+                    :disabled="exporting"
+                    @click="exportXlsx"
+                />
+                <MalioButton
+                    v-if="canManage"
+                    :label="t('commercial.clients.add')"
+                    icon-name="mdi:add-bold"
+                    icon-position="left"
+                    @click="goToCreate"
+                />
+            </template>
+        </PageHeader>
+
+        <!-- Toggle « Voir les archivés » : etat 100 % local (regle ABSOLUE n°6),
+             desactive par defaut (clients actifs uniquement). -->
+        <div class="mb-4">
+            <MalioCheckbox
+                id="clients-include-archived"
+                :label="t('commercial.clients.showArchived')"
+                :model-value="includeArchived"
+                @update:model-value="onToggleArchived"
+            />
+        </div>
+
+        <!-- Datatable branchee sur usePaginatedList via useClientsRepository :
+             pagination serveur, tri companyName ASC par defaut (cote back). -->
+        <MalioDataTable
+            :columns="columns"
+            :items="rows"
+            :total-items="totalItems"
+            :page="currentPage"
+            :per-page="itemsPerPage"
+            :per-page-options="itemsPerPageOptions"
+            row-clickable
+            :empty-message="t('commercial.clients.empty')"
+            @row-click="onRowClick"
+            @update:page="goToPage"
+            @update:per-page="setItemsPerPage"
+        >
+            <!-- Contact principal : prenom + nom (l'un des deux peut etre vide). -->
+            <template #cell-contact="{ item }">
+                {{ formatContact(item) }}
+            </template>
+
+            <!-- Telephone principal formate XX XX XX XX XX (ERP-66). -->
+            <template #cell-phone="{ item }">
+                {{ formatPhoneFR(item.phonePrimary as string | null) }}
+            </template>
+
+            <!-- Categories : codes stables separes par une virgule (ERP-78). -->
+            <template #cell-categories="{ item }">
+                {{ formatCategories(item) }}
+            </template>
+
+            <!-- Sites : badges colores (name + color), agreges des adresses. -->
+            <template #cell-sites="{ item }">
+                <span class="flex flex-wrap gap-1">
+                    <span
+                        v-for="site in (item.sites as ClientSite[])"
+                        :key="site.id"
+                        class="inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium text-white"
+                        :style="{ backgroundColor: site.color }"
+                    >
+                        {{ site.name }}
+                    </span>
+                </span>
+            </template>
+        </MalioDataTable>
+    </div>
+</template>
+
+<script setup lang="ts">
+import type { Client, ClientSite } from '~/modules/commercial/composables/useClientsRepository'
+
+const { t } = useI18n()
+const api = useApi()
+const router = useRouter()
+const toast = useToast()
+const { can } = usePermissions()
+
+useHead({ title: t('commercial.clients.title') })
+
+// Bouton « + Ajouter » reserve a `manage` (POST /clients garde manage seul →
+// Compta / Usine ne creent pas). « Exporter » suit `view`.
+const canManage = computed(() => can('commercial.clients.manage'))
+const canView = computed(() => can('commercial.clients.view'))
+
+const {
+    items: clients,
+    totalItems,
+    currentPage,
+    itemsPerPage,
+    itemsPerPageOptions,
+    includeArchived,
+    fetch: loadClients,
+    goToPage,
+    setItemsPerPage,
+    setIncludeArchived,
+} = useClientsRepository()
+
+// Mappe les clients en objets « plats » pour MalioDataTable (items typees
+// Record<string, unknown>[]) : un objet litteral porte une signature d'index
+// implicite, contrairement a l'interface Client. Meme pattern que sites.vue.
+const rows = computed(() => clients.value.map(client => ({
+    id: client.id,
+    companyName: client.companyName,
+    firstName: client.firstName,
+    lastName: client.lastName,
+    phonePrimary: client.phonePrimary,
+    email: client.email,
+    categories: client.categories,
+    sites: client.sites,
+})))
+
+const columns = [
+    { key: 'companyName', label: t('commercial.clients.column.companyName') },
+    { key: 'contact', label: t('commercial.clients.column.contact') },
+    { key: 'phone', label: t('commercial.clients.column.phone') },
+    { key: 'email', label: t('commercial.clients.column.email') },
+    { key: 'categories', label: t('commercial.clients.column.categories') },
+    { key: 'sites', label: t('commercial.clients.column.sites') },
+]
+
+/** Contact principal : « Prenom Nom » en ignorant les parties vides. */
+function formatContact(item: Record<string, unknown>): string {
+    return [item.firstName, item.lastName].filter(Boolean).join(' ')
+}
+
+/** Codes des categories du client, separes par une virgule (ERP-78). */
+function formatCategories(item: Record<string, unknown>): string {
+    const categories = (item.categories as Client['categories']) ?? []
+    return categories.map(c => c.code).join(', ')
+}
+
+/** Clic sur une ligne → ecran Consultation (route a plat /clients/{id}). */
+function onRowClick(item: Record<string, unknown>): void {
+    router.push(`/clients/${item.id}`)
+}
+
+function goToCreate(): void {
+    router.push('/clients/new')
+}
+
+function onToggleArchived(value: boolean): void {
+    setIncludeArchived(value)
+}
+
+// Export XLSX : memes filtres que la vue (includeArchived). La colonne SIREN
+// n'est dans le fichier que si l'utilisateur a accounting.view (gere cote back).
+const exporting = ref(false)
+
+async function exportXlsx(): Promise<void> {
+    if (exporting.value) {
+        return
+    }
+    exporting.value = true
+    try {
+        const query: Record<string, unknown> = {}
+        if (includeArchived.value) {
+            query.includeArchived = true
+        }
+
+        // useApi type ses options en JSON ; l'export renvoie un binaire, donc on
+        // force responseType:'blob' (transmis tel quel a ofetch au runtime). Cast
+        // contenu faute d'overload blob sur le client partage — a generaliser via
+        // un ticket dedie si d'autres exports binaires arrivent.
+        const blob = await api.get<Blob>('/clients/export.xlsx', query, {
+            responseType: 'blob',
+            toast: false,
+        } as unknown as Parameters<typeof api.get>[2])
+
+        triggerDownload(blob, 'repertoire-clients.xlsx')
+    }
+    catch {
+        toast.error({
+            title: t('commercial.clients.toast.error'),
+            message: t('commercial.clients.toast.error'),
+        })
+    }
+    finally {
+        exporting.value = false
+    }
+}
+
+/** Declenche le telechargement d'un blob via un lien temporaire. */
+function triggerDownload(blob: Blob, filename: string): void {
+    const url = URL.createObjectURL(blob)
+    const link = document.createElement('a')
+    link.href = url
+    link.download = filename
+    document.body.appendChild(link)
+    link.click()
+    link.remove()
+    URL.revokeObjectURL(url)
+}
+
+onMounted(() => {
+    loadClients()
+})
+</script>