Toolbox — IDEOLAB Admin Tools Extended

Objectif & positionnement du package

IDEOLAB Admin Tools Extended est un addon conçu pour enrichir l’admin Django en s’appuyant sur django-admin-tools, sans le remplacer. L’idée n’est pas de forker toute la librairie upstream, mais de lui ajouter une couche d’outillage technique réutilisable, dense, moderne et orientée exploitation.

Ce que le package apporte concrètement :

Un module Visibility Toggle permettant de filtrer l’affichage des Data Models vides
Une CountedAppList affichant les modèles avec compteur SQL et mise en évidence visuelle
Un bouton Structure pour afficher la définition détaillée d’un Data Model
Un bouton Relation Diagram pour visualiser les FK / O2O / M2M de manière graphique
Un menu FK compact affichant les tables reliées et leur volumétrie
Un bouton Migration Doctor en lazy loading pour analyser un modèle sans alourdir le chargement initial

Philosophie de conception

Le package embarque le noyau UI et technique réutilisable. En revanche, l’organisation métier des blocs du dashboard — par exemple SRDF Topology, SRDF Capture, SRDF Bootstrap — reste dans le projet consommateur.

Reusable UI Admin addon Lazy doctor No full fork

Pourquoi en faire un package

Éviter de recopier le même code dashboard d’un projet à l’autre
Centraliser les améliorations dans un seul dépôt
Distribuer facilement l’addon via une wheel
Simplifier le déploiement via pip install
Rendre le système plus propre qu’un collage direct dans un projet monolithique

Cas d’usage typiques

Projet SRDF avec backoffice technique dense
Projet multi-apps nécessitant une vue admin structurée par domaines
Besoin d’inspection rapide des tables, champs, relations, indexes et risques de migration
Environnements internes où l’admin Django sert aussi d’outil d’exploitation

Livrables & Toolbox

Télécharger la wheel du package

/static/toolbox/ideolab_admin_tools-0.1.0-py3-none-any.whl

Télécharger ce guide HTML

/static/toolbox/ideolab_admin_tools_complete_guide.html

Architecture logique du package

Le package est volontairement découpé en blocs très lisibles. L’objectif est d’isoler : l’UI dashboard, les vues AJAX, les services techniques, et les templates.

ideolab_admin_tools/
  pyproject.toml
  README.md
  src/
    ideolab_admin_tools/
      __init__.py
      apps.py
      dashboard.py
      views.py
      urls.py
      services/
        __init__.py
        model_migration_doctor.py
      templates/
        admin/
          ideolab_admin_tools/
            dashboard_visibility_toggle.html

dashboard.py

Contient les composants réutilisables branchés dans le dashboard :

VisibilityToggleModule
CountedAppList
modals Structure / Relation
FK dropdown
bouton Doctor lazy

views.py

Contient les vues AJAX génériques du package :

doctor_modal_view
résolution dynamique du modèle via apps.get_model()
retour JSON + HTML de la modal doctor

services/model_migration_doctor.py

Moteur d’analyse technique d’un modèle Django :

introspection Django
introspection DB réelle
schema diff
index risks
migration impact
recommended actions

Point clé : le package ne doit pas embarquer la composition métier finale du dashboard d’un projet. Le fichier dashboard_parameters.py du projet client doit rester dans le projet client. Il décrit les blocs, l’ordre, les titres et les modèles à afficher.

Flux global côté interface

Dashboard page load
  -> admin_tools renders CountedAppList
  -> row counters + buttons are rendered
  -> heavy "Migration Doctor" analysis is NOT executed

User clicks DOC
  -> AJAX call to /admin-tools-ext/doctor/modal/
  -> doctor_modal_view resolves the model
  -> ModelMigrationDoctorService.analyze()
  -> JSON response with HTML fragment
  -> modal content is injected client-side

Contenu détaillé du package

Fichiers Python minimaux

Fichier	Rôle	Remarque
`apps.py`	Déclare l’AppConfig du package	Nom logique : `ideolab_admin_tools`
`dashboard.py`	Dashboard modules réutilisables	Ne pas y laisser des classes 100% métier SRDF
`views.py`	Vue doctor modal	Vue AJAX générique, découplée du domaine métier
`urls.py`	Namespace du package	Exemple : `ideolab_admin_tools:doctor_modal`
`services/model_migration_doctor.py`	Moteur technique du doctor	Analyse d’un seul modèle à la fois

