docs/PROTO-QUICK-START.md

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)

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

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

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

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

# فقط ساخت 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

# اضافه کردن 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):

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

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

Production (Deploy):

# 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

---

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

# جستجو در 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):

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

Production (Release):

<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

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

<!-- قبل: -->
<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 پیدا نمی‌شود

# بررسی 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

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

# Restore دوباره
dotnet restore

# Build
dotnet build -c Release

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

# بررسی 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