# CI Bitbucket de kView INVESTOR

## À quoi elle sert

Une fois Pipelines activé, le fichier racine `bitbucket-pipelines.yml`
transforme chaque push Bitbucket en contrôle reproductible du dépôt. En termes
simples, Bitbucket reconstruit kView INVESTOR dans une machine neuve, crée une base
jetable, puis vérifie que le backend, le frontend et les parcours navigateur
fonctionnent ensemble.

Cette CI ne déploie rien. Elle ne se connecte ni à la base locale, ni à l'UAT,
ni à une future production.

## Ce que le quality gate vérifie

Le job unique `kView INVESTOR quality gate` utilise :

- PHP 8.4 et Composer vérifié par la signature officielle de l'installateur ;
- Node 22.23.1, dont l'archive est vérifiée par le checksum officiel ;
- PostgreSQL 16 dans un service isolé nommé `kview_investor_testing` ;
- Chromium installé par la version Playwright verrouillée dans
  `package-lock.json`.

Il exécute ensuite, dans cet ordre :

1. validation Composer et installation exacte des dépendances PHP/JavaScript ;
   l'audit Composer bloque tout avis connu et l'audit npm les vulnérabilités de
   sévérité haute ou critique ;
2. migrations fraîches, cache des vues et suite PHPUnit complète ;
3. Pint et PHPStan sur les fichiers PHP modifiés par la branche ;
4. typecheck TypeScript, ESLint et Vitest ;
5. contrats de publication kView et consommateurs propres Laravel 11, 12 et
   13 ;
6. build Vite de production ;
7. nouvelle base fraîche, données de démonstration, compte E2E aléatoire et
   matrice Playwright desktop/mobile.

Le job est volontairement unique : le build et les tests navigateur utilisent
exactement les dépendances et les assets qui viennent de réussir les contrôles
unitaires. On pourra le paralléliser plus tard si sa durée devient gênante.

## Isolation et secrets

La base `kview_investor_testing`, son utilisateur et son mot de passe n'existent que
dans les conteneurs du pipeline. `migrate:fresh` y est donc sûr et ne peut pas
effacer les données d'un développeur. Le garde-fou PHP des tests refuse par
ailleurs toute base PostgreSQL dont le nom ne finit pas par `_test` ou
`_testing`.

Le compte navigateur administrateur `kview_investor-ci@example.test` est créé après
un second `migrate:fresh` avec l'option explicite `--admin`, car les parcours
Settings couvrent des surfaces réservées aux administrateurs. Son mot de passe
est généré aléatoirement dans le job, conservé
uniquement dans une variable shell et jamais écrit dans le dépôt ni affiché.
Les tests PHP gardent des sessions en mémoire ; le stockage fichier n'est
activé qu'ensuite pour que Chromium puisse conserver sa session entre requêtes.

Les secrets `UAT_SMOKE_*` ne sont pas requis : `kview_investor:verify-uat` reste une
porte de déploiement à lancer sur le véritable environnement UAT. Il ne fait
pas partie d'une CI de push isolée.

## Dette PHP historique

La baseline du projet documente encore une dette globale Pint/PHPStan dans du
code antérieur à la migration. Pour que la CI soit utile dès maintenant sans
masquer de nouvelle dette :

- PHPUnit couvre toujours tout le dépôt ;
- Pint contrôle tous les fichiers PHP ajoutés ou modifiés par la branche ;
- PHPStan contrôle les fichiers applicatifs modifiés sous `app`, `database` et
  `routes` ;
- TypeScript, ESLint, Vitest, les contrats kView, le build et Playwright restent
  globaux.

Sur une branche, la comparaison part du merge-base avec `master`. Sur
`master`, elle part du commit versionné
`017a3c6f6985bfb84513dbf0f42fe61632c81391`, dernière baseline antérieure à la
migration. Un push contenant plusieurs commits ne peut donc pas soustraire ses
premiers commits au contrôle différentiel.

Quand la dette historique sera résorbée, remplacer ces deux contrôles
différentiels par `vendor/bin/pint --test` et
`vendor/bin/phpstan analyse --no-progress`.

## Activation dans Bitbucket

Après le premier push contenant `bitbucket-pipelines.yml` :

1. ouvrir **Repository settings > Pipelines > Settings** et vérifier que
   Pipelines est activé ;
2. vérifier que le pipeline `default` apparaît pour la branche poussée ;
3. dans les restrictions de `master`, interdire les pushes directs et exiger
   un build réussi avant merge ;
4. ne créer aucune variable UAT ou production pour ce pipeline.

Le YAML lance le gate sur chaque push. L'obligation d'un build vert avant merge
est un réglage du dépôt Bitbucket et ne peut pas être imposée par le fichier
versionné seul.

## Résultats et diagnostic

En cas d'échec, Bitbucket conserve :

- `test-results/phpunit.xml` ;
- `test-results/vitest.xml` ;
- `test-results/playwright.xml` ;
- les captures, traces et pièces jointes Playwright sous
  `test-results/playwright/` ;
- `storage/logs/ci-server.log`.

Les trois caches sont indexés par `composer.lock` ou `package-lock.json`. Ils
accélèrent les téléchargements sans réutiliser `vendor`, `node_modules`, la
base ou les assets construits d'un ancien job.

Pour reproduire localement un échec, utiliser les commandes du
`kView INVESTOR UI Verification Contract`. Ne jamais lancer `migrate:fresh` contre la
base de développement : créer une base PostgreSQL dédiée finissant par
`_testing` et lui passer explicitement les variables `DB_*`.

## Références officielles

- [Configuration de Bitbucket Pipelines](https://support.atlassian.com/bitbucket-cloud/docs/bitbucket-pipelines-configuration-reference/)
- [Caches et services](https://support.atlassian.com/bitbucket-cloud/docs/cache-and-service-container-definitions/)
- [Images de build Docker](https://support.atlassian.com/bitbucket-cloud/docs/use-docker-images-as-build-environments/)