docs: add synthetic email warning design spec

2026-05-24 12:18:27 +05:00
parent ff2271ecb1
commit dba8e902bf
1 changed files with 74 additions and 0 deletions
@@ -0,0 +1,74 @@
+# Synthetic Email Warning Design
+
+**Date:** 2026-05-24
+**Status:** Draft
+
+## Problem
+
+When users authenticate via VK without providing a real email, the server generates a synthetic email (`vk_<userId>@vk.local`). These users cannot receive email notifications, but there is no indication of this in the personal account (LK).
+
+## Solution
+
+Display an informational MUI Alert in two places when the user's email matches a known synthetic domain:
+
+1. **AuthMethodsSection** — where the current email is displayed
+2. **NotificationsPage** — where notification settings are managed
+
+## Architecture
+
+### Email Utility
+
+New file: `client/src/shared/lib/email-utils.ts`
+
+```ts
+const SYNTHETIC_DOMAINS = ['vk.local']
+
+export function isSyntheticEmail(email: string): boolean {
+  return SYNTHETIC_DOMAINS.some(domain => email.endsWith(`@${domain}`))
+}
+```
+
+This is a pure client-side check. The `@vk.local` domain is internal-only — real users cannot register with it.
+
+### AuthMethodsSection
+
+Add MUI Alert below the email display:
+
+```tsx
+{isSyntheticEmail(user.email) && (
+  <Alert severity="info">
+    Ваша почта сгенерирована автоматически. Без указания реальной почты вы не сможете получать уведомления о заказах.
+  </Alert>
+)}
+```
+
+### NotificationsPage
+
+Add MUI Alert at the top of the page:
+
+```tsx
+{isSyntheticEmail(user.email) && (
+  <Alert severity="info">
+    Ваша почта сгенерирована автоматически. Для получения уведомлений укажите реальную почту в настройках профиля.
+  </Alert>
+)}
+```
+
+## Data Flow
+
+```
+user.email (from auth model)
+  → isSyntheticEmail() check
+    → true → render Alert
+    → false → no change
+```
+
+## Error Handling
+
+- No errors possible — pure string comparison
+- If `user.email` is undefined/null, the check returns `false` (safe)
+
+## Testing
+
+- Unit test for `isSyntheticEmail()` with real emails, synthetic emails, edge cases
+- No component tests needed — trivial conditional rendering