Dio Auth Interceptor

Per-request resolution of which token to attach. Five-step priority: explicit authScope='none' opt-out → caller-supplied Authorization header → explicit scope='seller'|'customer' → path heuristics (/vendor /seller → seller; /store /social /auth/customer → customer) → fall back to persisted active role.

1. onRequest reads options.extra['auth_scope'] from the per-call RequestTrace.
2. If 'none' → strip Authorization and pass through.
3. If caller already set Authorization → respect it but also attach seller_tok header for /vendor paths.
4. Otherwise pick scope by extra → path prefix → loadUserRole() (persisted role).
5. Attach Bearer token from AuthStorageService; fire-and-forget _checkAndSendFcmToken on first use of that token.

• /vendor paths always also receive a seller_tok header in addition to Authorization — required by the backend's vendor-impersonation middleware.
• FCM sync uses a separate raw Dio instance to avoid interceptor recursion (would otherwise self-call /fcm/token).
• If no token is found for the resolved scope, the request is sent unauthenticated (no early error) — debug log only.
• _fcmSyncInProgress set prevents concurrent FCM sync for the same auth token during burst requests at app start.

• lib/src/core/network/dio_helper.dart:143 // _authInterceptor
• lib/src/core/network/dio_helper.dart:129 // _isSellerOnlyPath
• lib/src/core/network/dio_helper.dart:82 // _checkAndSendFcmToken
• lib/src/core/network/request_trace.dart // RequestTrace.toOptions

• POST/fcm/tokenno status

  Side-channel: upload the FCM push token for the active auth scope so the backend can target push to this device + role.

  Request

  { token: string /* fcmToken */ } + header `Authorization: Bearer <authToken>`

  Response

  200 / 201 (no body)

  lib/src/core/network/dio_helper.dart:82 // _checkAndSendFcmToken

  auth: bearer (per role). Fired through a separate raw Dio instance to avoid interceptor recursion. Dedup is tracked in SharedPreferences via 'fcm_sent_<fcmToken>_<authSuffix>'.

The path heuristics are the load-bearing piece — many endpoints don't pass authScope explicitly and rely on this fallback. Adding a new endpoint family means updating _isSellerOnlyPath / _isCustomerOnlyPath.