sogoms/TODO.md

TODO - SOGOMS V1 Minimale

Objectif : valider l'architecture avec 2-3 microservices basiques.

Phase 0 : Infrastructure

• Container gw3 : Alpine sur IN3 (13.23.33.5)
• Config Prokov : routes + scénarios YAML (auth, projects, tasks, tags, statuses)
• Nginx host IN3 : routing /api/ → gw3:8080, / → dva-front

Phase 1 : Protocole IPC

• internal/protocol/message.go : structs Request/Response JSON
• internal/protocol/server.go : listener Unix socket
• internal/protocol/client.go : client pour appeler les services

Phase 2 : Microservice DB

• cmd/sogoms/db/main.go : point d'entrée
• Connexion MariaDB (pool par application)
• Action query : SELECT multi-résultats
• Action query_one : SELECT un résultat
• Action insert : INSERT retourne insert_id
• Action update : UPDATE retourne affected_rows
• Action delete : DELETE retourne affected_rows
• Écoute sur /run/sogoms-db.1.sock
• Test standalone sogoms-db

Phase 3 : Config

• internal/config/config.go : lecture YAML + registry par host
• internal/config/routes.go : parser routes (intégré dans config.go)

Phase 4 : Gateway HTTP

• cmd/sogoway/main.go : serveur HTTP :8080
• Routing par host → charge le bon fichier routes (prokov.yaml)
• internal/auth/jwt.go : génération + validation JWT (HS256)
• internal/auth/password.go : hash + verify password (bcrypt)
• Endpoint POST /api/auth/login : vérifie credentials, retourne JWT
• Endpoint GET /api/auth/me : valide JWT, retourne user
• Endpoint POST /api/auth/register : crée user, retourne JWT
• Communication avec sogoms-db via Unix socket
• Test standalone sogoway

Phase 5 : Superviseur

• cmd/sogoctl/main.go : point d'entrée
• Config config/sogoctl.yaml : services à lancer
• Lancement sogoms-db + sogoway (avec dépendances)
• Health check (socket + HTTP)
• Redémarrage automatique si crash

Phase 6 : Test de validation

# 1. Lancer sogoctl (démarre les services)
./sogoctl

# 2. Login
curl -X POST https://prokov.unikoffice.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"secret"}'
# → {"success":true,"data":{"token":"eyJ...","user":{...}}}

# 3. Vérifier le token
curl https://prokov.unikoffice.com/api/auth/me \
  -H "Authorization: Bearer eyJ..."
# → {"success":true,"data":{"user":{...}}}

• Test login OK
• Test /me avec token valide OK
• Test /me sans token → 401

Phase 7 : Microservice Logs

• cmd/sogoms/logs/main.go : point d'entrée
• Écoute sur Unix socket /run/sogoms-logs.1.sock
• Actions log_error, log_event : écriture dans fichiers
• Format fichiers : /var/log/sogoms/{app}-{YYYYMMDD}-{type}.log
• Rotation automatique : suppression des fichiers > 30 jours
• Paramètre retention_days dans config (config/routes/prokov.yaml)
• Intégration avec sogoway et sogoms-db

Phase 8 : Système de Queries YAML

