CMS/docs/cms-data-and-business.md

# مستندات داده و بیزینس مایکروسرویس CMS

## معماری و لایه‌ها
- **پشته فنی**: ‎.NET 9‎ + ASP.NET Core WebAPI، MediatR برای پیاده‌سازی CQRS، EF Core برای دسترسی داده، Mapster برای مپینگ DTO و gRPC/Protobuf برای قرارداد سرویس بین BFF ها و FrontOffice.
- **ساختار پروژه**: لایه‌های Domain (موجودیت و قواعد)، Application (CQRS Commands/Queries، ولیدیشن، DTO)، Infrastructure (EF Core + سرویس‌های جانبی) و WebApi (ورودی HTTP/gRPC) به همراه پروژه مستقل Protobuf جهت به‌اشتراک‌گذاری قراردادها.
- **الگوی کلی**: هر درخواست ورودی از طریق WebApi به MediatR ارسال و Handler مربوطه داده را از DbContext می‌خواند/می‌نویسد. تمام موجودیت‌ها از `BaseAuditableEntity` ارث می‌برند و ستون‌های `Id`, `Created`, `CreatedBy`, `LastModified`, `IsDeleted` را به صورت یکپارچه فراهم می‌کنند.
- **ملاحظات مقیاس‌پذیری**: Handler ها stateless هستند و می‌توانند افقی مقیاس شوند. کنترل تراکنش‌ها توسط EF Core انجام می‌شود و در عملیات چندمرحله‌ای (مثلاً ثبت سفارش) تغییرات داخل یک `TransactionScope` واحد اعمال می‌شود تا سازگاری داده حفظ شود.
- **پایش و ردگیری**: رفتارهای `Common/Behaviours` برای لاگ‌گیری و اعتبارسنجی فعال‌اند و برای هر درخواست یک شناسه ردگیری تولید می‌کنند تا ارتباط بین لاگ BackOffice و FrontOffice حفظ گردد.

## مدل داده
برای فهم بهتر بیزینس، موجودیت‌ها در پنج خوشه اصلی (هویت، کاتالوگ، سفارش، کیف پول، قرارداد) دسته‌بندی شده‌اند و هر خوشه قواعد و قیود مخصوص خود را دارد.
### لایه کاربر و هویت
- **User**: اطلاعات هویتی، وضعیت تایید موبایل، تنظیمات اعلان، کد ارجاع و رابطه والد/فرزند. ارتباط یک‌به‌چند با آدرس‌ها، نقش‌ها، سفارش‌ها، قراردادها، کیف پول و سبد خرید.
- **Role / UserRole**: تعریف نقش‌های سیستمی و نگاشت چند-به-چند کاربر به نقش. جهت کنترل دسترسی BackOffice.
- **OtpToken**: ذخیره توکن‌های OTP با هش کد، هدف (Purpose)، زمان انقضا، تعداد تلاش و وضعیت مصرف برای جریان لاگین/ثبت‌نام.

### لایه محتوا و کاتالوگ محصول
- **Category**: ساختار درختی دسته‌بندی با عنوان، توضیحات، تصویر، ترتیب نمایش و وضعیت فعال بودن. `ParentId` برای تو در تویی و ارتباط با `PruductCategory`.
- **Tag / PruductTag**: برچسب‌های قابل جستجو برای محصولات با وضعیت فعال و ترتیب. جدول واسط `PruductTag` اتصال چند-به-چند محصول و تگ را نگه می‌دارد.
- **Products**: جزئیات کامل محصول شامل توضیحات کوتاه/طولانی، قیمت، تخفیف، نرخ، تصاویر اصلی/Thumbnail، آمار فروش و موجودی. ارتباط با سبد، گالری، فاکتور، دسته و تگ.
- **ProductImages / ProductGallerys**: مدیریت دارایی‌های تصویری. `ProductImages` مشخصات فایل را نگه می‌دارد و `ProductGallerys` رابطه هر تصویر با یک محصول را ثبت می‌کند تا چیدمان گالری قابل کنترل باشد.
- **Package**: باندل یا سرویس قابل فروش با عنوان، توضیح، تصویر و قیمت ثابت که می‌تواند داخل سفارش کاربر قرار گیرد.
- **Category–Product Pivot (`PruductCategory`)**: ردیف‌های عضویت محصول در دسته‌های متعدد. هر ردیف شامل `ProductId` و `CategoryId` است.

