update

2026-01-03 18:27:49 +03:30
parent 0369292d7f
commit 5965b98728
156 changed files with 16082 additions and 0 deletions
@@ -0,0 +1,420 @@
+# راهنمای Package کردن Proto Projects برای Production
+
+> تاریخ: December 6, 2025  
+> وضعیت: Production Deployment Guide
+
+---
+
+## 🎯 مسئله
+
+**Development (Local)**:
+- استفاده از `<ProjectReference>` برای توسعه سریع
+- تغییرات proto بلافاصله در همه پروژه‌ها اعمال می‌شود
+
+**Production (Server)**:
+- استفاده از `<PackageReference>` و NuGet packages
+- هر لایه پکیج خودش را منتشر می‌کند
+- پروژه‌های بالاتر از NuGet server پکیج‌ها را می‌گیرند
+
+---
+
+## 📦 معماری Packaging
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    LAYER 1: CMS Proto                        │
+│  CMSMicroservice.Protobuf → Foursat.CMSMicroservice.Protobuf │
+└────────────────────┬────────────────────────────────────────┘
+                     │ (NuGet Package v1.0.x)
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│              LAYER 2: BFF Proto (depends on CMS)             │
+│  BackOffice.BFF.*.Protobuf → Foursat.BackOffice.BFF.*.Protobuf │
+│  FrontOffice.BFF.*.Protobuf → Foursat.FrontOffice.BFF.*.Protobuf │
+└────────────────────┬────────────────────────────────────────┘
+                     │ (NuGet Package v1.0.x)
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│            LAYER 3: UI Apps (depends on BFF)                 │
+│  BackOffice UI → uses Foursat.BackOffice.BFF.*.Protobuf     │
+│  FrontOffice UI → uses Foursat.FrontOffice.BFF.*.Protobuf   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔧 Setup 1: Private NuGet Server
+
+### گزینه A: BaGet (پیشنهادی - رایگان و ساده)
+
+```bash
+# نصب با Docker
+docker run -d \
+  --name foursat-nuget \
+  --restart unless-stopped \
+  -p 5555:80 \
+  -e ApiKey=FOURSAT-SECRET-API-KEY-2025 \
+  -e Storage__Type=FileSystem \
+  -e Storage__Path=/var/baget/packages \
+  -e Database__Type=Sqlite \
+  -e Database__ConnectionString="Data Source=/var/baget/baget.db" \
+  -e Search__Type=Database \
+  -v /opt/foursat-nuget/packages:/var/baget/packages \
+  -v /opt/foursat-nuget/database:/var/baget \
+  loicsharma/baget:latest
+
+# سرور روی http://YOUR_SERVER:5555 در دسترس خواهد بود
+```
+
+### گزینه B: Azure Artifacts
+
+```bash
+# اضافه کردن feed
+az artifacts universal publish \
+  --organization https://dev.azure.com/yourorg \
+  --feed foursat-packages \
+  --name CMSMicroservice.Protobuf \
+  --version 1.0.0 \
+  --path ./nupkg
+```
+
+### گزینه C: GitHub Packages
+
+```bash
+# تنظیم authentication
+dotnet nuget add source https://nuget.pkg.github.com/YOURORG/index.json \
+  --name github \
+  --username YOURNAME \
+  --password ghp_YOUR_TOKEN \
+  --store-password-in-clear-text
+```
+
+---
+
+## 📝 Setup 2: تنظیمات Proto Projects
+
+### 1. CMS Protobuf (لایه اول - پایه)
+
+**CMSMicroservice.Protobuf.csproj** از قبل آماده است:
+
+```xml
+<PropertyGroup>
+  <TargetFramework>net9.0</TargetFramework>
+  <Version>1.0.0</Version>
+  <PackageId>Foursat.CMSMicroservice.Protobuf</PackageId>
+  <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
+  
+  <!-- اطلاعات پکیج -->
+  <Authors>FourSat Development Team</Authors>
+  <Company>FourSat</Company>
+  <Description>gRPC Protobuf contracts for CMS Microservice</Description>
+  <PackageTags>grpc;protobuf;foursat;cms</PackageTags>
+  <RepositoryUrl>https://github.com/foursat/cms</RepositoryUrl>
+  <PackageLicenseExpression>MIT</PackageLicenseExpression>
+</PropertyGroup>
+```
+
+### 2. BackOffice.BFF Proto Projects (لایه دوم)
+
+مثال برای **BackOffice.BFF.Products.Protobuf**:
+
+```xml
+<PropertyGroup>
+  <TargetFramework>net9.0</TargetFramework>
+  <Version>1.0.0</Version>
+  <PackageId>Foursat.BackOffice.BFF.Products.Protobuf</PackageId>
+  <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
+  <Authors>FourSat Development Team</Authors>
+  <Company>FourSat</Company>
+  <Description>gRPC Protobuf contracts for BackOffice BFF - Products Module</Description>
+  <PackageTags>grpc;protobuf;foursat;backoffice</PackageTags>
+</PropertyGroup>
+
+<!-- Development: ProjectReference -->
+<ItemGroup Condition="'$(Configuration)' == 'Debug'">
+  <ProjectReference Include="..\..\..\CMS\src\CMSMicroservice.Protobuf\CMSMicroservice.Protobuf.csproj" />
+</ItemGroup>
+
+<!-- Production: PackageReference -->
+<ItemGroup Condition="'$(Configuration)' == 'Release'">
+  <PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="1.0.0" />
+</ItemGroup>
+```
+
+### 3. FrontOffice.BFF Proto Projects (لایه دوم)
+
+مشابه BackOffice.BFF:
+
+```xml
+<PropertyGroup>
+  <PackageId>Foursat.FrontOffice.BFF.Products.Protobuf</PackageId>
+  <Version>1.0.0</Version>
+</PropertyGroup>
+
+<ItemGroup Condition="'$(Configuration)' == 'Debug'">
+  <ProjectReference Include="..\..\..\CMS\src\CMSMicroservice.Protobuf\CMSMicroservice.Protobuf.csproj" />
+</ItemGroup>
+
+<ItemGroup Condition="'$(Configuration)' == 'Release'">
+  <PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="1.0.0" />
+</ItemGroup>
+```
+
+---
+
+## 🚀 فرآیند Deployment
+
+### مرحله 1: Package CMS Protobuf
+
+```bash
+cd /home/masoud/Apps/project/FourSat/CMS/src/CMSMicroservice.Protobuf
+
+# Build در حالت Release
+dotnet build -c Release
+
+# ایجاد NuGet package
+dotnet pack -c Release -o ./nupkg
+
+# Push به NuGet server
+dotnet nuget push ./nupkg/Foursat.CMSMicroservice.Protobuf.1.0.0.nupkg \
+  --source http://YOUR_SERVER:5555/v3/index.json \
+  --api-key FOURSAT-SECRET-API-KEY-2025
+```
+
+### مرحله 2: Package BackOffice.BFF Protos
+
+```bash
+# تمام Proto projects را pack کن
+cd /home/masoud/Apps/project/FourSat/BackOffice.BFF/src/Protobufs
+
+for dir in */; do
+  if [ -f "$dir/*.csproj" ]; then
+    cd "$dir"
+    dotnet pack -c Release -o ../../nupkg
+    cd ..
+  fi
+done
+
+# Push همه packages
+cd ../../nupkg
+dotnet nuget push "Foursat.BackOffice.BFF.*.nupkg" \
+  --source http://YOUR_SERVER:5555/v3/index.json \
+  --api-key FOURSAT-SECRET-API-KEY-2025
+```
+
+### مرحله 3: Package FrontOffice.BFF Protos
+
+```bash
+cd /home/masoud/Apps/project/FourSat/FrontOffice.BFF/src/Protobufs
+
+for dir in */; do
+  cd "$dir"
+  dotnet pack -c Release -o ../../nupkg
+  cd ..
+done
+
+cd ../../nupkg
+dotnet nuget push "Foursat.FrontOffice.BFF.*.nupkg" \
+  --source http://YOUR_SERVER:5555/v3/index.json \
+  --api-key FOURSAT-SECRET-API-KEY-2025
+```
+
+### مرحله 4: تنظیم UI Projects برای Production
+
+**BackOffice.csproj**:
+
+```xml
+<!-- Development -->
+<ItemGroup Condition="'$(Configuration)' == 'Debug'">
+  <ProjectReference Include="..\..\BackOffice.BFF\src\Protobufs\BackOffice.BFF.Products.Protobuf\BackOffice.BFF.Products.Protobuf.csproj" />
+  <ProjectReference Include="..\..\BackOffice.BFF\src\Protobufs\BackOffice.BFF.User.Protobuf\BackOffice.BFF.User.Protobuf.csproj" />
+  <!-- ... سایر proto references -->
+</ItemGroup>
+
+<!-- Production -->
+<ItemGroup Condition="'$(Configuration)' == 'Release'">
+  <PackageReference Include="Foursat.BackOffice.BFF.Products.Protobuf" Version="1.0.0" />
+  <PackageReference Include="Foursat.BackOffice.BFF.User.Protobuf" Version="1.0.0" />
+  <!-- ... سایر package references -->
+</ItemGroup>
+```
+
+**FrontOffice.csproj**: مشابه
+
+---
+
+## 🔄 Versioning Strategy
+
+### Semantic Versioning
+
+```
+MAJOR.MINOR.PATCH
+
+1.0.0 → Initial release
+1.0.1 → Bug fix (backward compatible)
+1.1.0 → New feature (backward compatible)
+2.0.0 → Breaking change
+```
+
+### مثال:
+
+```xml
+<!-- CMS Proto v1.0.0 -->
+<Version>1.0.0</Version>
+
+<!-- بعد از اضافه کردن فیلد جدید (backward compatible) -->
+<Version>1.1.0</Version>
+
+<!-- بعد از تغییر RPC signature (breaking) -->
+<Version>2.0.0</Version>
+```
+
+---
+
+## 🛠️ Scripts خودکار
+
+### pack-all-protos.sh
+
+```bash
+#!/bin/bash
+
+# رنگ‌ها برای output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+NUGET_SERVER="http://YOUR_SERVER:5555/v3/index.json"
+API_KEY="FOURSAT-SECRET-API-KEY-2025"
+
+echo -e "${BLUE}🚀 Starting Proto Packaging Process...${NC}\n"
+
+# 1. CMS Protobuf
+echo -e "${GREEN}📦 Step 1: Packaging CMS Protobuf${NC}"
+cd /home/masoud/Apps/project/FourSat/CMS/src/CMSMicroservice.Protobuf
+dotnet pack -c Release -o ./nupkg
+dotnet nuget push ./nupkg/*.nupkg --source $NUGET_SERVER --api-key $API_KEY --skip-duplicate
+
+# 2. BackOffice.BFF Protos
+echo -e "${GREEN}📦 Step 2: Packaging BackOffice.BFF Protos${NC}"
+cd /home/masoud/Apps/project/FourSat/BackOffice.BFF/src/Protobufs
+for dir in BackOffice.BFF.*.Protobuf/; do
+  if [ -d "$dir" ]; then
+    echo "  → Packaging $dir"
+    cd "$dir"
+    dotnet pack -c Release -o ../../../nupkg
+    cd ..
+  fi
+done
+cd ../../nupkg
+dotnet nuget push Foursat.BackOffice.BFF.*.nupkg --source $NUGET_SERVER --api-key $API_KEY --skip-duplicate
+
+# 3. FrontOffice.BFF Protos
+echo -e "${GREEN}📦 Step 3: Packaging FrontOffice.BFF Protos${NC}"
+cd /home/masoud/Apps/project/FourSat/FrontOffice.BFF/src/Protobufs
+for dir in FrontOffice.BFF.*.Protobuf/; do
+  if [ -d "$dir" ]; then
+    echo "  → Packaging $dir"
+    cd "$dir"
+    dotnet pack -c Release -o ../../../nupkg
+    cd ..
+  fi
+done
+cd ../../nupkg
+dotnet nuget push Foursat.FrontOffice.BFF.*.nupkg --source $NUGET_SERVER --api-key $API_KEY --skip-duplicate
+
+echo -e "\n${GREEN}✅ All packages published successfully!${NC}"
+```
+
+اجرا:
+```bash
+chmod +x pack-all-protos.sh
+./pack-all-protos.sh
+```
+
+---
+
+## 📋 NuGet.Config برای Development
+
+**nuget.config** در root:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <!-- Official NuGet -->
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
+    
+    <!-- FourSat Private NuGet Server -->
+    <add key="foursat" value="http://YOUR_SERVER:5555/v3/index.json" />
+  </packageSources>
+  
+  <packageSourceCredentials>
+    <foursat>
+      <add key="Username" value="foursat" />
+      <add key="ClearTextPassword" value="FOURSAT-SECRET-API-KEY-2025" />
+    </foursat>
+  </packageSourceCredentials>
+</configuration>
+```
+
+---
+
+## 🔍 بررسی Packages
+
+```bash
+# لیست packages روی server
+curl http://YOUR_SERVER:5555/v3/search?q=foursat
+
+# دانلود package
+dotnet add package Foursat.CMSMicroservice.Protobuf --version 1.0.0
+
+# بررسی dependency tree
+dotnet list package --include-transitive
+```
+
+---
+
+## 📊 خلاصه Packages
+
+| Package | Layer | Depends On | Version |
+|---------|-------|------------|---------|
+| Foursat.CMSMicroservice.Protobuf | 1 | - | 1.0.x |
+| Foursat.BackOffice.BFF.Products.Protobuf | 2 | CMS Proto | 1.0.x |
+| Foursat.BackOffice.BFF.User.Protobuf | 2 | CMS Proto | 1.0.x |
+| Foursat.BackOffice.BFF.*.Protobuf (14 pkg) | 2 | CMS Proto | 1.0.x |
+| Foursat.FrontOffice.BFF.Products.Protobuf | 2 | CMS Proto | 1.0.x |
+| Foursat.FrontOffice.BFF.*.Protobuf (8 pkg) | 2 | CMS Proto | 1.0.x |
+
+**جمع**: ~23 NuGet packages
+
+---
+
+## 🎯 مزایا
+
+✅ **Development**: سریع (ProjectReference)  
+✅ **Production**: مستقل (PackageReference)  
+✅ **Versioning**: کنترل دقیق تغییرات  
+✅ **CI/CD**: خودکارسازی آسان  
+✅ **Rollback**: برگشت به نسخه قبلی ساده  
+✅ **Team Work**: همکاری بهتر روی Proto ها
+
+---
+
+## 🚨 نکات مهم
+
+1. **همیشه از Semantic Versioning استفاده کنید**
+2. **Breaking changes** = Major version bump (2.0.0)
+3. **Proto changes باید documented باشند**
+4. **هر push به production نیاز به package جدید دارد**
+5. **Development با Debug build** = ProjectReference
+6. **Production با Release build** = PackageReference
+
+---
+
+## 📞 Support
+
+سوال یا مشکل؟
+- داکیومنت: `/home/masoud/Apps/project/FourSat/PROTO-PACKAGING-GUIDE.md`
+- BaGet UI: http://YOUR_SERVER:5555
+- Team: FourSat Development Team