Crealcs Development DokuWiki

Vous affichez une ancienne révision du document ! Si vous l'enregistrez, vous créerez une nouvelle version avec ce contenu.

====== Sprint 3 — Gestion des Clients ======

===== Objectif =====

Implémenter le premier domaine métier CRM complet de la plateforme.

Le domaine :

<code>
Customer
</code>

deviendra le pivot central de :

<code>
Réservations

Facturation

CRM

Marketing

Communication

Programme de fidélité

Revenue Management
</code>

----

====== Périmètre du Sprint 3 ======

===== Entités =====

<code>
Customer

CustomerAddress

CustomerDocument

CustomerTag

CustomerNote

CustomerCommunication

CustomerPreference
</code>

----

===== Fonctionnalités =====

<code>
CRUD Clients

Profil Client

Adresses

Documents

Tags CRM

Notes internes

Historique communications

Préférences client

Segmentation

Fidélisation
</code>

----

====== Architecture cible ======

<code>
Customer

├── Addresses

├── Documents

├── Tags

├── Notes

├── Communications

├── Preferences

├── Reservations

├── Invoices

└── CRM Activities
</code>

----

====== Découpage du Sprint ======

===== Sprint 3-A =====

Modèle CRM Prisma

<code>
Customer

CustomerAddress

CustomerPreference
</code>

----

===== Sprint 3-B =====

CRUD Clients

<code>
CustomerModule

CustomerController

CustomerService
</code>

----

===== Sprint 3-C =====

Adresses Client

<code>
CustomerAddressModule
</code>

----

===== Sprint 3-D =====

Documents Client

<code>
CustomerDocument

Upload

Stockage
</code>

----

===== Sprint 3-E =====

Tags CRM

<code>
CustomerTag

Segmentation
</code>

----

===== Sprint 3-F =====

Notes CRM

<code>
CustomerNote
</code>

----

===== Sprint 3-G =====

Communications

<code>
CustomerCommunication
</code>

----

===== Sprint 3-H =====

Préférences Client

<code>
CustomerPreference
</code>

----

===== Sprint 3-I =====

Recherche CRM Avancée

<code>
Filtres

Segmentation

Recherche globale
</code>

----

===== Sprint 3-J =====

Vue CRM Enterprise

<code>
Dashboard Client

Vue 360°

Historique complet
</code>

----

====== Sprint 3-A.1 — Implémentation Prisma CRM Core ======

===== Objectif =====

Créer le socle CRM principal de la plateforme.

Ces modèles deviendront les fondations de :

<code>
Reservations

CRM

Marketing

Facturation

Communication

Fidélisation

Revenue Management
</code>

----

====== Architecture CRM ======

<code>
Customer

├── CustomerAddress

├── CustomerPreference

├── Reservations

├── Invoices

├── Notes

├── Tags

├── Documents

└── Communications
</code>

----

====== Étape 1 — Création Customer ======

===== Ajouter dans schema.prisma =====

<code prisma>
model Customer {

id                    String
                        @id
                        @default(uuid())

tenantId              String

customerNumber        String?

externalReference     String?

type                  String
                        @default("INDIVIDUAL")

status                String
                        @default("ACTIVE")

firstName             String

lastName              String

companyName           String?

email                 String?

phone                 String?

mobilePhone           String?

dateOfBirth           DateTime?

nationality           String?

language              String?

source                String?

acquisitionChannel    String?

notes                 String?

vip                   Boolean
                        @default(false)

blacklisted           Boolean
                        @default(false)

marketingConsent      Boolean
                        @default(false)

emailVerified         Boolean
                        @default(false)

phoneVerified         Boolean
                        @default(false)

createdAt             DateTime
                        @default(now())

updatedAt             DateTime
                        @updatedAt

deletedAt             DateTime?

tenant                Tenant
                        @relation(
                          fields:[tenantId],
                          references:[id]
                        )

addresses             CustomerAddress[]

preferences           CustomerPreference?

@@index([tenantId])

@@index([status])

@@index([email])

@@index([phone])

@@index([vip])

@@index([createdAt])

@@unique([
    tenantId,
    customerNumber
  ])
}
</code>

----

====== Étape 2 — Création CustomerAddress ======

===== Ajouter =====

<code prisma>
model CustomerAddress {

id                    String
                        @id
                        @default(uuid())

customerId            String

label                 String

addressLine1          String

addressLine2          String?

postalCode            String

city                  String

state                 String?

country               String

latitude              Decimal?
                        @db.Decimal(10,7)

longitude             Decimal?
                        @db.Decimal(10,7)

formattedAddress      String?

placeId               String?

isDefault             Boolean
                        @default(false)

createdAt             DateTime
                        @default(now())

updatedAt             DateTime
                        @updatedAt

customer              Customer
                        @relation(
                          fields:[customerId],
                          references:[id],
                          onDelete:Cascade
                        )

@@index([customerId])

@@index([country])

@@index([city])

@@index([isDefault])
}
</code>

----

====== Étape 3 — Création CustomerPreference ======

===== Ajouter =====

<code prisma>
model CustomerPreference {

id                    String
                        @id
                        @default(uuid())

customerId            String
                        @unique

preferredLanguage     String?

preferredCurrency     String?

preferredChannel      String?

prefersEmail          Boolean
                        @default(true)

prefersSms            Boolean
                        @default(false)

prefersPhone          Boolean
                        @default(false)

acceptsMarketing      Boolean
                        @default(false)

acceptsNewsletter     Boolean
                        @default(false)

acceptsPromotions     Boolean
                        @default(false)

acceptsSurveys        Boolean
                        @default(false)

loyaltyEligible       Boolean
                        @default(true)

vipProgramEligible    Boolean
                        @default(false)

createdAt             DateTime
                        @default(now())

updatedAt             DateTime
                        @updatedAt

customer              Customer
                        @relation(
                          fields:[customerId],
                          references:[id],
                          onDelete:Cascade
                        )

@@index([preferredLanguage])

@@index([preferredCurrency])

@@index([acceptsMarketing])
}
</code>

----

====== Étape 4 — Relation Tenant ======

===== Ajouter dans Tenant =====

<code prisma>
customers Customer[]
</code>

----

====== Étape 5 — Préparation Reservations ======

===== Ajouter dans Customer =====

<code prisma>
reservations Reservation[]
</code>

----

===== Ajouter dans Reservation =====

<code prisma>
customerId String?

customer   Customer?
           @relation(
             fields:[customerId],
             references:[id]
           )
</code>

----

====== Étape 6 — Préparation CRM ======

===== Ajouter dans Customer =====

Relations futures :

<code prisma>
notes             CustomerNote[]

documents         CustomerDocument[]

communications    CustomerCommunication[]

tags              CustomerTag[]
</code>

----

===== Ne pas créer encore =====

Ces modèles arriveront dans :

<code>
Sprint 3-D

Sprint 3-E

Sprint 3-F

Sprint 3-G
</code>

----

====== Étape 7 — Préparation Marketing ======

===== Champs CRM =====

Déjà présents :

<code prisma>
source

acquisitionChannel

marketingConsent
</code>

----

===== Exemples =====

<code>
Website

Booking

Airbnb

Google Ads

Facebook

Referral

Direct
</code>

----

====== Étape 8 — Préparation Fidélité ======

===== Champs =====

<code prisma>
vip

loyaltyEligible

vipProgramEligible
</code>

----

===== Utilisation future =====

<code>
Loyalty Program

Reward Engine

Customer Segmentation
</code>

----

====== Étape 9 — Migration ======

===== Générer =====

<code bash>
npx prisma migrate dev \
--name crm_customer_core
</code>

----

===== Générer =====

<code bash>
npx prisma generate
</code>

----

====== Étape 10 — Validation ======

===== Exécuter =====

<code bash>
npx prisma validate
</code>

----

===== Résultat attendu =====

<code>
The schema at prisma/schema.prisma is valid
</code>

----

====== Étape 11 — Vérification SQL ======

===== PostgreSQL =====

<code sql>
\d "Customer"

\d "CustomerAddress"

\d "CustomerPreference"
</code>

----

====== Modèle CRM obtenu ======

<code>
Customer
│
├── Profil CRM
│
├── Préférences
│
├── Adresses
│
├── Réservations
│
├── Marketing
│
└── Fidélité
</code>

----

====== Définition de terminé ======

Le Sprint 3-A.1 est terminé lorsque :

<code>
✓ Customer créé

✓ CustomerAddress créée

✓ CustomerPreference créée

✓ Tenant relation ajoutée

✓ Reservation relation préparée

✓ Migration exécutée

✓ Prisma Client généré

✓ Validation Prisma verte
</code>

----

====== Livrables ======

<code>
Customer

CustomerAddress

CustomerPreference

Migration crm_customer_core

Prisma Client mis à jour
</code>

----

====== Sprint 3-A.2 — Amélioration Enterprise du modèle Customer ======

===== Objectif =====

Faire évoluer le modèle CRM Core vers un modèle Enterprise capable de supporter :

<code>
CRM avancé

Segmentation

Marketing Automation

Fidélisation

Analyse comportementale

Revenue Management

RGPD

Conformité
</code>

----

====== Architecture cible ======

<code>
Customer

├── Profile

├── Preferences

├── Addresses

├── Segmentation

├── Scoring

├── Risk

├── Lifetime Value

├── GDPR

├── Communications

├── Reservations

└── CRM History
</code>

----

====== Sprint 3-A.2-A ======

===== CustomerStatus =====

----

====== Étape 1 — Création Enum ======

===== Ajouter =====

<code prisma>
enum CustomerStatus {

LEAD

ACTIVE

VIP

INACTIVE

BLOCKED

BLACKLISTED
}
</code>

----

====== Étape 2 — Utilisation ======

===== Remplacer =====

Dans :

<code prisma>
model Customer
</code>

----

===== Ancien =====

<code prisma>
status String
</code>

----

===== Nouveau =====

<code prisma>
status CustomerStatus
       @default(ACTIVE)
</code>

----

====== Sprint 3-A.2-B ======

===== CustomerSource =====

----

====== Étape 3 — Enum Source ======

===== Ajouter =====

<code prisma>
enum CustomerSource {

WEBSITE

DIRECT

AIRBNB

BOOKING

EXPEDIA

VRBO

GOOGLE

FACEBOOK

INSTAGRAM

REFERRAL

PARTNER

IMPORT

OTHER
}
</code>

----

====== Étape 4 — Utilisation ======

===== Remplacer =====

<code prisma>
source String?
</code>

----

===== Par =====

<code prisma>
source CustomerSource?
</code>

----

====== Sprint 3-A.2-C ======

===== Customer Score =====

----

====== Étape 5 — Ajouter =====

Dans :

<code prisma>
model Customer
</code>

----

===== Champs =====

<code prisma>
customerScore          Int
                       @default(0)

engagementScore        Int
                       @default(0)

satisfactionScore      Int
                       @default(0)

loyaltyScore           Int
                       @default(0)
</code>

----

===== Utilisation =====

<code>
Segmentation

CRM

Marketing

Fidélisation
</code>

----

====== Sprint 3-A.2-D ======

===== Customer Lifetime Value =====

----

====== Étape 6 — Ajouter =====

<code prisma>
lifetimeValue          Decimal?
                       @db.Decimal(14,2)

totalReservations      Int
                       @default(0)

totalRevenue           Decimal?
                       @db.Decimal(14,2)

