# نقشه راه اجرایی یکپارچه — ANBT Battery Shop Backend
### نسخه Agent-Ready — قابل اجرا بدون تصمیم‌گیری اضافه

**منبع:** ترکیب (۱) گزارش ارزیابی معماری PDF نسخه ۱.۰ (۹ شهریور ۱۴۰۵)، (۲) راستی‌آزمایی مستقل کد در تاریخ تهیه این سند، (۳) دو نیازمندی کسب‌وکاری قبلاً مشخص‌شده (قیمت فرسودهٔ اختصاصی به‌تفکیک برند، ویرایش دستی قیمت عمده قبل از فاکتور).
**دامنه:** `Backend/` (PHP 8.1، بدون فریمورک) + `lib/admin/` (فلاتر ادمین).
**مخاطب این سند:** یک ایجنت کدنویسی (یا توسعه‌دهنده) که باید بدون تصمیم طراحی اضافه، صرفاً TASKها را به ترتیب اجرا کند.

---

## بخش ۰ — پروتکل اجرا برای ایجنت (must-read قبل از شروع)

### ۰.۱ قوانین سراسری
1. **ترتیب اجباری است.** TASKها باید به ترتیب شناسه (T-000 → T-A0x → T-B0x → T-C0x → T-D0x → T-E0x → [دروازه خروج فاز بحرانی] → T-F0x → T-G0x) اجرا شوند مگر جایی که صراحتاً «قابل اجرای موازی با T-xxx» نوشته شده باشد.
2. **هر TASK روی شاخهٔ خودش.** نام‌گذاری: `git checkout -b task/<ID>-<slug>` از روی آخرین `main` سبز. مثال: `task/T-B03-order-repository-consolidation`.
3. **پیام کامیت.** فرمت اجباری:
   ```
   [<ID>] <خلاصه یک‌خطی به فارسی>

   - <ریز تغییر ۱>
   - <ریز تغییر ۲>

   Refs: <شمارهٔ بخش گزارش معماری مرتبط، در صورت وجود>
   ```
4. **تعریف «Done» برای هر TASK (چک‌لیست ثابت، برای همهٔ TASKها یکسان است مگر استثنای صریح):**
   - [ ] کد دقیقاً مطابق دستور TASK نوشته شده (نه کمتر، نه «بهبود» اضافه خارج از اسکوپ).
   - [ ] تمام تست‌های ذکرشده در همان TASK نوشته و پاس شده‌اند.
   - [ ] `composer quality` (=`lint` + `stan` + `test:arch`) بدون خطای جدید سبز است.
   - [ ] `composer test:unit` و `composer test:integration` سبزند (اگر TASK یک ماژول دیتابیسی را لمس کرده).
   - [ ] اگر فایلی حذف شد، با `grep -rn "<ClassName>" src/ tests/` تأیید شود که هیچ رفرنس باقی‌مانده‌ای نیست.
   - [ ] کامیت با فرمت بخش ۰.۱.۳ ثبت شده.
5. **اگر تستی شکست خورد:** ایجنت حق ندارد تست را نرم‌تر یا skip کند تا سبز شود. باید یا کد را اصلاح کند یا (فقط اگر انتظار رفتار قبلی اشتباه بوده) اسمبلی/assertion تست را با توضیح در کامیت تغییر دهد.
6. **بدون migration جدید برای داده (نه اسکیما):** ستون‌ها و جدول‌های لازم برای این نقشه راه از قبل در دیتابیس وجود دارند (تأیید شد). هیچ TASKی در این سند نیاز به `ALTER TABLE` ندارد مگر صراحتاً ذکر شود. تغییرات «داده» (مثل افزودن یک ردیف permission) با یک SQL ساده مستقیم روی دیتابیس اعمال می‌شوند، نه با ساخت فایل migration تازه (چون سیستم فعلی Phinx فقط یک migration پایه (`SchemaBaseline`) دارد و باقی کنترل نسخهٔ اسکیما از طریق `database/ANBT_SCHEMA_REFERENCE.sql` + ابزار drift انجام می‌شود — نساختن migration جدید برای داده، عمدی و صحیح است).
7. **دستورهای تأیید سراسری (بعد از هر TASK اجرا شوند):**
   ```bash
   composer lint
   composer stan
   composer test:arch
   composer test:unit
   composer test:integration
   php tools/schema-drift.php          # فقط اگر TASK ستون/جدول را لمس کرده
   php tools/openapi-check.php         # فقط اگر TASK اندپوینت جدید/تغییریافته دارد
   ```

### ۰.۲ الگوهای مرجع (Reference Patterns) — همیشه به این‌ها ارجاع داده می‌شود، حفظشان کنید
- **الگوی صحیح قفل موجودی:** `src/Common/Repository/InventoryRepository.php::adjustStock()` (خط ۳۱-۵۴) — `SELECT ... FOR UPDATE` + گارد منفی + `UPDATE`.
- **الگوی صحیح تراکنش+idempotency پرداخت:** `src/Payment/PaymentService.php::confirmCodPayment()` (خط ۳۱۱-۳۷۴) — چک `already_completed` قبل از هر نوشتار + `$this->app->db()->transaction(function () {...})` دور هر سه نوشتار.
- **الگوی صحیح حل نرخ برند-محور:** `src/Common/Service/BrandRateService.php::getUsedBatteryRate(int $brandId, ?int $productId)` — هرگز با `$brandId = 0` صدا زده نشود مگر عمداً برای «فقط سراسری».
- **قرارداد Repository:** طبق کامنت خودِ `InventoryRepository.php` خط ۱۰-۱۱: *«Repositories do NOT manage transactions – callers must wrap operations in a transaction when needed.»* — این قانون در همهٔ TASKهای زیر رعایت می‌شود.

---

## بخش ۱ — چک‌لیست کلی (Master Checklist)

| # | ID | عنوان | فایل(های) اصلی | وابسته به |
|---|---|---|---|---|
| 1 | T-000 | آماده‌سازی محیط و خط پایه | — | — |
| 2 | T-A01 | افزودن permission «ویرایش دستی قیمت فاکتور» | دیتابیس (داده) + `config/permissions.php` | T-000 |
| 3 | T-A02 | کاهش TTL توکن دسترسی JWT | `.env`/`config`, `src/Auth/JwtService.php` | T-000 |
| 4 | T-A03 | کلید محدودساز نرخ → IP-محور | `src/Core/Middleware/RateLimitMiddleware.php` | T-000 |
| 5 | T-A04 | عبور ۴۰۴/۴۰۵ از میدلور سراسری | `src/Core/Router.php` | T-000 |
| 6 | T-B01 | افزودن `allowNegative` به `adjustStock` | `src/Common/Repository/InventoryRepository.php` | T-000 |
| 7 | T-B02 | تحکیم `OrderRepository.php` (فرسودهٔ برند-محور + موجودی اتمیک + شمارهٔ سفارش) | `src/Order/OrderRepository.php` | T-B01 |
| 8 | T-B03 | تحکیم `OrderCommandService.php` (موجودی اتمیک + ردگیری قیمت + override مجوزدار + فرسودهٔ برند-محور) | `src/Order/Service/OrderCommandService.php` | T-A01, T-B01 |
| 9 | T-B04 | اتصال مجوز override به `AdminOrderController` | `src/Admin/AdminOrderController.php` | T-A01, T-B03 |
| 10 | T-B05 | رفع سبد خرید (Cart) — نرخ فرسودهٔ per-item | `src/Cart/CartRepository.php`, `src/Cart/CartValidationService.php` | T-000 |
| 11 | T-B06 | رفع دریافت باتری فرسوده — نرخ برند-محور | `src/UsedBattery/UsedBatteryControllerHandler.php`, `.../Repository/UsedBatteryControllerRepository.php` | T-000 |
| 12 | T-B07 | تراکنشی + idempotent کردن تأیید پرداخت آنلاین | `src/Payment/PaymentService.php` | T-000 |
| 13 | T-B08 | یکپارچه‌سازی لغو سفارش (مسیر مشتری → OrderStatusService) | `src/Order/OrderRepository.php`, `src/Order/Service/OrderStatusService.php`, `src/Order/OrderController*.php` | T-B02 |
| 14 | T-C01 | فرانت: فیلد «فرسوده» در صفحهٔ قیمت‌گذاری برند | `lib/admin/screens/brand_pricing_screen.dart` | T-A01 |
| 15 | T-C02 | فرانت: نرخ فرسودهٔ per-brand + شفافیت override در فروش عمده | `lib/admin/screens/wholesale_detail_screen.dart` | T-B03, T-B04 |
| 16 | T-D01 | اتمیک‌سازی شمارندهٔ تلاش OTP | `src/Auth/OtpService.php` | T-000 |
| 17 | T-D02 | حذف کد مرده (Accounting/AuthRepository/CorrelationIdMiddleware/…) | چند فایل | T-000 |
| 18 | T-D03 | هم‌ترازی مستندات و گیت‌ها (README، عدد ۱۸۳، php-swagger) | `README.md`, `tools/openapi-check.php`, `tests/Architecture/OpenApiContractTest.php`, `composer.json` | T-000 |
| 19 | T-E01 | تست همزمانی موجودی | `tests/Integration/...` | T-B01,B02,B03 |
| 20 | T-E02 | تست تراکنشی/idempotent پرداخت | `tests/Integration/...` | T-B07 |
| 21 | T-E03 | تست نرخ برند-محور فرسوده (سبد/سفارش/دریافت) | `tests/Unit`, `tests/Integration` | T-B02,B05,B06 |
| 22 | T-E04 | تست override قیمت + ردگیری provenance | `tests/Integration/...` | T-B03,B04 |
| — | **GATE-1** | **دروازه خروج فاز بحرانی** — قبل از فاز ساختاری اجرا شود | — | همهٔ بالا |
| 23 | T-F01 تا T-F08 | همراستاسازی ساختاری (فاز ۲ گزارش) | متعدد | GATE-1 |
| 24 | T-G01 تا T-G06 | ارتقای سیستماتیک (فاز ۳ گزارش) | متعدد | T-F* |


---

## بخش ۲ — فاز صفر: آماده‌سازی

### T-000 — آماده‌سازی محیط و خط پایه
**هدف:** اطمینان از سبز بودن baseline قبل از هر تغییری، و ثبت متریک‌های فعلی برای مقایسهٔ بعد از هر فاز.

**گام‌ها:**
1. `git checkout main && git pull`
2. `composer install`
3. اجرای کامل تست‌ها و ذخیرهٔ خروجی به‌عنوان baseline:
   ```bash
   composer quality > /tmp/baseline_quality.log 2>&1; echo "exit=$?" >> /tmp/baseline_quality.log
   composer test:unit > /tmp/baseline_unit.log 2>&1
   composer test:integration > /tmp/baseline_integration.log 2>&1
   ```
4. اگر baseline از قبل قرمز است (تست‌های موجود شکست می‌خورند)، **متوقف شوید** و ابتدا علت را در یک TASK مجزا (خارج از این نقشه راه) رفع کنید — این نقشه راه فرض می‌کند baseline سبز است.
5. ثبت عدد پوشش فعلی: `grep -o 'line-rate="[0-9.]*"' coverage.xml | head -1`
6. ایجاد فایل `docs/arch/ROADMAP_EXECUTION_LOG.md` (جدید) با محتوای اولیه:
   ```markdown
   # لاگ اجرای نقشه راه معماری
   | تاریخ | TASK | نتیجه | یادداشت |
   |---|---|---|---|
   | <امروز> | T-000 | ✅ | baseline ثبت شد — پوشش: <عدد> |
   ```
   بعد از هر TASK، یک ردیف به همین جدول اضافه کنید (این جایگزین «حس تیم» با یک رکورد ماشینی می‌شود — دقیقاً توصیهٔ بخش ۱۴ گزارش ارزیابی).

**Definition of Done:** فایل لاگ ساخته شده، baseline سبز تأیید شده، کامیت با پیام `[T-000] ثبت خط پایه اجرای نقشه راه`.

---

## بخش ۳ — فاز یک: پایه‌های داده/پیکربندی (Group A)

### T-A01 — افزودن مجوز اختصاصی «ویرایش دستی قیمت فاکتور»
**چرا:** در حال حاضر override دستی `unit_price` (که در T-B03/T-B04 مکانیزم اجرایی‌اش کامل می‌شود) پشت مجوز عمومی `orders.edit` است. طبق درخواست صریح («برای مدیر»)، باید یک مجوز مجزا و قابل‌تخصیص وجود داشته باشد.

**گام ۱ — درج ردیف در جدول `permissions`:**
این یک تغییر **داده** است نه اسکیما؛ نیازی به migration نیست. عبارت زیر را مستقیماً روی دیتابیس (تمام محیط‌های development/testing/production) اجرا کنید. `sort_order` بعد از آخرین مقدار گروه `orders` (که `13` است، متعلق به `orders.cancel`) قرار می‌گیرد:
```sql
INSERT INTO `permissions` (`code`, `name`, `group_name`, `description`, `sort_order`)
VALUES ('orders.price_override', 'ویرایش دستی قیمت فاکتور', 'orders',
        'اجازهٔ نادیده‌گرفتن قیمت محاسبه‌شدهٔ سیستم (خرده/عمده/برند) هنگام ثبت سفارش دستی', 14);
```
این دستور را در یک اسکریپت یک‌باره در `database/one-off/2026-09-add-price-override-permission.sql` هم ذخیره کنید (فقط برای ردیابی تاریخی — این فایل هرگز به‌صورت خودکار اجرا نمی‌شود، صرفاً مستندسازی است).

**گام ۲ — ثبت اندپوینت‌های تحت پوشش این مجوز در `config/permissions.php`:**
فایل را باز کنید، الگوی موجود برای `orders.edit` را پیدا کنید (`grep -n "orders.edit" config/permissions.php`). به‌جای اضافه‌کردن یک route جدید (چون مسیر `POST /admin/orders` عوض نمی‌شود)، این مجوز به‌صورت **درون‌کنترلری** (نه سطح route) چک می‌شود — پس در این فایل چیزی برای route جدید ثبت نمی‌کنید؛ فقط این خط کامنت را بالای map مربوط به `orders.edit` اضافه کنید تا برای توسعه‌دهندهٔ بعدی مستند بماند:
```php
// NOTE: 'orders.price_override' یک مجوز درون‌کنترلری است (نه route-level).
// در AdminOrderController::store() چک می‌شود — نگاه کنید به T-B04 در نقشه راه معماری.
```

**گام ۳ — تخصیص به کاربر مدیر:**
```sql
INSERT INTO admin_permissions (admin_id, permission_id)
SELECT <ADMIN_ID_MدDIR>, id FROM permissions WHERE code = 'orders.price_override';
```
(`<ADMIN_ID_MDIR>` باید توسط عملیات/DBA با شناسهٔ واقعی کاربر مدیر جایگزین شود — این تنها نقطه‌ای در کل نقشه راه است که به یک ورودی انسانی نیاز دارد؛ اگر ایجنت این را به‌صورت خودکار اجرا می‌کند و مقدار مشخص نیست، این گام را skip کند و در لاگ اجرا با برچسب `[MANUAL]` یادداشت بگذارد.)

**تست:** در `tests/Integration/Admin/` تستی بنویسید که فرض می‌کند این permission وجود دارد:
```php
public function testPriceOverridePermissionExists(): void
{
    $row = $this->db->fetchOne("SELECT id FROM permissions WHERE code = 'orders.price_override'");
    $this->assertNotNull($row, 'Permission orders.price_override باید در seed تست هم وجود داشته باشد');
}
```
اگر دیتابیس تست از یک seed/فیکسچر جدا استفاده می‌کند (بررسی کنید `tests/bootstrap.php` یا معادل)، همان INSERT گام ۱ را به فیکسچر تست هم اضافه کنید.

**Definition of Done:** ردیف در دیتابیس (dev + test) موجود است، تست بالا سبز است، کامیت `[T-A01] افزودن مجوز orders.price_override`.

---

### T-A02 — کاهش TTL توکن دسترسی JWT
**شاهد دقیق:** `src/Auth/JwtService.php` خط ۴۶: `'access_ttl' => $app->config('jwt.access_token_ttl', 604800),` (پیش‌فرض ۷ روز).

**گام‌ها:**
1. مقدار پیش‌فرض کد را از `604800` به `1800` (۳۰ دقیقه) تغییر دهید — این عدد پیش‌فرض فقط زمانی اعمال می‌شود که `jwt.access_token_ttl` در پیکربندی/`.env` ست نشده باشد:
   ```php
   'access_ttl'  => $app->config('jwt.access_token_ttl', 1800),
   ```
2. اگر فایل `.env.example` وجود دارد، کلید `JWT_ACCESS_TOKEN_TTL=1800` را در آن (یا اضافه کنید) با کامنت `# ثانیه؛ پیش‌فرض ۳۰ دقیقه — Refresh Token چرخش کامل دارد`.
3. **مهم:** پیش از merge، بررسی کنید فرانت (فلاتر) مکانیزم `refresh` خودکار روی خطای ۴۰۱ دارد (جستجو کنید `grep -rn "401\|refreshToken\|refresh_token" lib/` در هر دو ریشهٔ فرانت). اگر مکانیزم refresh خودکار وجود ندارد، این TASK را روی مقدار محافظه‌کارانه‌تر `3600` (۱ ساعت) تنظیم کنید و در لاگ اجرا دلیل را یادداشت بگذارید — این تنها تصمیم عددی این سند است که به شرط بیرونی (رفتار فرانت) وابسته است؛ در نبود قطعیت، عدد محافظه‌کارانه‌تر (۳۶۰۰) را انتخاب کنید، نه ریسک‌پذیرتر.

