# مدیریت Package های Proto در FourSat با GitLab Registry

> **تاریخ**: December 6, 2025  
> **NuGet Server**: GitLab Package Registry (Afrino)  
> **URL**: `https://git.afrino.co/api/packages/FourSat/nuget/index.json`

---

## 📊 معماری فعلی

```
┌────────────────────────────────────────────────────┐
│  LAYER 1: CMS Proto (Base)                         │
│  CMSMicroservice.Protobuf                          │
│  Version: 0.0.142 → Auto-push به GitLab           │
└─────────────────┬──────────────────────────────────┘
                  │ PackageReference
                  ▼
┌────────────────────────────────────────────────────┐
│  LAYER 2: BFF Protos                               │
│  BackOffice.BFF.*.Protobuf (14 packages)           │
│  FrontOffice.BFF.*.Protobuf (8 packages)           │
│  → Depend on: CMS Proto v0.0.x                     │
└─────────────────┬──────────────────────────────────┘
                  │ PackageReference
                  ▼
┌────────────────────────────────────────────────────┐
│  LAYER 3: UI Applications                          │
│  BackOffice UI → BackOffice.BFF Protos             │
│  FrontOffice UI → FrontOffice.BFF Protos           │
└────────────────────────────────────────────────────┘
```

---

## 🔧 تنظیمات فعلی در csproj

شما از قبل این Target را دارید:

```xml
<Target Name="PushToFoursatNuget" AfterTargets="Pack">
  <PropertyGroup>
    <NugetPackagePath>$(PackageOutputPath)$(PackageId).$(Version).nupkg</NugetPackagePath>
    <PushCommand>dotnet nuget push **/*.nupkg --source https://git.afrino.co/api/packages/FourSat/nuget/index.json --api-key 061a5cb15517c6da39c16cfce8556c55ae104d0d --skip-duplicate &amp;&amp; del "$(NugetPackagePath)"</PushCommand>
  </PropertyGroup>
  <Exec Command="$(PushCommand)" />
</Target>
```

✅ **مزیت**: خودکار push می‌شه  
⚠️ **نیاز**: فقط Version افزایش پیدا کنه

---

## 🚀 Workflow پیشنهادی

### حالت 1️⃣: Development (Local)

```xml
<!-- Debug Mode: استفاده از ProjectReference -->
<ItemGroup Condition="'$(Configuration)' == 'Debug'">
  <ProjectReference Include="..\..\..\CMS\src\CMSMicroservice.Protobuf\CMSMicroservice.Protobuf.csproj" />
</ItemGroup>
```

**مزایا**:
- تغییرات بلافاصله اعمال می‌شود
- نیازی به build/pack/push نیست
- سرعت توسعه بالا

### حالت 2️⃣: Production (Release)

```xml
<!-- Release Mode: استفاده از PackageReference -->
<ItemGroup Condition="'$(Configuration)' == 'Release'">
  <PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="0.0.142" />
</ItemGroup>

<!-- Auto-Push Target -->
<Target Name="PushToFoursatNuget" AfterTargets="Pack" Condition="'$(Configuration)' == 'Release'">
  <!-- ... همان کدی که دارید -->
</Target>
```

**مزایا**:
- استقلال پروژه‌ها
- Version control دقیق
- امکان Rollback

---

## 📝 مثال کامل csproj

### CMSMicroservice.Protobuf.csproj

```xml
<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    
    <!-- Package Info -->
    <PackageId>Foursat.CMSMicroservice.Protobuf</PackageId>
    <Version>0.0.142</Version>  <!-- 👈 این خط را با script تغییر می‌دهیم -->
    <Authors>FourSat Team</Authors>
    <Company>Afrino</Company>
    <Description>gRPC Protobuf contracts for CMS Microservice</Description>
    <RepositoryUrl>https://git.afrino.co/FourSat/cms</RepositoryUrl>
  </PropertyGroup>

  <!-- Dependencies -->
  <ItemGroup>
    <PackageReference Include="Google.Protobuf" Version="3.23.3" />
    <PackageReference Include="Grpc.Core.Api" Version="2.54.0" />
    <PackageReference Include="Grpc.Tools" Version="2.55.1">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>

  <!-- Proto Files -->
  <ItemGroup>
    <Protobuf Include="Protos\*.proto" ProtoRoot="Protos\" GrpcServices="Both" />
  </ItemGroup>

  <!-- Auto-Push به GitLab (فقط در Release mode) -->
  <Target Name="PushToFoursatNuget" AfterTargets="Pack" Condition="'$(Configuration)' == 'Release'">
    <PropertyGroup>
      <NugetPackagePath>$(PackageOutputPath)$(PackageId).$(Version).nupkg</NugetPackagePath>
      <PushCommand>dotnet nuget push "$(NugetPackagePath)" --source https://git.afrino.co/api/packages/FourSat/nuget/index.json --api-key 061a5cb15517c6da39c16cfce8556c55ae104d0d --skip-duplicate</PushCommand>
    </PropertyGroup>
    <Exec Command="$(PushCommand)" />
    <!-- پاک کردن فایل بعد از push موفق -->
    <Delete Files="$(NugetPackagePath)" />
  </Target>

</Project>
```

### BackOffice.BFF.Products.Protobuf.csproj