### لایه سفارش و تراکنش
- **UserCarts**: آیتم‌های سبد خرید کاربر، شامل شناسه محصول، کاربر و تعداد. منبع اصلی عملیات افزودن/حذف سبد در FrontOffice.
- **UserAddress**: آدرس‌های پستی کاربران با عنوان، متن آدرس، کد پستی، شهر، وضعیت پیش‌فرض و ارتباط با سفارش‌ها.
- **UserOrder**: سفارش نهایی شامل مبلغ، ارجاع به پکیج/تراکنش، وضعیت و تاریخ پرداخت، روش پرداخت، وضعیت ارسال، کد رهگیری و توضیحات ارسال. همچنین به آدرس کاربر و آیتم‌های فاکتور (`FactorDetails`) متصل است.
- **FactorDetails**: اقلام درون سفارش؛ هر ردیف به محصول و سفارش اشاره دارد و تعداد، قیمت واحد، تخفیف و وضعیت تغییر قیمت را نگه می‌دارد.
- **Transactions**: لاگ مالی سطح درگاه با مبلغ، توضیح، وضعیت/تاریخ پرداخت، شناسه مرجع درگاه و نوع تراکنش (Persistent در Enum `TransactionType`). سفارش‌ها می‌توانند به یک تراکنش اشاره کنند.

### لایه کیف پول و تسویه
- **UserWallet**: کیف پول ریالی/شبکه‌ای هر کاربر با موجودی جاری و موجودی شبکه (`NetworkBalance`).
- **UserWalletChangeLog**: ژورنال تغییرات کیف پول شامل موجودی قبل/بعد، مقدار تغییر، تغییر شبکه، اینکه افزایش یا کاهش بوده و شناسه مرجع (مثلاً تراکنش یا سفارش). ستون `Created` منبع اصلی timestamp فاکتور کیف پول است.

### لایه قرارداد و رعایت الزامات
- **Contract**: قالب قراردادها با عنوان، توضیحات، متن HTML و نوع قرارداد (`ContractType`).
- **UserContract**: سوابق موافقت کاربر با قراردادها، شامل فایل PDF امضا شده و `SignGuid` برای ردیابی امضا.

## ماژول‌ها و بیزینس مفصل
### کاربران و هویت
- **ثبت‌نام**: با دریافت موبایل، رکورد `User` ساخته و OTP برای تایید ارسال می‌شود. شرط یکتایی موبایل در سطح پایگاه داده enforced است و در Handler نیز بررسی می‌شود.
- **تکمیل پروفایل**: کاربر می‌تواند نام، کد ملی، تاریخ تولد و تنظیمات اعلان را تکمیل کند. فعال‌سازی اعلان‌ها به BFF اطلاع می‌دهد تا Subscription در سرویس پوش ثبت شود.
- **مدیریت نقش**: Admin می‌تواند از API `UserRoleCQ` برای افزودن نقش جدید استفاده کند؛ در صورت حذف نقش، ابتدا باید عضویت‌های فعال کاربر قطع شود.

### کاتالوگ و محتوا
- **دسته‌بندی درختی**: سطح بی‌نهایت تو در تو پشتیبانی می‌شود. حذف یک دسته زمانی مجاز است که هیچ `Categorys` فرزند و هیچ `PruductCategory` فعالی نداشته باشد؛ در غیر این صورت باید انتقال انجام شود.
- **چرخه محصول**: ایجاد محصول شامل ثبت داده متنی، بارگذاری تصویر شاخص، تعریف قیمت و تعیین تخفیف است. تغییر قیمت در Handler ثبت شده و قوانین جلوگیری از عدد منفی یا Discount بزرگ‌تر از 100٪ اعمال می‌شود.
- **گالری و تصاویر**: ابتدا تصویر در `ProductImages` ثبت و سپس با `ProductGallerys` به محصول متصل می‌شود تا یک تصویر بتواند در چند محصول استفاده شود. حذف تصویر اگر در گالری فعال باشد ممنوع است.
- **پکیج‌ها**: برای فروش سرویس اشتراکی یا باندل؛ فیلد `Price` مبنای محاسبه سفارش‌های نوع Package است و تغییر قیمت روی سفارش‌های ثبت‌شده تاثیر ندارد زیرا مبلغ در `UserOrder.Amount` ذخیره می‌شود.

