# MyKollectOr — Module Cartes Cadeaux (`mkogiftcard`)

Cartes cadeaux numériques pour la boutique MyKollectOr (PrestaShop 8 / 9).
Le bénéficiaire reçoit une médaille, un pack ou un montant à dépenser,
**port inclus dès l'achat**. L'adresse de livraison n'est demandée qu'à
l'activation : l'acheteur n'a jamais besoin de la connaître.

---

## 1. Principe

1. Le client achète une carte cadeau et saisit le bénéficiaire, un message et
   une date d'envoi.
2. À la date prévue, le bénéficiaire reçoit un e-mail aux couleurs MyKollectOr
   avec un bouton « J'active mon cadeau ».
3. Il se connecte ou crée son compte, puis renseigne **son** adresse de livraison.
4. La carte apparaît dans « Mon compte → Mes cartes cadeaux ».
5. Selon le type, il choisit sa médaille à 0 €, commande son pack, ou dépense
   son solde.

## 2. Les trois types de cartes

| Type | Description | Prix |
|------|-------------|------|
| `medaille` | Bon générique : le bénéficiaire choisit **une** médaille dans la catégorie autorisée, gravure et port inclus. | fixe (prix médaille + port) |
| `pack` | Contenu composé par l'admin (médaille, tour de cou, goodies…). Inclut les packs saisonniers (Saint-Valentin, Fête des Pères). | fixe, défini par l'admin |
| `montant` | Portefeuille à dépenser librement sur la boutique. | = valeur offerte |

Le bon `medaille` est volontairement générique : comme toutes les médailles sont
au même prix, le bénéficiaire choisit le parcours qu'il veut au moment de
commander. **Aucun bon à recréer quand un nouveau parcours est ajouté**, et plus
de blocage côté bénéficiaire (donc moins de SAV).

## 3. Installation

Le téléversement de zip du back-office dépend du module `ps_mbo` ; s'il est
désactivé (cas actuel de la boutique), passer par la copie de fichiers :

1. Décompresser `mkogiftcard.zip` sur l'ordinateur → dossier `mkogiftcard/`.
2. Par FTP, envoyer ce dossier dans `/home/mykollu/shop/modules/`.
   Vérifier le chemin final : `modules/mkogiftcard/mkogiftcard.php`
   (un seul niveau `mkogiftcard`, pas deux).
3. Back-office → **Modules**, rechercher « Cartes Cadeaux », cliquer
   **Installer**. (Le bouton Installer fonctionne même sans `ps_mbo`.)
4. Cliquer **Configurer** pour régler les paramètres (voir §7).
5. Importer les produits cartes cadeaux : exécuter `sql/products_seed.sql` (§5).
6. Planifier l'URL CRON affichée dans la page de configuration.

> Pré-requis : PrestaShop 8.0+ ou 9.x, PHP 8.1+. Compatible Stripe / PayPal.

## 4. Architecture des fichiers

```
mkogiftcard/
├── mkogiftcard.php                  Module principal (install, hooks)
├── logo.png
├── classes/
│   ├── MkoGiftCard.php              ObjectModel d'une carte
│   ├── MkoGiftCardGenerator.php     Numéros et codes uniques
│   └── MkoGiftCardService.php       Logique métier (créer, envoyer, activer, débiter)
├── controllers/
│   ├── admin/AdminMkoGiftCardController.php   Back-office (liste, vue, actions)
│   └── front/
│       ├── activation.php           Activation côté bénéficiaire
│       ├── account.php              Espace « Mes cartes cadeaux »
│       └── cron.php                 Envoi programmé + expiration
├── views/
│   ├── templates/front/             Templates Smarty (login, adresse, compte…)
│   ├── templates/admin/view.tpl     Vue détaillée + historique
│   ├── templates/hook/              Bloc espace client
│   └── css/front.css                Styles aux couleurs MyKollectOr
├── mails/fr/                        E-mail d'activation (HTML + texte)
└── sql/
    ├── install.sql                  Tables du module
    ├── uninstall.sql
    └── products_seed.sql            Produits cartes cadeaux à injecter
```

## 5. Produits cartes cadeaux

Un produit « carte cadeau » est un **produit PrestaShop standard** repéré par
des features techniques que le module lit :

- `mko_giftcard` = `1` → ce produit est une carte cadeau ;
- `mko_giftcard_type` = `medaille` | `pack` | `montant` ;
- `mko_giftcard_categorie` = `id_category` commandable (bon `medaille`) ;
- `mko_giftcard_allowed` = CSV d'`id_product` autorisés (pour les packs).

