خطة CI/CD واستراتيجية الإصدارات — نظام إدارة المغسلة¶

معلومات الوثيقة¶

الحقل	القيمة
المشروع	نظام إدارة المغسلة
الإصدار	1.0
اللغة	العربية
التحكم بالمصدر	GitHub
منصة CI/CD	GitHub Actions
استراتيجية التفريع	Git Flow
نوع الوثيقة	دليل CI/CD والإصدارات

جدول المحتويات¶

استراتيجية التفريع — Git Flow
نظرة عامة على سير العمل
بناء واختبار الخلفية
بناء الواجهة
بناء ورفع صور Docker
بناء تطبيق Tauri المكتبي
تجميع أصول الإصدار
توليد بيان التحديث التلقائي
استراتيجية ترميز الإصدارات (SemVer)
نشر بيئة Staging
سير النشر الإنتاجي
سير عمل المطورين
الأسرار ومتغيرات البيئة

1. استراتيجية التفريع — Git Flow¶

الفرع	الغرض	مشغل CI
`main`	كود جاهز للإنتاج	عند الدفع: بناء صور Docker + مثبتات Tauri + إنشاء GitHub Release
`develop`	فرع التكامل	عند PR: بناء + اختبار. عند الدمج: نشر إلى Staging
`feature/*`	تطوير خاصية جديدة	عند PR: بناء + اختبار فقط
`hotfix/*`	إصلاحات طارئة	عند PR: خط أنابيب كامل
`release/*`	تجهيز إصدار	عند PR: خط أنابيب كامل

2. نظرة عامة على سير العمل¶

دفع المطور لفرع feature
    │
    ▼
┌──────────────────────────────┐
│  GitHub Actions: build-test  │
│  • dotnet build + test       │
│  • npm ci + ng lint + test   │
└──────────────────────────────┘
    │
   فتح PR إلى develop
    │
