# Proto Package Management - Quick Start

این فایل یک راهنمای سریع برای مدیریت Proto Packages در پروژه FourSat است.

---

## 📦 فایل‌های مهم

| فایل | توضیحات |
|------|---------|
| `PROTO-PACKAGING-GUIDE.md` | راهنمای کامل و جامع (همه جزئیات) |
| `pack-protos.sh` | Script خودکار برای Package کردن همه Proto ها |
| `docker-compose.baget.yml` | راه‌اندازی Private NuGet Server |
| `EXAMPLE-PROTO-CSPROJ.xml` | مثال csproj با تنظیمات Debug/Release |

---

## 🚀 شروع سریع

### 1. راه‌اندازی NuGet Server (اختیاری برای Local Development)

```bash
# شروع BaGet با Docker
docker-compose -f docker-compose.baget.yml up -d

# بررسی وضعیت
docker ps | grep baget

# دسترسی به UI
# مرورگر: http://localhost:5555
```

### 2. Package کردن همه Proto ها

```bash
# فقط ساخت packages (بدون push)
./pack-protos.sh

# ساخت و push به NuGet server
./pack-protos.sh --push

# استفاده از custom server
NUGET_SERVER=https://nuget.foursat.com ./pack-protos.sh --push
```

### 3. اضافه کردن NuGet Source

```bash
# اضافه کردن local BaGet
dotnet nuget add source http://localhost:5555/v3/index.json \
  --name foursat-local \
  --username foursat \
  --password FOURSAT-SECRET-API-KEY-2025 \
  --store-password-in-clear-text

# بررسی sources
dotnet nuget list source
```

---

## 🔄 Workflow توسعه

### Development (Local):

```bash
# Build با Debug config → استفاده از ProjectReference
cd BackOffice/src
dotnet build -c Debug

# همه تغییرات Proto بلافاصله اعمال می‌شود
```

### Production (Deploy):

```bash
# 1. Package کردن CMS Proto
cd CMS/src/CMSMicroservice.Protobuf
dotnet pack -c Release -o ./nupkg

# 2. Push به NuGet Server
dotnet nuget push ./nupkg/*.nupkg \
  --source http://localhost:5555/v3/index.json \
  --api-key FOURSAT-SECRET-API-KEY-2025

# 3. Package کردن BFF Protos (وابسته به CMS)
cd BackOffice.BFF/src/Protobufs
# ... (مشابه)

# 4. Build UI با Release config → استفاده از PackageReference
cd BackOffice/src
dotnet build -c Release
```

---

## 📊 ساختار Packages

```
Foursat.CMSMicroservice.Protobuf (v1.0.0)
  └─ Base Proto Layer
     └─ استفاده شده در:
        ├─ Foursat.BackOffice.BFF.Products.Protobuf
        ├─ Foursat.BackOffice.BFF.User.Protobuf
        ├─ Foursat.BackOffice.BFF.*.Protobuf (12 package دیگر)
        ├─ Foursat.FrontOffice.BFF.Products.Protobuf
        └─ Foursat.FrontOffice.BFF.*.Protobuf (7 package دیگر)
```

**تعداد کل Packages**: ~23 package

---

## 🔍 دستورات مفید

```bash
# جستجو در local NuGet server
dotnet nuget search Foursat --source foursat-local

# نصب یک package
dotnet add package Foursat.CMSMicroservice.Protobuf \
  --version 1.0.0 \
  --source foursat-local

# بررسی dependencies
dotnet list package --include-transitive

# حذف package cache
dotnet nuget locals all --clear

# بررسی محتویات package
unzip -l package.nupkg
```

---

## ⚙️ تنظیمات csproj

### Development (Debug):
```xml
<ItemGroup Condition="'$(Configuration)' == 'Debug'">
  <ProjectReference Include="..\..\CMS\src\CMSMicroservice.Protobuf\CMSMicroservice.Protobuf.csproj" />
</ItemGroup>
```

### Production (Release):
```xml
<ItemGroup Condition="'$(Configuration)' == 'Release'">
  <PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="1.0.0" />
</ItemGroup>
```

**مثال کامل**: `EXAMPLE-PROTO-CSPROJ.xml`

---

## 📝 Versioning

### Semantic Versioning (SemVer):

```
MAJOR.MINOR.PATCH

1.0.0 → Initial release
1.0.1 → Bug fix
1.1.0 → New feature (backward compatible)
2.0.0 → Breaking change
```

### مثال تغییر نسخه:

```xml
<!-- قبل: -->
<Version>1.0.0</Version>

<!-- بعد از اضافه کردن فیلد جدید (compatible): -->
<Version>1.1.0</Version>

<!-- بعد از تغییر RPC signature (breaking): -->
<Version>2.0.0</Version>
```

---

## 🎯 نکات مهم

1. ✅ **Local Development**: همیشه با `Debug` build کار کنید
2. ✅ **Production Build**: همیشه با `Release` build
3. ✅ **Version Bump**: هر تغییر در Proto → نسخه جدید
4. ✅ **Push Order**: اول CMS، بعد BFF ها، آخر UI ها
5. ✅ **Testing**: قبل از push حتماً test کنید

---

## 🆘 عیب‌یابی

### مشکل: Package پیدا نمی‌شود

```bash
# بررسی source ها
dotnet nuget list source

# اضافه کردن source
dotnet nuget add source http://localhost:5555/v3/index.json --name foursat-local

# پاک کردن cache
dotnet nuget locals all --clear
```

### مشکل: Version conflict

```bash
# حذف obj و bin
find . -name "obj" -o -name "bin" | xargs rm -rf

# Restore دوباره
dotnet restore

# Build
dotnet build -c Release
```

### مشکل: BaGet server در دسترس نیست

```bash
# بررسی container
docker ps | grep baget

# restart container
docker-compose -f docker-compose.baget.yml restart

# لاگ‌ها
docker logs foursat-nuget-server
```

---

## 📚 منابع بیشتر

- **راهنمای کامل**: `PROTO-PACKAGING-GUIDE.md`
- **BaGet Documentation**: https://loic-sharma.github.io/BaGet/
- **NuGet CLI Reference**: https://docs.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference
- **Semantic Versioning**: https://semver.org/

---

**تاریخ**: December 6, 2025  
**نسخه**: 1.0.0  
**پروژه**: FourSat