Add scenario documentation for importing doctors from IRIMC and managing profile ownership
- Introduced a new document outlining the process for importing a dataset of 160 doctors from the IRIMC system into Clinic Pro. - Defined a new ownership model to handle doctors without a user account, allowing for management by a system owner. - Documented the technical design changes required in the database and API for the import process. - Included detailed steps for the import command, field mappings, and validation rules. - Specified the workflow for claiming profiles by real doctors and the admin approval process.
This commit is contained in:
hamed
@@ -0,0 +1,385 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="fa" dir="rtl">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>سناریو: ایمپورت پزشکان نظام پزشکی و مدیریت مالکیت پروفایل</title>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Vazirmatn:wght@300;400;500;600;700;800&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
:root{
|
||||
--bg:#f7f8fa; --card:#ffffff; --ink:#1f2933; --muted:#5b6673;
|
||||
--line:#e3e8ee; --accent:#0f6fbf; --accent-soft:#eaf3fb; --code:#f2f4f7;
|
||||
}
|
||||
*{box-sizing:border-box}
|
||||
html,body{margin:0;padding:0}
|
||||
body{
|
||||
font-family:'Vazirmatn',system-ui,sans-serif;
|
||||
background:var(--bg); color:var(--ink);
|
||||
direction:rtl; text-align:right;
|
||||
line-height:1.95; font-size:16px; font-weight:400;
|
||||
}
|
||||
.wrap{max-width:900px;margin:0 auto;padding:40px 22px 80px}
|
||||
.card{background:var(--card);border:1px solid var(--line);border-radius:16px;padding:38px 42px;box-shadow:0 1px 3px rgba(16,24,40,.04)}
|
||||
h1{font-weight:800;font-size:1.9rem;line-height:1.5;margin:.2em 0 .6em;border-bottom:3px solid var(--accent);padding-bottom:.4em}
|
||||
h2{font-weight:700;font-size:1.35rem;margin:2em 0 .7em;color:var(--accent);border-right:4px solid var(--accent);padding-right:12px}
|
||||
h3{font-weight:600;font-size:1.1rem;margin:1.5em 0 .5em}
|
||||
p{margin:.7em 0}
|
||||
a{color:var(--accent);text-decoration:none}
|
||||
a:hover{text-decoration:underline}
|
||||
strong{font-weight:700;color:#0b3d5c}
|
||||
blockquote{margin:1.2em 0;padding:.6em 16px;background:var(--accent-soft);border-right:4px solid var(--accent);border-radius:8px;color:#124a6b}
|
||||
blockquote p{margin:.3em 0}
|
||||
ul,ol{padding-right:1.4em;margin:.6em 0}
|
||||
li{margin:.35em 0}
|
||||
hr{border:none;border-top:1px solid var(--line);margin:2em 0}
|
||||
table{border-collapse:collapse;width:100%;margin:1.2em 0;font-size:.94rem}
|
||||
th,td{border:1px solid var(--line);padding:9px 12px;text-align:right;vertical-align:top}
|
||||
th{background:var(--accent-soft);font-weight:700;color:#0b3d5c}
|
||||
tr:nth-child(even) td{background:#fafbfc}
|
||||
code{font-family:'Vazirmatn',ui-monospace,monospace;background:var(--code);padding:2px 6px;border-radius:5px;font-size:.9em;direction:ltr;unicode-bidi:embed}
|
||||
pre{background:#0f1b26;color:#e6edf3;padding:18px 20px;border-radius:12px;overflow-x:auto;direction:ltr;text-align:left;line-height:1.7}
|
||||
pre code{background:transparent;color:inherit;padding:0;font-size:.88rem}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="wrap"><div class="card">
|
||||
<h1 id="_1">سناریو: ایمپورت پزشکان سازمان نظام پزشکی و مدیریت مالکیت پروفایل</h1>
|
||||
<blockquote>
|
||||
<p>نسخه: ۱.۰ — تاریخ: ۱۴۰۵/۰۴/۱۹ (۲۰۲۶-۰۷-۱۰)
|
||||
دامنه: <code>clinicpro</code> (بکاند + پنل ادمین) · <code>nobat724_front</code> (سایت عمومی) · <code>clinic-pro-tauri</code> (اپ دسکتاپ)
|
||||
وضعیت: پیشنویس طراحی برای پیادهسازی</p>
|
||||
</blockquote>
|
||||
<hr />
|
||||
<h2 id="_2">۱. خلاصه اجرایی</h2>
|
||||
<p>یک دیتاست ۱۶۰ نفره از پزشکان از سامانه استعلام اعضای سازمان نظام پزشکی (<code>membersearch.irimc.org</code>) استخراج شده است. هدف، وارد کردن این پزشکان به Clinic Pro است تا در سایت عمومی Nobat724 نمایش داده شوند، <strong>پیش از آنکه پزشک واقعی در سیستم ثبتنام کرده باشد</strong>.</p>
|
||||
<p>مشکل محوری: در مدل دادهی فعلی، هر پزشک (<code>Doctor</code>) بهصورت اجباری و <strong>یکبهیک و یکتا</strong> به یک کاربر (<code>User</code>) متصل است، و هر کاربر نیز الزاماً یک <strong>شماره موبایل یکتا و غیرتهی</strong> دارد. اما رکوردهای سازمان نظام پزشکی فاقد شماره موبایل هستند (<code>mobileNumber: null</code>). بنابراین نه میتوان کاربر ساخت (چون موبایل لازم است) و نه میتوان یک پزشک را بدون کاربر ذخیره کرد.</p>
|
||||
<p>این سند یک مدل «مالکیت پروفایل» (Profile Ownership) طراحی میکند که در آن پزشکان ایمپورتشده در حالت <strong>«بدونمالک» (unclaimed)</strong> ذخیره و مدیریت میشوند، و بعداً از طریق یک فرایند احراز هویتشده در Nobat724 به پزشک واقعی <strong>منتقل (claim/transfer)</strong> میشوند.</p>
|
||||
<hr />
|
||||
<h2 id="_3">۲. مسئله و محدودیتهای سیستم فعلی</h2>
|
||||
<p>پیش از طراحی راهحل، محدودیتهای واقعی کد فعلی مستند میشوند (منبع: <code>src/Doctor/Entity/Doctor.php</code>, <code>src/Auth/Entity/User.php</code>, <code>src/Doctor/Controller/DoctorController.php</code>).</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>محدودیت</th>
|
||||
<th>جزئیات کد فعلی</th>
|
||||
<th>پیامد برای ایمپورت</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>کاربر برای پزشک اجباری است</td>
|
||||
<td><code>Doctor::$user</code> → <code>OneToOne</code>، <code>JoinColumn(nullable: false, onDelete: RESTRICT)</code></td>
|
||||
<td>نمیتوان پزشک بدون کاربر ذخیره کرد.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>رابطه پزشک↔کاربر یکتاست</td>
|
||||
<td><code>UniqueConstraint idx_doctors_user (user_id)</code></td>
|
||||
<td><strong>نمیتوان چند پزشک را به یک کاربر مشترک وصل کرد</strong> — ایدهی «همه به یک کاربر سیستمی» با این قید نقض میشود.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>موبایل کاربر اجباری و یکتاست</td>
|
||||
<td><code>User::$mobileNumber</code> → <code>NOT NULL</code>، <code>UniqueConstraint uniq_mobile</code></td>
|
||||
<td>بدون موبایل نمیتوان <code>User</code> ساخت؛ دادهی نظام پزشکی موبایل ندارد.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ساخت پزشک به کاربر لاگینشده گره خورده</td>
|
||||
<td><code>DoctorController::create()</code> از <code>#[CurrentUser] User $user</code> استفاده میکند و اگر همان کاربر پزشک داشته باشد خطای ۴۰۹ میدهد</td>
|
||||
<td>مسیر فعلی ساخت پزشک برای ایمپورت انبوه مناسب نیست.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>medical_system_code</code> یکتا نیست</td>
|
||||
<td><code>Doctor::$medicalSystemCode</code> → <code>nullable</code>, بدون <code>unique</code></td>
|
||||
<td>برای جلوگیری از ایمپورت تکراری و برای تطبیق هنگام claim، باید کلید طبیعی یکتا شود.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3 id="_4">نتیجهگیری کلیدی طراحی</h3>
|
||||
<p>خواستهی اولیه («همهی پزشکان ایمپورتشده به یک کاربر سیستمی اختصاص یابند») بهدلیل قید یکتای <code>user_id</code> روی جدول <code>doctors</code> <strong>مستقیماً قابل اجرا نیست</strong>. بنابراین یکی از دو مسیر زیر لازم است، و این سند <strong>گزینه A</strong> را توصیه میکند:</p>
|
||||
<ul>
|
||||
<li><strong>گزینه A (توصیهشده): جداسازی «مالکیت» از «کاربر».</strong> ستون <code>Doctor.user</code> اختیاری (<code>nullable</code>) میشود. یک کاربر سیستمی بهنام «مالک سیستمی» (System Owner) صرفاً بهعنوان <strong>مدیرِ منطقیِ</strong> پزشکان بدونمالک عمل میکند (نه از طریق ستون <code>user_id</code>، بلکه از طریق فیلد جدید <code>managed_by</code>). این کار قید یکتا را نقض نمیکند و مدل تمیزتری میسازد.</li>
|
||||
<li><strong>گزینه B (جایگزین کمتغییر): کاربر جانشین (Placeholder User) بهازای هر پزشک.</strong> برای هر پزشک یک <code>User</code> غیرفعال با شناسهی مصنوعی (مثلاً موبایل رزروشدهی <code>IRIMC-<code></code>) ساخته میشود. اسکیمای <code>doctors</code> تقریباً دستنخورده میماند اما جدول <code>users</code> با ۱۶۰ کاربر جعلی شلوغ میشود و هنگام claim باید ادغام (merge) انجام شود.</li>
|
||||
</ul>
|
||||
<p>مقایسه و تصمیم نهایی در بخش ۱۳ آمده است.</p>
|
||||
<hr />
|
||||
<h2 id="ownership-model">۳. مدل مفهومی مالکیت (Ownership Model)</h2>
|
||||
<p>هر پروفایل پزشک یکی از این وضعیتهای مالکیت را دارد:</p>
|
||||
<ul>
|
||||
<li><strong><code>unclaimed</code> (بدونمالک):</strong> ایمپورتشده از نظام پزشکی، هنوز به پزشک واقعی وصل نشده. توسط «مالک سیستمی» مدیریت میشود. در Nobat724 نمایش داده میشود اما قابل ویرایش توسط عموم نیست و نوبتدهی آنلاین آن پیشفرض <strong>غیرفعال</strong> است.</li>
|
||||
<li><strong><code>pending_transfer</code> (در انتظار انتقال):</strong> پزشک واقعی درخواست تصاحب داده و در حال احراز هویت / انتظار تأیید ادمین است.</li>
|
||||
<li><strong><code>claimed</code> (تصاحبشده):</strong> مالکیت به پزشک واقعی منتقل شده؛ پروفایل به کاربر واقعی او متصل است و او کنترل کامل دارد.</li>
|
||||
</ul>
|
||||
<p>منبع پروفایل نیز ثبت میشود:</p>
|
||||
<ul>
|
||||
<li><strong><code>source</code></strong>: <code>irimc</code> (نظام پزشکی) یا <code>manual</code> (ساخت دستی/ثبتنام عادی — رفتار فعلی).</li>
|
||||
<li><strong><code>source_ref</code></strong>: شناسهی یکتای رکورد مبدأ (<code>profile_url</code> id یا <code>medicalSystemCode</code>) برای idempotency و ممیزی.</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="_5">۴. بخش اول — ایمپورت پزشکان نظام پزشکی</h2>
|
||||
<h3 id="_6">۴.۱ کاربر «مالک سیستمی»</h3>
|
||||
<p>یک کاربر ویژه یکبار ساخته میشود (از طریق دستور کنسول، همسبک <code>CreateAdminCommand</code>):</p>
|
||||
<ul>
|
||||
<li>موبایل رزروشده و ثابت، مثلاً <code>0000000000</code> (خارج از فضای شمارههای واقعی ایران، ۱۱ رقمی نامعتبر).</li>
|
||||
<li>نقشها: <code>['ROLE_USER', 'ROLE_ADMIN']</code> یا نقش اختصاصی <code>ROLE_SYSTEM_OWNER</code>.</li>
|
||||
<li><code>status = 0</code> (غیرفعال برای لاگین) تا امکان ورود با آن وجود نداشته باشد.</li>
|
||||
<li><code>real_name = 'مالک سیستمی نوبت۷۲۴'</code>.</li>
|
||||
</ul>
|
||||
<p>این کاربر <strong>صاحب <code>user_id</code> پزشکان نیست</strong> (چون یکتاست)؛ بلکه شناسهاش در ستون جدید <code>Doctor.managed_by</code> قرار میگیرد تا مشخص باشد این پزشکان توسط پلتفرم مدیریت میشوند و بعداً قابل واگذاریاند.</p>
|
||||
<h3 id="doctorsjson">۴.۲ نگاشت فیلدها از <code>doctors.json</code></h3>
|
||||
<p>هر رکورد ورودی به این شکل به موجودیت <code>Doctor</code> نگاشت میشود:</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>فیلد ورودی (JSON)</th>
|
||||
<th>مقصد در <code>Doctor</code></th>
|
||||
<th>توضیح</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>name</code></td>
|
||||
<td><code>name</code></td>
|
||||
<td>مثلاً «دکتر فرخنده حسینی»</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>gender</code> (<code>woman</code>/<code>man</code>)</td>
|
||||
<td><code>gender</code></td>
|
||||
<td>با <code>Doctor::GENDERS</code> سازگار است</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>medicalSystemCode</code></td>
|
||||
<td><code>medical_system_code</code> + <code>source_ref</code></td>
|
||||
<td>کلید طبیعی یکتا برای dedup</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>mobileNumber</code> (<code>null</code>)</td>
|
||||
<td><code>mobile_number</code> = <code>null</code></td>
|
||||
<td>اجازه دارد null بماند</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>degree</code> (<code>general</code>)</td>
|
||||
<td><code>degree</code></td>
|
||||
<td>با <code>Doctor::DEGREES</code> سازگار است</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>info</code></td>
|
||||
<td><code>info</code></td>
|
||||
<td>«دکترای حرفهای پزشکی»</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>specialty_id</code> / <code>specialty_uuid</code></td>
|
||||
<td>رابطه <code>specialties</code></td>
|
||||
<td>تطبیق با جدول <code>specialties</code> (fallback با uuid)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>state_id</code> / <code>state_uuid</code></td>
|
||||
<td>رابطه <code>provinces</code></td>
|
||||
<td>استان محل فعالیت</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>city_id</code> / <code>city_uuid</code></td>
|
||||
<td>رابطه <code>cities</code></td>
|
||||
<td>شهر محل فعالیت</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>images</code> (<code>[]</code>)</td>
|
||||
<td><code>images</code></td>
|
||||
<td>خالی → <code>null</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>socialMedia</code></td>
|
||||
<td><code>social_media</code></td>
|
||||
<td>نگاشت به کلیدهای مجاز</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>profile_url</code> / <code>source_url</code></td>
|
||||
<td>متادیتای ایمپورت</td>
|
||||
<td>برای ممیزی و لینک بازبینی</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>فیلدهای ثابت هنگام ایمپورت: <code>owner_status = 'unclaimed'</code>، <code>source = 'irimc'</code>، <code>managed_by = <systemOwnerId></code>، <code>active_doctor_appointment = false</code> (تا وقتی مالک واقعی برنامهی کاری تعریف کند نوبتدهی روشن نشود).</p>
|
||||
<h3 id="idempotency">۴.۳ قواعد Idempotency و اعتبارسنجی</h3>
|
||||
<ul>
|
||||
<li>کلید یکتای ایمپورت: <code>(source = 'irimc', medical_system_code)</code>. اجرای مجدد ایمپورت رکورد موجود را <strong>بهروزرسانی</strong> میکند نه تکراریسازی.</li>
|
||||
<li>رکوردهای بدون <code>medicalSystemCode</code> رد و در گزارش ایمپورت لاگ میشوند.</li>
|
||||
<li>تطبیق تخصص/استان/شهر ابتدا با <code>*_id</code> و در صورت نبود، با <code>*_uuid</code> انجام میشود؛ عدم تطبیق باعث رد کل رکورد نمیشود بلکه فقط آن رابطه خالی میماند و در گزارش ثبت میشود.</li>
|
||||
<li>خروجی دستور ایمپورت: تعداد ساختهشده / بهروزشده / ردشده + مسیر فایل گزارش.</li>
|
||||
</ul>
|
||||
<h3 id="_7">۴.۴ روش اجرا</h3>
|
||||
<p>دستور کنسول اختصاصی (همسبک <code>SeedDemoDataCommand</code> و <code>SeedCategoriesCommand</code>):</p>
|
||||
<pre><code class="language-bash">ddev exec php bin/console app:doctors:import-irimc var/import/doctors.json --dry-run
|
||||
ddev exec php bin/console app:doctors:import-irimc var/import/doctors.json
|
||||
</code></pre>
|
||||
<p><code>--dry-run</code> فقط گزارش میدهد و چیزی ذخیره نمیکند. ایمپورت درون یک تراکنش دیتابیس و بهصورت دستهای (batch/flush هر ۵۰ رکورد) انجام میشود.</p>
|
||||
<hr />
|
||||
<h2 id="_8">۵. طراحی فنی دیتابیس</h2>
|
||||
<p>تغییرات روی موجودیت <code>Doctor</code> (بههمراه یک migration در <code>migrations/</code>):</p>
|
||||
<pre><code>doctors:
|
||||
user_id INT NULL -- تغییر از NOT NULL به NULL (گزینه A)
|
||||
managed_by INT NULL -- FK به users.id؛ کاربر «مالک سیستمی»
|
||||
owner_status VARCHAR(20) NOT NULL DEFAULT 'claimed'
|
||||
-- unclaimed | pending_transfer | claimed
|
||||
source VARCHAR(20) NOT NULL DEFAULT 'manual' -- irimc | manual
|
||||
source_ref VARCHAR(100) NULL -- شناسه رکورد مبدأ
|
||||
claimed_at INT NULL
|
||||
medical_system_code VARCHAR(25) NULL -- (موجود) + ایندکس یکتای جزئی
|
||||
</code></pre>
|
||||
<p>قیود و ایندکسها:</p>
|
||||
<ul>
|
||||
<li>حذف/تعدیل <code>UniqueConstraint idx_doctors_user</code>: یکتایی فقط باید برای پزشکانِ <strong>دارای کاربر</strong> اعمال شود. چون MariaDB از partial unique index پشتیبانی مستقیم ندارد، یکتایی <code>user_id</code> در سطح اپلیکیشن (هنگام claim) تضمین میشود و ایندکس دیتابیس به <code>INDEX</code> ساده تبدیل میشود.</li>
|
||||
<li>ایندکس یکتای طبیعی: <code>UNIQUE (source, medical_system_code)</code> برای idempotency ایمپورت.</li>
|
||||
<li>ایندکس <code>owner_status</code> برای فیلتر سریع «پزشکان بدونمالک».</li>
|
||||
</ul>
|
||||
<p>سازگاری با دادهی موجود: تمام پزشکان فعلی هنگام migration مقدار <code>owner_status = 'claimed'</code> و <code>source = 'manual'</code> میگیرند تا رفتارشان تغییر نکند.</p>
|
||||
<blockquote>
|
||||
<p>نکته سازگاری: طبق <code>CLAUDE.md</code>، <code>medical_system_code</code> تا الان <code>nullable</code> و بدون یکتایی بوده؛ پیش از افزودن ایندکس یکتا باید دادهی موجود از نظر تکراری بودن پاکسازی شود.</p>
|
||||
</blockquote>
|
||||
<hr />
|
||||
<h2 id="api-clinicpro">۶. طراحی API (بکاند clinicpro)</h2>
|
||||
<p>پاسخها از پوشش <code>BaseController</code> پیروی میکنند: <code>{ success, data }</code> / <code>{ success, errors }</code> / صفحهبندی <code>{ data, meta }</code>. مطابق قانون پروژه، هر تغییر کنترلر باید در <code>docs/api/*</code> هم مستند شود.</p>
|
||||
<h3 id="_9">۶.۱ ایمپورت (داخلی / ادمین)</h3>
|
||||
<p>معمولاً از طریق دستور کنسول انجام میشود؛ در صورت نیاز به تریگر از پنل ادمین:</p>
|
||||
<pre><code>POST /api/v1/admin/doctors/import-irimc [ROLE_ADMIN]
|
||||
body: { source_url?, dry_run?: bool, records: [...] }
|
||||
→ 200 { success, data: { created, updated, skipped, report_url } }
|
||||
</code></pre>
|
||||
<h3 id="_10">۶.۲ فهرست پزشکان بدونمالک</h3>
|
||||
<p>اندپوینت موجود <code>GET /api/v1/doctors</code> با فیلتر جدید <code>owner_status</code> توسعه مییابد تا هم برای پنل ادمین و هم برای صفحهی «تصاحب پروفایل» در Nobat724 قابلاستفاده باشد:</p>
|
||||
<pre><code>GET /api/v1/doctors?owner_status=unclaimed&search=&city_id=&specialty_id=
|
||||
→ 200 { success, data: [...], meta }
|
||||
</code></pre>
|
||||
<h3 id="claim">۶.۳ درخواست تصاحب (Claim) — عمومی و احراز هویتشده</h3>
|
||||
<pre><code>POST /api/v1/doctor/{uuid}/claim [IS_AUTHENTICATED_FULLY]
|
||||
body: { national_code, medical_system_code, activity_time? }
|
||||
قواعد:
|
||||
- پروفایل باید owner_status = 'unclaimed' باشد، وگرنه 409.
|
||||
- medical_system_code ورودی باید با رکورد پزشک مطابقت کند، وگرنه 422.
|
||||
- کاربر لاگینشده (که موبایلش قبلاً با OTP تأیید شده) نباید از قبل پزشکِ دیگری داشته باشد.
|
||||
- رکورد به pending_transfer میرود و یک ClaimRequest ثبت میشود.
|
||||
→ 202 { success, data: { claim_id, status: 'pending_transfer' } }
|
||||
</code></pre>
|
||||
<h3 id="_11">۶.۴ تأیید/رد توسط ادمین و نهاییسازی انتقال</h3>
|
||||
<pre><code>GET /api/v1/admin/doctor-claims?status=pending [ROLE_ADMIN]
|
||||
POST /api/v1/admin/doctor-claims/{claimId}/approve [ROLE_ADMIN]
|
||||
POST /api/v1/admin/doctor-claims/{claimId}/reject [ROLE_ADMIN] { reason }
|
||||
</code></pre>
|
||||
<p>هنگام approve، عملیات انتقال مالکیت (بخش ۷) بهصورت اتمیک اجرا میشود.</p>
|
||||
<blockquote>
|
||||
<p>امکان «انتقال خودکار» (بدون ادمین) نیز قابل تعریف است: اگر <code>national_code</code> کاربر تأییدشده باشد و <code>medical_system_code</code> و نام کاملاً منطبق باشند، سیستم میتواند مستقیماً claim را تأیید کند. تصمیم پیشفرض این سند: <strong>تأیید ادمین اجباری برای فاز اول</strong> (بخش ۱۳).</p>
|
||||
</blockquote>
|
||||
<hr />
|
||||
<h2 id="_12">۷. بخش دوم — مکانیزم انتقال مالکیت</h2>
|
||||
<p>جریان کامل تصاحب پروفایل توسط پزشک واقعی:</p>
|
||||
<ol>
|
||||
<li><strong>کشف:</strong> پزشک در Nobat724 نام خود را میبیند (پروفایل <code>unclaimed</code>) و روی «این پروفایل من است» کلیک میکند.</li>
|
||||
<li><strong>احراز هویت پایه:</strong> اگر لاگین نیست، با موبایل + OTP ثبتنام/ورود میکند. در این مرحله یک <code>User</code> واقعی با موبایل واقعی ساخته میشود (مسیر عادی auth موجود).</li>
|
||||
<li><strong>تطبیق هویت:</strong> فرم تصاحب، <code>national_code</code> و <code>medical_system_code</code> را میگیرد و با رکورد پزشک تطبیق میدهد (<code>POST .../claim</code>). پروفایل به <code>pending_transfer</code> میرود.</li>
|
||||
<li><strong>بازبینی:</strong> ادمین در پنل، درخواست را با <code>profile_url</code> سازمان نظام پزشکی بازبینی و approve/reject میکند.</li>
|
||||
<li><strong>نهاییسازی انتقال (اتمیک):</strong></li>
|
||||
<li><code>Doctor.user</code> = کاربر واقعی پزشک (پر شدن ستونی که تا الان null بود).</li>
|
||||
<li><code>Doctor.managed_by</code> = <code>null</code>؛ <code>owner_status = 'claimed'</code>؛ <code>claimed_at = time()</code>.</li>
|
||||
<li>افزودن <code>ROLE_DOCTOR</code> به کاربر واقعی (همان منطق موجود در <code>DoctorController::create</code>).</li>
|
||||
<li>از این پس ویرایش پروفایل توسط خود پزشک از طریق <code>PATCH /api/v1/doctor/{uuid}</code> مجاز است (چک مالکیت فعلی <code>getUser()->getId() === user</code> اکنون درست کار میکند).</li>
|
||||
<li><strong>اطلاعرسانی:</strong> پیامک/نوتیف تأیید به پزشک (همسبک <code>Sms</code> موجود).</li>
|
||||
</ol>
|
||||
<p>قواعد یکتایی هنگام انتقال: چون یک کاربر واقعی نباید صاحب دو پزشک شود، پیش از اتصال باید بررسی شود که <code>user_id</code> مقصد در جدول <code>doctors</code> تکراری نشود (تضمین در سطح اپلیکیشن، جایگزین قید یکتای حذفشده).</p>
|
||||
<hr />
|
||||
<h2 id="nobat724-nobat724_front">۸. اتصال با Nobat724 (<code>nobat724_front</code>)</h2>
|
||||
<p>مصرفکنندهی API از طریق <code>services/response.js</code> است (که هماکنون <code>getDoctors</code>, <code>postDoctor</code>, ... را دارد). تغییرات لازم:</p>
|
||||
<ul>
|
||||
<li><strong>نمایش پزشکان بدونمالک:</strong> فهرست فعلی پزشکان (<code>api/v1/doctors</code>) بهطور خودکار پزشکان <code>unclaimed</code> را هم شامل میشود؛ در کارت پزشک، بهجای دکمهی «رزرو نوبت»، دکمهی «این پروفایل من است / تکمیل پروفایل» نمایش داده میشود چون <code>active=false</code> است.</li>
|
||||
<li><strong>صفحه/فرم تصاحب:</strong> فراخوانی <code>POST api/v1/doctor/{uuid}/claim</code> پس از ورود با OTP. نگهداری <code>access_token</code>/<code>refresh_token</code> در کوکی (مطابق الگوی فعلی Nobat724).</li>
|
||||
<li><strong>زبان/تقویم:</strong> تمام رشتههای جدید فارسی و تاریخها جلالی (شمسی) بمانند.</li>
|
||||
<li>رعایت قرارداد: تغییر قالب پاسخ در بکاند باید در <code>nobat724_front/services/response.js</code> هم منعکس شود، چون در زمان build خطا نمیدهد.</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="clinic-pro-tauri">۹. اثر بر <code>clinic-pro-tauri</code></h2>
|
||||
<p>اپ دسکتاپ نیز کلاینت همان API است (<code>src/service/response.js</code>) و از CASL برای نقشها استفاده میکند (<code>clinic</code>, <code>doctor</code>, <code>clinic_doctor</code>, <code>secretary</code>).</p>
|
||||
<ul>
|
||||
<li>اگر لیست پزشکان در اپ نمایش داده میشود، باید فیلد <code>owner_status</code> و رفتار <code>active=false</code> را مدیریت کند (پزشک بدونمالک قابل رزرو آنلاین نیست).</li>
|
||||
<li>مرز sync آفلاین/آنلاین این اپ هنوز کامل نگاشت نشده؛ پیش از فرض همترازی، رفتار <code>owner_status</code> در دیتابیس محلی SQLite باید بررسی شود (طبق هشدار <code>AGENTS.md</code>).</li>
|
||||
<li>برای فاز اول، تغییر در Tauri <strong>اختیاری</strong> است؛ فقط در صورتی که این اپ پزشکان <code>unclaimed</code> را نشان دهد لازم میشود.</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="_13">۱۰. جریان کاربری (خلاصهی گامبهگام)</h2>
|
||||
<pre><code>[نظام پزشکی JSON] → دستور ایمپورت → پزشکِ unclaimed (managed_by = System Owner)
|
||||
│
|
||||
▼
|
||||
نمایش در Nobat724 (active=false، بدون نوبت آنلاین)
|
||||
│ پزشک واقعی: «این پروفایل من است»
|
||||
▼
|
||||
ورود با موبایل + OTP → ساخت User واقعی
|
||||
│
|
||||
▼
|
||||
فرم تصاحب (کد ملی + کد نظام پزشکی) → POST /claim → pending_transfer
|
||||
│
|
||||
▼
|
||||
بازبینی ادمین (approve) → انتقال اتمیک:
|
||||
user_id=واقعی، owner_status=claimed، +ROLE_DOCTOR
|
||||
│
|
||||
▼
|
||||
پزشک پروفایل و برنامهی کاری را کامل میکند → active=true → نوبتدهی آنلاین فعال
|
||||
</code></pre>
|
||||
<hr />
|
||||
<h2 id="_14">۱۱. حالات مرزی و قواعد کسبوکار</h2>
|
||||
<ul>
|
||||
<li><strong>درخواست تصاحب همزمان دو نفر برای یک پروفایل:</strong> فقط اولین <code>pending_transfer</code> پذیرفته میشود؛ بقیه با ۴۰۹ رد میشوند تا تعیین تکلیف قبلی روشن شود.</li>
|
||||
<li><strong>کاربری که قبلاً پزشک دارد:</strong> نمیتواند پروفایل دوم را تصاحب کند (قید یکتای منطقی <code>user_id</code>).</li>
|
||||
<li><strong>عدم تطابق کد نظام پزشکی:</strong> رد با ۴۲۲ و بدون تغییر وضعیت.</li>
|
||||
<li><strong>رد توسط ادمین:</strong> پروفایل به <code>unclaimed</code> بازمیگردد و برای تصاحب مجدد آزاد میشود.</li>
|
||||
<li><strong>حذف پزشک بدونمالک:</strong> مجاز برای ادمین (مسیر فعلی <code>DELETE</code>); اما پزشکِ <code>claimed</code> طبق رفتار فعلی محافظت میشود.</li>
|
||||
<li><strong>ایمپورت مجدد یک پزشکِ از قبل claimed:</strong> فیلدهای هویتی بهروز نمیشوند (مالک واقعی اولویت دارد)؛ فقط در گزارش «skipped/claimed» ثبت میشود.</li>
|
||||
<li><strong>نوبتدهی:</strong> تا زمانی که پروفایل <code>unclaimed</code> است، <code>active_doctor_appointment=false</code> و برنامهی کاری وجود ندارد؛ لذا در <code>toListArray</code> مقدار <code>active=false</code> میشود و رزرو ممکن نیست.</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="_15">۱۲. مراحل پیادهسازی (بهترتیب و بهتفکیک ریپو)</h2>
|
||||
<p>مطابق <code>CLAUDE.md</code>: ابتدا بکاند <code>clinicpro</code>، سپس مستندسازی API، سپس کلاینتها.</p>
|
||||
<p><strong>الف) <code>clinicpro</code> (بکاند):</strong>
|
||||
1. افزودن فیلدهای <code>managed_by</code>, <code>owner_status</code>, <code>source</code>, <code>source_ref</code>, <code>claimed_at</code> و nullable کردن <code>user_id</code> در <code>Doctor</code> + migration در <code>migrations/</code>.
|
||||
2. پاکسازی داده و افزودن ایندکس یکتای <code>(source, medical_system_code)</code>.
|
||||
3. دستور کنسول <code>app:doctors:import-irimc</code> (با <code>--dry-run</code>، گزارش، تراکنش).
|
||||
4. دستور/سیدر ساخت کاربر «مالک سیستمی».
|
||||
5. موجودیت/جدول <code>DoctorClaim</code> + اندپوینتهای claim و approve/reject.
|
||||
6. توسعهی فیلتر <code>owner_status</code> در <code>GET /api/v1/doctors</code> و بهروزرسانی چکهای مالکیت.
|
||||
7. بهروزرسانی <code>docs/api/*</code> (طبق قانون استاندارد پروژه) و افزودن این سند به مستندات.</p>
|
||||
<p><strong>ب) <code>nobat724_front</code>:</strong>
|
||||
8. همترازی <code>services/response.js</code> با قالبهای جدید.
|
||||
9. دکمهی «این پروفایل من است» روی کارت پزشکِ <code>unclaimed</code> + صفحهی فرم تصاحب (فارسی، جلالی، RTL).</p>
|
||||
<p><strong>ج) <code>clinic-pro-tauri</code> (در صورت نیاز):</strong>
|
||||
10. مدیریت <code>owner_status</code>/<code>active=false</code> در لیست پزشکان و بررسی مرز sync محلی.</p>
|
||||
<p><strong>د) بازبینی نهایی:</strong>
|
||||
11. تست ایمپورت روی نمونهی ۱۶۰ رکورد، تست جریان claim سرتاسری، و بازسازی کاربران تست (<code>ddev exec php create_test_users.php</code>).</p>
|
||||
<hr />
|
||||
<h2 id="_16">۱۳. تصمیمات باز و ریسکها</h2>
|
||||
<ul>
|
||||
<li><strong>گزینه A در برابر B:</strong> این سند گزینه A (nullable کردن <code>user_id</code> + <code>managed_by</code>) را توصیه میکند چون جدول <code>users</code> را با کاربران جعلی آلوده نمیکند و مدل مالکیت را صریح میسازد. هزینهاش: از دست رفتن قید یکتای دیتابیسی روی <code>user_id</code> و انتقال آن به سطح اپلیکیشن.</li>
|
||||
<li><strong>تأیید ادمین در برابر انتقال خودکار:</strong> پیشفرض فاز اول تأیید دستی ادمین است (امنتر برای هویت پزشک). خودکارسازی بعداً با اتکا به تأیید کد ملی افزوده میشود.</li>
|
||||
<li><strong>کیفیت دادهی نظام پزشکی:</strong> برخی رکوردها ممکن است فاقد <code>specialty_id</code>/<code>city_id</code> معتبر باشند؛ گزارش ایمپورت باید اینها را شفاف کند.</li>
|
||||
<li><strong>حریم خصوصی:</strong> نمایش عمومی نام و کد نظام پزشکی پیش از رضایت پزشک، ملاحظهی حقوقی دارد و باید با سیاست پلتفرم بررسی شود.</li>
|
||||
<li><strong>یکتایی موبایل مالک سیستمی:</strong> مقدار رزروشده باید تضمیناً هرگز با موبایل واقعی کاربر تداخل نکند.</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="_17">۱۴. مرجع نمونهی داده</h2>
|
||||
<p>نمونهی یک رکورد ورودی از <code>doctors.json</code> (۱۶۰ رکورد، همگی <code>mobileNumber: null</code>):</p>
|
||||
<pre><code class="language-json">{
|
||||
"name": "دکتر فرخنده حسینی",
|
||||
"gender": "woman",
|
||||
"medicalSystemCode": "145657",
|
||||
"mobileNumber": null,
|
||||
"degree": "general",
|
||||
"info": "دکترای حرفهای پزشکی",
|
||||
"specialty_id": 1,
|
||||
"specialty_name": "پزشک عمومی",
|
||||
"state_id": 23,
|
||||
"state_name": "کهگیلویه و بویراحمد",
|
||||
"city_id": 123,
|
||||
"city_name": "یاسوج",
|
||||
"profile_url": "https://membersearch.irimc.org/member/profile?id=02058131-...",
|
||||
"source_url": "https://membersearch.irimc.org"
|
||||
}
|
||||
</code></pre>
|
||||
</div></div>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user