Watch
1
0
Fork
You've already forked Seyyed_arc
0
forked from hesabix/arc
Seyyed_arc/docs/person-phone-identity.md

47 lines
5.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# هویت شماره تلفن اشخاص
این سند قرارداد فنی شماره تلفن اشخاص را برای جست‌وجو و ثبت سریع تعریف می‌کند.
## مدل داده
مقادیر `mobile`، `mobile_2`، `mobile_3` و `phone` فیلدهای نمایشی و قابل ویرایش فعلی باقی می‌مانند و migration یا تغییر منطقه آن‌ها را بازنویسی نمی‌کند. ثبت سریع مشتری جدید، شماره استانداردشده را در `mobile` ذخیره می‌کند. برای هر فیلد یک ستون متناظر با پسوند `_normalized` وجود دارد که فقط در صورت معتبر بودن شماره، مقدار E.164 را نگه می‌دارد.
هر ستون استاندارد همراه `business_id` ایندکس شده است. تطبیق یک شماره در فروش سریع با query مستقیم روی این چهار ایندکس انجام می‌شود و به تعداد اشخاص کسب‌وکار یا سقف نتایج جست‌وجوی نام وابسته نیست.
## منطقه پیش‌فرض
`businesses.default_phone_region` یک کد دوحرفی ISO-3166 است. مقدار پیش‌فرض برای کسب‌وکارهای فعلی `IR` است.
- شماره‌های دارای `+` یا پیش‌شماره `00` مستقل از این تنظیم تفسیر می‌شوند.
- شماره‌های محلی با منطقه کسب‌وکار تفسیر می‌شوند.
- نمونه‌ها: `IR`، `AE`، `TR` و `US`.
- تغییر منطقه، ستون‌های استاندارد اشخاص همان کسب‌وکار را در batchهای محدود بازسازی می‌کند؛ مقدار خام شماره تغییر نمی‌کند.
برای کسب‌وکار فعلی خارج از ایران باید ابتدا منطقه درست در «تنظیمات کسب‌وکار ← اطلاعات کسب‌وکار» ثبت شود. پس از ذخیره، شماره‌های محلی موجود دوباره بررسی و استاندارد می‌شوند.
## Migration و داده‌های قبلی
Migration `20261018_000001_person_phone_identity` ستون منطقه، چهار ستون استاندارد و چهار ایندکس مرکب را اضافه می‌کند. سپس شماره‌های قبلی را به‌صورت دسته‌ای backfill می‌کند. چون کسب‌وکارهای قدیمی هنوز منطقه‌ای نداشته‌اند، اولین backfill با مقدار پیش‌فرض `IR` انجام می‌شود.
شماره نامعتبر یا مبهم بدون کلید استاندارد باقی می‌ماند و مقدار اصلی آن حذف نمی‌شود. رکوردهای تکراری موجود نیز خودکار حذف یا ادغام نمی‌شوند، زیرا انتخاب رکورد مرجع یک تصمیم حسابداری است. فروش سریع تطبیق‌های یک شماره را مستقل از جایگاه شخص در فهرست پیدا می‌کند و تا سقف پاسخ endpoint برای انتخاب کاربر برمی‌گرداند.
## مسیرهای نوشتن
رویدادهای SQLAlchemy مدل `Person` قبل از insert و update کلیدهای استاندارد را با منطقه کسب‌وکار همگام می‌کنند. در نتیجه ثبت سریع، فرم اشخاص، ورود فایل و سایر مسیرهای ORM از یک تابع مرکزی استفاده می‌کنند.
منطقه کسب‌وکار در سطح Session پایگاه داده cache می‌شود تا ورود گروهی اشخاص برای هر ردیف یک query جداگانه ایجاد نکند. تغییر منطقه این cache را پیش از بازسازی کلیدها باطل می‌کند.
بازیابی بکاپ اشخاص را با SQL خام وارد می‌کند و رویدادهای ORM در آن اجرا نمی‌شوند؛ به همین دلیل هر دو مسیر restore پس از ورود جدول‌ها، کلیدهای استاندارد اشخاص کسب‌وکار بازیابی‌شده را صریحاً بازسازی می‌کنند. بکاپ قدیمی که فیلد منطقه را ندارد، برای کسب‌وکار جدید `IR` می‌گیرد و در حالت جایگزینی، منطقه فعلی کسب‌وکار را حفظ می‌کند.
ثبت سریع در PostgreSQL پیش از query و create یک advisory transaction lock مخصوص همان کسب‌وکار می‌گیرد. دو درخواست هم‌زمان فروش سریع نمی‌توانند هر دو مرحله «پیدا نشد» را رد کنند و یک شماره را هم‌زمان بسازند.
این ساختار عمداً unique constraint سراسری روی موبایل ایجاد نمی‌کند تا داده‌های تکراری قبلی migration را متوقف نکنند و کاربردهای فعلی سایر ماژول‌ها شکسته نشوند. جلوگیری از ایجاد تکراری در مسیر ثبت سریع از query مستقیم و قفل تراکنشی حاصل می‌شود.
## آزمون‌های لازم
- ورودی محلی ایران، امارات و آمریکا و ورودی بین‌المللی با `+` یا `00` باید به E.164 مورد انتظار برسند.
- ارقام فارسی و عربی باید همان کلید ارقام لاتین را تولید کنند.
- شماره نامعتبر نباید هویت استاندارد بگیرد.
- query موبایل باید بدون `LIMIT 500` اجرا شود.
- ثبت هم‌زمان PostgreSQL باید advisory lock را پیش از create بگیرد.
- Alembic باید پس از افزودن migration فقط یک head داشته باشد.