# Architecture de référence — AffiliaMini

## Principe de sécurité

Chaque requête serveur doit recevoir un `TenantContext` établi à partir d'une session Shopify validée. Les identifiants fournis par le navigateur ne déterminent jamais seuls une boutique. Toutes les lectures et écritures portent le `shopId` issu du contexte ; une ressource d'une autre boutique est traitée comme introuvable.

```text
Shopify OAuth / App Bridge
          |
          v
Validation HMAC + session serveur
          |
          v
TenantContext(shopId, merchantUserId, permissions)
          |
          +--> services métier --> PostgreSQL avec RLS
          +--> file de jobs --> workers idempotents
          +--> webhooks signés --> journal d'audit
```

## Modules et frontières

| Module | Responsabilité | Intégration prévue |
| --- | --- | --- |
| tenancy/auth | OAuth Shopify, session, rôles, isolation | OAuth/HMAC, PostgreSQL RLS |
| catalog | synchronisation incrémentale produits/collections | Admin GraphQL + webhooks |
| affiliate/programs | affiliés, programmes, liens, coupons | App Home + portail affilié |
| attribution/commissions | clics, attribution, conversions, journal financier | Web Pixel, commandes/webhooks |
| payouts | lots, factures, moyens de paiement, validation | fournisseur de paiement officiellement autorisé |
| referral | parrainage client et récompenses | extensions Shopify compatibles |
| portal | pages publiques, branding, langues, créatifs | theme/customer account extensions selon disponibilité |
| social | campagnes, brouillons, publication autorisée ou partage assisté | OAuth officiel de chaque réseau |
| reports/compliance | rapports, consentement, logs d'audit, exports | jobs, stockage chiffré |

## Règles non négociables

1. Les écritures financières utilisent transactions, `idempotency_key` et un journal append-only.
2. Les tokens sociaux sont chiffrés au repos, jamais envoyés au client, et chaque publication conserve une preuve/identifiant externe avant d'être marquée publiée.
3. Les webhooks sont vérifiés, dédupliqués et rejouables sans double commission.
4. Les réseaux sociaux sont connectés par OAuth officiel uniquement ; sans permission de publication, le produit propose un partage assisté sans faux statut de publication.
5. Les données marketing ne sont collectées qu'après vérification du consentement Shopify applicable.

## Découpage de livraison

1. Installation, OAuth, tenancy et schéma.
2. Affiliés, liens, coupons, attribution, commissions, paiements.
3. Paliers, bonus, cadeaux, MLM et parrainage.
4. Portails, personnalisation, langues, emails et rapports.
5. Studio social, catalogue, hashtag, calendrier et preuves de publication.
6. Automatisations, conformité, résilience et publication App Store.
