BackOffice/docs/SESSION-2026-01-03-PROTO-DLL-MIGRATION.md

Session 2026-01-03: Proto DLL Migration & Domain Changes

تاریخ: January 3, 2026
موضوع: مایگریشن به DLL-based Proto References + تغییر دامنه‌ها

---

📋 خلاصه تغییرات

1. ✅ مایگریشن Proto References به DLL-based Approach

مشکل: در CI/CD نمی‌توانستیم از ProjectReference به پروژه‌های proto در BackOffice.BFF استفاده کنیم چون ریپوها جدا هستند.

راه‌حل: ایجاد سیستم hybrid با DLL های pre-built:

فایل‌های ایجاد شده:

1. BackOffice/build-deps.sh:

   #!/bin/bash
   # Build all BFF proto dependencies and copy DLLs to libs folder
   
   # Builds all 24 proto projects from BackOffice.BFF/src/Protobufs/
   # Copies DLLs to BackOffice/libs/ folder
   # Supports both net8.0 and net9.0 target frameworks
   

2. BackOffice/libs/: فولدر شامل 24 فایل DLL:

   • BackOffice.BFF.Category.Protobuf.dll
   • BackOffice.BFF.ClubMembership.Protobuf.dll
   • BackOffice.BFF.Commission.Protobuf.dll
   • BackOffice.BFF.Common.Protobuf.dll
   • BackOffice.BFF.Configuration.Protobuf.dll
   • BackOffice.BFF.DiscountCategory.Protobuf.dll
   • BackOffice.BFF.DiscountOrder.Protobuf.dll
   • BackOffice.BFF.DiscountProduct.Protobuf.dll
   • BackOffice.BFF.DiscountShoppingCart.Protobuf.dll
   • BackOffice.BFF.Health.Protobuf.dll
   • BackOffice.BFF.Inventory.Protobuf.dll
   • BackOffice.BFF.ManualPayment.Protobuf.dll
   • BackOffice.BFF.NetworkMembership.Protobuf.dll
   • BackOffice.BFF.Otp.Protobuf.dll
   • BackOffice.BFF.Package.Protobuf.dll
   • BackOffice.BFF.Products.Protobuf.dll
   • BackOffice.BFF.ProductTag.Protobuf.dll
   • BackOffice.BFF.PublicMessage.Protobuf.dll ⚠️ (net8.0)
   • BackOffice.BFF.Role.Protobuf.dll
   • BackOffice.BFF.Tag.Protobuf.dll
   • BackOffice.BFF.User.Protobuf.dll
   • BackOffice.BFF.UserAddress.Protobuf.dll
   • BackOffice.BFF.UserOrder.Protobuf.dll
   • BackOffice.BFF.UserRole.Protobuf.dll

تغییرات در BackOffice/src/BackOffice/BackOffice.csproj:

PackageReferences اضافه شده (برای transitive dependencies):

<!-- Proto dependencies (needed when using DLL references) -->
<PackageReference Include="Google.Protobuf" Version="3.28.3"/>
<PackageReference Include="Grpc.Core.Api" Version="2.71.0"/>
<PackageReference Include="Google.Api.CommonProtos" Version="2.10.0"/>
<PackageReference Include="FluentValidation" Version="11.2.2"/>
<PackageReference Include="FluentValidation.DependencyInjectionExtensions" Version="11.2.2"/>

Conditional ItemGroups:

<!-- CI/CD Mode: Use pre-built DLLs from libs/ folder -->
<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>

<!-- Development Mode: Fallback to ProjectReference 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"/>
    <!-- ... all 24 proto projects ... -->
</ItemGroup>

تغییرات در BackOffice/Dockerfile:

# Copy pre-built proto DLLs
COPY ["libs/", "libs/"]

مشکلات حل شده:

1. Google.Protobuf Version Conflict:

   • مشکل: PublicMessage.Protobuf از ورژن 3.28.3 استفاده می‌کرد ولی بقیه از 3.23.3
   • راه‌حل: آپگرید به 3.28.3 در BackOffice.csproj

2. Grpc.Core.Api Version Conflict:

   • مشکل: Downgrade از 2.71.0 به 2.54.0
   • راه‌حل: تنظیم explicit version 2.71.0 در BackOffice.csproj

3. PublicMessage.Protobuf Missing:

   • مشکل: این پروژه net8.0 است نه net9.0
   • راه‌حل: اسکریپت build-deps.sh حالا هر دو framework را چک می‌کند

نتیجه:

✅ Build: SUCCESS (0 Errors, 246 Warnings - فقط MudBlazor)
✅ Publish: SUCCESS - همه 24 proto assembly به WASM کامپایل شدند
✅ CI/CD Ready: می‌توان با ./build-deps.sh قبل از build، DLL ها را آماده کرد

---

2. ✅ تغییر دامنه‌ها (Domain Migration)

تغییر از *.foursat.afrino.co به *.se.kbs1.ir

دستور اجرا شده:

cd /home/masoud/Apps/project/FourSat
find . -type f \( -name "*.json" -o -name "*.yml" -o -name "*.yaml" \) \
  -exec sed -i 's/foursat\.afrino\.co/se.kbs1.ir/g' {} \;