### سفارش، پرداخت و لجستیک
- **سبد خرید**: عملیات Add/Update/Delete روی `UserCarts` انجام می‌شود. در هر لحظه برای ترکیب (User, Product) تنها یک رکورد وجود دارد. اگر Count صفر شود، رکورد حذف منطقی می‌شود تا تاریخچه حفظ گردد.
- **Checkout**: Handler `SubmitShopBuyOrder` اقلام سبد را قفل خوش‌بینانه کرده، سفارش (`UserOrder`) و اقلام فاکتور (`FactorDetails`) را می‌سازد، آدرس پیش‌فرض را نگاشت و وضعیت پرداخت را Pending می‌گذارد.
- **پرداخت آنلاین**: پس از هدایت به درگاه، سیستم CallBack در `TransactionsCQ` را دریافت می‌کند؛ شناسه مرجع (`RefId`) و مبلغ تطبیق داده می‌شود. در صورت موفقیت، `PaymentStatus` سفارش و تراکنش Success شده و `PaymentDate` ذخیره می‌شود. در صورت Reject، سبد به حالت قبل بازگردانده می‌شود.
- **پرداخت با کیف پول**: اگر موجودی کافی باشد، به صورت اتمیک از کیف پول کسر و سفارش Success می‌شود؛ نیازی به تراکنش درگاه نیست.
- **لجستیک**: فیلدهای `DeliveryStatus`, `TrackingCode`, `DeliveryDescription` وضعیت ارسال را پوشش می‌دهند. هر تغییر وضعیت می‌تواند Notification برای کاربر یا تیم پشتیبانی ایجاد کند.

### کیف پول و تسویه داخلی
- **ساخت کیف پول**: همزمان با ثبت‌نام یا اولین تراکنش، رکورد `UserWallet` ساخته می‌شود. موجودی شبکه برای پشتیبانی از دارایی‌های خارج از پلتفرم است.
- **ChangeLog**: هر تغییر موجودی همراه با مقدار قبل/بعد، مقدار شبکه، نوع عملیات (Increase/Decrease) و `ReferenceId` ثبت می‌شود تا audit کافی فراهم گردد. Handler ها Idempotency را با بررسی ReferenceId رعایت می‌کنند.
- **واریز**: می‌تواند از طریق درگاه آنلاین یا عملیات دستی ادمین باشد. پس از تایید بانک، مبلغ به `Balance` افزوده و ChangeLog با نوع Deposit ذخیره می‌شود.
- **برداشت/تسویه**: درخواست Withdrawal ابتدا به صف تایید دستی می‌رود (Business Rule). پس از تایید، مبلغ از `Balance` کم و اگر نیاز به ارسال به شبکه بلاکچین باشد، `NetworkBalance` نیز به‌روزرسانی می‌شود.
- **بازپرداخت سفارش**: در صورت لغو سفارش پرداخت‌شده، مقدار پرداختی با ChangeLog نوع Refund به کیف پول برمی‌گردد تا کاربر بتواند مجدد خرید کند یا برداشت انجام دهد.

### قرارداد و انطباق
- **مدیریت نسخه**: هر بار که متن قرارداد تغییر کند، رکورد جدیدی در `Contract` ساخته می‌شود. `UserContract` با نگه داشتن `ContractId` مشخص می‌کند کاربر کدام نسخه را امضا کرده است.
- **فرآیند امضا**: برای امضای دیجیتال، سیستم `SignGuid` را به سرویس امضای بیرونی ارسال می‌کند. پس از تکمیل، فایل PDF در فضای ذخیره‌سازی آپلود و مسیر آن در `UserContract.SignedPdfFile` ثبت می‌شود.
- **کنترل پذیرش قوانین**: فیلدهای `IsRulesAccepted` و `RulesAcceptedAt` در موجودیت User نیز نگهداری می‌شوند تا بتوان دفعات قبول قوانین عمومی را از قراردادهای اختصاصی تفکیک کرد.

