Fichiers
jobrunner-html/DOCUMENTATION.md

190 lignes
13 KiB
Markdown

# 📚 DOCUMENTATION TECHNIQUE & GUIDE PROJET - JOBRUNNER
> **Plateforme de mise en relation de services et prestations avec séquestre bancaire sécurisé.**
> **Dépôt privé :** `https://github.com/gastinelt/jobrunner.html`
> **Nom de domaine de production :** `https://jobrunner.fr`
---
## 📑 Sommaire
1. [Vue d'ensemble du Projet](#1-vue-densemble-du-projet)
2. [Architecture et Organisation des Fichiers](#2-architecture-et-organisation-des-fichiers)
3. [Règles de Travail sur le Dépôt Git Privé](#3-règles-de-travail-sur-le-dépôt-git-privé)
4. [Fonctionnalités Actuelles du Site (Frontend)](#4-fonctionnalités-actuelles-du-site-frontend)
5. [Spécifications Techniques des APIs à Intégrer](#5-spécifications-techniques-des-apis-à-intégrer)
- [Paiements & Séquestre (Stripe)](#51-paiements--séquestre-stripe)
- [Vérification d'Identité 100% Légale & Gratuite](#52-vérification-didentité-100-légale--gratuite)
6. [Mise en Ligne & Configuration du Domaine `Jobrunner.fr`](#6-mise-en-ligne--configuration-du-domaine-jobrunnerfr)
7. [Stratégie Marketing & Acquisition Réseaux Sociaux](#7-stratégie-marketing--acquisition-réseaux-sociaux)
---
## 1. Vue d'ensemble du Projet
**Jobrunner** met en relation des clients ayant un besoin de service du quotidien (bricolage, déménagement, ménage, urgences, livraisons, etc.) avec des prestataires indépendants et fiables appelés les **"Runners"**.
### Le modèle économique :
* **Garantie Séquestre (Escrow) :** Les fonds du client sont débités et mis en sécurité lors de la réservation. Le runner n'est payé qu'une fois la prestation réalisée et validée par le client.
* **Modèle 0 € de frais fixes :** Aucun abonnement récurrent pour le gérant. Les frais Stripe (~1,5% + 0,25 €) sont directement couverts par la commission de la plateforme (10% à 15%).
* **Confiance & Conformité :** Respect strict des lois françaises (RGPD, CNIL, DSP2) et vérifications des profils (numéro de téléphone certifié, SIRET officiel État français, et pièce d'identité sécurisée).
---
## 2. Architecture et Organisation des Fichiers
```
jobrunner web/
├── .gitignore # Protection des clés privées, logs et dépendances
├── README.md # Présentation du dépôt
├── DOCUMENTATION.md # Présente documentation technique complète
├── index.html # Espace projet : tableau de bord & générateur de codes bêta (admin.jobrunner.fr)
├── app.html # Application Web frontend complète (HTML, CSS inline, JS vanilla)
├── charte.html # Charte graphique v1.1 (couleurs, typo, logo, icônes, animations)
├── legal.html # Documents légaux (CGU, CGV, confidentialité, cookies, mentions) — brouillon
├── package.json # Outil de build CSS (devDependency : Tailwind 3.4.19)
├── tailwind.config.js # Palette et ombres du site (source du CSS généré, lit app.html)
├── beta/ # Couche autonome de la bêta testeurs (Python 3 standard)
│ ├── server.py # Serveur HTTP (porte d'entrée, sessions, API admin, injection CSS/JS)
│ ├── codes.py # CLI d'administration des codes d'accès (génération, révocation, liste)
│ ├── db.py # Couche SQLite (codes, sessions, tentatives, audit, démo)
│ ├── bots.py # Simulation d'activité lente et profils fictifs
│ ├── static/ # Pages HTML autonomes (formulaire.html, gate.html)
│ ├── pdf/ # Générateur du formulaire d'engagement testeur PDF (AcroForm)
│ ├── deploiement/ # Architecture et plan de déploiement en production (PLAN.md)
│ └── tests/ # Suite de 25 tests unitaires automatisés
└── assets/
├── css/
│ ├── app.css # CSS Tailwind compilé (généré, à versionner)
│ ├── espace.css # Styles de l'espace projet (index.html) dont zone gestion bêta
│ ├── legal.css # Styles de legal.html
│ ├── tailwind.src.css # Entrée du build Tailwind + règle reduced-motion
│ └── fonts.css # @font-face Plus Jakarta Sans et Outfit (auto-hébergées)
├── js/
│ └── legal.js # Navigation de legal.html
├── icones-jobrunner/ # 15 icônes de la charte (SVG, currentColor, sans cadre)
├── img/logo-j.svg # Logo J de la charte v1.1
├── fonts/ # Fichiers .woff2 Plus Jakarta Sans et Outfit (latin + latin-ext)
└── icons/
├── phosphor.css # Icônes Phosphor (sous-ensemble utilisé)
└── Phosphor-*.woff2 # Polices d'icônes (Regular, Bold, Fill)
```
### Technologies du Frontend :
* **HTML5 / JavaScript Vanilla :** Application Single Page dynamique sans framework, sans bibliothèque JS externe.
* **Tailwind CSS 3.4.19 (build statique) :** le CSS est compilé dans `assets/css/app.css` ; aucun script Tailwind n'est chargé dans le navigateur. Palette sur-mesure (`#F4F2EC` écru/beige, `#7A8E76` sauge, `#1F221E` sombre).
* **Phosphor Icons 2.1.2 (MIT) :** sous-ensemble de la police d'icônes, auto-hébergé dans `assets/icons/`.
* **Typographies :** *Plus Jakarta Sans* (corps de texte) et *Outfit* (titres, classe `font-titre`), toutes deux auto-hébergées sous licence OFL.
* **Note :** la marque utilisait *Chillax* (Fontshare) pour les titres. Elle est remplacée par *Outfit*, faute d'accès au téléchargement de Chillax depuis l'environnement de build. Pour revenir à Chillax, déposer les `.woff2` dans `assets/fonts/`, ajouter les `@font-face` dans `assets/css/fonts.css` et adapter `tailwind.config.js`.
* **Aucun appel externe pour le code ou les polices :** plus de CDN Tailwind, unpkg, Google Fonts ni Fontshare. Seules les images et vidéos de démonstration restent hébergées ailleurs (Unsplash, Mixkit, placehold.co).
* **Responsive Hybride :** Conçu en priorité pour mobile (format app native avec dock de navigation bas) et adapté pour grand écran desktop.
### Régénérer le CSS (uniquement après ajout de classes Tailwind) :
```bash
npm install
npm run build:css
```
Le CSS est versionné : il n'est pas nécessaire d'installer Node pour déployer le site.
---
## 3. Règles de Travail sur le Dépôt Git Privé
Pour garantir la sécurité et la propreté du travail d'équipe avec vos collaborateurs (`gastinelt` & `ronnetnils-cyber`) :
1. **Dépôt Privé Obligatoire :** Tout le code source, la documentation et les développements sont stockés sur le dépôt privé `gastinelt/jobrunner.html`.
2. **Gestion des Secrets & Clés API :**
* **JAMAIS** de clé secrète Stripe (`sk_live_...` ou `sk_test_...`) dans le code HTML/JS côté client.
* Toutes les clés sensibles doivent résider dans un fichier `.env` ou sur le serveur backend uniquement.
* Le fichier `.gitignore` bloque l'envoi de ces fichiers sensibles sur Git.
3. **Commandes usuelles de synchronisation :**
```bash
# Récupérer les dernières modifications de vos collaborateurs
git pull origin main
# Enregistrer vos modifications locales
git add .
git commit -m "description claire de vos modifications"
# Envoyer sur le dépôt privé GitHub
git push origin main
```
---
## 4. Fonctionnalités Actuelles du Site (Frontend)
Le fichier `index.html` intègre déjà les modules complets suivants :
| Module | Description |
| :--- | :--- |
| **Accueil & Recommandations** | Bannière, recherche rapide, catégories de services, sélection de runners recommandés. |
| **Moteur de Recherche & Filtres** | Filtres par catégorie, tarif horaire, localisation, badge vérifié, tri par avis. |
| **Shorts / Vidéos UGC** | Lecteur vidéo vertical style TikTok/Reels intégré, présentant les prestations des runners. |
| **Fiche Runner / Annonce** | Détails du profil, photos, tarifs, avis clients, garanties et bouton de réservation. |
| **Messagerie Instantanée** | Système de messagerie interactif complet (vue liste + fenêtre de conversation dédiée). |
| **Processus de Séquestre Mock** | Modale de paiement avec explication des fonds protégés et validation de fin de mission. |
| **Espace Profil & Annonces** | Gestion des annonces personnelles, favoris, historique et statut de certification. |
| **Footer & Mentions Légales** | Modales légales (Mentions légales, CGU, Politique de confidentialité RGPD, Cookies). |
| **Inscription Libre & Bêta (`jobrunner.fr`)** | Inscription directe via formulaire autonome (`/__beta/formulaire`), accès immédiat sans code requis, conservation des adresses IP pendant 13 mois (décret n° 2021-1362 / LCEN), bandeau testeur et retours d'expérience. |
| **Gestionnaire Bêta (`admin.jobrunner.fr`)** | Suivi en temps réel des testeurs inscrits, affichage des adresses IP et dates de purge légale 13 mois, suspension/réactivation des accès, et outil d'émission de codes d'exception. |
---
## 5. Spécifications Techniques des APIs à Intégrer
### 5.1 Paiements & Séquestre (Stripe)
* **Objectif :** Bloquer les fonds du client jusqu'à validation du service.
* **Fonctionnement :**
1. Le client clique sur *"Réserver avec Séquestre"*.
2. Le serveur appelle `stripe.paymentIntents.create` avec l'option `capture_method: 'manual'` (autorisation préalable).
3. L'argent est bloqué sans être transféré au runner immédiatement.
4. Fin de mission : le client valide $\rightarrow$ le serveur exécute `stripe.paymentIntents.capture` $\rightarrow$ les fonds sont libérés.
* **Frais :** ~1,5% + 0,25 € par transaction par carte bancaire (couverts par les frais de service de la plateforme).
### 5.2 Vérification d'Identité 100% Légale & Gratuite
1. **Vérification SIRET Auto-entrepreneurs / Artisans (0 €) :**
* **API Officielle :** `api.gouv.fr` (Base SIRENE État français).
* **Vérification instantanée :** Le runner renseigne son SIRET $\rightarrow$ l'API confirme l'existence de l'entreprise, son immatriculation et son gérant légal $\rightarrow$ Attribution automatique du badge *"Pro Vérifié SIRET"*.
2. **Vérification Numéro de Téléphone (0 €) :**
* **API :** Google Firebase Phone Auth.
* **Vérification :** Envoi d'un code SMS à 6 chiffres. En France, toute ligne mobile 06/07 est obligatoirement liée à une identité chez un opérateur téléphonique.
3. **Vérification Pièce d'Identité CNI (Optionnelle via Stripe Identity) :**
* Facturée ~1,50 € par vérification $\rightarrow$ Frais répercutés au runner qui choisit de débloquer le badge *"Identité Certifiée CNI"*.
---
## 6. Mise en Ligne & Architecture de Production (Déployé le 29/10/2026)
L'infrastructure sépare le site public de test et l'espace projet / administration :
### 6.1 Domaines & DNS (Infomaniak)
* `jobrunner.fr`, `www.jobrunner.fr`, `beta.jobrunner.fr` : Enregistrements `A` vers `179.237.102.233` (VPS Suisse).
* `admin.jobrunner.fr` : Enregistrement `A` vers `179.237.102.233` (Espace projet sous authentification HTTP Basic Auth).
### 6.2 Architecture Caddy (VPS `cornafsuisse`)
* **`admin.jobrunner.fr`** : Protégé par HTTP Basic Auth (`/etc/caddy/jobrunner-auth.caddy`). Sert les fichiers statiques de `/srv/jobrunner.fr`. La route `/_admin/api/*` est proxifiée vers `10.88.88.2:8830` via WireGuard (`wg2`) avec l'en-tête interne `X-Admin: 1`.
* **`jobrunner.fr` (et alias `www`, `beta`)** : Proxifié vers `10.88.88.2:8830` via WireGuard (`wg2`).
### 6.3 Serveur Backend (`cornafserver`)
* **Service** : `jobrunner-beta.service` (systemd utilisateur).
* **Port** : `8830`, sécurisé par `nftables` (accessible uniquement depuis le VPS via WireGuard `wg2`).
* **Données** : `/home/cornaf2049/jobrunner-beta-data/beta.sqlite` avec permissions restreintes (`0600`).
* **Sécurité applicative** : HMAC-SHA256 pour les codes d'accès, anti-bruteforce (6 essais / 15 min), plafonds de requêtes concurrentes, timeouts stricts de 20 s.
---
## 7. Stratégie Marketing & Acquisition Réseaux Sociaux
### Deux cibles distinctes :
1. **Les Clients (Demandeurs de services) :**
* *Accroche :* "Besoin d'un coup de main en urgence ? Ne prenez aucun risque : vos fonds sont protégés par séquestre et le runner n'est payé que si vous êtes 100% satisfait."
2. **Les Runners (Prestataires / Indépendants) :**
* *Accroche :* "Comment gagner de 100 € à 300 € par semaine à côté de vos études ou de votre travail, avec la certitude d'être payé sans impayé."
### Formats Vidéos Recommandés :
* **Shorts / TikTok / Reels (Format 9:16) :**
* Utiliser le style UGC (face caméra, smartphone en main, authentique, sous-titres dynamiques).
* Montrer la plateforme en action directement à l'écran grâce à l'interface mobile de Jobrunner.