docs: migration map §10.9 — order expert credit and the owner's rulings

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-08 10:40:22 +03:30
parent 38ce3d2488
commit 53b61ae80d
1 changed files with 49 additions and 0 deletions
@@ -1692,6 +1692,55 @@ D13 و §۷.۲)، تاریخچه‌ی وضعیت سفارش (`order_activity`)،

 ---

+## ۱۰.۹ — «میزان فروش» و کارشناسِ هر سفارش (۲۰۲۶-۱۰-۰۸)
+
+**مشکل:** کارفرما در مقایسه‌ی چشمی دید که «میزان فروش» چند کارشناس با سیستم
+قدیم فرق دارد (مثلاً موسوی کیانی و ملاطایفه). دو علت داشت:
+
+۱. سیستم جدید سفارش‌های **خود** کارشناس را نمی‌شمرد. قدیم می‌شمرد:
+   `updateGramSell`: `customer_id = X OR reagent_id = X`.
+۲. سیستم جدید هر سفارش را به کارشناسِ **فعلیِ** مشتری نسبت می‌داد. قدیم آن را
+   به کارشناسِ **زمان ثبت** سفارش (`orders.reagent_id`) نسبت می‌داد. در
+   `ApiMobileController.php:601` این مقدار یک‌بار نوشته می‌شود و دیگر عوض نمی‌شود.
+
+**حکم کارفرما:** رفتار قدیم دقیقاً حفظ شود. هر سفارش کارشناسِ خودش را در لحظه‌ی
+ثبت نگه دارد، تا با جابه‌جایی بعدی مشتری، آمار فروش و کمیسیونِ گذشته عوض نشود.
+«هیچ دیتایی نباید مغایرت داشته باشد».
+
+**پیاده‌سازی:**
+- **پایگاه داده:** مایگریشن `20261008120000_order_sales_agent` که فقط افزایشی است.
+  - `Order.salesAgentId` برای کارشناس سفارش.
+  - `Order.referrerCustomerId` فقط برای تاریخچه: یک مشتری غیرکارشناس، ۱۷ سفارش
+    سال ۲۰۲۲. قدیم آن‌ها را در «میزان فروش» همان مشتری می‌شمرد.
+- **ثبت سفارش:** کارشناسِ همان لحظه‌ی مشتری را ذخیره می‌کند.
+- **ابزار انتقال:** `orders.reagent_id` را عیناً می‌آورد.
+- **محاسبه:** `agent-orders.ts` در هر چهار جا (لیست، جزئیات، داشبورد، اپ کارشناس).
+- **صفحه‌ی مشتری:** «میزان فروش» به آن اضافه شد؛ در پورت جا افتاده بود.
+- **فهرست سفارش‌های زیرمجموعه** در اپ کارشناس هم طبق همین قانون است
+  (`getChildOrder`).
+- **مدیرهایی که قبلاً کارشناس بودند:** پروفایل کارشناسی‌شان نگه داشته شد تا
+  سفارش‌های خودشان به آن‌ها وصل بماند. نقش و دسترسی‌شان تغییری نکرد.
+
+**نتیجه (`reconcile-sales`، روی نسخه‌ی آزمایشی):**
+- **فروش:** ۱٬۵۵۷ از ۱٬۵۵۸ نفر دقیقاً برابر فرمول خود سیستم قدیم است. ردیف‌های
+  تکراریِ ادغام‌شده با هم مقایسه شدند.
+- **بدهی:** همه‌ی ۱٬۵۰۳ نفر بدون تغییر ماندند.
+
+**دو مورد که کارفرما تأیید کرد (۲۰۲۶-۱۰-۰۸، «درستن»):**
+- **عدد کهنه در صفحه‌ی قدیم (۹ نفر):** صفحه‌ی قدیم عدد ذخیره‌شده‌ای را نشان
+  می‌دهد که فقط در بعضی رویدادها دوباره حساب می‌شود.
+  - نفرات: #62، #66، #622، #596، #597، #1138، #1198، #1418، #1579.
+  - سیستم جدید عددِ فرمولِ خود سیستم قدیم را نشان می‌دهد. **همین درست است.**
+- **۱۵٫۲۵۵ گرم برای #413:** سفارش #666 مال حساب آزمایشی «تست» است که بدون
+  موبایل واقعی است و منتقل نمی‌شود. #413 الان مدیر است و در هیچ صفحه‌ای این عدد
+  را نمی‌بیند. **کنار گذاشتن آن پذیرفته شد.**
+
+**هم‌زمان در همین تغییر (بدون اثر روی داده):**
+- تاریخ ثبت در همه‌ی جدول‌های پنل شمسی شد، به شکل `1405/5/3-16:02`.
+- «وضعیت ثبت سفارش» دوباره برچسب سبز/قرمزِ «فعال/عدم سفارش» را نشان می‌دهد.
+
+---
+
 ## ۱۱. جمع‌بندی — کارهای لازم قبل از نوشتن ابزار

 ### 🔴 مسدودکننده (بدون این‌ها ابزار در میانه می‌شکند یا داده خراب می‌کند)