masoodafar-web
250 lines
5.5 KiB
Markdown
250 lines
5.5 KiB
Markdown
# 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
|