averageBasket          Decimal?
                       @db.Decimal(14,2)

lastReservationAt      DateTime?
</code>

----

===== Préparation =====

Pour :

<code>
Revenue Management

Business Intelligence

Customer Analytics
</code>

----

====== Sprint 3-A.2-E ======

===== Customer Risk =====

----

====== Étape 7 — Enum ======

<code prisma>
enum CustomerRiskLevel {

LOW

MEDIUM

HIGH

CRITICAL
}
</code>

----

====== Étape 8 — Ajouter =====

Dans Customer :

<code prisma>
riskLevel CustomerRiskLevel
          @default(LOW)

riskScore Int
          @default(0)

fraudFlag Boolean
          @default(false)
</code>

----

===== Utilisation =====

<code>
Fraude

Paiements

Réservations

Sécurité
</code>

----

====== Sprint 3-A.2-F ======

===== Segmentation =====

----

====== Étape 9 — Enum ======

<code prisma>
enum CustomerSegment {

STANDARD

FREQUENT

VIP

CORPORATE

OWNER

PARTNER

BLACKLISTED
}
</code>

----

====== Étape 10 — Ajouter =====

<code prisma>
segment CustomerSegment
        @default(STANDARD)
</code>

----

===== Utilisation =====

<code>
Campagnes

CRM

Automatisation

Fidélisation
</code>

----

====== Sprint 3-A.2-G ======

===== RGPD =====

----

====== Étape 11 — Ajouter =====

Dans Customer :

<code prisma>
gdprConsentGiven       Boolean
                       @default(false)

gdprConsentAt          DateTime?

marketingConsentAt     DateTime?

privacyPolicyAccepted  Boolean
                       @default(false)

privacyPolicyAcceptedAt DateTime?

dataRetentionUntil     DateTime?
</code>

----

===== Préparation =====

Pour :

<code>
Consent

ComplianceAudit

RetentionPolicy
</code>

----

====== Sprint 3-A.2-H ======

===== Historisation CRM =====

----

====== Étape 12 — Création CustomerHistory ======

===== Ajouter =====

<code prisma>
model CustomerHistory {

id                    String
                        @id
                        @default(uuid())

customerId            String

changedField          String

oldValue              String?

newValue              String?

changedBy             String?

changedAt             DateTime
                        @default(now())

customer              Customer
                        @relation(
                          fields:[customerId],
                          references:[id],
                          onDelete:Cascade
                        )

@@index([customerId])

@@index([changedAt])
}
</code>

----

====== Étape 13 — Relation ======

===== Ajouter =====

Dans :

<code prisma>
model Customer
</code>

<code prisma>
history CustomerHistory[]
</code>

----

====== Sprint 3-A.2-I ======

===== Scoring Automatique =====

----

====== Étape 14 — Préparer =====

Ajouter dans Customer :

<code prisma>
firstReservationAt      DateTime?

lastCommunicationAt     DateTime?

lastActivityAt          DateTime?
</code>

----

===== Calcul futur =====

<code>
Customer Score

Engagement Score

Loyalty Score

Risk Score
</code>

seront alimentés par :

<code>
Reservations

Invoices

CRM Activities

Communications
</code>

----

====== Sprint 3-A.2-J ======

===== Préparation Marketing =====

----

====== Étape 15 — Ajouter =====

<code prisma>
preferredPropertyType   String?

preferredStayDuration   Int?

preferredDestination    String?

preferredTravelSeason   String?
</code>

----

===== Utilisation =====

<code>
Marketing IA

Recommandations

Segmentation

Campagnes
</code>

----

====== Étape 16 — Index CRM ======

===== Ajouter =====

Dans Customer :

<code prisma>
@@index([segment])

@@index([customerScore])

@@index([riskLevel])

@@index([source])

@@index([lifetimeValue])

@@index([lastReservationAt])

@@index([gdprConsentGiven])
</code>

----

====== Étape 17 — Migration ======

===== Générer =====

<code bash>
npx prisma migrate dev \
--name customer_enterprise
</code>

----

===== Générer =====

<code bash>
npx prisma generate
</code>

----

====== Étape 18 — Validation ======

===== Exécuter =====

<code bash>
npx prisma validate
</code>

----

===== Résultat attendu =====

<code>
The schema at prisma/schema.prisma is valid
</code>

----

====== Modèle CRM Enterprise obtenu ======

<code>
Customer

├── Profil

├── Adresses

├── Préférences

├── Segmentation

├── Score

├── Lifetime Value

├── Risque

├── RGPD

├── Historique

├── Marketing

└── Fidélisation
</code>

----

====== Définition de terminé ======

Le Sprint 3-A.2 est terminé lorsque :

<code>
✓ CustomerStatus

✓ CustomerSource

✓ CustomerScore

✓ CustomerLifetimeValue

✓ CustomerRisk

✓ CustomerSegment

✓ RGPD

✓ CustomerHistory

✓ Index CRM

✓ Migration exécutée
</code>

----

====== Livrables ======

<code>
Customer Enterprise

CustomerHistory

CustomerStatus

CustomerSource

CustomerSegment

CustomerRiskLevel

Migration customer_enterprise
</code>

----

====== Sprint 3-B.1 — Création du CustomerModule ======

===== Objectif =====

Implémenter le premier module CRM métier complet basé sur :

<code>
Customer
</code>

avec :

<code>
CRUD Clients

Recherche CRM

Pagination

Tri

Filtres

Multi-Tenant Security

Swagger
</code>

----

====== Architecture ======

===== Créer =====

<code>
src/modules/customers
</code>

----

===== Structure =====

<code>
customers

├── application
│
│   └── dto
│
│       ├── create-customer.dto.ts
│       ├── update-customer.dto.ts
│       ├── customer-query.dto.ts
│       └── customer-response.dto.ts
│
├── domain
│
│   └── services
│
│       └── customer.service.ts
│
├── presentation
│
│   └── controllers
│
│       └── customer.controller.ts
│
└── customer.module.ts
</code>

----

====== Sprint 3-B.1-A ======

===== DTOs =====

----

====== Étape 1 — CreateCustomerDto ======

===== Créer =====

<code>
create-customer.dto.ts
</code>

----

===== Implémentation =====

<code ts>
export class CreateCustomerDto {

firstName: string;

lastName: string;

email?: string;

phone?: string;

mobilePhone?: string;

companyName?: string;

language?: string;

source?: string;

marketingConsent?: boolean;
}
</code>

----

====== Étape 2 — UpdateCustomerDto ======

===== Créer =====

<code>
update-customer.dto.ts
</code>

----

===== Implémentation =====

<code ts>
export class UpdateCustomerDto
  extends PartialType(
    CreateCustomerDto
  ) {}
</code>

----

====== Étape 3 — CustomerQueryDto ======

===== Créer =====

<code>
customer-query.dto.ts
</code>

----

===== Ajouter =====

<code ts>
export class CustomerQueryDto {

page?: number = 1;

limit?: number = 25;

search?: string;

status?: string;

segment?: string;

source?: string;

vip?: boolean;

sortBy?: string =
    'createdAt';

sortOrder?: 'asc' | 'desc' =
    'desc';
}
</code>

----

====== Étape 4 — CustomerResponseDto ======

===== Créer =====

<code>
customer-response.dto.ts
</code>

----

===== Ajouter =====

<code ts>
export class CustomerResponseDto {

id: string;

firstName: string;

lastName: string;

email?: string;

phone?: string;

status: string;

segment: string;

customerScore: number;

lifetimeValue?: number;

vip: boolean;

createdAt: Date;
}
</code>

----

====== Sprint 3-B.1-B ======

===== CustomerService =====

----

====== Étape 5 — Création ======

===== Créer =====

<code>
customer.service.ts
</code>

----

===== Injection =====

<code ts>
@Injectable()
export class CustomerService {

constructor(

private readonly prisma:
      PrismaService
  ) {}
}
</code>

----

====== Étape 6 — Méthodes ======

===== Ajouter =====

<code ts>
findAll()

findOne()

create()

update()

remove()
</code>

----

====== Étape 7 — Multi-Tenant Security ======

===== Principe =====

Aucune requête CRM ne doit sortir du tenant.

----

===== Exemple =====

<code ts>
where: {

tenantId:
    currentTenantId
}
</code>

----

===== Obligatoire =====

Dans :

<code>
Toutes les requêtes
</code>

----

====== Étape 8 — Recherche CRM ======

===== Recherche globale =====

<code ts>
OR: [

{
    firstName: {
      contains: search,
      mode: 'insensitive'
    }
  },

{
    lastName: {
      contains: search,
      mode: 'insensitive'
    }
  },

{
    email: {
      contains: search,
      mode: 'insensitive'
    }
  },

{
    companyName: {
      contains: search,
      mode: 'insensitive'
    }
  }
]
</code>

----

====== Étape 9 — Filtres ======

===== Ajouter =====

<code ts>
status

segment

source

vip
</code>

----

===== Exemple =====

<code ts>
if (query.vip !== undefined) {

where.vip =
    query.vip;
}
</code>

----

====== Étape 10 — Pagination ======

===== Calcul =====

<code ts>
const skip =

(page - 1) * limit;
</code>

----

===== Prisma =====

<code ts>
skip,

take: limit
</code>

----

====== Étape 11 — Tri ======

===== Ajouter =====

<code ts>
orderBy: {

[query.sortBy]:
    query.sortOrder
}
</code>

----

====== Étape 12 — findAll ======

===== Implémentation =====

<code ts>
async findAll(

tenantId: string,

query:
    CustomerQueryDto
)
</code>

----

===== Retour =====

<code ts>
return {

data:

customers,

meta: {

page,

limit,

total
  }
};
</code>

----

====== Étape 13 — findOne ======

===== Implémentation =====

<code ts>
async findOne(

tenantId: string,

id: string
)
</code>

----

===== Sécurité =====

<code ts>
where: {

id,

tenantId
}
</code>

----

===== Sinon =====

<code ts>
throw new NotFoundException(
  'Customer not found'
);
</code>

----

====== Étape 14 — create ======

===== Génération CRM =====

<code ts>
customerNumber =

`CUS-${Date.now()}`
</code>

----

===== Création =====

<code ts>
await prisma.customer.create({

data: {

tenantId,

customerNumber,

...dto
  }
});
</code>

----

====== Étape 15 — CustomerPreference ======

===== Création automatique =====

<code ts>
await prisma.customerPreference.create({

data: {

customerId:
      customer.id
  }
});
</code>

----

====== Étape 16 — update ======

===== Vérifier =====

<code>
Customer existe

+

Même tenant
</code>

----

===== Mise à jour =====

<code ts>
await prisma.customer.update(...)
</code>

----

====== Étape 17 — remove ======

===== Soft Delete =====

Ne jamais supprimer réellement.

----

===== Ajouter =====

<code ts>
deletedAt:
  new Date()
</code>

----

===== Mise à jour =====

<code ts>
await prisma.customer.update({

where: {

id
  },

data: {

deletedAt:
      new Date(),

status:
      'INACTIVE'
  }
});
</code>

----

====== Sprint 3-B.1-C ======

===== CustomerController =====

----

====== Étape 18 — Création ======

===== Créer =====

<code>
customer.controller.ts
</code>

----

===== Déclaration =====

<code ts>
@ApiTags('Customers')

@Controller('customers')

