From e4fc34b90fa7604109851c3af2f431cfc713fb34 Mon Sep 17 00:00:00 2001
From: matthieu <matthieu@yuno.malio.fr>
Date: Sun, 15 Mar 2026 22:09:16 +0100
Subject: [PATCH] refactor : simplify codebase and fix critical issues

Backend:
- Add MCP Serializer to centralize entity-to-array conversion (~300 lines deduped)
- Fix race condition in task/ticket number generation (SELECT FOR UPDATE + transaction)
- Add unique constraint on task (project_id, number) with migration
- Fix MIME type validation: use server-detected finfo instead of client-supplied type
- Add allowlist of permitted MIME types for uploads
- Fix TaskDocumentDownloadController: allow ROLE_CLIENT access, add priority:1
- Fix notification sent even when ticket status unchanged
- Remove redundant exception constructors
- Simplify services (BookStackApi double fetch, TokenEncryptor, GiteaApi)
- Consolidate duplicate checks in processors

Frontend:
- Fix useApi isHandlingUnauthorized scope (module-level to prevent double 401 redirect)
- Fix client-tickets toast key copy-paste bug
- Merge duplicated tasks service methods (getByProject + getByProjectArchived)
- Extract shared uploadWithRelation helper in task-documents service
- Extract formatFileSize utility from duplicated component code
- Extract status transition logic into useClientTicketHelpers composable
- Remove dead code (unused router, handleLogout, empty script blocks)
- Merge duplicate watchers and onMounted calls
- Normalize arrow functions to function declarations per convention

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../components/admin/AdminBookStackTab.vue    |  16 +-
 .../client-ticket/ProjectClientTickets.vue    |  15 +-
 .../components/project/ProjectGroupTab.vue    |   2 +-
 frontend/components/task/TaskDocumentList.vue |   8 +-
 .../components/task/TaskDocumentPreview.vue   |   9 +-
 frontend/components/task/TaskModal.vue        |  32 +-
 frontend/composables/useApi.ts                |  11 +-
 frontend/composables/useAppVersion.ts         |   4 +-
 .../composables/useClientTicketHelpers.ts     |  21 +-
 frontend/layouts/auth.vue                     |   4 -
 frontend/layouts/default.vue                  |   5 -
 frontend/pages/login.vue                      |   5 +-
 frontend/pages/time-tracking.vue              |  23 +-
 frontend/services/auth.ts                     |  30 +-
 frontend/services/client-tickets.ts           |   2 +-
 frontend/services/task-documents.ts           |  22 +-
 frontend/services/tasks.ts                    |  14 +-
 frontend/stores/timer.ts                      |  13 +-
 frontend/utils/format.ts                      |   5 +
 migrations/Version20260315210619.php          |  31 ++
 .../TaskDocumentDownloadController.php        |  15 +-
 src/Entity/Task.php                           |   2 +
 src/Exception/BookStackApiException.php       |   9 +-
 src/Exception/GiteaApiException.php           |   9 +-
 src/Mcp/Tool/Project/CreateProjectTool.php    |  14 +-
 src/Mcp/Tool/Project/GetProjectTool.php       |  13 +-
 src/Mcp/Tool/Project/ListProjectsTool.php     |  14 +-
 src/Mcp/Tool/Project/UpdateProjectTool.php    |  14 +-
 src/Mcp/Tool/Serializer.php                   | 277 ++++++++++++++++++
 src/Mcp/Tool/Task/CreateTaskTool.php          |  41 +--
 src/Mcp/Tool/Task/GetTaskTool.php             |  56 +---
 src/Mcp/Tool/Task/ListTasksTool.php           |  45 +--
 src/Mcp/Tool/Task/UpdateTaskTool.php          |  41 +--
 src/Mcp/Tool/TaskMeta/CreateGroupTool.php     |  14 +-
 src/Mcp/Tool/TaskMeta/ListGroupsTool.php      |  14 +-
 src/Mcp/Tool/TaskMeta/UpdateGroupTool.php     |  14 +-
 .../Tool/TimeEntry/CreateTimeEntryTool.php    |  27 +-
 .../Tool/TimeEntry/ListTimeEntriesTool.php    |  30 +-
 .../Tool/TimeEntry/UpdateTimeEntryTool.php    |  26 +-
 src/Repository/ClientTicketRepository.php     |  19 +-
 src/Repository/TaskRepository.php             |  24 +-
 src/Service/BookStackApiService.php           |  44 +--
 src/Service/GiteaApiService.php               |   7 +-
 src/Service/NotificationService.php           |  10 +-
 src/Service/TokenEncryptor.php                |  46 ++-
 src/State/ClientTicketNumberProcessor.php     |   9 +-
 src/State/ClientTicketProvider.php            |  18 +-
 src/State/ClientTicketStatusProcessor.php     |  19 +-
 src/State/GiteaBranchNameProvider.php         |   1 +
 src/State/TaskDocumentProcessor.php           |  69 +++--
 src/State/TaskNumberProcessor.php             |  10 +-
 src/State/UserPasswordHasherProcessor.php     |   8 +-
 52 files changed, 662 insertions(+), 569 deletions(-)
 create mode 100644 frontend/utils/format.ts
 create mode 100644 migrations/Version20260315210619.php
 create mode 100644 src/Mcp/Tool/Serializer.php

diff --git a/frontend/components/admin/AdminBookStackTab.vue b/frontend/components/admin/AdminBookStackTab.vue
index 9584353..e846930 100644
--- a/frontend/components/admin/AdminBookStackTab.vue
+++ b/frontend/components/admin/AdminBookStackTab.vue
@@ -10,15 +10,13 @@
                 input-class="w-full"
             />
 
-            <div>
-                <MalioInputText
-                    v-model="form.tokenId"
-                    :label="$t('bookstack.settings.tokenId')"
-                    :placeholder="$t('bookstack.settings.tokenIdPlaceholder')"
-                    input-class="w-full"
-                    type="password"
-                />
-            </div>
+            <MalioInputText
+                v-model="form.tokenId"
+                :label="$t('bookstack.settings.tokenId')"
+                :placeholder="$t('bookstack.settings.tokenIdPlaceholder')"
+                input-class="w-full"
+                type="password"
+            />
 
             <div>
                 <MalioInputText