**تست:** `tests/Unit/Auth/JwtServiceTest.php` (اگر وجود ندارد بسازید) — assert کنید توکن صادرشده با پیکربندی پیش‌فرض، `exp - iat` را بین ۱۷۰۰ تا ۱۹۰۰ ثانیه (یا بازهٔ متناظر با عدد نهایی انتخابی) قرار می‌دهد.

**Definition of Done:** مقدار تغییر کرد، تست جدید سبز است، `composer test:integration` (که مسیرهای Auth را پوشش می‌دهد) سبز است، کامیت `[T-A02] کاهش TTL توکن دسترسی JWT از ۷ روز به <عدد نهایی>`.

---

### T-A03 — کلید محدودساز نرخ → IP-محور (نه مسیر-محور)
**شاهد دقیق:** `src/Core/Middleware/RateLimitMiddleware.php` خط ۴۹-۵۰:
```php
$clientIp = $request->ip();
$key      = "rl:{$clientIp}:{$path}";
```
مشکل: مهاجم با تنوع‌دادن مسیر (query string متفاوت، یا مسیرهای مختلف API) هر بار یک bucket جدید می‌گیرد و عملاً سهمیهٔ نرخ IP-محور را دور می‌زند.

**گام:** خط کلید را به‌صورت زیر تغییر دهید تا سهمیه **سراسری per-IP** باشد، ولی سهمیهٔ سخت‌گیرانه‌تر per-IP+path را هم برای مسیرهای حساس (لاگین/OTP) نگه دارید — یعنی دو کلید مجزا، نه جایگزینی کامل:
```php
$clientIp    = $request->ip();
$globalKey   = "rl:global:{$clientIp}";
$pathKey     = "rl:{$clientIp}:{$path}";

// سهمیهٔ سراسری per-IP — همیشه چک می‌شود
$globalResult = $this->rateLimiter->limit($globalKey, self::GLOBAL_LIMIT, self::GLOBAL_WINDOW);
if (!$globalResult['allowed']) {
    return $this->tooManyRequestsResponse($globalResult);
}

// سهمیهٔ per-path (رفتار قبلی، برای throttle دقیق‌تر مسیرهای حساس)
$result = $this->rateLimiter->limit($pathKey, $limit, $window);
```
مقادیر `GLOBAL_LIMIT`/`GLOBAL_WINDOW` را به‌عنوان دو ثابت کلاس تعریف کنید (مثلاً ۳۰۰ درخواست در ۶۰ ثانیه — این عدد باید طوری انتخاب شود که کمتر از مجموع سهمیه‌های per-path موجود نباشد؛ قبل از finalize، `grep -n "RATE_LIMIT\|limit(" config/*.php src/Core/Middleware/RateLimitMiddleware.php` را اجرا کنید و مطمئن شوید سقف سراسری از مجموع مسیرهای پرتردد کمتر تنظیم نشده).

**تست:** تست انتگرال جدید که با دو path متفاوت اما یک IP، بعد از عبور از سقف سراسری، درخواست سوم (حتی به path سوم) را ۴۲۹ بگیرد.

**Definition of Done:** کد تغییر کرد، تست جدید سبز، `composer test:integration` سبز، کامیت `[T-A03] کلید محدودساز نرخ به‌صورت IP-محور سراسری + per-path`.

---

### T-A04 — عبور دادن پاسخ‌های ۴۰۴/۴۰۵ از میدلور سراسری
**شاهد دقیق:** `src/Core/Router.php` — دو نقطهٔ خروج زودهنگام **قبل از** حلقهٔ میدلور سراسری:
- خط ۱۲۴-۱۳۰: `throw new AppException('ERR_METHOD_NOT_ALLOWED', ..., 405)` — قبل از هر تطبیق مسیر.
- خط ۱۶۴-۱۶۸: `throw new AppException('ERR_NOT_FOUND', ..., 404)` — بعد از حلقهٔ `foreach` بدون match.
- حلقهٔ میدلور سراسری در خط ۱۴۲-۱۴۸ فقط **داخل** بلوک `if ($isMatch)` اجرا می‌شود.

**گام:** منطق را طوری بازآرایی کنید که میدلورهای سراسری (به‌خصوص `RateLimitMiddleware`) روی *هر* درخواست — چه مسیر پیدا شود چه نه — اجرا شوند. جایگزینی پیشنهادی برای متد `dispatch`:
```php
public function dispatch(Request $request, Application $app): Response
{
    // میدلورهای سراسری همیشه، حتی برای مسیرهای ناموجود/متد اشتباه، اجرا می‌شوند.
    foreach ($this->globalMiddlewares as $globalMw) {
        $globalResponse = $globalMw->handle($request, $app);
        if ($globalResponse !== null) {
            return $globalResponse;
        }
    }

    $method = $request->method();
    $path   = $request->path();

    if (!isset($this->routes[$method])) {
        throw new AppException('ERR_METHOD_NOT_ALLOWED', 'متد درخواست پشتیبانی نمی‌شود', 405);
    }

    foreach ($this->routes[$method] as $route) {
        $isMatch = preg_match($route['pattern'], $path, $matches);
        if ($isMatch) {
            $params = array_filter($matches, fn ($key) => is_string($key), ARRAY_FILTER_USE_KEY);
            $request->setRouteParams($params);
            $request->setMatchedRoutePath($route['path']);

            // میدلورهای اختصاصی مسیر (نه سراسری — آن‌ها بالا اجرا شدند)
            foreach ($route['middlewares'] as $middleware) {
                $middlewareResponse = $middleware->handle($request, $app);
                if ($middlewareResponse !== null) {
                    return $middlewareResponse;
                }
            }
            return $this->executeHandler($route['handler'], $request, $app);
        }
    }

    throw new AppException('ERR_NOT_FOUND', 'آدرس درخواستی یافت نشد', 404);
}
```
**نکتهٔ ایمنی:** `CorsMiddleware` و `SecurityHeadersMiddleware` هم جزو `globalMiddlewares` هستند (طبق `Application.php` خط ۱۴۸-۱۵۰) — این تغییر یعنی این دو هم روی ۴۰۴/۴۰۵ اجرا می‌شوند که **درست و مطلوب** است (هدرهای CORS/امنیتی باید روی همهٔ پاسخ‌ها باشند، نه فقط پاسخ‌های موفق).

**تست:** تست انتگرال: N+۱ درخواست به مسیرهای **ناموجود** (۴۰۴) از یک IP → درخواست N+۱ باید ۴۲۹ برگرداند نه ۴۰۴ (یعنی rate limiter واقعاً قبل از 404 اجرا شده).

**Definition of Done:** کد تغییر کرد، تست بالا سبز، `composer test:arch` سبز (چون این تغییر روی `Router.php` است که مستقیماً تحت پوشش `LayeringTest` نیست ولی باید مطمئن شوید تستی آن را نشکسته)، کامیت `[T-A04] اجرای میدلور سراسری قبل از پاسخ‌های ۴۰۴/۴۰۵`.


---

## بخش ۴ — فاز دو: تحکیم دامنهٔ سفارش/فرسوده/پرداخت (Group B — قلب نقشه راه)

> **قاعدهٔ سازمان‌دهی این بخش:** هر فایل **دقیقاً یک‌بار** و به‌صورت جامع لمس می‌شود (نه چند pass جدا برای هر باگ) تا از conflict و بازبینی تکراری جلوگیری شود. اگر یک فایل هم به رفع ریسک بحرانی (موجودی/فرسوده) و هم به قابلیت override قیمت مربوط است، همهٔ تغییرات آن فایل در یک TASK می‌آیند.

### T-B01 — افزودن حالت `allowNegative` به `InventoryRepository::adjustStock`
**چرا:** الگوی امن موجودی (`adjustStock`) به‌طور پیش‌فرض اجازهٔ منفی‌شدن موجودی را نمی‌دهد، اما طبق کامنت موجود در `OrderCommandService.php` خط ۴۴۷ (`// Reduce stock (may go negative for wholesale)`), سفارش‌های عمده **عمداً** مجازند موجودی را منفی کنند (خرید فراتر از موجودی فعلی، در انتظار تأمین مجدد). این یک قاعدهٔ کسب‌وکاری موجود است، نه باگ — پس نباید حذف شود؛ باید در پترن امن هم پشتیبانی شود.

**فایل:** `src/Common/Repository/InventoryRepository.php`

**تغییر دقیق (جایگزینی کامل متد `adjustStock`، خط ۳۱-۵۴):**
```php
public function adjustStock(int $productId, int $difference, bool $allowNegative = false): \App\Common\DTO\InventoryAdjustmentResult
{
    // Acquire a row lock before adjusting stock.
    $selectSql = 'SELECT stock_quantity FROM products WHERE id = ? FOR UPDATE';
    $current   = $this->app->db()->fetchOne($selectSql, [$productId]);
    if ($current === null) {
        throw new AppException('ERR_NOT_FOUND', 'Product not found', 404);
    }
    $beforeQuantity = (int) $current['stock_quantity'];
    $newBalance     = $beforeQuantity + $difference;
    if ($newBalance < 0 && !$allowNegative) {
        throw new AppException('ERR_INSUFFICIENT_STOCK', 'Not enough stock', 409);
    }
    // Perform the stock update.
    $sql = 'UPDATE products SET stock_quantity = stock_quantity + ? WHERE id = ?';
    $this->app->db()->query($sql, [$difference, $productId]);
    // Return DTO with before/after quantities.
    return new \App\Common\DTO\InventoryAdjustmentResult(
        $productId,
        $beforeQuantity,
        $newBalance,
        $difference,
    );
}
```
تنها تغییر: پارامتر سوم `bool $allowNegative = false` (پیش‌فرض `false` یعنی رفتار فعلی برای همهٔ فراخوان‌های موجود دست‌نخورده می‌ماند — backward compatible) و شرط خط `if ($newBalance < 0 && !$allowNegative)`.

**تست:** `tests/Unit/InventoryRepositoryTest.php` (یا معادل) — یک تست جدید: `adjustStock($id, -100, true)` روی محصولی با موجودی ۵، بدون exception اجرا شود و `newBalance === -95` برگرداند؛ و یک تست که تأیید کند رفتار پیش‌فرض (`allowNegative` حذف‌شده از فراخوانی) هنوز exception می‌دهد.

**Definition of Done:** طبق پروتکل بخش ۰.۱.۴. کامیت: `[T-B01] افزودن پارامتر allowNegative به InventoryRepository::adjustStock`.

---

### T-B02 — تحکیم `src/Order/OrderRepository.php`
**فایل:** `src/Order/OrderRepository.php` (۵۳۲ خط، مسیر سفارش مشتری/self-checkout).

**۳ مشکل که در این یک pass رفع می‌شوند:**

**(الف) نرخ فرسودهٔ سراسری به‌جای برند-محور.**
شاهد: خط ۴۱ (`$usedBatteryRate = $this->getUsedBatteryRate();`) یک نرخ برای کل سفارش می‌گیرد و به `createOrderItem()` پاس می‌دهد؛ خود `createOrderItem()` (خط ۹۶-۱۴۱) از قبل با `SELECT * FROM products WHERE id = ?` (خط ۹۹-۱۰۲) رکورد محصول را — شامل `brand_id` — می‌گیرد، پس همهٔ داده برای حل برند-محور از قبل در دسترس است.

**(ب) کاهش غیراتمیک موجودی.**
شاهد: متد خصوصی `reserveInventory()` (خط ۳۹۳-۴۰۱)، فراخوانی‌شده در خط ۸۲ (داخل همان تراکنش `createOrder`):
```php
private function reserveInventory(array $items): void
{
    foreach ($items as $item) {
        $this->app->db()->query(
            'UPDATE products SET stock_quantity = stock_quantity - ? WHERE id = ?',
            [$item['quantity'], $item['product_id']],
        );
    }
}
```
بدون قفل ردیفی، بدون گارد منفی.

**(ج) شمارهٔ سفارش بدون بررسی برخورد.**
شاهد: `SecurityHelper::generateOrderNumber()` (`src/Common/Helper/SecurityHelper.php` خط ۱۱۹-۱۲۵) صرفاً `random_int(100000, 999999)` است، بدون هیچ چک یکتایی.

**گام ۱ — Import های لازم را در بالای فایل اضافه کنید (بعد از `use App\Core\Application;`):**
```php
use App\Common\Repository\InventoryRepository;
use App\Common\Service\BrandRateService;
```

**گام ۲ — حذف نرخ سراسری از `createOrder()` و `createOrderItem()`:**
در `createOrder()` (خط ۳۴-۸۹)، خط ۴۱ (`$usedBatteryRate = $this->getUsedBatteryRate();`) را **کامل حذف کنید**.
خط ۷۲ را از
```php
$this->createOrderItem($orderId, $item, $usedBatteryRate);
```
به
```php
$this->createOrderItem($orderId, $item);
```
تغییر دهید.

سپس امضای `createOrderItem()` (خط ۹۶) را از
```php
private function createOrderItem(int $orderId, array $item, int $usedBatteryRate): void
```
به
```php
private function createOrderItem(int $orderId, array $item): void
```
تغییر دهید. **بلافاصله بعد از** خط ۱۰۲ (بعد از دریافت `$product`)، این بلوک را اضافه کنید:
```php
$rateService     = new BrandRateService($this->app);
$usedBatteryRate = ($item['has_used_battery'] && $item['used_battery_amperage'])
    ? $rateService->getUsedBatteryRate((int) ($product['brand_id'] ?? 0), (int) $item['product_id'])
    : 0;
```
(متغیر `$usedBatteryRate` محلی جایگزین پارامتر ورودی قبلی می‌شود؛ بقیهٔ بدنهٔ متد — خط ۱۱۲ به بعد — بدون تغییر کار می‌کند چون همان نام متغیر را مصرف می‌کند.)

**گام ۳ — رفع موجودی غیراتمیک:**
متد `reserveInventory()` (خط ۳۹۳-۴۰۱) را کامل با این جایگزین کنید:
```php
private function reserveInventory(array $items): void
{
    $inventoryRepo = new InventoryRepository($this->app);
    foreach ($items as $item) {
        // مشتری نهایی (self-checkout) هرگز نباید موجودی منفی ایجاد کند — allowNegative=false
        $inventoryRepo->adjustStock((int) $item['product_id'], -(int) $item['quantity'], false);
    }
}
```
چون `reserveInventory` از داخل `transaction()` صدا زده می‌شود (خط ۸۲، درون کلوژر خط ۳۵-۸۸)، و `AppException('ERR_INSUFFICIENT_STOCK', ..., 409)` به‌طور طبیعی throw و باعث rollback خودکار تراکنش می‌شود — نیازی به try/catch نیست.

**گام ۴ — رفع شمارهٔ سفارش بدون بررسی برخورد.**
داخل `createOrder()`، خط ۳۶ (`$orderNumber = SecurityHelper::generateOrderNumber();`) را با یک حلقهٔ بررسی یکتایی جایگزین کنید — از همان الگوی موجود در `OrderCommandService::persistOrder()` (خط ۳۲۰-۳۲۴) الهام می‌گیریم:
```php
$orderNumber = SecurityHelper::generateOrderNumber();
while ((int) $this->app->db()->fetchColumn(
    'SELECT COUNT(*) FROM orders WHERE order_number = ?',
    [$orderNumber],
) > 0) {
    $orderNumber = SecurityHelper::generateOrderNumber();
}
```
(چون این حلقه داخل تراکنش با `SELECT` ساده اجرا می‌شود و فضای نمونهٔ `random_int(100000,999999)` حدود ۹۰۰ هزار مقدار دارد، احتمال برخورد عملاً نزدیک صفر است؛ اما این حلقه یک شبکهٔ ایمنی صریح ایجاد می‌کند به‌جای سکوت روی خطای احتمالی `UNIQUE constraint` — بررسی کنید ستون `order_number` واقعاً `UNIQUE` است: `grep -n "order_number" database/ANBT_SCHEMA_REFERENCE.sql | grep -i unique`؛ اگر ایندکس یکتا وجود ندارد، این را به‌عنوان یک یافتهٔ اضافه در `docs/arch/ROADMAP_EXECUTION_LOG.md` با برچسب `[FINDING]` ثبت کنید و در T-F* پیگیری کنید.)

**گام ۵ — حذف متد اضافی/تکراری:**
بعد از گام‌های ۱ تا ۴، متد خصوصی `getUsedBatteryRate()` (خط ~۴۲۱-۴۳۲) دیگر از هیچ‌جای این کلاس صدا زده نمی‌شود (طبق طراحی، منبع حقیقت اکنون منحصراً `BrandRateService` است). با `grep -n "getUsedBatteryRate" src/Order/OrderRepository.php` تأیید کنید صفر فراخوانی باقی مانده، سپس کل متد را حذف کنید.