┌──────────────────────────────┐
│  الشروط:                     │
│  ✅ جميع الاختبارات ناجحة     │
│  ✅ تغطية الكود ≥ 80%        │
│  ✅ مراجعة الكود معتمدة      │
└──────────────────────────────┘
    │
   دمج إلى develop → نشر Staging
    │
   دمج إلى main (أو release/*)
    │
    ▼
┌─────────────────────────────────────────┐
│  release.yml                             │
│  • بناء صور Docker + رفع لـ ghcr.io       │
│  • بناء Tauri (Windows/Mac/Linux)         │
│  • تجميع أصول الإصدار                     │
│  • توليد بيان التحديث التلقائي            │
│  • إنشاء GitHub Release                   │
└─────────────────────────────────────────┘

3. بناء واختبار الخلفية¶

# .github/workflows/build-and-test.yml
name: Build & Test

on:
  pull_request:
    branches: [develop, main]
  push:
    branches: [develop]

jobs:
  backend:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_DB: laundry_test
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
        ports: [5432:5432]

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: 10.0.x

      - run: dotnet restore backend/Laundry.sln
      - run: dotnet build backend/Laundry.sln --no-restore -c Release
      - run: dotnet test backend/Laundry.sln --no-build -c Release --collect:"XPlat Code Coverage"

4. بناء الواجهة¶

  frontend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci
        working-directory: frontend/laundry-app
      - run: npm run lint
        working-directory: frontend/laundry-app
      - run: npm run test -- --watch=false --browsers=ChromeHeadless --code-coverage
        working-directory: frontend/laundry-app
      - run: npm run build -- --configuration=production
        working-directory: frontend/laundry-app

5. بناء ورفع صور Docker¶

# .github/workflows/release.yml
on:
  push:
    tags: ['v*']

jobs:
  docker:
    runs-on: ubuntu-latest
    permissions:
      packages: write

    steps:
      - uses: actions/checkout@v4
      - name: Login to ghcr.io
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build frontend
        uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci && npm run build -- --configuration=production
        working-directory: frontend/laundry-app

      - name: Build & Push API Image
        uses: docker/build-push-action@v6
        with:
          context: .
          file: backend/Laundry.Api/Dockerfile
          push: true
          tags: |
            ghcr.io/${{ github.repository_owner }}/laundry-api:${{ github.ref_name }}
            ghcr.io/${{ github.repository_owner }}/laundry-api:latest

      - name: Export Docker images for offline deployment
        run: |
          docker save \
            ghcr.io/${{ github.repository_owner }}/laundry-api:${{ github.ref_name }} \
            postgres:16-alpine traefik:v3 datalust/seq:2024.1 \
            -o laundry-images.tar

6. بناء تطبيق Tauri المكتبي¶

  tauri:
    needs: [docker]
    strategy:
      matrix:
        include:
          - platform: windows-latest
            target: x86_64-pc-windows-msvc
          - platform: macos-latest
            target: aarch64-apple-darwin
          - platform: ubuntu-latest
            target: x86_64-unknown-linux-gnu

    runs-on: ${{ matrix.platform }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
        working-directory: frontend/laundry-app
      - uses: dtolnay/rust-toolchain@stable
      - name: Build Tauri
        uses: tauri-apps/tauri-action@v0
        with:
          projectPath: frontend/laundry-app
          args: --target ${{ matrix.target }}

تبني المنصات الثلاث (Windows, macOS, Linux) بالتوازي في GitHub Actions. تنتج مثبتات .msi و .dmg و .deb.

7. تجميع أصول الإصدار¶

  release:
    needs: [docker, tauri]
    permissions:
      contents: write

    steps:
      - uses: actions/download-artifact@v4
      - name: Create GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          name: Release ${{ github.ref_name }}
          files: |
            docker-images/laundry-images_*.tar
            tauri-windows-latest/msi/*.msi
            tauri-macos-latest/dmg/*.dmg
            tauri-ubuntu-latest/deb/*.deb

8. توليد بيان التحديث التلقائي¶

لـ Type 1 (الخادم المتصل)، يتحقق تطبيق Tauri من latest.json المنشور على GitHub Releases:

{
  "version": "1.0.1",
  "notes": "إصلاح خطأ ترقيم الفواتير",
  "pub_date": "2026-05-09T18:00:00Z",
  "platforms": {
    "windows-x86_64": {
      "url": "https://github.com/org/repo/releases/download/v1.0.1/LaundrySystem.msi"
    },
    "darwin-aarch64": {
      "url": "https://github.com/org/repo/releases/download/v1.0.1/LaundrySystem.dmg"
    },
    "linux-x86_64": {
      "url": "https://github.com/org/repo/releases/download/v1.0.1/laundry-system.deb"
    }
  }
}

9. استراتيجية ترميز الإصدارات (SemVer)¶

الصيغة	`v<MAJOR>.<MINOR>.<PATCH>`
`v1.0.0`	أول إصدار مستقر
`v1.0.1`	إصلاح خطأ (متوافق مع السابق)
`v1.1.0`	خاصية جديدة (متوافقة مع السابق)
`v2.0.0`	تغييرات جذرية

git checkout main
git tag -a v1.0.1 -m "Release v1.0.1: Fix invoice numbering"
git push origin v1.0.1
# ← يشغل release.yml تلقائياً

10. نشر بيئة Staging¶

on:
  push:
    branches: [develop]

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    steps:
      - uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.STAGING_HOST }}
          username: deploy
          key: ${{ secrets.STAGING_SSH_KEY }}
          script: |
            cd /opt/laundry-staging
            docker compose pull && docker compose up -d

11. سير النشر الإنتاجي¶

لا يتم النشر الإنتاجي تلقائياً أبداً. خط CI/CD ينتج الأصول فقط (صور Docker، مثبتات Tauri). النشر الإنتاجي يدوي بالكامل:

نوع العميل	طريقة النشر
Type 1 (خادم متصل)	المورّد يتصل SSH بالخادم. `docker compose pull && docker compose up -d`
Type 2/3 (فرع غير متصل)	تحميل أصل الإصدار `.tar.gz` من GitHub Releases → USB → زيارة الفرع → `docker load < images.tar && docker compose up -d`

12. سير عمل المطورين¶

git checkout -b feature/xxx develop

# تشغيل محلي
cd backend/Laundry.Api
docker compose -f docker-compose.dev.yml up -d postgres seq
dotnet run

cd frontend/laundry-app
npm install
npx tauri dev       # نافذة Tauri مع تحديث تلقائي

قائمة تدقيق Pull Request¶

[ ] جميع اختبارات الخلفية ناجحة
[ ] تغطية ≥ 80%
[ ] اختبارات الواجهة ناجحة + ESLint نظيف
[ ] بناء الإنتاج ناجح
[ ] Tauri يعمل في وضع التطوير
[ ] ترحيل EF Core مضاف إذا تغير المخطط
[ ] الترحيل مختبر على حاوية PostgreSQL جديدة

13. الأسرار ومتغيرات البيئة¶

أسرار GitHub¶

السر	الغرض
`GITHUB_TOKEN`	تلقائي — للرفع إلى ghcr.io وإنشاء الإصدارات
`STAGING_HOST`	IP خادم Staging
`STAGING_SSH_KEY`	مفتاح SSH لخادم Staging

متغيرات لكل عميل (أبداً في GitHub)¶

المتغير	كيفية التوليد
`DB_PASSWORD`	32 حرفاً عشوائياً — معالج التثبيت
`BRANCH_ID`	UUID — معالج التثبيت
`license.dat`	ملف مشفر — يصدره المورّد لكل عميل

سجل المراجعة¶

التاريخ	الإصدار	المعد	التغييرات
2026-05-10	1.0	مهندس النظم	الإصدار الأولي لخطة CI/CD