# راهنمای 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