Template du Visibility Toggle

Le template dashboard_visibility_toggle.html doit être placé dans :

templates/admin/ideolab_admin_tools/dashboard_visibility_toggle.html

Et le module dashboard doit pointer explicitement dessus :

template = "admin/ideolab_admin_tools/dashboard_visibility_toggle.html"

Piège classique : si tu gardes un ancien chemin du type admin/srdf/dashboard_visibility_toggle.html, le package semblera installé, mais l’UI ne sera pas cohérente, voire ne s’affichera pas du tout.

pyproject.toml type

[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "ideolab-admin-tools"
version = "0.1.0"
description = "IDEO Lab extensions for django-admin-tools"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
  "Django>=4.1,<4.3",
  "django-admin-tools>=0.9"
]

[tool.setuptools]
package-dir = {"" = "src"}

[tool.setuptools.packages.find]
where = ["src"]

[tool.setuptools.package-data]
ideolab_admin_tools = [
  "templates/**/*.html",
]

Build de la wheel

Le build se fait depuis la racine du package, pas depuis le projet Django consommateur.

cd D:\wamp5\SSIDEO_LAB\SSPLUGINS\ideolab_admin_tools
python -m pip install --upgrade build wheel setuptools
python -m build

Résultat attendu → dist/ideolab_admin_tools-0.1.0-py3-none-any.whl

Vérifier les artefacts

dir dist

Artefact	Rôle	Conseil
`ideolab_admin_tools-0.1.0-py3-none-any.whl`	Package installable	À déposer dans `/static/toolbox` pour distribution interne
`ideolab_admin_tools-0.1.0.tar.gz`	Source distribution	Utile pour audit, archive, ou reconstruction

Erreurs fréquentes au build

README.md absent ou vide

Le champ readme = "README.md" du pyproject.toml suppose que le fichier existe et soit cohérent.

Fichiers hors de `src/`

Si certains modules restent à la racine ou dans un ancien projet, ils ne seront pas embarqués dans la wheel.

Templates non inclus

Sans la section package-data, les templates HTML peuvent être oubliés au packaging.

Installation du package

Installation standard via wheel

pip install /static/toolbox/ideolab_admin_tools-0.1.0-py3-none-any.whl

Installation depuis un fichier local

pip install dist/ideolab_admin_tools-0.1.0-py3-none-any.whl

Installation editable (développement)

cd /path/to/ideolab_admin_tools
pip install -e .

Choix recommandé :

wheel pour les serveurs, recettes, déploiements stables et distribution interne
-e . pour le développement actif du package lui-même

Vérification post-install

python manage.py shell -c "import ideolab_admin_tools; print('OK')"

Attendu → OK

Intégration dans un projet Django

1) INSTALLED_APPS

INSTALLED_APPS = [
    "admin_tools",
    "admin_tools.theming",
    "admin_tools.menu",
    "admin_tools.dashboard",

    "ideolab_admin_tools",

    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
]

2) URLs du projet

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("admin-tools-ext/", include("ideolab_admin_tools.urls")),
    path("admin/", admin.site.urls),
]

3) Settings admin-tools

ADMIN_TOOLS_INDEX_DASHBOARD = "srdf_project.dashboard_parameters.CustomIndexDashboard"
ADMIN_TOOLS_APP_INDEX_DASHBOARD = "srdf_project.dashboard_parameters.CustomAppIndexDashboard"

4) Imports dans le dashboard projet

from ideolab_admin_tools.dashboard import CountedAppList, VisibilityToggleModule

Important : les classes CustomIndexDashboard et CustomAppIndexDashboard du projet client doivent rester côté projet client. Le package fournit les briques, pas la composition métier complète.

5) Namespace URLs

Si la vue doctor modal est namespacée dans le package, le reverse doit utiliser ce namespace :

reverse("ideolab_admin_tools:doctor_modal")

Dashboard & expérience utilisateur

L’objectif du dashboard étendu n’est pas seulement esthétique. Il vise à fournir un cockpit technique permettant de voir immédiatement :

quels modèles ont des données
les relations entre tables
la structure Django d’un modèle
les points d’attention de migration

Exemple d’intégration SRDF

