fix api contact search

docs/PHONE_CONTACTS_API.md

@@ -44,13 +44,14 @@ curl --fail-with-body --get 'https://crm.example.com/api/phone-contacts' \
 
 ## پاسخ موفق
 
-ریشهٔ پاسخ همیشه یک شیء JSON با کلید `contacts` است. هر عضو این آرایه یک نام و آرایهٔ شماره‌ها دارد:
+ریشهٔ پاسخ همیشه یک شیء JSON با کلید `contacts` است. هر عضو این آرایه نام، شمارهٔ همراه و آرایهٔ شماره‌ها را دارد:
 
 ```json
 {
   "contacts": [
     {
       "name": "علی رضایی",
+      "mobile": "09123456789",
       "phones": [
         {"type": "همراه", "number": "09123456789"}
       ]
@@ -63,11 +64,12 @@ curl --fail-with-body --get 'https://crm.example.com/api/phone-contacts' \
 | --- | --- | --- |
 | `contacts` | آرایه | حداکثر ۵۰ مخاطب، یا آرایهٔ خالی. |
 | `contacts[].name` | رشته | نام نمایشی غیرخالی؛ فاصلهٔ دو سر حذف شده و حداکثر ۱۲۰ نویسه است. |
-| `contacts[].phones` | آرایه | در ساختار کنونی پروژه، یک شمارهٔ همراه معتبر برای هر مخاطب. |
-| `contacts[].phones[].type` | رشته | برای شمارهٔ موجود، مقدار `همراه`. |
-| `contacts[].phones[].number` | رشته | شمارهٔ قابل شماره‌گیری، معمولاً در قالب محلی `09...`؛ تبدیل خودکار آن به `+98...` انجام نمی‌شود. |
+| `contacts[].mobile` | رشته | همان مقدار `phones[].number`، برای مصرف‌کننده‌ای که فیلد مستقیم شماره را می‌خواهد. نام این فیلد برای سازگاری حفظ شده و ممکن است مقدار آن تلفن ثابت باشد. |
+| `contacts[].phones` | آرایه | در ساختار کنونی پروژه، یک شمارهٔ ثبت‌شدهٔ معتبر برای هر مخاطب. |
+| `contacts[].phones[].type` | رشته | برای همراه ایرانی `همراه` و برای شمارهٔ دیگر `تلفن`. |
+| `contacts[].phones[].number` | رشته | شمارهٔ قابل شماره‌گیری؛ شمارهٔ ایرانی با `0` محلی برگردانده می‌شود، مانند `0913...` یا `021...`. |
 
-شماره پیش از ارسال به متن تبدیل می‌شود؛ فاصله، پرانتز، نقطه و خط تیره حذف می‌شوند و رقم‌های فارسی و عربی به رقم لاتین تبدیل می‌شوند. شمارهٔ نهایی باید حداکثر ۶۴ نویسه و فقط شامل رقم، `+`، `*` یا `#` باشد. مخاطب بدون نام یا شمارهٔ معتبر در پاسخ نمی‌آید. چون دیتابیس فعلی برای این خروجی شمارهٔ دفتر مستقلی ندارد، نمونهٔ بالا فقط شمارهٔ همراه را نشان می‌دهد؛ هیچ شمارهٔ فرضی تولید نمی‌شود. شناسهٔ داخلی مخاطب نیز در پاسخ فرستاده نمی‌شود.
+شماره پیش از ارسال به متن تبدیل می‌شود؛ فاصله، پرانتز، نقطه و خط تیره حذف می‌شوند و رقم‌های فارسی و عربی به رقم لاتین تبدیل می‌شوند. شمارهٔ نهایی باید حداکثر ۶۴ نویسه و فقط شامل رقم، `+`، `*` یا `#` باشد. مخاطب بدون نام یا شمارهٔ معتبر در پاسخ نمی‌آید. چون دیتابیس فعلی فیلد مستقل برای تلفن ثابت ندارد، هیچ شمارهٔ فرضی تولید نمی‌شود. شناسهٔ داخلی مخاطب نیز در پاسخ فرستاده نمی‌شود.
 
 محدودیت ۵۰ مخاطب، نام ۱۲۰ نویسه‌ای و یک شمارهٔ حداکثر ۶۴ نویسه‌ای برای هر مخاطب، پاسخ را بسیار پایین‌تر از سقف پردازش ۱ MiB در Phone نگه می‌دارد.
 
