docs/final-docs/02-PROTO-GUIDE.md

📦 Proto & gRPC Complete Guide

آخرین بروزرسانی: January 3, 2026
NuGet Server: GitLab Package Registry
URL جدید: https://git.se.kbs1.ir/api/packages/FourSat/nuget/index.json

---

📊 معماری Packaging

┌─────────────────────────────────────────────────────────────┐
│  LAYER 1: CMS Proto (Base)                                  │
│  CMSMicroservice.Protobuf                                   │
│  Version: 0.0.142+ → Auto-push به GitLab                   │
└─────────────────────────────────────────────────────────────┘
                              │
                     PackageReference
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  LAYER 2: BFF Protos                                        │
│  BackOffice.BFF.*.Protobuf (24 packages)                    │
│  FrontOffice.BFF.*.Protobuf (packages)                      │
│  → Depend on: CMS Proto v0.0.x                              │
└─────────────────────────────────────────────────────────────┘
                              │
                     PackageReference / DLL Reference
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  LAYER 3: UI Applications                                   │
│  BackOffice UI → libs/*.dll (24 DLLs)                       │
│  FrontOffice UI → FrontOffice.BFF Protos                    │
└─────────────────────────────────────────────────────────────┘

---

⚠️ قانون طلایی

هر تغییر در Proto = این 3 مرحله اجباری:

# 1️⃣ افزایش Version
<Version>X.Y.Z</Version>  →  <Version>X.Y.Z+1</Version>

# 2️⃣ Pack کردن
dotnet pack -c Release
# ✅ خودکار push می‌شه به GitLab

# 3️⃣ Update در لایه بالاتر
<PackageReference Include="PackageName" Version="NEW_VERSION" />

---

🔧 روش‌های Reference در BackOffice

روش 1: DLL Reference (Production/CI-CD) ✅ پیشنهادی

مزایا: مستقل از ریپوی BFF، مناسب CI/CD

# Build proto DLLs
cd BackOffice
./build-deps.sh

# DLLs در libs/ قرار می‌گیرند
ls libs/*.dll | wc -l  # 24 DLL

BackOffice.csproj:

<!-- CI/CD Mode: Use pre-built DLLs -->
<ItemGroup Condition="Exists('../../libs/BackOffice.BFF.Common.Protobuf.dll')">
    <Reference Include="BackOffice.BFF.Common.Protobuf">
        <HintPath>../../libs/BackOffice.BFF.Common.Protobuf.dll</HintPath>
    </Reference>
    <!-- ... all 24 proto DLLs ... -->
</ItemGroup>

<!-- Transitive Dependencies -->
<PackageReference Include="Google.Protobuf" Version="3.28.3"/>
<PackageReference Include="Grpc.Core.Api" Version="2.71.0"/>

---

روش 2: ProjectReference (Development)

مزایا: تغییرات بلافاصله اعمال می‌شود

<!-- Development Mode: Fallback if libs/ doesn't exist -->
<ItemGroup Condition="!Exists('../../libs/BackOffice.BFF.Common.Protobuf.dll')">
    <ProjectReference Include="..\..\..\BackOffice.BFF\src\Protobufs\BackOffice.BFF.Common.Protobuf\BackOffice.BFF.Common.Protobuf.csproj"/>
</ItemGroup>

---

روش 3: PackageReference (قدیمی)

مزایا: کنترل دقیق ورژن

<ItemGroup>
    <PackageReference Include="Foursat.BackOffice.BFF.Common.Protobuf" Version="1.0.0"/>
</ItemGroup>

معایب: نیاز به push به NuGet server

---

📝 اسکریپت build-deps.sh

مسیر: /home/masoud/Apps/project/FourSat/BackOffice/build-deps.sh

#!/bin/bash
# Build all BFF proto dependencies and copy DLLs to libs folder

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
LIBS_DIR="$SCRIPT_DIR/libs"
BFF_PROTOS_DIR="$SCRIPT_DIR/../BackOffice.BFF/src/Protobufs"

echo "🔧 Building all proto dependencies..."
mkdir -p "$LIBS_DIR"

# All 24 proto projects
PROTO_PROJECTS=(
    "BackOffice.BFF.Common.Protobuf"
    "BackOffice.BFF.Category.Protobuf"
    # ... (complete list)
)

for PROJECT in "${PROTO_PROJECTS[@]}"; do
    PROJECT_DIR="$BFF_PROTOS_DIR/$PROJECT"
    dotnet build "$PROJECT_DIR" -c Release --verbosity quiet
    
    # Check both net9.0 and net8.0
    if [ -f "$PROJECT_DIR/bin/Release/net9.0/$PROJECT.dll" ]; then
        cp "$PROJECT_DIR/bin/Release/net9.0/$PROJECT.dll" "$LIBS_DIR/"
    elif [ -f "$PROJECT_DIR/bin/Release/net8.0/$PROJECT.dll" ]; then
        cp "$PROJECT_DIR/bin/Release/net8.0/$PROJECT.dll" "$LIBS_DIR/"
    fi
done

echo "✅ Build complete! Total DLLs: $(ls $LIBS_DIR/*.dll | wc -l)"

---

🚀 Workflow توسعه

Development (Local):

# Build با Debug config
cd BackOffice/src
dotnet build -c Debug

# اگر libs/ نباشد → از ProjectReference استفاده می‌شود
# تغییرات Proto بلافاصله اعمال می‌شود

Production (Deploy):

# 1. Build proto DLLs
cd BackOffice
./build-deps.sh

# 2. Build & Publish
cd src
dotnet publish BackOffice/BackOffice.csproj -c Release -o ./publish

# 3. بررسی output
ls ./publish/wwwroot/_framework/*.wasm | grep "BackOffice.BFF" | wc -l
# Result: 24 ✅

---

📦 لیست Proto Projects

BackOffice.BFF (24 پروژه)

پروژه	Target Framework	وضعیت
BackOffice.BFF.Common.Protobuf	net9.0	✅
BackOffice.BFF.Category.Protobuf	net9.0	✅
BackOffice.BFF.ClubMembership.Protobuf	net9.0	✅
BackOffice.BFF.Commission.Protobuf	net9.0	✅
BackOffice.BFF.Configuration.Protobuf	net9.0	✅
BackOffice.BFF.DiscountCategory.Protobuf	net9.0	✅
BackOffice.BFF.DiscountOrder.Protobuf	net9.0	✅
BackOffice.BFF.DiscountProduct.Protobuf	net9.0	✅
BackOffice.BFF.DiscountShoppingCart.Protobuf	net9.0	✅
BackOffice.BFF.Health.Protobuf	net9.0	✅
BackOffice.BFF.Inventory.Protobuf	net9.0	✅
BackOffice.BFF.ManualPayment.Protobuf	net9.0	✅
BackOffice.BFF.NetworkMembership.Protobuf	net9.0	✅
BackOffice.BFF.Otp.Protobuf	net9.0	✅
BackOffice.BFF.Package.Protobuf	net9.0	✅
BackOffice.BFF.Products.Protobuf	net9.0	✅
BackOffice.BFF.ProductTag.Protobuf	net9.0	✅
BackOffice.BFF.PublicMessage.Protobuf	net8.0	✅
BackOffice.BFF.Role.Protobuf	net9.0	✅
BackOffice.BFF.Tag.Protobuf	net9.0	✅
BackOffice.BFF.User.Protobuf	net9.0	✅
BackOffice.BFF.UserAddress.Protobuf	net9.0	✅
BackOffice.BFF.UserOrder.Protobuf	net9.0	✅
BackOffice.BFF.UserRole.Protobuf	net9.0	✅

⚠️ نکته: PublicMessage.Protobuf تنها پروژه با net8.0 است

---

🔧 تنظیمات csproj با Auto-Push

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <PackageId>Foursat.BackOffice.BFF.Products.Protobuf</PackageId>
    <Version>1.0.0</Version>
    <Authors>FourSat</Authors>
    <Company>FourSat</Company>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    <PackageOutputPath>./nupkg</PackageOutputPath>
  </PropertyGroup>

  <!-- Auto-Push به GitLab -->
  <Target Name="PushToFoursatNuget" AfterTargets="Pack" 
          Condition="'$(Configuration)' == 'Release'">
    <PropertyGroup>
      <NugetPackagePath>$(PackageOutputPath)$(PackageId).$(Version).nupkg</NugetPackagePath>
      <PushCommand>dotnet nuget push **/*.nupkg --source https://git.se.kbs1.ir/api/packages/FourSat/nuget/index.json --api-key YOUR_API_KEY --skip-duplicate</PushCommand>
    </PropertyGroup>
    <Exec Command="$(PushCommand)" />
  </Target>

</Project>

---

🛠️ Troubleshooting

مشکل: Version Conflict

علامت:

error NU1605: Detected package downgrade: Grpc.Core.Api from 2.71.0 to 2.54.0

راه‌حل:

<PackageReference Include="Grpc.Core.Api" Version="2.71.0"/>

---

مشکل: Missing Transitive Dependencies

علامت:

CS0234: The type or namespace name 'Google' does not exist

راه‌حل: اضافه کردن dependencies در csproj:

<PackageReference Include="Google.Protobuf" Version="3.28.3"/>
<PackageReference Include="Google.Api.CommonProtos" Version="2.10.0"/>
<PackageReference Include="FluentValidation" Version="11.2.2"/>

---

مشکل: DLL Not Found

علامت:

warning MSB3245: Could not resolve this reference

راه‌حل:

# Rebuild all proto DLLs
cd BackOffice
rm -rf libs/
./build-deps.sh

---

مشکل: net8.0 vs net9.0

علامت: DLL یک پروژه کپی نشده

راه‌حل: اسکریپت build-deps.sh هر دو framework را چک می‌کند

---

📚 مراجع

• gRPC for .NET
• Protocol Buffers
• NuGet CLI Reference