### گزارش و مانیتورینگ
- تمام Queries دارای پارامترهای Paging و Sorting هستند تا BackOffice بتواند داشبورد مدیریتی بسازد.
- به کمک Mapster Projection فقط ستون‌های مورد نیاز خوانده می‌شود؛ در موارد خاص (مثل تاریخ تراکنش کیف پول) Projection دستی به DTO اعمال شده است.
- ساختار CQRS اجازه می‌دهد که در آینده Event Handler یا Outbox برای همگام‌سازی با سرویس‌های دیگر اضافه شود.

## فرایندهای بیزینسی کلیدی
### 1. احراز هویت و ورود
1. کاربر شماره موبایل را ارسال می‌کند؛ `OtpTokenCQ` یک رکورد جدید با کد هش‌شده، زمان انقضا و شمارش تلاش‌ها می‌سازد. درصورت وجود رکورد فعال، ابتدا Attempts چک و درصورت عبور از سقف، خطای تجاری برگردانده می‌شود.
2. کاربر کد را ارسال می‌کند؛ سیستم hash تولید می‌کند و با `CodeHash` مقایسه می‌شود. در صورت موفقیت، `IsUsed` و `IsMobileVerified` تنظیم می‌شوند و تاریخ تایید موبایل ذخیره می‌گردد.
3. اگر کاربر برای اولین‌بار وارد شود، کیف پول و Role پیش‌فرض ایجاد می‌شود. سپس سرویس JWT توکن امضا شده (همراه با Claims نقش‌ها) را برمی‌گرداند.

### 2. مدیریت کاتالوگ و محتوای فروش
- اپراتور BackOffice از طریق دسته‌ها، تگ‌ها و محصولات API های `CategoryCQ`, `ProductsCQ`, `TagCQ` و … اقلام را CRUD می‌کند.
- تصاویر از طریق `ProductImagesCQ` ثبت و سپس با `ProductGallerysCQ` به محصولات لینک می‌شوند تا ترتیب نمایش قابل تغییر باشد.
- باندل‌های اشتراکی یا خدمات از طریق `PackageCQ` تعریف می‌شوند و در سفارش‌ها استفاده می‌شوند.
- قوانین کیفیت داده: عنوان و توضیح محصول نمی‌تواند خالی باشد، تصویر شاخص باید پیش از انتشار محصول مشخص شود و حداقل یک دسته فعال برای محصول الزامی است.
- وضعیت فعال/غیرفعال دسته‌ها در API لیست محصولات اعمال می‌شود تا محصولات دسته غیرفعال نمایش داده نشوند.

### 3. تجربه خرید (Cart → Order → Transaction)
1. FrontOffice اقلام را در `UserCarts` ثبت/ویرایش می‌کند.
2. هنگام تسویه، Handler های `UserOrderCQ` سفارش و اقلام `FactorDetails` را می‌سازند، آدرس پیش‌فرض UserAddress را ضمیمه می‌کنند و وضعیت پرداخت را `Pending` قرار می‌دهند.
3. پس از موفقیت درگاه، سرویس تراکنش (`TransactionsCQ`) شناسه مرجع را ذخیره و `PaymentStatus` سفارش و تراکنش را `Success` می‌کند؛ تاریخ پرداخت نیز ست می‌شود.
4. وضعیت ارسال (`DeliveryStatus`) در طول فرایند Fulfillment آپدیت شده و کد رهگیری پستی داخل سفارش نگه‌داری می‌شود.
- سناریو شکست درگاه: اگر درگاه خطا دهد، سفارش در حالت Pending باقی می‌ماند و Job زمان‌بندی شده این سفارش‌ها را بعد از زمان مشخص لغو می‌کند تا سبد دوباره آزاد شود.
- امکان پرداخت ترکیبی (کیف پول + درگاه) وجود دارد؛ ابتدا از کیف پول برداشت و سپس باقی‌مانده به درگاه ارسال می‌شود.

### 4. کیف پول و صورتحساب داخلی
- هر کاربر دقیقا یک کیف پول فعال دارد (`UserWalletCQ`).
- واریز/برداشت (چه ناشی از پرداخت آنلاین چه عملیات دستی) همیشه یک رکورد در `UserWalletChangeLog` ایجاد می‌کند تا موجودی قبلی، مقدار تغییر و منبع (ReferenceId) مشخص باشد.
- FrontOffice برای نمایش تاریخ دقیق تراکنش‌ها از `Created` لاگ استفاده می‌کند؛ بنابراین Handler های `UserWalletChangeLogCQ` حتما `CreatedAt` را به DTO و gRPC پاسخ اضافه می‌کنند.
- ChangeLog ها قابلیت فیلتر بر اساس نوع عملیات، بازه تاریخی و ReferenceId دارند و مقادیر در DTO به timestamp یونیکس هم تبدیل می‌شود تا فرانت به راحتی فرمت کند.
- عملیات دستی ادمین حتما توضیح (Description) و شناسه اپراتور را ثبت می‌کند تا audit کامل باشد.

