‫تثبیت استانداردهای معماری با فایل copilot-instructions.md در سطح مخزن

# راهنما و استانداردهای مهندسی پروژه C# / .NET

## اصول و ویژگی‌های زبان C#
- قابلیت Nullable Reference Types همیشه فعال است؛ کدهای تولیدی نباید هشدار NRT داشته باشند.
- از امکانات مدرن C# (شامل Primary Constructors، Collection Expressions، Pattern Matching و File-scoped Namespaces) استفاده کن.
- از انتزاع‌های غیرضروری و پیچیدگی‌های ساختگی (Over-engineering) بپرهیز؛ خوانایی بر ترفندهای هوشمندانه ارجحیت دارد.
- از الگوی Guard Clauses و Fail-Fast برای اعتبارسنجی پارامترهای ورودی استفاده کن.

## معماری و طراحی API
- هرگز موجودیت‌های پایگاه داده (EF Core Entities) را مستقیماً از Controller یا Minimal APIها برنگردان.
- برای تمام قراردادهای ورودی و خروجی API از DTOها یا `record`های اختصاصی و Immutable استفاده کن.
- برای اعتبارسنجی مدل‌ها از کتابخانه FluentValidation استفاده کن.
- پاسخ‌های خطای API باید منطبق بر استاندارد RFC 7807 (نوع ProblemDetails) باشند.

## الگوهای ناهمگام و کارایی (Async / Performance)
- برای تمام عملیات I/O از متدهای Asynchronous استفاده کن.
- پارامتر `CancellationToken` باید در تمام لایه‌ها از کنترلر تا کوئری‌های پایگاه داده منتقل شود.
- کوئری‌های صرفاً خواندنی در EF Core باید با `.AsNoTracking()` اجرا شوند.
- هرگز از متدهای مسدودکننده (`.Result` یا `.Wait()`) استفاده نکن.

## تست‌نویسی
- فریم‌ورک تست پروژه xUnit است.
- برای ارزیابی خروجی‌ها از کتابخانه FluentAssertions استفاده کن.
- برای Mock کردن وابستگی‌ها از NSubstitute یا Moq استفاده کن.
- تست‌ها باید سناریوهای مرزی (Edge Cases)، ورودی‌های تهی و مبالغ نامعتبر را پوشش دهند.

## مدیریت وابستگی‌ها و پکیج‌ها
- هیچ کتابخانه شخص ثالث جدیدی را بدون دلیل فنی موجه به پروژه اضافه نکن.
- ثبت سرویس‌ها در Dependency Injection باید از تفکیک صحیح طول‌عمر (Scoped, Singleton, Transient) پیروی کند.

• حذف تکرار پرامپت‌ها: نیازی نیست در هر نوبت چت، قوانین پایه‌ای پروژه را مجدداً تایپ کنید.
• یکپارچگی کد در تمام تیم: همه توسعه‌دهندگانی که روی مخزن کار می‌کنند (چه با VS Code و چه با Visual Studio)، خروجی‌هایی هماهنگ با سبک توافق‌شده دریافت خواهند کرد.
• کوتاه‌تر شدن پرامپت‌های روزمره: پرامپت‌های شما از دستورالعمل‌های طولانی به اهداف مشخص بیزینسی تغییر می‌کنند:
• به جای: «یک اکشن متد برای واکشی سفارش بساز با DTO، آسنکرون، بدون انتتی و با xUnit...»
• می‌گویید: «اکشن متد دریافت سفارش بر اساس شناسه را اضافه کن.»

• دستورالعمل‌های اختصاصی مسیرها (Path-Specific Instructions): در صورت نیاز به تفکیک قوانین (مثلاً استانداردهای متفاوت برای لایه فرانت‌اند/Blazor در مقایسه با سرویس‌های بک‌اند)، می‌توانید دستورالعمل‌های محلی را در پوشه‌های مختلف پروژه تعریف کنید.
• بازبینی و نسخه‌گذاری دستورالعمل‌ها: فایل copilot-instructions.md را همانند کدهای اصلی پروژه در فرآیند Code Review و Pull Request ارتقا دهید. هرگاه تصمیم فنی جدیدی در تیم گرفته شد، بلافاصله آن را به این فایل اضافه کنید.
• تمرکز بر قراردادها به جای جزییات اجرایی: دستورالعمل‌ها باید الگوهای طراحی و محدودیت‌های قطعی را مشخص کنند، نه اینکه جزییات پیاده‌سازی متدهای خاص را محدود سازند.