NeedFinder - Documentation technique

Dernière MAJ : 24/01/2026

Localisation

Structure base de données

SERVER: supabase-db-prod (prod-portainer)
    │
    └── DATABASE: postgres
            │
            └── SCHEMA: needfinder
                    │
                    ├── sources (2 rows)
                    ├── posts (450+ rows)
                    ├── needs (270+ rows)
                    ├── mentions (270+ rows)
                    └── collection_logs (81+ rows)

Connexion correcte

postgresql://needfinder_service:UK3GlkfwnFZZVAGxScyz5DF6@supabase-db-prod:5432/postgres

Note : Le code utilise SET search_path TO needfinder pour accéder au schema.

Tables

Historique nettoyage

23/01/2026 - Migration PROD + Nettoyage DEV

Actions effectuées :

• Database needfinder sur DEV : DROP DATABASE
• Container needfinder-collector-dev : docker rm
• Tables orphelines dans postgres (DEV) : Nettoyées

Etat actuel : Aucune donnée NeedFinder sur DEV. Tout est sur PROD.

Backup

Backup automatique

Le schema needfinder est inclus dans le backup O2switch (cron toutes les 6h) :

• Script : /stock_8to/33800-stack/scripts/backup/pg-to-o2switch.sh
• Destination : o2switch:~/backup/postgres/

Backup manuel

# Dump schema needfinder depuis PROD
ssh gouroubleu@prod-portainer.local "docker exec supabase-db-prod pg_dump -U postgres postgres --schema=needfinder --inserts" > /stock_8to/backups/needfinder/needfinder_$(date +%Y%m%d_%H%M).sql

Restauration

ssh gouroubleu@prod-portainer.local "docker exec -i supabase-db-prod psql -U postgres" < /stock_8to/backups/needfinder/FICHIER.sql

API Endpoints

URLs publiques

Scheduler

• Cron : Toutes les 6h (00:00, 06:00, 12:00, 18:00 UTC)
• Cycle : Collect (Reddit + HN) → Analyze (via AI Orchestrator)

Système Webhook Async (24/01/2026)

Architecture

Post → submitAnalysisJobAsync() → AI-Orchestrator (queue)
                                        ↓
                                   Ollama traite
                                        ↓
                              Webhook /api/webhook/analysis
                                        ↓
                              Need créé → submitTranslationJobAsync()
                                        ↓
                              Webhook /api/webhook/translation
                                        ↓
                              need_statement_fr mis à jour

Endpoints Webhook

Champ analysis_status

Fonctions clés (orchestrator-client.ts)

submitAnalysisJobAsync(postId, prompt, options) → job_id
submitTranslationJobAsync(targetId, targetType, text, field) → job_id

Chaînage automatique

Quand un need est créé, la traduction FR est automatiquement soumise via submitTranslationJobAsync().

Historique des problèmes

Leçons :

• Toujours vérifier qu'on est sur DATABASE postgres, SCHEMA needfinder (PROD)
• NE JAMAIS modifier generate-needfinder.sh sans vérifier l'API_URL

Points critiques (NE PAS CASSER)

ATTENTION : Après migration PROD, TOUJOURS mettre à jour les scripts de génération dashboard.

ATTENTION : Le fichier services-registry.json peut être créé par root (via cron). Si git add échoue avec "Permission denied", faire : sudo chown gouroubleu:gouroubleu services-registry.json

Convention projets/schemas

Règle : 1 projet = 1 schema dédié

Avantages :

• Isolation des données par projet
• Backup/restore plus simple (pg_dump --schema=X)
• Pas de confusion entre tables
• Nettoyage facile si projet abandonné

Commandes de vérification

# Vérifier la connexion actuelle du container
ssh gouroubleu@prod-portainer.local "docker exec needfinder env | grep DB"

# Compter les données
ssh gouroubleu@prod-portainer.local "docker exec supabase-db-prod psql -U postgres -d postgres -c \"
SELECT 'posts' as t, count(*) FROM needfinder.posts
UNION ALL SELECT 'needs', count(*) FROM needfinder.needs
UNION ALL SELECT 'mentions', count(*) FROM needfinder.mentions;
\""

# Vérifier le health
curl -s http://192.168.1.12:5200/health | jq

# Vérifier via API publique
curl -s https://needfinder-api.33800.nowhere84.com/api/stats | jq