**تست‌ها:**
- تست انتگرال: سفارشی با دو آیتم از دو برند متفاوت که هر دو `has_used_battery=true` هستند و نرخ اختصاصی برند دارند → `order_items.used_battery_rate` هر ردیف باید برابر نرخ برند خودش باشد، نه یک نرخ یکسان.
- تست انتگرال همزمانی (نگاه کنید T-E01 برای الگوی کامل).
- تست شمارهٔ سفارش: mock کردن `random_int` برای برگرداندن یک عدد تکراری در دو فراخوانی متوالی، assert کنید سفارش دوم شمارهٔ متفاوت گرفت.

**Definition of Done:** طبق پروتکل. کامیت: `[T-B02] تحکیم OrderRepository: نرخ فرسودهٔ برند-محور + موجودی اتمیک + رفع برخورد شمارهٔ سفارش`.

---

### T-B03 — تحکیم `src/Order/Service/OrderCommandService.php`
**فایل:** `src/Order/Service/OrderCommandService.php` (۵۶۳ خط، مسیر POS/عمده‌فروشی/آمپری ادمین — همان جایی که ویرایش دستی قیمت عمده در `wholesale_detail_screen.dart` به آن وصل می‌شود).

**۴ مشکل که در این یک pass رفع می‌شوند:**

**(الف) کاهش غیراتمیک موجودی.** شاهد خط ۴۴۷-۴۵۱ در `persistOrderItems()`:
```php
// Reduce stock (may go negative for wholesale)
$this->app->db()->query(
    'UPDATE products SET stock_quantity = stock_quantity - ? WHERE id = ?',
    [$oi['quantity'], $oi['product_id']],
);
```

**(ب) override قیمت بدون کنترل مجوز و بدون ثبت ردگیری.** شاهد `resolveUnitPrice()` خط ۲۴۳-۲۴۵:
```php
if (isset($item['unit_price']) && (int)$item['unit_price'] > 0) {
    return (int)$item['unit_price'];
}
```
هر کسی که به این متد برسد (یعنی هرکسی با مجوز `orders.edit`) می‌تواند قیمت را دستی عوض کند؛ و هیچ‌جا ثبت نمی‌شود که این قیمت override شده یا نه — ستون‌های `pricing_source`/`pricing_unit_rial`/`pricing_rate_snapshot`/`pricing_rate_id`/`pricing_amperage_snapshot` در جدول `order_items` وجود دارند ولی هرگز پر نمی‌شوند (تأیید شد: `grep -rn "pricing_source" src/` صفر نتیجه می‌دهد).

**(ج) fallback «باتری فرسودهٔ سراسری» با SQL خام تکراری.** شاهد خط ۳۹۶-۴۰۰ در `persistOrderItems()`:
```php
if ($itemUsedRate <= 0) {
    $itemUsedRate = (int) ($this->app->db()->fetchColumn(
        'SELECT rate_per_amp FROM used_battery_rates WHERE is_current = 1 LIMIT 1',
    ) ?: $this->app->db()->fetchColumn(
        "SELECT value FROM settings WHERE setting_group = 'used_battery' AND setting_key = 'rate_per_amp'",
    ) ?: 6000);
}
```
و مشابه آن در `calculateUsedCredit()` خط ۲۷۹-۲۸۷ با `$rateService->getUsedBatteryRate(0)` (که چون `brand_id=0` هیچ برندی نیست، همیشه از مسیر legacy عبور می‌کند — معادل عملیِ دور زدن BrandRateService).

**گام ۱ — Import لازم:**
بعد از خط ۱۲ (`use App\Core\Logger;`) اضافه کنید:
```php
use App\Common\Repository\InventoryRepository;
```
(`BrandRateService` از قبل import شده — خط ۹.)

**گام ۲ — رفع (ب): افزودن پارامتر `bool $canOverridePrice` به `createOrder()` و `buildOrderItems()`.**

امضای `createOrder()` (خط ۷۵-۸۴) را با افزودن یک پارامتر جدید در انتها تغییر دهید:
```php
public function createOrder(
    int $adminId,
    ?int $customerId,
    array $items,
    string $orderType,
    ?array $usedBattery,
    int $discountAmount,
    array $payments,
    ?string $paymentMethod,
    bool $canOverridePrice = false,
): array {
```
داخل کلوژر تراکنش (خط ۱۰۸)، فراخوانی `buildOrderItems` در خط ۱۰۹ را از
```php
[$orderItems, $subtotal] = $this->buildOrderItems($items, $orderType);
```
به
```php
[$orderItems, $subtotal] = $this->buildOrderItems($items, $orderType, $canOverridePrice);
```
تغییر دهید. امضای `use (...)` کلوژر خط ۱۰۸ را هم با افزودن `$canOverridePrice` به‌روزرسانی کنید:
```php
function () use ($adminId, $finalCustomerId, $items, &$payments, $usedBattery, $orderType, $discountAmount, $canOverridePrice) {
```

امضای `buildOrderItems()` (خط ۱۶۹) را تغییر دهید:
```php
private function buildOrderItems(array $items, string $orderType, bool $canOverridePrice): array
```
داخل حلقهٔ `foreach ($items as $item)`، فراخوانی `resolveUnitPrice` در خط ۱۹۲ را از
```php
$unitPrice = $this->resolveUnitPrice($product, $item, $orderType, $rateService);
```
به
```php
[$unitPrice, $pricingSource, $referenceRate] = $this->resolveUnitPrice($product, $item, $orderType, $rateService, $canOverridePrice);
```
تغییر دهید و در آرایهٔ خروجی `$orderItems[]` (خط ۲۱۰-۲۲۶) دو کلید جدید اضافه کنید:
```php
'pricing_source'    => $pricingSource,
'pricing_unit_rial' => $referenceRate,
```

**گام ۳ — بازنویسی `resolveUnitPrice()` (خط ۲۳۸-۲۶۵) برای برگرداندن provenance و رعایت مجوز:**
```php
/**
 * Resolve unit price based on order type and item override.
 *
 * @param array<string, mixed> $product
 * @param array<string, mixed> $item
 * @return array{0: int, 1: string, 2: int}  [$unitPrice, $pricingSource, $systemReferenceRate]
 */
private function resolveUnitPrice(array $product, array $item, string $orderType, BrandRateService $rateService, bool $canOverridePrice): array
{
    if ($orderType === 'ampere_credit') {
        return [0, 'dedicated', 0];
    }

    $brandId    = (int)$product['brand_id'];
    $productId  = (int)$product['id'];
    $amperageId = $product['amperage_id'] !== null ? (int)$product['amperage_id'] : null;

    $rateType = $orderType === 'wholesale'
        ? BrandRateService::TYPE_WHOLESALE
        : BrandRateService::TYPE_RETAIL;

    $res = $rateService->resolvePrice($brandId, $rateType, $amperageId, $productId);

    if ($res['rate'] !== null) {
        $amp = (int)($product['amperage_value'] ?? 0);
        $systemPrice   = (int)($res['rate'] * $amp);
        $systemSource  = 'brand_rate';
    } else {
        $systemPrice  = $orderType === 'wholesale' ? (int)$product['wholesale_price'] : (int)$product['retail_price'];
        $systemSource = 'legacy';
    }

    // Manual override — فقط اگر مجوز orders.price_override اعطا شده باشد.
    if ($canOverridePrice && isset($item['unit_price']) && (int)$item['unit_price'] > 0 && (int)$item['unit_price'] !== $systemPrice) {
        return [(int)$item['unit_price'], 'manual_override', $systemPrice];
    }

    return [$systemPrice, $systemSource, $systemPrice];
}
```
**نکته:** اگر `$item['unit_price']` ست شده ولی `$canOverridePrice === false`، مقدار override **بی‌صدا نادیده گرفته می‌شود** و قیمت سیستم اعمال می‌شود (نه پرتاب خطا) — این رفتار عمدی است تا کاربران بدون مجوز، بدون توقف تجربهٔ کاربری، فقط نتوانند override کنند؛ اگر می‌خواهید به‌جای نادیده‌گرفتن بی‌صدا، خطای صریح ۴۰۳ بدهید، خط زیر را به ابتدای `createOrder()` (بعد از اعتبارسنجی‌های خط ۸۶-۹۴) اضافه کنید:
```php
if (!$canOverridePrice && array_filter($items, static fn ($i) => isset($i['unit_price']) && (int)$i['unit_price'] > 0) !== []) {
    throw new AppException('ERR_PRICE_OVERRIDE_FORBIDDEN', 'شما مجوز ویرایش دستی قیمت را ندارید', 403);
}
```
تصمیم بین این دو رفتار (نادیده‌گرفتن بی‌صدا در برابر خطای ۴۰۳) یک تصمیم محصولی است — **پیش‌فرض این نقشه راه: خطای ۴۰۳ صریح** (خط بالا را اضافه کنید)، چون شفاف‌تر است و از ثبت اشتباهِ «قیمت پایین‌تر از حد انتظار بدون هشدار» جلوگیری می‌کند.

**گام ۴ — رفع (الف): موجودی اتمیک در `persistOrderItems()`.**
خط ۴۴۷-۴۵۱ را با این جایگزین کنید:
```php
// Reduce stock (wholesale may intentionally go negative — pending restock)
$inventoryRepo = new InventoryRepository($this->app);
$inventoryRepo->adjustStock(
    (int) $oi['product_id'],
    -(int) $oi['quantity'],
    $orderType === 'wholesale',
);
```
از آنجا که `$orderType` در امضای `persistOrderItems()` فعلاً پاس داده نمی‌شود (خط ۳۵۷: `private function persistOrderItems(int $orderId, array &$orderItems, ?array $usedBattery): void`)، امضا را تغییر دهید:
```php
private function persistOrderItems(int $orderId, array &$orderItems, ?array $usedBattery, string $orderType): void
```
و فراخوانی آن در خط ۱۴۶ (`$this->persistOrderItems($orderId, $orderItems, $usedBattery);`) را به‌روزرسانی کنید:
```php
$this->persistOrderItems($orderId, $orderItems, $usedBattery, $orderType);
```
همچنین import `InventoryRepository` را در ابتدای متد اضافه کنید (یا در بالای فایل طبق گام ۱ — کافی است).

**گام ۵ — رفع (ج): fallback فرسودهٔ سراسری با `BrandRateService`.**
خط ۳۹۶-۴۰۰ داخل `persistOrderItems()` را جایگزین کنید:
```php
if ($itemUsedRate <= 0) {
    $fallbackBrandId = (int) ($oi['brand_id'] ?? 0);
    $rateService      = new BrandRateService($this->app);
    $itemUsedRate     = $rateService->getUsedBatteryRate($fallbackBrandId, (int) $oi['product_id']);
}
```
(از برند همان آیتمی که باتری سراسری به آن attach می‌شود استفاده می‌کنیم — این دقیقاً همان آیتمی است که چند خط پایین‌تر، در همان iteration، رکورد `order_used_batteries` برایش درج می‌شود؛ `$oi['brand_id']` از قبل در آرایهٔ `$orderItems` هر آیتم موجود است — نگاه کنید خط ۲۱۳ در `buildOrderItems`.)

مشابه آن در `calculateUsedCredit()` خط ۲۷۹-۲۸۷، خط‌های
```php
if ($rate <= 0) {
    $rateService = new BrandRateService($this->app);
    // Fall back to settings/legacy via getUsedBatteryRate(0)
    $rate = $rateService->getUsedBatteryRate(0);
}
```
را جایگزین کنید با:
```php
if ($rate <= 0) {
    $rateService     = new BrandRateService($this->app);
    $fallbackBrandId = (int) ($orderItems[0]['brand_id'] ?? 0);
    $rate            = $rateService->getUsedBatteryRate($fallbackBrandId, (int) ($orderItems[0]['product_id'] ?? 0));
}
```
(اینجا چون `usedBattery` سراسری هنوز به هیچ آیتمی attach نشده، از برند **اولین آیتم سفارش** به‌عنوان قاعدهٔ کسب‌وکاری ثابت و مستند استفاده می‌کنیم — این دقیقاً همان آیتمی است که بعداً در `persistOrderItems` باتری سراسری بهش وصل می‌شود، پس سازگار است.)

**گام ۶ — ثبت provenance در insert جدول `order_items`.**
داخل `persistOrderItems()`، در فراخوانی `$this->app->db()->insert('order_items', [...])` (خط ۳۷۰-۳۸۵)، بعد از خط ۳۸۴ (`'product_snapshot' => $productSnapshot,`) دو کلید اضافه کنید:
```php
'pricing_source'    => $oi['pricing_source']    ?? 'brand_rate',
'pricing_unit_rial' => $oi['pricing_unit_rial'] ?? $oi['unit_price'],
```
(این دو کلید از گام ۲/۳ در آرایهٔ `$orderItems` هر آیتم از قبل موجودند.)

**تست‌ها:**
- تست انتگرال: `createOrder(..., canOverridePrice: false)` با `unit_price` دستی روی یک آیتم → انتظار خطای `ERR_PRICE_OVERRIDE_FORBIDDEN` (۴۰۳).
- تست انتگرال: `createOrder(..., canOverridePrice: true)` با `unit_price` دستی → سفارش ثبت شود؛ ردیف `order_items` مربوطه باید `pricing_source = 'manual_override'` و `pricing_unit_rial` برابر قیمت محاسبه‌شدهٔ سیستم (نه قیمت override) داشته باشد.
- تست انتگرال: سفارش عمده (`wholesale`) با موجودی ناکافی → باید موفق شود و موجودی منفی شود؛ سفارش `pos` با موجودی ناکافی → باید `ERR_INSUFFICIENT_STOCK` بگیرد (نه فقط چک early-exit خط ۱۸۸-۱۹۰، بلکه چون آن چک بدون قفل است، سناریوی همزمانی را هم در T-E01 پوشش دهید).
- تست انتگرال فرسودهٔ سراسری: سفارش دو-آیتمی با `usedBattery` سراسری (نه per-item) و بدون `rate` صریح → نرخ باید برابر نرخ برند آیتم اول باشد، نه ۶۰۰۰ (پیش‌فرض hard-coded).

**Definition of Done:** طبق پروتکل. کامیت: `[T-B03] تحکیم OrderCommandService: موجودی اتمیک + مجوز/ردگیری override قیمت + فرسودهٔ برند-محور`.

---

### T-B04 — اتصال مجوز override به `AdminOrderController`
**فایل:** `src/Admin/AdminOrderController.php`

**شاهد دقیق (خط ۸۱-۱۰۰+، متد `store`):**
```php
public function store(Request $request): Response
{
    ...
    $commandService = new OrderCommandService($this->app);
    $result = $commandService->createOrder(
        ...
    );
```

**گام:** قبل از فراخوانی `$commandService->createOrder(...)`، مجوز کاربر جاری را چک کنید و به‌عنوان آخرین آرگومان پاس دهید:
```php
$canOverridePrice = $this->hasPermission($request, 'orders.price_override');

$commandService = new OrderCommandService($this->app);
$result = $commandService->createOrder(
    // ...آرگومان‌های موجود، بدون تغییر...
    canOverridePrice: $canOverridePrice,
);
```
از آنجا که کلاس `AdminMiddleware` (`src/Admin/AdminMiddleware.php`) از قبل منطق چک permission را دارد (بررسی `super_admin` role یا join جدول `admin_permissions`)، یک متد کمکی خصوصی به `AdminOrderController` اضافه کنید که همان منطق را برای یک چک ad-hoc (نه سطح route) استفاده می‌کند:
```php
private function hasPermission(Request $request, string $code): bool
{
    if ($request->adminRole() === 'super_admin') {
        return true;
    }
    $adminId = $request->adminId();
    $row = $this->app->db()->fetchOne(
        'SELECT 1 FROM admin_permissions ap
         JOIN permissions p ON ap.permission_id = p.id
         WHERE ap.admin_id = ? AND p.code = ? LIMIT 1',
        [$adminId, $code],
    );
    return $row !== null;
}
```
(قبل از نوشتن این متد، حتماً `src/Admin/AdminMiddleware.php` را دوباره باز کنید و مطمئن شوید نام دقیق ستون‌ها/جدول‌های join با آنچه در آنجا استفاده شده یکی است — اگر AdminMiddleware از یک متد عمومی‌تر مثل `PermissionChecker::has($adminId, $role, $code)` استفاده می‌کند، به‌جای کپی‌کردن منطق، همان کلاس را فراخوانی کنید تا تکرار کد ایجاد نشود.)

**تست:** تست انتگرال HTTP: کاربر ادمین بدون مجوز `orders.price_override` → درخواست `POST /admin/orders` با `unit_price` دستی روی یک آیتم wholesale → پاسخ ۴۰۳ با کد `ERR_PRICE_OVERRIDE_FORBIDDEN`. همان درخواست با کاربر `super_admin` یا کاربری با مجوز → ۲۰۰ و `pricing_source=manual_override` در دیتابیس.

**Definition of Done:** طبق پروتکل. کامیت: `[T-B04] اتصال مجوز orders.price_override به AdminOrderController`.