from django.utils.translation import gettext_lazy as _
from django.urls import reverse
from admin_tools.dashboard import modules, Dashboard
from admin_tools.utils import get_admin_site_name

from ideolab_admin_tools.dashboard import CountedAppList, VisibilityToggleModule


class CustomIndexDashboard(Dashboard):
    columns = 2

    def init_with_context(self, context):
        site_name = get_admin_site_name(context)

        self.children.append(modules.LinkList(
            _("IDEOLAB ADMIN SRDF"),
            layout="inline",
            draggable=True,
            deletable=True,
            collapsible=True,
            children=[
                [_("SRDF"), "/admin"],
                [_("SYST"), "/admin-system"],
                [_("HOME"), "/"],
                [_("PSW"), reverse("%s:password_change" % site_name)],
                [_("EXIT"), reverse("%s:logout" % site_name)],
            ]
        ))

        self.children.append(VisibilityToggleModule())

        self.children.append(CountedAppList(
            _("----  SRDF TOPOLOGY / INSTALL / SETTINGS  ----"),
            models=(
                "srdf.Node",
                "srdf.models.ReplicationService",
                "srdf.models.SRDFInstallProfile",
                "srdf.models.SRDFInstallRun",
                "srdf.models.SRDFSettingDefinition",
                "srdf.models.SRDFSettingValue",
            ),
        ))

Exemple pour un autre projet

self.children.append(CountedAppList(
    _("----  OPS / CUSTOMER SUCCESS  ----"),
    models=(
        "crm.Customer",
        "crm.Contract",
        "crm.Ticket",
        "ops.DeploymentRun",
        "ops.Incident",
    ),
))

Composants disponibles dans chaque ligne de modèle

Composant	Usage	Effet
`VisibilityToggleModule`	haut du dashboard	filtre les Data Models vides
`CountedAppList`	bloc principal	ligne modèle + compteur + boutons + couleur
`Structure`	bouton compact	ouvre la structure des champs
`Relation`	bouton compact	ouvre le diagramme relationnel
`FK`	menu compact	liste les tables liées + compteurs
`DOC`	bouton lazy	charge la modal doctor via AJAX

Migration Doctor — fonctionnement détaillé

Le Migration Doctor est le composant le plus lourd techniquement. Pour préserver les performances du dashboard, il ne s’exécute plus au chargement initial de la page. Il est chargé à la demande.

Pourquoi lazy loading ?

éviter une introspection DB complète pour chaque modèle
garder un dashboard réactif même avec plusieurs dizaines de tables
ne payer le coût d’analyse que pour le modèle demandé

Ce que la modal analyse

structure Django du modèle
snapshot DB réelle
schema diff
index risks
relation risks
migration impact
recommended actions

Onglets affichés

Overview
Structure
DB Objects
Relations
Index Risks
Migration Impact
Repair Plan

Route du doctor

path("doctor/modal/", doctor_modal_view, name="doctor_modal")

Exemple d’appel AJAX

GET /admin-tools-ext/doctor/modal/?app_label=srdf&model_name=replicationservice

Principe de la vue

@require_GET
def doctor_modal_view(request):
    app_label = request.GET.get("app_label")
    model_name = request.GET.get("model_name")
    model = apps.get_model(app_label, model_name)

    service = ModelMigrationDoctorService(model=model, using="default")
    doctor = service.analyze()

    return JsonResponse({
        "success": True,
        "html": "...rendered modal html..."
    })

Recommandation : même si le projet n’a “que” 20 à 30 tables, garde le doctor en lazy loading. C’est la meilleure garantie contre les régressions de performance.

Déploiement & distribution interne

Copier la wheel dans la toolbox

cp dist/ideolab_admin_tools-0.1.0-py3-none-any.whl /static/toolbox/

Procédure recommandée

Build local de la wheel
Test sur un projet sandbox
Copie dans /static/toolbox
Publication du guide HTML
Installation sur projet cible
Validation dashboard + modals + doctor lazy

Bonne pratique : conserver à la fois la wheel et la source distribution. La wheel sert à l’installation rapide ; le tar.gz sert à l’archive et à l’audit.

Checklist post-install