Le script `sql/products_seed.sql` crée ces features puis 6 cartes prêtes : le bon
Médaille générique et 5 cartes Montant (30 à 150 €). Les bons Pack ne sont pas
créés par le SQL : tu les fabriques toi-même quand tu auras des packs (voir plus
bas).

**Avant de l'exécuter :** sauvegarder la base, vérifier le préfixe (`MkO025_`),
l'`id_lang`, la catégorie d'affichage, la règle de taxe, et surtout renseigner
`@ID_CAT_MEDAILLES` (catégorie des médailles commandables) et `@PRIX_MEDAILLE`
(prix médaille + port). **Après :** ajouter une image et les champs de
personnalisation à chaque produit, puis vider le cache.

### Champs de personnalisation requis (par produit carte)

À créer dans la fiche produit (onglet Personnalisation, champs texte) :
`recipient_name`, `recipient_email`, `personal_message`, `send_date`,
`sender_name`. Le module récupère ces valeurs à la validation de la commande.

### Créer un bon Pack (plus tard, quand tu auras des packs)

Le SQL d'exemple ne crée volontairement aucun bon Pack. Tu crées tes packs
toi-même dans PrestaShop, et chaque pack vit sous deux fiches distinctes :

1. **Le pack produit** : une fiche PrestaShop normale, achetable par un sportif
   pour lui-même et livrée classiquement. Elle ne porte **aucune** feature
   `mko_giftcard`. Le module l'ignore totalement.
2. **Le bon Pack** : une fiche séparée, à offrir. Pour la créer :
   - dupliquer ou créer un produit dédié (ex. « Carte Cadeau - Pack Starter ») ;
   - définir son prix (celui du pack offert) ;
   - lui ajouter les features : `mko_giftcard` = `1`, `mko_giftcard_type` =
     `pack`, et `mko_giftcard_allowed` = l'`id_product` du pack produit ;
   - ajouter les champs de personnalisation (voir ci-dessus) et un visuel.

Ainsi le sportif achète le pack produit normalement, et celui qui veut l'offrir
prend le bon Pack, qui déclenche code, e-mail et activation. Les packs
saisonniers (Saint-Valentin, Fête des Pères) sont de simples bons Pack avec un
nom et un visuel dédiés.

## 6. CRON (envoi programmé et expiration)

Définir une clé secrète puis planifier l'appel quotidien :

```
https://shop.mykollector.com/index.php?fc=module&module=mkogiftcard&controller=cron&secure_key=VOTRE_CLE
```

La clé se règle via la configuration `MKO_GC_CRON_KEY`. Le CRON envoie les cartes
dont la date est atteinte et passe en `expired` celles dépassées.

## 7. Configuration (dans PrestaShop)

Tout se règle depuis le back-office : **Modules → MyKollectOr - Cartes Cadeaux →
Configurer**. La page permet de définir :

| Paramètre | Défaut | Rôle |
|-----------|--------|------|
| Durée de validité (mois) | 24 | Validité d'une carte à partir de l'achat |
| Seuil de port offert | 0 | Port offert au-delà de ce montant (cartes Montant) ; 0 = jamais |
| Expéditeur par défaut | nom boutique | Nom affiché dans l'e-mail si l'acheteur n'en met pas |
| Clé secrète CRON | générée à l'installation | Protège l'URL d'envoi automatique |

La page affiche aussi l'**URL CRON prête à copier** pour ta tâche planifiée
(1 fois par jour), et un bouton pour régénérer la clé.

## 8. Points d'attention (à traiter avant production)

- **Commande à 0 €** : vérifier que le tunnel accepte un total nul (un mode de
  validation dédié peut être nécessaire selon la passerelle).
- **Carte Montant** : trancher la règle de port et le sort du solde résiduel
  (réglementation française sur les cartes cadeaux).
- **Base mykollu584** : le module crée ses propres tables côté PrestaShop. Toute
  synchronisation avec MyKollectOr (`mykollufab`) passe par l'API OAuth2, jamais
  en SQL direct (règle absolue du projet).

## 9. Désinstallation

La désinstallation supprime les tables et **efface les cartes émises**. Exporter
la liste au préalable (bouton d'export du back-office) si besoin de conservation.

---

*MyKollectOr — Julien Carpentier. Document interne.*
