PD-231 — Plan d'implémentation¶

📚 Navigation User Story

| Document | | | ---------- | -- | | 📋 [Spécification](PD-231-specification.md) | | | 🛠️ **Plan d'implémentation** | *(ce document)* | | ✅ [Critères d'acceptation](PD-231-acceptability.md) | | | 📝 [Retour d'expérience](PD-231-rex.md) | | [← Retour à site-vitrine](../PD-225-epic.md) · [↑ Index User Story](index.md)

1. Découpage en composants¶

Structure CI/CD¶

ProbatioVault-site/
├── .gitlab-ci.yml            # Pipeline principal
├── package.json              # Scripts npm
├── public/
│   └── _headers              # Headers sécurité GitLab Pages
└── scripts/
    └── deploy-preview.sh     # Script preview MR (optionnel)

Composants clés¶

Composant	Responsabilité
`.gitlab-ci.yml`	Définition du pipeline
`pages` job	Déploiement GitLab Pages
`preview` job	Artefacts preview MR
`_headers`	Headers HTTP personnalisés

2. Flux techniques¶

Pipeline production (main)¶

Push sur main
    │
    ▼
GitLab CI déclenché
    │
    ├── Stage: build
    │   └── npm ci && npm run build
    │
    ├── Stage: test
    │   ├── npm run lint
    │   └── npm run test:a11y
    │
    └── Stage: deploy
        └── Job: pages
            ├── mv dist public
            └── Artifacts → GitLab Pages
    │
    ▼
https://probatiovault.com (live)

Pipeline preview (MR)¶

Push sur feature-branch
    │
    ▼
GitLab CI déclenché
    │
    ├── Stage: build
    │   └── npm ci && npm run build
    │
    ├── Stage: test
    │   └── npm run lint
    │
    └── Stage: preview
        └── Job: pages:preview
            ├── mv dist public
            ├── Artifacts (expire 7 days)
            └── Environment: review/$CI_COMMIT_REF_SLUG
    │
    ▼
URL preview affichée dans MR

3. Mapping invariants → mécanismes¶

Invariant	Mécanisme technique
INV-1 : Déploiement auto sur main	`only: [main]` sur job `pages`
INV-2 : Preview MR	Job `pages:preview` avec `environment`

Configuration .gitlab-ci.yml¶

# .gitlab-ci.yml
image: node:20

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/

stages:
  - build
  - test
  - deploy

# =============================================================================
# BUILD
# =============================================================================
build:
  stage: build
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour

# =============================================================================
# TEST
# =============================================================================
lint:
  stage: test
  script:
    - npm ci
    - npm run lint
  needs: []

typecheck:
  stage: test
  script:
    - npm ci
    - npm run check
  needs: []

a11y:
  stage: test
  script:
    - npm ci
    - npm run build
    - npm run preview &
    - sleep 5
    - npx pa11y-ci --config pa11y.config.js
  needs: []
  allow_failure: true  # Warning, pas bloquant

# =============================================================================
# DEPLOY PRODUCTION
# =============================================================================
pages:
  stage: deploy
  script:
    - rm -rf public
    - mv dist public
  artifacts:
    paths:
      - public
  only:
    - main
  needs:
    - build
    - lint
    - typecheck
  environment:
    name: production
    url: https://probatiovault.com

# =============================================================================
# PREVIEW MR
# =============================================================================
pages:preview:
  stage: deploy
  script:
    - rm -rf public
    - mv dist public
    - echo "Preview URL: $CI_PAGES_URL"
  artifacts:
    paths:
      - public
    expire_in: 7 days
  except:
    - main
  needs:
    - build
    - lint
  when: manual  # INV-2: validation manuelle
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: $CI_PAGES_URL
    on_stop: stop_preview
    auto_stop_in: 7 days

stop_preview:
  stage: deploy
  script:
    - echo "Stopping preview environment"
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  except:
    - main

Scripts package.json¶

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "check": "astro check",
    "lint": "eslint src --ext .astro,.ts,.js",
    "lint:fix": "eslint src --ext .astro,.ts,.js --fix",
    "test:a11y": "pa11y-ci --config pa11y.config.js"
  }
}

4. Gestion des erreurs¶

Erreur	Cause	Mitigation
Build fail	Erreur TypeScript	`astro check` en stage test
Lint fail	Code non conforme	Job lint bloquant
Pages fail	Artefacts manquants	`needs: [build]`
Preview 404	Mauvais chemin	Vérifier `mv dist public`

Notifications¶

# .gitlab-ci.yml (ajout)
.notify_failure: &notify_failure
  after_script:
    - |
      if [ "$CI_JOB_STATUS" == "failed" ]; then
        curl -X POST "$SLACK_WEBHOOK" \
          -H 'Content-Type: application/json' \
          -d "{\"text\": \"Pipeline failed: $CI_PROJECT_NAME - $CI_COMMIT_REF_NAME\"}"
      fi

5. Impacts sécurité¶

Aspect	Mesure
Secrets CI	Variables GitLab masked
Headers HTTP	`_headers` avec CSP
Preview exposure	`when: manual` obligatoire
HTTPS	Forcé par GitLab Pages

Headers GitLab Pages¶

# public/_headers
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Permissions-Policy: geolocation=(), microphone=(), camera=()
  Content-Security-Policy: default-src 'self'; script-src 'self' https://www.googletagmanager.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self' https://api.brevo.com

6. Hypothèses techniques¶

Hypothèse	Justification
GitLab Pages disponible	Projet GitLab SaaS
Node 20 runner	Image Docker officielle
`_headers` supporté	GitLab Pages supporte format
DNS configuré	probatiovault.com → GitLab

7. Points de vigilance¶

Point	Risque	Action
Cache CI	Build obsolète	Clé cache par branche
Temps pipeline	Trop long	Paralléliser jobs test
Preview cleanup	Artefacts accumulés	`expire_in: 7 days`
Rollback	Régression prod	Re-run pipeline ancien commit
DNS propagation	Latence après deploy	Attendre 2-5 min

Fichiers à créer/modifier¶

Fichier	Description
`.gitlab-ci.yml`	Pipeline complet
`public/_headers`	Headers sécurité
`package.json`	Scripts npm
`pa11y.config.js`	Config a11y (si pas déjà créé)