@@ -89,7 +91,11 @@ Cache-Control: no-store
 
 نام نمایشی به این ترتیب انتخاب می‌شود: نام و نام خانوادگی پروفایل، سپس نام و نام خانوادگی حساب، سپس نام سازمان پروفایل. خروجی نام به ۱۲۰ نویسه محدود می‌شود.
 
-جست‌وجو در نام، نام خانوادگی و نام سازمان پروفایل، نام و نام خانوادگی حساب، و شمارهٔ ذخیره‌شدهٔ حساب انجام می‌شود. برای جست‌وجوی چندواژه‌ای، **هر واژه** باید دست‌کم در یکی از این فیلدها پیدا شود. جست‌وجو نسبت به بزرگی حروف لاتین حساس نیست؛ شکل عربی «ي/ك» در متن ورودی به «ی/ک» تبدیل می‌شود. نتیجه‌هایی که یک فیلدشان دقیقاً با کل متن جست‌وجو برابر است، اول می‌آیند؛ سپس نتیجه‌هایی که فیلدی با آن متن شروع می‌شود و بعد سایر تطبیق‌ها. در هر گروه، شناسهٔ داخلی ترتیب را تعیین می‌کند.
+اگر `search` شماره باشد، شکل‌های محلی با `0`، بین‌المللی با `+98` یا `0098`، و شکل ۱۰ رقمی بدون پیشوند برای شماره‌های ایرانی به یک قالب مقایسه تبدیل می‌شوند. این قاعده به `912` یا هیچ پیش‌شمارهٔ موبایلی محدود نیست؛ برای نمونه `02112345678`، `+982112345678` و `00982112345678` نیز معادل‌اند. رقم‌های فارسی/عربی و جداکننده‌هایی مانند فاصله و خط تیره پذیرفته می‌شوند. تطبیق با مقدار ذخیره‌شده **دقیق** است و شمارهٔ ایرانی در پاسخ با `0` محلی برمی‌گردد.
+
+این API فقط شماره‌ای را می‌تواند پیدا کند که در دادهٔ موجود حساب مخاطب ذخیره شده باشد. مدل فعلی `User.mobile` هنگام ثبت معمول، شمارهٔ همراه ایرانی را می‌پذیرد و فیلد جداگانه‌ای برای خط ثابت ندارد؛ بنابراین جست‌وجوی `021...` فقط برای داده‌ای نتیجه می‌دهد که چنین شماره‌ای از قبل در آن موجود باشد. مدل مخاطب و فرم ثبت آن برای این قابلیت تغییر نکرده‌اند.
+
+برای جست‌وجوی متنی، نام، نام خانوادگی و نام سازمان پروفایل و نام و نام خانوادگی حساب بررسی می‌شوند. برای جست‌وجوی چندواژه‌ای، **هر واژه** باید دست‌کم در یکی از این فیلدها پیدا شود. جست‌وجو نسبت به بزرگی حروف لاتین حساس نیست؛ شکل عربی «ي/ك» در متن ورودی به «ی/ک» تبدیل می‌شود. نتیجه‌هایی که یک فیلدشان دقیقاً با کل متن جست‌وجو برابر است، اول می‌آیند؛ سپس نتیجه‌هایی که فیلدی با آن متن شروع می‌شود و بعد سایر تطبیق‌ها. در هر گروه، شناسهٔ داخلی ترتیب را تعیین می‌کند.
 
 `limit` سقف تعداد رکوردهای بررسی‌شده برای خروجی را تعیین می‌کند. اگر در میان آن‌ها رکوردی هنگام ساخت پاسخ به علت نام یا شمارهٔ نامعتبر کنار گذاشته شود، ممکن است تعداد نهایی کمتر از `limit` باشد. API صفحه‌بندی یا پارامتر `page` ندارد؛ Phone باید نتایج مورد نیاز را از همین پاسخ اول دریافت کند.