ldc-cocotte/REGLES METIERS.md

10 KiB

Règles Métiers du projet

Les règles reposent sur le code de la partie Domaine.

1. Planification des Retraits

La sélection du retrait se fait désormais sur une journée complète et non plus par tranches horaires via PickupSchedulingService.

  • Jour de retrait standard : Uniquement le Vendredi (PICKUP_DAY = WeekDay::Friday).
  • Heure de clôture (Cutoff) : Lundi à 14h00 (Europe/Paris) de la même semaine (CUTOFF_DAY = Monday, CUTOFF_HOUR = 14).
    • Comportement : Une commande validée avant Lundi 14h00 (<= 14:00:00 Europe/Paris) est préparée pour le vendredi en cours. Passé ce délai, nextPickup() et currentCutoff() basculent automatiquement sur le vendredi et le lundi de la semaine suivante.
    • Lundis fériés : Si un lundi (CUTOFF_DAY) est un jour férié, la prise de commande et le cutoff restent inchangés (seuls les jours de retrait sont affectés par les jours fériés).
  • Fuseaux horaires & Persistance BDD (MySQL) :
    • Toute la logique métier du cutoff et des jours de retrait opère en Europe/Paris.
    • En base de données (config('app.timezone') = 'UTC'), toutes les colonnes datetime/timestamp sont converties et stockées en UTC via App\Casts\UtcDatetimeCast (et converties côté requêtes BO depuis client_timezone via ConvertsClientDatesToUtc), puis affichées au fuseau local via Date::forHumans() / Date::toLocalInput().
    • Les colonnes SQL DATE calendaires sans heure (pickup_exceptions.date, replacement_date, pickup_day, employees.start_date/end_date, stats.date) utilisent App\Casts\CalendarDateCast afin d'être stockées en Y-m-d sans décalage horaire ni perte d'un jour, et affichées via Date::forHumansDate().
  • Gestion des Exceptions & Jours fériés :
    • Les fermetures et jours fériés sont gérés via des ShopPickupException.
    • Une exception peut fermer le retrait, ou proposer un jour de remplacement. Ce jour de remplacement peut posséder sa propre limite de validation (orderDeadlineAt).
    • Une tâche planifiée EnsurePublicHolidaysSyncedJob synchronise les jours fériés de la zone Métropole (calendrier.api.gouv.fr/jours-feries/metropole/:year.json, hors Alsace-Moselle) pour toutes les boutiques existantes (UpsertShopsPickupExceptionsForYear).
    • Lors de la création d'une nouvelle boutique (CreateShop), les jours fériés déjà synchronisés (auto_updated = true, année courante et suivantes) lui sont automatiquement rattachés.

2. Limites de Montants

Les montants pouvant être commandés sont gérés par un service dédié CustomerOrderLimitPolicy

  • Plafond par commande : 200€ max (maxOrderAmountCents = 20000). Lève une OrderLimitExceededException.
  • Plafond hebdomadaire : 200€ max par client sur l'ensemble de la semaine (maxWeeklyAmountCents = 20000). Lève une WeeklyLimitExceededException.

3. Disponibilité des Produits

Elle est géré par le service ProductAvailabilityService.

  • Conditions d'ajout au panier :

    • Le produit est actif (status = true).
    • Il est éligible INCO (hasInco = true).
    • La date actuelle est supérieure ou égale à orderable_start (si défini).
    • La date actuelle est inférieure à orderable_end (si défini).

4. Statut Actif du Salarié