diff --git a/frontend/components/client-ticket/ProjectClientTickets.vue b/frontend/components/client-ticket/ProjectClientTickets.vue
index bba608e..18572fd 100644
--- a/frontend/components/client-ticket/ProjectClientTickets.vue
+++ b/frontend/components/client-ticket/ProjectClientTickets.vue
@@ -211,7 +211,7 @@ const props = defineProps<{
 
 const { t } = useI18n()
 const clientTicketService = useClientTicketService()
-const { typeBadgeClass, statusBadgeClass, formatDate } = useClientTicketHelpers()
+const { typeBadgeClass, statusBadgeClass, formatDate, getAvailableStatusTransitions } = useClientTicketHelpers()
 
 const isOpen = ref(false)
 const isLoading = ref(false)
@@ -238,18 +238,7 @@ const isUpdatingStatus = ref(false)
 
 const availableStatusTransitions = computed(() => {
     if (!statusTarget.value) return []
-    const current = statusTarget.value.status
-    const allStatuses: { label: string; value: ClientTicketStatus }[] = [
-        { label: t('clientTicket.status.new'), value: 'new' },
-        { label: t('clientTicket.status.in_progress'), value: 'in_progress' },
-        { label: t('clientTicket.status.done'), value: 'done' },
-        { label: t('clientTicket.status.rejected'), value: 'rejected' },
-    ]
-    return allStatuses.filter(s => {
-        if (s.value === current) return false
-        if ((current === 'done' || current === 'rejected') && s.value === 'new') return false
-        return true
-    })
+    return getAvailableStatusTransitions(statusTarget.value.status, t)
 })
 
 async function loadTickets() {
diff --git a/frontend/components/project/ProjectGroupTab.vue b/frontend/components/project/ProjectGroupTab.vue
index 240ce73..d8d457a 100644
--- a/frontend/components/project/ProjectGroupTab.vue
+++ b/frontend/components/project/ProjectGroupTab.vue
@@ -117,7 +117,7 @@ async function loadItems() {
         const [g, t, at] = await Promise.all([
             groupService.getByProject(props.projectId),
             taskService.getByProject(props.projectId),
-            taskService.getByProjectArchived(props.projectId),
+            taskService.getByProject(props.projectId, true),
         ])
         allGroups.value = g
         activeTasks.value = t
diff --git a/frontend/components/task/TaskDocumentList.vue b/frontend/components/task/TaskDocumentList.vue
index dd4098c..25b0e0e 100644
--- a/frontend/components/task/TaskDocumentList.vue
+++ b/frontend/components/task/TaskDocumentList.vue
@@ -28,7 +28,7 @@
                 <!-- File info -->
                 <div class="min-w-0 flex-1">
                     <p class="truncate text-xs font-medium text-neutral-700">{{ doc.originalName }}</p>
-                    <p class="text-xs text-neutral-400">{{ formatSize(doc.size) }}</p>
+                    <p class="text-xs text-neutral-400">{{ formatFileSize(doc.size) }}</p>
                 </div>
 
                 <!-- Delete button -->
@@ -47,6 +47,7 @@
 <script setup lang="ts">
 import type { TaskDocument } from '~/services/dto/task-document'
 import { useTaskDocumentService } from '~/services/task-documents'
+import { formatFileSize } from '~/utils/format'
 
 defineProps<{
     documents: TaskDocument[]
@@ -72,9 +73,4 @@ function getIconForMime(mimeType: string): string {
     return 'heroicons:paper-clip'
 }
 
-function formatSize(bytes: number): string {
-    if (bytes < 1024) return `${bytes} o`
-    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} Ko`
-    return `${(bytes / (1024 * 1024)).toFixed(1)} Mo`
-}
 </script>
diff --git a/frontend/components/task/TaskDocumentPreview.vue b/frontend/components/task/TaskDocumentPreview.vue
index b9b8543..243c009 100644
--- a/frontend/components/task/TaskDocumentPreview.vue
+++ b/frontend/components/task/TaskDocumentPreview.vue
@@ -56,7 +56,7 @@
                     <div v-else class="flex flex-col items-center gap-4 rounded-xl bg-white p-10">
                         <Icon name="heroicons:document" class="h-16 w-16 text-neutral-400" />
                         <p class="max-w-xs truncate text-lg font-medium text-neutral-700">{{ document.originalName }}</p>
-                        <p class="text-sm text-neutral-400">{{ formatSize(document.size) }}</p>
+                        <p class="text-sm text-neutral-400">{{ formatFileSize(document.size) }}</p>
                         <a
                             :href="downloadUrl"
                             download
@@ -77,6 +77,7 @@
 <script setup lang="ts">
 import type { TaskDocument } from '~/services/dto/task-document'
 import { useTaskDocumentService } from '~/services/task-documents'
+import { formatFileSize } from '~/utils/format'
 
 const props = defineProps<{
     document: TaskDocument | null
@@ -98,12 +99,6 @@ const downloadUrl = computed(() => props.document ? getDownloadUrl(props.documen
 const isImage = computed(() => props.document?.mimeType.startsWith('image/') ?? false)
 const isPdf = computed(() => props.document?.mimeType === 'application/pdf')
 
-function formatSize(bytes: number): string {
-    if (bytes < 1024) return `${bytes} o`
-    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} Ko`
-    return `${(bytes / (1024 * 1024)).toFixed(1)} Mo`
-}
-
 // Focus overlay for keyboard events
 watch(() => props.document, (doc) => {
     if (doc) {
diff --git a/frontend/components/task/TaskModal.vue b/frontend/components/task/TaskModal.vue
index 0ebdf95..fe6f082 100644
--- a/frontend/components/task/TaskModal.vue
+++ b/frontend/components/task/TaskModal.vue
@@ -154,7 +154,7 @@
                         />
                         <TaskDocumentList
                             v-if="isEditing && task"
-                            :documents="documents"
+                            :documents="localDocuments"
                             :is-admin="isAdmin"
                             @preview="openPreview"
                             @delete="handleDeleteDocument"
@@ -164,7 +164,7 @@
                         <TaskDocumentPreview
                             :document="previewDoc"
                             :has-prev="previewIndex > 0"
-                            :has-next="previewIndex < documents.length - 1"
+                            :has-next="previewIndex < localDocuments.length - 1"
                             @close="previewDoc = null"
                             @prev="prevPreview"
                             @next="nextPreview"
@@ -396,6 +396,14 @@ watch(() => props.modelValue, async (open) => {
         } catch {
             clientTickets.value = []
         }
+        if (props.task?.project?.giteaOwner && props.task?.project?.giteaRepo && !giteaUrl.value) {
+            try {
+                const settings = await getGiteaSettings()
+                giteaUrl.value = settings.url ?? ''
+            } catch {
+                // Gitea not available
+            }
+        }
     }
 })
 
@@ -405,17 +413,6 @@ watch(() => props.task, (task) => {
     }
 })
 
-watch(() => props.modelValue, async (open) => {
-    if (open && props.task?.project?.giteaOwner && props.task?.project?.giteaRepo && !giteaUrl.value) {
-        try {
-            const settings = await getGiteaSettings()
-            giteaUrl.value = settings.url ?? ''
-        } catch {
-            // Gitea not available
-        }
-    }
-})
-
 const { create, update, remove } = useTaskService()
 const { remove: removeDocument, getByTask: getDocumentsByTask } = useTaskDocumentService()
 const clientTicketService = useClientTicketService()
@@ -440,7 +437,6 @@ function ticketStatusClass(status: string): string {
 }
 
 const localDocuments = ref<TaskDocument[]>([])
-const documents = computed(() => localDocuments.value)
 const previewDoc = ref<TaskDocument | null>(null)
 
 // Sync documents from task prop when modal opens or task changes
@@ -455,7 +451,7 @@ async function refreshDocuments() {
 
 const previewIndex = computed(() => {
     if (!previewDoc.value) return -1
-    return documents.value.findIndex(d => d.id === previewDoc.value!.id)
+    return localDocuments.value.findIndex(d => d.id === previewDoc.value!.id)
 })
 
 function openPreview(doc: TaskDocument) {
@@ -464,13 +460,13 @@ function openPreview(doc: TaskDocument) {
 
 function prevPreview() {
     if (previewIndex.value > 0) {
-        previewDoc.value = documents.value[previewIndex.value - 1]
+        previewDoc.value = localDocuments.value[previewIndex.value - 1]
     }
 }
 
 function nextPreview() {
-    if (previewIndex.value < documents.value.length - 1) {
-        previewDoc.value = documents.value[previewIndex.value + 1]
+    if (previewIndex.value < localDocuments.value.length - 1) {
+        previewDoc.value = localDocuments.value[previewIndex.value + 1]
     }
 }
 
diff --git a/frontend/composables/useApi.ts b/frontend/composables/useApi.ts
index b81a602..760df5b 100644
--- a/frontend/composables/useApi.ts
+++ b/frontend/composables/useApi.ts
@@ -29,13 +29,14 @@ export type ApiFetchOptions<ResponseType extends 'json' | 'blob'> =
     toastSuccessKey?: string
   }
 
-export const useApi = (): ApiClient => {
+let isHandlingUnauthorized = false
+
+export function useApi(): ApiClient {
   const config = useRuntimeConfig()
   const baseURL = config.public.apiBase || '/api'
   const toast = useToast()
   const auth = useAuthStore()
   const nuxtApp = useNuxtApp()
-  let isHandlingUnauthorized = false
   const i18n = nuxtApp.$i18n as
     | {
         t: (key: string) => string
@@ -45,7 +46,7 @@ export const useApi = (): ApiClient => {
   const t = (key: string) => (i18n?.t ? String(i18n.t(key)) : key)
   const te = (key: string) => (i18n?.te ? i18n.te(key) : false)
 
-  const extractErrorMessage = (error: unknown, responseData?: unknown): string => {
+  function extractErrorMessage(error: unknown, responseData?: unknown): string {
     const data = responseData ?? (error as FetchError)?.data
 
     if (typeof data === 'string') {
@@ -169,11 +170,11 @@ export const useApi = (): ApiClient => {
     }
   })
 
-  const request = <T>(
+  function request<T>(
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
     url: string,
     options: ApiFetchOptions<'json'> = {}
-  ) => {
+  ) {
     const needsJsonBody = method === 'POST' || method === 'PUT'
     const needsMergePatch = method === 'PATCH'
 
diff --git a/frontend/composables/useAppVersion.ts b/frontend/composables/useAppVersion.ts
index 803278d..921f546 100644
--- a/frontend/composables/useAppVersion.ts
+++ b/frontend/composables/useAppVersion.ts
@@ -1,8 +1,8 @@
-export const useAppVersion = () => {
+export function useAppVersion() {
     const api = useApi()
     const version = useState<string | null>('app-version', () => null)
 
-    const load = async () => {
+    async function load(): Promise<string | null> {
         if (version.value) {
             return version.value
         }
diff --git a/frontend/composables/useClientTicketHelpers.ts b/frontend/composables/useClientTicketHelpers.ts
index 2742eef..feab80f 100644
--- a/frontend/composables/useClientTicketHelpers.ts
+++ b/frontend/composables/useClientTicketHelpers.ts
@@ -1,3 +1,5 @@
+import type { ClientTicketStatus } from '~/services/dto/client-ticket'
+
 export function useClientTicketHelpers() {
     function typeBadgeClass(type: string): string {
         switch (type) {
@@ -25,5 +27,22 @@ export function useClientTicketHelpers() {
         })
     }
 
-    return { typeBadgeClass, statusBadgeClass, formatDate }
+    function getAvailableStatusTransitions(
+        current: ClientTicketStatus,
+        t: (key: string) => string,
+    ): { label: string; value: ClientTicketStatus }[] {
+        const allStatuses: { label: string; value: ClientTicketStatus }[] = [
+            { label: t('clientTicket.status.new'), value: 'new' },
+            { label: t('clientTicket.status.in_progress'), value: 'in_progress' },
+            { label: t('clientTicket.status.done'), value: 'done' },
+            { label: t('clientTicket.status.rejected'), value: 'rejected' },
+        ]
+        return allStatuses.filter(s => {
+            if (s.value === current) return false
+            if ((current === 'done' || current === 'rejected') && s.value === 'new') return false
+            return true
+        })
+    }
+
+    return { typeBadgeClass, statusBadgeClass, formatDate, getAvailableStatusTransitions }
 }
diff --git a/frontend/layouts/auth.vue b/frontend/layouts/auth.vue
index 009acb7..117c591 100644
--- a/frontend/layouts/auth.vue
+++ b/frontend/layouts/auth.vue
@@ -5,7 +5,3 @@
     </main>
   </div>
 </template>
-
-<script setup lang="ts">
-const { version } = useAppVersion()
-</script>
diff --git a/frontend/layouts/default.vue b/frontend/layouts/default.vue
index 1616d11..bbf64ae 100644
--- a/frontend/layouts/default.vue
+++ b/frontend/layouts/default.vue
@@ -242,11 +242,6 @@ function onCompleteSaved() {
         timerStore.clearPendingEntry()
     })
 }
-
-const handleLogout = async () => {
-    await auth.logout()
-    await navigateTo('/login')
-}
 </script>
 
 <style scoped>
diff --git a/frontend/pages/login.vue b/frontend/pages/login.vue
index 41fb87c..c7ec8c8 100644
--- a/frontend/pages/login.vue
+++ b/frontend/pages/login.vue
@@ -48,7 +48,6 @@ useHead({
     title: 'Connexion'
 })
 
-const router = useRouter()
 const auth = useAuthStore()
 const {version} = useAppVersion()
 
@@ -56,7 +55,7 @@ const username = ref('')
 const password = ref('')
 const isSubmitting = ref(false)
 
-const handleSubmit = async () => {
+async function handleSubmit() {
     if (isSubmitting.value) return
 
     isSubmitting.value = true
@@ -64,7 +63,7 @@ const handleSubmit = async () => {
         await auth.login(username.value, password.value)
 
         const isClient = auth.user?.roles?.includes('ROLE_CLIENT') ?? false
-        await router.push(isClient ? '/portal' : '/')
+        await navigateTo(isClient ? '/portal' : '/')
     } finally {
         isSubmitting.value = false
     }
diff --git a/frontend/pages/time-tracking.vue b/frontend/pages/time-tracking.vue
index 19fa9a6..b97e39b 100644
--- a/frontend/pages/time-tracking.vue
+++ b/frontend/pages/time-tracking.vue
@@ -284,24 +284,10 @@ async function onPaste() {
     await loadEntries()
 }
 
-onMounted(() => {
-    updatePageHeaderHeight()
-
-    if (!pageHeaderEl.value || typeof ResizeObserver === 'undefined') {
-        return
-    }
-
-    pageHeaderResizeObserver = new ResizeObserver(() => {
-        updatePageHeaderHeight()
-    })
-    pageHeaderResizeObserver.observe(pageHeaderEl.value)
-})
-
 onBeforeUnmount(() => {
     pageHeaderResizeObserver?.disconnect()
 })
 
-
 async function onDelete(entry: TimeEntry) {
     await timeEntryService.remove(entry.id)
     await loadEntries()
@@ -333,6 +319,15 @@ async function loadReferenceData() {
 }
 
 onMounted(async () => {
+    updatePageHeaderHeight()
+
+    if (pageHeaderEl.value && typeof ResizeObserver !== 'undefined') {
+        pageHeaderResizeObserver = new ResizeObserver(() => {
+            updatePageHeaderHeight()
+        })
+        pageHeaderResizeObserver.observe(pageHeaderEl.value)
+    }
+
     await loadReferenceData()
     await loadEntries()
 })
diff --git a/frontend/services/auth.ts b/frontend/services/auth.ts
index bef14f5..b09cfb9 100644
--- a/frontend/services/auth.ts
+++ b/frontend/services/auth.ts
@@ -1,22 +1,22 @@
 import type { UserData } from './dto/user-data'
 
-export const getCurrentUser = () => {
-  const api = useApi()
-  return api.get<UserData>('/me', {}, { toastErrorKey: 'errors.auth.session' })
+export function getCurrentUser() {
+    const api = useApi()
+    return api.get<UserData>('/me', {}, { toastErrorKey: 'errors.auth.session' })
 }
 
-export const login = (username: string, password: string) => {
-  const api = useApi()
-  return api.post('/login_check', { username, password }, {
-    toastOn401: true,
-    toastErrorKey: 'errors.auth.login'
-  })
+export function login(username: string, password: string) {
+    const api = useApi()
+    return api.post('/login_check', { username, password }, {
+        toastOn401: true,
+        toastErrorKey: 'errors.auth.login'
+    })
 }
 
-export const logout = () => {
-  const api = useApi()
-  return api.post('/logout', {}, {
-    toastErrorKey: 'errors.auth.logout',
-    toastSuccessKey: 'success.auth.logout'
-  })
+export function logout() {
+    const api = useApi()
+    return api.post('/logout', {}, {
+        toastErrorKey: 'errors.auth.logout',
+        toastSuccessKey: 'success.auth.logout'
+    })
 }
diff --git a/frontend/services/client-tickets.ts b/frontend/services/client-tickets.ts
index c938a51..5097fbe 100644
--- a/frontend/services/client-tickets.ts
+++ b/frontend/services/client-tickets.ts
@@ -32,7 +32,7 @@ export function useClientTicketService() {
 
     async function update(id: number, data: Partial<ClientTicketWrite>): Promise<ClientTicket> {
         return api.patch<ClientTicket>(`/client_tickets/${id}`, data as Record<string, unknown>, {
-            toastSuccessKey: 'clientTicket.statusUpdated',
+            toastSuccessKey: 'clientTicket.updated',
         })
     }
 
diff --git a/frontend/services/task-documents.ts b/frontend/services/task-documents.ts
index 2afc99c..3bc9336 100644
--- a/frontend/services/task-documents.ts
+++ b/frontend/services/task-documents.ts
@@ -15,30 +15,24 @@ export function useTaskDocumentService() {
         return extractHydraMembers(data)
     }
 
-    async function upload(taskId: number, file: File): Promise<TaskDocument> {
+    async function uploadWithRelation(relationField: string, relationIri: string, file: File): Promise<TaskDocument> {
         const formData = new FormData()
         formData.append('file', file)
-        formData.append('task', `/api/tasks/${taskId}`)
+        formData.append(relationField, relationIri)
 
-        return await $fetch<TaskDocument>(`${baseURL}/task_documents`, {
+        return $fetch<TaskDocument>(`${baseURL}/task_documents`, {
             method: 'POST',
             body: formData,
             credentials: 'include',
-            // Do NOT set Content-Type — browser sets multipart boundary automatically
         })
     }
 
-    async function uploadForTicket(clientTicketId: number, file: File): Promise<TaskDocument> {
-        const formData = new FormData()
-        formData.append('file', file)
-        formData.append('clientTicket', `/api/client_tickets/${clientTicketId}`)
+    async function upload(taskId: number, file: File): Promise<TaskDocument> {
+        return uploadWithRelation('task', `/api/tasks/${taskId}`, file)
+    }
 
-        return await $fetch<TaskDocument>(`${baseURL}/task_documents`, {
-            method: 'POST',
-            body: formData,
-            credentials: 'include',
-            // Do NOT set Content-Type — browser sets multipart boundary automatically
-        })
+    async function uploadForTicket(clientTicketId: number, file: File): Promise<TaskDocument> {
+        return uploadWithRelation('clientTicket', `/api/client_tickets/${clientTicketId}`, file)
     }
 
     async function getByTicket(clientTicketId: number): Promise<TaskDocument[]> {
diff --git a/frontend/services/tasks.ts b/frontend/services/tasks.ts
index 647ca01..c4d6fa3 100644
--- a/frontend/services/tasks.ts
+++ b/frontend/services/tasks.ts
@@ -10,18 +10,10 @@ export function useTaskService() {
         return extractHydraMembers(data)
     }
 
-    async function getByProject(projectId: number): Promise<Task[]> {
+    async function getByProject(projectId: number, archived = false): Promise<Task[]> {
         const data = await api.get<HydraCollection<Task>>('/tasks', {
             project: `/api/projects/${projectId}`,
-            archived: false,
-        })
-        return extractHydraMembers(data)
-    }
-
-    async function getByProjectArchived(projectId: number): Promise<Task[]> {
-        const data = await api.get<HydraCollection<Task>>('/tasks', {
-            project: `/api/projects/${projectId}`,
-            archived: true,
+            archived,
         })
         return extractHydraMembers(data)
     }
@@ -49,5 +41,5 @@ export function useTaskService() {
         })
     }
 
-    return { getAll, getByProject, getByProjectArchived, getFiltered, create, update, remove }
+    return { getAll, getByProject, getFiltered, create, update, remove }
 }
diff --git a/frontend/stores/timer.ts b/frontend/stores/timer.ts
index 003f2ec..28d5688 100644
--- a/frontend/stores/timer.ts
+++ b/frontend/stores/timer.ts
@@ -66,6 +66,11 @@ export const useTimerStore = defineStore('timer', () => {
         startTicking()
     }
 
+    function toIri<T extends { '@id'?: string; id: number }>(entity: T | string, prefix: string): string {
+        if (typeof entity === 'string') return entity
+        return entity['@id'] ?? `${prefix}/${entity.id}`
+    }
+
     async function startFromTask(task: Task) {
         const authStore = useAuthStore()
         if (!authStore.user) return
@@ -79,11 +84,9 @@ export const useTimerStore = defineStore('timer', () => {
             startedAt: new Date().toISOString(),
             user: `/api/users/${authStore.user.id}`,
             title: task.title,
-            project: task.project
-                ? (typeof task.project === 'string' ? task.project : (task.project['@id'] ?? (task.project.id ? `/api/projects/${task.project.id}` : null)))
-                : null,
-            task: typeof task === 'string' ? task : (task['@id'] ?? `/api/tasks/${task.id}`),
-            tags: task.tags?.map((t) => typeof t === 'string' ? t : (t['@id'] ?? `/api/task_tags/${t.id}`)) ?? [],
+            project: task.project ? toIri(task.project, '/api/projects') : null,
+            task: toIri(task, '/api/tasks'),
+            tags: task.tags?.map(t => toIri(t, '/api/task_tags')) ?? [],
         })
         startTicking()
     }
diff --git a/frontend/utils/format.ts b/frontend/utils/format.ts
new file mode 100644
index 0000000..9f0c5ef
--- /dev/null
+++ b/frontend/utils/format.ts
@@ -0,0 +1,5 @@
+export function formatFileSize(bytes: number): string {
+    if (bytes < 1024) return `${bytes} o`
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} Ko`
+    return `${(bytes / (1024 * 1024)).toFixed(1)} Mo`
+}
diff --git a/migrations/Version20260315210619.php b/migrations/Version20260315210619.php
new file mode 100644
index 0000000..7aa7edd
--- /dev/null
+++ b/migrations/Version20260315210619.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DoctrineMigrations;
+
+use Doctrine\DBAL\Schema\Schema;
+use Doctrine\Migrations\AbstractMigration;
+
+/**
+ * Auto-generated Migration: Please modify to your needs!
+ */
+final class Version20260315210619 extends AbstractMigration
+{
+    public function getDescription(): string
+    {
+        return '';
+    }
+
+    public function up(Schema $schema): void
+    {
+        // this up() migration is auto-generated, please modify it to your needs
+        $this->addSql('CREATE UNIQUE INDEX uniq_task_project_number ON task (project_id, number)');
+    }
+
+    public function down(Schema $schema): void
+    {
+        // this down() migration is auto-generated, please modify it to your needs
+        $this->addSql('DROP INDEX uniq_task_project_number');
+    }
+}
diff --git a/src/Controller/TaskDocumentDownloadController.php b/src/Controller/TaskDocumentDownloadController.php
index 17ef4c2..7ec344c 100644
--- a/src/Controller/TaskDocumentDownloadController.php
+++ b/src/Controller/TaskDocumentDownloadController.php
@@ -7,8 +7,10 @@ namespace App\Controller;
 use App\Entity\TaskDocument;
 use Doctrine\ORM\EntityManagerInterface;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Bundle\SecurityBundle\Security;
 use Symfony\Component\HttpFoundation\BinaryFileResponse;
 use Symfony\Component\HttpFoundation\ResponseHeaderBag;
+use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
 use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 use Symfony\Component\Routing\Attribute\Route;
 use Symfony\Component\Security\Http\Attribute\IsGranted;
@@ -17,11 +19,12 @@ class TaskDocumentDownloadController extends AbstractController
 {
     public function __construct(
         private readonly EntityManagerInterface $entityManager,
+        private readonly Security $security,
         private readonly string $uploadDir,
     ) {}
 
-    #[Route('/api/task_documents/{id}/download', name: 'task_document_download', methods: ['GET'])]
-    #[IsGranted('ROLE_USER')]
+    #[Route('/api/task_documents/{id}/download', name: 'task_document_download', methods: ['GET'], priority: 1)]
+    #[IsGranted('IS_AUTHENTICATED_FULLY')]
     public function __invoke(int $id): BinaryFileResponse
     {
         $document = $this->entityManager->getRepository(TaskDocument::class)->find($id);
@@ -30,6 +33,14 @@ class TaskDocumentDownloadController extends AbstractController
             throw new NotFoundHttpException('Document not found.');
         }
 
+        // ROLE_CLIENT can only download documents from their own tickets
+        if (!$this->security->isGranted('ROLE_ADMIN') && !$this->security->isGranted('ROLE_USER')) {
+            $ticket = $document->getClientTicket();
+            if (null === $ticket || $ticket->getSubmittedBy() !== $this->security->getUser()) {
+                throw new AccessDeniedHttpException('You do not have access to this document.');
+            }
+        }
+
         $filePath = $this->uploadDir.'/'.$document->getFileName();
 
         if (!file_exists($filePath)) {
diff --git a/src/Entity/Task.php b/src/Entity/Task.php
index 0e5ef5d..22890b7 100644
--- a/src/Entity/Task.php
+++ b/src/Entity/Task.php
@@ -35,6 +35,8 @@ use Symfony\Component\Serializer\Attribute\Groups;
 #[ApiFilter(SearchFilter::class, properties: ['project' => 'exact', 'group' => 'exact', 'assignee' => 'exact', 'priority' => 'exact', 'effort' => 'exact', 'tags' => 'exact', 'status' => 'exact'])]
 #[ApiFilter(BooleanFilter::class, properties: ['archived'])]
 #[ORM\Entity(repositoryClass: TaskRepository::class)]
+#[ORM\Table(name: 'task')]
+#[ORM\UniqueConstraint(name: 'uniq_task_project_number', columns: ['project_id', 'number'])]
 class Task
 {
     #[ORM\Id]
diff --git a/src/Exception/BookStackApiException.php b/src/Exception/BookStackApiException.php
index 81bec70..5b9691a 100644
--- a/src/Exception/BookStackApiException.php
+++ b/src/Exception/BookStackApiException.php
@@ -5,12 +5,5 @@ declare(strict_types=1);
 namespace App\Exception;
 
 use RuntimeException;
-use Throwable;
 
-final class BookStackApiException extends RuntimeException
-{
-    public function __construct(string $message, int $code = 0, ?Throwable $previous = null)
-    {
-        parent::__construct($message, $code, $previous);
-    }
-}
+final class BookStackApiException extends RuntimeException {}
diff --git a/src/Exception/GiteaApiException.php b/src/Exception/GiteaApiException.php
index b10627e..d5174f0 100644
--- a/src/Exception/GiteaApiException.php
+++ b/src/Exception/GiteaApiException.php
@@ -5,12 +5,5 @@ declare(strict_types=1);
 namespace App\Exception;
 
 use RuntimeException;
-use Throwable;
 
-final class GiteaApiException extends RuntimeException
-{
-    public function __construct(string $message, int $code = 0, ?Throwable $previous = null)
-    {
-        parent::__construct($message, $code, $previous);
-    }
-}
+final class GiteaApiException extends RuntimeException {}
diff --git a/src/Mcp/Tool/Project/CreateProjectTool.php b/src/Mcp/Tool/Project/CreateProjectTool.php
index 75001c4..8daeb7e 100644
--- a/src/Mcp/Tool/Project/CreateProjectTool.php
+++ b/src/Mcp/Tool/Project/CreateProjectTool.php
@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace App\Mcp\Tool\Project;
 
 use App\Entity\Project;
+use App\Mcp\Tool\Serializer;
 use App\Repository\ClientRepository;
 use Doctrine\ORM\EntityManagerInterface;
 use InvalidArgumentException;
@@ -48,17 +49,6 @@ class CreateProjectTool
         $this->entityManager->persist($project);
         $this->entityManager->flush();
 
-        return json_encode([
-            'id'          => $project->getId(),
-            'code'        => $project->getCode(),
-            'name'        => $project->getName(),
-            'description' => $project->getDescription(),
-            'color'       => $project->getColor(),
-            'client'      => $project->getClient() ? [
-                'id'   => $project->getClient()->getId(),
-                'name' => $project->getClient()->getName(),
-            ] : null,
-            'archived' => $project->isArchived(),
-        ]);
+        return json_encode(Serializer::project($project));
     }
 }
diff --git a/src/Mcp/Tool/Project/GetProjectTool.php b/src/Mcp/Tool/Project/GetProjectTool.php
index c886efc..a45796a 100644
--- a/src/Mcp/Tool/Project/GetProjectTool.php
+++ b/src/Mcp/Tool/Project/GetProjectTool.php
@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Mcp\Tool\Project;
 
+use App\Mcp\Tool\Serializer;
 use App\Repository\ProjectRepository;
 use App\Repository\TaskRepository;
 use InvalidArgumentException;
@@ -45,17 +46,7 @@ class GetProjectTool
             $totalTasks += $count;
         }
 
-        return json_encode([
-            'id'          => $project->getId(),
-            'code'        => $project->getCode(),
-            'name'        => $project->getName(),
-            'description' => $project->getDescription(),
-            'color'       => $project->getColor(),
-            'client'      => $project->getClient() ? [
-                'id'   => $project->getClient()->getId(),
-                'name' => $project->getClient()->getName(),
-            ] : null,
-            'archived'    => $project->isArchived(),
+        return json_encode(Serializer::project($project) + [
             'taskSummary' => $statusCounts,
             'totalTasks'  => $totalTasks,
         ]);
diff --git a/src/Mcp/Tool/Project/ListProjectsTool.php b/src/Mcp/Tool/Project/ListProjectsTool.php
index eae89ca..ef0f737 100644
--- a/src/Mcp/Tool/Project/ListProjectsTool.php
+++ b/src/Mcp/Tool/Project/ListProjectsTool.php
@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Mcp\Tool\Project;
 
+use App\Mcp\Tool\Serializer;
 use App\Repository\ProjectRepository;
 use Mcp\Capability\Attribute\McpTool;
 
@@ -18,17 +19,6 @@ class ListProjectsTool
     {
         $projects = $this->projectRepository->findBy(['archived' => $archived], ['name' => 'ASC']);
 
-        return json_encode(array_map(fn ($project) => [
-            'id'          => $project->getId(),
-            'code'        => $project->getCode(),
-            'name'        => $project->getName(),
-            'description' => $project->getDescription(),
-            'color'       => $project->getColor(),
-            'client'      => $project->getClient() ? [
-                'id'   => $project->getClient()->getId(),
-                'name' => $project->getClient()->getName(),
-            ] : null,
-            'archived' => $project->isArchived(),
-        ], $projects));
+        return json_encode(array_map(Serializer::project(...), $projects));
     }
 }
diff --git a/src/Mcp/Tool/Project/UpdateProjectTool.php b/src/Mcp/Tool/Project/UpdateProjectTool.php
index ee08b96..3ed6e27 100644
--- a/src/Mcp/Tool/Project/UpdateProjectTool.php
+++ b/src/Mcp/Tool/Project/UpdateProjectTool.php
@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Mcp\Tool\Project;
 
+use App\Mcp\Tool\Serializer;
 use App\Repository\ClientRepository;
 use App\Repository\ProjectRepository;
 use Doctrine\ORM\EntityManagerInterface;
@@ -61,17 +62,6 @@ class UpdateProjectTool
 
         $this->entityManager->flush();
 
-        return json_encode([
-            'id'          => $project->getId(),
-            'code'        => $project->getCode(),
-            'name'        => $project->getName(),
-            'description' => $project->getDescription(),
-            'color'       => $project->getColor(),
-            'client'      => $project->getClient() ? [
-                'id'   => $project->getClient()->getId(),
-                'name' => $project->getClient()->getName(),
-            ] : null,
-            'archived' => $project->isArchived(),
-        ]);
+        return json_encode(Serializer::project($project));
     }
 }
diff --git a/src/Mcp/Tool/Serializer.php b/src/Mcp/Tool/Serializer.php
new file mode 100644
index 0000000..a4d4608
--- /dev/null
+++ b/src/Mcp/Tool/Serializer.php
@@ -0,0 +1,277 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Mcp\Tool;
+
+use App\Entity\Project;
+use App\Entity\Task;
+use App\Entity\TaskDocument;
+use App\Entity\TaskEffort;
+use App\Entity\TaskGroup;
+use App\Entity\TaskPriority;
+use App\Entity\TaskStatus;
+use App\Entity\TaskTag;
+use App\Entity\TimeEntry;
+use App\Entity\User;
+use Doctrine\Common\Collections\Collection;
+
+/**
+ * Shared serialization helpers for MCP tools.
+ *
+ * Keeps JSON output consistent across all tools.
+ */
+final class Serializer
+{
+    /**
+     * @return array{id: ?int, code: ?string, name: ?string}
+     */
+    public static function projectRef(Project $project): array
+    {
+        return [
+            'id'   => $project->getId(),
+            'code' => $project->getCode(),
+            'name' => $project->getName(),
+        ];
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public static function project(Project $project): array
+    {
+        return [
+            'id'          => $project->getId(),
+            'code'        => $project->getCode(),
+            'name'        => $project->getName(),
+            'description' => $project->getDescription(),
+            'color'       => $project->getColor(),
+            'client'      => $project->getClient() ? [
+                'id'   => $project->getClient()->getId(),
+                'name' => $project->getClient()->getName(),
+            ] : null,
+            'archived' => $project->isArchived(),
+        ];
+    }
+
+    /**
+     * @return null|array{id: ?int, label: ?string, color: ?string}
+     */
+    public static function status(?TaskStatus $status): ?array
+    {
+        if (null === $status) {
+            return null;
+        }
+
+        return [
+            'id'    => $status->getId(),
+            'label' => $status->getLabel(),
+            'color' => $status->getColor(),
+        ];
+    }
+
+    /**
+     * @return null|array{id: ?int, label: ?string, color: ?string, isFinal: bool}
+     */
+    public static function statusFull(?TaskStatus $status): ?array
+    {
+        if (null === $status) {
+            return null;
+        }
+
+        return [
+            'id'      => $status->getId(),
+            'label'   => $status->getLabel(),
+            'color'   => $status->getColor(),
+            'isFinal' => $status->getIsFinal(),
+        ];
+    }
+
+    /**
+     * @return null|array{id: ?int, label: ?string, color: ?string}
+     */
+    public static function priority(?TaskPriority $priority): ?array
+    {
+        if (null === $priority) {
+            return null;
+        }
+
+        return [
+            'id'    => $priority->getId(),
+            'label' => $priority->getLabel(),
+            'color' => $priority->getColor(),
+        ];
+    }
+
+    /**
+     * @return null|array{id: ?int, label: ?string}
+     */
+    public static function effort(?TaskEffort $effort): ?array
+    {
+        if (null === $effort) {
+            return null;
+        }
+
+        return [
+            'id'    => $effort->getId(),
+            'label' => $effort->getLabel(),
+        ];
+    }
+
+    /**
+     * @return null|array{id: ?int, username: ?string}
+     */
+    public static function user(?User $user): ?array
+    {
+        if (null === $user) {
+            return null;
+        }
+
+        return [
+            'id'       => $user->getId(),
+            'username' => $user->getUsername(),
+        ];
+    }
+
+    /**
+     * @return null|array{id: ?int, title: ?string, color: ?string}
+     */
+    public static function group(?TaskGroup $group): ?array
+    {
+        if (null === $group) {
+            return null;
+        }
+
+        return [
+            'id'    => $group->getId(),
+            'title' => $group->getTitle(),
+            'color' => $group->getColor(),
+        ];
+    }
+
+    /**
+     * @return null|array{id: ?int, title: ?string}
+     */
+    public static function groupRef(?TaskGroup $group): ?array
+    {
+        if (null === $group) {
+            return null;
+        }
+
+        return [
+            'id'    => $group->getId(),
+            'title' => $group->getTitle(),
+        ];
+    }
+
+    /**
+     * Full group serialization for MCP group tools (includes description, project, archived).
+     *
+     * @return array<string, mixed>
+     */
+    public static function groupFull(TaskGroup $group): array
+    {
+        return [
+            'id'          => $group->getId(),
+            'title'       => $group->getTitle(),
+            'description' => $group->getDescription(),
+            'color'       => $group->getColor(),
+            'project'     => self::projectRef($group->getProject()),
+            'archived'    => $group->isArchived(),
+        ];
+    }
+
+    /**
+     * @param Collection<int, TaskTag> $tags
+     *
+     * @return list<array{id: ?int, label: ?string}>
+     */
+    public static function tags(Collection $tags): array
+    {
+        return $tags->map(fn (TaskTag $t) => [
+            'id'    => $t->getId(),
+            'label' => $t->getLabel(),
+        ])->toArray();
+    }
+
+    /**
+     * @param Collection<int, TaskTag> $tags
+     *
+     * @return list<array{id: ?int, label: ?string, color: ?string}>
+     */
+    public static function tagsWithColor(Collection $tags): array
+    {
+        return $tags->map(fn (TaskTag $t) => [
+            'id'    => $t->getId(),
+            'label' => $t->getLabel(),
+            'color' => $t->getColor(),
+        ])->toArray();
+    }
+
+    /**
+     * Compute duration in minutes between two timestamps, or null if still active.
+     */
+    public static function durationMinutes(TimeEntry $entry): ?int
+    {
+        $started = $entry->getStartedAt();
+        $stopped = $entry->getStoppedAt();
+
+        if (null === $stopped || null === $started) {
+            return null;
+        }
+
+        return (int) round(($stopped->getTimestamp() - $started->getTimestamp()) / 60);
+    }
+
+    /**
+     * @return null|array{id: ?int, number: ?int, title: ?string}
+     */
+    public static function taskRef(?Task $task): ?array
+    {
+        if (null === $task) {
+            return null;
+        }
+
+        return [
+            'id'     => $task->getId(),
+            'number' => $task->getNumber(),
+            'title'  => $task->getTitle(),
+        ];
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public static function timeEntry(TimeEntry $entry): array
+    {
+        return [
+            'id'          => $entry->getId(),
+            'title'       => $entry->getTitle(),
+            'description' => $entry->getDescription(),
+            'startedAt'   => $entry->getStartedAt()?->format('c'),
+            'stoppedAt'   => $entry->getStoppedAt()?->format('c'),
+            'duration'    => self::durationMinutes($entry),
+            'user'        => self::user($entry->getUser()),
+            'project'     => $entry->getProject() ? self::projectRef($entry->getProject()) : null,
+            'task'        => self::taskRef($entry->getTask()),
+            'tags'        => self::tags($entry->getTags()),
+        ];
+    }
+
+    /**
+     * @param Collection<int, TaskDocument> $documents
+     *
+     * @return list<array<string, mixed>>
+     */
+    public static function documents(Collection $documents): array
+    {
+        return $documents->map(fn (TaskDocument $doc) => [
+            'id'           => $doc->getId(),
+            'originalName' => $doc->getOriginalName(),
+            'mimeType'     => $doc->getMimeType(),
+            'size'         => $doc->getSize(),
+            'createdAt'    => $doc->getCreatedAt()?->format('c'),
+            'uploadedBy'   => self::user($doc->getUploadedBy()),
+        ])->toArray();
+    }
+}
diff --git a/src/Mcp/Tool/Task/CreateTaskTool.php b/src/Mcp/Tool/Task/CreateTaskTool.php
index 11093cb..716de42 100644
--- a/src/Mcp/Tool/Task/CreateTaskTool.php
+++ b/src/Mcp/Tool/Task/CreateTaskTool.php
@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace App\Mcp\Tool\Task;
 
 use App\Entity\Task;
+use App\Mcp\Tool\Serializer;
 use App\Repository\ProjectRepository;
 use App\Repository\TaskEffortRepository;
 use App\Repository\TaskGroupRepository;
@@ -111,38 +112,14 @@ class CreateTaskTool
             'number'      => $task->getNumber(),
             'title'       => $task->getTitle(),
             'description' => $task->getDescription(),
-            'status'      => $task->getStatus() ? [
-                'id'    => $task->getStatus()->getId(),
-                'label' => $task->getStatus()->getLabel(),
-                'color' => $task->getStatus()->getColor(),
-            ] : null,
-            'priority' => $task->getPriority() ? [
-                'id'    => $task->getPriority()->getId(),
-                'label' => $task->getPriority()->getLabel(),
-                'color' => $task->getPriority()->getColor(),
-            ] : null,
-            'effort' => $task->getEffort() ? [
-                'id'    => $task->getEffort()->getId(),
-                'label' => $task->getEffort()->getLabel(),
-            ] : null,
-            'assignee' => $task->getAssignee() ? [
-                'id'       => $task->getAssignee()->getId(),
-                'username' => $task->getAssignee()->getUsername(),
-            ] : null,
-            'group' => $task->getGroup() ? [
-                'id'    => $task->getGroup()->getId(),
-                'title' => $task->getGroup()->getTitle(),
-            ] : null,
-            'project' => [
-                'id'   => $project->getId(),
-                'code' => $project->getCode(),
-                'name' => $project->getName(),
-            ],
-            'tags' => $task->getTags()->map(fn ($t) => [
-                'id'    => $t->getId(),
-                'label' => $t->getLabel(),
-            ])->toArray(),
-            'archived' => $task->isArchived(),
+            'status'      => Serializer::status($task->getStatus()),
+            'priority'    => Serializer::priority($task->getPriority()),
+            'effort'      => Serializer::effort($task->getEffort()),
+            'assignee'    => Serializer::user($task->getAssignee()),
+            'group'       => Serializer::groupRef($task->getGroup()),
+            'project'     => Serializer::projectRef($project),
+            'tags'        => Serializer::tags($task->getTags()),
+            'archived'    => $task->isArchived(),
         ]);
     }
 }
diff --git a/src/Mcp/Tool/Task/GetTaskTool.php b/src/Mcp/Tool/Task/GetTaskTool.php
index f214f3f..b0696cf 100644
--- a/src/Mcp/Tool/Task/GetTaskTool.php
+++ b/src/Mcp/Tool/Task/GetTaskTool.php
@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Mcp\Tool\Task;
 
+use App\Mcp\Tool\Serializer;
 use App\Repository\TaskRepository;
 use InvalidArgumentException;
 use Mcp\Capability\Attribute\McpTool;
@@ -30,52 +31,15 @@ class GetTaskTool
             'number'      => $task->getNumber(),
             'title'       => $task->getTitle(),
             'description' => $task->getDescription(),
-            'status'      => $task->getStatus() ? [
-                'id'      => $task->getStatus()->getId(),
-                'label'   => $task->getStatus()->getLabel(),
-                'color'   => $task->getStatus()->getColor(),
-                'isFinal' => $task->getStatus()->getIsFinal(),
-            ] : null,
-            'priority' => $task->getPriority() ? [
-                'id'    => $task->getPriority()->getId(),
-                'label' => $task->getPriority()->getLabel(),
-                'color' => $task->getPriority()->getColor(),
-            ] : null,
-            'effort' => $task->getEffort() ? [
-                'id'    => $task->getEffort()->getId(),
-                'label' => $task->getEffort()->getLabel(),
-            ] : null,
-            'assignee' => $task->getAssignee() ? [
-                'id'       => $task->getAssignee()->getId(),
-                'username' => $task->getAssignee()->getUsername(),
-            ] : null,
-            'group' => $task->getGroup() ? [
-                'id'    => $task->getGroup()->getId(),
-                'title' => $task->getGroup()->getTitle(),
-                'color' => $task->getGroup()->getColor(),
-            ] : null,
-            'project' => [
-                'id'   => $task->getProject()->getId(),
-                'code' => $task->getProject()->getCode(),
-                'name' => $task->getProject()->getName(),
-            ],
-            'tags' => $task->getTags()->map(fn ($t) => [
-                'id'    => $t->getId(),
-                'label' => $t->getLabel(),
-                'color' => $t->getColor(),
-            ])->toArray(),
-            'documents' => $task->getDocuments()->map(fn ($doc) => [
-                'id'           => $doc->getId(),
-                'originalName' => $doc->getOriginalName(),
-                'mimeType'     => $doc->getMimeType(),
-                'size'         => $doc->getSize(),
-                'createdAt'    => $doc->getCreatedAt()?->format('c'),
-                'uploadedBy'   => $doc->getUploadedBy() ? [
-                    'id'       => $doc->getUploadedBy()->getId(),
-                    'username' => $doc->getUploadedBy()->getUsername(),
-                ] : null,
-            ])->toArray(),
-            'archived' => $task->isArchived(),
+            'status'      => Serializer::statusFull($task->getStatus()),
+            'priority'    => Serializer::priority($task->getPriority()),
+            'effort'      => Serializer::effort($task->getEffort()),
+            'assignee'    => Serializer::user($task->getAssignee()),
+            'group'       => Serializer::group($task->getGroup()),
+            'project'     => Serializer::projectRef($task->getProject()),
+            'tags'        => Serializer::tagsWithColor($task->getTags()),
+            'documents'   => Serializer::documents($task->getDocuments()),
+            'archived'    => $task->isArchived(),
         ]);
     }
 }
diff --git a/src/Mcp/Tool/Task/ListTasksTool.php b/src/Mcp/Tool/Task/ListTasksTool.php
index bc914d6..fa9b397 100644
--- a/src/Mcp/Tool/Task/ListTasksTool.php
+++ b/src/Mcp/Tool/Task/ListTasksTool.php
@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Mcp\Tool\Task;
 
+use App\Mcp\Tool\Serializer;
 use App\Repository\TaskRepository;
 use Mcp\Capability\Attribute\McpTool;
 
@@ -67,40 +68,16 @@ class ListTasksTool
         }
 
         return json_encode(array_map(fn ($task) => [
-            'id'     => $task->getId(),
-            'number' => $task->getNumber(),
-            'title'  => $task->getTitle(),
-            'status' => $task->getStatus() ? [
-                'id'    => $task->getStatus()->getId(),
-                'label' => $task->getStatus()->getLabel(),
-                'color' => $task->getStatus()->getColor(),
-            ] : null,
-            'priority' => $task->getPriority() ? [
-                'id'    => $task->getPriority()->getId(),
-                'label' => $task->getPriority()->getLabel(),
-                'color' => $task->getPriority()->getColor(),
-            ] : null,
-            'assignee' => $task->getAssignee() ? [
-                'id'       => $task->getAssignee()->getId(),
-                'username' => $task->getAssignee()->getUsername(),
-            ] : null,
-            'effort' => $task->getEffort() ? [
-                'id'    => $task->getEffort()->getId(),
-                'label' => $task->getEffort()->getLabel(),
-            ] : null,
-            'group' => $task->getGroup() ? [
-                'id'    => $task->getGroup()->getId(),
-                'title' => $task->getGroup()->getTitle(),
-            ] : null,
-            'project' => [
-                'id'   => $task->getProject()->getId(),
-                'code' => $task->getProject()->getCode(),
-                'name' => $task->getProject()->getName(),
-            ],
-            'tags' => $task->getTags()->map(fn ($t) => [
-                'id'    => $t->getId(),
-                'label' => $t->getLabel(),
-            ])->toArray(),
+            'id'       => $task->getId(),
+            'number'   => $task->getNumber(),
+            'title'    => $task->getTitle(),
+            'status'   => Serializer::status($task->getStatus()),
+            'priority' => Serializer::priority($task->getPriority()),
+            'assignee' => Serializer::user($task->getAssignee()),
+            'effort'   => Serializer::effort($task->getEffort()),
+            'group'    => Serializer::groupRef($task->getGroup()),
+            'project'  => Serializer::projectRef($task->getProject()),
+            'tags'     => Serializer::tags($task->getTags()),
             'archived' => $task->isArchived(),
         ], array_values($tasks)));
     }
diff --git a/src/Mcp/Tool/Task/UpdateTaskTool.php b/src/Mcp/Tool/Task/UpdateTaskTool.php
index 96db18f..74efcad 100644
--- a/src/Mcp/Tool/Task/UpdateTaskTool.php
+++ b/src/Mcp/Tool/Task/UpdateTaskTool.php
@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Mcp\Tool\Task;
 
+use App\Mcp\Tool\Serializer;
 use App\Repository\TaskEffortRepository;
 use App\Repository\TaskGroupRepository;
 use App\Repository\TaskPriorityRepository;
@@ -114,38 +115,14 @@ class UpdateTaskTool
             'number'      => $task->getNumber(),
             'title'       => $task->getTitle(),
             'description' => $task->getDescription(),
-            'status'      => $task->getStatus() ? [
-                'id'    => $task->getStatus()->getId(),
-                'label' => $task->getStatus()->getLabel(),
-                'color' => $task->getStatus()->getColor(),
-            ] : null,
-            'priority' => $task->getPriority() ? [
-                'id'    => $task->getPriority()->getId(),
-                'label' => $task->getPriority()->getLabel(),
-                'color' => $task->getPriority()->getColor(),
-            ] : null,
-            'effort' => $task->getEffort() ? [
-                'id'    => $task->getEffort()->getId(),
-                'label' => $task->getEffort()->getLabel(),
-            ] : null,
-            'assignee' => $task->getAssignee() ? [
-                'id'       => $task->getAssignee()->getId(),
-                'username' => $task->getAssignee()->getUsername(),
-            ] : null,
-            'group' => $task->getGroup() ? [
-                'id'    => $task->getGroup()->getId(),
-                'title' => $task->getGroup()->getTitle(),
-            ] : null,
-            'project' => [
-                'id'   => $task->getProject()->getId(),
-                'code' => $task->getProject()->getCode(),
-                'name' => $task->getProject()->getName(),
-            ],
-            'tags' => $task->getTags()->map(fn ($t) => [
-                'id'    => $t->getId(),
-                'label' => $t->getLabel(),
-            ])->toArray(),
-            'archived' => $task->isArchived(),
+            'status'      => Serializer::status($task->getStatus()),
+            'priority'    => Serializer::priority($task->getPriority()),
+            'effort'      => Serializer::effort($task->getEffort()),
+            'assignee'    => Serializer::user($task->getAssignee()),
+            'group'       => Serializer::groupRef($task->getGroup()),
+            'project'     => Serializer::projectRef($task->getProject()),
+            'tags'        => Serializer::tags($task->getTags()),
+            'archived'    => $task->isArchived(),
         ]);
     }
 }
diff --git a/src/Mcp/Tool/TaskMeta/CreateGroupTool.php b/src/Mcp/Tool/TaskMeta/CreateGroupTool.php
index a98a91e..f344dde 100644
--- a/src/Mcp/Tool/TaskMeta/CreateGroupTool.php
+++ b/src/Mcp/Tool/TaskMeta/CreateGroupTool.php
@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace App\Mcp\Tool\TaskMeta;
 
 use App\Entity\TaskGroup;
+use App\Mcp\Tool\Serializer;
 use App\Repository\ProjectRepository;
 use Doctrine\ORM\EntityManagerInterface;
 use InvalidArgumentException;
@@ -45,17 +46,6 @@ class CreateGroupTool
         $this->entityManager->persist($group);
         $this->entityManager->flush();
 
-        return json_encode([
-            'id'          => $group->getId(),
-            'title'       => $group->getTitle(),
-            'description' => $group->getDescription(),
-            'color'       => $group->getColor(),
-            'project'     => [
-                'id'   => $project->getId(),
-                'code' => $project->getCode(),
-                'name' => $project->getName(),
-            ],
-            'archived' => $group->isArchived(),
-        ]);
+        return json_encode(Serializer::groupFull($group));
     }
 }
diff --git a/src/Mcp/Tool/TaskMeta/ListGroupsTool.php b/src/Mcp/Tool/TaskMeta/ListGroupsTool.php
index 35cddf7..d79d32b 100644
--- a/src/Mcp/Tool/TaskMeta/ListGroupsTool.php
+++ b/src/Mcp/Tool/TaskMeta/ListGroupsTool.php
@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Mcp\Tool\TaskMeta;
 
+use App\Mcp\Tool\Serializer;
 use App\Repository\TaskGroupRepository;
 use Mcp\Capability\Attribute\McpTool;
 
@@ -23,17 +24,6 @@ class ListGroupsTool
 
         $groups = $this->taskGroupRepository->findBy($criteria, ['title' => 'ASC']);
 
-        return json_encode(array_map(fn ($g) => [
-            'id'          => $g->getId(),
-            'title'       => $g->getTitle(),
-            'description' => $g->getDescription(),
-            'color'       => $g->getColor(),
-            'project'     => [
-                'id'   => $g->getProject()->getId(),
-                'code' => $g->getProject()->getCode(),
-                'name' => $g->getProject()->getName(),
-            ],
-            'archived' => $g->isArchived(),
-        ], $groups));
+        return json_encode(array_map(Serializer::groupFull(...), $groups));
     }
 }
diff --git a/src/Mcp/Tool/TaskMeta/UpdateGroupTool.php b/src/Mcp/Tool/TaskMeta/UpdateGroupTool.php
index 3b818d8..e1c7dc0 100644
--- a/src/Mcp/Tool/TaskMeta/UpdateGroupTool.php
+++ b/src/Mcp/Tool/TaskMeta/UpdateGroupTool.php
@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Mcp\Tool\TaskMeta;
 
+use App\Mcp\Tool\Serializer;
 use App\Repository\TaskGroupRepository;
 use Doctrine\ORM\EntityManagerInterface;
 use InvalidArgumentException;
@@ -47,17 +48,6 @@ class UpdateGroupTool
 
         $this->entityManager->flush();
 
-        return json_encode([
-            'id'          => $group->getId(),
-            'title'       => $group->getTitle(),
-            'description' => $group->getDescription(),
-            'color'       => $group->getColor(),
-            'project'     => [
-                'id'   => $group->getProject()->getId(),
-                'code' => $group->getProject()->getCode(),
-                'name' => $group->getProject()->getName(),
-            ],
-            'archived' => $group->isArchived(),
-        ]);
+        return json_encode(Serializer::groupFull($group));
     }
 }
diff --git a/src/Mcp/Tool/TimeEntry/CreateTimeEntryTool.php b/src/Mcp/Tool/TimeEntry/CreateTimeEntryTool.php
index 75642c9..94ce4d6 100644
--- a/src/Mcp/Tool/TimeEntry/CreateTimeEntryTool.php
+++ b/src/Mcp/Tool/TimeEntry/CreateTimeEntryTool.php
@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace App\Mcp\Tool\TimeEntry;
 
 use App\Entity\TimeEntry;
+use App\Mcp\Tool\Serializer;
 use App\Repository\ProjectRepository;
 use App\Repository\TaskRepository;
 use App\Repository\TaskTagRepository;
@@ -92,30 +93,6 @@ class CreateTimeEntryTool
         $this->entityManager->persist($entry);
         $this->entityManager->flush();
 
-        return json_encode([
-            'id'          => $entry->getId(),
-            'title'       => $entry->getTitle(),
-            'description' => $entry->getDescription(),
-            'startedAt'   => $entry->getStartedAt()?->format('c'),
-            'stoppedAt'   => $entry->getStoppedAt()?->format('c'),
-            'duration'    => $entry->getStoppedAt() && $entry->getStartedAt()
-                ? (int) round(($entry->getStoppedAt()->getTimestamp() - $entry->getStartedAt()->getTimestamp()) / 60)
-                : null,
-            'user'    => ['id' => $user->getId(), 'username' => $user->getUsername()],
-            'project' => $entry->getProject() ? [
-                'id'   => $entry->getProject()->getId(),
-                'code' => $entry->getProject()->getCode(),
-                'name' => $entry->getProject()->getName(),
-            ] : null,
-            'task' => $entry->getTask() ? [
-                'id'     => $entry->getTask()->getId(),
-                'number' => $entry->getTask()->getNumber(),
-                'title'  => $entry->getTask()->getTitle(),
-            ] : null,
-            'tags' => $entry->getTags()->map(fn ($t) => [
-                'id'    => $t->getId(),
-                'label' => $t->getLabel(),
-            ])->toArray(),
-        ]);
+        return json_encode(Serializer::timeEntry($entry));
     }
 }
diff --git a/src/Mcp/Tool/TimeEntry/ListTimeEntriesTool.php b/src/Mcp/Tool/TimeEntry/ListTimeEntriesTool.php
index 77435c2..c949d1e 100644
--- a/src/Mcp/Tool/TimeEntry/ListTimeEntriesTool.php
+++ b/src/Mcp/Tool/TimeEntry/ListTimeEntriesTool.php
@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Mcp\Tool\TimeEntry;
 
+use App\Mcp\Tool\Serializer;
 use App\Repository\TimeEntryRepository;
 use DateTimeImmutable;
 use Mcp\Capability\Attribute\McpTool;
@@ -56,33 +57,6 @@ class ListTimeEntriesTool
 
         $entries = $qb->getQuery()->getResult();
 
-        return json_encode(array_map(fn ($entry) => [
-            'id'          => $entry->getId(),
-            'title'       => $entry->getTitle(),
-            'description' => $entry->getDescription(),
-            'startedAt'   => $entry->getStartedAt()?->format('c'),
-            'stoppedAt'   => $entry->getStoppedAt()?->format('c'),
-            'duration'    => $entry->getStoppedAt() && $entry->getStartedAt()
-                ? (int) round(($entry->getStoppedAt()->getTimestamp() - $entry->getStartedAt()->getTimestamp()) / 60)
-                : null,
-            'user' => [
-                'id'       => $entry->getUser()->getId(),
-                'username' => $entry->getUser()->getUsername(),
-            ],
-            'project' => $entry->getProject() ? [
-                'id'   => $entry->getProject()->getId(),
-                'code' => $entry->getProject()->getCode(),
-                'name' => $entry->getProject()->getName(),
-            ] : null,
-            'task' => $entry->getTask() ? [
-                'id'     => $entry->getTask()->getId(),
-                'number' => $entry->getTask()->getNumber(),
-                'title'  => $entry->getTask()->getTitle(),
-            ] : null,
-            'tags' => $entry->getTags()->map(fn ($t) => [
-                'id'    => $t->getId(),
-                'label' => $t->getLabel(),
-            ])->toArray(),
-        ], $entries));
+        return json_encode(array_map(Serializer::timeEntry(...), $entries));
     }
 }
diff --git a/src/Mcp/Tool/TimeEntry/UpdateTimeEntryTool.php b/src/Mcp/Tool/TimeEntry/UpdateTimeEntryTool.php
index 2bd514d..eb3457b 100644
--- a/src/Mcp/Tool/TimeEntry/UpdateTimeEntryTool.php
+++ b/src/Mcp/Tool/TimeEntry/UpdateTimeEntryTool.php
@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace App\Mcp\Tool\TimeEntry;
 
+use App\Mcp\Tool\Serializer;
 use App\Repository\ProjectRepository;
 use App\Repository\TaskRepository;
 use App\Repository\TaskTagRepository;
@@ -83,29 +84,6 @@ class UpdateTimeEntryTool
 
         $this->entityManager->flush();
 
-        return json_encode([
-            'id'        => $entry->getId(),
-            'title'     => $entry->getTitle(),
-            'startedAt' => $entry->getStartedAt()?->format('c'),
-            'stoppedAt' => $entry->getStoppedAt()?->format('c'),
-            'duration'  => $entry->getStoppedAt() && $entry->getStartedAt()
-                ? (int) round(($entry->getStoppedAt()->getTimestamp() - $entry->getStartedAt()->getTimestamp()) / 60)
-                : null,
-            'user'    => ['id' => $entry->getUser()->getId(), 'username' => $entry->getUser()->getUsername()],
-            'project' => $entry->getProject() ? [
-                'id'   => $entry->getProject()->getId(),
-                'code' => $entry->getProject()->getCode(),
-                'name' => $entry->getProject()->getName(),
-            ] : null,
-            'task' => $entry->getTask() ? [
-                'id'     => $entry->getTask()->getId(),
-                'number' => $entry->getTask()->getNumber(),
-                'title'  => $entry->getTask()->getTitle(),
-            ] : null,
-            'tags' => $entry->getTags()->map(fn ($t) => [
-                'id'    => $t->getId(),
-                'label' => $t->getLabel(),
-            ])->toArray(),
-        ]);
+        return json_encode(Serializer::timeEntry($entry));
     }
 }
diff --git a/src/Repository/ClientTicketRepository.php b/src/Repository/ClientTicketRepository.php
index 3f661b7..37815b0 100644
--- a/src/Repository/ClientTicketRepository.php
+++ b/src/Repository/ClientTicketRepository.php
@@ -19,15 +19,18 @@ class ClientTicketRepository extends ServiceEntityRepository
         parent::__construct($registry, ClientTicket::class);
     }
 
-    public function findNextNumberForProject(Project $project): int
+    /**
+     * Returns the next ticket number for a project, using a row-level lock
+     * to prevent race conditions when creating tickets concurrently.
+     */
+    public function findNextNumberForProjectForUpdate(Project $project): int
     {
-        $result = $this->createQueryBuilder('ct')
-            ->select('MAX(ct.number)')
-            ->where('ct.project = :project')
-            ->setParameter('project', $project)
-            ->getQuery()
-            ->getSingleScalarResult()
-        ;
+        $conn = $this->getEntityManager()->getConnection();
+
+        $result = $conn->fetchOne(
+            'SELECT COALESCE(MAX(number), 0) FROM client_ticket WHERE project_id = :project FOR UPDATE',
+            ['project' => $project->getId()],
+        );
 
         return ((int) $result) + 1;
     }
diff --git a/src/Repository/TaskRepository.php b/src/Repository/TaskRepository.php
index 342c025..d2fb050 100644
--- a/src/Repository/TaskRepository.php
+++ b/src/Repository/TaskRepository.php
@@ -9,6 +9,9 @@ use App\Entity\Task;
 use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
 use Doctrine\Persistence\ManagerRegistry;
 
+/**
+ * @extends ServiceEntityRepository<Task>
+ */
 class TaskRepository extends ServiceEntityRepository
 {
     public function __construct(ManagerRegistry $registry)
@@ -16,16 +19,19 @@ class TaskRepository extends ServiceEntityRepository
         parent::__construct($registry, Task::class);
     }
 
-    public function findMaxNumberByProject(Project $project): int
+    /**
+     * Returns the max task number for a project, using a row-level lock
+     * to prevent race conditions when creating tasks concurrently.
+     */
+    public function findMaxNumberByProjectForUpdate(Project $project): int
     {
-        $result = $this->createQueryBuilder('t')
-            ->select('MAX(t.number)')
-            ->where('t.project = :project')
-            ->setParameter('project', $project)
-            ->getQuery()
-            ->getSingleScalarResult()
-        ;
+        $conn = $this->getEntityManager()->getConnection();
 
-        return (int) ($result ?? 0);
+        $result = $conn->fetchOne(
+            'SELECT COALESCE(MAX(number), 0) FROM task WHERE project_id = :project FOR UPDATE',
+            ['project' => $project->getId()],
+        );
+
+        return (int) $result;
     }
 }
diff --git a/src/Service/BookStackApiService.php b/src/Service/BookStackApiService.php
index 39fdae7..cf4b66c 100644
--- a/src/Service/BookStackApiService.php
+++ b/src/Service/BookStackApiService.php
@@ -59,7 +59,7 @@ final class BookStackApiService
      * Search for pages and books within a specific shelf.
      *
      * Algorithm:
-     * 1. Fetch the shelf's book IDs
+     * 1. Fetch the shelf data (book IDs + slugs)
      * 2. Run two search queries (one for pages, one for books)
      * 3. Filter results: pages must belong to a book on the shelf, books must be on the shelf
      *
@@ -67,17 +67,27 @@ final class BookStackApiService
      */
     public function searchInShelf(int $shelfId, string $query): array
     {
-        $bookIds = $this->getShelfBookIds($shelfId);
+        $shelfData = $this->request('GET', sprintf('/api/shelves/%d', $shelfId));
+        $books     = $shelfData['books'] ?? [];
 
-        if (empty($bookIds)) {
+        if (empty($books)) {
             return [];
         }
 
+        $bookIds   = array_map(static fn (array $book): int => $book['id'], $books);
+        $bookSlugs = [];
+        foreach ($books as $book) {
+            $bookSlugs[$book['id']] = $book['slug'] ?? '';
+        }
+
+        // Update cache for getShelfBookIds
+        $this->shelfBookCache[$shelfId] = $bookIds;
+
         $config  = $this->getConfiguration();
         $baseUrl = rtrim($config->getUrl() ?? '', '/');
         $trimmed = trim($query);
 
-        // BookStack search API accepts {type:X} for one type at a time — run two queries
+        // BookStack search API accepts {type:X} for one type at a time -- run two queries
         $pageResults = $this->request('GET', '/api/search', [
             'query' => ['query' => $trimmed.' {type:page}', 'count' => 50],
         ]);
@@ -87,13 +97,6 @@ final class BookStackApiService
 
         $allResults = array_merge($pageResults['data'] ?? [], $bookResults['data'] ?? []);
 
-        // Build a map of bookId → bookSlug for URL construction
-        $shelfData = $this->request('GET', sprintf('/api/shelves/%d', $shelfId));
-        $bookSlugs = [];
-        foreach ($shelfData['books'] ?? [] as $book) {
-            $bookSlugs[$book['id']] = $book['slug'] ?? '';
-        }
-
         $filtered = [];
         foreach ($allResults as $item) {
             $type = $item['type'] ?? '';
@@ -101,23 +104,20 @@ final class BookStackApiService
             if ('page' === $type) {
                 $bookId = $item['book_id'] ?? 0;
                 if (in_array($bookId, $bookIds, true)) {
-                    $bookSlug   = $bookSlugs[$bookId] ?? '';
                     $filtered[] = [
                         'id'   => $item['id'],
                         'type' => 'page',
                         'name' => $item['name'] ?? '',
-                        'url'  => $baseUrl.'/books/'.$bookSlug.'/page/'.$item['slug'],
-                    ];
-                }
-            } elseif ('book' === $type) {
-                if (in_array($item['id'], $bookIds, true)) {
-                    $filtered[] = [
-                        'id'   => $item['id'],
-                        'type' => 'book',
-                        'name' => $item['name'] ?? '',
-                        'url'  => $baseUrl.'/books/'.$item['slug'],
+                        'url'  => $baseUrl.'/books/'.($bookSlugs[$bookId] ?? '').'/page/'.$item['slug'],
                     ];
                 }
+            } elseif ('book' === $type && in_array($item['id'], $bookIds, true)) {
+                $filtered[] = [
+                    'id'   => $item['id'],
+                    'type' => 'book',
+                    'name' => $item['name'] ?? '',
+                    'url'  => $baseUrl.'/books/'.$item['slug'],
+                ];
             }
         }
 
diff --git a/src/Service/GiteaApiService.php b/src/Service/GiteaApiService.php
index 46881eb..a61df03 100644
--- a/src/Service/GiteaApiService.php
+++ b/src/Service/GiteaApiService.php
@@ -126,9 +126,10 @@ final readonly class GiteaApiService
 
         $regex = sprintf('#^[^/]+/%s($|-.+)#', preg_quote($taskCode, '#'));
 
-        return array_values(array_filter($allBranches, static function (array $branch) use ($regex): bool {
-            return 1 === preg_match($regex, $branch['name']);
-        }));
+        return array_values(array_filter(
+            $allBranches,
+            static fn (array $branch): bool => 1 === preg_match($regex, $branch['name']),
+        ));
     }
 
     /**
diff --git a/src/Service/NotificationService.php b/src/Service/NotificationService.php
index d2d9917..20d4639 100644
--- a/src/Service/NotificationService.php
+++ b/src/Service/NotificationService.php
@@ -52,12 +52,12 @@ final readonly class NotificationService
             return;
         }
 
-        $number      = sprintf('CT-%03d', $ticket->getNumber());
-        $statusLabel = $ticket->getStatus();
-        $message     = 'Nouveau statut : '.$statusLabel;
+        $number        = sprintf('CT-%03d', $ticket->getNumber());
+        $statusComment = $ticket->getStatusComment();
+        $message       = 'Nouveau statut : '.$ticket->getStatus();
 
-        if (null !== $ticket->getStatusComment() && '' !== $ticket->getStatusComment()) {
-            $message .= ' — '.$ticket->getStatusComment();
+        if (null !== $statusComment && '' !== $statusComment) {
+            $message .= ' — '.$statusComment;
         }
 
         $notification = new Notification();
diff --git a/src/Service/TokenEncryptor.php b/src/Service/TokenEncryptor.php
index 3038820..4ba94ce 100644
--- a/src/Service/TokenEncryptor.php
+++ b/src/Service/TokenEncryptor.php
@@ -17,31 +17,10 @@ final class TokenEncryptor
         #[Autowire('%env(ENCRYPTION_KEY)%')]
         string $encryptionKey,
     ) {
-        if ('' === $encryptionKey) {
-            $this->key        = '';
-            $this->configured = false;
+        $key = $this->tryDecodeKey($encryptionKey);
 
-            return;
-        }
-
-        try {
-            $key = sodium_hex2bin($encryptionKey);
-        } catch (SodiumException) {
-            $this->key        = '';
-            $this->configured = false;
-
-            return;
-        }
-
-        if (SODIUM_CRYPTO_SECRETBOX_KEYBYTES !== mb_strlen($key, '8bit')) {
-            $this->key        = '';
-            $this->configured = false;
-
-            return;
-        }
-
-        $this->key        = $key;
-        $this->configured = true;
+        $this->key        = $key ?? '';
+        $this->configured = null !== $key;
     }
 
     public function encrypt(string $plaintext): string
@@ -71,6 +50,25 @@ final class TokenEncryptor
         return $plaintext;
     }
 
+    private function tryDecodeKey(string $encryptionKey): ?string
+    {
+        if ('' === $encryptionKey) {
+            return null;
+        }
+
+        try {
+            $key = sodium_hex2bin($encryptionKey);
+        } catch (SodiumException) {
+            return null;
+        }
+
+        if (SODIUM_CRYPTO_SECRETBOX_KEYBYTES !== mb_strlen($key, '8bit')) {
+            return null;
+        }
+
+        return $key;
+    }
+
     private function assertConfigured(): void
     {
         if (!$this->configured) {
diff --git a/src/State/ClientTicketNumberProcessor.php b/src/State/ClientTicketNumberProcessor.php
index c985332..f96e4ba 100644
--- a/src/State/ClientTicketNumberProcessor.php
+++ b/src/State/ClientTicketNumberProcessor.php
@@ -51,12 +51,13 @@ final readonly class ClientTicketNumberProcessor implements ProcessorInterface
             }
         }
 
-        $nextNumber = $this->clientTicketRepository->findNextNumberForProject($project);
-        $data->setNumber($nextNumber);
+        $now = new DateTimeImmutable();
+
+        $data->setNumber($this->clientTicketRepository->findNextNumberForProjectForUpdate($project));
         $data->setSubmittedBy($user);
         $data->setStatus('new');
-        $data->setCreatedAt(new DateTimeImmutable());
-        $data->setUpdatedAt(new DateTimeImmutable());
+        $data->setCreatedAt($now);
+        $data->setUpdatedAt($now);
 
         $this->entityManager->persist($data);
         $this->entityManager->flush();
diff --git a/src/State/ClientTicketProvider.php b/src/State/ClientTicketProvider.php
index ee1dcbd..6e2dd23 100644
--- a/src/State/ClientTicketProvider.php
+++ b/src/State/ClientTicketProvider.php
@@ -54,17 +54,27 @@ final readonly class ClientTicketProvider implements ProviderInterface
         // Apply filters from query parameters
         $filters = $context['filters'] ?? [];
         if (isset($filters['project'])) {
-            $projectId = is_numeric($filters['project']) ? (int) $filters['project'] : (int) basename($filters['project']);
-            $qb->andWhere('ct.project = :project')->setParameter('project', $projectId);
+            $qb->andWhere('ct.project = :project')
+                ->setParameter('project', self::extractId($filters['project']))
+            ;
         }
         if (isset($filters['status'])) {
             $qb->andWhere('ct.status = :status')->setParameter('status', $filters['status']);
         }
         if (isset($filters['submittedBy']) && $this->security->isGranted('ROLE_ADMIN')) {
-            $submittedById = is_numeric($filters['submittedBy']) ? (int) $filters['submittedBy'] : (int) basename($filters['submittedBy']);
-            $qb->andWhere('ct.submittedBy = :submittedBy')->setParameter('submittedBy', $submittedById);
+            $qb->andWhere('ct.submittedBy = :submittedBy')
+                ->setParameter('submittedBy', self::extractId($filters['submittedBy']))
+            ;
         }
 
         return $qb->getQuery()->getResult();
     }
+
+    /**
+     * Extract an entity ID from a value that may be a numeric ID or an IRI string.
+     */
+    private static function extractId(string $value): int
+    {
+        return is_numeric($value) ? (int) $value : (int) basename($value);
+    }
 }
diff --git a/src/State/ClientTicketStatusProcessor.php b/src/State/ClientTicketStatusProcessor.php
index 747f295..7248cb6 100644
--- a/src/State/ClientTicketStatusProcessor.php
+++ b/src/State/ClientTicketStatusProcessor.php
@@ -35,18 +35,21 @@ final readonly class ClientTicketStatusProcessor implements ProcessorInterface
 
         $originalData = $context['previous_data'] ?? null;
 
-        // ROLE_CLIENT: can only edit content fields, not status
-        if (!$this->security->isGranted('ROLE_ADMIN') && $originalData instanceof ClientTicket) {
-            $data->setStatus($originalData->getStatus());
-            $data->setStatusComment($originalData->getStatusComment());
-        }
+        $statusChanged = false;
 
         if ($originalData instanceof ClientTicket) {
+            // ROLE_CLIENT: can only edit content fields, not status
+            if (!$this->security->isGranted('ROLE_ADMIN')) {
+                $data->setStatus($originalData->getStatus());
+                $data->setStatusComment($originalData->getStatusComment());
+            }
+
             $oldStatus = $originalData->getStatus();
             $newStatus = $data->getStatus();
 
             if ($oldStatus !== $newStatus) {
-                $forbidden = self::FORBIDDEN_TRANSITIONS[$oldStatus] ?? [];
+                $statusChanged = true;
+                $forbidden     = self::FORBIDDEN_TRANSITIONS[$oldStatus] ?? [];
                 if (in_array($newStatus, $forbidden, true)) {
                     throw new BadRequestHttpException(sprintf('Transition from "%s" to "%s" is not allowed.', $oldStatus, $newStatus));
                 }
@@ -62,7 +65,9 @@ final readonly class ClientTicketStatusProcessor implements ProcessorInterface
         $this->entityManager->persist($data);
         $this->entityManager->flush();
 
-        $this->notificationService->createForStatusChange($data);
+        if ($statusChanged) {
+            $this->notificationService->createForStatusChange($data);
+        }
 
         return $data;
     }
diff --git a/src/State/GiteaBranchNameProvider.php b/src/State/GiteaBranchNameProvider.php
index 42fba49..d226b62 100644
--- a/src/State/GiteaBranchNameProvider.php
+++ b/src/State/GiteaBranchNameProvider.php
@@ -15,6 +15,7 @@ use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 
 final readonly class GiteaBranchNameProvider implements ProviderInterface
 {
+    /** @see GiteaBranchProcessor::ALLOWED_TYPES */
     private const array ALLOWED_TYPES = ['feature', 'fix', 'refactor', 'hotfix', 'chore'];
 
     public function __construct(
diff --git a/src/State/TaskDocumentProcessor.php b/src/State/TaskDocumentProcessor.php
index aa98f63..d32d3cb 100644
--- a/src/State/TaskDocumentProcessor.php
+++ b/src/State/TaskDocumentProcessor.php
@@ -24,6 +24,35 @@ final readonly class TaskDocumentProcessor implements ProcessorInterface
 {
     private const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50 MB
 
+    private const ALLOWED_MIME_TYPES = [
+        'image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml',
+        'application/pdf',
+        'application/msword',
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        'application/vnd.ms-excel',
+        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        'application/vnd.ms-powerpoint',
+        'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+        'text/plain', 'text/csv',
+        'application/zip', 'application/x-rar-compressed', 'application/gzip',
+        'application/json', 'application/xml', 'text/xml',
+    ];
+
+    private const MIME_TO_EXTENSION = [
+        'image/jpeg'                                                                => 'jpg', 'image/png' => 'png', 'image/gif' => 'gif',
+        'image/webp'                                                                => 'webp', 'image/svg+xml' => 'svg',
+        'application/pdf'                                                           => 'pdf',
+        'application/msword'                                                        => 'doc',
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document'   => 'docx',
+        'application/vnd.ms-excel'                                                  => 'xls',
+        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'         => 'xlsx',
+        'application/vnd.ms-powerpoint'                                             => 'ppt',
+        'application/vnd.openxmlformats-officedocument.presentationml.presentation' => 'pptx',
+        'text/plain'                                                                => 'txt', 'text/csv' => 'csv',
+        'application/zip'                                                           => 'zip', 'application/x-rar-compressed' => 'rar', 'application/gzip' => 'gz',
+        'application/json'                                                          => 'json', 'application/xml' => 'xml', 'text/xml' => 'xml',
+    ];
+
     public function __construct(
         private EntityManagerInterface $entityManager,
         private Security $security,
@@ -52,50 +81,48 @@ final readonly class TaskDocumentProcessor implements ProcessorInterface
             throw new BadRequestHttpException('File size exceeds 50 MB limit.');
         }
 
-        $taskIri         = $request->request->get('task');
-        $clientTicketIri = $request->request->get('clientTicket');
+        $taskIri         = $request->request->get('task', '');
+        $clientTicketIri = $request->request->get('clientTicket', '');
 
-        if ((null === $taskIri || '' === $taskIri) && (null === $clientTicketIri || '' === $clientTicketIri)) {
+        if ('' === $taskIri && '' === $clientTicketIri) {
             throw new BadRequestHttpException('Either task or clientTicket IRI is required.');
         }
 
         $task         = null;
         $clientTicket = null;
 
-        if (null !== $taskIri && '' !== $taskIri) {
-            // Extract task ID from IRI (e.g., "/api/tasks/42" -> 42)
-            $taskId = (int) basename((string) $taskIri);
-            $task   = $this->entityManager->getRepository(Task::class)->find($taskId);
+        if ('' !== $taskIri) {
+            $task = $this->entityManager->getRepository(Task::class)->find((int) basename($taskIri));
 
             if (null === $task) {
                 throw new BadRequestHttpException('Task not found.');
             }
         }
 
-        if (null !== $clientTicketIri && '' !== $clientTicketIri) {
-            $clientTicketId = (int) basename((string) $clientTicketIri);
-            $clientTicket   = $this->entityManager->getRepository(ClientTicket::class)->find($clientTicketId);
+        if ('' !== $clientTicketIri) {
+            $clientTicket = $this->entityManager->getRepository(ClientTicket::class)->find((int) basename($clientTicketIri));
 
             if (null === $clientTicket) {
                 throw new BadRequestHttpException('Client ticket not found.');
             }
 
-            // Ownership validation for ROLE_CLIENT
-            if (!$this->security->isGranted('ROLE_ADMIN')) {
-                $currentUser = $this->security->getUser();
-                if ($clientTicket->getSubmittedBy() !== $currentUser) {
-                    throw new AccessDeniedHttpException('You can only upload documents to your own tickets.');
-                }
+            if (!$this->security->isGranted('ROLE_ADMIN') && $clientTicket->getSubmittedBy() !== $this->security->getUser()) {
+                throw new AccessDeniedHttpException('You can only upload documents to your own tickets.');
             }
         }
 
-        // Capture file metadata BEFORE move() — move invalidates the temp file
+        // Use server-detected MIME type (finfo), not the client-supplied one
         $originalName = $file->getClientOriginalName();
-        $extension    = $file->getClientOriginalExtension() ?: 'bin';
-        $mimeType     = $file->getClientMimeType() ?? 'application/octet-stream';
+        $mimeType     = $file->getMimeType() ?: 'application/octet-stream';
         $fileSize     = $file->getSize();
-        $uuid         = Uuid::v4()->toRfc4122();
-        $fileName     = $uuid.'.'.$extension;
+
+        if (!in_array($mimeType, self::ALLOWED_MIME_TYPES, true)) {
+            throw new BadRequestHttpException(sprintf('File type "%s" is not allowed.', $mimeType));
+        }
+
+        $extension = self::MIME_TO_EXTENSION[$mimeType] ?? 'bin';
+        $uuid      = Uuid::v4()->toRfc4122();
+        $fileName  = $uuid.'.'.$extension;
 
         if (!is_dir($this->uploadDir)) {
             mkdir($this->uploadDir, 0o775, true);
diff --git a/src/State/TaskNumberProcessor.php b/src/State/TaskNumberProcessor.php
index 480a36f..f8e5b23 100644
--- a/src/State/TaskNumberProcessor.php
+++ b/src/State/TaskNumberProcessor.php
@@ -9,6 +9,7 @@ use ApiPlatform\Metadata\Post;
 use ApiPlatform\State\ProcessorInterface;
 use App\Entity\Task;
 use App\Repository\TaskRepository;
+use Doctrine\ORM\EntityManagerInterface;
 use Symfony\Component\DependencyInjection\Attribute\Autowire;
 
 /**
@@ -23,6 +24,7 @@ final readonly class TaskNumberProcessor implements ProcessorInterface
         #[Autowire(service: 'api_platform.doctrine.orm.state.persist_processor')]
         private ProcessorInterface $persistProcessor,
         private TaskRepository $taskRepository,
+        private EntityManagerInterface $entityManager,
     ) {}
 
     /**
@@ -31,8 +33,12 @@ final readonly class TaskNumberProcessor implements ProcessorInterface
     public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
     {
         if ($operation instanceof Post && null !== $data->getProject()) {
-            $maxNumber = $this->taskRepository->findMaxNumberByProject($data->getProject());
-            $data->setNumber($maxNumber + 1);
+            return $this->entityManager->wrapInTransaction(function () use ($data, $operation, $uriVariables, $context) {
+                $maxNumber = $this->taskRepository->findMaxNumberByProjectForUpdate($data->getProject());
+                $data->setNumber($maxNumber + 1);
+
+                return $this->persistProcessor->process($data, $operation, $uriVariables, $context);
+            });
         }
 
         return $this->persistProcessor->process($data, $operation, $uriVariables, $context);
diff --git a/src/State/UserPasswordHasherProcessor.php b/src/State/UserPasswordHasherProcessor.php
index d4a9437..06ef694 100644
--- a/src/State/UserPasswordHasherProcessor.php
+++ b/src/State/UserPasswordHasherProcessor.php
@@ -29,10 +29,10 @@ final readonly class UserPasswordHasherProcessor implements ProcessorInterface
      */
     public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = []): mixed
     {
-        if (null !== $data->getPassword() && !str_starts_with($data->getPassword(), '$')) {
-            $data->setPassword(
-                $this->passwordHasher->hashPassword($data, $data->getPassword())
-            );
+        $plainPassword = $data->getPassword();
+
+        if (null !== $plainPassword && !str_starts_with($plainPassword, '$')) {
+            $data->setPassword($this->passwordHasher->hashPassword($data, $plainPassword));
         }
 
         return $this->persistProcessor->process($data, $operation, $uriVariables, $context);