Accounts & Authentication

API fact source: Django backend generated docs

Module Role

accounts owns identity, roles, login methods, and request-time role context. Business modules consume login state and current_role through this module instead of interpreting authentication details independently.

Code entry:

• backend/apps/accounts/models/
• backend/apps/accounts/views/
• backend/apps/accounts/serializers/
• backend/apps/accounts/authentication.py
• backend/apps/accounts/middleware.py
• backend/apps/accounts/tasks.py

Why The Active Role Is Not Persisted

Users can hold multiple roles. roles describes the available identities; current_role describes the identity selected for one request. Keeping it as request context avoids global state changes when the same account switches roles, and it keeps different clients independent.

current_role comes from a JWT claim or X-Current-Role, then middleware verifies that it belongs to user.roles. Role identifiers are therefore a cross-module protocol; renaming one affects string checks in business apps.

auth_version revokes old tokens. Password, role, and status changes need to use the existing version bump path, otherwise old tokens remain valid.

Web clients receive JWTs in cookies. Mini program clients receive tokens in the response body. Plaintext password fallback after SM2 decrypt failure is compatibility behavior for older clients, not a new authentication target.

When Changing Authentication

• Permission checks use the existing role helpers and permission patterns. Reading user.roles[0] ignores the active role selected for the request.
• A new login method needs token delivery, TOTP handling, auth_version validation, and locale initialization.
• User batch import is an async task. Moving Excel parsing and user creation back into the request thread brings back timeout risk.

Easy-To-Miss Flows

• Foreign-teacher registration is anonymous. Check the default role, account status, and immediate login behavior after changes.
• WeChat login relies on wxid=open_id. Binding changes affect mini program login, bind, and unbind flows.
• WebAuthn, TOTP, and SM2 require client cooperation, so real frontend verification matters in addition to unit tests.