Instruction file imported from dtebar-10010/tq_v02 (.github/instructions/auth-allauth.instructions.md). Copyright stays with the author.

Auth & django-allauth Instructions

URL ordering rule (CRITICAL)

In tqv02_settings/urls.py, all custom auth views (login, register, password-reset, ajax variants) MUST appear BEFORE path('accounts/', include('allauth.urls')). If allauth's include comes first it shadows /accounts/login/ and the AJAX modal returns HTML instead of JSON.

Symptom of regression: "Invalid email or password" with correct credentials, no JSON in network tab.

Multi-backend login rule

AUTHENTICATION_BACKENDS contains both Django's ModelBackend and allauth's AuthenticationBackend. Any explicit login(request, user) call MUST pass:

login(request, user, backend="django.contrib.auth.backends.ModelBackend")

Omitting backend= raises ValueError: multiple authentication backends configured.

Cart-merge handoff (do NOT bypass)

Both email/password and social logins funnel post-login redirect through TQAccountAdapter.get_login_redirect_url(). If session['pending_merge'] is set, the adapter routes to cart_merge_prompt. New auth flows MUST preserve this; do not call login() and then immediately redirect('home') -- always go through the adapter.

Social-login regressions to honour

Tests live in tqv02_app/tests/test_views_social_auth.py. Run them after any change to templates/socialaccount/ or allauth_adapter.py.

Provider configuration

• Social provider URLs (/accounts/<provider>/login/) are registered by include('allauth.urls') regardless of DB state.
• SocialApp.DoesNotExist at request time = admin has not configured the provider in /admin/socialaccount/socialapp/. NOT a URL bug.
• Production requires ACCOUNT_DEFAULT_HTTP_PROTOCOL = 'https' (already set). Without it the callback URL sent to Google is http:// and rejected.
• Site.objects.get_current().domain must match the user-visible domain (www vs non-www) OR both redirect URIs must be registered in the provider console.
• setup_social_providers management command is the canonical way to upsert providers from .env. Never edit SocialApp rows directly in fixtures (secret leak class).

Registration flow

• register_ajax_view creates the user, then calls login(request, user, backend='...'), then merges session cart via merge_session_to_db(request, user), then returns JSON.
• If a guest had items in the session cart, the response includes pending_merge=True so the modal redirects to cart_merge_prompt.
• Email verification: token is generated, persisted on EmailSubscription (newsletter) or CustomUser.email_verification_token (account). Verify-link views are NOT @login_required.

Password reset

• Uses Django built-in views wired to custom templates in templates/registration/.
• Reset emails go through the standard PasswordResetForm. Subject and body templates MUST be wrapped in {% trans %}.

Forbidden patterns

• login(request, user) without backend= -- ValueError.
• path('accounts/', include('allauth.urls')) placed before custom auth paths -- shadows /accounts/login/.
• Hardcoding Google / Apple / Facebook client secrets in setup_social_providers defaults -- read from os.environ.
• Dumping socialaccount.socialapp into a tracked fixture -- secret leak.

Tests to run after touching this surface

python manage.py test tqv02_app.tests.test_allauth `
  tqv02_app.tests.test_allauth_regressions `
  tqv02_app.tests.test_guest_auth_matrix `
  tqv02_app.tests.test_setup_social_providers `
  tqv02_app.tests.test_views_social_auth `
  --settings=tqv02_settings.test_settings --keepdb