حسابات الزوّار

التسجيل والتحقّق برمز بريدي وتسجيل الدخول واستعادة كلمة المرور — وما الذي يفتحه رمز الزائر تحت ‎/api/public/me‎.

يمكن لزائر الموقع أن يملك حسابًا خاصًّا به: مفضّلات وعمليات بحث محفوظة وإشعارات وطلبات معاينة تتبعه إلى جهاز آخر. والتسجيل ينشئ كذلك جهة اتصال في النظام عند مرحلة LEAD، وهذا هو سبب بناء الموقع فوق النظام لا بجانبه.

كل مسارات /public/auth/* مفتوحة. وكل ما تحت /public/me/* يحتاج رمز الزائر.

المسار

register  ──▶  verify-otp  ──▶  token
   │              ▲
   │              │
   └──▶  resend-otp

login  ──▶  token
forgot-password  ──▶  (بريد)  ──▶  reset-password  ──▶  login

الطريقة	المسار	الجسم	الجواب
POST	`/public/auth/register`	`{ email, password, firstName?, lastName?, phone? }`	201 `{ visitorId }`
POST	`/public/auth/verify-otp`	`{ visitorId, code }` (ستّة أرقام)	`{ token, visitor }`
POST	`/public/auth/resend-otp`	`{ visitorId }`	`{ sent: true }`
POST	`/public/auth/login`	`{ email, password }`	`{ token, visitor }`
POST	`/public/auth/logout`	—	`{ loggedOut: true }`
POST	`/public/auth/forgot-password`	`{ email }`	`{ sent: true }`
POST	`/public/auth/reset-password`	`{ token, password }`	—

طول كلمة المرور ٨ محارف على الأقل. وregister وforgot-password محميّان من الروبوتات.

الرمز

يعيد verify-otp وlogin رمزًا حاملًا. أرسله مع كل نداء إلى /public/me/*:

Authorization: Bearer <token>

يعيش ٧ أيام وهو عديم الحالة. و«تسجيل الخروج» هو أن يتخلّص عميلك منه؛ POST /public/auth/logout يعيد { loggedOut: true } ولا يفعل شيئًا غير ذلك.
ليس رمز موظّف في النظام. الاثنان موقّعان بالمفتاح نفسه ويفصل بينهما ادّعاء الجمهور، فلا يعمل أحدهما مكان الآخر.
احفظه حيث تحفظ أي اعتماد جلسة. ولا تضعه في كوكي يقرؤه كود خادمك بوصفه تصريحًا — فحارس الواجهة هو حدّ الأمان، لا وسيطك.

وحقل visitor صغير عمدًا وبلا حقل name:

{
  "id": "…", "email": "…", "firstName": "Sara", "lastName": "Kamal",
  "phone": "…", "emailVerified": true, "contactId": "…"
}

اشتقّ اسم العرض بنفسك: الأول + الأخير، وإلّا الجزء المحلي من البريد، وإلّا تسمية ثابتة.

ما الذي يفتحه الرمز

المسار	ما هو
`GET /public/me`	الملف الشخصي والتفضيلات وحقل `counts` الذي ترسم منه شارات القائمة الجانبية.
`PATCH /public/me` و`DELETE /public/me`	تعديل الحساب أو حذفه.
`POST /public/me/password` و`POST /public/me/avatar`	تغيير كلمة المرور ورفع صورة (بحدّ ٢ ميجابايت).
`GET/PUT/DELETE /public/me/favorites…`	المفضّلات، بسقف ١٠ لكل نوع.
`GET/POST/PATCH/DELETE /public/me/saved-searches…`	عمليات البحث المحفوظة وتكرار تنبيهاتها.
`GET /public/me/notifications` و`POST …/read`	الإشعارات داخل الموقع.
`GET /public/me/viewing-requests` و`POST …/{id}/cancel`	معاينات الزائر نفسه.

تعيد GET /public/me/favorites و/saved-searches و/viewing-requests مصفوفة مجرّدة في data؛ أما /public/me/notifications فمقسّمة إلى صفحات. انظر مرجع الواجهة لكل شكل.

رموز الأخطاء

الرمز	الحالة	ماذا تفعل الواجهة
`VISITOR_EMAIL_TAKEN`	400	هناك حساب موثّق بالفعل. اعرض تسجيل الدخول.
`VISITOR_CREDENTIALS_INVALID`	401	بريد خاطئ أو كلمة مرور خاطئة — لا يُميَّزان عمدًا. اعرض رسالة واحدة.
`VISITOR_EMAIL_NOT_VERIFIED`	401	الحساب موجود ولم يُوثَّق قط. انقله إلى شاشة الرمز واعرض `resend-otp`.
`OTP_INVALID`	401	رمز خاطئ.
`OTP_EXPIRED`	401	تعيش الرموز ١٠ دقائق.
`OTP_LOCKED`	401	خمس محاولات خاطئة. ولا يفكّه إلا `resend-otp`.
`RESET_TOKEN_INVALID`	400	تعيش رموز الاستعادة ٣٠ دقيقة.
`PASSWORD_CURRENT_INVALID`	401	تغيير كلمة المرور بكلمة حالية خاطئة.
`VISITOR_TOKEN_REQUIRED` / `VISITOR_TOKEN_INVALID`	401	لا رمز، أو رمز منتهٍ، على نداء `/public/me/*`. سجّل خروج الزائر واطلب الدخول.

سلوكان يستحقّان المعرفة

التسجيل فوق حساب غير موثّق ينجح، ويبدو تمامًا كتسجيل أول مرّة. فالسجلّ غير الموثّق ليس حساب أحد — يُنشأ واحد لأي بريد يكتبه مالك في نموذج عرض وحدته — ورفضه إلى الأبد كان سيتيح لأي أحد أن يحبس غريبًا خارج عنوانه. تحلّ كلمة المرور الجديدة محلّ القديمة ويُرسل رمز جديد؛ ولا يُمسّ emailVerified، فيبقى الرمز البريدي وحده قادرًا على ضبطه. لا تستطيع واجهتك التمييز بين الحالتين ولا ينبغي أن تحاول.

تسجيل الدخول لا يصدر رمزًا بريديًّا أبدًا. والاستجابة التي تحمل visitorId بلا token هي تحدّي التسجيل ولا شيء غيره.

بريد التحقّق والاستعادة ترسله خدمة منفصلة من النظام. فإن لم تكن تلك الخدمة تعمل في بيئتك، لن تصل الرموز وستبقى السجلّات في الطابور. لا تبنِ مسار تسجيل يعتمد تطويره المحلي على وصول بريد.