# AGENTS.md ## Project Overview این مخزن مربوط به یک سوپرپلتفرم فارسی، RTL، API-First و ماژولار است. محصول نهایی قابلیت توسعه ماژول‌های زیر را دارد: - پیام‌رسان خصوصی، گروه و کانال - پلتفرم ساخت بات - مارکت‌پلیس چندفروشندگی - سامانه آگهی - تاکسی اینترنتی - ارسال مرسوله - خدمات منزل - رزرو آنلاین - کیف پول - پرداخت - اعتبار و اقساط - کمیسیون و تسویه در فاز نخست، سیستم باید روی هاست اشتراکی cPanel قابل نصب باشد؛ اما معماری آن باید برای انتقال آینده به VPS، Docker، Redis، Queue Worker دائمی، WebSocket اختصاصی و سرویس‌های مستقل آماده بماند. شرح جامع محصول در فایل زیر قرار دارد: ```text docs/product-vision.md ``` قبل از انجام تغییرات مهم، این فایل و مستندات مرتبط با ماژول موردنظر را مطالعه کن. --- ## Core Principles در تمام تغییرات، اصول زیر الزامی هستند: 1. معماری پروژه Modular Monolith باقی بماند. 2. هر قابلیت تجاری در ماژول مناسب خودش پیاده‌سازی شود. 3. هیچ ماژولی نباید مستقیماً داده‌های داخلی ماژول دیگری را تغییر دهد. 4. ارتباط بین ماژول‌ها از طریق Contract، Interface، Event، Job یا Service عمومی انجام شود. 5. منطق تجاری داخل Controller، Route، View یا Command نوشته نشود. 6. وابستگی به سرویس‌های خارجی باید از طریق Adapter و Interface باشد. 7. تمام عملیات مالی باید Transactional و Idempotent باشند. 8. هیچ رکورد مالی تأییدشده‌ای حذف یا بازنویسی نشود. 9. اطلاعات محرمانه نباید در سورس، تست، Fixture یا Log قرار گیرند. 10. تغییرات باید کوچک، قابل بررسی و محدود به Scope درخواست باشند. --- ## Required Workflow قبل از تغییر کد: 1. ساختار مخزن را بررسی کن. 2. فایل‌های مرتبط را مطالعه کن. 3. قوانین `AGENTS.md` موجود در مسیرهای فرزند را بررسی کن. 4. وضعیت Git را بررسی کن. 5. تغییرات موجود کاربر را حفظ کن. 6. وابستگی‌ها و الگوهای فعلی پروژه را شناسایی کن. 7. برای کارهای چندمرحله‌ای، یک برنامه کوتاه بنویس. 8. فایل‌هایی را که احتمالاً تغییر خواهند کرد مشخص کن. هنگام پیاده‌سازی: 1. از الگوهای موجود مخزن پیروی کن. 2. کمترین تغییر لازم را انجام بده. 3. از بازنویسی بخش‌های نامرتبط خودداری کن. 4. Migration، Test و Documentation مرتبط را هم‌زمان به‌روزرسانی کن. 5. خطاها را صریح مدیریت کن. 6. عملیات حساس را Log و Audit کن. 7. ورودی تمام APIها را Validation کن. 8. دسترسی و مالکیت منابع را بررسی کن. پس از پیاده‌سازی: 1. Formatter را اجرا کن. 2. Static Analysis را اجرا کن. 3. تست‌های مرتبط را اجرا کن. 4. در صورت امکان کل Test Suite را اجرا کن. 5. Migrationها را بررسی کن. 6. تغییرات نهایی را مرور کن. 7. فایل‌های تغییرکرده را اعلام کن. 8. تست‌های اجراشده و نتیجه آن‌ها را اعلام کن. 9. موارد اجرا‌نشده و دلیل آن را صریح بنویس. 10. بدهی فنی یا ریسک باقی‌مانده را گزارش کن. --- ## Do Not بدون درخواست صریح کاربر موارد زیر را انجام نده: - حذف فایل یا قابلیت موجود - تغییر معماری کل پروژه - تغییر Framework یا Database - تغییر API عمومی موجود - تغییر نام گسترده کلاس‌ها یا پوشه‌ها - نصب وابستگی بزرگ - اجرای Migration مخرب - حذف داده - تغییر فایل‌های محیط واقعی - قرار دادن Secret یا API Key - Force Push - بازنویسی Git History - Commit یا Push - تغییر تنظیمات Production - پیاده‌سازی قابلیت خارج از Scope از دستورهای مخرب مانند موارد زیر استفاده نکن: ```bash git reset --hard git clean -fd git checkout -- . rm -rf php artisan migrate:fresh php artisan db:wipe ``` مگر اینکه کاربر صریحاً همان عملیات را درخواست کرده باشد و اثر آن کاملاً مشخص باشد. --- ## Technology Baseline فناوری پایه پروژه: ```text Backend: Laravel Language: PHP Database: MySQL / MariaDB Frontend Web: Next.js or repository-defined frontend Mobile: Flutter Queue Phase 1: Database Queue Cache Phase 1: File or Database Scheduler: cPanel Cron Realtime Phase 1: Polling or external WebSocket provider Storage Phase 1: Local or S3-compatible driver API Style: REST, versioned Primary Locale: Persian Direction: RTL ``` نسخه واقعی فناوری‌ها را از فایل‌های پروژه مانند موارد زیر استخراج کن و حدس نزن: ```text composer.json composer.lock package.json package-lock.json pnpm-lock.yaml pubspec.yaml ``` --- ## Repository Structure ساختار هدف پروژه: ```text app/ ├── Core/ ├── Modules/ │ ├── Messenger/ │ ├── Bots/ │ ├── Marketplace/ │ ├── Classifieds/ │ ├── Ride/ │ ├── Delivery/ │ ├── HomeServices/ │ ├── Booking/ │ ├── Wallet/ │ ├── Payment/ │ ├── Credit/ │ ├── Commission/ │ └── Settlement/ └── Infrastructure/ ├── Sms/ ├── Payments/ ├── Realtime/ ├── Storage/ ├── Search/ └── Maps/ ``` اگر ساختار واقعی مخزن متفاوت است، بدون دلیل آن را جابه‌جا نکن. پیش از ایجاد ساختار جدید: 1. ساختار موجود را بررسی کن. 2. الگوی فعلی پروژه را پیدا کن. 3. سازگاری با Autoload را بررسی کن. 4. در صورت نیاز، تصمیم معماری را در ADR ثبت کن. --- ## Module Rules هر ماژول باید تا حد امکان اجزای زیر را در محدوده خودش نگه دارد: ```text Actions Contracts Data Domain Enums Events Exceptions Http Jobs Listeners Models Policies Providers Queries Resources Routes Services Tests database config lang module.json ``` وجود همه پوشه‌ها اجباری نیست؛ فقط پوشه‌های موردنیاز ساخته شوند. هر ماژول باید: - Namespace مستقل داشته باشد. - Migrationهای مستقل داشته باشد. - Permissionهای خودش را ثبت کند. - Routeهای خودش را ثبت کند. - تنظیمات خودش را ثبت کند. - تست‌های خودش را داشته باشد. - Manifest یا metadata مشخص داشته باشد. - وابستگی‌هایش را صریح اعلام کند. - امکان فعال یا غیرفعال‌شدن داشته باشد. - به مدل‌ها و جدول‌های خصوصی ماژول‌های دیگر وابستگی مستقیم نداشته باشد. --- ## Module Boundaries ماژول‌ها فقط از API یا Contract عمومی یکدیگر استفاده کنند. ممنوع: ```php Order::query()->where(...); ``` در داخل یک ماژول نامرتبط، وقتی `Order` متعلق به ماژول Marketplace است. ترجیح داده شود: ```php $order = $orderReader->findById($orderId); ``` یا: ```php event(new PaymentCompleted(...)); ``` ماژول دریافت‌کننده مسئول واکنش به Event مربوطه است. برای Contextهای مشترک مانند چت سفارش یا چت آگهی، از شناسه عمومی استفاده شود: ```text context_type context_id ``` Messenger نباید به جدول اختصاصی Marketplace، Classifieds، Ride یا Booking اتصال مستقیم داشته باشد. --- ## Laravel Conventions از قابلیت‌های استاندارد Laravel استفاده کن، مگر اینکه پروژه الگوی دیگری داشته باشد: - Form Request برای Validation - API Resource برای Response - Policy یا Gate برای Authorization - Service یا Action برای Use Case - Event و Listener برای Side Effect - Job برای پردازش غیرهم‌زمان - Database Transaction برای عملیات چندمرحله‌ای - Enum برای وضعیت‌های محدود - Value Object برای مفاهیم حساس - Config برای تنظیمات - Translation File برای متن قابل نمایش - Factory برای داده تست - Feature Test برای جریان‌های API Controller باید نازک باشد. نمونه قابل قبول: ```php public function store( CreateMessageRequest $request, SendMessageAction $action ): MessageResource { $message = $action->execute( actor: $request->user(), data: SendMessageData::fromRequest($request), ); return new MessageResource($message); } ``` منطق زیر نباید مستقیماً داخل Controller نوشته شود: - محاسبات مالی - تغییر موجودی - ارسال پیامک - فراخوانی درگاه - تعیین کمیسیون - ساخت چند رکورد مرتبط - تصمیم‌های پیچیده دسترسی - ارسال Webhook --- ## API Conventions تمام APIها باید نسخه‌بندی شوند: ```text /api/v1/... /api/bot/v1/... ``` Response موفق باید ساختار یکپارچه داشته باشد. نمونه: ```json { "success": true, "data": {}, "meta": {} } ``` Response خطا: ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "اطلاعات واردشده معتبر نیست.", "fields": {} }, "request_id": "01J..." } ``` قواعد API: - از کد HTTP مناسب استفاده کن. - پیام داخلی Exception را مستقیماً به کاربر نمایش نده. - پاسخ Validation یکپارچه باشد. - APIهای لیستی Pagination داشته باشند. - تاریخچه پیام از Cursor Pagination استفاده کند. - شناسه عمومی از UUID یا ULID استفاده کند. - ID ترتیبی داخلی را در API افشا نکن. - تمام تاریخ‌ها در API با ISO 8601 بازگردانده شوند. - تاریخ در دیتابیس میلادی و UTC ذخیره شود. - تبدیل شمسی فقط در لایه نمایش انجام شود. --- ## Database Rules قواعد دیتابیس: - همه تغییرات Schema با Migration انجام شوند. - Migration موجود و اجراشده را بازنویسی نکن. - برای اصلاح Schema، Migration جدید بساز. - پول به‌صورت Integer ذخیره شود. - از Float برای مبلغ استفاده نکن. - Constraintهای مهم در دیتابیس نیز اعمال شوند. - Unique Indexهای لازم تعریف شوند. - Foreign Key فقط در صورتی استفاده شود که با مرز ماژول‌ها سازگار باشد. - ستون‌های پرتکرار در فیلتر و مرتب‌سازی Index شوند. - JSON فقط برای داده‌های واقعاً پویا استفاده شود. - داده‌های قابل گزارش را بدون دلیل داخل JSON ذخیره نکن. - Soft Delete فقط زمانی استفاده شود که نیاز تجاری مشخصی وجود دارد. - وضعیت‌های حساس با Enum یا Constraint کنترل شوند. Migration مخرب باید: 1. Backward-compatible باشد. 2. مسیر Backfill داشته باشد. 3. خطر از دست رفتن داده را توضیح دهد. 4. بدون درخواست صریح روی محیط Production اجرا نشود. --- ## Financial Rules این قواعد برای Wallet، Payment، Credit، Commission و Settlement اجباری هستند: - موجودی فقط یک ستون قابل تغییر روی User نیست. - دفتر کل مالی منبع اصلی حقیقت است. - عملیات مالی در Database Transaction اجرا شوند. - عملیات خارجی داخل Transaction طولانی اجرا نشوند. - Callbackهای پرداخت Idempotent باشند. - Verify پرداخت فقط در سمت سرور انجام شود. - مبلغ Callback با مبلغ ثبت‌شده مقایسه شود. - Currency و Amount کنترل شوند. - تراکنش موفق دوباره اعمال نشود. - رکورد مالی تأییدشده حذف یا ویرایش نشود. - اصلاح مالی با Entry معکوس یا تعدیلی انجام شود. - شناسه مرجع یکتا ثبت شود. - Race Condition با Lock مناسب کنترل شود. - Idempotency Key برای عملیات قابل تکرار استفاده شود. - تمام تغییرات مالی Audit شوند. - اطلاعات محرمانه درگاه در Log ذخیره نشوند. هر قابلیت مالی جدید باید تست‌های زیر را داشته باشد: - موفقیت - شکست - Callback تکراری - مبلغ نامعتبر - تراکنش هم‌زمان - Rollback - بازپرداخت - دسترسی غیرمجاز --- ## Payment Gateway Rules منطق تجاری نباید مستقیماً به یک درگاه خاص وابسته باشد. تمام درگاه‌ها باید Contract مشترک را پیاده‌سازی کنند. حداقل عملیات: ```php interface PaymentGatewayInterface { public function request( PaymentRequestData $data ): PaymentRequestResult; public function verify( PaymentVerificationData $data ): PaymentVerificationResult; public function refund( RefundRequestData $data ): RefundResult; } ``` هر Provider باید: - Config مستقل داشته باشد. - Sandbox داشته باشد، در صورت پشتیبانی Provider. - Timeout مشخص داشته باشد. - Exceptionهای خارجی را به Exception داخلی تبدیل کند. - داده حساس را Mask کند. - Request و Response لازم را با Redaction ثبت کند. - تست Fake یا Mock داشته باشد. - به‌صورت مستقل فعال یا غیرفعال شود. هیچ کلید واقعی در کد یا Fixture قرار نده. --- ## SMS and IPPanel Rules SMS باید از طریق `SmsProviderInterface` ارسال شود. هیچ بخش تجاری نباید مستقیماً `IpPanelSmsProvider` را فراخوانی کند. قابلیت‌های Provider: - ارسال متن عادی - ارسال Pattern - ارسال OTP - Timeout - Retry محدود - Log امن - ثبت شناسه پیام - Rate Limit - جلوگیری از ارسال تکراری - Mock Provider برای تست Patternها باید از تنظیمات یا دیتابیس خوانده شوند و داخل Serviceهای تجاری Hardcode نشوند. نمونه فراخوانی صحیح: ```php $sms->sendPattern( mobile: $mobile, patternCode: $pattern->code, parameters: [ 'code' => $otp, ], ); ``` API Key، Sender و تنظیمات IPPanel فقط از Config و Environment خوانده شوند. --- ## Messenger Rules Messenger یک ماژول مرکزی اما مستقل است. انواع Conversation اولیه: ```text private group channel bot support order listing ride service booking ``` انواع Message اولیه: ```text text image video audio voice file location contact poll product listing order booking payment bot system ``` قواعد: - پیام قبل از انتشار Realtime در دیتابیس ثبت شود. - دیتابیس منبع اصلی حقیقت باشد. - WebSocket تنها کانال انتقال رویداد باشد. - تاریخچه پیام با Cursor Pagination دریافت شود. - دسترسی عضو به Conversation بررسی شود. - ارسال پیام در Channel فقط با Permission مجاز باشد. - ویرایش و حذف پیام محدودیت زمانی یا Permission مشخص داشته باشد. - فایل‌ها قبل از ذخیره Validation شوند. - پیام حذف‌شده طبق سیاست سیستم Tombstone یا Soft Delete شود. - Read Receipt باید برای گفتگوهای بزرگ قابل مقیاس طراحی شود. - شمارنده خوانده‌نشده نباید با Queryهای بسیار سنگین محاسبه شود. - اطلاعات Presence موقت و قابل جایگزینی باشد. - Messenger نباید مستقیماً منطق سفارش، آگهی، سفر یا رزرو را اجرا کند. --- ## Realtime Rules Realtime باید Driver-Based باشد. Driverهای قابل پشتیبانی: - Polling - Long Polling - External WebSocket - Pusher-compatible - Laravel Reverb در آینده نسخه cPanel نباید به Worker دائمی یا WebSocket داخلی وابسته باشد. قواعد: - Business Logic مستقل از Realtime Driver باشد. - شکست Realtime نباید باعث از دست رفتن پیام شود. - Event بعد از Commit منتشر شود. - Payloadها نسخه‌بندی شوند. - داده محرمانه در Channel عمومی منتشر نشود. - Channel Authorization اجباری باشد. - امکان Replay یا دریافت داده ازدست‌رفته از API وجود داشته باشد. --- ## Bot Platform Rules توکن بات: - باید با CSPRNG تولید شود. - نسخه خام آن فقط هنگام ایجاد یا Rotation نمایش داده شود. - در دیتابیس فقط Hash ذخیره شود. - در Log نمایش داده نشود. - قابل لغو و Rotation باشد. Bot API باید: - نسخه‌بندی شود. - Rate Limit داشته باشد. - Scope و Permission داشته باشد. - Webhook Signature داشته باشد. - Secret Header اختیاری داشته باشد. - Update ID یکتا داشته باشد. - Delivery Retry محدود داشته باشد. - Duplicate Delivery را قابل تشخیص کند. - وضعیت Webhook را ثبت کند. - Timeout خارجی داشته باشد. - SSRF Protection داشته باشد. بات نباید بدون Permission: - به پیام‌های خصوصی نامرتبط دسترسی داشته باشد. - اطلاعات موبایل کاربران را بخواند. - کیف پول را تغییر دهد. - پرداخت را تأیید کند. - در گروه یا کانال پیام ارسال کند. --- ## cPanel Compatibility تا زمانی که مستندات پروژه مهاجرت به VPS را اعلام نکرده‌اند، این محدودیت‌ها را رعایت کن: - Redis اجباری نباشد. - Supervisor اجباری نباشد. - Docker اجباری نباشد. - WebSocket داخلی اجباری نباشد. - Queue پیش‌فرض بتواند Database باشد. - Cache پیش‌فرض بتواند File یا Database باشد. - Scheduler با یک Cron استاندارد کار کند. - Jobهای صف بتوانند با اجرای کوتاه و دوره‌ای پردازش شوند. - فایل‌ها بتوانند در Storage محلی ذخیره شوند. - نصب با دسترسی معمول cPanel امکان‌پذیر باشد. - دستورات نصب به SSH دائمی وابسته نباشند. از طراحی‌هایی که تنها با Process دائمی کار می‌کنند اجتناب کن. برای قابلیت‌های نیازمند Process دائمی، Driver جایگزین یا Degraded Mode ارائه کن. --- ## Security Rules در تمام تغییرات موارد زیر را بررسی کن: - Authentication - Authorization - Ownership - IDOR - Mass Assignment - Validation - SQL Injection - XSS - CSRF برای صفحات وب - Rate Limiting - Brute Force - OTP Abuse - File Upload - MIME Spoofing - Path Traversal - SSRF - Open Redirect - Webhook Forgery - Replay Attack - Race Condition - Sensitive Data Exposure - Log Injection - Insecure Direct File Access فایل آپلودی باید بر اساس محتوای واقعی و MIME معتبر بررسی شود، نه فقط Extension. URL خارجی برای Webhook، Import یا Bot باید در برابر SSRF محافظت شود. --- ## Logging and Audit Log فنی و Audit Log تجاری از هم جدا باشند. در Log قرار نده: - Password - OTP کامل - Access Token - Bot Token - API Key - اطلاعات کارت - کل Payload حساس درگاه - Headerهای احراز هویت - فایل خصوصی - متن خصوصی پیام، مگر برای Debug کنترل‌شده و بدون Production عملیات زیر باید Audit شوند: - ورود مدیر - تغییر Permission - مسدودسازی کاربر - تأیید یا رد آگهی - تغییر تنظیمات مالی - بازپرداخت - اصلاح کیف پول - تسویه - ایجاد یا Rotation توکن بات - مشاهده داده حساس - حذف مدیریتی پیام یا محتوا --- ## Frontend Rules رابط کاربری: - فارسی و RTL باشد. - Mobile First باشد. - متن‌ها Hardcode نشوند. - حالت Loading، Empty، Error و Offline در نظر گرفته شود. - دسترسی کاربر در UI و Backend هر دو بررسی شود. - منطق امنیتی فقط به مخفی‌کردن دکمه وابسته نباشد. - API Client یکپارچه باشد. - Error Handling یکپارچه باشد. - فرم‌ها Validation سمت کلاینت و سرور داشته باشند. - تاریخ در API میلادی باشد و در UI قابل نمایش شمسی باشد. صفحه اصلی برنامه Messenger است و تب‌های زیر را دارد: ```text خصوصی گروه‌ها کانال‌ها خدمات ``` ماژول‌ها باید Service Entry خود را از Registry ثبت کنند و UI نباید فهرست خدمات را Hardcode کند. --- ## Testing Requirements هر تغییر رفتاری باید تست داشته باشد. ترجیح تست: 1. Feature Test برای Use Case 2. Unit Test برای منطق مستقل 3. Integration Test برای Adapter 4. End-to-End Test فقط برای جریان‌های حیاتی تست‌ها نباید: - به اینترنت واقعی وابسته باشند. - پیامک واقعی ارسال کنند. - پرداخت واقعی ایجاد کنند. - به ساعت واقعی وابستگی شکننده داشته باشند. - از Secret واقعی استفاده کنند. - به ترتیب اجرای تست‌ها وابسته باشند. برای سرویس‌های خارجی از Fake یا Mock استفاده کن. حداقل سناریوهای تست: - مسیر موفق - Validation نامعتبر - دسترسی غیرمجاز - مالکیت نامعتبر - داده تکراری - اجرای هم‌زمان - شکست Provider - Retry - Idempotency - Rollback --- ## Commands قبل از اجرای دستورات، نسخه و ابزارهای واقعی پروژه را بررسی کن. دستورات متداول Laravel: ```bash composer install php artisan key:generate php artisan migrate php artisan db:seed php artisan test php artisan route:list php artisan config:clear php artisan cache:clear ``` فرمت کد PHP: ```bash ./vendor/bin/pint ``` تحلیل ایستا، در صورت نصب: ```bash ./vendor/bin/phpstan analyse ``` تست Frontend، در صورت وجود: ```bash npm test npm run lint npm run typecheck npm run build ``` دستورهایی را که در پروژه وجود ندارند اجرا نکن. قبل از اضافه‌کردن ابزار جدید، بررسی کن ابزار مشابهی از قبل نصب نشده باشد. --- ## Test Execution Policy برای تغییر کوچک: 1. تست مستقیم فایل یا Feature مرتبط 2. تست ماژول مرتبط 3. Formatter برای تغییر بین‌ماژولی یا حساس: 1. تست‌های مرتبط 2. کل Backend Test Suite 3. Static Analysis 4. Frontend Lint و Typecheck 5. بررسی Migration برای تغییر مالی، احراز هویت، Permission یا پیام‌رسان: - فقط به تست واحد اکتفا نکن. - حداقل یک Feature Test برای جریان کامل اضافه کن. اگر تستی قابل اجرا نبود، دقیقاً اعلام کن: - کدام دستور اجرا نشد. - چرا اجرا نشد. - چه چیزی همچنان تأیید نشده است. --- ## Documentation Requirements برای قابلیت جدید، حسب نیاز موارد زیر را به‌روزرسانی کن: ```text README.md docs/product-vision.md docs/architecture/ docs/adr/ docs/api/ docs/modules/ docs/deployment/ .env.example ``` هر Adapter خارجی باید مستند کند: - متغیرهای محیطی - نحوه فعال‌سازی - Sandbox - Timeout - Retry - Error Mapping - Webhook یا Callback - روش تست هر ماژول باید یک README کوتاه داشته باشد که شامل موارد زیر باشد: - هدف - مرز مسئولیت - وابستگی‌ها - API عمومی - Eventهای منتشرشده - Eventهای مصرف‌شده - Permissionها - دستورات - تست‌ها --- ## Architecture Decision Records برای تصمیم‌های مهم معماری ADR ایجاد کن. نمونه مسیر: ```text docs/adr/0001-modular-monolith.md ``` ADR لازم است وقتی: - Dependency جدید و مهم اضافه می‌شود. - مرز ماژول تغییر می‌کند. - شیوه ذخیره داده حساس تغییر می‌کند. - Driver زیرساختی انتخاب می‌شود. - API عمومی تغییر می‌کند. - فناوری اصلی جایگزین می‌شود. - تصمیمی با Trade-off بلندمدت گرفته می‌شود. هر ADR شامل: - Context - Decision - Alternatives - Consequences - Migration Plan باشد. --- ## Dependency Policy قبل از نصب Package جدید: 1. بررسی کن قابلیت با ابزارهای موجود قابل انجام نباشد. 2. وضعیت نگهداری Package را بررسی کن. 3. سازگاری نسخه را بررسی کن. 4. License را بررسی کن. 5. اثر آن بر cPanel را بررسی کن. 6. دلیل استفاده را ثبت کن. برای قابلیت ساده Package بزرگ اضافه نکن. وابستگی جدید را بدون استفاده واقعی نصب نکن. --- ## Code Quality کد باید: - خوانا باشد. - نام‌گذاری صریح داشته باشد. - کوچک و قابل تست باشد. - از Side Effect پنهان دور باشد. - از Boolean Parameterهای مبهم دور باشد. - از Serviceهای همه‌کاره دور باشد. - از God Class دور باشد. - از Traitهای بزرگ و چندمنظوره دور باشد. - از Query تکراری و N+1 جلوگیری کند. - Exceptionهای Domain مشخص داشته باشد. - Typeهای ورودی و خروجی مشخص داشته باشد. از Comment برای توضیح «چرا» استفاده کن، نه تکرار «چه کاری» که کد واضح انجام می‌دهد. --- ## Backward Compatibility بدون درخواست صریح: - API موجود را نشکن. - نام فیلد Response را تغییر نده. - وضعیت‌های موجود را حذف نکن. - Event موجود را تغییر ناسازگار نده. - Migration مخرب ایجاد نکن. - تنظیمات محیطی فعلی را حذف نکن. در صورت نیاز به تغییر ناسازگار: 1. نسخه جدید API ایجاد کن. 2. دوره Deprecation مشخص کن. 3. Migration Plan بنویس. 4. مستندات را به‌روزرسانی کن. --- ## Completion Criteria هیچ تسکی را فقط با ایجاد فایل یا نوشتن TODO کامل اعلام نکن. یک تسک زمانی کامل است که: - قابلیت درخواست‌شده پیاده‌سازی شده باشد. - Validation اجرا شود. - Authorization اجرا شود. - Error Handling وجود داشته باشد. - تست مرتبط اضافه شده باشد. - تست‌های مربوط موفق باشند. - Formatter اجرا شده باشد. - مستندات ضروری به‌روزرسانی شده باشند. - Secret وارد کد نشده باشد. - تغییر خارج از Scope انجام نشده باشد. - نتیجه قابل توضیح و بررسی باشد. --- ## Final Response Format در پایان هر کار، پاسخ را با این ساختار ارائه کن: ```text Summary - چه چیزی پیاده‌سازی شد Changed Files - فایل‌های مهم ایجاد یا ویرایش‌شده Tests - دستورات اجراشده - نتیجه هر دستور Database - Migrationهای ایجادشده - ملاحظات اجرا Security - کنترل‌های امنیتی مهم Remaining Work - موارد خارج از Scope - بدهی‌های فنی - ریسک‌های باقی‌مانده ``` از ادعای اجرای تست یا موفقیت Build بدون اجرای واقعی آن خودداری کن. --- ## Source of Truth Priority در صورت تعارض، ترتیب اولویت منابع پروژه به این صورت است: 1. درخواست صریح فعلی کاربر 2. نزدیک‌ترین `AGENTS.md` به فایل در حال تغییر 3. `AGENTS.md` ریشه 4. ADRهای پذیرفته‌شده 5. مستندات ماژول 6. `docs/product-vision.md` 7. الگوهای موجود و تست‌شده کد 8. README عمومی در صورت تعارض جدی که تصمیم اشتباه می‌تواند باعث از دست رفتن داده، مشکل امنیتی یا شکستن API شود، تغییر پرخطر را انجام نده و مسئله را صریح گزارش کن.