• Structure config/queries/{app}/*.yaml
• Requêtes SQL externalisées (pas de recompilation)
• internal/config/config.go : QueryConfig, GetQuery(), Build()
• Placeholders :user_id, :id, etc.
• Filtres par rôle (default, admin)
• Login enrichi : charge projects, tasks, tags, statuses

Phase 9 : CRUD Générique

• Routing /api/{resource} dans sogoway
• GET list/show avec filtres YAML
• POST create avec fields YAML
• PUT update avec fields + filtres YAML
• DELETE avec filtres YAML
• Config YAML pour projects, tasks, tags, statuses
• Sécurité : filtre user_id automatique

Phase 10 : Améliorations Deploy

• deploy.sh : build sogoms-logs
• deploy.sh : backup archives dans /home/pierre/samba/back/sogoms/
• deploy.sh : redémarrage auto sogoctl
• deploy.sh : kill propre des processus zombies
• Documentation DOCTECH.md
• Version 1.0.1

Phase 11 : Microservice Crypt

• cmd/sogoms/crypt/main.go : point d'entrée
• Écoute sur Unix socket /run/sogoms-crypt.1.sock
• Action encrypt : chiffre une donnée (AES-256-GCM)
• Action decrypt : déchiffre une donnée
• Action hash : hash irréversible (SHA-256)
• Clé de chiffrement par application (/secrets/{app}_crypt_key)
• Intégration avec sogoway pour champs sensibles
• Config YAML : liste des champs à chiffrer par table
• Application Prokov : chiffrement users.email

Phase 12 : Microservices Email

12a. sogoms-smtp (Envoi)

• cmd/sogoms/smtp/main.go : point d'entrée
• Écoute sur Unix socket /run/sogoms-smtp.1.sock
• Action send : envoi email simple (to, subject, body, html)
• Action send_template : envoi avec template YAML
• Action send_bulk : envoi en masse (liste de destinataires)
• Config SMTP par application (config/routes/{app}.yaml)
• Support TLS/STARTTLS
• Templates YAML (config/emails/{app}/*.yaml)
• Queue d'envoi avec retry en cas d'échec

12b. sogoms-imap (Lecture)

• cmd/sogoms/imap/main.go : point d'entrée
• Écoute sur Unix socket /run/sogoms-imap.1.sock
• Action list : liste les emails (folder, limit, offset)
• Action fetch : récupère un email complet (uid)
• Action delete : supprime un email
• Action mark_read : marque comme lu
• Action move : déplace vers un autre dossier
• Config IMAP par application (config/routes/{app}.yaml)
• Support IMAP IDLE pour notifications temps réel

12c. sogoms-mailproc (Traitement)

• cmd/sogoms/mailproc/main.go : point d'entrée
• Écoute sur Unix socket /run/sogoms-mailproc.1.sock
• Action parse : parse un email (headers, body, attachments)
• Action apply_rules : applique des règles configurées
• Config YAML : règles par application (config/mailrules/{app}.yaml)
• Webhooks : notification vers URL externe
• Intégration Prokov : email entrant → création de tâche

Phase 13 : Microservice Cron

• cmd/sogoms/cron/main.go : point d'entrée
• internal/cron/scheduler.go : parser cron + calcul next run
• Écoute sur Unix socket /run/sogoms-cron.1.sock
• Config YAML par application (config/apps/{app}/cron.yaml)
• Parser cron schedule (format standard * * * * *)
• Support timezone (Europe/Paris)
• Retry configurable (max_attempts, delay)
• Historique des exécutions (configurable, défaut 7 jours)
• Action list : liste les jobs configurés avec prochain run
• Action trigger : déclenche un job manuellement
• Action status : historique des dernières exécutions
• Type service : appel service interne (sogoms-smtp, sogoms-db, etc.)
• Type http : appel HTTP (GET/POST) vers endpoint interne ou externe
• Type query_email : requête DB + envoi email groupé par user
• Logging des exécutions dans sogoms-logs
• Application Prokov : email quotidien tasks_today (8h00 lun-ven)
• Intégration sogoctl.yaml
• Intégration deploy.sh

Phase 14 : Push Temps Réel (MQTT)

14a. Infrastructure Mosquitto

• Installation Mosquitto sur gw3 (Alpine: apk add mosquitto)
• Config /etc/mosquitto/mosquitto.conf
• Auth par user/password ou plugin JWT
• Port 1883 (MQTT) + 9001 (WebSocket)
• TLS optionnel pour production

14b. sogoms-push

• cmd/sogoms/push/main.go : point d'entrée
• Écoute sur Unix socket /run/sogoms-push.1.sock
• Connexion au broker MQTT
• Config YAML par application (config/push/{app}.yaml)
• Action publish : publie un message sur un topic
• Action notify_user : publie vers {app}/user/{user_id}/{channel}
• Action broadcast : publie vers tous les users d'une app
• Topics : notifications, tasks, projects, comments
• Intégration sogoway : publish auto sur événements CRUD

14c. Intégration Flutter

• Package mqtt_client dans Prokov Flutter
• Service MqttService : connexion, reconnexion auto
• Subscription aux topics user
• Mise à jour state en temps réel
• Notifications in-app

Phase 15 : Schema-Driven API (Socle SOGOMS)

Cette phase transforme SOGOMS en générateur d'API automatique.

15a. Définition du Schema

• Format config/schemas/{app}.yaml : tables, fields, relations
• Types supportés : int, string, text, float, date, datetime, json
• Contraintes : primary, auto, unique, required, default
• Relations : foreign key avec foreign: table.field
• Sécurité : filter: owner pour filtrage auto par user_id
• Auth : auth: login, auth: password pour détection auto
• CRUD : liste des opérations autorisées par table
• Filtres custom : définition de filtres nommés
• Ordre par défaut : order: "position ASC"

15b. Introspection DB (via API admin)

• Action introspect dans sogoms-db : scan INFORMATION_SCHEMA
• Endpoint GET /api/_admin/schema/introspect : retourne JSON
• Endpoint POST /api/_admin/schema/generate : génère schema.yaml
• Détection auto : types, clés primaires/étrangères, contraintes
• Détection pattern filter: owner sur colonnes user_id
• Commande validate {app} : valide le schema
• Commande diff {app} : compare schema vs DB réelle
• Commande migrate {app} : génère SQL de migration

15c. Runtime Dynamique (sogoway)

• Chargement schema au démarrage
• Routes CRUD auto-générées depuis schema
• Validation des inputs selon types/contraintes
• Filtrage user_id automatique (filter: owner)
• Gestion relations (include, nested)
• Pas de fichiers queries YAML requis (optionnels pour override)

15d. Dictionnaire de Données

• Endpoint /api/_schema : expose le schema (pour admin/debug)
• Endpoint /api/_schema/{table} : détail d'une table
• Documentation auto-générée
• Utilisable par Flutter pour génération de formulaires

Phase 16 : Réorganisation Config par Application

Objectif : regrouper tous les fichiers d'une application dans un seul dossier.

16a. Nouvelle structure

config/
├── apps/
│   └── {app}/
│       ├── app.yaml           ← config principale (ex routes/{app}.yaml)
│       ├── schema.yaml        ← schema DB généré
│       ├── queries/           ← requêtes SQL
│       │   ├── auth.yaml
│       │   ├── projects.yaml
│       │   └── ...
│       ├── scenarios/         ← orchestrations complexes
│       │   └── auth/
│       │       └── login.yaml
│       └── emails/            ← templates email
│           └── welcome.yaml
└── sogoctl.yaml

16b. Migration

• Créer config/apps/prokov/ avec nouvelle structure
• Migrer config/routes/prokov.yaml → config/apps/prokov/app.yaml
• Migrer config/schemas/prokov.yaml → config/apps/prokov/schema.yaml
• Migrer config/queries/prokov/ → config/apps/prokov/queries/
• Migrer config/scenarios/prokov/ → config/apps/prokov/scenarios/
• Migrer config/emails/prokov/ → config/apps/prokov/emails/

16c. Adaptation du code

• internal/config/config.go : nouveau chemin de chargement
• internal/config/config.go : charger schema.yaml (optionnel)
• cmd/sogoway/main.go : adapter handleSchemaGenerate()
• deploy.sh : adapter les chemins de déploiement
• Supprimer anciens dossiers après validation

16d. Avantages

• Clarté : tout ce qui concerne une app dans un seul dossier
• Portabilité : copier/sauvegarder une app = copier un dossier
• Scalabilité : ajouter une app = créer un dossier dans apps/
• Cohérence : plus de répétition du nom d'app partout

Phase 17 : Interface Web Administration (sogoms-admin)

17a. Backend Go

• internal/admin/config.go : chargement admin_users.yaml
• internal/admin/permissions.go : vérification des droits
• internal/admin/audit.go : logging des actions vers sogoms-logs
• cmd/sogoms/admin/session.go : sessions en mémoire, cookies signés HMAC-SHA256
• cmd/sogoms/admin/middleware.go : auth, CSRF, rate limiting
• cmd/sogoms/admin/services.go : appels vers services (db, logs, cron)
• cmd/sogoms/admin/handlers.go : handlers HTTP (login, dashboard, logout)
• cmd/sogoms/admin/main.go : serveur HTTP :9000

17b. Frontend Templates

• templates/layout.html : layout commun avec htmx + Pico.css
• templates/login.html : page de connexion avec CSRF
• templates/dashboard.html : dashboard principal
• templates/partials/apps_list.html : liste apps (htmx)
• templates/partials/services_status.html : statut services (htmx)

17c. Sécurité

• Passwords : bcrypt cost=12
• Sessions : Cookie HttpOnly + Secure + SameSite=Strict
• CSRF : Token par session, vérifié sur POST
• Rate limiting : 5 tentatives/min par IP sur login
• Audit : Toutes actions loggées vers sogoms-logs

17d. Rôles et Permissions

• Super-admin : accès global à toutes les apps et services
• App-admin : accès limité aux apps assignées avec permissions fines
• Permissions granulaires : schema:, queries:, emails:, cron:, logs:, db:

17e. Intégration

• config/sogoctl.yaml : ajout service sogoms-admin
• deploy.sh : build et déploiement sogoms-admin
• Configuration Nginx : admin.sogoms.com → :9000

17f. Configuration requise

# /secrets/admin_users.yaml
session:
  secret_file: /secrets/admin_session_secret
  max_age: 3600
  cookie_name: sogoms_admin_sid

rate_limit:
  login_max: 5
  login_window: 60

users:
  - username: pierre
    password_hash: "$2a$12$..."
    role: super_admin
    email: pierre@example.com

Hors scope V1

• sogorch (orchestrateur scénarios)
• sogoms-pdf, sogoms-storage
• Multi-tenant avancé (workspaces, partage)
• Rate limiting
• Rôles utilisateurs (admin, manager, user)

Phase 19 : Création d'App via Admin UI

Objectif : permettre la création et configuration d'une app directement depuis l'interface admin.

19a. Formulaire de création

• Page /admin/apps/new : formulaire création app
• Champs : nom app, version, base_path
• Champs hosts : liste des domaines
• Champs database : host, port, user, password, name
• Champs auth : JWT secret (auto-généré ou manuel), expiry
• Validation : test connexion DB avant création
• Création : génère config/apps/{app}/app.yaml

19b. Introspection et génération schema

• Bouton "Scanner la base" : appelle introspection DB
• Génération automatique schema.yaml depuis INFORMATION_SCHEMA
• Détection : types, clés primaires/étrangères, contraintes
• Détection auto filter: owner sur colonnes user_id
• Sauvegarde config/apps/{app}/schema.yaml

19c. Bouton "Update Schema"

• Relecture structure DB (nouvelle introspection)
• Mise à jour schema.yaml (nouvelles tables/colonnes)
• Régénération routes CRUD automatiques
• Rechargement registry après scan
• Rechargement automatique sogoway via SIGHUP (socket sogoctl)

Note : le bouton "Scanner la base" (19b) fait office d'Update Schema.

19d. Affichage dans Admin

• Page détail app : liste tables avec colonnes
• Page détail app : liste routes générées
• Page détail app : dictionnaire des données (types, contraintes)
• Indicateur : schema synchronisé / désynchronisé avec DB

19e. Gestion des secrets

• Génération auto fichiers secrets (/secrets/{app}_*)
• DB password : saisi une fois, stocké dans fichier
• JWT secret : auto-généré (openssl rand -base64 32)
• Permissions fichiers : 600

Phase 18 : Application Geosector (Janvier-Février 2026)

Migration de l'API PHP 8.3 existante vers SOGOMS pour l'application Flutter (Web + mobiles).

18a. Préparation

• Introspection DB MariaDB existante
• Génération schema.yaml depuis introspection
• Création config/apps/geosector/
• Analyse des endpoints PHP existants

18b. Migration

• Configuration app.yaml (DB, auth, hosts)
• Adaptation des queries spécifiques
• Migration des endpoints custom si nécessaire
• Configuration jobs cron (si applicable)
• Configuration emails (si applicable)

18c. Tests et bascule

• Tests avec app Flutter (web)
• Tests avec app Flutter (iOS/Android)
• Configuration Nginx geosector.sogoms.com
• Bascule DNS production
• Monitoring post-migration