@UseGuards(
  JwtAuthGuard
)

@ApiBearerAuth()
</code>

----

====== Étape 19 — GET /customers ======

===== Route =====

----

===== Paramètres =====

<code>
Recherche

Pagination

Filtres
</code>

----

====== Étape 20 — GET /customers/{id} ======

===== Route =====

----

====== Étape 21 — POST /customers ======

===== Route =====

----

====== Étape 22 — PUT /customers/{id} ======

===== Route =====

----

====== Étape 23 — DELETE /customers/{id} ======

===== Route =====

<code ts>
@Delete(':id')
</code>

----

====== Sprint 3-B.1-D ======

===== CustomerModule =====

----

====== Étape 24 — Création ======

===== Créer =====

<code>
customer.module.ts
</code>

----

===== Implémentation =====

<code ts>
@Module({

imports: [

PrismaModule,

AuthModule
  ],

controllers: [

CustomerController
  ],

providers: [

CustomerService
  ],

exports: [

CustomerService
  ]
})
export class CustomerModule {}
</code>

----

====== Étape 25 — AppModule ======

===== Ajouter =====

<code ts>
imports: [

...

CustomerModule
]
</code>

----

====== Sprint 3-B.1-E ======

===== Swagger =====

----

====== Étape 26 — Vérification ======

===== Endpoints =====

<code http>
GET    /customers

GET    /customers/{id}

POST   /customers

PUT    /customers/{id}

DELETE /customers/{id}
</code>

----

====== Étape 27 — Exemple GET ======

===== Requête =====

<code http>
GET /customers?page=1&limit=25
</code>

----

===== Réponse =====

