117 lines
4.4 KiB
Markdown
117 lines
4.4 KiB
Markdown
# 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)
|
||
|
||
```bash
|
||
git clone <url-du-depot>
|
||
cd jira-descours
|
||
npm install
|
||
```
|
||
|
||
---
|
||
|
||
## Configuration locale
|
||
|
||
1. Copie le modèle d’environnement :
|
||
|
||
```bash
|
||
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](https://id.atlassian.com/manage-profile/security/api-tokens) |
|
||
|
||
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
|
||
|
||
```bash
|
||
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.
|