init

.junie/plans/migrate-seaorm-2-model-relations.md

@@ -0,0 +1,106 @@
+---
+sessionId: session-260713-090509-126z
+---
+
+# Requirements
+
+### Objectif
+Migrer les entités SeaORM de `src/models` du format `Relation`/`DeriveRelation`/`Related` vers le format SeaORM 2.x basé sur `#[sea_orm::model]`, avec les relations `HasOne` et `HasMany`, sans modifier le schéma SQL ni les contrats applicatifs.
+
+### Périmètre inclus
+- Migrer les quatre modèles pilotes `attachment`, `category`, `channel` et `message`.
+- Migrer ensuite les autres entités présentes sous `src/models` : `server`, `user`, `role`, `server_user`, `role_user`, `channel_user`, `channel_user_permission`, `channel_role_permission`, `server_user_permission`, `server_role_permission` et `computed_permission`.
+- Préserver les noms de tables/colonnes, les types nullable, les clés primaires et les comportements `Cascade`, `SetNull` et `NoAction`.
+- Conserver les implémentations `ActiveModelBehavior` et leurs valeurs par défaut (`Uuid::new_v4`/`Uuid::now_v7`, `is_default`, etc.).
+- Utiliser la syntaxe effectivement supportée par `sea-orm 2.0.0-rc.42`.
+
+### Hors périmètre
+- Aucun changement dans `src/repositories`, `src/routes`, DTO, réponses HTTP ou frontend.
+- Aucun changement dans `migration/src/m20220101_000001_create_table.rs` ou dans le schéma SQL.
+- Aucun ajout de tests spécifiques demandé dans cette étape.
+- Aucun mapping ORM artificiel pour `computed_permission.resource_id`, qui reste polymorphe entre serveur, catégorie et channel.
+
+### Critères d’acceptation
+- Chaque entité migrée utilise un seul format SeaORM 2.x, sans ancien enum `Relation` ou `impl Related` résiduel inutile.
+- Les relations pilotes compilent avec la release candidate déclarée.
+- La relation auto-référente de `Message` expose un parent optionnel et plusieurs réponses, avec `SetNull` à la suppression du parent.
+- Les champs relationnels ne deviennent pas des colonnes d’`ActiveModel`.
+- Les commandes de compilation intermédiaires et finales réussissent, sans exiger à ce stade l’adaptation des repositories.
+
+# Technical Design
+
+### État actuel
+- `Cargo.toml` déclare `sea-orm = 2.0.0-rc.42` avec les backends SQLite/Postgres/MySQL et `schema-sync`; le workspace utilise Rust édition 2024.
+- Les fichiers `src/models/attachment.rs`, `category.rs`, `channel.rs` et `message.rs` utilisent actuellement `DeriveEntityModel`, un enum `Relation` avec `DeriveRelation`, puis des `impl Related<...>`.
+- `message.rs` contient déjà les cas particuliers `reply_to_id: Option<Uuid>`, `ReplyTo` auto-référent avec `SetNull` et `Replies` via `via_rel`.
+- `channel.rs` combine relations vers des champs nullable (`server_id`, `category_id`), une relation `HasMany` vers les messages et l’enum SQL `ChannelType`.
+- Les autres entités suivent le même patron généré; leurs relations existantes doivent être transposées sans élargir le périmètre fonctionnel.
+- `src/repositories/server.rs` utilise `category::Entity::find().find_with_related(channel::Entity)`. Cet usage est explicitement laissé inchangé pour cette étape; la compatibilité de compilation sera constatée, et son adaptation fera l’objet d’une étape ultérieure si nécessaire.
+
+### Décisions
+- **Migration incrémentale** : commencer par `attachment`, `category`, `channel`, `message`, lancer `cargo check`, puis migrer les entités restantes par groupes dépendants.
+- **Relations dans `Model`** : représenter les relations parent/enfant avec les types SeaORM 2.x validés par la release candidate (`HasOne`/`HasMany` ou leur forme exacte requise), en conservant les cardinalités et actions SQL.
+- **Schéma inchangé** : les attributs de relation refléteront les migrations existantes; aucune migration SQL ne sera ajoutée.
+- **Polymorphisme explicite** : ne pas déclarer de relation sur `computed_permission.resource_id`.
+- **ActiveModel séparé** : vérifier que les champs de relation sont ignorés par les insertions/mises à jour et que les constructeurs `new()` restent inchangés.
+
+### Modifications proposées
+- Dans chaque fichier `src/models/*.rs`, ajouter l’attribut de modèle SeaORM 2.x et déplacer les relations du bloc `Relation` vers les champs relationnels de `Model`.
+- Remplacer les `impl Related` et les enums `Relation` devenus inutiles, sans modifier les champs scalaires ni les dérivations nécessaires aux DTO/OpenAPI.
+- Pour `message.rs`, représenter `channel`, `user`, `reply_to`, `attachments` et `replies`; préserver la relation inverse auto-référente et l’action `on_delete = SetNull`.
+- Pour `channel.rs`, conserver `Category`, `Server`, `Message` et `ChannelUser`, avec les relations optionnelles cohérentes avec `category_id` et `server_id`.
+- Pour `server.rs`, `user.rs`, `role.rs` et les tables de jonction/permissions, transposer les relations présentes dans leurs enums actuels et vérifier les colonnes source/cible contre la migration.
+- Ne pas modifier `src/models/mod.rs` ou `prelude.rs` sauf si la syntaxe SeaORM 2.x l’exige pour résoudre les types d’entités.
+
+### Fichiers concernés
+- Pilote : `src/models/attachment.rs`, `src/models/category.rs`, `src/models/channel.rs`, `src/models/message.rs`.
+- Lots suivants : `src/models/server.rs`, `user.rs`, `role.rs`, `server_user.rs`, `role_user.rs`, `channel_user.rs`, `channel_user_permission.rs`, `channel_role_permission.rs`, `server_user_permission.rs`, `server_role_permission.rs`, `computed_permission.rs`.
+- Référence en lecture seule : `migration/src/m20220101_000001_create_table.rs`.
+- Explicitement non modifiés : `src/repositories/**`, `src/routes/**`, `frontend/**` et les migrations.
+
+### Risques et garde-fous
+- La syntaxe de `#[sea_orm::model]` et des relations auto-référentes peut différer entre la documentation stable et `rc.42`; valider la version verrouillée avant d’écrire les modèles.
+- Les relations inverses et les relations multiples vers la même entité peuvent provoquer des ambiguïtés de nommage; utiliser des noms de champs distincts et compiler après chaque groupe.
+- Une compilation peut révéler que `find_with_related` nécessite encore l’ancien trait `Related`; ne pas corriger les repositories dans cette étape, mais documenter précisément le blocage pour la suite.
+- Comparer chaque relation avec la migration pour éviter de transformer une colonne polymorphe ou nullable en relation incorrecte.
+
+# Testing
+
+### Validation autorisée
+La validation est volontairement limitée à la compilation, conformément au périmètre demandé.
+
+- Après le groupe pilote, exécuter `cargo check`.
+- Après chaque groupe d’entités restant, exécuter `cargo check`.
+- En fin de migration, exécuter `cargo fmt --all -- --check` puis `cargo check`.
+- Vérifier par recherche statique que les entités migrées ne contiennent plus d’ancien enum `Relation` ou d’`impl Related` inutile.
+- Vérifier manuellement que les repositories et routes n’ont pas été modifiés; leurs adaptations et tests relationnels sont reportés.
+
+# Delivery Steps
+
+### ✓ Step 1: Migrer les quatre modèles pilotes
+Les entités pilotes utilisent le format SeaORM 2.x et compilent avec la release candidate verrouillée.
+
+- Adapter `src/models/attachment.rs`, `category.rs`, `channel.rs` et `message.rs`.
+- Déclarer les relations dans `Model` avec les types et la syntaxe exacts supportés par `sea-orm 2.0.0-rc.42`.
+- Préserver `ChannelType`, les champs optionnels et les actions `Cascade`, `SetNull` et `NoAction`.
+- Représenter dans `message.rs` le parent `reply_to` et les `replies` sans relation sur une colonne polymorphe.
+- Exécuter `cargo check` immédiatement après ce pilote.
+
+### ✓ Step 2: Migrer les entités de base et de jonction
+Les modèles de serveurs, utilisateurs, rôles et tables de jonction sont convertis sans changement de colonnes SQL.
+
+- Migrer `server.rs`, `user.rs`, `role.rs`, `server_user.rs`, `role_user.rs` et `channel_user.rs`.
+- Migrer les entités de permissions `channel_user_permission.rs`, `channel_role_permission.rs`, `server_user_permission.rs` et `server_role_permission.rs`.
+- Transposer chaque relation existante avec ses colonnes source/cible et sa cardinalité.
+- Conserver les implémentations `ActiveModelBehavior` et les valeurs par défaut propres à chaque modèle.
+- Exécuter `cargo check` après ce groupe.
+
+### ✓ Step 3: Finaliser le modèle polymorphe et nettoyer les anciens patrons
+Toutes les entités de `src/models` utilisent exclusivement le format SeaORM 2.x, tandis que `computed_permission` conserve son champ polymorphe sans faux lien ORM.
+
+- Migrer `src/models/computed_permission.rs` en conservant `resource_id` comme simple colonne.
+- Supprimer dans les entités migrées les enums `Relation`, dérivations et `impl Related` devenus inutiles.
+- Vérifier que les relations ne sont pas incluses dans les colonnes d’`ActiveModel`.
+- Contrôler les noms de champs relationnels et les éventuelles ambiguïtés de relations multiples.
+- Exécuter `cargo fmt --all -- --check` puis `cargo check`.
+- Ne modifier ni repositories, ni routes, ni migrations; relever séparément toute incompatibilité de `find_with_related` pour une future étape.