---

### T-B05 — رفع سبد خرید (Cart): نرخ فرسوده به‌تفکیک آیتم/برند
**فایل‌ها:** `src/Cart/CartRepository.php`، `src/Cart/CartValidationService.php`

**شاهد دقیق باگ:** `CartRepository.php` خط ۳۲۵-۳۲۹:
```php
public function getUsedBatteryRate(): int
{
    $rateService = new BrandRateService($this->app);
    return $rateService->getUsedBatteryRate(0);
}
```
چون `brand_id=0` هیچ برندی نیست، `resolvePrice()` همیشه `null` برمی‌گرداند و مسیر برند-محور **هرگز** اجرا نمی‌شود — این متد معادل «همیشه نرخ سراسری» است، صرف‌نظر از این‌که چه نرخ‌های اختصاصی برندی در `brand_ampere_rates` ثبت شده باشند.

مصرف‌کنندهٔ این متد: `CartValidationService.php` خط ۱۸۱-۲۵۰، به‌ویژه خط ۱۸۳ (`$usedBatteryRate = $this->repository->getUsedBatteryRate();`) که یک نرخ برای **کل سبد** می‌گیرد و در خط ۱۹۷ به همهٔ آیتم‌ها یکسان اعمال می‌کند — با اینکه `p.brand_id` از قبل در کوئری سبد (`CartRepository.php` خط ۹۳) انتخاب شده و در حلقهٔ `foreach ($cart['items'] as $item)` (خط ۱۸۹) در دسترس است.

**گام ۱ — حذف متد باگ‌دار از `CartRepository.php`:**
با `grep -rn "getUsedBatteryRate" src/Cart/` مطمئن شوید تنها فراخوان همان خط ۱۸۳ در `CartValidationService.php` است، سپس کل متد (خط ۳۲۵-۳۲۹ به‌همراه امضایش) را از `CartRepository.php` حذف کنید.

**گام ۲ — بازنویسی `CartValidationService::calculateTotals()` برای حل per-item:**
فایل `src/Cart/CartValidationService.php`، ابتدا import اضافه کنید (بالای فایل، کنار سایر use):
```php
use App\Common\Service\BrandRateService;
```
سپس خط ۱۸۱-۲۲۸ را با این جایگزین کنید:
```php
public function calculateTotals(array $cart): array
{
    $rateService     = new BrandRateService($this->app);
    $subtotal        = 0;
    $usedCredit      = 0;
    $installFee      = 0;
    $itemsWithPrices = [];
    $lastUsedBatteryRate = 0; // فقط برای فیلد خلاصهٔ خروجی (نگاه کنید گام ۳)

    foreach ($cart['items'] as $item) {
        $itemPrice      = (int) $item['current_price'];
        $itemTotal      = $itemPrice * (int) $item['quantity'];
        $itemUsedCredit = 0;
        $itemUsedRate   = 0;
        $itemInstallFee = 0;

        // Used battery credit — نرخ به‌تفکیک برند همان محصول
        if ($item['has_used_battery'] && $item['used_battery_amperage']) {
            $itemUsedRate    = $rateService->getUsedBatteryRate((int) $item['brand_id'], (int) $item['product_id']);
            $itemUsedCredit  = (int) $item['used_battery_amperage'] * $itemUsedRate * (int) $item['quantity'];
            $usedCredit     += $itemUsedCredit;
            $lastUsedBatteryRate = $itemUsedRate;
        }

        // Installation fee
        if ($item['has_installation']) {
            $itemInstallFee = (int) ($item['installation_fee'] ?? 0) * (int) $item['quantity'];
            $installFee += $itemInstallFee;
        }

        $subtotal += $itemTotal;

        $itemsWithPrices[] = [
            'id'                    => (int) $item['id'],
            'product_id'            => (int) $item['product_id'],
            'product_name'          => $item['product_name'],
            'product_slug'          => $item['product_slug'],
            'product_sku'           => $item['product_sku'],
            'brand_name'            => $item['brand_name'],
            'primary_image'         => $item['primary_image'],
            'quantity'              => (int) $item['quantity'],
            'unit_price'            => $itemPrice,
            'total_price'           => $itemTotal,
            'has_used_battery'      => (bool) $item['has_used_battery'],
            'used_battery_amperage' => $item['used_battery_amperage'] ? (int) $item['used_battery_amperage'] : null,
            'used_battery_rate'     => $itemUsedRate,
            'used_credit'           => $itemUsedCredit,
            'has_installation'      => (bool) $item['has_installation'],
            'install_fee'           => $itemInstallFee,
            'warranty_months'       => (int) $item['warranty_months'],
            'stock_status'          => $this->getStockStatus((int) $item['stock_quantity']),
        ];
    }
```
**نکات دقیق این جایگزینی:**
- کلید جدید `'used_battery_rate' => $itemUsedRate` به هر آیتم در `$itemsWithPrices` اضافه شد (قبلاً این فیلد فقط در سطح خلاصهٔ کل سبد بود، نه هر آیتم) — این برای فرانت لازم است تا بتواند نرخ متفاوت هر برند را نشان دهد (نگاه کنید T-C02 که مصرف‌کنندهٔ همین فیلد در سمت ادمین است، هرچند این مسیر خاص Cart برای مشتری نهایی است نه ادمین — مسیر ادمین جدا در T-B03 اصلاح شده).
- بقیهٔ متد (خط ۲۳۰ به بعد در فایل اصلی، یعنی «Shipping fee logic» تا انتهای return) **بدون تغییر** باقی می‌ماند، فقط در بخش `return [...]` (خط ۲۴۴ در فایل اصلی: `'used_battery_rate' => $usedBatteryRate,`) این خط را به‌روزرسانی کنید:
```php
'used_battery_rate'       => $lastUsedBatteryRate, // DEPRECATED: میانگین/آخرین نرخ، فقط برای سازگاری عقب‌رو — فرانت باید از items[].used_battery_rate استفاده کند
```

**گام ۳ — یادداشت سازگاری عقب‌رو:** فیلد سطح-بالای `used_battery_rate` در پاسخ (خارج از `items`) دیگر معنای دقیقی ندارد وقتی آیتم‌ها نرخ‌های متفاوت دارند. آن را حذف نکنید (تا کلاینت‌های قدیمی نشکنند) اما در `docs/openapi/` (اگر توضیح این فیلد آنجا هست) کامنت `@deprecated` اضافه کنید و در OpenAPI spec یادداشت بگذارید که منبع درست، `items[].used_battery_rate` است.

**تست‌ها:**
- تست انتگرال: دو آیتم در سبد از دو برند با نرخ فرسودهٔ اختصاصی متفاوت (مثلاً ۴۰۰۰۰۰ و ۴۵۰۰۰۰ ریال) → `calculateTotals()['items'][0]['used_battery_rate']` و `[1]['used_battery_rate']` باید متفاوت و برابر مقادیر ثبت‌شده باشند؛ `used_credit` کل باید مجموع دقیق دو محاسبهٔ جداگانه باشد (نه یک نرخ ضربدر کل آمپراژ).
- تست رگرسیون: برندی بدون نرخ اختصاصی → باید دقیقاً همان نرخ سراسری قبلی را بگیرد (نه صفر).

**Definition of Done:** طبق پروتکل. کامیت: `[T-B05] رفع Cart: نرخ فرسوده به‌تفکیک آیتم/برند به‌جای brand_id=0`.

---

### T-B06 — رفع دریافت باتری فرسوده: نرخ برند-محور در `UsedBatteryControllerHandler`
**فایل‌ها:** `src/UsedBattery/UsedBatteryControllerHandler.php`، `src/UsedBattery/Repository/UsedBatteryControllerRepository.php`

**وضعیت فعلی (پس از T-B02/T-B03):** ستون `order_used_batteries.used_rate` اکنون در لحظهٔ ایجاد سفارش با نرخ **صحیحِ برند-محور** پر می‌شود (چون `OrderCommandService::persistOrderItems` و `OrderRepository::createOrderItem` هر دو اصلاح شدند). یعنی `$item['used_rate']` که در خط ۹۱ و ۱۳۱ این فایل خوانده می‌شود، از این پس معمولاً درست است. مشکل باقی‌مانده فقط لایهٔ fallback **دوم** است (وقتی `used_rate` صفر/خالی باشد — مثلاً سفارش‌های قدیمیِ قبل از این نقشه راه) که هنوز SQL خام سراسری صدا می‌زند.

**شاهد دقیق:** `sql003()`/`sql004()`/`sql005()`/`sql006()` در `UsedBatteryControllerRepository.php` (خط ۳۷-۵۹) — هر چهارتا یا `settings` یا `used_battery_rates` را می‌خوانند، بدون هیچ آگاهی از برند. مصرف در `receiveLess()` خط ۹۰-۹۵ و `receiveMore()` خط ۱۳۰-۱۳۵.

**گام ۱ — افزودن `brand_id` به کوئری `sql002()`:**
فایل `UsedBatteryControllerRepository.php`، متد `sql002()` (خط ۲۱-۳۵) را با این جایگزین کنید:
```php
public function sql002(): string
{
    return '
        SELECT 
            oub.*, 
            oi.order_id, 
            oi.product_id,
            p.brand_id,
            o.status AS order_status
        FROM order_used_batteries oub
        JOIN order_items oi ON oub.order_item_id = oi.id
        JOIN orders o ON oi.order_id = o.id
        JOIN products p ON oi.product_id = p.id
        WHERE o.id = ?
        LIMIT 1
    ';
}
```
(تنها تغییر: `JOIN products p ON oi.product_id = p.id` و افزودن `p.brand_id` به `SELECT`.)

**گام ۲ — رفع fallback در `receiveLess()`:**
فایل `UsedBatteryControllerHandler.php`، خط ۹۰-۹۵ را جایگزین کنید:
```php
if ($rate <= 0) {
    $rate = (int) ($item['used_rate'] ?? 0);
}
if ($rate <= 0) {
    $rateService = new \App\Common\Service\BrandRateService($this->app);
    $rate        = $rateService->getUsedBatteryRate((int) ($item['brand_id'] ?? 0), (int) $item['product_id']);
}
```

**گام ۳ — رفع fallback در `receiveMore()`:**
همان الگو، خط ۱۳۰-۱۳۵:
```php
if ($rate <= 0) {
    $rate = (int) ($item['used_rate'] ?? 0);
}
if ($rate <= 0) {
    $rateService = new \App\Common\Service\BrandRateService($this->app);
    $rate        = $rateService->getUsedBatteryRate((int) ($item['brand_id'] ?? 0), (int) $item['product_id']);
}
```

**گام ۴ — افزودن import در بالای فایل** (به‌جای FQCN تکراری در گام‌های ۲/۳، بهتر است در ابتدای فایل اضافه کنید و در بدنه فقط `BrandRateService` بنویسید):
```php
use App\Common\Service\BrandRateService;
```
و آنگاه گام ۲/۳ را با `new BrandRateService($this->app)` (بدون FQCN کامل) بنویسید.

**گام ۵ — پاکسازی متدهای بلااستفاده:** بعد از گام ۲/۳، با `grep -n "sql003\|sql004\|sql005\|sql006" src/UsedBattery/UsedBatteryControllerHandler.php` تأیید کنید صفر فراخوانی باقی مانده، سپس این چهار متد را از `UsedBatteryControllerRepository.php` حذف کنید (`sql001` و `sql002` دست‌نخورده می‌مانند چون هنوز استفاده می‌شوند).

**تست‌ها:**
- تست انتگرال: سفارشی با آیتمی از برند دارای نرخ اختصاصی فرسوده، که `order_used_batteries.used_rate` آن (عمداً در فیکسچر تست) صفر گذاشته شده (شبیه‌سازی دادهٔ قدیمی) → `receiveLess()` بدون پارامتر `rate` صریح فراخوانی شود → مبلغ محاسبه‌شده باید بر مبنای نرخ برند باشد، نه ۶۰۰۰ پیش‌فرض.
- تست رگرسیون: `receiveExact()` دست‌نخورده مانده (این متد اصلاً از نرخ استفاده نمی‌کند) — تست موجود باید همچنان سبز باشد.

**Definition of Done:** طبق پروتکل. کامیت: `[T-B06] رفع UsedBatteryControllerHandler: fallback نرخ برند-محور به‌جای SQL سراسری خام`.

---

### T-B07 — تراکنشی و idempotent کردن تأیید پرداخت آنلاین
**فایل:** `src/Payment/PaymentService.php`