### 5. قراردادها و انطباق
- محتوای قرارداد (Term of Service، قرارداد نمایندگی و …) در `Contract` نگه‌داری می‌شود.
- هنگام امضا، یک `UserContract` شامل فایل PDF امضا شده و `SignGuid` ایجاد می‌گردد تا سوابق حقوقی نگهداری شود. این اطلاعات در درخواست‌های بعدی احراز می‌شوند تا از کاربران فقط یکبار امضا گرفته شود.
- در صورت به‌روزرسانی متن قرارداد، کاربران باید مجدداً آن را تایید کنند؛ FrontOffice هنگام ورود این شرط را بررسی و کاربر را به صفحه امضا هدایت می‌کند.
- سیستم گزارش می‌دهد چه تعداد کاربر هر نسخه را امضا کرده‌اند تا تیم حقوقی مطمئن شود پوشش قانونی کامل است.

## نکات پیاده‌سازی و توسعه
- **CQRS پوشه‌بندی**: هر ماژول (مثلاً `UserWalletCQ`) شامل زیرپوشه‌های Commands و Queries است. درخواست‌های gRPC از پروژه Protobuf با DTO های Application نگاشت می‌شوند.
- **همگام‌سازی قراردادها**: هر زمان فیلد جدیدی به موجودیت اضافه شود باید DTO، Handler و قرارداد Protobuf متناظر نیز به‌روزرسانی و `dotnet build` برای تولید مجدد stubs اجرا شود. سپس BFF ها باید پکیج جدید را دریافت کنند.
- **اتصال با BFF**: CMS WebApi سرویس‌های gRPC را در پورت تعریف شده در `appsettings` اکسپوز می‌کند. BFF ها با استفاده از Channel مطمئن (TLS داخلی) به آن متصل می‌شوند و Mapster را برای تبدیل به مدل‌های فرانت استفاده می‌کنند.
- **Dependency Injection**: تمام Handler ها و سرویس‌ها در `CMSMicroservice.Application/ConfigureServices.cs` و `CMSMicroservice.Infrastructure/ConfigureServices.cs` ثبت می‌شوند تا تست‌پذیری افزایش یابد.
- **اعتبارسنجی و لاگ**: Behaviour های مشترک (LoggingBehaviour, ValidationBehaviour) روی Pipeline MediatR نشسته‌اند تا قبل از اجرای Handler، ورودی‌ها چک و لاگ ساختارمند تولید شود.
- **زمان‌بندی تمیزکاری**: ستون `IsDeleted` برای Soft Delete به‌کار می‌رود. Handler هایی که لیست می‌دهند معمولا فیلتر `!IsDeleted` را اعمال می‌کنند؛ برای نمایش آرشیو باید صراحتاً flag درخواست شود.
- **Enums مهم**: `PaymentStatus`, `PaymentMethod`, `DeliveryStatus`, `ContractType`, `TransactionType` طیف وضعیت‌های مالی/قراردادی را استاندارد می‌کنند و باید بین FrontOffice و BackOffice همسو نگه داشته شوند.
- **آیتم‌های Idempotent**: عملیات حساس مثل واریز کیف پول یا ثبت سفارش از ReferenceId استفاده می‌کنند تا در تکرار درخواست‌ها نتیجه‌ی تکراری ایجاد نشود.

## مسیرهای مرتبط
- ساختار کد: `CMS/src/CMSMicroservice.Domain/Entities`, `CMSMicroservice.Application/*CQ`, `CMSMicroservice.Protobuf/Protos`.
- مستند حاضر: `CMS/docs/cms-data-and-business.md`
- نقاط تماس بیرونی: gRPC Endpoint های `CMSMicroservice.WebApi` به صورت داخلی مصرف می‌شوند و از طریق FrontOffice/BackOffice BFF در اختیار UI قرار می‌گیرند.