```xml
<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <PackageId>Foursat.BackOffice.BFF.Products.Protobuf</PackageId>
    <Version>1.0.0</Version>  <!-- 👈 این را با script تغییر می‌دهیم -->
  </PropertyGroup>

  <!-- gRPC Dependencies -->
  <ItemGroup>
    <PackageReference Include="Google.Protobuf" Version="3.28.3" />
    <PackageReference Include="Grpc.Core.Api" Version="2.70.0" />
    <PackageReference Include="Grpc.Tools" Version="2.68.1">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

  <!-- 🔧 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="0.0.142" />
  </ItemGroup>

  <!-- Proto Files -->
  <ItemGroup>
    <Protobuf Include="Protos\products.proto" ProtoRoot="Protos\" GrpcServices="Both" />
  </ItemGroup>

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

</Project>
```

---

## 🔄 فرآیند Release جدید

### مرحله 1: افزایش Version

```bash
# افزایش Patch version (0.0.142 → 0.0.143)
./bump-version.sh patch

# افزایش Minor version (0.0.142 → 0.1.0)
./bump-version.sh minor

# افزایش Major version (0.0.142 → 1.0.0)
./bump-version.sh major

# افزایش version یک پروژه خاص
./bump-version.sh patch /path/to/Project.csproj
```

### مرحله 2: Build & Pack (Auto-Push)

```bash
# Build & Pack CMS Proto (Layer 1)
cd /home/masoud/Apps/project/FourSat/CMS/src/CMSMicroservice.Protobuf
dotnet pack -c Release

# ✅ بعد از Pack، خودکار push می‌شه به GitLab!
```

### مرحله 3: Update BFF Dependencies

```bash
# بعد از push CMS Proto، version جدید را در BFF ها update کنید:
# BackOffice.BFF.Products.Protobuf.csproj:

<ItemGroup Condition="'$(Configuration)' == 'Release'">
  <PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="0.0.143" />  <!-- ⬅️ Update -->
</ItemGroup>
```

### مرحله 4: Build & Pack BFF Protos (Layer 2)

```bash
# Build & Pack همه BackOffice.BFF Protos
cd /home/masoud/Apps/project/FourSat/BackOffice.BFF/src/Protobufs

for dir in BackOffice.BFF.*.Protobuf; do
    cd "$dir"
    dotnet pack -c Release  # ✅ Auto-push می‌شه
    cd ..
done
```

### مرحله 5: Update UI Dependencies

```bash
# BackOffice.csproj:

<ItemGroup Condition="'$(Configuration)' == 'Release'">
  <PackageReference Include="Foursat.BackOffice.BFF.Products.Protobuf" Version="1.0.1" />  <!-- ⬅️ Update -->
  <!-- ... other protos -->
</ItemGroup>
```

---

## 🛠️ Scripts خودکار

### 1. `bump-version.sh` - افزایش Version

```bash
# همه Proto projects
./bump-version.sh patch

# یک پروژه خاص
./bump-version.sh minor CMS/src/CMSMicroservice.Protobuf/CMSMicroservice.Protobuf.csproj
```

### 2. `release-proto.sh` - Release کامل

```bash
#!/bin/bash

# 1. Bump version
./bump-version.sh patch

# 2. Build & Pack (Auto-push)
cd CMS/src/CMSMicroservice.Protobuf
dotnet pack -c Release

# 3. Commit changes
git add .
git commit -m "chore: bump proto version"
git push
```

---

## 📊 Version Strategy

```
0.0.142  →  Current CMS Proto version
│ │  │
│ │  └── PATCH: Bug fixes, compatible changes
│ └───── MINOR: New features, compatible
└────── MAJOR: Breaking changes
```

**مثال**:
- اضافه کردن فیلد جدید → **PATCH** (0.0.143)
- اضافه کردن RPC جدید → **MINOR** (0.1.0)
- تغییر signature RPC → **MAJOR** (1.0.0)

---

## 🔍 بررسی Packages روی GitLab

```bash
# اضافه کردن GitLab source
dotnet nuget add source https://git.afrino.co/api/packages/FourSat/nuget/index.json \
  --name foursat-gitlab \
  --username YOUR_USERNAME \
  --password 061a5cb15517c6da39c16cfce8556c55ae104d0d \
  --store-password-in-clear-text

# جستجو
dotnet nuget search Foursat --source foursat-gitlab

# نصب
dotnet add package Foursat.CMSMicroservice.Protobuf --version 0.0.142 --source foursat-gitlab
```

---

## ⚙️ nuget.config (Optional)

```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="foursat-gitlab" value="https://git.afrino.co/api/packages/FourSat/nuget/index.json" />
  </packageSources>
  
  <packageSourceCredentials>
    <foursat-gitlab>
      <add key="Username" value="foursat" />
      <add key="ClearTextPassword" value="061a5cb15517c6da39c16cfce8556c55ae104d0d" />
    </foursat-gitlab>
  </packageSourceCredentials>
</configuration>
```

---

## 🎯 خلاصه

✅ **Development** → Debug build → `ProjectReference` → سرعت بالا  
✅ **Production** → Release build → `PackageReference` → استقلال  
✅ **Auto-Push** → بعد از Pack خودکار به GitLab می‌ره  
✅ **Version Bump** → با `bump-version.sh` خودکار  
✅ **Rollback** → برگشت به version قبلی ساده  

---

**تاریخ**: December 6, 2025  
**NuGet Registry**: GitLab (Afrino)  
**Current CMS Version**: 0.0.142