**این حیاتی‌ترین TASK کل نقشه راه است (ریسک #۲ گزارش ارزیابی، شدت «بحرانی»).**

**شاهد دقیق مشکل** — متد `verifyOnlinePayment()` (تقریباً خط ۷۷-۱۴۰): سه نوشتار متوالی (`payments` را آپدیت می‌کند، `orders` را آپدیت می‌کند، `order_status_history` را insert می‌کند) **بدون** `transaction()` دور آن‌ها، و **بدون** چک اینکه پرداخت از قبل `completed` نشده (idempotency).

**شاهد الگوی صحیحِ موجود در همان کلاس** — متد `confirmCodPayment()` (خط ۳۱۱-۳۷۴):
```php
// خط ۳۳۷ — چک idempotency قبل از هر نوشتار
if ($payment['status'] === 'completed') {
    return ['status' => 'already_completed', ...];
}
...
// دور هر سه نوشتار
$this->app->db()->transaction(function () use (...) {
    $this->app->db()->update('payments', [...], 'id = ?', [$paymentId]);
    $this->app->db()->update('orders', [...], 'id = ?', [$orderId]);
    $this->app->db()->insert('order_status_history', [...]);
});
```

**گام:** ابتدا با `view src/Payment/PaymentService.php` محدودهٔ دقیق خط شروع/پایان `verifyOnlinePayment()` را در حالت فعلی فایل تعیین کنید (چون TASKهای قبلی این فایل را لمس نکرده‌اند، شماره‌خط‌ها باید نزدیک به آنچه در این سند آمده باشد، ولی برای اطمینان دوباره چک کنید). سپس بدنهٔ متد را با این ساختار بازنویسی کنید — **الگوی دقیق `confirmCodPayment` را کپی کنید**، فقط بخش «تأیید با درگاه» (که مخصوص آنلاین است و در COD وجود ندارد) قبل از تراکنش باقی می‌ماند:

```php
public function verifyOnlinePayment(string $gatewayRef, /* ...بقیهٔ پارامترهای موجود... */): array
{
    $payment = $this->app->db()->fetchOne(
        'SELECT * FROM payments WHERE gateway_ref = ?',
        [$gatewayRef],
    );
    if ($payment === null) {
        throw new AppException('ERR_PAYMENT_NOT_FOUND', 'پرداخت یافت نشد', 404);
    }

    // Idempotency guard — دقیقاً الگوی confirmCodPayment خط ۳۳۷
    if ($payment['status'] === 'completed') {
        return [
            'status'     => 'already_completed',
            'order_id'   => $payment['order_id'],
            'payment_id' => $payment['id'],
        ];
    }

    // --- تأیید با درگاه (منطق موجود این بخش دست‌نخورده باقی می‌ماند؛ فراخوانی cURL/Zarinpal و
    //     هر منطق تعیین موفق/ناموفق‌بودن تراکنش، همان‌طور که در نسخهٔ فعلی هست، اینجا اجرا می‌شود) ---

    // اگر تأیید درگاه ناموفق بود، همان رفتار قبلی (throw/return) حفظ شود — این بخش را عوض نکنید،
    // فقط مسیر «موفق» را از اینجا به بعد داخل transaction() ببرید:

    return $this->app->db()->transaction(function () use ($payment, /* سایر متغیرهای لازم از نتیجهٔ تأیید درگاه */) {
        $orderId   = (int) $payment['order_id'];
        $paymentId = (int) $payment['id'];

        $this->app->db()->update('payments', [
            'status'       => 'completed',
            'completed_at' => date('Y-m-d H:i:s'),
            // ...سایر فیلدهایی که نسخهٔ فعلی آپدیت می‌کند (ref number, card mask, و...)...
        ], 'id = ?', [$paymentId]);

        $this->app->db()->update('orders', [
            'status'  => 'paid', // یا مقدار دقیقی که نسخهٔ فعلی استفاده می‌کند
            'paid_at' => date('Y-m-d H:i:s'),
        ], 'id = ?', [$orderId]);

        $this->app->db()->insert('order_status_history', [
            'order_id'    => $orderId,
            'from_status' => 'pending_payment', // یا مقدار دقیقی که نسخهٔ فعلی به‌عنوان status_from هاردکد کرده — این را
                                                  // با مقدار واقعیِ قبلیِ سفارش جایگزین کنید، نه رشتهٔ ثابت (رفع بدهی فنی
                                                  // مرتبط: «هاردکد status_from» که در بخش ۶ گزارش ارزیابی ذکر شده)
            'to_status'   => 'paid',
            'notes'       => 'پرداخت آنلاین تأیید شد',
            'created_at'  => date('Y-m-d H:i:s'),
        ]);

        return [
            'status'     => 'completed',
            'order_id'   => $orderId,
            'payment_id' => $paymentId,
        ];
    });
}
```
**نکتهٔ حیاتی دربارهٔ status_from هاردکد:** گزارش ارزیابی (بخش ۶) به‌صراحت اشاره می‌کند «وضعیت مبدأ status_from را هاردکد کرده». قبل از نوشتن کد بالا، با `grep -n "from_status\|status_from" src/Payment/PaymentService.php` مقدار فعلی هاردکدشده را پیدا کنید و به‌جایش، `status_from` واقعیِ سفارش را از همان `SELECT` اولیهٔ سفارش (که باید قبل از تراکنش یا در ابتدای تراکنش خوانده شود) بگیرید:
```php
$order = $this->app->db()->fetchOne('SELECT status FROM orders WHERE id = ? FOR UPDATE', [$orderId]);
// ...
'from_status' => $order['status'],
```
(`FOR UPDATE` هم اینجا قفل ردیفی سفارش را می‌گیرد — یک لایهٔ اضافیِ ایمنی در برابر دو callback هم‌زمان که با idempotency guard بالا ترکیب می‌شود.)

**گام تکمیلی — حذف بلوک تکراری «علامت‌گذاری پرداخت‌شده»:** گزارش ارزیابی می‌گوید این بلوک «سه بار در همان سرویس کپی شده». با `grep -n "status.*=.*'completed'\|'paid'" src/Payment/PaymentService.php` همهٔ محل‌های تکرار را پیدا کنید و آن‌ها را در یک متد خصوصی مشترک `markPaymentCompleted(int $paymentId, int $orderId, string $fromStatus): array` (که دقیقاً بدنهٔ تراکنشیِ بالا را در خود دارد) تجمیع کنید؛ `confirmCodPayment()` و `verifyOnlinePayment()` و هر نقطهٔ سوم، همگی این متد مشترک را صدا بزنند.

**تست‌ها:**
- تست انتگرال idempotency: `verifyOnlinePayment()` را دو بار پشت‌سرهم با همان `gatewayRef` فراخوانی کنید → بار دوم باید `status === 'already_completed'` برگرداند و **هیچ نوشتار دومی** در `order_status_history` ثبت نشود (assert کنید `COUNT(*) FROM order_status_history WHERE order_id = ?` برابر همان مقدار بعد از فراخوانی اول است).
- تست انتگرال تراکنش: با mock/stub کردن `Database::insert` برای پرتاب exception در نوشتار سوم (`order_status_history`) → assert کنید نوشتار اول و دوم (`payments`, `orders`) هم rollback شده‌اند (یعنی بعد از exception، `payments.status` هنوز `pending` است، نه `completed`).

**Definition of Done:** طبق پروتکل. کامیت: `[T-B07] تراکنشی و idempotent کردن verifyOnlinePayment + رفع status_from هاردکد`.

---

### T-B08 — یکپارچه‌سازی لغو سفارش (مسیر مشتری → `OrderStatusService`)
**فایل‌ها:** `src/Order/OrderRepository.php` (متد `cancelOrder`، خط ۳۳۷-۳۷۲)، `src/Order/Service/OrderStatusService.php` (متد `cancelOrder`، خط ۴۰+)

**مشکل:** دو پیاده‌سازی مستقل و ناهمگام برای لغو سفارش وجود دارد — یکی برای مسیر مشتری (`OrderRepository::cancelOrder`) با بازگرداندن موجودی از طریق `UPDATE` خام بدون قفل (خط ۳۶۴-۳۶۷)، و یکی برای مسیر ادمین (`OrderStatusService::cancelOrder`) که جدیدتر و از الگوی CQRS پیروی می‌کند. تغییر قواعد کسب‌وکار لغو (مثلاً «فقط تا ۱ ساعت بعد از ثبت قابل لغو است») باید در **دو جا** اعمال شود، وگرنه واگرا می‌شوند.

**گام ۱ — بررسی امضا:** ابتدا `OrderStatusService::cancelOrder()` را کامل `view` کنید (امضا فعلاً `cancelOrder(int $orderId, int $adminId, string $reason): void` است — پارامتر دوم `adminId` است، نه `customerId`؛ باید بررسی کنید آیا این متد فرض می‌کند فراخواننده همیشه ادمین است یا می‌تواند برای مشتری هم استفاده شود).

**گام ۲ — گسترش `OrderStatusService::cancelOrder()` برای پشتیبانی از مبدأ مشتری:**
امضا را طوری تغییر دهید که نوع مبدأ (ادمین/مشتری) و شناسهٔ مالکیت قابل‌تفکیک باشد:
```php
public function cancelOrder(int $orderId, string $actorType, int $actorId, string $reason): void
```
داخل بدنه، قبل از منطق فعلی، این چک مالکیت را اضافه کنید (فقط وقتی `$actorType === 'customer'`):
```php
if ($actorType === 'customer') {
    $order = $this->db->fetchOne('SELECT customer_id, status FROM orders WHERE id = ?', [$orderId]);
    if ($order === null || (int) $order['customer_id'] !== $actorId) {
        throw new AppException('ERR_NOT_FOUND', 'سفارش یافت نشد', 404);
    }
    if ($order['status'] !== 'pending_payment') {
        throw new AppException('ERR_INVALID_STATUS', 'فقط سفارش‌های در انتظار پرداخت قابل لغو توسط مشتری هستند', 400);
    }
}
```
(این دقیقاً همان دو قاعدهٔ کسب‌وکاری‌ای است که در `OrderRepository::cancelOrder` خط ۳۴۴-۳۵۱ وجود دارد — با انتقال به اینجا، منبع حقیقت واحد می‌شود.)

**گام ۳ — بررسی بازگرداندن موجودی در `OrderStatusService::cancelOrder`:** اگر این متد از قبل موجودی را (با الگوی امن `InventoryRepository::adjustStock` مثبت) برمی‌گرداند، کاری لازم نیست. اگر بازگرداندن موجودی در این متد وجود ندارد یا از UPDATE خام استفاده می‌کند، همان الگوی T-B01/T-B02 را اعمال کنید:
```php
$inventoryRepo = new InventoryRepository($this->app);
foreach ($items as $item) {
    $inventoryRepo->adjustStock((int) $item['product_id'], (int) $item['quantity'], true); // allowNegative=true چون بازگرداندن همیشه مثبت است، منفی‌شدن اینجا اصلاً معنا ندارد — می‌توانید false هم بگذارید چون difference مثبت است و هرگز negative نمی‌شود
}
```

**گام ۴ — حذف `OrderRepository::cancelOrder()` و بازتوجیه فراخوان‌های آن:**
با `grep -rn "->cancelOrder(" src/ tests/` همهٔ فراخوان‌های `OrderRepository::cancelOrder` را پیدا کنید (احتمالاً در یک `OrderController` سمت مشتری). هر فراخوانی را از
```php
$this->orderRepository->cancelOrder($orderId, $customerId, $reason);
```
به
```php
(new OrderStatusService($this->app->db()))->cancelOrder($orderId, 'customer', $customerId, $reason);
```
تغییر دهید (با import لازم `use App\Order\Service\OrderStatusService;`). سپس متد `cancelOrder()` را کامل از `OrderRepository.php` (خط ۳۳۷-۳۷۲) حذف کنید.

**تست‌ها:**
- تست رگرسیون: تمام تست‌های موجود برای لغو سفارش مشتری (`tests/Integration/Order/...`) باید بعد از این تغییر بدون ویرایش assertion سبز بمانند (رفتار بیرونی API نباید تغییر کند).
- تست جدید: مشتری تلاش کند سفارش مشتری *دیگری* را لغو کند → ۴۰۴ (نه ۴۰۳، تا وجود/عدم‌وجود سفارش برای مهاجم فاش نشود — طبق الگوی امنیتی موجود در همین متد).

**Definition of Done:** طبق پروتکل، به‌علاوه: `grep -rn "class OrderRepository" -A 5 src/Order/OrderRepository.php` تأیید کند این کلاس دیگر متد `cancelOrder` ندارد. کامیت: `[T-B08] یکپارچه‌سازی لغو سفارش زیر OrderStatusService`.


---

## بخش ۵ — فاز سه: فرانت فلاتر ادمین (Group C)

> **پیش‌نیاز:** T-A01 (وجود مجوز) و T-B03/T-B04 (بک‌اند آماده) باید قبل از این بخش انجام شده باشند.

### T-C01 — افزودن فیلد «فرسوده» به صفحهٔ قیمت‌گذاری برند
**فایل:** `lib/admin/screens/brand_pricing_screen.dart`
**ریپازیتوری (بدون تغییر، از قبل آماده):** `lib/admin/data/repositories/brand_pricing_repository.dart` — از قبل `rateType: 'used_battery'` و برچسب فارسی «باتری دست دوم» را پشتیبانی می‌کند؛ متد `createUnifiedRate({required int brandId, required String rateType, required int ratePerAmpere, ...})` عمومی است.

**گام ۱ — گسترش مدل داخلی صفحه:**
کلاس/رکورد داخلی که نرخ‌های هر برند را نگه می‌دارد (در کد فعلی چیزی شبیه `_BrandRateSnapshot` با فیلدهای `retailRate`/`wholesaleRate`) را با یک فیلد سوم گسترش دهید:
```dart
class _BrandRateSnapshot {
  final int? retailRate;
  final int? wholesaleRate;
  final int? usedBatteryRate;   // جدید
  // ...سازنده و copyWith را متناظر گسترش دهید...
}
```

**گام ۲ — واکشی نرخ سوم هنگام لود صفحه:**
هرجا که صفحه `_repo.getRates(rateType: 'retail', isCurrent: true)` و `_repo.getRates(rateType: 'wholesale', isCurrent: true)` را صدا می‌زند (معمولاً در یک متد `_loadRates()` یا داخل `initState`/`FutureBuilder`)، یک فراخوانی سوم موازی اضافه کنید:
```dart
final usedBatteryRates = await _repo.getRates(rateType: 'used_battery', isCurrent: true);
```
و نتیجه را در `_BrandRateSnapshot.usedBatteryRate` هر برند merge کنید (همان الگوی merge موجود برای retail/wholesale را برای فیلد سوم تکرار کنید).

**گام ۳ — نمایش در کارت هر برند:**
هرجا که `_RateTile` برای «خرده‌فروشی» و «عمده‌فروشی» رندر می‌شود (در body کارت برند)، یک `_RateTile` سوم اضافه کنید:
```dart
_RateTile(
  label: 'فرسوده',
  value: snapshot.usedBatteryRate,
  icon: Icons.battery_alert, // یا آیکن مشابه موجود در پروژه، هماهنگ با سبک بصری فعلی
),
```

**گام ۴ — افزودن فیلد ویرایش در دیالوگ:**
در دیالوگ ویرایش نرخ برند (متدی شبیه `_showEditRateDialog` یا `_editRates`)، کنار دو `TextField` موجود برای خرده/عمده، یک سومی اضافه کنید:
```dart
TextField(
  controller: _usedBatteryController,
  decoration: const InputDecoration(labelText: 'قیمت فرسوده (تومان)', border: OutlineInputBorder()),
  keyboardType: TextInputType.number,
  inputFormatters: [/* همان فرمتر جداکنندهٔ هزارگان که برای retail/wholesale استفاده شده */],
),
```
و در تابع ذخیره (`_saveRates` یا معادل)، بعد از دو فراخوانی موجود `createUnifiedRate` برای retail/wholesale، یک فراخوانی سوم اضافه کنید:
```dart
if (_usedBatteryController.text.isNotEmpty) {
  await _repo.createUnifiedRate(
    brandId: brand.id,
    rateType: 'used_battery',
    ratePerAmpere: AppFormatters.tomanToRial(int.parse(_usedBatteryController.text.replaceAll(',', ''))),
  );
}
```
(از همان تابع `AppFormatters.tomanToRial` استفاده کنید که در `_editPrice` صفحهٔ `wholesale_detail_screen.dart` هم استفاده می‌شود — واحد ورودی کاربر «تومان» است، ذخیرهٔ دیتابیس «ریال».)

**گام ۵ — پاک‌سازی کنترلر بعد از بستن دیالوگ:** مطمئن شوید `_usedBatteryController` هم مثل دو کنترلر دیگر در `dispose()` و بعد از بستن دیالوگ پاک/reset می‌شود.

**تست (Flutter widget test، اگر پروژه تست ویجت دارد؛ در غیر این صورت این گام را با یادداشت `[MANUAL-QA]` علامت بزنید):**
باز کردن دیالوگ ویرایش، وارد کردن مقدار در فیلد فرسوده، تأیید، و assert کردن سه فراخوانی به `createUnifiedRate` (mock ریپازیتوری) با `rateType` های `retail`، `wholesale`، `used_battery`.

**Definition of Done:** کد کامپایل می‌شود (`flutter analyze` بدون خطای جدید)، فیلد سوم در UI دیده می‌شود، کامیت: `[T-C01] افزودن فیلد قیمت فرسوده به صفحهٔ قیمت‌گذاری برند`.

---

### T-C02 — نرخ فرسودهٔ per-brand + شفافیت override در صفحهٔ فروش عمده
**فایل:** `lib/admin/screens/wholesale_detail_screen.dart`

**شاهد دقیق مشکل (۱) — نرخ سراسری:** `_loadSettings()` (خط ~۹۴-۱۱۷) فقط یک نرخ از `/admin/settings/used-battery-rate` می‌گیرد و در `_usedBatteryRate` ذخیره می‌کند؛ در `_checkout()` (خط ~۲۳۸-۲۴۰) همین یک عدد برای **همهٔ** ردیف‌ها به‌عنوان `used_battery_rate` ارسال می‌شود.

**شاهد دقیق مشکل (۲) — شفافیت override:** `_editPrice()` (خط ۱۸۰-۲۳۰ تقریباً) دیالوگی نشان می‌دهد که فقط قیمت فعلی قابل‌ویرایش را دارد، بدون نمایش قیمت مرجع سیستم برای مقایسه.

**گام ۱ — رفع نرخ سراسری:**
چون endpoint اختصاصی برای «نرخ فرسودهٔ یک برند» به‌صورت مجزا در این نقشه راه بک‌اند اضافه نشده (T-B03 نرخ را در لحظهٔ ثبت سفارش سمت سرور حل می‌کند)، دو راه داریم؛ **راه توصیه‌شده** (سازگارتر با معماری فعلی که برند-محور بودن باید سمت سرور authoritative باشد):
- فیلد `used_battery_rate` را از payload چک‌اوت **حذف کامل کنید** (دیگر آن را از `_usedBatteryRate` سراسری پر نکنید) تا بک‌اند (بعد از T-B03) خودش نرخ برند-محور صحیح را resolve کند:
  ```dart
  // در payload آیتم — این خط را حذف کنید:
  // 'used_battery_rate': i.usedBatteryAmperage != null ? _usedBatteryRate : null,
  ```
- برای اینکه مدیر **قبل از ثبت** بتواند مبلغ تقریبی اعتبار فرسوده را ببیند (تجربهٔ کاربری)، از endpoint موجود `GET /admin/brand-rates/summary` (همانی که `brand_pricing_repository.dart` مصرف می‌کند) برای واکشی نرخ فرسودهٔ هر برندِ محصولات حاضر در سبد عمده استفاده کنید، در متدی مثل `_loadUsedBatteryRatesForCurrentItems()` که بعد از انتخاب برند/محصولات صدا زده می‌شود:
  ```dart
  Future<int> _resolveDisplayRate(int brandId) async {
    final rates = await _brandPricingRepo.getRates(rateType: 'used_battery', isCurrent: true, brandId: brandId);
    if (rates.isNotEmpty) return rates.first.ratePerAmpere;
    return _usedBatteryRate; // fallback نمایشی به نرخ سراسری قدیمی، فقط برای پیش‌نمایش UI
  }
  ```
  و در محاسبهٔ `_totalUsedBatteryCredit` (خط ~۱۲۶-۱۳۴)، به‌جای ضرب همهٔ آیتم‌ها در یک `_usedBatteryRate`، برای هر آیتم نرخ اختصاصی برندش را (که در گام بالا resolve شد و باید در مدل `WholesaleItem` به‌عنوان فیلد جدید `displayUsedBatteryRate` کش شود) استفاده کنید. **مهم:** این عدد فقط **نمایشی/پیش‌نمایش** است؛ منبع حقیقتِ نهایی همیشه چیزی است که بک‌اند بعد از T-B03 محاسبه و ذخیره می‌کند — پس هرگز این عدد را در payload چک‌اوت به‌عنوان `used_battery_rate` نفرستید (مطابق گام قبلی، این کلید از payload حذف شده است).

**گام ۲ — افزودن شفافیت به `_editPrice()`:**
دیالوگ `_editPrice(int index)` را طوری گسترش دهید که علاوه بر فیلد قابل‌ویرایش، قیمت مرجع سیستم را هم (به‌صورت فقط-خواندنی) نشان دهد:
```dart
Future<void> _editPrice(int index) async {
  final item = _items[index];
  final systemPrice = item.systemComputedPrice; // فیلدی که باید هنگام افزودن آیتم به سبد از پاسخ بک‌اند (قیمت عمدهٔ محاسبه‌شده قبل از هر override) ذخیره شود — اگر این فیلد در مدل WholesaleItem وجود ندارد، آن را اضافه کنید
  final controller = TextEditingController(text: AppFormatters.formatCurrencyShort(item.price));
  await showDialog(
    context: context,
    builder: (_) => AlertDialog(
      title: const Text('ویرایش قیمت فاکتور (تومان)'),
      content: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          Text('قیمت پیشنهادی سیستم: ${AppFormatters.formatCurrencyShort(systemPrice)} تومان',
               style: Theme.of(context).textTheme.bodySmall?.copyWith(color: Colors.grey)),
          const SizedBox(height: 8),
          TextField(controller: controller, keyboardType: TextInputType.number, /* ...بقیهٔ decoration موجود... */),
        ],
      ),
      // ...بقیهٔ اکشن‌های موجود (لغو/تأیید) بدون تغییر...
    ),
  );
}
```
اگر `WholesaleItem` فیلد `systemComputedPrice` ندارد، آن را در مدل اضافه کنید و هنگام افزودن محصول به سبد (جایی که قیمت اولیهٔ عمده از بک‌اند/محلی خوانده می‌شود)، همان مقدار اولیه را در این فیلد هم کپی کنید (این مقدار هرگز بعد از override تغییر نمی‌کند — همیشه «قیمت پیش از دستکاری» را نشان می‌دهد).

**گام ۳ — نمایش نشانگر override‌شده در لیست:** در ردیف نمایش هر آیتم (خط ~۴۴۵)، اگر `item.price != item.systemComputedPrice`، یک برچسب کوچک (مثلاً `Chip` با متن «ویرایش دستی») کنار قیمت نشان دهید تا قبل از ثبت نهایی، مدیر وضوح کامل داشته باشد.

**گام ۴ — کنترل نمایش دکمهٔ ویرایش قیمت بر اساس مجوز:** اگر کاربر جاری مجوز `orders.price_override` را ندارد (این اطلاعات باید هنگام لاگین/بوت اپ در قالب لیست مجوزهای کاربر از بک‌اند دریافت و در یک provider/state سراسری نگه داشته شود — بررسی کنید آیا چنین مکانیزمی از قبل وجود دارد؛ اگر نه، این گام را با برچسب `[DEFER-TO-T-F]` علامت بزنید و به فاز ساختاری موکول کنید، چون افزودن یک سیستم مدیریت-مجوز سمت فرانت از صفر، خارج از اسکوپ این TASK است)، دکمهٔ `onTap: () => _editPrice(index)` (خط ۴۴۵) را غیرفعال/مخفی کنید تا کاربر بدون مجوز اصلاً وارد این جریان نشود (حتی اگر بک‌اند هم آن را رد می‌کند، تجربهٔ کاربری بهتر است بدون تلاش بی‌نتیجه باشد).

**Definition of Done:** `flutter analyze` تمیز، پیش‌نمایش نرخ per-brand در UI دیده می‌شود، دیالوگ ویرایش قیمت مرجع را نشان می‌دهد، کامیت: `[T-C02] نرخ فرسودهٔ per-brand + شفافیت override در صفحهٔ فروش عمده`.


---

## بخش ۶ — فاز چهار: پاکسازی کد مرده و امنیت باقی‌مانده (Group D)

### T-D01 — اتمیک‌سازی شمارندهٔ تلاش OTP
**فایل:** `src/Auth/OtpService.php`، متد `verify()`.

**شاهد دقیق:** خط ۱۳۹-۱۵۴ — چک (`if ($otp['attempts'] >= self::MAX_VERIFY_ATTEMPTS)`) و افزایش (`update(..., ['attempts' => $otp['attempts'] + 1], ...)`) دو عملیات جدا هستند (read-then-write)؛ بین این دو، درخواست هم‌زمان دیگری می‌تواند از همان مقدار قدیمی `attempts` عبور کند.

**گام:** خط ۱۳۹-۱۵۴ را با یک `UPDATE` شرطی اتمیک جایگزین کنید که هم چک و هم افزایش را در یک round-trip انجام می‌دهد:
```php
// Atomically check-and-increment attempts in a single guarded UPDATE.
$affected = ($this->db ?? $this->app->db())->update(
    'otp_codes',
    ['attempts' => $otp['attempts'] + 1],
    'id = ? AND attempts < ?',
    [$otp['id'], self::MAX_VERIFY_ATTEMPTS],
);
if ($affected === 0) {
    throw new AuthException(
        'ERR_OTP_ATTEMPTS_EXCEEDED',
        'تعداد تلاش‌ها بیش از حد مجاز است. لطفاً کد جدید درخواست دهید.',
        429,
    );
}
```
(`Database::update()` طبق امضای موجود در `src/Core/Database.php` مقدار `int` (تعداد ردیف تحت‌تأثیر) برمی‌گرداند — اگر `attempts` هنگام اجرای UPDATE از قبل به سقف رسیده باشد، شرط `attempts < ?` هیچ ردیفی را match نمی‌کند، `$affected === 0` می‌شود، و throw اتفاق می‌افتد — این رفتار دقیقاً معادل نسخهٔ قبلی است ولی بدون پنجرهٔ race.)

بقیهٔ متد (خط ۱۵۶ به بعد — چک `password_verify` و علامت‌گذاری `verified_at`) بدون تغییر باقی می‌ماند.

**تست:** تست انتگرال همزمانی مشابه T-E01 (نگاه کنید بخش ۷) — دو verify هم‌زمان با کد اشتباه وقتی `attempts = MAX_VERIFY_ATTEMPTS - 1` است → دقیقاً یکی باید موفق به افزایش شود و دیگری فوراً ۴۲۹ بگیرد (نه هر دو موفق).

**Definition of Done:** طبق پروتکل. کامیت: `[T-D01] اتمیک‌سازی شمارندهٔ تلاش OTP با UPDATE شرطی`.

---

### T-D02 — حذف کد مرده و stubهای ناتمام
**اقلام این TASK (هر کدام مستقل، می‌توانند در یک کامیت یا کامیت‌های جدا انجام شوند):**

**(الف) ماژول `Accounting`.**
شاهد: `src/Accounting/` فقط شامل `Service/BusinessTransactionService.php` است که ۸ کلاس را import می‌کند (`TransactionRequest`, `TransactionResult`, `BusinessTransactionRepository`, `FiscalPeriodRepository`, `IdempotencyRepository`, `AmpereLedgerWriter`, `RialLedgerWriter`, `FinancialUnitOfWork`) و **هیچ‌کدام در پروژه وجود ندارند** (تأیید شد با بررسی مستقیم فایل‌سیستم).
```bash
grep -rln "BusinessTransactionService" src/ tests/ config/ routes/ | grep -v "src/Accounting/Service/BusinessTransactionService.php"
```
اگر خروجی این دستور خالی بود (یعنی هیچ‌جای دیگر پروژه این کلاس را صدا نمی‌زند)، کل پوشهٔ `src/Accounting/` را حذف کنید:
```bash
git rm -r src/Accounting/
```
اگر خروجی خالی نبود (یعنی جایی این کلاس فراخوانی می‌شود)، این TASK را متوقف کنید و در `docs/arch/ROADMAP_EXECUTION_LOG.md` با برچسب `[BLOCKED]` علت را ثبت کنید — چون این حالت یعنی یک قابلیت production واقعی به یک ماژول خراب وابسته است و نیاز به بررسی محصولی دارد، نه صرفاً پاکسازی.

**(ب) `src/Auth/AuthRepository.php`.**
شاهد: `grep -rln "AuthRepository" src/` (به‌جز فایل خودش) صفر نتیجه می‌دهد.
```bash
grep -rln "AuthRepository" src/ tests/ | grep -v "src/Auth/AuthRepository.php"
```
اگر خروجی خالی بود، فایل را حذف کنید. اگر تستی مستقیماً این کلاس را instantiate می‌کند (بدون استفادهٔ واقعی در کد production)، آن تست را هم حذف کنید (چون تستی که فقط یک کلاس یتیم را پوشش می‌دهد، ارزش رگرسیونی ندارد).

**(ج) `src/Core/Middleware/CorrelationIdMiddleware.php`.**
شاهد: کلاس در `Application.php` هیچ‌جا ثبت نمی‌شود (بررسی شد: فقط در فایل خودش و در دو کامنت توضیحی در `RequestContext.php` و `AuditLogService.php` ذکر می‌شود). **دو گزینه، یکی را انتخاب کنید:**
- **گزینهٔ ۱ (توصیه‌شده — تکمیل به‌جای حذف):** چون `RequestContext` صراحتاً کامنت دارد «populated by the CorrelationIdMiddleware» و امکان دارد این قابلیت (correlation id سراسری برای ردیابی لاگ/تریس بین سرویس‌ها) مطلوب باشد، این میدلور را در `Application.php` کنار سایر `globalMiddlewares` (همان محلی که `RateLimitMiddleware`, `CorsMiddleware` ثبت می‌شوند) ثبت کنید:
  ```php
  $this->router->addGlobalMiddleware(new CorrelationIdMiddleware());
  ```
  سپس با اجرای کامل `composer test:integration` مطمئن شوید هیچ تستی که رفتار قبلی (بدون correlation id) را فرض کرده بود نمی‌شکند.
- **گزینهٔ ۲ (اگر تصمیم محصولی این است که این قابلیت لازم نیست):** فایل را حذف کنید و کامنت‌های ارجاع‌دهنده در `RequestContext.php`/`AuditLogService.php` را هم پاک/به‌روزرسانی کنید.

**پیش‌فرض این نقشه راه: گزینهٔ ۱** (فعال‌سازی، نه حذف) — چون correlation id سراسری مستقیماً به توانایی ردیابی حادثه در تولید کمک می‌کند و کد از قبل نوشته و آمادهٔ استفاده است؛ صرف فعال‌سازی، ارزان‌ترین راه افزایش قابلیت مشاهده‌پذیری است.

**(د) `SecurityHelper::rateLimit()` (پیاده‌سازی فایل‌محور قدیمی).**
شاهد: `src/Common/Helper/SecurityHelper.php` خط ۳۱ و ۱۸۸ — پیاده‌سازی محدودسازی نرخ مبتنی بر فایل (`storage/cache/rate_limits`)، موازی و مستقل از `RateLimitMiddleware` مبتنی بر Redis+Lua که در تولید فعال است.
```bash
grep -rln "SecurityHelper::rateLimit\|SecurityHelper::\$rateLimit" src/ | grep -v "src/Common/Helper/SecurityHelper.php"
```
اگر هیچ‌جا صدا زده نمی‌شود، دو متد (خط ۳۱ و منطق مرتبط با آن حدود خط ۱۸۸) را حذف کنید. اگر جایی هنوز صدا زده می‌شود (مثلاً یک اندپوینت قدیمی که هنوز به `RateLimitMiddleware` مهاجرت نکرده)، آن فراخوانی را به‌جای حذف کد، به `RateLimitMiddleware`/`RedisRateLimiter` مهاجرت دهید تا فقط **یک** پیاده‌سازی محدودساز نرخ در کل پروژه باقی بماند.

**Definition of Done (کل T-D02):** برای هر زیربخش (الف تا د)، `grep` تأییدی که هیچ رفرنس شکسته باقی نمانده + `composer quality` سبز. کامیت‌ها به‌ازای هر زیربخش جدا: `[T-D02a] حذف ماژول مردهٔ Accounting`، `[T-D02b] حذف AuthRepository یتیم`، `[T-D02c] فعال‌سازی CorrelationIdMiddleware`، `[T-D02d] یکپارچه‌سازی محدودساز نرخ روی پیاده‌سازی Redis`.

---

### T-D03 — هم‌ترازی مستندات و گیت‌های کیفیت
**اقلام:**

**(الف) سطح PHPStan در README.**
شاهد: `README.md` خط ۲۰ می‌گوید `# Level 5 PHPStan static analysis` در حالی‌که `phpstan.neon` واقعاً `level: 8` دارد.
```bash
sed -i 's/# Level 5 PHPStan static analysis/# Level 8 PHPStan static analysis/' README.md
```
سپس با `grep -n "Level 5\|level 5\|سطح ۵" README.md docs/` مطمئن شوید هیچ ارجاع باقی‌ماندهٔ دیگری به «سطح ۵» نیست.

**(ب) عدد ۱۸۳ هاردکد در دو فایل.**
شاهد دقیق: `tools/openapi-check.php` خط ۴۳ و ۵۱، و `tests/Architecture/OpenApiContractTest.php` — هر دو مقدار `183` را به‌صورت literal دارند به‌جای اینکه از خودِ فایل OpenAPI spec تولیدشده بشمارند.
در هر دو فایل، الگوی
```php
$expected !== 183
```
را با شمارش پویا از خود اسپک جایگزین کنید:
```php
$expectedCount = count($generatedSpec['paths'] ?? []); // یا معادل دقیق ساختار آرایهٔ اسپک این پروژه — قبل از این تغییر، ساختار خروجی تولیدکنندهٔ OpenAPI (احتمالاً src/Core/OpenApi/... یا tools/openapi-generate.php) را view کنید تا کلید دقیق مسیرها را پیدا کنید
$expected !== $expectedCount
```
(این تضمین می‌کند وقتی endpoint جدیدی در آینده اضافه شود، این عدد **خودکار** به‌روز شود و دیگر نیازی به یادآوریِ دستی «این عدد را هم عوض کن» نباشد — این خودش رفع یک بدهی مستندسازی بلندمدت است.)

**(ج) وابستگی بلااستفادهٔ `php-swagger`.**
```bash
grep -n "swagger" composer.json
composer why zircote/swagger-php 2>/dev/null || true   # یا نام دقیق پکیج که در composer.json دیده می‌شود
grep -rln "Swagger\\\\" src/ tools/
```
اگر هیچ فایلی از namespace این پکیج استفاده نمی‌کند، آن را حذف کنید:
```bash
composer remove <نام-دقیق-پکیج-یافت‌شده>
```

**(د) شمارش جدول در مستندات (۱۱۱ در برابر ۱۱۳ واقعی).**
```bash
grep -rn "111 جدول\|111 tables" docs/ README.md
```
عدد را با شمارش واقعی جایگزین کنید:
```bash
grep -c "^CREATE TABLE" database/ANBT_SCHEMA_REFERENCE.sql
```
و مقدار واقعی را در مستندات جایگزین ۱۱۱ کنید.

**Definition of Done:** `grep -rn "Level 5\|111 جدول" README.md docs/` صفر نتیجه، `composer why-not` یا معادل تأیید کند پکیج swagger حذف شده، هر دو فایل هاردکد ۱۸۳ اکنون پویا هستند و `php tools/openapi-check.php` هنوز PASS می‌دهد. کامیت: `[T-D03] هم‌ترازی مستندات با واقعیت کد (PHPStan level، شمارش جدول، حذف عدد هاردکد ۱۸۳، حذف وابستگی بلااستفاده)`.


---

## بخش ۷ — فاز پنج: تست‌های نهایی همگرا (Group E)

> این تست‌ها مکمل تست‌های داخل هر TASK بالا هستند و تمرکزشان روی **سناریوهای همزمانی/یکپارچگی end-to-end** است که نمی‌توان آن‌ها را در دل یک TASK کوچک‌تر جای داد.

### T-E01 — تست همزمانی کاهش موجودی
**فایل جدید:** `tests/Integration/Order/InventoryConcurrencyTest.php`

**سناریو:** یک محصول با `stock_quantity = 1` بسازید. دو درخواست خرید هم‌زمان (هرکدام `quantity = 1`) برای همان محصول با نوع سفارش `pos` (نه wholesale) شبیه‌سازی کنید.

**روش پیاده‌سازی همزمانی واقعی در PHPUnit (بدون نیاز به thread/process واقعی):** از دو اتصال PDO جدا به همان دیتابیس تست استفاده کنید تا `SELECT ... FOR UPDATE` واقعاً قفل ایجاد کند:
```php
public function testConcurrentPurchaseDoesNotOversell(): void
{
    $productId = $this->createTestProduct(['stock_quantity' => 1]);

    $conn1 = $this->createSecondaryConnection(); // اتصال PDO دوم، جدا از $this->db تست اصلی
    $conn2 = $this->createSecondaryConnection();

    $conn1->beginTransaction();
    $conn1->query("SELECT stock_quantity FROM products WHERE id = {$productId} FOR UPDATE");

    // تلاش دوم باید تا آزادشدن قفل conn1 بلاک شود — با یک timeout کوتاه شبیه‌سازی می‌کنیم
    $conn2->exec('SET SESSION innodb_lock_wait_timeout = 1');
    $blocked = false;
    try {
        $conn2->beginTransaction();
        $conn2->exec("UPDATE products SET stock_quantity = stock_quantity - 1 WHERE id = {$productId}");
        $conn2->commit();
    } catch (\PDOException $e) {
        $blocked = true; // انتظار: لاک تایم‌اوت یا deadlock
        $conn2->rollBack();
    }

    $conn1->exec("UPDATE products SET stock_quantity = stock_quantity - 1 WHERE id = {$productId}");
    $conn1->commit();

    $this->assertTrue($blocked, 'اتصال دوم باید هنگام تلاش هم‌زمان روی همان ردیف بلاک/رد شود');

    $finalStock = (int) $this->db->fetchColumn("SELECT stock_quantity FROM products WHERE id = {$productId}");
    $this->assertGreaterThanOrEqual(0, $finalStock, 'موجودی هرگز نباید بعد از این سناریو منفی شود (سفارش pos، نه wholesale)');
}
```
سپس یک تست سطح بالاتر که مستقیماً `OrderCommandService::createOrder()` را از دو thread شبیه‌سازی‌شده (با همین تکنیک دو-اتصالی، یا با فراخوانی `adjustStock` مستقیم از دو کانکشن) صدا می‌زند و assert می‌کند مجموع `quantity` فروخته‌شده هرگز از موجودی اولیه (برای سفارش‌های غیرعمده) بیشتر نمی‌شود.

**تست مکمل برای wholesale:** همان سناریو ولی `orderType = 'wholesale'` → انتظار: **بدون** بلاک‌شدن غیرمنتظره، موجودی نهایی می‌تواند منفی شود (رفتار عمدی، طبق T-B01).

**Definition of Done:** هر دو تست (pos و wholesale) سبز، کامیت: `[T-E01] تست همزمانی کاهش موجودی (pos ایمن، wholesale مجاز به منفی‌شدن)`.

---

### T-E02 — تست تراکنشی/idempotent بودن پرداخت
**فایل جدید:** `tests/Integration/Payment/OnlinePaymentIdempotencyTest.php`

پوشش دقیق دو سناریوی ذکرشده در T-B07 (idempotency + rollback روی شکست نوشتار سوم). این فایل باید هر دو تست را که در T-B07 مشخص شد، رسماً در قالب متدهای PHPUnit ثبت کند (اگر در T-B07 مستقیماً نوشته شدند، این TASK صرفاً بازبینی/تکمیل پوشش edge-caseهای زیر است):
- callback درگاه با `gatewayRef` نامعتبر (پرداختی که اصلاً وجود ندارد) → ۴۰۴، نه ۵۰۰.
- دو callback هم‌زمان (نه فقط پشت‌سرهم) با همان `gatewayRef` — با همان تکنیک دو-اتصالی T-E01 شبیه‌سازی کنید — دقیقاً یکی باید `status=completed` واقعی برگرداند و دیگری `already_completed`؛ در دیتابیس نباید دو ردیف `order_status_history` برای همان انتقال وضعیت ثبت شده باشد.

**Definition of Done:** طبق پروتکل. کامیت: `[T-E02] پوشش تست idempotency و تراکنش پرداخت آنلاین برای سناریوهای لبه`.

---

### T-E03 — تست جامع نرخ برند-محور فرسوده در سه مسیر
**فایل جدید:** `tests/Integration/Pricing/BrandUsedBatteryRateEndToEndTest.php`

یک سناریوی واحد را در **هر سه مسیر** (سبد مشتری، ثبت سفارش ادمین/عمده، دریافت باتری فرسوده) تکرار کنید تا از رگرسیون آینده در هرکدام جلوگیری شود:
```php
protected function setUp(): void
{
    parent::setUp();
    $this->brandA = $this->createTestBrand();
    $this->brandB = $this->createTestBrand();
    $this->registerBrandRate($this->brandA, 'used_battery', 400000); // ۴۰,۰۰۰ تومان
    $this->registerBrandRate($this->brandB, 'used_battery', 450000); // ۴۵,۰۰۰ تومان
    $this->productA = $this->createTestProduct(['brand_id' => $this->brandA]);
    $this->productB = $this->createTestProduct(['brand_id' => $this->brandB]);
}

public function testCartCalculatesDistinctRatesPerBrand(): void { /* ... */ }
public function testAdminOrderCreationStoresDistinctRatesPerBrand(): void { /* ... */ }
public function testUsedBatteryReceptionUsesBrandRateOnFallback(): void { /* ... */ }
public function testBrandWithoutSpecificRateFallsBackToGlobalSetting(): void { /* ... */ }
```

**Definition of Done:** هر ۴ متد سبز، کامیت: `[T-E03] تست end-to-end نرخ فرسودهٔ برند-محور در سبد/سفارش/دریافت`.

---

### T-E04 — تست override قیمت و ردگیری provenance
**فایل جدید:** `tests/Integration/Order/PriceOverrideAuditTest.php`

پوشش کامل ماتریس: {کاربر با/بدون مجوز} × {ارسال/عدم‌ارسال unit_price دستی} × {بررسی `pricing_source` نهایی} — ۴ حالت. به‌علاوه یک تست که مطمئن شود سفارش‌های **بدون** override (مسیر عادی) هم `pricing_source` را با مقدار `brand_rate` یا `legacy` (نه NULL) پر می‌کنند — یعنی از این پس هیچ ردیف جدید `order_items` نباید `pricing_source IS NULL` داشته باشد.

**Definition of Done:** طبق پروتکل. کامیت: `[T-E04] تست ماتریسی override قیمت و ردگیری pricing_source`.

---

## بخش ۸ — GATE-1: دروازهٔ خروج فاز بحرانی

**قبل از شروع بخش ۹ (فاز ساختاری)، همهٔ موارد زیر باید ✅ باشند — این چک‌لیست را عیناً در `docs/arch/ROADMAP_EXECUTION_LOG.md` کپی و تیک بزنید:**

- [ ] همهٔ TASKهای T-000 تا T-E04 با وضعیت Done ثبت شده‌اند.
- [ ] `composer quality && composer test:unit && composer test:integration` بدون هیچ خطا/شکست سبز است.
- [ ] `php tools/schema-drift.php` صفر انحراف گزارش می‌دهد.
- [ ] `php tools/openapi-check.php` همچنان PASS است (تعداد اندپوینت‌ها اکنون از خود اسپک خوانده می‌شود، نه هاردکد).
- [ ] هیچ‌کدام از دو ریسک «بحرانی» گزارش ارزیابی (کاهش غیراتمیک موجودی، تأیید پرداخت بدون تراکنش) دیگر در کد یافت نمی‌شود — تأیید نهایی با:
  ```bash
  grep -rn "stock_quantity = stock_quantity -" src/Order/ src/Common/
  # باید صفر نتیجه بدهد یا فقط داخل InventoryRepository::adjustStock دیده شود
  ```
- [ ] پوشش تست (`coverage.xml` تازه‌تولیدشده) نسبت به baseline ثبت‌شده در T-000 **افت نکرده** (افزایش، حتی جزئی، انتظار می‌رود چون تست‌های جدید اضافه شدند).
- [ ] یک اجرای دستی/QA کامل از دو جریان کسب‌وکاری اصلی این نقشه راه (ثبت نرخ فرسودهٔ اختصاصی دو برند از پنل ادمین، و ثبت یک فاکتور عمده با override دستی قیمت توسط کاربر مجاز) روی محیط staging انجام و نتیجه در لاگ ثبت شده.

**اگر همهٔ موارد ✅ بودند:** یک تگ Git بزنید: `git tag phase1-complete-<تاریخ>` و به بخش ۹ بروید.
**اگر نه:** به هیچ TASK بخش ۹/۱۰ ورود نکنید تا این چک‌لیست کامل شود.


---

## بخش ۹ — فاز شش: همراستاسازی ساختاری (Group F — معادل فاز ۲ گزارش ارزیابی، بازهٔ ۱ تا ۳ ماه)

> این تسک‌ها بزرگ‌تر و کمی باز-پایان‌تر از Group A-E هستند (چون طبیعتاً بازآرایی گسترده‌تری‌اند)، اما هرکدام **معیار پذیرش عددی و فایل‌های هدف مشخص** دارند تا همچنان بدون تصمیم طراحی اضافه قابل‌اجرا باشند. ترتیب اجرای T-F01 تا T-F08 الزامی نیست مگر وابستگی صریح ذکر شده باشد؛ می‌توانند موازی تقسیم شوند.

### T-F01 — تعریف DTO برای ایجاد سفارش (رفع «دو دنیای DTO»)
**هدف:** جایگزینی امضای هشت‌پارامتریِ `OrderCommandService::createOrder()` (که در T-B03 حتی یک پارامتر نهم `canOverridePrice` هم به آن اضافه شد) با یک DTO تغییرناپذیر، به سبک الگوی موجود `PricingContext` (`src/Pricing/DTO/PricingContext.php`).
**گام‌ها:**
1. کلاس جدید `src/Order/DTO/CreateOrderRequest.php` بسازید: property های readonly برای `adminId`, `customerId`, `items` (که خودش باید به یک `OrderItemRequest[]` تبدیل شود، نه آرایهٔ انجمنی خام), `orderType`, `usedBattery`, `discountAmount`, `payments`, `paymentMethod`, `canOverridePrice`.
2. یک factory static `CreateOrderRequest::fromArray(array $payload): self` با اعتبارسنجی ساختاری در سازنده (دقیقاً الگوی `PricingContext::forCartItem`/`forProduct`) اضافه کنید.
3. امضای `OrderCommandService::createOrder()` را به `createOrder(CreateOrderRequest $request): array` تغییر دهید؛ بدنهٔ متد را با `$request->adminId` و... جایگزین کنید.
4. `AdminOrderController::store()` را به‌روزرسانی کنید تا payload خام را با `CreateOrderRequest::fromArray($request->json())` بسازد.
5. تمام تست‌های موجود این مسیر را با `CreateOrderRequest` بازنویسی کنید (نه حذف).

**معیار پذیرش:** `grep -n "function createOrder" src/Order/Service/OrderCommandService.php` باید دقیقاً یک پارامتر (از نوع `CreateOrderRequest`) نشان دهد؛ همهٔ تست‌های integration مسیر سفارش سبزند.

---

### T-F02 — یکسان‌سازی مکانیزم تراکنش
**هدف:** طبق بخش ۶ گزارش، سه اصطلاح موازی تراکنش (`db()->transaction()`، `TransactionalExecutor` با retry روی deadlock، `beginTransaction/commit` دستی) وجود دارد.
**گام‌ها:**
1. `grep -rn "beginTransaction\(\)" src/` — همهٔ استفاده‌های دستی را پیدا کنید؛ هرکدام را به `$this->app->db()->transaction(fn () => ...)` یا `TransactionalExecutor` (هرکدام که retry روی deadlock لازم دارد، دومی) تبدیل کنید.
2. قاعدهٔ ثابت: عملیاتی که روی جدول‌های با تراکنش هم‌زمان بالا کار می‌کند (`orders`, `products`, `payments`) باید از `TransactionalExecutor` استفاده کند (نه `transaction()` ساده)، چون تنها این یکی retry روی deadlock دارد.
3. `StockAuditService` را به‌عنوان مرجع نگه دارید (از قبل درست است)؛ همان الگو را به `OrderRepository`, `OrderCommandService`, `PaymentService` (بعد از T-B02/B03/B07) تعمیم دهید.

**معیار پذیرش:** `grep -rn "beginTransaction()" src/` صفر نتیجه (به‌جز خود پیاده‌سازی `Database::transaction()`).

---

### T-F03 — تک‌کالینتی‌کردن Predis
**هدف:** رفع «سه اتصال جداگانهٔ Predis در هر فرآیند».
**گام‌ها:**
1. `grep -rn "new \\\\Predis\\\\Client\|new Predis" src/` همهٔ نقاط instantiation را پیدا کنید.
2. یک `RedisConnectionFactory` یا سرویس singleton در `ContainerFactory` ثبت کنید که یک `Predis\Client` واحد برمی‌گرداند.
3. سه مصرف‌کنندهٔ فعلی (کش، rate limiter، صف) را به تزریق همین سرویس مشترک مهاجرت دهید.

**معیار پذیرش:** تست جدید در `tests/Architecture/` که با بازتاب یا شمارش instantiation، فقط یک نقطهٔ `new Predis\Client(...)` در کل `src/` مجاز می‌شمارد (تست نگهبان به سبک همان‌هایی که در `tests/Architecture/` هست).

---

### T-F04 — سخت‌تر کردن `LayeringTest` برای پوشش `*Handler.php` و `sqlNNN`
**هدف:** رفع «دور زدن قفل‌سنج با نام‌گذاری Handler» — گزارش می‌گوید تست فعلی فقط `*Controller.php` را می‌سنجد، نه `*ControllerHandler.php` که SQL خام و منطق تجاری در آن‌ها انباشته شده (بعضی +۵۰۰ خط).
**گام‌ها:**
1. `tests/Architecture/LayeringTest.php` را باز کنید، الگوی چک فعلی روی `*Controller.php` را پیدا کنید.
2. یک قانون جدید اضافه کنید: فایل‌های `*ControllerHandler.php` مجاز به SQL خام مستقیم (`$this->app->db()->query`) **نیستند** مگر از طریق یک Repository تزریق‌شده — این قانون باید یک allowlist منجمد داشته باشد (دقیقاً الگوی «قفل‌سنج دوطرفه» موجود، خط کامنت آن را در `tests/Architecture/DependencyInjectionTest.php` ببینید: هر ورودی جدید به allowlist = شکست، هر پاکسازی بدون حذف از لیست = شکست).
3. سقف خط برای `*ControllerHandler.php` را (`مثلاً ۲۰۰` طبق قانون مستند خودِ پروژه) به‌عنوان یک تست جدید اضافه کنید که فایل‌های فراتر از سقف را در یک allowlist منجمد اولیه قرار می‌دهد (شامل فایل‌های بزرگ فعلی مثل `AdminPartnerAmpereControllerHandler.php`) — این allowlist باید **فقط کوچک شود**، هرگز بزرگ.
4. با ساخت این تست جدید، بلافاصله معلوم می‌شود کدام فایل‌ها باید در T-F05 شکسته شوند.

**معیار پذیرش:** تست جدید موجود است و روی وضعیت فعلی کد (با allowlist اولیه‌ای که همهٔ ناقضین امروز را نام می‌برد) سبز است — یعنی از این پس هیچ فایل *جدیدی* نمی‌تواند بدون ورود آگاهانه به allowlist از این قانون فرار کند.

---

### T-F05 — شکستن کلاس‌های خدا
**اهداف (بر اساس یافتهٔ گزارش، بخش ۵):**
- `OrderCommandService.php` (بعد از T-B03 حتی بزرگ‌تر شده — این طبیعی است چون منطق provenance/override اضافه شد؛ حالا وقت استخراج است): استخراج `resolveUnitPrice`+ منطق قیمت‌گذاری به یک کلاس `OrderPricingResolver` جدا؛ استخراج منطق موجودی/باتری فرسوده به `OrderInventoryAllocator` و `OrderUsedBatteryAllocator`.
- `AdminPartnerAmpereControllerHandler.php` (۵۳۹ خط، ۵ زیردامنه): تفکیک به ۵ کلاس/Handler جدا به ازای هر زیردامنه (حساب‌ها، فروش، تسویه، تراکنش‌ها، نرخ) — هرکدام کوچک‌تر از سقف T-F04.
- `AdminCustomerProfileControllerHandler.php` (۵۱۲ خط، ۱۳ اندپوینت): تفکیک بر اساس گروه‌بندی منطقی اندپوینت‌ها (مثلاً پروفایل پایه / آدرس‌ها / سفارش‌های مشتری / یادداشت‌ها).

**قاعدهٔ عمومی برای هر استخراج:** کلاس جدید باید تست واحد مستقل خودش را داشته باشد؛ کلاس اصلی (Handler) فقط delegate می‌کند؛ هیچ تغییر رفتاری بیرونی (API contract) مجاز نیست — این یک refactor خالص است، تست‌های integration موجود باید بدون تغییر assertion سبز بمانند.

**معیار پذیرش:** بعد از این TASK، `find src -name "*.php" -exec wc -l {} \; | sort -rn | head -5` باید نشان دهد بزرگ‌ترین فایل کمتر از ۳۵۰ خط است (عدد قابل تنظیم توسط تیم، اما باید مشخصاً کمتر از وضعیت فعلی ۵۶۲/۵۳۹/۵۲۰/۵۱۲ باشد).

---

### T-F06 — انتقال سرویس‌های دامنه‌ای از `Common` به ماژول‌های واقعی
**هدف:** رفع «چندمنظوره‌شدن Common» — گزارش صراحتاً `LedgerService`، `BrandRateService`، `CheckService`، و ۴ سرویس ممیزی را نام می‌برد.
**گام‌ها (به‌ازای هر سرویس):**
1. `BrandRateService` + `BrandRateRepository` → به `src/Pricing/Service/` و `src/Pricing/Repository/` منتقل شوند (این دقیقاً ماژول Pricing، همان leaf-context نمونه‌ای که خودِ گزارش آن را الگوی مرجع می‌داند). **توجه:** چون T-B02 تا T-B06 همگی `new BrandRateService($this->app)` را در چندین فایل صدا زده‌اند، بعد از انتقال namespace، همهٔ آن `use App\Common\Service\BrandRateService;` ها باید به `use App\Pricing\Service\BrandRateService;` تغییر کنند — با `grep -rln "Common\\\\Service\\\\BrandRateService" src/` همهٔ نقاط را پیدا و به‌صورت دسته‌ای (`sed -i`) به‌روزرسانی کنید.
2. `LedgerService` → به `src/Accounting/` (بعد از این‌که در T-D02 ماژول Accounting یا حذف یا کامل شد — اگر حذف شد، این سرویس باید یک ماژول `Ledger` مستقل جدید بگیرد، نه اینکه به یک ماژول خراب منتقل شود).
3. `CheckService` و ۴ سرویس ممیزی → بر اساس دامنهٔ واقعی‌شان (مثلاً اگر مربوط به سفارش‌اند، به `Order`؛ اگر مربوط به موجودی‌اند، به یک ماژول `Inventory` مستقل که فعلاً به‌طور ضمنی در `Common/Repository/InventoryRepository.php` است — این خودش نامزد استخراج به ماژول `Inventory` مستقل است).

**معیار پذیرش:** تعداد فایل‌های باقی‌ماندهٔ `src/Common/Service/` که «سرویس تمام‌عیار دامنه» هستند (نه واقعاً مشترک مثل `AuditLogService` عمومی) به صفر برسد؛ گراف importهای متقابل ماژول‌ها (طبق روش خودِ گزارش: `grep -rn "use App\\\\" src/ | wc -l` و تفکیک بر اساس ماژول مبدأ/مقصد) دوباره محاسبه و با عدد پایهٔ گزارش (۱۸ از ۴۶۷) مقایسه شود — انتظار می‌رود این عدد کمی افزایش یابد (چون Common واقعی‌تر و کوچک‌تر شد، وابستگی‌های واقعی که قبلاً پنهان بودند اکنون آشکار می‌شوند) و این افزایش، نشانهٔ **صداقت بیشتر گراف**، نه بدتر شدن معماری است — این نکته را در `docs/arch/ROADMAP_EXECUTION_LOG.md` توضیح دهید تا در سنجش بعدی نمرهٔ معماری بد تفسیر نشود.

---

### T-F07 — جانشینی واقعی `TokenIssuerInterface`
**هدف:** رفع نقض OCP/LSP مستند در گزارش — انتزاع `TokenIssuerInterface` تعریف، متصل (در Container)، و تست‌شده است ولی هیچ مصرف‌کنندهٔ تولیدی ندارد؛ میدلور Auth و کنترلرها مستقیماً `JwtService` را تزریق می‌کنند.
**گام‌ها:**
1. `grep -rn "JwtService \$" src/Auth/AuthMiddleware.php src/Admin/AdminMiddleware.php src/Auth/AuthControllerHandler.php` همهٔ نقاط تزریق مستقیم را پیدا کنید.
2. type-hint هرکدام را از `JwtService` به `TokenIssuerInterface` تغییر دهید (چون `JwtService` باید از قبل این اینترفیس را implement کند — تأیید کنید؛ اگر نه، این را هم اضافه کنید).
3. اطمینان از این‌که `ContainerFactory` این binding را از قبل دارد (طبق گزارش، بله).

**معیار پذیرش:** `grep -rn ": JwtService\b" src/` (به‌جز خودِ فایل `JwtService.php` و binding داخل `ContainerFactory`) صفر نتیجه.

---

### T-F08 — تجمیع نهایی تکرار SQL نرخ باتری مستعمل
**هدف:** بعد از T-B02, T-B03, T-B05, T-B06، عملاً همهٔ نقاط مصرف روی `BrandRateService` یکپارچه شده‌اند. این TASK یک ممیزی نهایی است تا مطمئن شویم چیزی جا نمانده.
```bash
grep -rn "used_battery_rates\|setting_group = 'used_battery'" src/ | grep -v "src/Common/Service/BrandRateService.php" | grep -v "src/Admin/AdminUsedBatteryControllerHandler.php"
```
(دو فایل استثنا: `BrandRateService.php` که خودش منبع حقیقتِ fallback است، و `AdminUsedBatteryControllerHandler.php` که مدیریت خودِ نرخ سراسری/«قسمت سراسری فرسوده» است — این دو **باید** باقی بمانند.) هر نتیجهٔ دیگری یعنی یک نقطهٔ فراموش‌شده که باید به `BrandRateService` مهاجرت کند.

**معیار پذیرش:** خروجی دستور بالا فقط شامل دو فایل استثنا باشد.


---

## بخش ۱۰ — فاز هفت: ارتقای سیستماتیک (Group G — معادل فاز ۳ گزارش ارزیابی، ۳ ماه به بعد)

### T-G01 — افزایش پوشش تست به ٪۵۵ سپس ٪۶۵ (نردبان هدف)
**وضعیت فعلی:** ٪۳۶٫۲۶ کل؛ `Payment`, `Partner`, `User`, `UsedBattery`, `Warranty`, `Notification`, `Upload`, `Accounting`, `Settings` صفر درصد؛ `Admin` تنها ٪۱۵٫۸.

**اولویت‌بندی اجباری (به همین ترتیب اجرا شود، نه به دلخواه):**
1. `Payment` — چون T-B07 همین ماژول را دستکاری کرده، اولین کاندید طبیعی برای پوشش است (ریسک بالا + تغییر تازه = بالاترین ارزش تست).
2. `Order` (بخش‌هایی که هنوز پوشش ندارند) — همان دلیل، بعد از T-B02/B03/B08.
3. `Partner` — طبق جدول ریسک گزارش، `AdminPartnerAmpereControllerHandler` (که در T-F05 شکسته می‌شود) صفر پوشش دارد؛ نوشتن تست باید **همزمان با** T-F05 انجام شود (هر کلاس استخراج‌شده با تست خودش متولد شود، نه بعداً).
4. باقی ماژول‌های صفر-درصد به ترتیب حجم کد نزولی.

**گام اجرایی برای هر ماژول:** `php vendor/bin/phpunit --coverage-text --filter=<ModuleNamespace>` را قبل و بعد اجرا کنید؛ برای هر متد عمومی بدون تست، حداقل یک تست happy-path + یک تست حالت خطای اصلی بنویسید. سقف پذیرش هر sprint/PR: پوشش کلی نباید نسبت به مرحلهٔ قبل **کاهش** یابد (گیت CI باید این را اجباری کند — نگاه کنید T-G02).

**معیار پذیرش نهایی این TASK:** `coverage.xml` کلی ≥ ٪۵۵ در پایان زیرفاز اول، ≥ ٪۶۵ در پایان زیرفاز دوم؛ هیچ ماژول دامنه‌ای (نه زیرساخت عمومی) صفر درصد باقی نماند.

---

### T-G02 — فعال‌سازی CI با هر چهار گیت
**هدف:** گزارش می‌گوید CI فقط در کامنت‌ها ارجاع دارد و در این بسته قابل‌راستی‌آزمایی نیست.
**گام‌ها:**
1. فایل CI (مثلاً `.github/workflows/ci.yml` — اگر وجود ندارد بسازید؛ اگر یک placeholder ناقص دارد، تکمیل کنید) با ۴ مرحلهٔ اجباری و **ترتیبی** (هرکدام fail کند، بعدی اجرا نشود):
   ```yaml
   - run: composer lint
   - run: composer stan
   - run: composer test:arch
   - run: composer test:unit
   - run: composer test:integration   # نیازمند سرویس MySQL + Redis در CI runner
   ```
2. یک گیت کاهش پوشش اضافه کنید: مقایسهٔ `coverage.xml` جدید با مقدار ثبت‌شده در آخرین `main` — اگر کمتر شد، CI fail کند (این خودش پیاده‌سازی مستقیم توصیهٔ گزارش دربارهٔ «بودجهٔ دوطرفهٔ» تست نگهبان DI است، تعمیم‌یافته به کل پوشش).
3. دیتابیس و Redis سرویس‌شده در CI runner (نه mock) — طبق همان معماری `tests/Integration` که از قبل به MySQL واقعی متکی است.

**معیار پذیرش:** یک PR آزمایشی با یک تست عمداً شکسته‌شده بسازید و تأیید کنید CI واقعاً قرمز می‌شود و merge را مسدود می‌کند؛ سپس تست را تعمیر و تأیید کنید سبز می‌شود.

---

### T-G03 — حذف تدریجی `excludePaths` از PHPStan
**هدف:** رساندن `Application.php`, `ContainerFactory.php`, `Logger.php`, سرویس‌های Redis به تحلیل سطح ۸ کامل.
**ترتیب اجرا (از کم‌ریسک‌ترین به پرریسک‌ترین):**
1. یکی از فایل‌های excluded را از لیست `phpstan.neon` حذف کنید.
2. `composer stan` را اجرا کنید و خطاهای گزارش‌شده را ببینید.
3. هر خطا را یا با type-hint دقیق‌تر رفع کنید، یا (فقط اگر واقعاً false-positive است — نادر) با `@phpstan-ignore-line` **موضعی** (نه فایل کامل) و توضیح کامنت رد کنید.
4. تکرار برای فایل بعدی.

**معیار پذیرش:** آرایهٔ `excludePaths` در `phpstan.neon` خالی است.

---

### T-G04 — ریزه‌سازی نهایی مرزهای دامنه (تکمیل T-F06)
بعد از T-F06، بررسی مجدد اینکه آیا `Common` واقعاً فقط زیرساخت خالص (Database wrapper، Helper های عمومی بدون منطق تجاری، Exception های پایه) باقی مانده است یا نه. اگر سرویس دامنه‌ای دیگری باقی مانده، همان الگوی T-F06 را تکرار کنید.

**معیار پذیرش:** بازبینی دستی لیست `src/Common/Service/*.php` — هر فایلی که «قاعدهٔ کسب‌وکار» دارد (نه صرفاً ابزار عمومی)، باید توجیه مکتوب داشته باشد چرا در Common مانده (مثلاً واقعاً بین ≥۳ ماژول دامنه‌ای مشترک است) یا منتقل شود.

---

### T-G05 — آمادگی برای رانتایم طولانی‌مدت Worker
**هدف:** رفع «وضعیت استاتیک ناسازگار» — `RequestContext`، هوک‌های استاتیک `Database::$queryListener`/`Database::$metricsCollector`، کش استاتیک `CheckService`.
**گام‌ها:**
1. `RequestContext` را از static holder به یک شیء تزریق‌شده (per-request، از طریق Container با scope `make()` نه `get()`) تبدیل کنید.
2. هوک‌های استاتیک `Database` را به فیلدهای instance تبدیل کنید (یا صراحتاً در ابتدای هر job در Worker، reset دستی آن‌ها را تضمین کنید — راه‌حل دوم سریع‌تر ولی شکننده‌تر است؛ راه‌حل اول توصیه می‌شود).
3. کش استاتیک `CheckService` را به یک کش instance-scoped یا Redis-backed (اگر باید بین request ها هم پایدار بماند) تبدیل کنید.
4. یک تست انتگرال جدید بنویسید که دو "job" شبیه‌سازی‌شده را در یک پروسهٔ PHP واحد (بدون بازنشانی کامل بین آن‌ها — دقیقاً شبیه‌سازی Worker) اجرا کند و assert کند state جاب اول به جاب دوم نشت نمی‌کند.

**معیار پذیرش:** تست بالا سبز؛ `grep -rn "private static\|public static \$" src/Core/ src/Common/` بازبینی دستی شود که هیچ static mutable state باقی‌مانده‌ای برای per-request data وجود ندارد.

---

### T-G06 — حاکمیت دانش معماری (ADR + سند نقشه راه یکپارچه)
**گام‌ها:**
1. پوشهٔ `docs/adr/` ایجاد کنید (اگر نیست).
2. برای هر تصمیم معماری مهم گرفته‌شده در این نقشه راه (مثلاً: «چرا override قیمت به‌جای رد بی‌صدا، خطای ۴۰۳ می‌دهد» از T-B03، یا «چرا Predis تک‌کالینت شد» از T-F03)، یک فایل ADR کوتاه (`docs/adr/0001-price-override-explicit-403.md` و مشابه) با فرمت استاندارد (Context / Decision / Consequences) بنویسید.
3. این سند اجرایی (`EXECUTION_ROADMAP.md`) را در `docs/arch/` کنار گزارش ارزیابی PDF نگه دارید تا سند مرجع بازآرایی مخزن باشد (توصیهٔ صریح بخش ۱۴ گزارش ارزیابی).
4. یک بخش «بازتولیدپذیری امتیاز» (طبق روش خودِ گزارش، پیوست پایانی PDF) را به‌عنوان اسکریپت اجرایی درآورید: `tools/rescore-architecture.php` که گراف importها، پوشش تست، excludePaths باقی‌مانده، و شمار تست‌های نگهبان را خودکار جمع‌آوری و در قالب همان جدول ۱۰-محوره چاپ می‌کند — این ابزار بعد از هر فاز اجرا می‌شود تا پیشرفت با یک «منحنی قابل‌رسم»، نه حس تیم، سنجیده شود (دقیقاً پیشنهاد پایانی خودِ گزارش ارزیابی).

**معیار پذیرش:** حداقل ۵ فایل ADR برای تصمیم‌های کلیدی این نقشه راه، `tools/rescore-architecture.php` قابل‌اجرا و خروجی‌دهنده.


---

## پیوست الف — نقشهٔ معکوس «فایل → TASK» (برای جست‌وجوی سریع)

| فایل | TASKهای مرتبط |
|---|---|
| `src/Common/Repository/InventoryRepository.php` | T-B01 |
| `src/Order/OrderRepository.php` | T-B02, T-B08 |
| `src/Order/Service/OrderCommandService.php` | T-B03, T-F01, T-F05 |
| `src/Admin/AdminOrderController.php` | T-B04 |
| `src/Cart/CartRepository.php`, `src/Cart/CartValidationService.php` | T-B05 |
| `src/UsedBattery/UsedBatteryControllerHandler.php` + Repository | T-B06 |
| `src/Payment/PaymentService.php` | T-B07 |
| `src/Order/Service/OrderStatusService.php` | T-B08 |
| `src/Auth/JwtService.php` | T-A02 |
| `src/Core/Middleware/RateLimitMiddleware.php` | T-A03 |
| `src/Core/Router.php` | T-A04 |
| `src/Auth/OtpService.php` | T-D01 |
| `src/Accounting/**`, `src/Auth/AuthRepository.php`, `src/Core/Middleware/CorrelationIdMiddleware.php`, `src/Common/Helper/SecurityHelper.php` | T-D02 |
| `README.md`, `tools/openapi-check.php`, `tests/Architecture/OpenApiContractTest.php`, `composer.json` | T-D03 |
| `src/Common/Service/BrandRateService.php`, `BrandRateRepository.php` | T-F06, T-F08 (مرجع در همهٔ Group B) |
| `lib/admin/screens/brand_pricing_screen.dart` | T-C01 |
| `lib/admin/screens/wholesale_detail_screen.dart` | T-C02 |

## پیوست ب — قالب پیام کامیت (تکرار برای رجوع سریع)
```
[<ID>] <خلاصه یک‌خطی به فارسی>

- <ریز تغییر ۱>
- <ریز تغییر ۲>

Refs: <بخش گزارش ارزیابی، در صورت وجود>
```

## پیوست ج — دستورهای تأیید (تکرار برای رجوع سریع)
```bash
composer lint
composer stan
composer test:arch
composer test:unit
composer test:integration
php tools/schema-drift.php
php tools/openapi-check.php
```

## پیوست د — چرا این ترتیب فازبندی؟
1. **Group A/B اول** چون مستقیماً پول و امنیت مشتری را لمس می‌کنند (ریسک‌های «بحرانی»/«بالا»ی جدول ریسک گزارش ارزیابی) — تأخیر در این‌ها هزینهٔ واقعی روزانه دارد.
2. **Group B پیش از C** چون فرانت (T-C02) به رفتار نهایی بک‌اند (T-B03/B04) وابسته است؛ اجرای معکوس یعنی فرانت باید دوباره‌کاری شود.
3. **Group D بعد از B نه قبلش** چون پاکسازی کد مرده و هم‌ترازی مستندات هیچ ریسک مالی ندارند و می‌توانند صبر کنند؛ اولویت‌دهی به آن‌ها قبل از B، منابع را از جایی که واقعاً مهم است منحرف می‌کند.
4. **GATE-1 قبل از Group F/G** چون بازآرایی ساختاری گسترده (شکستن کلاس‌های خدا، جابه‌جایی ماژول‌ها) روی کدی که هنوز باگ همزمانی/تراکنش دارد، ریسک را دوچندان می‌کند — گزارش ارزیابی هم دقیقاً همین توالی را در نقشهٔ راه خودش پیشنهاد داده (فاز ۱ برندگان سریع → فاز ۲ همراستاسازی ساختاری → فاز ۳ ارتقای سیستماتیک).
5. **Group G آخر** چون افزایش پوشش تست و فعال‌سازی CI روی کدی که هنوز در حال جابه‌جایی ساختاری بزرگ است (Group F)، باعث بازنویسی مکرر تست‌ها می‌شود — پوشش باید روی معماری *نهایی* هر ماژول نوشته شود.

---

*پایان سند. این نقشه راه باید در `docs/arch/EXECUTION_ROADMAP.md` مخزن نگه‌داری و بعد از هر TASK در `docs/arch/ROADMAP_EXECUTION_LOG.md` به‌روزرسانی شود.*
