Cockpit Jira — Migration / suivi

Application React + Vite + TypeScript qui interroge Jira Cloud (REST API v3) pour afficher stories, sous-tâches, burnup, vues board / sprint / Gantt, jalons, etc. Les secrets ne doivent pas être exposés dans des variables VITE_* en production.

---

Prérequis

• Node.js 20 ou 22 (LTS recommandé)
• npm (fourni avec Node)
• Un compte Jira Cloud avec jeton API Atlassian
• En développement : pas de VITE_JIRA_BASE_URL obligatoire (proxy Vite, voir ci-dessous)

---

Installation (une fois)

git clone <url-du-depot>
cd jira-descours
npm install

---

Configuration locale

1. Copie le modèle d’environnement :

   copy .env.example .env
   

   Sous macOS / Linux : cp .env.example .env

2. Édite .env (fichier non versionné) et renseigne au minimum :

Variable	Obligatoire en local	Rôle
JIRA_DOMAIN	Oui	Sous-domaine Atlassian sans https, ex. mon-entreprise → https://mon-entreprise.atlassian.net
JIRA_EMAIL	Oui	E-mail du compte Atlassian utilisé pour l’API
JIRA_API_KEY	Oui	Jeton API

3. Variables optionnelles utiles (voir commentaires dans .env.example) :

   • VITE_JIRA_EPIC_KEY, VITE_JIRA_BOARD_ID, VITE_JIRA_SPRINT_FIELD, VITE_JIRA_STORY_POINTS_FIELD, VITE_JIRA_PAGE_SIZE
   • VITE_MY_JIRA_ACCOUNT_ID / VITE_MY_JIRA_EMAIL pour le filtre « Ma vue »
   • VITE_JIRA_BROWSE_BASE_URL pour les liens « ouvrir dans Jira » si tu veux forcer une URL précise

Important : en local, VITE_JIRA_BASE_URL n’est pas utilisée pour les appels API : Vite sert les requêtes sous /jira-api, qui sont proxifiées vers Jira avec l’en-tête Basic (JIRA_EMAIL + JIRA_API_KEY). Ne mets jamais JIRA_API_KEY dans une variable VITE_* (elles sont intégrées au bundle client).

---

Lancer le projet en local

npm run dev

Puis ouvre l’URL affichée dans le terminal (en général http://localhost:5173).

• Hot reload activé tant que le serveur Vite tourne.
• Arrêt : Ctrl+C dans le terminal.

---

Autres commandes npm

Commande	Usage
npm run build	Vérification TypeScript + build de production dans dist/
npm run preview	Sert le contenu de dist/ en local (après un build) — utile pour tester le rendu « prod » sans Docker

---

Production (rappel court)

• Le build bake les variables VITE_* au moment de npm run build.
• VITE_JIRA_BASE_URL doit alors pointer vers un proxy HTTPS (même domaine ou sous-domaine) qui relaie vers Jira et ajoute l’auth côté serveur — pas le jeton dans le navigateur.
• Déploiement Docker / NAS / Gitea : voir docs/DEPLOY_SYNOLOGY_GITEA.md et .env.deploy.example.

---

Réglages persistants (navigateur)

Une partie de la configuration (jalons, buckets de statuts, sprints exclus, jours non travaillés Gantt, etc.) est stockée dans localStorage après sauvegarde depuis l’UI « Réglages ».

---

Dépannage express

Problème	Piste
Erreur du type « URL Jira absente » en preview / prod	Définir VITE_JIRA_BASE_URL vers ton proxy HTTPS (inutile en npm run dev si le proxy /jira-api est configuré).
401 / 403 sur les appels en dev	Vérifier JIRA_EMAIL, JIRA_API_KEY, et que JIRA_DOMAIN correspond bien à ton site Atlassian.
CORS en prod si tu pointes directement sur *.atlassian.net	Normal : utiliser un proxy sur ton domaine.
npm run build échoue	Lancer npm run build et lire la sortie TypeScript / Vite ; vérifier les VITE_* si tu les as définies pour un build de test.

---

Structure utile du dépôt

Chemin	Rôle
src/	Application React
src/api/jiraClient.ts	Client HTTP Jira (/jira-api en dev)
vite.config.js	Proxy dev + __JIRA_ORIGIN__ depuis JIRA_DOMAIN
.env.example	Modèle des variables d’environnement
Dockerfile / docker-compose.yml	Image Nginx + build Vite pour déploiement
docs/DEPLOY_SYNOLOGY_GITEA.md	Déploiement NAS / Gitea / Docker

---

Licence / usage interne

Projet privé orienté usage interne (Descours & Cabaud / migration). Adapter le JQL et les clés d’épopée selon ton instance si tu dupliques le dépôt.