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()etcurrentCutoff()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).
- Comportement : Une commande validée avant Lundi 14h00 (
- 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 colonnesdatetime/timestampsont converties et stockées en UTC viaApp\Casts\UtcDatetimeCast(et converties côté requêtes BO depuisclient_timezoneviaConvertsClientDatesToUtc), puis affichées au fuseau local viaDate::forHumans()/Date::toLocalInput(). - Les colonnes SQL
DATEcalendaires sans heure (pickup_exceptions.date,replacement_date,pickup_day,employees.start_date/end_date,stats.date) utilisentApp\Casts\CalendarDateCastafin d'être stockées enY-m-dsans décalage horaire ni perte d'un jour, et affichées viaDate::forHumansDate().
- Toute la logique métier du cutoff et des jours de retrait opère en
- 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
EnsurePublicHolidaysSyncedJobsynchronise 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.
- Les fermetures et jours fériés sont gérés via des
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 uneOrderLimitExceededException. - Plafond hebdomadaire : 200€ max par client sur l'ensemble de la semaine (
maxWeeklyAmountCents = 20000). Lève uneWeeklyLimitExceededException.
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).
- Le produit est actif (
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_dateetend_datesont des colonnes SQLDATE(sans heure ni fuseau, chargées viaCalendarDateCast). - 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.
- En base de données,
-
Date de début (
start_date) :- Le salarié est actif lorsque
start_dateest inférieure ou égale au jour courant enEurope/Paris(ou sistart_dateestnullen base de données). - Un salarié dont la
start_dateest dans le futur est considéré comme inactif jusqu'à la date d'effet (00:00:00 Europe/Parisdu jour de début).
- Le salarié est actif lorsque
-
Date de fin (
end_date) :- Le salarié est actif uniquement si
end_dateestnullou strictement supérieure au jour courant enEurope/Paris(end_date > aujourd'hui Europe/Paris). - Comportement assumé : le salarié devient donc inactif dès
00:00:00 Europe/Parisde son dernier jour renseigné (end_date).
- Le salarié est actif uniquement si
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 dePlacePendingOrderavant 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 commandePENDINGbloqué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, TTL60s) protège la séquence synchronePlacePendingOrder(elle-même protégée par#[Locked]surorder: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 dansorder_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()(etgetCanceledRate()) additionnent les commandes historiquesWAITINGet les tentativesorder_tunnel_attemptsnon 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,PENDINGouFAILED, mais autorise intentionnellement un administrateur à annuler toute commande métier (WAITINGouVALIDATED), y compris lorsquepickup_dayest 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()puispersist()) 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, longueur7) est dérivé de façon déterministe à partir dumatriculedu salarié viaSerialCasterBuilder(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.
- Chaque code d'accès (
- Validation à l'inscription (
RegisterRequest) :- L'existence d'un
matriculenon 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 surcode(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).
- L'existence d'un
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).
- L'API CRM (
- Alignement sur
laravel/ui(VerificationController) :- Conformément au fonctionnement standard de
laravel/ui,VerificationControllerrequiert une session authentifiée (auth:frontend) pour accéder aux routesemail/verify,email/verify/{id}/{hash}etemail/resend. - Lorsqu'un client saisit le bon mot de passe sur un compte non encore activé,
CrmUserProvider::validateCredentials()intercepteCrmCustomerNotActivatedException, renvoie l'e-mail de vérification et retournetrueafin d'ouvrir la session et de laisser le middlewareverified(EnsureCustomerEmailIsVerified) rediriger versfo.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()).
- Conformément au fonctionnement standard de