فایل‌های تغییر یافته:

Workflow Files (.gitea/workflows/*.yml):

• BackOffice/.gitea/workflows/prod-deploy.yml
• BackOffice/.gitea/workflows/kub-deploy.yml
• BackOffice.BFF/.gitea/workflows/prod-deploy.yml
• BackOffice.BFF/.gitea/workflows/kub-deploy.yml
• FrontOffice/.gitea/workflows/prod-deploy.yml
• FrontOffice/.gitea/workflows/kub-deploy.yml
• FrontOffice.BFF/.gitea/workflows/prod-deploy.yml
• FrontOffice.BFF/.gitea/workflows/kub-deploy.yml
• CMS/.gitea/workflows/prod-deploy.yml
• CMS/.gitea/workflows/kub-deploy.yml

تغییرات در Workflows:

# قبل:
EXTERNAL_REGISTRY: git.foursat.afrino.co
"insecure-registries": ["git.foursat.afrino.co", "gitea-svc:3000"]

# بعد:
EXTERNAL_REGISTRY: git.se.kbs1.ir
"insecure-registries": ["git.se.kbs1.ir", "gitea-svc:3000"]

Configuration Files (appsettings):

• BackOffice/src/BackOffice/wwwroot/appsettings.json
• BackOffice/src/BackOffice/wwwroot/appsettings.Staging.json
• FrontOffice/src/FrontOffice.Main/appsettings.json
• FrontOffice/src/FrontOffice.Main/appsettings.Staging.json
• FrontOffice.BFF/src/FrontOffice.BFF.WebApi/appsettings.json

تغییرات در appsettings:

// BackOffice
"GwUrl": "https://backoffice-bff.se.kbs1.ir"

// FrontOffice
"GwUrl": "https://frontoffice-bff.se.kbs1.ir"

// FrontOffice.BFF
"CMSMSAddress": "https://cms.se.kbs1.ir"

نتیجه:

✅ 21 فایل با موفقیت تغییر کرد
✅ 0 آدرس قدیمی باقی مانده

---

3. ✅ تغییر Git Remote URLs

دستورات اجرا شده:

# FrontOffice
cd FrontOffice
git remote set-url kub-stage https://git.se.kbs1.ir/admin/FrontOffice.git

# BackOffice
cd BackOffice
git remote set-url kub-stage https://git.se.kbs1.ir/admin/BackOffice.git

# BackOffice.BFF
cd BackOffice.BFF
git remote set-url kub-stage https://git.se.kbs1.ir/admin/BackOffice.BFF.git

# FrontOffice.BFF
cd FrontOffice.BFF
git remote set-url kub-stage https://git.se.kbs1.ir/admin/FrontOffice.BFF.git

# CMS
cd CMS
git remote set-url gitea https://git.se.kbs1.ir/admin/CMS.git

# totalDoc
cd totalDoc
git remote set-url foursatDocs https://git.se.kbs1.ir/FourSat/docs.git

نتیجه:

✅ 6 ریپو بروز شد
✅ همه remote ها به git.se.kbs1.ir تغییر کرد

---

📊 آمار کلی

مورد	تعداد
Proto DLL های ایجاد شده	24
فایل‌های JSON/YAML تغییر یافته	21
Git Repositories بروز شده	6
Build Errors	0 ✅
Build Warnings	246 (MudBlazor)

---

🚀 دستورات CI/CD

قبل از Build/Deploy:

# 1. Build proto dependencies
cd /home/masoud/Apps/project/FourSat/BackOffice
./build-deps.sh

# 2. Build project
cd src
dotnet build BackOffice.sln -c Release

# 3. Publish
dotnet publish BackOffice/BackOffice.csproj -c Release -o ./publish

بررسی Output:

# تعداد proto assemblies در output
ls ./publish/wwwroot/_framework/*.wasm | grep "BackOffice.BFF" | wc -l
# Result: 24 ✅

---

🔧 Troubleshooting

اگر Build شکست:

1. بررسی libs/ folder:

   ls BackOffice/libs/*.dll | wc -l
   # باید 24 باشد
   

2. Rebuild proto dependencies:

   cd BackOffice
   rm -rf libs/
   ./build-deps.sh
   

3. بررسی Package Versions:

   • Google.Protobuf: باید 3.28.3 باشد
   • Grpc.Core.Api: باید 2.71.0 باشد

اگر Git Push شکست:

# تست اتصال به remote جدید
git ls-remote https://git.se.kbs1.ir/admin/BackOffice.git

---

📝 نکات مهم

1. PublicMessage.Protobuf تنها پروژه‌ای است که net8.0 دارد
2. اسکریپت build-deps.sh خودکار هر دو framework را چک می‌کند
3. در Development Mode می‌توان از ProjectReference استفاده کرد (اگر libs/ وجود نداشته باشد)
4. همه آدرس‌های *.foursat.afrino.co به *.se.kbs1.ir تغییر کرد
5. همه Git remote ها بروز شدند

---

✅ Status: COMPLETED

تاریخ تکمیل: January 3, 2026
Build Status: ✅ SUCCESS
Publish Status: ✅ SUCCESS
Domain Migration: ✅ COMPLETED
Git Remotes: ✅ UPDATED