Elle est vérifiée côté Domaine par Shopper::isActive() et côté Eloquent par Employee::isActive / Employee::scopeActive().

  • Fuseau calendaire (Europe/Paris) :

    • En base de données, start_date et end_date sont des colonnes SQL DATE (sans heure ni fuseau, chargées via CalendarDateCast).
    • L'activation et la désactivation sont évaluées par rapport à la date calendaire du jour en Europe/Paris (00:00:00 Europe/Paris), afin d'éviter le décalage nocturne de 1 h à 2 h lié à UTC.
  • Date de début (start_date) :

    • Le salarié est actif lorsque start_date est inférieure ou égale au jour courant en Europe/Paris (ou si start_date est null en base de données).
    • Un salarié dont la start_date est dans le futur est considéré comme inactif jusqu'à la date d'effet (00:00:00 Europe/Paris du jour de début).
  • Date de fin (end_date) :

    • Le salarié est actif uniquement si end_date est null ou strictement supérieure au jour courant en Europe/Paris (end_date > aujourd'hui Europe/Paris).
    • Comportement assumé : le salarié devient donc inactif dès 00:00:00 Europe/Paris de son dernier jour renseigné (end_date).

5. Cycle de Vie, Tunnel de Commande & Annulation (Back-Office)

Statuts des commandes (Domain\Enums\OrderStatus)

  • WAITING ('waiting') : reliquat historique des commandes créées avant la refonte (paniers non transformés). Conservé en lecture dans les statistiques historiques.
  • PENDING ('pending') : commande technique créée lors de PlacePendingOrder avant l'export Régate. Elle est comptabilisée dans le plafond hebdomadaire de 200 € (EloquentEmployeeStatisticsService), masquée en Front-Office (GetFoCustomerPaginatedOrdersQuery, Frontend\OrderPolicy::viewOwn) et masquée par défaut en Back-Office (affichable à la demande via le filtre statut).
  • VALIDATED ('validated') : commande confirmée après succès de l'export Régate (ConfirmPlacedOrder).
  • FAILED ('failed') : statut technique en cas d'échec de l'export Régate (FailPendingOrder) ou d'expiration d'une commande PENDING bloquée au-delà de 10 minutes (FailStalePendingOrders / FailStalePendingOrdersJob, planifié toutes les 5 minutes). Masqué en Front-Office, affichable à la demande en Back-Office, exclu du plafond hebdomadaire et des statistiques.
  • CANCELED ('canceled') : annulation métier (Back-Office ou Régate).

Concurrence du tunnel & suivi des paniers non transformés

  • Lors de la soumission finale (TunnelController::confirmationSubmit()), un verrou distribué non bloquant (order:checkout:shopper:{id}, waitSeconds: 0, TTL 60s) protège la séquence synchrone PlacePendingOrder (elle-même protégée par #[Locked] sur order:finalize:shopper:{id}) → ExportOrderToRegate → ConfirmPlacedOrder / FailPendingOrder.
  • Les entrées dans le tunnel (étape 1, OrderTunnelService::initializeFromBasket) créent ou réutilisent une tentative en session dans order_tunnel_attempts (TunnelAttemptTrackerService::recordEntry), marquée convertie lors de la validation (markConverted) ou réinitialisée en session si le panier est vidé (BasketRemoved → ResetTunnelAttemptOnBasketRemoved). StatsService::getNbWaitingCmd() (et getCanceledRate()) additionnent les commandes historiques WAITING et les tentatives order_tunnel_attempts non converties (converted_at IS NULL).

Annulation de Commande (Back-Office)

Elle est autorisée côté HTTP par App\Policies\Backend\OrderPolicy::cancel() et exécutée côté Domaine par Domain\Services\OrderService::cancelOrder().

  • Statuts autorisés & date de retrait (pickup_day) : Backend\OrderPolicy::cancel() interdit d'annuler une commande déjà CANCELED, PENDING ou FAILED, mais autorise intentionnellement un administrateur à annuler toute commande métier (WAITING ou VALIDATED), y compris lorsque pickup_day est déjà dépassé (rattrapage/correction administrative).
  • Comportement assumé : l'annulation d'une commande depuis le Back-Office met uniquement à jour son statut en base de données (cancel() puis persist()) sans émettre d'événement de domaine ni envoyer d'e-mail ou de notification à Régate ou au client.

6. Code d'Accès Salarié & Inscription

La génération des codes d'accès salariés est gérée par App\Services\CodeGenerationService et leur validation à l'inscription par App\Http\Requests\Fo\Auth\RegisterRequest.

  • Génération déterministe du code :
    • Chaque code d'accès (Code, longueur 7) est dérivé de façon déterministe à partir du matricule du salarié via SerialCasterBuilder (Code::ALLOWED_CHARACTERS, Code::LENGTH). Il ne s'agit pas d'un secret aléatoire, mais d'un code d'appariement court lié au matricule.
  • Validation à l'inscription (RegisterRequest) :
    • L'existence d'un matricule non encore associé à un compte client (employees.customer_id IS NULL) est validée explicitement (Rule::exists('employees', 'matricule')->whereNull('customer_id')), séparément de la règle sur code (Rule::exists('employees', 'code')->where('matricule', ...)->whereNull('customer_id')).
    • Les messages d'erreur distincts entre « matricule inconnu / déjà utilisé » et « code incorrect » sont assumés pour faciliter le support utilisateur, les routes d'authentification étant protégées par un rate limiter (throttle).

7. Connexion d'un Compte Non Activé (CRM & laravel/ui)

Elle est gérée par App\Auth\CrmUserProvider::validateCredentials() et App\Http\Controllers\Fo\Auth\LoginController::authenticated().

  • Validation CRM (CrmService::login()) :
    • L'API CRM (Api\V4\CustomerController::authenticate()) vérifie d'abord le mot de passe (ApiError::authFailed) avant de vérifier si le compte est activé (ApiError::customerNotActivated → CrmCustomerNotActivatedException).
  • Alignement sur laravel/ui (VerificationController) :
    • Conformément au fonctionnement standard de laravel/ui, VerificationController requiert une session authentifiée (auth:frontend) pour accéder aux routes email/verify, email/verify/{id}/{hash} et email/resend.
    • Lorsqu'un client saisit le bon mot de passe sur un compte non encore activé, CrmUserProvider::validateCredentials() intercepte CrmCustomerNotActivatedException, renvoie l'e-mail de vérification et retourne true afin d'ouvrir la session et de laisser le middleware verified (EnsureCustomerEmailIsVerified) rediriger vers fo.auth.verification.notice.
    • En revanche, LoginController::authenticated() ne flashe le message "You are logged in!" que si l'e-mail du client est déjà vérifié (AppCustomerAuthService::hasVerifiedEmail()).