Contrôle	Attendu
Import Python	`import ideolab_admin_tools` fonctionne
Dashboard	les blocs s’affichent
Visibility toggle	la checkbox filtre bien les modèles
DOC	le doctor se charge en AJAX sans erreur JSON
Templates	pas d’erreur de template introuvable

Upgrade / patch d’une version à une autre

Comme le package est amené à évoluer, il faut prévoir une procédure claire de montée de version.

Cas simple : réinstaller une wheel plus récente

pip install --upgrade /static/toolbox/ideolab_admin_tools-0.1.1-py3-none-any.whl

En environnement de recette / prod

# 1) sauvegarder le contexte
pip freeze > requirements_before_upgrade.txt

# 2) installer la nouvelle wheel
pip install --upgrade ideolab_admin_tools-0.1.1-py3-none-any.whl

# 3) redémarrer l’application
systemctl restart gunicorn
systemctl reload nginx

Conseil : si tu modifies dashboard.py, views.py ou les templates du package, fais toujours un test sur un projet de recette avant déploiement large. Les régressions dans les modals sont visibles immédiatement.

Ce qu’il faut retester après upgrade

affichage initial du dashboard
checkbox de visibilité
Structure modal
Relation modal
FK dropdown
Migration Doctor lazy
reverse namespace des URLs

Dépannage

1) Le dashboard ne charge pas

python manage.py check
python manage.py shell -c "import ideolab_admin_tools; print('OK')"

2) NoReverseMatch sur doctor modal

Vérifie le namespace et l’include des URLs du package.

reverse("ideolab_admin_tools:doctor_modal")

3) Le bouton DOC ouvre une erreur JSON

ouvrir l’onglet Réseau du navigateur
regarder la réponse exacte de /doctor/modal/
corriger la vraie erreur Python côté serveur

4) Le template checkbox n’est pas trouvé

template = "admin/ideolab_admin_tools/dashboard_visibility_toggle.html"

5) La wheel s’installe mais rien ne s’affiche

vérifier INSTALLED_APPS
vérifier l’import dans dashboard_parameters.py
vérifier ADMIN_TOOLS_INDEX_DASHBOARD
redémarrer le serveur Django

6) Dashboard lent

Le premier point à surveiller est le doctor. Il ne doit pas être rendu de manière eager.

# mauvais
doctor_modal_html = self._build_doctor_modal_html(model)

# bon
doctor_modal_html = self._build_doctor_lazy_button_html(model)

Point de vigilance : ne pas garder des chemins hardcodés vers srdf_project.dashboard ou admin/srdf/... à l’intérieur du package. Tout le package doit être cohérent avec son propre namespace ideolab_admin_tools.

Objectif & positionnement du package

Philosophie de conception

Pourquoi en faire un package

Cas d’usage typiques

Livrables & Toolbox

Architecture logique du package

dashboard.py

views.py

services/model_migration_doctor.py

Flux global côté interface

Contenu détaillé du package

Fichiers Python minimaux

Template du Visibility Toggle

pyproject.toml type

Build de la wheel

Vérifier les artefacts

Erreurs fréquentes au build

README.md absent ou vide

Fichiers hors de src/

Templates non inclus

Installation du package

Installation standard via wheel

Installation depuis un fichier local

Installation editable (développement)

Vérification post-install

Intégration dans un projet Django

1) INSTALLED_APPS

2) URLs du projet

3) Settings admin-tools

4) Imports dans le dashboard projet

5) Namespace URLs

Dashboard & expérience utilisateur

Exemple d’intégration SRDF

Exemple pour un autre projet

Composants disponibles dans chaque ligne de modèle

Migration Doctor — fonctionnement détaillé

Pourquoi lazy loading ?

Ce que la modal analyse

Onglets affichés

Route du doctor

Exemple d’appel AJAX

Principe de la vue

Déploiement & distribution interne

Copier la wheel dans la toolbox

Procédure recommandée

Checklist post-install

Upgrade / patch d’une version à une autre

Cas simple : réinstaller une wheel plus récente

En environnement de recette / prod

Ce qu’il faut retester après upgrade

Dépannage

1) Le dashboard ne charge pas

2) NoReverseMatch sur doctor modal

3) Le bouton DOC ouvre une erreur JSON

4) Le template checkbox n’est pas trouvé

5) La wheel s’installe mais rien ne s’affiche

6) Dashboard lent

Fichiers hors de `src/`