Aller au contenu

Django admin

Status: Placeholder — to be developed. Last reviewed: — Reference structural sibling: guidelines/ui/forms.md (component-style sectioning).

Scope (when this guideline lands)

When to register a model in Django admin (and when not), list_display / list_filter / search_fields conventions, inlines, custom admin actions, read-only vs editable fields for audit-sensitive models, how admin coexists with the user-facing CRUD UI, who can access admin (the roadmap/done/website-pages-audit.md decision: superuser-only).

Out of scope (cross-refs)

  • Multi-tenant queryset scoping in admin → guidelines/security/multi-tenant-isolation.md (placeholder). Default Django admin doesn't honour app-level practice scoping; document the rule.
  • Display strings (short_description, action labels, list_filter titles) → guidelines/i18n/translation-rules.md (French source).
  • Website-side CRUD UI (the user-facing equivalent that admin is being demoted in favour of) → guidelines/ui/lists.md, forms.md, detail-pages.md.
  • Field conventions on the underlying model → guidelines/backend/models.md (placeholder).

Sources to mine when writing this

  • apps/*/admin.py across the project — survey what's registered and what's not. Especially apps/practices/admin.py (rich inlines per roadmap/done/website-pages-audit.md), apps/entities/admin.py (curated).
  • roadmap/done/website-pages-audit.md — Section 1 ("Recommendation: Website > Admin") and Section 2 (data coverage gaps). The decision to demote admin to superuser-only debugging is binding.
  • apps/accounts/admin.py — User admin customisation.
  • Django docs on ModelAdmin (reference, link don't quote).

Starter hard rules to investigate

  1. Admin is superuser-only per website-pages-audit.md decision. Don't grant is_staff to non-superusers.
  2. list_display max ~8 columns — admin is for debugging, not high-density data review (use website list pages for that).
  3. Inlines for ≤ 10 children; for more, link to a separate admin page (admin inlines get clunky at scale).
  4. All registered models have search_fields and list_filter — debugging requires fast lookup.
  5. No business logic in admin actions — call the same services the website views call.

Decision points to settle

  1. Which models stop being admin-managed entirely? Per website-pages-audit.md Section 1, "stop investing in admin fieldsets/inlines." Define what minimum admin coverage looks like.
  2. Custom admin themes: any project-specific styling? Currently default Django.
  3. Admin actions for one-off data fixes vs management commands: pick a default.
  4. History tracking: django-simple-history or custom AuditModel? Coordinate with backend/models.md.

Known deviations to look for during writing

  • Heavy admin pages with 20+ list_display columns (signal: admin is doing UI work that should be on the website).
  • Admin actions performing business logic inline.
  • Models registered in admin but not on website (gap from the website-pages-audit.md Section 2 inventory — most cleared, verify).

If found, file as roadmap/backlog/backend-admin-drift-2026-MM.md.