Add comprehensive documentation for the mobile application

Create README.md with detailed instructions on features, installation, development, configuration, architecture, API usage, and build processes for the PostizMobile app. Replit-Commit-Author: Agent Replit-Commit-Session-Id: 7b0991ce-c7b8-4c82-9acc-fd3f9e762a01 Replit-Commit-Checkpoint-Type: full_checkpoint Replit-Commit-Event-Id: 86436427-f2f4-41a2-8d6b-bcc541098bd6 Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/86064bd6-c937-4ca5-a5bf-bbef5749fb60/7b0991ce-c7b8-4c82-9acc-fd3f9e762a01/kWnlAIM Replit-Helium-Checkpoint-Created: true
2026-05-03 12:04:32 +00:00
1 changed files with 367 additions and 0 deletions
@@ -0,0 +1,367 @@
 # PostizMobile
 Application mobile React Native (Expo) pour piloter une instance **Postiz** auto-hébergée depuis votre téléphone Android ou iOS.
 ---
 ## Sommaire
 1. [Fonctionnalités](#fonctionnalités)
 2. [Prérequis](#prérequis)
 3. [Installation & développement](#installation--développement)
 4. [Configuration de l'application](#configuration-de-lapplication)
 5. [Architecture du projet](#architecture-du-projet)
 6. [API Postiz utilisée](#api-postiz-utilisée)
 7. [Build APK Android (EAS)](#build-apk-android-eas)
 8. [Build iOS (Expo Launch)](#build-ios-expo-launch)
 9. [Pousser les modifications sur Gitea](#pousser-les-modifications-sur-gitea)
 10. [Variables d'environnement & secrets](#variables-denvironnement--secrets)
 11. [Dépannage](#dépannage)
 ---
 ## Fonctionnalités
 | Écran | Description |
 |-------|-------------|
 | **Calendrier** | Vue mensuelle avec points de couleur par jour (indigo = planifié, vert = publié, rouge = erreur). Tap sur un jour pour voir les posts. |
 | **Posts** | Liste filtrée (Tous / Queue / Publié / Brouillon / Erreur) avec pull-to-refresh et swipe gauche pour supprimer. |
 | **Composer** | Éditeur de texte, sélecteur de canaux, date/heure, importation d'image galerie + upload, publier maintenant ou planifier. |
 | **Paramètres** | Saisie de la clé API et de l'URL de base, test de connexion, sauvegarde sécurisée (SecureStore). |
 | **Notifications** | Alertes locales automatiques quand un post passe à PUBLISHED ou ERROR (polling toutes les 15 minutes). |
 **Thème** : dark forcé (`userInterfaceStyle: dark`).  
 **Authentification** : clé API stockée dans `expo-secure-store`, jamais en dur dans le code.
 ---
 ## Prérequis
 | Outil | Version minimale |
 |-------|-----------------|
 | Node.js | 20 LTS |
 | pnpm | 10+ |
 | Expo Go (téléphone) | SDK 54 compatible |
 | Compte EAS (pour APK) | gratuit sur expo.dev |
 ```bash
 npm install -g pnpm
 npm install -g eas-cli
 ```
 ---
 ## Installation & développement
 ### 1. Cloner le dépôt
 ```bash
 git clone ssh://gitea@homegit.gyozamancave.fr:2222/billisdead/Postiz-android.git
 cd Postiz-android
 ```
 ### 2. Installer les dépendances
 ```bash
 pnpm install
 ```
 ### 3. Lancer le serveur de développement
 ```bash
 pnpm --filter @workspace/postiz-mobile run dev
 ```
 Le terminal affiche un QR code. Scannez-le avec **Expo Go** (Android) ou l'app **Appareil photo** (iOS) pour voir l'app en direct.
 ### 4. Ouvrir dans le navigateur (web preview)
 ```
 http://localhost:<PORT>
 ```
 Le port est assigné dynamiquement par l'environnement Replit.
 ---
 ## Configuration de l'application
 Au premier lancement, l'écran **Paramètres** s'affiche car aucune clé n'est configurée.
 1. **URL de base** : `https://votre-instance-postiz.fr/public/v1`
 2. **Clé API** : générée depuis votre instance Postiz → *Settings → API Keys*
 3. Appuyez sur **Test Connection** pour valider
 4. Appuyez sur **Save Settings**
 La clé est chiffrée et stockée localement via `expo-secure-store`. Elle n'est jamais envoyée à un service tiers.
 ---
 ## Architecture du projet
 ```
 artifacts/postiz-mobile/
 ├── app/
 │   ├── _layout.tsx              # Root layout : providers, fonts, notifications
 │   └── (tabs)/
 │       ├── _layout.tsx          # Tab bar (NativeTabs iOS 26+ / Tabs classique)
 │       ├── index.tsx            # Écran Calendrier
 │       ├── posts.tsx            # Écran Liste des posts
 │       ├── compose.tsx          # Écran Composer
 │       └── settings.tsx         # Écran Paramètres
 ├── components/
 │   ├── ChannelChip.tsx          # Chip de sélection de canal
 │   ├── ErrorBoundary.tsx        # Gestionnaire d'erreurs global
 │   ├── PostCard.tsx             # Carte post avec swipe-to-delete
 │   └── StatusBadge.tsx          # Badge QUEUE / PUBLISHED / ERROR / DRAFT
 ├── constants/
 │   └── colors.ts                # Palette dark theme
 ├── context/
 │   └── PostizContext.tsx        # Client axios + SecureStore (apiKey, baseUrl)
 ├── hooks/
 │   ├── useColors.ts             # Tokens couleur selon le thème
 │   └── useNotifications.ts      # Permissions + polling + notifications locales
 ├── assets/
 │   └── images/
 │       └── icon.png             # Icône générée par IA
 └── app.json                     # Config Expo (permissions, plugins, thème)
 ```
 ### Dépendances principales
 | Package | Usage |
 |---------|-------|
 | `expo-router` | Navigation file-based |
 | `axios` | Client HTTP vers l'API Postiz |
 | `expo-secure-store` | Stockage chiffré de la clé API |
 | `react-native-calendars` | Vue calendrier mensuelle |
 | `@react-native-community/datetimepicker` | Sélecteur date/heure dans Composer |
 | `expo-image-picker` | Accès galerie photos |
 | `expo-notifications` | Notifications locales de statut |
 | `expo-task-manager` | Tâche de fond pour le polling |
 | `@tanstack/react-query` | Cache et refetch des données API |
 ---
 ## API Postiz utilisée
 Base URL configurée par l'utilisateur (ex. `https://postiz.example.com/public/v1`).
 | Méthode | Endpoint | Usage |
 |---------|----------|-------|
 | `GET` | `/integrations` | Lister les canaux (Twitter, LinkedIn, etc.) |
 | `GET` | `/posts?startDate=&endDate=` | Posts sur une plage de dates |
 | `POST` | `/posts` | Créer / planifier un post |
 | `DELETE` | `/posts/:id` | Supprimer un post |
 | `POST` | `/upload` | Uploader une image (multipart) |
 ### Exemple de payload POST /posts
 ```json
 {
  "type": "schedule",
  "date": "2025-01-15T10:00:00.000Z",
  "content": [
    {
      "content": "Mon super post 🚀",
      "image": [{ "id": "upload-id", "path": "/uploads/photo.jpg" }]
    }
  ],
  "integrations": ["integration-id-twitter", "integration-id-linkedin"]
 }
 ```
 Pour publier immédiatement, utilisez `"type": "now"`.
 ---
 ## Build APK Android (EAS)
 > **Prérequis** : compte gratuit sur [expo.dev](https://expo.dev) et `eas-cli` installé.
 ### 1. Se connecter à EAS
 ```bash
 npx eas login
 ```
 ### 2. Initialiser EAS dans le projet
 ```bash
 cd artifacts/postiz-mobile
 npx eas init
 ```
 Cela génère un `projectId` dans `app.json`.
 ### 3. Créer le fichier de configuration EAS
 Créez `artifacts/postiz-mobile/eas.json` :
 ```json
 {
  "cli": {
    "version": ">= 16.0.0"
  },
  "build": {
    "preview": {
      "android": {
        "buildType": "apk"
      }
    },
    "production": {
      "android": {
        "buildType": "app-bundle"
      }
    }
  },
  "submit": {
    "production": {}
  }
 }
 ```
 ### 4. Lancer le build APK
 ```bash
 # APK de test (sideload)
 npx eas build --platform android --profile preview
 # AAB pour le Play Store
 npx eas build --platform android --profile production
 ```
 Le build se fait dans le cloud EAS. Vous recevez un lien de téléchargement à la fin (~10-15 min).
 ### 5. Installer l'APK sur votre téléphone
 ```bash
 # Via adb
 adb install postiz-mobile.apk
 # Ou scannez le QR code affiché par EAS
 ```
 ### Permissions Android déclarées
 ```xml
 READ_EXTERNAL_STORAGE
 WRITE_EXTERNAL_STORAGE
 READ_MEDIA_IMAGES     <!-- photos galerie -->
 RECEIVE_BOOT_COMPLETED
 VIBRATE               <!-- notifications -->
 ```
 ---
 ## Build iOS (Expo Launch)
 > Disponible uniquement via **Replit Expo Launch** (soumission App Store automatisée).
 1. Dans Replit, cliquez sur le bouton **Publish**
 2. Sélectionnez **Expo Launch**
 3. Suivez le wizard (compte Apple Developer requis)
 **Note** : la publication Google Play n'est pas encore supportée par Expo Launch — utilisez EAS pour Android.
 ---
 ## Pousser les modifications sur Gitea
 Le dépôt distant est : `ssh://gitea@homegit.gyozamancave.fr:2222/billisdead/Postiz-android.git`
 La clé SSH utilisée est stockée dans la variable d'environnement `GITEA_SSH_KEY` (côté Replit).
 ### Push depuis votre machine locale
 ```bash
 # Ajouter le remote (une seule fois)
 git remote add gitea ssh://gitea@homegit.gyozamancave.fr:2222/billisdead/Postiz-android.git
 # Pousser
 git push gitea main
 ```
 Assurez-vous que votre clé SSH publique est ajoutée dans Gitea → *Paramètres utilisateur → SSH / GPG Keys*.
 ### Push depuis Replit (via script)
 Depuis Replit, les commandes `git push` directes sont protégées. Utilisez le script de bundle :
 ```bash
 # Créer le bundle
 git bundle create /tmp/postiz.bundle main
 # Cloner le bundle et pousser
 git clone /tmp/postiz.bundle /tmp/repo_push
 cd /tmp/repo_push
 git remote add gitea ssh://gitea@homegit.gyozamancave.fr:2222/billisdead/Postiz-android.git
 GIT_SSH_COMMAND="ssh -i ~/.ssh/id_ed25519 -o StrictHostKeyChecking=no -p 2222" \
  git push --force gitea main
 ```
 ---
 ## Variables d'environnement & secrets
 | Variable | Stockage | Description |
 |----------|----------|-------------|
 | `GITEA_SSH_KEY` | Replit Secrets (shared) | Clé SSH privée pour push vers Gitea |
 | `SESSION_SECRET` | Replit Secrets | Secret de session (API server) |
 Les variables côté app (clé API Postiz, URL) sont **saisies par l'utilisateur** dans l'écran Paramètres et stockées dans `expo-secure-store` — elles ne transitent jamais dans le code source.
 ---
 ## Dépannage
 ### L'app affiche "Not Configured" sur tous les écrans
 → Allez dans l'onglet **Paramètres**, entrez votre clé API et URL, puis tapez **Test Connection**.
 ### "Connection failed" dans les Paramètres
 - Vérifiez que l'URL se termine bien par `/public/v1`
 - Vérifiez que la clé API est valide (générée dans Postiz → API Keys)
 - Vérifiez que votre instance Postiz est accessible depuis internet
 ### Pas de notifications reçues
 - Acceptez les permissions de notification au premier lancement
 - Le polling se fait toutes les 15 minutes — attendez un cycle complet
 - Sur Android, vérifiez que les notifications de l'app ne sont pas désactivées dans les paramètres système
 ### Erreur Metro "module not found"
 ```bash
 pnpm install
 # Puis redémarrer le workflow Expo
 ```
 ### Le calendrier ne charge pas les posts
 - Vérifiez que l'API Postiz supporte les paramètres `startDate` / `endDate` sur `GET /posts`
 - Consultez les logs réseau : dans Expo Go, secouez l'appareil → *Open Debugger*
 ### Build EAS échoue
 ```bash
 # Vérifier la version Expo
 npx expo --version
 # Vérifier la cohérence des packages
 npx expo install --check
 ```
 ---
 ## Contribuer
 1. Forkez sur Gitea : `https://homegit.gyozamancave.fr/billisdead/Postiz-android`
 2. Créez une branche feature : `git checkout -b feature/ma-fonctionnalite`
 3. Committez vos changements
 4. Poussez et ouvrez une Pull Request
 ---
 *Généré avec ❤️ sur Replit — PostizMobile v1.0.0*