<code json>
{
  "data": [
    {
      "id": "xxx",
      "firstName": "Jean",
      "lastName": "Dupont",
      "segment": "VIP"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 132
  }
}
</code>

----

====== Étape 28 — Exemple POST ======

===== Body =====

<code json>
{
  "firstName": "Jean",
  "lastName": "Dupont",
  "email": "jean@demo.fr",
  "marketingConsent": true
}
</code>

----

===== Résultat =====

<code>
Customer créé

CustomerPreference créée

Numéro CRM généré
</code>

----

====== Préparation Sprint 3-C ======

Ce module servira directement à :

<code>
CustomerAddress

CustomerDocument

CustomerTag

CustomerNote

CustomerCommunication
</code>

----

====== Définition de terminé ======

Le Sprint 3-B.1 est terminé lorsque :

<code>
✓ CustomerModule créé

✓ CustomerController créé

✓ CustomerService créé

✓ CRUD Clients opérationnel

✓ Recherche CRM

✓ Pagination

✓ Filtres

✓ Multi-Tenant Security

✓ Swagger documenté

✓ Soft Delete
</code>

----

====== Livrables ======

<code>
CustomerModule

CustomerController

CustomerService

CreateCustomerDto

UpdateCustomerDto

CustomerQueryDto

CustomerResponseDto
</code>

----

====== Sprint 3-B.2 — CRM Enterprise Search & Segmentation ======

===== Objectif =====

Transformer le CRUD Clients en véritable CRM Enterprise.

À l'issue de cette étape :

<code>
✓ Recherche avancée

✓ Segmentation dynamique

✓ Smart Segments

✓ Scores CRM

✓ Filtres combinés

✓ Export CSV

✓ Vues enregistrées

✓ CRM Analytics Ready
</code>

----

====== Architecture cible ======

<code>
Customer

↓

CRM Search Engine

↓

Dynamic Filters

↓

Segmentation Engine

↓

Smart Segments

↓

Export / Campaigns / Analytics
</code>

----

====== Sprint 3-B.2-A ======

===== Segments CRM =====

----

====== Étape 1 — Création SavedCustomerView ======

===== Ajouter dans schema.prisma =====

<code prisma>
model SavedCustomerView {

id                    String
                        @id
                        @default(uuid())

tenantId              String

userId                String

name                  String

description           String?

filters               Json

isDefault             Boolean
                        @default(false)

createdAt             DateTime
                        @default(now())

updatedAt             DateTime
                        @updatedAt

tenant                Tenant
                        @relation(
                          fields:[tenantId],
                          references:[id]
                        )

user                  User
                        @relation(
                          fields:[userId],
                          references:[id]
                        )

@@index([tenantId])

@@index([userId])
}
</code>

----

====== Étape 2 — Création CustomerSegmentRule ======

===== Ajouter =====

<code prisma>
model CustomerSegmentRule {

id                    String
                        @id
                        @default(uuid())

tenantId              String

name                  String

code                  String
                        @unique

description           String?

conditions            Json

active                Boolean
                        @default(true)

createdAt             DateTime
                        @default(now())

updatedAt             DateTime
                        @updatedAt

tenant                Tenant
                        @relation(
                          fields:[tenantId],
                          references:[id]
                        )

@@index([tenantId])

@@index([active])
}
</code>

----

====== Étape 3 — Migration ======

===== Générer =====

<code bash>
npx prisma migrate dev \
--name crm_segmentation
</code>

----

===== Générer =====

<code bash>
npx prisma generate
</code>

----

====== Sprint 3-B.2-B ======

===== Recherche CRM Avancée =====

----

====== Étape 4 — Extension CustomerQueryDto ======

===== Ajouter =====

<code ts>
customerScoreMin?: number;

customerScoreMax?: number;

lifetimeValueMin?: number;

lifetimeValueMax?: number;

riskLevel?: string;

country?: string;

language?: string;

createdFrom?: Date;

createdTo?: Date;

lastReservationFrom?: Date;

lastReservationTo?: Date;

marketingConsent?: boolean;

segment?: string;

vip?: boolean;
</code>

----

====== Étape 5 — Recherche multi-critères ======

===== Exemple =====

<code ts>
AND: [

status,

segment,

vip,

marketingConsent,

riskLevel
]
</code>

----

===== Recherche texte =====

<code ts>
OR: [

firstName,

lastName,

email,

companyName,

customerNumber
]
</code>

----

====== Étape 6 — Recherche CRM complète ======

===== Exemple =====

<code>
VIP

ET

Score > 80

ET

LifetimeValue > 5000€

ET

MarketingConsent = true
</code>

----

===== Résultat =====

<code>
Liste filtrée
</code>

----

====== Sprint 3-B.2-C ======

===== CRM Score Engine =====

----

====== Étape 7 — Création ======

<code>
crm-score.service.ts
</code>

----

===== Méthodes =====

<code ts>
calculateCustomerScore()

calculateEngagementScore()

calculateLoyaltyScore()
</code>

----

====== Étape 8 — Exemple Score ======

<code>
Réservations
+30

Paiements
+20

Avis positifs
+15

Ancienneté
+20

Marketing
+15
</code>

----

===== Total =====

----

====== Étape 9 — Classification ======

<code>
0-25

LOW
</code>

<code>
26-50

NORMAL
</code>

<code>
51-75

GOOD
</code>

<code>
76-100

EXCELLENT
</code>

----

====== Sprint 3-B.2-D ======

===== Smart Segments =====

----

====== Étape 10 — Segments automatiques ======

===== Créer =====

<code>
crm-segmentation.service.ts
</code>

----

===== Segments =====

<code>
VIP

Frequent Travelers

Corporate

High Revenue

Inactive

High Risk

Marketing Qualified
</code>

----

====== Étape 11 — Segment VIP ======

===== Règle =====

<code>
LifetimeValue > 10000

ET

Score > 80
</code>

----

====== Étape 12 — Segment Inactif ======

===== Règle =====

<code>
Dernière réservation

> 365 jours
</code>

----

====== Étape 13 — Segment Corporate ======

===== Règle =====

<code>
CompanyName != null
</code>

----

====== Sprint 3-B.2-E ======

===== Vues enregistrées =====

----

====== Étape 14 — DTO ======

===== Créer =====

<code>
create-saved-view.dto.ts
</code>

----

===== Structure =====

<code ts>
export class CreateSavedViewDto {

description?: string;

filters: Record<
    string,
    unknown
  >;
}
</code>

----

====== Étape 15 — API ======

===== Ajouter =====

<code http>
GET /customers/views

POST /customers/views

DELETE /customers/views/{id}
</code>

----

===== Exemple =====

<code>
Mes VIP

Clients inactifs

Corporate France

Top Revenue
</code>

----

====== Sprint 3-B.2-F ======

===== Export CSV =====

----

====== Étape 16 — Service ======

===== Créer =====

<code>
crm-export.service.ts
</code>

----

===== Méthodes =====

<code ts>
exportCsv()

exportExcel()
</code>

----

====== Étape 17 — Colonnes ======

<code>
CustomerNumber

FirstName

LastName

Email

Segment

Score

LifetimeValue

Status
</code>

----

====== Étape 18 — Endpoint ======

===== Ajouter =====

<code http>
GET /customers/export
</code>

----

===== Paramètres =====

<code>
Même filtres CRM
</code>

----

====== Sprint 3-B.2-G ======

===== API CRM Enterprise =====

----

====== Étape 19 — Nouveaux endpoints ======

<code http>
GET /customers/search

GET /customers/export

GET /customers/views

POST /customers/views

DELETE /customers/views/{id}

GET /customers/segments

POST /customers/segments/recalculate
</code>

----

====== Étape 20 — Exemple recherche ======

===== Requête =====

<code http>
GET /customers/search
</code>

----

===== Paramètres =====

<code>
segment=VIP

scoreMin=80

marketingConsent=true

country=FR
</code>

----

===== Résultat =====

<code>
Liste CRM filtrée
</code>

----

====== Sprint 3-B.2-H ======

===== Multi-Tenant Security =====

----

====== Étape 21 — Obligatoire =====

Toutes les requêtes :

<code ts>
tenantId
</code>

doivent être injectées automatiquement.

----

===== Vérification =====

<code>
SavedCustomerView

CustomerSegmentRule

Customer

Export
</code>

----

====== Étape 22 — Audit ======

===== Journaliser =====

<code>
CRM_SEARCH

CRM_EXPORT

CRM_SEGMENT_UPDATE

CRM_VIEW_CREATE
</code>

dans :

<code>
AuditLog
</code>

----

====== Sprint 3-B.2-I ======

===== Préparation Marketing =====

----

===== Compatible =====

<code>
Campaign

CampaignRecipient

MarketingSegment

AutomationRule

Recommendation
</code>

----

===== Préparation IA =====

Compatible avec :

<code>
Customer Scoring

Recommendations

Lead Scoring

Predictive Segmentation
</code>

----

====== Définition de terminé ======

Le Sprint 3-B.2 est terminé lorsque :

<code>
✓ Recherche avancée

✓ Segmentation dynamique

✓ Smart Segments

✓ CRM Score Engine

✓ Export CSV

✓ Vues enregistrées

✓ Audit CRM

✓ Swagger documenté
</code>

----

====== Livrables ======

<code>
SavedCustomerView

CustomerSegmentRule

CrmScoreService

CrmSegmentationService

CrmExportService

CRM Search API

CRM Segments API

CRM Views API
</code>

----

====== Sprint 3-C.1 — Gestion des Adresses Client ======

===== Objectif =====

Implémenter la gestion complète des adresses CRM client basée sur :

<code>
CustomerAddress
</code>

avec :

<code>
CRUD Adresses

Adresse principale

Géolocalisation

Validation avancée

Multi-Tenant Security

Historisation CRM
</code>

----

====== Architecture ======

===== Créer =====

<code>
src/modules/customer-addresses
</code>

----

===== Structure =====

<code>
customer-addresses

├── application
│
│   └── dto
│
│       ├── create-customer-address.dto.ts
│       ├── update-customer-address.dto.ts
│       └── customer-address-response.dto.ts
│
├── domain
│
│   └── services
│
│       └── customer-address.service.ts
│
├── presentation
│
│   └── controllers
│
│       └── customer-address.controller.ts
│
└── customer-address.module.ts
</code>

----

====== Sprint 3-C.1-A ======

===== DTOs =====

----

====== Étape 1 — CreateCustomerAddressDto ======

===== Créer =====

<code>
create-customer-address.dto.ts
</code>

----

===== Implémentation =====

<code ts>
export class CreateCustomerAddressDto {

label: string;

addressLine1: string;

addressLine2?: string;

postalCode: string;

city: string;

state?: string;

country: string;

isDefault?: boolean;
}
</code>

----

====== Étape 2 — UpdateCustomerAddressDto ======

===== Créer =====

<code>
update-customer-address.dto.ts
</code>

----

===== Implémentation =====

<code ts>
export class UpdateCustomerAddressDto
  extends PartialType(
    CreateCustomerAddressDto
  ) {}
</code>

----

====== Étape 3 — CustomerAddressResponseDto ======

===== Créer =====

<code>
customer-address-response.dto.ts
</code>

----

===== Ajouter =====

<code ts>
export class CustomerAddressResponseDto {

id: string;

label: string;

addressLine1: string;

postalCode: string;

city: string;

country: string;

latitude?: number;

longitude?: number;

formattedAddress?: string;

isDefault: boolean;

createdAt: Date;
}
</code>

----

====== Sprint 3-C.1-B ======

===== CustomerAddressService =====

----

====== Étape 4 — Création ======

===== Créer =====

<code>
customer-address.service.ts
</code>

----

===== Injection =====

<code ts>
@Injectable()
export class CustomerAddressService {

constructor(

private readonly prisma:
      PrismaService,

private readonly geocodingService:
      GeocodingService
  ) {}
}
</code>

----

====== Étape 5 — Méthodes ======

===== Ajouter =====

<code ts>
findAll()

create()

update()

remove()

setDefault()
</code>

----

====== Étape 6 — Vérification CRM ======

===== Vérifier =====

Le client appartient au tenant.

----

===== Requête =====

<code ts>
const customer =

await prisma.customer.findFirst({

where: {

id: customerId,

tenantId
  }
});
</code>

----

===== Sinon =====

<code ts>
throw new NotFoundException(
  'Customer not found'
);
</code>

----

====== Étape 7 — Recherche adresses ======

===== Implémentation =====

<code ts>
async findAll(

tenantId: string,

customerId: string
)
</code>

----

===== Requête =====

<code ts>
return prisma.customerAddress.findMany({

where: {

customerId
  },

orderBy: [

{
      isDefault:
        'desc'
    },

{
      createdAt:
        'desc'
    }
  ]
});
</code>

----

====== Sprint 3-C.1-C ======

===== Adresse principale =====

----

====== Étape 8 — Reset adresse principale ======

===== Ajouter =====

<code ts>
private async resetDefaultAddress(
  customerId: string
)
</code>

----

===== Implémentation =====

<code ts>
await prisma.customerAddress.updateMany({

where: {

customerId
  },

data: {

isDefault: false
  }
});
</code>

----

====== Étape 9 — Création ======

===== Si =====

<code ts>
dto.isDefault === true
</code>

----

===== Exécuter =====

<code ts>
await resetDefaultAddress(
  customerId
);
</code>

----

====== Étape 10 — Première adresse ======

===== Si aucune adresse =====

<code ts>
count === 0
</code>

----

===== Alors =====

<code ts>
isDefault = true
</code>

----

====== Sprint 3-C.1-D ======

===== Géolocalisation =====

----

====== Étape 11 — Construction adresse ======

===== Ajouter =====

<code ts>
const fullAddress =

`${dto.addressLine1}
 ${dto.postalCode}
 ${dto.city}
 ${dto.country}`;
</code>

----

====== Étape 12 — Géocoder ======

===== Utiliser =====

<code ts>
await geocodingService.geocode(
  fullAddress
);
</code>

----

===== Retour =====

<code ts>
latitude

longitude

formattedAddress

placeId
</code>

----

====== Étape 13 — Gestion erreur ======

===== Fallback =====

Si :

<code>
OpenStreetMap indisponible
</code>

----

===== Alors =====

Créer quand même l'adresse.

----

===== Valeurs =====

<code ts>
latitude = null

longitude = null
</code>

----

====== Sprint 3-C.1-E ======

===== Validation avancée =====

----

====== Étape 14 — Validation pays ======

===== Réutiliser =====

<code>
SUPPORTED_COUNTRIES
</code>

----

====== Étape 15 — Validation code postal ======

===== Réutiliser =====

<code>
PostalCodeValidator
</code>

----

====== Étape 16 — Validation géographique ======

===== Vérifier =====

<code>
Ville

Code postal

Pays
</code>

sont cohérents avec :

<code>
GeocodingResult
</code>

----

===== Sinon =====

<code ts>
throw new BadRequestException(
  'Address validation failed'
);
</code>

----

====== Sprint 3-C.1-F ======

===== Historisation CRM =====

----

====== Étape 17 — CustomerHistory ======

===== Ajouter =====

Lors de :

<code>
CREATE

UPDATE

DELETE
</code>

----

===== Exemple =====

<code ts>
await prisma.customerHistory.create({

data: {

customerId,

changedField:
      'address',

oldValue:
      oldAddress,

newValue:
      newAddress
  }
});
</code>

----

====== Étape 18 — AuditLog ======

===== Journaliser =====

<code>
CUSTOMER_ADDRESS_CREATED

CUSTOMER_ADDRESS_UPDATED

CUSTOMER_ADDRESS_DELETED

CUSTOMER_ADDRESS_DEFAULT_CHANGED
</code>

----

====== Sprint 3-C.1-G ======

===== Update =====

----

====== Étape 19 — Contrôle tenant ======

===== Vérifier =====

<code>
Customer

Adresse

Tenant
</code>

avant toute modification.

----

====== Étape 20 — Mise à jour ======

===== Si =====

<code>
dto.isDefault = true
</code>

----

===== Alors =====

<code ts>
resetDefaultAddress()
</code>

----

===== Puis =====

<code ts>
update()
</code>

----

====== Étape 21 — Delete ======

===== Soft Delete recommandé =====

Ajouter dans Prisma :

<code prisma>
deletedAt DateTime?
</code>

à :

<code>
CustomerAddress
</code>

----

===== Suppression =====

<code ts>
deletedAt:
  new Date()
</code>

----

====== Sprint 3-C.1-H ======

===== CustomerAddressController =====

----

====== Étape 22 — Création ======

===== Créer =====

<code>
customer-address.controller.ts
</code>

----

===== Déclaration =====

<code ts>
@ApiTags('Customer Addresses')

@Controller(
  'customers/:id/addresses'
)

@UseGuards(
  JwtAuthGuard
)

@ApiBearerAuth()
</code>

----

====== Étape 23 — GET ======

===== Route =====

<code http>
GET /customers/{id}/addresses
</code>

----

====== Étape 24 — POST ======

===== Route =====

<code http>
POST /customers/{id}/addresses
</code>

----

====== Étape 25 — PUT ======

===== Route =====

<code http>
PUT /customers/{id}/addresses/{addressId}
</code>

----

====== Étape 26 — DELETE ======

===== Route =====

<code http>
DELETE /customers/{id}/addresses/{addressId}
</code>

----

====== Sprint 3-C.1-I ======

===== CustomerAddressModule =====

----

====== Étape 27 — Création ======

===== Créer =====

<code>
customer-address.module.ts
</code>

----

===== Implémentation =====

<code ts>
@Module({

imports: [

PrismaModule,

AuthModule,

GeocodingModule
  ],

controllers: [

CustomerAddressController
  ],

providers: [

CustomerAddressService
  ],

exports: [

CustomerAddressService
  ]
})
export class CustomerAddressModule {}
</code>

----

====== Étape 28 — Swagger ======

===== Vérifier =====

<code http>
GET    /customers/{id}/addresses

POST   /customers/{id}/addresses

PUT    /customers/{id}/addresses/{addressId}

DELETE /customers/{id}/addresses/{addressId}
</code>

----

====== Étape 29 — Exemple POST ======

===== Body =====

<code json>
{
  "label": "Residence",
  "addressLine1": "10 Rue Victor Hugo",
  "postalCode": "75001",
  "city": "Paris",
  "country": "FR",
  "isDefault": true
}
</code>

----

===== Résultat =====

<code>
Adresse créée

Adresse principale définie

Coordonnées GPS calculées

Historique CRM enregistré
</code>

----

====== Préparation Sprint 3-D ======

Les adresses client seront utilisées par :

<code>
Reservations

Invoices

Documents

Marketing

CRM Analytics
</code>

----

====== Définition de terminé ======

Le Sprint 3-C.1 est terminé lorsque :

<code>
✓ CustomerAddressModule créé

✓ CustomerAddressController créé

✓ CustomerAddressService créé

✓ CRUD adresses opérationnel

✓ Adresse principale opérationnelle

✓ Géolocalisation opérationnelle

✓ Validation avancée

✓ Historisation CRM

✓ AuditLog intégré

✓ Swagger documenté
</code>

----

====== Livrables ======

<code>
CustomerAddressModule

CustomerAddressController

CustomerAddressService

CreateCustomerAddressDto

UpdateCustomerAddressDto

CustomerAddressResponseDto
</code>

----

====== Sprint 3-C.2 — Adresses Enterprise & Cartographie CRM ======

===== Objectif =====

Transformer le système d'adresses CRM en moteur géospatial Enterprise.

À l'issue de cette étape :

<code>
✓ Multi-adresses

✓ Zones géographiques

✓ Distance client

✓ Recherche par rayon

✓ Clustering géographique

✓ Cartographie CRM

✓ Heatmaps

✓ Géo-segmentation
</code>

----

====== Architecture cible ======

<code>
Customer

↓

CustomerAddress

↓

Geo Engine

↓

Spatial Queries

↓

Maps

↓

CRM Analytics
</code>

----

====== Sprint 3-C.2-A ======

===== Extension Prisma =====

----

====== Étape 1 — Création GeoZone ======

===== Ajouter =====

<code prisma>
model GeoZone {

id                    String
                        @id
                        @default(uuid())

tenantId              String

code                  String

name                  String

description           String?

zoneType              GeoZoneType

country               String?

region                String?

city                  String?

polygon               Json?

centerLatitude        Decimal?
                        @db.Decimal(10,7)

centerLongitude       Decimal?
                        @db.Decimal(10,7)

radiusKm              Decimal?
                        @db.Decimal(10,2)

active                Boolean
                        @default(true)

createdAt             DateTime
                        @default(now())

updatedAt             DateTime
                        @updatedAt

tenant                Tenant
                        @relation(
                          fields:[tenantId],
                          references:[id]
                        )

@@index([tenantId])

@@index([zoneType])

@@index([active])
}
</code>

----

====== Étape 2 — Enum GeoZoneType ======

===== Ajouter =====

<code prisma>
enum GeoZoneType {

COUNTRY

REGION

CITY

CUSTOM

SALES

MARKETING

DELIVERY
}
</code>

----

====== Étape 3 — Extension CustomerAddress ======

===== Ajouter =====

<code prisma>
geoHash               String?

geoValidated          Boolean
                      @default(false)

geoValidatedAt        DateTime?

timezone              String?

district              String?
</code>

----

====== Étape 4 — Migration ======

===== Générer =====

<code bash>
npx prisma migrate dev \
--name crm_geospatial
</code>

----

===== Générer =====

<code bash>
npx prisma generate
</code>

----

====== Sprint 3-C.2-B ======

===== GeoSpatial Module =====

----

====== Étape 5 — Création ======

<code>
src/modules/geospatial
</code>

----

===== Structure =====

<code>
geospatial

├── domain
│
│   └── services
│
│       ├── geo-distance.service.ts
│
│       ├── geo-search.service.ts
│
│       ├── geo-clustering.service.ts
│
│       └── geo-zone.service.ts
│
└── geospatial.module.ts
</code>

----

====== Étape 6 — Dépendances ======

===== Installer =====

<code bash>
npm install geolib

npm install ngeohash
</code>

----

====== Sprint 3-C.2-C ======

===== Distance Client =====

----

====== Étape 7 — GeoDistanceService ======

===== Créer =====

<code>
geo-distance.service.ts
</code>

----

===== Méthodes =====

<code ts>
calculateDistance()

calculateTravelRadius()

findNearestCustomers()
</code>

----

====== Étape 8 — Calcul ======

===== Exemple =====

<code ts>
getDistance(

{
    latitude: lat1,
    longitude: lng1
  },

{
    latitude: lat2,
    longitude: lng2
  }
)
</code>

----

===== Retour =====

<code>
Distance en kilomètres
</code>

----

====== Étape 9 — Cas d'usage ======

<code>
Client ↔ Propriété

Client ↔ Agence

Client ↔ Région

Client ↔ Zone commerciale
</code>

----

====== Sprint 3-C.2-D ======

===== Recherche par rayon =====

----

====== Étape 10 — Endpoint ======

===== Ajouter =====

<code http>
GET /customers/search/radius
</code>

----

===== Paramètres =====

<code>
latitude

longitude

radiusKm
</code>

----

====== Étape 11 — Service ======

===== Ajouter =====

<code ts>
findCustomersInRadius(
  tenantId,
  lat,
  lng,
  radiusKm
)
</code>

----

===== Retour =====

<code>
Tous les clients

dans le rayon demandé
</code>

----

====== Étape 12 — Exemple ======

===== Recherche =====

<code>
Paris

50 km
</code>

----

===== Retour =====

<code>
Clients Paris

Clients Versailles

Clients Saint-Denis
</code>

----

====== Sprint 3-C.2-E ======

===== Clustering CRM =====

----

====== Étape 13 — GeoClusteringService ======

===== Créer =====

<code>
geo-clustering.service.ts
</code>

----

===== Méthodes =====

<code ts>
clusterCustomers()

clusterByCity()

clusterByRegion()
</code>

----

====== Étape 14 — Types ======

<code>
Ville

Région

Pays

Distance

Segment CRM
</code>

----

====== Étape 15 — Exemple ======

===== Résultat =====

<code json>
{
  "cluster":"Paris",
  "customers":421
}
</code>

----

====== Sprint 3-C.2-F ======

===== Cartographie CRM =====

----

====== Étape 16 — DTO ======

===== Créer =====

<code>
customer-map-point.dto.ts
</code>

----

===== Structure =====

<code ts>
export class CustomerMapPointDto {

customerId: string;

customerNumber: string;

latitude: number;

longitude: number;

city: string;

segment: string;

customerScore: number;
}
</code>

----

====== Étape 17 — Endpoint ======

===== Ajouter =====

<code http>
GET /customers/map
</code>

----

===== Retour =====

<code>
Points cartographiques CRM
</code>

----

====== Étape 18 — Préparation Front ======

Compatible :

<code>
Leaflet

Mapbox

Google Maps

OpenLayers
</code>

----

====== Sprint 3-C.2-G ======

===== Heatmaps CRM =====

----

====== Étape 19 — Endpoint ======

===== Ajouter =====

<code http>
GET /customers/heatmap
</code>

----

===== Retour =====

<code>
Densité clients

par zone géographique
</code>

----

====== Étape 20 — Agrégation ======

===== Calcul =====

<code>
Nombre clients

par géohash

ou

par ville
</code>

----

===== Exemple =====

<code json>
[
  {
    "city":"Paris",
    "count":421
  },
  {
    "city":"Lyon",
    "count":187
  }
]
</code>

----

====== Sprint 3-C.2-H ======

===== Zones Marketing =====

----

====== Étape 21 — Gestion GeoZone ======

===== Endpoints =====

<code http>
GET    /geo-zones

POST   /geo-zones

PUT    /geo-zones/{id}

DELETE /geo-zones/{id}
</code>

----

====== Étape 22 — Segmentation ======

===== Exemple =====

<code>
Zone Paris

↓

Clients VIP

↓

Campagne Marketing
</code>

----

====== Étape 23 — Attribution automatique ======

===== Workflow =====

<code>
Adresse Client

↓

GeoZone Matching

↓

Segment Géographique

↓

Marketing
</code>

----

====== Sprint 3-C.2-I ======

===== CRM Analytics =====

----

====== Étape 24 — Dashboard ======

===== Ajouter =====

<code http>
GET /customers/geographic-statistics
</code>

----

===== Retour =====

<code json>
{
  "countries":12,
  "regions":38,
  "cities":142,
  "topCity":"Paris"
}
</code>

----

====== Étape 25 — Métriques ======

<code>
Top villes

Top régions

Répartition pays

Répartition segments

Lifetime Value géographique
</code>

----

====== Sprint 3-C.2-J ======

===== Audit & Sécurité =====

----

====== Étape 26 — Journaliser ======

Dans :

<code>
AuditLog
</code>

----

===== Événements =====

<code>
CRM_GEO_SEARCH

CRM_MAP_VIEW

CRM_HEATMAP_VIEW

CRM_ZONE_CREATED

CRM_ZONE_UPDATED
</code>

----

====== Étape 27 — Multi-Tenant ======

===== Obligatoire =====

Toutes les requêtes :

<code ts>
tenantId
</code>

doivent filtrer :

<code>
GeoZone

Customer

CustomerAddress
</code>

----

====== Préparation Sprint 9 ======

Compatible avec :

<code>
Campaign

MarketingSegment

CampaignRecipient
</code>

----

====== Préparation Sprint 13 ======

Compatible avec :

<code>
Recommendation

AutomationScenario

AI Segmentation
</code>

----

====== Définition de terminé ======

Le Sprint 3-C.2 est terminé lorsque :

<code>
✓ GeoZone créée

✓ Distance Client

✓ Recherche par rayon

✓ Clustering CRM

✓ Cartographie CRM

✓ Heatmaps

✓ Dashboard géographique

✓ Multi-Tenant Security

✓ Swagger documenté
</code>

----

====== Livrables ======

<code>
GeoZone

GeoDistanceService

GeoSearchService

GeoClusteringService

GeoZoneService

CRM Map API

CRM Heatmap API

CRM Geographic Analytics
</code>

----

====== Sprint 3-D.1 — Gestion des Documents Client ======

===== Objectif =====

Implémenter la gestion documentaire CRM complète basée sur :

<code>
CustomerDocument
</code>

avec :

<code>
Upload

Stockage MinIO/S3

Catégorisation

Validation documentaire

Historisation

Audit

RGPD
</code>

----

====== Architecture cible ======

<code>
Customer

↓

CustomerDocument

↓

StorageService

↓

MinIO / S3

↓

CRM / Reservations / Compliance
</code>

----

====== Sprint 3-D.1-A ======

===== Modèle Prisma =====

----

====== Étape 1 — Création CustomerDocument ======

===== Ajouter dans schema.prisma =====

<code prisma>
model CustomerDocument {

id                    String
                        @id
                        @default(uuid())

tenantId              String

customerId            String

documentType          CustomerDocumentType

category              String?

name                  String

originalFilename      String

storagePath           String

mimeType              String

fileSize              Int

checksum              String?

version               Int
                        @default(1)

status                DocumentStatus
                        @default(PENDING)

expiresAt             DateTime?

verifiedAt            DateTime?

verifiedBy            String?

uploadedBy            String?

metadata              Json?

createdAt             DateTime
                        @default(now())

updatedAt             DateTime
                        @updatedAt

deletedAt             DateTime?

tenant                Tenant
                        @relation(
                          fields:[tenantId],
                          references:[id]
                        )

customer              Customer
                        @relation(
                          fields:[customerId],
                          references:[id],
                          onDelete:Cascade
                        )

@@index([tenantId])

@@index([customerId])

@@index([documentType])

@@index([status])

@@index([expiresAt])
}
</code>

----

====== Étape 2 — Enum DocumentType ======

===== Ajouter =====

<code prisma>
enum CustomerDocumentType {

IDENTITY_CARD

PASSPORT

DRIVING_LICENSE

VISA

RESIDENCE_PERMIT

CONTRACT

INVOICE

PROOF_OF_ADDRESS

INSURANCE

TAX_DOCUMENT

OTHER
}
</code>

----

====== Étape 3 — Enum DocumentStatus ======

===== Ajouter =====

<code prisma>
enum DocumentStatus {

PENDING

VERIFIED

REJECTED

EXPIRED

ARCHIVED
}
</code>

----

====== Étape 4 — Relation Customer ======

===== Ajouter =====

Dans :

<code prisma>
model Customer
</code>

<code prisma>
documents CustomerDocument[]
</code>

----

====== Étape 5 — Migration ======

===== Générer =====

<code bash>
npx prisma migrate dev \
--name customer_documents
</code>

----

===== Générer =====

<code bash>
npx prisma generate
</code>

----

====== Sprint 3-D.1-B ======

===== Module ======

----

====== Étape 6 — Création ======

<code>
src/modules/customer-documents

├── application
│
│   └── dto
│
│       ├── upload-customer-document.dto.ts
│       └── customer-document-response.dto.ts
│
├── domain
│
│   └── services
│
│       └── customer-document.service.ts
│
├── presentation
│
│   └── controllers
│
│       └── customer-document.controller.ts
│
└── customer-document.module.ts
</code>

----

====== Sprint 3-D.1-C ======

===== DTOs =====

----

====== Étape 7 — Upload DTO ======

===== Créer =====

<code>
upload-customer-document.dto.ts
</code>

----

===== Ajouter =====

<code ts>
export class UploadCustomerDocumentDto {

documentType:
    CustomerDocumentType;

category?: string;

expiresAt?: Date;
}
</code>

----

====== Étape 8 — Response DTO ======

===== Créer =====

<code>
customer-document-response.dto.ts
</code>

----

===== Ajouter =====

<code ts>
export class CustomerDocumentResponseDto {

id: string;

documentType: string;

status: string;

mimeType: string;

fileSize: number;

createdAt: Date;
}
</code>

----

====== Sprint 3-D.1-D ======

===== Validation documentaire =====

----

====== Étape 9 — Types autorisés ======

===== Créer =====

<code>
shared/constants

document-mime-types.ts
</code>

----

===== Ajouter =====

<code ts>
export const ALLOWED_DOCUMENT_TYPES = [

'application/pdf',

'image/jpeg',

'image/png',

'image/webp'
];
</code>

----

====== Étape 10 — Taille maximale ======

===== Ajouter =====

<code ts>
export const MAX_DOCUMENT_SIZE =

20 * 1024 * 1024;
</code>

----

====== Étape 11 — Validation ======

===== Vérifier =====

<code ts>
mimetype

size
</code>

----

===== Rejeter =====

<code>
EXE

ZIP

JS

BAT

SH
</code>

----

====== Sprint 3-D.1-E ======

===== CustomerDocumentService =====

----

====== Étape 12 — Création ======

===== Créer =====

<code>
customer-document.service.ts
</code>

----

===== Injection =====

<code ts>
@Injectable()
export class CustomerDocumentService {

constructor(

private readonly prisma:
      PrismaService,

private readonly storageService:
      StorageService
  ) {}
}
</code>

----

====== Étape 13 — Méthodes ======

===== Ajouter =====

<code ts>
findAll()

upload()

remove()

verify()

generateDownloadUrl()
</code>

----

====== Étape 14 — Upload ======

===== Chemin =====

<code ts>
customers/
{customerId}/
documents/
{uuid}
</code>

----

===== Upload MinIO =====

<code ts>
const storagePath =

await storageService
  .uploadDocument(
    file,
    customerId
  );
</code>

----

====== Étape 15 — Enregistrement ======

===== Créer =====

<code ts>
await prisma.customerDocument.create({

data: {

tenantId,

customerId,

documentType,

storagePath,

mimeType:
      file.mimetype,

fileSize:
      file.size,

status:
      'PENDING'
  }
});
</code>

----

====== Étape 16 — URL sécurisée ======

===== Générer =====

<code ts>
generateDownloadUrl()
</code>

----

===== Utiliser =====

<code>
Presigned URL

Expiration 1h
</code>

----

====== Sprint 3-D.1-F ======

===== Historisation CRM =====

----

====== Étape 17 — CustomerHistory ======

===== Ajouter =====

<code>
DOCUMENT_UPLOADED

DOCUMENT_VERIFIED

DOCUMENT_DELETED
</code>

----

===== Exemple =====

<code ts>
changedField:
  'document'
</code>

----

====== Étape 18 — Audit ======

===== Ajouter =====

Dans :

<code>
AuditLog
</code>

----

===== Événements =====

<code>
CUSTOMER_DOCUMENT_UPLOAD

CUSTOMER_DOCUMENT_VERIFY

CUSTOMER_DOCUMENT_DELETE
</code>

----

====== Sprint 3-D.1-G ======

===== Contrôleur =====

----

====== Étape 19 — Création ======

===== Créer =====

<code>
customer-document.controller.ts
</code>

----

===== Déclaration =====

<code ts>
@ApiTags(
  'Customer Documents'
)

@Controller(
  'customers/:id/documents'
)

@UseGuards(
  JwtAuthGuard
)

@ApiBearerAuth()
</code>

----

====== Étape 20 — GET ======

===== Route =====

<code http>
GET /customers/{id}/documents
</code>

----

====== Étape 21 — POST ======

===== Route =====

<code http>
POST /customers/{id}/documents
</code>

----

===== Upload =====

<code ts>
@UseInterceptors(
  FileInterceptor(
    'file'
  )
)
</code>

----

====== Étape 22 — DELETE ======

===== Route =====

<code http>
DELETE /customers/{id}/documents/{documentId}
</code>

----

====== Étape 23 — Download ======

===== Ajouter =====

<code http>
GET /customers/{id}/documents/{documentId}/download
</code>

----

====== Sprint 3-D.1-H ======

===== Vérification documentaire =====

----

====== Étape 24 — Endpoint ======

===== Ajouter =====

<code http>
PUT /customers/{id}/documents/{documentId}/verify
</code>

----

===== Action =====

<code>
Status

↓

VERIFIED
</code>

----

===== Métadonnées =====

<code>
verifiedAt

verifiedBy
</code>

----

====== Étape 25 — Expiration ======

===== Vérifier =====

<code>
Passport

Visa

Insurance
</code>

----

===== Automatisation future =====

Créer alertes :

<code>
30 jours avant expiration
</code>

----

====== Sprint 3-D.1-I ======

===== Module =====

----

====== Étape 26 — Création ======

===== Créer =====

<code>
customer-document.module.ts
</code>

----

===== Implémentation =====

<code ts>
@Module({

imports: [

PrismaModule,

AuthModule,

StorageModule
  ],

controllers: [

CustomerDocumentController
  ],

providers: [

CustomerDocumentService
  ],

exports: [

CustomerDocumentService
  ]
})
export class CustomerDocumentModule {}
</code>

----

====== Étape 27 — Swagger ======

===== Vérifier =====

<code http>
GET    /customers/{id}/documents

POST   /customers/{id}/documents

DELETE /customers/{id}/documents/{documentId}

GET    /customers/{id}/documents/{documentId}/download

PUT    /customers/{id}/documents/{documentId}/verify
</code>

----

====== Étape 28 — Exemple ======

===== Upload =====

<code>
Passeport.pdf
</code>

----

===== Résultat =====

<code>
Document stocké

MinIO

Status=PENDING

Historique CRM créé

Audit créé
</code>

----

====== Préparation Sprint 19 ======

Compatible avec :

<code>
Consent

ComplianceAudit

RetentionPolicy

DataClassification
</code>

----

====== Préparation Sprint 13 ======

Compatible avec :

<code>
OCR

Document AI

Extraction automatique

Classification automatique
</code>

----

====== Définition de terminé ======

Le Sprint 3-D.1 est terminé lorsque :

<code>
✓ CustomerDocument créé

✓ Upload opérationnel

✓ MinIO/S3 intégré

✓ Validation documentaire

✓ Vérification documentaire

✓ AuditLog intégré

✓ Historisation CRM

✓ URLs sécurisées

✓ Swagger documenté
</code>

----

====== Livrables ======

<code>
CustomerDocument

CustomerDocumentModule

CustomerDocumentController

CustomerDocumentService

Document Validation

MinIO Integration

Secure Download URLs
</code>

----

====== Sprint 3-D.2 — Gestion Documentaire Enterprise ======

===== Objectif =====

Faire évoluer le système documentaire CRM vers une GED Enterprise complète.

À l'issue de cette étape :

<code>
✓ Versioning

✓ OCR

✓ Classification automatique

✓ Extraction de données

✓ Expiration automatique

✓ Workflow de validation

✓ Signature électronique

✓ Conformité RGPD

✓ Préparation ISO27001
</code>

----

====== Architecture cible ======

<code>
Document Upload

↓

OCR Engine

↓

Classification Engine

↓

Extraction Engine

↓

Validation Workflow

↓

Storage

↓

Compliance
</code>

----

====== Sprint 3-D.2-A ======

===== Extension Prisma =====

----

====== Étape 1 — Versioning documentaire ======

===== Ajouter dans CustomerDocument =====

<code prisma>
parentDocumentId      String?

documentVersion       Int
                      @default(1)

isLatestVersion       Boolean
                      @default(true)

supersededAt          DateTime?
</code>

----

====== Étape 2 — Relation Version ======

===== Ajouter =====

<code prisma>
parentDocument CustomerDocument?
               @relation(
                 "DocumentVersions",
                 fields:[parentDocumentId],
                 references:[id]
               )

versions CustomerDocument[]
         @relation(
           "DocumentVersions"
         )
</code>

----

====== Étape 3 — OCR ======

===== Ajouter =====

<code prisma>
ocrStatus             OcrStatus
                      @default(PENDING)

ocrText               String?

ocrExecutedAt         DateTime?
</code>

----

====== Étape 4 — Classification ======

===== Ajouter =====

<code prisma>
classificationScore   Float?

classificationSource  String?

detectedDocumentType  String?
</code>

----

====== Étape 5 — Extraction ======

===== Ajouter =====

<code prisma>
extractedData         Json?

extractionStatus      String?
</code>

----

====== Étape 6 — Signature ======

===== Ajouter =====

<code prisma>
signatureRequired     Boolean
                      @default(false)

signedAt              DateTime?

signatureProvider     String?

signatureReference    String?
</code>

----

====== Étape 7 — Enum OCR ======

===== Ajouter =====

<code prisma>
enum OcrStatus {

PENDING

PROCESSING

COMPLETED

FAILED
}
</code>

----

====== Étape 8 — Migration ======

===== Générer =====

<code bash>
npx prisma migrate dev \
--name customer_documents_enterprise
</code>

----

===== Générer =====

<code bash>
npx prisma generate
</code>

----

====== Sprint 3-D.2-B ======

===== GED Workflow =====

----

====== Étape 9 — Création DocumentWorkflow ======

===== Ajouter =====

<code prisma>
model DocumentWorkflow {

id                    String
                        @id
                        @default(uuid())

tenantId              String

name                  String

documentType          String

active                Boolean
                        @default(true)

createdAt             DateTime
                        @default(now())

updatedAt             DateTime
                        @updatedAt

tenant                Tenant
                        @relation(
                          fields:[tenantId],
                          references:[id]
                        )

steps                 DocumentWorkflowStep[]
}
</code>

----

====== Étape 10 — Workflow Steps ======

===== Ajouter =====

<code prisma>
model DocumentWorkflowStep {

id                    String
                        @id
                        @default(uuid())

workflowId            String

name                  String

stepOrder             Int

validatorRole         String?

required              Boolean
                        @default(true)

workflow              DocumentWorkflow
                        @relation(
                          fields:[workflowId],
                          references:[id],
                          onDelete:Cascade
                        )

@@index([workflowId])

@@index([stepOrder])
}
</code>

----

====== Étape 11 — Workflow Instance ======

===== Ajouter =====

<code prisma>
model CustomerDocumentWorkflow {

id                    String
                        @id
                        @default(uuid())

documentId            String

currentStep           Int
                        @default(1)

status                WorkflowStatus
                        @default(PENDING)

startedAt             DateTime
                        @default(now())

completedAt           DateTime?

document              CustomerDocument
                        @relation(
                          fields:[documentId],
                          references:[id]
                        )
}
</code>

----

====== Étape 12 — Enum Workflow ======

===== Ajouter =====

<code prisma>
enum WorkflowStatus {

PENDING

IN_PROGRESS

APPROVED

REJECTED

CANCELLED
}
</code>

----

====== Sprint 3-D.2-C ======

===== OCR Module =====

----

====== Étape 13 — Création ======

<code>
src/modules/document-ai
</code>

----

===== Structure =====

<code>
document-ai

├── domain
│
│   └── services
│
│       ├── ocr.service.ts
│
│       ├── document-classifier.service.ts
│
│       ├── extraction.service.ts
│
│       └── expiration-monitor.service.ts
│
└── document-ai.module.ts
</code>

----

====== Étape 14 — OCR Service ======

===== Méthodes =====

<code ts>
processDocument()

extractText()

detectLanguage()
</code>

----

===== Prévoir =====

Connecteurs futurs :

<code>
Tesseract

AWS Textract

Google Vision

Azure Form Recognizer
</code>

----

====== Étape 15 — OCR Workflow ======

<code>
Upload

↓

OCR

↓

Classification

↓

Extraction

↓

Validation

↓

Archive
</code>

----

====== Sprint 3-D.2-D ======

===== Classification Automatique =====

----

====== Étape 16 — DocumentClassifier ======

===== Méthodes =====

<code ts>
classify()

detectPassport()

detectInvoice()

detectContract()
</code>

----

====== Étape 17 — Classification ======

===== Exemple =====

<code>
Passeport

↓

IDENTITY_DOCUMENT
</code>

----

===== Résultat =====

<code ts>
classificationScore:
  0.98
</code>

----

====== Étape 18 — Mise à jour ======

===== Ajouter =====

<code ts>
detectedDocumentType

classificationScore

classificationSource
</code>

----

====== Sprint 3-D.2-E ======

===== Extraction de données =====

----

====== Étape 19 — ExtractionService ======

===== Méthodes =====

<code ts>
extractIdentityData()

extractInvoiceData()

extractContractData()
</code>

----

====== Étape 20 — Exemple ======

===== Passeport =====

<code>
Nom

Prénom

Nationalité

Date expiration

Numéro
</code>

----

===== Sauvegarder =====

<code prisma>
extractedData Json
</code>

----

====== Étape 21 — Exemple ======

===== Facture =====

<code>
Numéro facture

Montant

Date

TVA
</code>

----

====== Sprint 3-D.2-F ======

===== Expiration Automatique =====

----

====== Étape 22 — ExpirationMonitor ======

===== Méthodes =====

<code ts>
checkExpiringDocuments()

markExpiredDocuments()
</code>

----

====== Étape 23 — Workflow ======

<code>
Tous les jours

↓

Expiration < 30 jours

↓

Notification

↓

Alert
</code>

----

====== Étape 24 — Statut ======

===== Mise à jour =====

<code>
EXPIRED
</code>

automatiquement.

----

====== Sprint 3-D.2-G ======

===== Signature Électronique =====

----

====== Étape 25 — Préparation ======

===== Ajouter =====

<code>
SignatureProvider
</code>

----

===== Fournisseurs =====

<code>
DocuSign

Yousign

Adobe Sign
</code>

----

====== Étape 26 — Workflow ======

<code>
Document

↓

Signature Request

↓

Signed

↓

Archive
</code>

----

====== Étape 27 — Endpoints ======

===== Ajouter =====

<code http>
POST /customers/{id}/documents/{documentId}/sign

GET /customers/{id}/documents/{documentId}/signature
</code>

----

====== Sprint 3-D.2-H ======

===== API GED =====

----

====== Étape 28 — Endpoints ======

===== Ajouter =====

<code http>
POST /documents/{id}/ocr

POST /documents/{id}/classify

POST /documents/{id}/extract

GET  /documents/{id}/workflow

PUT  /documents/{id}/approve

PUT  /documents/{id}/reject
</code>

----

====== Étape 29 — Permissions ======

===== RBAC =====

<code>
documents.read

documents.write

documents.verify

documents.approve

documents.sign
</code>

----

====== Sprint 3-D.2-I ======

===== Audit & Conformité =====

----

====== Étape 30 — AuditLog ======

===== Journaliser =====

<code>
DOCUMENT_OCR

DOCUMENT_CLASSIFIED

DOCUMENT_EXTRACTED

DOCUMENT_APPROVED

DOCUMENT_REJECTED

DOCUMENT_SIGNED

DOCUMENT_EXPIRED
</code>

----

====== Étape 31 — DataClassification ======

===== Préparer =====

Compatible avec :

<code>
PII

IDENTITY

FINANCIAL

LEGAL

CONFIDENTIAL
</code>

----

====== Étape 32 — Retention ======

===== Préparer =====

Compatible avec :

<code>
RetentionPolicy

ComplianceAudit

GDPR
</code>

----

====== Sprint 3-D.2-J ======

===== Dashboard GED =====

----

====== Étape 33 — Statistiques ======

===== Ajouter =====

<code http>
GET /documents/statistics
</code>

----

===== Retour =====

<code json>
{
  "totalDocuments": 5234,
  "verifiedDocuments": 4987,
  "expiredDocuments": 74,
  "pendingValidation": 32,
  "pendingSignatures": 11
}
</code>

----

====== Étape 34 — Recherche GED ======

===== Ajouter =====

<code http>
GET /documents/search
</code>

----

===== Filtres =====

<code>
Type

Statut

Date expiration

Client

OCR

Workflow
</code>

----

====== Préparation Sprint 13 ======

Compatible avec :

<code>
KnowledgeDocument

Recommendation

AI Assistant

Document AI
</code>

----

====== Préparation Sprint 19 ======

Compatible avec :

<code>
ComplianceAudit

DataClassification

RetentionPolicy

SecurityIncident
</code>

----

====== Définition de terminé ======

Le Sprint 3-D.2 est terminé lorsque :

<code>
✓ Versioning

✓ OCR

✓ Classification automatique

✓ Extraction de données

✓ Expiration automatique

✓ Workflow validation

✓ Signature électronique

✓ Audit GED

✓ Conformité préparée
</code>

----

====== Livrables ======

<code>
DocumentWorkflow

DocumentWorkflowStep

CustomerDocumentWorkflow

OcrService

DocumentClassifierService

ExtractionService

ExpirationMonitorService

Enterprise GED API
</code>

----

====== Sprint 3-E.1 — Gestion des Tags CRM ======

===== Objectif =====

Implémenter un moteur de tags CRM permettant :

<code>
Segmentation

Classification

Automatisation

Marketing

CRM Analytics

Personnalisation
</code>

basé sur :

<code>
CustomerTag

CustomerTagAssignment
</code>

----

====== Architecture cible ======

<code>
Customer

↓

CustomerTagAssignment

↓

CustomerTag

↓

CRM Segmentation

↓

Campaigns

↓

Automation
</code>

----

====== Sprint 3-E.1-A ======

===== Modèle Prisma =====

----

====== Étape 1 — Création CustomerTag ======

===== Ajouter dans schema.prisma =====

<code prisma>
model CustomerTag {

id                    String
                        @id
                        @default(uuid())

tenantId              String

name                  String

code                  String

description           String?

color                 String?

icon                  String?

category              String?

tagType               CustomerTagType
                        @default(MANUAL)

active                Boolean
                        @default(true)

usageCount            Int
                        @default(0)

createdAt             DateTime
                        @default(now())

updatedAt             DateTime
                        @updatedAt

tenant                Tenant
                        @relation(
                          fields:[tenantId],
                          references:[id]
                        )

assignments           CustomerTagAssignment[]

@@unique([
    tenantId,
    code
  ])

@@index([tenantId])

@@index([tagType])

@@index([active])
}
</code>

----

====== Étape 2 — Création CustomerTagAssignment ======

===== Ajouter =====

<code prisma>
model CustomerTagAssignment {

id                    String
                        @id
                        @default(uuid())

customerId            String

tagId                 String

assignedBy            String?

assignedAt            DateTime
                        @default(now())

source                String?
                        @default("MANUAL")

expiresAt             DateTime?

metadata              Json?

customer              Customer
                        @relation(
                          fields:[customerId],
                          references:[id],
                          onDelete:Cascade
                        )

tag                   CustomerTag
                        @relation(
                          fields:[tagId],
                          references:[id],
                          onDelete:Cascade
                        )

@@unique([
    customerId,
    tagId
  ])

@@index([customerId])

@@index([tagId])

@@index([assignedAt])
}
</code>

----

====== Étape 3 — Enum TagType ======

===== Ajouter =====

<code prisma>
enum CustomerTagType {

MANUAL

DYNAMIC

SYSTEM

MARKETING

LOYALTY

RISK
}
</code>

----

====== Étape 4 — Relations ======

===== Ajouter dans Customer =====

<code prisma>
tags CustomerTagAssignment[]
</code>

----

====== Étape 5 — Migration ======

===== Générer =====

<code bash>
npx prisma migrate dev \
--name customer_tags
</code>

----

===== Générer =====

<code bash>
npx prisma generate
</code>

----

====== Sprint 3-E.1-B ======

===== Module =====

----

====== Étape 6 — Création ======

<code>
src/modules/customer-tags

├── application
│
│   └── dto
│
│       ├── create-customer-tag.dto.ts
│
│       ├── assign-customer-tag.dto.ts
│
│       └── customer-tag-response.dto.ts
│
├── domain
│
│   └── services
│
│       └── customer-tag.service.ts
│
├── presentation
│
│   └── controllers
│
│       └── customer-tag.controller.ts
│
└── customer-tag.module.ts
</code>

----

====== Sprint 3-E.1-C ======

===== DTOs =====

----

====== Étape 7 — CreateCustomerTagDto ======

===== Créer =====

<code>
create-customer-tag.dto.ts
</code>

----

===== Implémentation =====

<code ts>
export class CreateCustomerTagDto {

code: string;

description?: string;

color?: string;

icon?: string;

category?: string;

tagType?: string;
}
</code>

----

====== Étape 8 — AssignCustomerTagDto ======

===== Créer =====

<code>
assign-customer-tag.dto.ts
</code>

----

===== Implémentation =====

<code ts>
export class AssignCustomerTagDto {

tagId: string;

expiresAt?: Date;
}
</code>

----

====== Sprint 3-E.1-D ======

===== CustomerTagService =====

----

====== Étape 9 — Méthodes ======

===== Ajouter =====

<code ts>
findTags()

createTag()

assignTag()

removeTag()

getCustomerTags()

recalculateUsage()
</code>

----

====== Étape 10 — Création Tag ======

===== Vérifier =====

<code>
Code unique

par tenant
</code>

----

===== Création =====

<code ts>
await prisma.customerTag.create({

data: {

tenantId,

...dto
  }
});
</code>

----

====== Étape 11 — Affectation ======

===== Vérifier =====

<code>
Customer

Tag

Même tenant
</code>

----

===== Affecter =====

<code ts>
await prisma.customerTagAssignment.create({

data: {

customerId,

tagId,

assignedBy:
      userId
  }
});
</code>

----

====== Étape 12 — Usage Count ======

===== Mettre à jour =====

<code ts>
await prisma.customerTag.update({

where: {

id: tagId
  },

data: {

usageCount: {

increment: 1
    }
  }
});
</code>

----

====== Étape 13 — Suppression ======

===== Supprimer =====

<code>
CustomerTagAssignment
</code>

----

===== Décrémenter =====

<code>
usageCount
</code>

----

====== Sprint 3-E.1-E ======

===== Tags Dynamiques =====

----

====== Étape 14 — Extension CustomerTag ======

===== Ajouter =====

<code prisma>
dynamicRule Json?
</code>

----

====== Étape 15 — Exemple ======

===== VIP =====

<code json>
{
  "customerScore": {
    "gte": 80
  }
}
</code>

----

===== High Revenue =====

<code json>
{
  "lifetimeValue": {
    "gte": 10000
  }
}
</code>

----

====== Étape 16 — Recalcul ======

===== Méthode =====

<code ts>
evaluateDynamicTags()
</code>

----

===== Déclencheurs =====

<code>
Customer Updated

Reservation Created

Score Updated
</code>

----

====== Sprint 3-E.1-F ======

===== Tags Système =====

----

====== Étape 17 — Tags par défaut ======

===== Seed =====

<code>
VIP

FREQUENT

CORPORATE

HIGH_VALUE

INACTIVE

BLACKLISTED

HIGH_RISK

NEWSLETTER

LOYALTY
</code>

----

====== Étape 18 — Attribution automatique ======

===== Exemple =====

<code>
Segment = VIP

↓

Tag VIP
</code>

----

===== Exemple =====

<code>
Risk = HIGH

↓

Tag HIGH_RISK
</code>

----

====== Sprint 3-E.1-G ======

===== Contrôleur =====

----

====== Étape 19 — Création ======

===== Créer =====

<code>
customer-tag.controller.ts
</code>

----

===== Déclaration =====

<code ts>
@ApiTags('Customer Tags')

@Controller('customers')
</code>

----

====== Étape 20 — Liste tags ======

===== Route =====

<code http>
GET /customers/tags
</code>

----

====== Étape 21 — Création tag ======

===== Route =====

<code http>
POST /customers/tags
</code>

----

====== Étape 22 — Affectation ======

===== Route =====

<code http>
POST /customers/{id}/tags
</code>

----

====== Étape 23 — Suppression ======

===== Route =====

<code http>
DELETE /customers/{id}/tags/{tagId}
</code>

----

====== Étape 24 — Consultation ======

===== Ajouter =====

<code http>
GET /customers/{id}/tags
</code>

----

====== Sprint 3-E.1-H ======

===== Recherche CRM =====

----

====== Étape 25 — Filtre Tags ======

===== Ajouter dans =====

<code>
CustomerQueryDto
</code>

----

===== Champ =====

<code ts>
tags?: string[];
</code>

----

====== Étape 26 — Recherche ======

===== Exemple =====

<code>
VIP

+

NEWSLETTER
</code>

----

===== Résultat =====

<code>
Clients correspondants
</code>

----

====== Étape 27 — Segmentation ======

===== Exemple =====

<code http>
GET /customers/search
</code>

----

===== Utilisation =====

<code>
Marketing

Campagnes

Automatisation
</code>

----

====== Sprint 3-E.1-I ======

===== Audit & Historisation =====

----

====== Étape 28 — CustomerHistory ======

===== Journaliser =====

<code>
TAG_ASSIGNED

TAG_REMOVED
</code>

----

====== Étape 29 — AuditLog ======

===== Ajouter =====

<code>
CUSTOMER_TAG_CREATED

CUSTOMER_TAG_ASSIGNED

CUSTOMER_TAG_REMOVED

CUSTOMER_DYNAMIC_TAG_UPDATED
</code>

----

====== Sprint 3-E.1-J ======

===== Préparation Sprint 9 =====

----

===== Compatible =====

<code>
Campaign

CampaignRecipient

MarketingSegment

MarketingEvent
</code>

----

====== Préparation Sprint 13 ======

Compatible avec :

<code>
AutomationRule

Recommendation

AiConversation

AutomationScenario
</code>

----

====== Préparation Sprint 20 ======

Compatible avec :

<code>
Customer Analytics

Predictive Segmentation

Lead Scoring

AI Recommendations
</code>

----

====== Définition de terminé ======

Le Sprint 3-E.1 est terminé lorsque :

<code>
✓ CustomerTag créé

✓ CustomerTagAssignment créé

✓ Tags manuels

✓ Tags dynamiques

✓ Segmentation CRM

✓ Recherche par tags

✓ AuditLog intégré

✓ Historisation CRM

✓ Swagger documenté
</code>

----

====== Livrables ======

<code>
CustomerTag

CustomerTagAssignment

CustomerTagModule

CustomerTagController

CustomerTagService

Dynamic Tag Engine
</code>

----

====== Sprint 3-E.2 — Segmentation CRM Avancée & Smart Tags ======

===== Objectif =====

Transformer le moteur de tags CRM en moteur intelligent de segmentation Enterprise.

À l'issue de cette étape :

<code>
✓ Tag Rules Engine

✓ Smart Tags IA

✓ Segmentation comportementale

✓ Scoring automatique

✓ Segments prédictifs

✓ Marketing Intelligence

✓ CRM Intelligence Engine
</code>

----

====== Architecture cible ======

<code>
Customer Data

↓

Behavior Analysis

↓

Scoring Engine

↓

Tag Rules Engine

↓

Smart Segments

↓

Marketing Intelligence

↓

Automation
</code>

----

====== Sprint 3-E.2-A ======

===== Extension Prisma =====

----

====== Étape 1 — Création SmartSegment ======

===== Ajouter dans schema.prisma =====

<code prisma>
model SmartSegment {

id                    String
                        @id
                        @default(uuid())

tenantId              String

name                  String

code                  String

description           String?

segmentType           SmartSegmentType

active                Boolean
                        @default(true)

ruleDefinition        Json

estimatedCustomers    Int
                        @default(0)

lastCalculatedAt      DateTime?

createdAt             DateTime
                        @default(now())

updatedAt             DateTime
                        @updatedAt

tenant                Tenant
                        @relation(
                          fields:[tenantId],
                          references:[id]
                        )

@@unique([
    tenantId,
    code
  ])

@@index([tenantId])

@@index([segmentType])

@@index([active])
}
</code>

----

====== Étape 2 — Création CustomerScore ======

===== Ajouter =====

<code prisma>
model CustomerScore {

id                    String
                        @id
                        @default(uuid())

customerId            String
                        @unique

engagementScore       Int
                        @default(0)

loyaltyScore          Int
                        @default(0)

revenueScore          Int
                        @default(0)

marketingScore        Int
                        @default(0)

riskScore             Int
                        @default(0)

predictiveScore       Int
                        @default(0)

overallScore          Int
                        @default(0)

calculatedAt          DateTime
                        @default(now())

customer              Customer
                        @relation(
                          fields:[customerId],
                          references:[id],
                          onDelete:Cascade
                        )
}
</code>

----

====== Étape 3 — Enum SegmentType ======

===== Ajouter =====

<code prisma>
enum SmartSegmentType {

BEHAVIORAL

REVENUE

LOYALTY

MARKETING

PREDICTIVE

RISK

AI_GENERATED
}
</code>

----

====== Étape 4 — Relations ======

===== Ajouter dans Customer =====

<code prisma>
score CustomerScore?
</code>

----

====== Étape 5 — Migration ======

===== Générer =====

<code bash>
npx prisma migrate dev \
--name crm_smart_segments
</code>

----

===== Générer =====

<code bash>
npx prisma generate
</code>

----

====== Sprint 3-E.2-B ======

===== Tag Rules Engine =====

----

====== Étape 6 — Création ======

<code>
crm-tag-rules.service.ts
</code>

----

===== Méthodes =====

<code ts>
evaluateRules()

executeRule()

assignTags()

removeTags()
</code>

----

====== Étape 7 — Structure Rule ======

===== Exemple =====

<code json>
{
  "conditions": [
    {
      "field": "lifetimeValue",
      "operator": "gte",
      "value": 10000
    }
  ],
  "action": {
    "tag": "HIGH_VALUE"
  }
}
</code>

----

====== Étape 8 — Opérateurs ======

<code>
eq

neq

gt

gte

lt

lte

contains

in

notIn
</code>

----

====== Sprint 3-E.2-C ======

===== Scoring Automatique =====

----

====== Étape 9 — Création ======

<code>
customer-scoring.service.ts
</code>

----

===== Méthodes =====

<code ts>
calculateOverallScore()

calculateEngagement()

calculateLoyalty()

calculateRevenue()

calculateRisk()
</code>

----

====== Étape 10 — Engagement ======

===== Critères =====

<code>
Communications

Ouvertures emails

Réponses

Activité CRM
</code>

----

===== Score =====

----

====== Étape 11 — Loyalty ======

===== Critères =====

<code>
Ancienneté

Réservations

Lifetime Value

VIP
</code>

----

====== Étape 12 — Revenue ======

===== Critères =====

<code>
Total Revenue

Average Basket

Frequency
</code>

----

====== Sprint 3-E.2-D ======

===== Smart Tags IA =====

----

====== Étape 13 — Création ======

<code>
smart-tag.service.ts
</code>

----

===== Méthodes =====

<code ts>
generateSmartTags()

predictCustomerCategory()

recommendTags()
</code>

----

====== Étape 14 — Smart Tags ======

===== Exemples =====

<code>
HIGH_VALUE

FUTURE_VIP

AT_RISK

LOYAL_CUSTOMER

UPSELL_TARGET

CHURN_RISK
</code>

----

====== Étape 15 — Attribution ======

===== Exemple =====

<code>
Lifetime Value élevé

+

Croissance forte

↓

FUTURE_VIP
</code>

----

====== Sprint 3-E.2-E ======

===== Segmentation Comportementale =====

----

====== Étape 16 — BehaviorSegmentService ======

===== Créer =====

<code>
behavior-segmentation.service.ts
</code>

----

===== Segments =====

<code>
Frequent Traveler

Weekend Traveler

Luxury Traveler

Business Traveler

Seasonal Traveler

Family Traveler
</code>

----

====== Étape 17 — Analyse ======

===== Sources =====

<code>
Reservations

Invoices

Communications

Preferences
</code>

----

====== Étape 18 — Exemple ======

<code>
80% réservations

Vendredi → Dimanche

↓

Weekend Traveler
</code>

----

====== Sprint 3-E.2-F ======

===== Segments Prédictifs =====

----

====== Étape 19 — PredictiveSegmentation ======

===== Créer =====

<code>
predictive-segmentation.service.ts
</code>

----

===== Segments =====

<code>
Future VIP

Future Churn

Future Corporate

Future High Revenue

Future Ambassador
</code>

----

====== Étape 20 — Prévision ======

===== Critères =====

<code>
Croissance dépenses

Fréquence réservations

Engagement

Satisfaction
</code>

----

====== Étape 21 — Exemple ======

<code>
Croissance 30%

↓

Future VIP
</code>

----

====== Sprint 3-E.2-G ======

===== Marketing Intelligence =====

----

====== Étape 22 — Création ======

<code>
marketing-intelligence.service.ts
</code>

----

===== Méthodes =====

<code ts>
findCampaignTargets()

findUpsellTargets()

findRetentionTargets()

findReferralCandidates()
</code>

----

====== Étape 23 — Exemples ======

===== Upsell =====

<code>
VIP

+

Revenue > 5000

↓

Campagne Premium
</code>

----

===== Rétention =====

<code>
CHURN_RISK

↓

Campagne Réactivation
</code>

----

====== Sprint 3-E.2-H ======

===== API CRM Intelligence =====

----

====== Étape 24 — Endpoints ======

===== Ajouter =====

<code http>
GET /customers/segments/smart

GET /customers/tags/smart

GET /customers/scoring

POST /customers/scoring/recalculate

POST /customers/segments/recalculate
</code>

----

====== Étape 25 — Exemple ======

===== Réponse =====

<code json>
{
  "customerId":"123",
  "overallScore":87,
  "smartTags":[
    "VIP",
    "LOYAL_CUSTOMER",
    "UPSELL_TARGET"
  ]
}
</code>

----

====== Sprint 3-E.2-I ======

===== Dashboard CRM Intelligence =====

----

====== Étape 26 — KPI ======

===== Ajouter =====

<code http>
GET /customers/intelligence/dashboard
</code>

----

===== Retour =====

<code json>
{
  "futureVip":54,
  "churnRisk":23,
  "upsellTargets":118,
  "loyalCustomers":401
}
</code>

----

====== Étape 27 — Visualisation ======

===== Répartition =====

<code>
Segments

Scores