Refactor code structure for improved readability and maintainability

2026-02-05 23:02:01 +03:30
parent 5965b98728
commit 8f02cec22f
11 changed files with 8685 additions and 0 deletions
@@ -0,0 +1,249 @@
+# Proto Package Management - Quick Start
+
+این فایل یک راهنمای سریع برای مدیریت Proto Packages در پروژه FourSat است.
+
+---
+
+## 📦 فایل‌های مهم
+
+| فایل | توضیحات |
+|------|---------|
+| `PROTO-PACKAGING-GUIDE.md` | راهنمای کامل و جامع (همه جزئیات) |
+| `pack-protos.sh` | Script خودکار برای Package کردن همه Proto ها |
+| `docker-compose.baget.yml` | راه‌اندازی Private NuGet Server |
+| `EXAMPLE-PROTO-CSPROJ.xml` | مثال csproj با تنظیمات Debug/Release |
+
+---
+
+## 🚀 شروع سریع
+
+### 1. راه‌اندازی NuGet Server (اختیاری برای Local Development)
+
+```bash
+# شروع BaGet با Docker
+docker-compose -f docker-compose.baget.yml up -d
+
+# بررسی وضعیت
+docker ps | grep baget
+
+# دسترسی به UI
+# مرورگر: http://localhost:5555
+```
+
+### 2. Package کردن همه Proto ها
+
+```bash
+# فقط ساخت packages (بدون push)
+./pack-protos.sh
+
+# ساخت و push به NuGet server
+./pack-protos.sh --push
+
+# استفاده از custom server
+NUGET_SERVER=https://nuget.foursat.com ./pack-protos.sh --push
+```
+
+### 3. اضافه کردن NuGet Source
+
+```bash
+# اضافه کردن local BaGet
+dotnet nuget add source http://localhost:5555/v3/index.json \
+  --name foursat-local \
+  --username foursat \
+  --password FOURSAT-SECRET-API-KEY-2025 \
+  --store-password-in-clear-text
+
+# بررسی sources
+dotnet nuget list source
+```
+
+---
+
+## 🔄 Workflow توسعه
+
+### Development (Local):
+
+```bash
+# Build با Debug config → استفاده از ProjectReference
+cd BackOffice/src
+dotnet build -c Debug
+
+# همه تغییرات Proto بلافاصله اعمال می‌شود
+```
+
+### Production (Deploy):
+
+```bash
+# 1. Package کردن CMS Proto
+cd CMS/src/CMSMicroservice.Protobuf
+dotnet pack -c Release -o ./nupkg
+
+# 2. Push به NuGet Server
+dotnet nuget push ./nupkg/*.nupkg \
+  --source http://localhost:5555/v3/index.json \
+  --api-key FOURSAT-SECRET-API-KEY-2025
+
+# 3. Package کردن BFF Protos (وابسته به CMS)
+cd BackOffice.BFF/src/Protobufs
+# ... (مشابه)
+
+# 4. Build UI با Release config → استفاده از PackageReference
+cd BackOffice/src
+dotnet build -c Release
+```
+
+---
+
+## 📊 ساختار Packages
+
+```
+Foursat.CMSMicroservice.Protobuf (v1.0.0)
+  └─ Base Proto Layer
+     └─ استفاده شده در:
+        ├─ Foursat.BackOffice.BFF.Products.Protobuf
+        ├─ Foursat.BackOffice.BFF.User.Protobuf
+        ├─ Foursat.BackOffice.BFF.*.Protobuf (12 package دیگر)
+        ├─ Foursat.FrontOffice.BFF.Products.Protobuf
+        └─ Foursat.FrontOffice.BFF.*.Protobuf (7 package دیگر)
+```
+
+**تعداد کل Packages**: ~23 package
+
+---
+
+## 🔍 دستورات مفید
+
+```bash
+# جستجو در local NuGet server
+dotnet nuget search Foursat --source foursat-local
+
+# نصب یک package
+dotnet add package Foursat.CMSMicroservice.Protobuf \
+  --version 1.0.0 \
+  --source foursat-local
+
+# بررسی dependencies
+dotnet list package --include-transitive
+
+# حذف package cache
+dotnet nuget locals all --clear
+
+# بررسی محتویات package
+unzip -l package.nupkg
+```
+
+---
+
+## ⚙️ تنظیمات csproj
+
+### Development (Debug):
+```xml
+<ItemGroup Condition="'$(Configuration)' == 'Debug'">
+  <ProjectReference Include="..\..\CMS\src\CMSMicroservice.Protobuf\CMSMicroservice.Protobuf.csproj" />
+</ItemGroup>
+```
+
+### Production (Release):
+```xml
+<ItemGroup Condition="'$(Configuration)' == 'Release'">
+  <PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="1.0.0" />
+</ItemGroup>
+```
+
+**مثال کامل**: `EXAMPLE-PROTO-CSPROJ.xml`
+
+---
+
+## 📝 Versioning
+
+### Semantic Versioning (SemVer):
+
+```
+MAJOR.MINOR.PATCH
+
+1.0.0 → Initial release
+1.0.1 → Bug fix
+1.1.0 → New feature (backward compatible)
+2.0.0 → Breaking change
+```
+
+### مثال تغییر نسخه:
+
+```xml
+<!-- قبل: -->
+<Version>1.0.0</Version>
+
+<!-- بعد از اضافه کردن فیلد جدید (compatible): -->
+<Version>1.1.0</Version>
+
+<!-- بعد از تغییر RPC signature (breaking): -->
+<Version>2.0.0</Version>
+```
+
+---
+
+## 🎯 نکات مهم
+
+1. ✅ **Local Development**: همیشه با `Debug` build کار کنید
+2. ✅ **Production Build**: همیشه با `Release` build
+3. ✅ **Version Bump**: هر تغییر در Proto → نسخه جدید
+4. ✅ **Push Order**: اول CMS، بعد BFF ها، آخر UI ها
+5. ✅ **Testing**: قبل از push حتماً test کنید
+
+---
+
+## 🆘 عیب‌یابی
+
+### مشکل: Package پیدا نمی‌شود
+
+```bash
+# بررسی source ها
+dotnet nuget list source
+
+# اضافه کردن source
+dotnet nuget add source http://localhost:5555/v3/index.json --name foursat-local
+
+# پاک کردن cache
+dotnet nuget locals all --clear
+```
+
+### مشکل: Version conflict
+
+```bash
+# حذف obj و bin
+find . -name "obj" -o -name "bin" | xargs rm -rf
+
+# Restore دوباره
+dotnet restore
+
+# Build
+dotnet build -c Release
+```
+
+### مشکل: BaGet server در دسترس نیست
+
+```bash
+# بررسی container
+docker ps | grep baget
+
+# restart container
+docker-compose -f docker-compose.baget.yml restart
+
+# لاگ‌ها
+docker logs foursat-nuget-server
+```
+
+---
+
+## 📚 منابع بیشتر
+
+- **راهنمای کامل**: `PROTO-PACKAGING-GUIDE.md`
+- **BaGet Documentation**: https://loic-sharma.github.io/BaGet/
+- **NuGet CLI Reference**: https://docs.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference
+- **Semantic Versioning**: https://semver.org/
+
+---
+
+**تاریخ**: December 6, 2025  
+**نسخه**: 1.0.0  
+**پروژه**: FourSat