Sedat ÖZTÜRK f292b6b6a5 Migrations ve Seeds düzenlemesi

2026-08-12 15:20:00 +03:00

45 KiB

Raw Blame History

Sozsoft Platform

Çalışma zamanında yapılandırılabilen, çok kiracılı (multi-tenant) low-code uygulama motoru.

Sozsoft Platform, klasik bir "kod yaz–derle–yayınla" uygulaması değildir. Ekranlar, menüler, route'lar, yetkiler, veri kaynakları, iş akışları ve hatta API endpoint'leri veritabanındaki konfigürasyon kayıtlarından üretilir. Yeni bir modül veya ekran eklemek çoğu durumda tek satır React/C# kodu yazmadan, yalnızca konfigürasyon ile mümkündür.

Temel ilke: Configuration first, code last. Bu ilkenin operasyonel karşılığı ve yapay zeka ajanları için bağlayıcı kurallar .github/instructions/ai.instructions.md dosyasındadır.

İçindekiler

Platform Ne Yapar?
Mimari Genel Bakış
Teknoloji Yığını
Depo Yapısı
Hızlı Başlangıç
Yapılandırma (Configuration)
Low-Code Motoru: ListForm Ekosistemi
Developer Kit
Dinamik Menü, Route ve Yetki Modeli
Modül Kataloğu
Kimlik, Oturum ve Güvenlik
Çok Kiracılılık (Multi-Tenancy)
Bildirim ve Entegrasyonlar
Arka Plan İşleri
Raporlama
Dosya Yönetimi ve CDN
Gerçek Zamanlı Özellikler
Frontend Mimarisi
API ve Swagger
Dağıtım (Deployment)
Geliştirme Standartları ve Sık Kullanılan Komutlar
Sorun Giderme
Bilinen Sınırlar ve Notlar

1. Platform Ne Yapar?

Yetenek	Açıklama
Dinamik liste/form ekranları	`ListForm` + `ListFormField` kayıtlarıyla tanımlanan; grid, pivot, ağaç, grafik, gantt, scheduler, kart ve todo görünümlerini destekleyen ekranlar.
Dinamik menü ve route	Menüler ve route'lar veritabanından okunur; frontend bunları çalışma zamanında React Router'a bağlar.
Yetki tabanlı görünürlük	Menü, ekran, sütun ve buton seviyesinde ABP permission kontrolü.
SQL Query Manager	Tarayıcı içinden SQL nesne gezgini, sorgu editörü, sonuç grid'i ve tablo tasarımcısı.
Custom / CRUD Endpoint	Kod yazmadan, SQL veya tablo tanımından REST endpoint üretimi.
Dynamic Service	Roslyn ile çalışma zamanında derlenen ve controller olarak kaydedilen C# ApplicationService'ler.
Custom Component	Babel ile tarayıcıda derlenen, veritabanında saklanan React bileşenleri ve bunların route'ları.
İş akışı / onay	ListForm üzerinde görsel workflow tasarımcısı, koşullu dallanma ve çok kişili onay adımları.
Çok kiracılılık	Tenant başına ayrı bağlantı dizesi (ayrı veritabanı) desteği, şube (branch) ve organizasyon birimi kırılımı.
Bildirim ve entegrasyon	SMS, e-posta, WhatsApp, Rocket.Chat, masaüstü ve UI kanallarına kural tabanlı bildirim.
Raporlama	DevExpress Report Designer/Viewer + ListForm'dan otomatik üretilen dinamik raporlar.
Arka plan işleri	Hangfire + ABP Background Worker; zamanlanmış SQL, mail kuyruğu, yedekleme, oturum temizliği.
Gerçek zamanlı	SignalR tabanlı messenger ve video oda (WebRTC/TURN) altyapısı.
Intranet & Forum	Duyuru, anket, sosyal duvar, etkinlik; kategori/konu/gönderi tabanlı forum.
Public web sitesi	Ana sayfa, hakkımızda, hizmetler, ürün, ödeme, blog, demo ve iletişim içerikleri (tasarımcı ekranlarıyla düzenlenebilir).
PWA	Service worker ile offline kabuk, kontrollü sürüm güncellemesi ve changelog bildirimi.

2. Mimari Genel Bakış

┌──────────────────────────────────────────────────────────────────────┐
│  UI  —  React 18 + Vite + TypeScript + DevExtreme + Tailwind (PWA)   │
│  ├─ DynamicRouter        (route kayıtlarından React Router üretimi)  │
│  ├─ ListForm runtime     (Grid / Pivot / Tree / Chart / Gantt / ...) │
│  ├─ Form runtime         (DevExtreme Form, metadata ile alan üretimi)│
│  ├─ Developer Kit UI     (SQL, endpoint, component, dynamic service) │
│  └─ easy-peasy store + React Query + SignalR                        │
└───────────────┬──────────────────────────────────────────────────────┘
                │ HTTPS / OAuth2 (OpenIddict) / SignalR
┌───────────────▼──────────────────────────────────────────────────────┐
│  API  —  ASP.NET Core (.NET 10) + ABP Framework 10                   │
│  ├─ HttpApi.Host   : Swagger, OpenIddict, Hangfire, SignalR Hub,     │
│  │                   DevExpress Reporting, Setup/Migration akışı     │
│  ├─ Application    : ListForms, DeveloperKit, Identity, Tenants,     │
│  │                   Menu, Routes, DataSource, FileManagement, ...   │
│  ├─ Domain         : Entity'ler, dinamik veri erişimi, seed'ler      │
│  └─ EF Core        : Migration'lar, dinamik DbContext, tenant DB     │
│                                                                      │
│  Modüller: Languages · Settings · Notifications · MailQueue ·        │
│            Sender · SqlQueryManager                                  │
└───────────────┬──────────────────────────────────────────────────────┘
                │
┌───────────────▼──────────────────────────────────────────────────────┐
│  Veri ve Altyapı                                                     │
│  SQL Server / PostgreSQL · Redis (cache + SignalR backplane) ·       │
│  Hangfire (job storage) · Dosya sistemi tabanlı BLOB/CDN ·           │
│  coturn (TURN) · nginx · Elasticsearch (opsiyonel)                   │
└──────────────────────────────────────────────────────────────────────┘

Akışın özeti: Kullanıcı giriş yapar → ABP application-configuration yanıtına PlatformApplicationConfigurationContributor menü, route ve yetkileri ekler → DynamicRouter route kayıtlarını React bileşenlerine bağlar → /admin/list/{ListFormCode} gibi bir ekran açıldığında ListFormsAppService metadata'yı, ListFormDataAppService ise veriyi döner → DevExtreme bileşenleri bu metadata'ya göre kendini kurar.

3. Teknoloji Yığını

Backend

Bileşen	Sürüm / Notlar
.NET	`net10.0` (SDK 10.0.300, `global.json` ile sabit)
ABP Framework	10.0.0 (Identity, TenantManagement, PermissionManagement, AuditLogging, OpenIddict, BlobStoring, BackgroundWorkers)
Veritabanı	SQL Server 2022 veya PostgreSQL 17 (`PlatformConsts.DefaultDatabaseProvider`)
ORM	Entity Framework Core
Kimlik	OpenIddict (password + refresh token, `/connect/token`)
Cache	Redis (opsiyonel; `Redis:IsEnabled`)
Job	Hangfire (`default`, `platform` kuyrukları) + ABP Background Workers
Raporlama	DevExpress Reporting (Web Document Viewer + Report Designer)
Log	Serilog
Dinamik derleme	Roslyn (`DynamicServiceCompiler`)
Şablon	Scriban (mail şablonları), MailKit/MimeKit
Gerçek zamanlı	SignalR (Redis backplane destekli)

Frontend

Bileşen	Sürüm / Notlar
React	18.3
Build	Vite 8 + TypeScript 5.9
UI kütüphaneleri	DevExtreme 25.2 (React), Tailwind CSS 3.4, kendi `components/ui` tasarım sistemi
Routing	react-router-dom 6 (dinamik route üretimi)
State	easy-peasy (global store) + @tanstack/react-query
Form	Formik + Yup, DevExtreme Form
Kod editörü	Monaco Editor
Runtime derleme	@babel/standalone (Custom Component)
Takvim/Gantt	FullCalendar, DevExtreme Scheduler/Gantt
Gerçek zamanlı	@microsoft/signalr
PWA	vite-plugin-pwa (Workbox)
Node	24.13 / npm 11 (`volta` ile sabitlenmiş)

4. Depo Yapısı

sozsoft-platform/
├── api/                                   # .NET çözümü (Sozsoft.Platform.sln)
│   ├── src/
│   │   ├── Sozsoft.Platform.Domain.Shared/    # Sabitler, enum'lar, permission kodları (AppCodes)
│   │   ├── Sozsoft.Platform.Domain/           # Entity'ler, dinamik veri erişimi, repository'ler
│   │   ├── Sozsoft.Platform.Application.Contracts/  # DTO'lar, servis arayüzleri, permission tanımları
│   │   ├── Sozsoft.Platform.Application/      # Uygulama servisleri (iş mantığı)
│   │   ├── Sozsoft.Platform.EntityFrameworkCore/    # DbContext, migration'lar, dinamik veri katmanı
│   │   ├── Sozsoft.Platform.HttpApi/          # Controller'lar (conventional)
│   │   ├── Sozsoft.Platform.HttpApi.Client/   # HTTP istemci proxy'leri
│   │   ├── Sozsoft.Platform.HttpApi.Host/     # Host: Swagger, auth, Hangfire, SignalR, raporlama
│   │   └── Sozsoft.Platform.DbMigrator/       # Migration + seed uygulaması
│   ├── modules/                           # Bağımsız ABP modülleri
│   │   ├── Sozsoft.Languages/                 # Dil, dil anahtarı, çeviri metinleri
│   │   ├── Sozsoft.Settings/                  # Ayar tanımları ve ayar UI'ı
│   │   ├── Sozsoft.Notifications/             # Bildirim tipleri, kuralları, kullanıcı bildirimleri
│   │   ├── Sozsoft.MailQueue/                 # Şablonlu mail kuyruğu ve ekleri
│   │   ├── Sozsoft.Sender/                    # Mail (SES), SMS, WhatsApp, Rocket.Chat göndericileri
│   │   └── Sozsoft.SqlQueryManager/           # SQL nesne yönetimi ve sorgu çalıştırma
│   └── test/                              # Test projeleri
├── ui/                                    # React uygulaması
│   └── src/
│       ├── routes/        # dynamicRouter, dynamicRouteLoader, route.constant
│       ├── views/         # list, form, admin, developerKit, public, intranet, forum, report, auth, setup
│       ├── components/    # ui (tasarım sistemi), template (layout), importManager, visualDesigner, componentEditor
│       ├── services/      # API istemcileri (her modül için ayrı servis dosyası)
│       ├── store/         # easy-peasy modelleri (auth, theme, locale, abpConfig, admin)
│       ├── contexts/      # ComponentContext (runtime bileşenler), Dialog, Scroll
│       └── utils/         # editorScriptRuntime, workflow, hooks, hoc, biçimlendirme yardımcıları
├── configs/
│   ├── docker/            # Yerel geliştirme için veri katmanı compose dosyaları ve scriptler
│   ├── deployment/        # Dev/Prod compose dosyaları, nginx/redis/turn konfigürasyonu, deploy scriptleri
│   └── ai/                # AI entegrasyonu (n8n akış tanımları)
├── .github/instructions/  # ai.instructions.md (bağlayıcı platform kuralları), list.instructions.md
├── CLAUDE.md              # Claude Code için operasyon kuralları
└── README.md

5. Hızlı Başlangıç

5.1. Önkoşullar

.NET SDK 10.0.300+
Node.js 24.x ve npm 11.x (Volta önerilir)
Docker Desktop (veritabanı ve Redis için)
DevExpress lisansı (api/DevExpress_License.txt) ve DevExtreme npm erişimi

5.2. Veri katmanını ayağa kaldırma

# SQL Server + Redis
.\configs\docker\start_sql.bat

# veya PostgreSQL + Redis
.\configs\docker\start_postgres.bat

Compose dosyaları configs/docker/docker-compose-data.yml içindedir; sql ve postgres profilleri ile hangi veritabanının kalkacağı seçilir. Redis her iki profilde de çalışır.

5.3. Backend

cd api
dotnet restore
dotnet run --project src/Sozsoft.Platform.HttpApi.Host

Uygulama https://localhost:44344 adresinde açılır. Swagger UI kök adreste yayınlanır.

Veritabanı ilk kurulum: Veritabanı yoksa host, tam ABP yığını yerine minimal bir "setup" uygulaması ile açılır (DbStartup/SetupAppRunner). Bu durumda:

GET /api/setup/application-status — veritabanının hazır olup olmadığını döner (anonim).
UI tarafında /setup route'u (views/setup/DatabaseSetup.tsx) migration'ı tetikleyen ekranı gösterir.
Migration için Setup:MigrationPassword yapılandırması veya App.Setup.Migrate yetkisi gerekir.

Alternatif olarak migration + seed'i doğrudan çalıştırabilirsiniz:

dotnet run --project api/src/Sozsoft.Platform.DbMigrator

DbMigrator; şema migration'larını uygular ve ardından menü, route, permission, dil, host ayarları, ülke/şehir/ilçe verileri ile seed edilmiş ListForm ekranlarını yükler (api/src/Sozsoft.Platform.DbMigrator/Seeds/).

5.4. Frontend

cd ui
npm install
npm start          # vite dev server (http://localhost:3000)

Visual Designer ve Custom Component altyapısının kullandığı bileşen kataloğu src/components/visualDesigner/generated/componentProps.json dosyasında tutulur ve repoya dahildir. src/components/ui altındaki bileşen prop'ları değiştiğinde bu dosya elle güncellenmelidir.

5.5. İlk giriş

Seed edilen host yöneticisi ile /login üzerinden giriş yapılır (kullanıcı bilgileri PlatformIdentityDataSeeder ve HostData.json ile belirlenir; ortam bazlı değerler HostData.Dev.json / HostData.Production.json dosyalarındadır). Giriş sonrası /admin/dashboard açılır.

6. Yapılandırma (Configuration)

6.1. Backend (`appsettings.json`)

Anahtar	Açıklama
`App:SelfUrl`	API'nin kendi adresi (OpenIddict authority ile uyumlu olmalı).
`App:ClientUrl`	React uygulamasının kök adresi (mail linkleri bu adresi kullanır).
`App:CorsOrigins`	Virgülle ayrılmış izinli origin listesi; wildcard subdomain destekli.
`App:RedirectAllowedUrls`	OAuth yönlendirme için izinli adresler.
`App:CdnUrl` / `App:CdnPath`	Dosya servisinin adresi ve BLOB kök dizini.
`App:AttachmentsPath`	Mail kuyruğu eklerinin yazıldığı dizin.
`App:BackupPath`	Veritabanı yedek dizini (BackupWorker kullanır).
`App:Version`	Uygulama sürümü (UI sürüm kontrolü ile eşleşir).
`ConnectionStrings:SqlServer` / `PostgreSql`	Host veritabanı bağlantıları.
`Redis:IsEnabled` / `Redis:Configuration`	Dağıtık cache ve SignalR backplane.
`AuthServer:Authority` / `SwaggerClientId`	OpenIddict authority ve Swagger istemcisi.
`OpenIddict:TokenLifetimes:*`	Access/refresh token ömrü (dakika).
`Setup:MigrationPassword`	Setup ekranından migration tetiklemek için parola.
`StringEncryption:DefaultPassPhrase`	ABP string şifreleme anahtarı.
`Serilog:MinimumLevel`	Log seviyeleri.

Güvenlik: Depodaki appsettings.json dosyaları geliştirme değerleri içerir. Üretimde bağlantı dizeleri, MigrationPassword, DefaultPassPhrase ve entegrasyon anahtarları ortam değişkeni veya secret yöneticisi ile verilmelidir; repoya yazılmamalıdır.

6.2. Frontend (`ui/.env`, `.env.dev`, `.env.production`)

Değişken	Açıklama
`VITE_API_URL`	API kök adresi.
`VITE_CDN_URL`	Dosya/CDN kök adresi.
`VITE_REACT_APP_VERSION`	`package.json` sürümünden beslenir.
`VITE_AI_URL`	AI asistanının n8n webhook kökü.
`VITE_USE_POLLING`	Dosya izlemede polling (WSL/Docker senaryoları).
`VITE_PWA_DEV`	Geliştirmede service worker'ı açar (varsayılan kapalı).

6.3. Uygulama içi ayarlar

Çalışma zamanı ayarları veritabanında tutulur ve Ayarlar ekranından (/admin/settings) yönetilir. Sozsoft.Settings modülü ayar tanımlarını, SettingUiAppService ise bu tanımların UI gösterimini yönetir. Şifre politikası, oturum kuralları, gönderici kimlik bilgileri (SMS, mail, WhatsApp, Rocket) ve AI bot yapılandırması bu yolla değiştirilir — kod dağıtımı gerekmez.

7. Low-Code Motoru: ListForm Ekosistemi

Platformun kalbi budur. Bir iş ekranı; bir ListForm kaydı, ona bağlı ListFormField kayıtları ve bir menü/route/permission üçlüsünden oluşur.

7.1. Kavramlar

Varlık	Rolü
`DataSource`	Hedef veritabanı bağlantısı (MSSQL / PostgreSQL). Ekranlar `DataSourceCode` ile bağlanır.
`ListForm`	Ekranın tüm davranışı: veri kaynağı, sütun/filtre/sayfalama/düzenleme ayarları, yetkiler, alt formlar, iş akışı, grafik ayarları.
`ListFormField`	Tek bir sütun/alanın davranışı: başlık, tip, genişlik, editör, lookup, doğrulama, biçim, yetki.
`ListFormCustomization`	Kullanıcı bazlı kişiselleştirme: kayıtlı filtre, grid state, sunucu tarafı join/where.
`ListFormWorkflow`	Onay ve koşul düğümlerinden oluşan iş akışı grafiği.
`ListFormImport` / `ImportLog`	Excel/CSV içe aktarma tanımı ve satır bazlı sonuç günlüğü.

7.2. `ListForm` anatomisi

Ekran davranışı büyük ölçüde JSON kolonlarında saklanır. Öne çıkanlar:

Alan	İşlevi
`SelectCommandType` + `SelectCommand`	Veri kaynağı türü: `Table`, `View`, `TableValuedFunction`, `Query`, `StoredProcedure`.
`KeyFieldName` / `KeyFieldDbSourceType`	Birincil anahtar alanı ve tipi.
`PermissionJson`	Ekranın create/read/update/delete/export/import/note yetki eşlemesi.
`EditingOptionJson` / `EditingFormJson`	Düzenleme modu (row/cell/batch/form/popup) ve düzenleme formu düzeni.
`FilterRowJson`, `HeaderFilterJson`, `FilterPanelJson`, `SearchPanelJson`, `GroupPanelJson`	Filtreleme, arama ve gruplama davranışı.
`ColumnOptionJson`, `PagerOptionJson`, `SelectionJson`, `StateStoringJson`	Sütun, sayfalama, seçim ve durum saklama ayarları.
`Insert/Update/DeleteCommand` (+ `Before` / `After`)	CRUD komutları ve öncesi/sonrası çalışacak SQL kancaları.
`Insert/Update/DeleteServiceAddress`	Varsayılan olarak `list-form-data/*`; özel endpoint'e yönlendirilebilir.
`SubFormsJson`	Ana-detay ilişkisi (ParentFieldName → ChildFieldName eşlemesi).
`WidgetsJson`	Ekranın üstünde gösterilecek KPI kartları.
`WorkflowJson`	İş akışı bağlaması.
`ExtraFilterJson`	Ekrana özel ek filtre araç çubuğu.
`PivotOptionJson`, `TreeOptionJson`, `GanttOptionJson`, `SchedulerOptionJson`, `TodoOptionJson`	Alternatif görünümlerin ayarları.
Grafik alanları (`SeriesJson`, `LegendJson`, `ArgumentAxisJson`, `ValueAxisJson`, `TooltipJson`, `ZoomAndPanJson`, …)	DevExtreme Chart yapılandırması.
`CustomJsSourcesJson` / `CustomStyleSourcesJson`	Ekran yüklendiğinde çalışacak JS/CSS.
`IsTenant`, `IsBranch`, `IsOrganizationUnit`	Otomatik tenant/şube/organizasyon birimi filtrelemesi.
`UserId`, `RoleId`, `CultureName`	Aynı ekranın kullanıcı, rol veya dil bazlı varyantları.

7.3. Görünüm tipleri

Aynı ListForm tanımı, aynı veri hattı üzerinden birden fazla görünümle sunulabilir:

Grid · Pivot · Tree · Chart · Gantt · Scheduler · CardView · TodoBoard · Widget Group

Kullanıcı görünümler arasında geçiş yapabilir; grid durumu (sütun sırası, genişlik, filtre, gruplama) kullanıcı bazlı saklanır ve sıfırlanabilir.

7.4. Alan (field) davranışı

Editör tipleri: dxTextBox, dxTextArea, dxNumberBox, dxDateBox, dxDateRangeBox, dxCalendar, dxCheckBox, dxSwitch, dxRadioGroup, dxSelectBox, dxTagBox, dxLookup, dxDropDownBox, dxGridBox, dxAutocomplete, dxColorBox, dxHtmlEditor, dxSlider, dxRangeSlider — ayrıca görsel yükleme/görüntüleme editörleri.
Lookup kaynakları: StaticData, Query, WebService; ebeveyn–çocuk (cascade) desteklidir.
Doğrulama: ValidationRuleJson ile required/range/pattern/custom kuralları.
Editör script: EditorScript alanı ile alan değişiminde çalışan JS (örn. tarih farkından gün hesaplama, miktar × birim fiyat toplamı). Çalıştırma utils/editorScriptRuntime.ts üzerinden yapılır.
Koşullu biçimlendirme: ColumnStylingJson, ColumnCssClass/ColumnCssValue.
Alan bazlı yetki: PermissionJson ile sütun düzeyinde okuma/yazma/dışa aktarma kontrolü.

7.5. İş akışı ve onay

FormTabWorkflow ve views/admin/listForm/workflow/WorkflowDesigner.tsx üzerinden görsel tasarlanır. Düğüm türleri koşul karşılaştırması (CompareColumn/CompareOperator/CompareValue) ve onay adımlarıdır; her adım için NextOnTrue, NextOnFalse, NextOnApprove, NextOnReject geçişleri tanımlanır. Onaycı birden fazla kişi olabilir. Formlar içinde iş akışına bağlı özel butonlar gösterilebilir.

7.6. Yeni ekran ekleme akışı (Wizard)

/admin/listform/wizard altındaki 11 adımlı sihirbaz, aşağıdaki yedi artefaktı tek akışta üretir:

ListForm kaydı (kod, ad, başlık, veri kaynağı, select komutu, anahtar alan)
ListFormField kümesi (sütunlar, editörler, lookup'lar, doğrulamalar)
Route kaydı (key, path, componentPath, routeType, authority)
Menu kaydı (ParentCode, Code, DisplayName, Url, Icon, RequiredPermissionName, Order)
Permission kayıtları (.Default, .Create, .Update, .Delete, .Export, .Import, .Note)
Gerekiyorsa ayar/entegrasyon bağımlılıkları
Doğrulama ve geri alma notları

Dinamik liste ekranlarının route deseni /admin/list/{ListFormCode} biçimindedir; form görünümleri /admin/form/{listFormCode}/:id, grafik /admin/chart/{listFormCode}, pivot /admin/pivot/{listFormCode} yollarını kullanır.

Var olan bir ekranı düzenlemek için /admin/listform/edit/{listFormCode} — tüm JSON yapılandırması sekmeli bir editörde yönetilir (Veritabanı, Sütunlar, Filtreler, Düzenleme, Yetkiler, Alt Form, Pivot, Tree, Gantt, Scheduler, Todo, Widget, Workflow, Durum, Grafik sekmeleri).

7.7. İçe/dışa aktarma

Dışa aktarma: xlsx, csv, pdf (grid durumuna ve görünür sütunlara saygı duyar).
İçe aktarma: components/importManager altındaki dosya yükleme → önizleme → ilerleme → sonuç akışı; sonuçlar ListFormImportLog üzerinde satır bazında raporlanır. Şablon dosyası ekran tanımından üretilir.

8. Developer Kit

Teknik kullanıcılar için /admin/developerkit altında toplanan araçlar:

Araç	Route	Ne işe yarar
SQL Query Manager	`/admin/sql-manager`	Nesne gezgini, Monaco tabanlı SQL editörü, sonuç grid'i, nesne özellikleri ve tablo tasarımcısı.
Custom Endpoint	`/admin/developerkit/endpoints`	SQL veya servis tanımından REST endpoint üretimi; GET/POST/PUT/DELETE için ayrı yetki kapıları (`App.DeveloperKit.CustomEndpoints.*`) ve kullanıcı/rol/global erişim kuralları.
CRUD Endpoint	`/admin/developerkit/entities`	Tablo tanımından tam CRUD endpoint kümesi üretimi.
Dynamic Service	`/admin/developerkit/dynamic-services`	C# kodunu tarayıcıda yazıp Roslyn ile derleme (`TestCompile`), yayınlama (`Publish`) ve çalışan uygulamaya controller olarak kaydetme. Yetkiler: Create/Edit/Delete/Manage/TestCompile/Publish/ViewCode.
Custom Component	`/admin/developerkit/components`	React bileşenini veritabanında saklama; `@babel/standalone` ile tarayıcıda derleyip route'a bağlama.
Visual Designer	Component editörü içinde	Sürükle-bırak kanvas ile bileşen üretimi ve kod üretimi (`visualDesigner/codeGenerator.ts`).

Tablo tasarımı varsayılanı: Yeni tablo oluştururken tenant ve tam denetim (audit) kolonları varsayılan olarak eklenir: Id, TenantId, CreationTime, CreatorId, LastModificationTime, LastModifierId, IsDeleted, DeletionTime, DeleterId. Kullanıcı açıkça istemedikçe bu kolonlar çıkarılmaz.

Dinamik servis yaşam döngüsü: DynamicServiceCompiler kodu derler → DynamicAssemblyRegistrationService assembly'yi tenant bağlamıyla kaydeder → ActionDescriptorChangeProvider MVC'ye route tablosunun değiştiğini bildirir → DynamicControllerActivator bağımlılıkları enjekte eder. Uygulama yeniden başlatılmaz.

9. Dinamik Menü, Route ve Yetki Modeli

Permission (ABP)  ──┐
                    ├──►  Menu.RequiredPermissionName  ──►  menüde görünürlük
Route.Authority   ──┘                                   └►  PermissionGuard ile erişim

Route (Entities/Tenant/Administration/Route.cs): Key, Path, ComponentType, ComponentPath, RouteType (public / protected), Authority[].
Menu (Menu.cs): Code, ParentCode, DisplayName, Url, Icon, Order, RequiredPermissionName, Target, IsDisabled, ayrıca UserId / RoleId / CultureName ile kullanıcı, rol ve dil bazlı menü varyantları.
Menü yöneticisi (/admin/menuManager): sürükle-bırak ağaç ile menü düzenleme.
Frontend'de dynamicRoutesContext route'ları çeker, dynamicRouteLoader bunları fiziksel view'lara veya runtime derlenmiş Custom Component'lere eşler, DynamicRouter React Router ağacını kurar; her korumalı route ProtectedRoute + PermissionGuard ile sarılır.

Yetki kodları PlatformConsts.AppCodes içinde merkezî olarak tanımlıdır ve PermissionsData.json ile seed edilir. Ana gruplar: App.Saas, App.Branches, App.Intranet.*, App.Definitions.*, App.Restrictions.*, App.Languages.*, App.Listforms.*, App.Notifications.*, App.BackgroundWorkers.*, App.Menus.*, App.DeveloperKit.*, App.Orders.*, App.BlogManagement.*, App.IdentityManagement.*, App.Reports.*, App.Administration, App.Setting, App.Setup.Migrate.

Kural: Yetki sözleşmesi olmayan menü/route önerilmez ve eklenmez.

10. Modül Kataloğu

10.1. Backend modülleri (`api/modules`)

Modül	Kapsam
Sozsoft.Languages	Dil tanımları, dil anahtarları, çeviri metinleri; tenant bazlı lokalizasyon (`TenantLocalizationMiddleware`).
Sozsoft.Settings	Ayar tanımları, sağlayıcılar, şifreleme bayrakları ve ayar ekranı metadata'sı.
Sozsoft.Notifications	Bildirim tipleri, kuralları ve kullanıcı bildirimleri; kanal bazlı yönlendirme.
Sozsoft.MailQueue	Şablon (Scriban) tabanlı gövde üretimi, ek dosya yaşam döngüsü, kuyruk çalıştırma ve günlükleme.
Sozsoft.Sender	Amazon SES (mail), Posta Güvercini (SMS), WhatsApp Cloud API, Rocket.Chat göndericileri.
Sozsoft.SqlQueryManager	SQL nesne yönetimi, sorgu çalıştırma, tablo/kolon metadata'sı.

10.2. Uygulama servisleri (`api/src/Sozsoft.Platform.Application`)

AiBots · AuditLogs · BackgroundWorker · Blog · Branch · Dashboard · DataSource · DeveloperKit · FileManagement · Forum · GlobalSearch · Hr · Identity · Intranet · ListForms (+ Administration) · Menu · Messenger · Note · OrgChart · OrganizationUnits · Public · Routes · Tenants · Videoroom

10.3. Yönetim ekranları (UI)

Alan	Route	Açıklama
Dashboard	`/admin/dashboard`	Widget tabanlı özet ekran.
Kullanıcı / Rol	`/admin/list/...`, `/admin/users/detail/:userId`	Kullanıcı, rol ve permission atamaları.
Organizasyon birimleri	`/admin/ous`	OU ağacı ve üyelik yönetimi.
Tenant yönetimi	ListForm ekranları	Tenant kayıtları, bağlantı dizeleri, siparişten otomatik tenant açma.
Ayarlar	`/admin/settings`	Sistem ve entegrasyon ayarları.
Menü yöneticisi	`/admin/menuManager`	Menü ağacı düzenleme.
Dosya yöneticisi	`/admin/files`	Klasör/dosya işlemleri.
Aktivite ve denetim kaydı	`/admin/activityLog`, `/admin/changeLog`	Kullanıcı hareketleri ve ABP audit log detayı.
Bildirimler	`/admin/profile/notification-settings`, bildirim ekranları	Kanal tercihleri ve bildirim oluşturma.
Forum	`/admin/forum`, `/admin/forumManagement`	Forum kullanımı ve yönetimi.
Intranet	Intranet dashboard ve widget'ları	Duyuru, anket, sosyal duvar, etkinlik.
Video oda	`/admin/videoroom/*`	Oda listesi, detay, planlama, katılımcı ve ekran paylaşımı.
Raporlar	`/admin/reports/:report/view	design/...`
AI asistanı	`/admin/ai`	n8n webhook üzerinden sohbet arayüzü.
Profil	`/admin/profile/*`	Genel bilgiler, şifre, bildirim ayarları.

10.4. Public site

/home · /about · /services · /products · /checkout · /payment · /success · /blog · /blog/:id · /demo · /contact — içerikler veritabanından yönetilir; /about/designer ve /services/designer sayfa tasarımcılarıdır.

11. Kimlik, Oturum ve Güvenlik

11.1. Kimlik doğrulama

OpenIddict password + refresh token akışı. Token uç noktası: POST /connect/token (grant_type=password, client_id=Platform_PublicApi, scope=offline_access Platform).
Token ömürleri OpenIddict:TokenLifetimes ile yapılandırılır (varsayılan 60 dk access, 90 dk refresh).
Swagger için ayrı istemci: AuthServer:SwaggerClientId.
İki aşamalı doğrulama (2FA) ve hesap doğrulama (e-posta/telefon) desteklenir.
Kayıt ve iletişim formlarında Cloudflare Turnstile tabanlı captcha (CaptchaMiddleware).

11.2. Oturum yönetimi

PlatformSessionValidationMiddleware her istekte oturumun hâlâ geçerli olduğunu doğrular.
PlatformSessionRevocationHandler token iptalinde oturumu sonlandırır.
PlatformSessionCleanupWorker süresi dolmuş oturumları temizler.
Eş zamanlı kullanıcı limiti aşıldığında giriş reddedilir.

11.3. Giriş engelleri

UserCannotSignInErrors altında tanımlı, kullanıcıya lokalize mesajla dönen durumlar:

Kod	Anlamı
`LoginNotAllowed_NotVerified`	Hesap doğrulanmamış.
`LoginNotAllowed_NotAllowedIp`	IP kısıtlaması (`IpRestriction`).
`LoginNotAllowed_WorkHour`	Çalışma saati kısıtlaması (`WorkHour`).
`LoginNotAllowed_LoginEndDateDue`	Kullanıcının giriş yetki süresi dolmuş.
`ShouldChangePasswordOnNextLogin` / `ShouldChangePasswordPeriodic`	Zorunlu şifre değişimi.
`LoginNotAllowed_TenantIsPassive` / `TenantNotFound`	Tenant pasif veya bulunamadı.
`LoginNotAllowed_BranchLimit`	Şube lisans limiti aşıldı.
`LoginNotAllowed_ConcurrentUserLimit`	Eş zamanlı kullanıcı limiti aşıldı.

11.4. Güvenlik kuralları

Tüm katmanlarda RBAC ve yetki tabanlı görünürlük zorunludur.
Dinamik SQL'de yalnızca parametreli desenler kullanılır; kullanıcı girdisi string birleştirme ile sorguya eklenmez.
Her sorgu ve eylemde tenant izolasyonu korunur (IsTenant, IsBranch, IsOrganizationUnit bayrakları ve ABP tenant filtreleri).
Gerçek kimlik bilgileri, token ve anahtarlar örneklerde/dokümanda yer almaz; yer tutucu kullanılır.
Denetim: kritik işlemler ABP Audit Log'a yazılır; yüksek frekanslı list-form-customization çağrıları denetim dışı bırakılmıştır.

12. Çok Kiracılılık (Multi-Tenancy)

PlatformConsts.IsMultiTenant = true.
Tenant çözümleme host adı (subdomain) ve ABP tenant resolver'ları ile yapılır (utils/subdomain.ts).
Tenant başına ayrı veritabanı: TenantConnectionString kayıtları ile her tenant kendi veritabanına yönlendirilebilir; migration'lar DatabaseMigrationEventHandlerBase üzerinden tenant oluşturulduğunda otomatik uygulanır.
Şube (Branch): Tenant altındaki fiziksel/örgütsel kırılım; kullanıcı–şube eşlemesi BranchUsers ile tutulur, lisans limiti girişte kontrol edilir.
Organizasyon birimi: ABP OrganizationUnit ağacı; ListForm'lar OU bazlı filtrelenebilir.
Tenant bazlı lokalizasyon: TenantLocalizationInitializer + TenantLocalizationMiddleware.

13. Bildirim ve Entegrasyonlar

13.1. Kanallar

Sms · Mail · Rocket · Desktop · UiActivity · UiToast · WhatsApp (Telegram altyapıda tanımlı, UI'da kapalı)

13.2. Yönlendirme modeli

Bildirim tip + kanal eşleşmesiyle yönlendirilir. Alıcı hedefleme seçenekleri: All, User, Role, OrganizationUnit, Custom. Kullanıcılar kendi bildirim tercihlerini /admin/profile/notification-settings üzerinden kanal bazında yönetir.

13.3. Göndericiler (`Sozsoft.Sender`)

Kanal	Sağlayıcı
E-posta	ABP Emailing + Amazon SES (`AmazonSesEmailSender`), arka plan iş kuyruğu ile
SMS	Posta Güvercini HTTP API
WhatsApp	WhatsApp Cloud API (şablon tabanlı)
Rocket.Chat	Rocket.Chat HTTP API

Tüm sağlayıcı kimlik bilgileri ayar ekranından yönetilir (App.Settings.* anahtarları); koda gömülmez.

13.4. Mail kuyruğu

Sozsoft.MailQueue; şablondan gövde üretir, PDF/XLS/TXT çıktıları ve ek dosyaları yönetir, kuyruğu arka plan işçisiyle çalıştırır ve sonuçları günlükler.

13.5. AI entegrasyonu

AiBot kayıtları tenant bazlıdır; n8n webhook üzerinden LangChain ajanı + bellek penceresi ve Gemini sohbet modeli bağlanır (configs/ai/Chat.json). UI tarafında /admin/ai ve header'daki asistan bileşeni bu uç noktayı kullanır.

14. Arka Plan İşleri

İki motor birlikte kullanılır: Hangfire (kalıcı iş deposu, default ve platform kuyrukları) ve ABP Background Workers (yinelenen işler). Yönetim /admin altındaki Background Worker ekranlarından yapılır; yetkiler App.BackgroundWorkers.RecurringJobs ve .Jobs.

Worker tipi	İşlevi
`MailQueueWorker`	Mail kuyruğunu işler.
`SqlWorker`	Zamanlanmış SQL çalıştırır.
`NotificationWorker`	Bildirim kurallarını değerlendirir ve gönderir.
`SessionCleanupWorker`	Süresi dolmuş oturumları temizler.
`BackupWorker`	Veritabanı yedeği alır ve eski yedekleri temizler.

Hangfire panosu geliştirmede serbest, üretimde AbpHangfireAuthorizationFilter ile korumalıdır (/hangfire).

15. Raporlama

DevExpress Reporting: Web Document Viewer (/admin/reports/:report/view/...) ve Report Designer (/admin/reports/:report/design/...).
Rapor deposu: ReportTemplate ve ReportCategory varlıkları; CustomReportStorageWebExtension ile veritabanı üzerinden okuma/yazma.
Dinamik raporlar (HttpApi.Host/PredefinedReports): ListForm tanımından otomatik üretilen grid, form ve ağaç raporları — grid durumunu (sütun sırası, gruplama, filtre) rapora yansıtır.
Linux konteynerlerde font sorunlarını önlemek için DevExpressFontConfiguration devrededir.

16. Dosya Yönetimi ve CDN

ABP BlobStoring, dosya sistemi sağlayıcısıyla App:CdnPath altına yazar; dosyalar App:CdnUrl üzerinden servis edilir.
FileManagementAppService: listeleme, yükleme, indirme, kopyalama, taşıma, yeniden adlandırma, silme.
UI: /admin/files (views/admin/files/FileManager.tsx) — breadcrumb, çoklu yükleme, önizleme.
Avatar, aktivite görselleri, içe aktarma dosyaları ve veritabanı yedekleri ayrı konteynerlerde tutulur.

17. Gerçek Zamanlı Özellikler

Messenger: SignalR hub'ı /messengerhub. Konuşma ve mesaj varlıkları veritabanında; Redis etkinse backplane olarak kullanılır. Query string ile gelen access_token, hub bağlantısı için Authorization başlığına çevrilir.
Video oda: Oda oluşturma/başlatma/bitirme, katılımcı yönetimi, sohbet, doküman ve ekran paylaşımı panelleri; TURN sunucusu configs/deployment/configs/turnserver.conf ile yapılandırılır.
Global arama: GlobalSearchAppService üzerinden çapraz modül arama.

18. Frontend Mimarisi

18.1. Route ve bileşen çözümü

Route kayıtları (DB)
   ├─ componentPath ──► fiziksel view (React.lazy)
   └─ CustomComponent ──► @babel/standalone ile runtime derleme ──► ComponentContext
                                     │
                              DynamicRouter ──► ProtectedRoute ──► PermissionGuard ──► PageContainer

ROUTES_ENUM (src/routes/route.constant.ts) statik yol sözleşmelerini tutar; iş modülleri için (supplychain, maintenance, warehouse, projects, hr, crm, mrp, accounting) ayrılmış yol desenleri de buradadır. Bu alanların ekranları, fiziksel React sayfaları yerine ListForm konfigürasyonu ile üretilir.

18.2. Durum yönetimi

easy-peasy global store: auth, theme, locale, abpConfig, admin, client, base. Oturum ve tercih verileri localStorage yerine store üzerinden yönetilir (stateSync.ts).
React Query: sunucu verisi önbellekleme.
Context'ler: ComponentContext (runtime bileşen kaydı), DialogContext, ScrollContext.

18.3. Tema ve lokalizasyon

Tailwind tabanlı tasarım sistemi (components/ui) + DevExtreme temaları; açık/koyu mod ve tema yapılandırıcı (ThemeConfigurator).
Dil metinleri veritabanından gelir (Sozsoft.Languages); dil seçici header'dadır. Tenant bazlı çeviri geçersiz kılma desteklenir.
Layout seçenekleri: dikey menü, yatay menü, yığılmış yan menü, mobil navigasyon.

18.4. PWA ve sürüm yönetimi

Precache yalnızca uygulama kabuğunu kapsar (index.html + entry JS/CSS ≈ 2.8 MB); DevExtreme temaları, lazy chunk'lar, font ve görseller runtime cache ile saklanır. Sebebi: dist klasörü ~55 MB olduğundan tam precache, yavaş bağlantılarda service worker kurulumunun timeout'a düşmesine yol açıyordu.
registerType: 'prompt' — yeni sürüm indirilir, kullanıcı onayıyla devreye alınır (views/version/swRegistration.ts, useAppVersionNotice.tsx).
version.json her zaman ağdan tazelenir (NetworkFirst); changelog /admin/changeLog ekranında gösterilir.
scripts/generate-version.js build sırasında sürüm bilgisini üretir.

19. API ve Swagger

Swagger UI, API kökünde yayınlanır; OAuth2 ile "Authorize" düğmesi üzerinden token alınabilir.
Endpoint'ler ABP conventional controller mekanizmasıyla uygulama servislerinden üretilir:

Namespace	Kök yol
`Sozsoft.Platform.ListForms.Administration`	`/api/admin/...`
Diğer `Sozsoft.Platform.*` servisleri	`/api/app/...`
Modül servisleri (Languages, Settings, MailQueue, Notifications, SqlQueryManager)	Modül kendi kök yolunu kullanır

DevExpress raporlama controller'ları (CustomReportDesigner, CustomWebDocumentViewer, QueryBuilder) Swagger dokümanından hariç tutulur.
Yanıtlar Brotli/Gzip ile sıkıştırılır; X-Correlation-Id başlığı istemciye açılır.
Hata kodları: PlatformConsts.AppErrorCodes (Error:0001 yetkisiz, App.NoResults kayıt yok, Error:0003 parametre geçersiz, Error:0005 iç hata).

Token örneği (yer tutucularla):

POST /connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=password
&username=<KULLANICI>
&password=<PAROLA>
&client_id=Platform_PublicApi
&scope=offline_access%20Platform

20. Dağıtım (Deployment)

configs/deployment altında üç ortam için compose dosyaları ve numaralandırılmış scriptler bulunur.

Dosya	Amaç
`docker-compose-data.yml`	Redis, SQL Server / PostgreSQL, yedek volume'ları
`docker-compose-app.yml` / `.dev.yml` / `.production.yml`	API, UI, migrator, nginx
`docker-compose-devops.yml`	Forgejo + runner (CI/CD)
`Dockerfile`, `api/*.Dockerfile`, `ui/Sozsoft.Platform.Ui.Dockerfile`	İmaj tanımları
`configs/nginx.conf`, `redis.conf`, `turnserver.conf`, `elasticsearch.yml`	Servis yapılandırmaları

Script sırası (configs/deployment/scripts):

1-devops.sh              → DevOps makinesi (Forgejo, runner)
2-data-postgres.sh /
3-data-sql.sh            → Veri katmanı
4-production-build.sh    → İmaj build
5-production-deploy.sh   → Yayın
6-production-migrator-true.sh → Migration çalıştırma
7-setup_ssl.sh           → Sertifika
8-dev-build.sh / 9-dev-deploy.sh / 10-dev-migrator-true.sh → Dev ortamı

Ayrıntılı kurulum notları: configs/deployment/README.md, Readme_Production.md, Readme_Devops.md.

Bu dokümanlarda geçmişte örnek amaçlı bırakılmış kimlik bilgileri bulunabilir; üretimde tümü döndürülmeli ve secret yöneticisine taşınmalıdır.

21. Geliştirme Standartları ve Sık Kullanılan Komutlar

21.1. Çözüm kuralları

Her istek şu sırayla değerlendirilir: (1) ListForm konfigürasyonu → (2) SQL Query Manager + Custom Endpoint → (3) Dynamic Service → (4) kod değişikliği (son çare, gerekçe zorunlu).
Standart iş ihtiyaçları için yeni özel React sayfası/bileşeni geliştirilmez.
Her öneri tenant ve yetki tasarımını içerir.
Platform yetkilendirme desenleri atlanmaz.
Secret, tenant id veya bağlantı dizesi koda gömülmez.

21.2. Frontend

cd ui
npm start          # geliştirme sunucusu
npm run build      # üretim derlemesi (metadata + version + vite build)
npm run lint       # ESLint
npm run format     # prettier --write + eslint --fix

21.3. Backend

cd api
dotnet build
dotnet run --project src/Sozsoft.Platform.HttpApi.Host
dotnet format --include .\modules\Sozsoft.Notifications\ --folder

# Migration (EntityFrameworkCore projesi içinde)
dotnet ef migrations add <Ad>
dotnet ef database update
dotnet ef migrations remove

Yeni ABP modülü eklemek için: abp new Sozsoft.<Modul> -t module --no-ui -m none --database-provider ef

21.4. Seed dosyaları

Yeni bir modülün nasıl kurulacağını öğrenmek için başvurulacak dosyalar:

api/src/Sozsoft.Platform.DbMigrator/Seeds/ListFormSeeder_Saas.cs
.../Migrations/ListFormSeeder_Administration.cs
.../Migrations/MenusData.json
.../Migrations/PermissionsData.json
.../Migrations/HostData.json
.../Migrations/LanguagesData.json

22. Sorun Giderme

Belirti	Olası neden ve çözüm
`/api/abp/application-configuration` 503 dönüyor	Veritabanına erişilemiyor. Bağlantı dizesini ve veri konteynerini kontrol edin; `/api/setup/application-status` ile durumu görün.
UI `/setup` ekranına düşüyor	Şema oluşmamış veya bekleyen migration var. Setup ekranından migration'ı tetikleyin ya da DbMigrator'ı çalıştırın.
Giriş "UserCannotSignIn..." hatası veriyor	11.3 tablosuna bakın: IP, çalışma saati, doğrulama, şube/eş zamanlı kullanıcı limiti.
Yeni sürüm tarayıcıda görünmüyor	Service worker `prompt` modundadır; güncelleme bildirimini onaylayın veya sekmeyi tamamen kapatıp açın.
DevExtreme teması yüklenmiyor	`public/css` altındaki tema dosyaları runtime cache'tedir (StaleWhileRevalidate); hard refresh yeterlidir.
Hangfire başlangıçta hata veriyor	Bağlantı dizesi boşsa Hangfire kaydı atlanır ama ABP modülleri yüklenir. Bağlantı dizesini doğrulayın.
Dinamik servis yayınlanmıyor	Önce `TestCompile` çalıştırın; derleme hatası mesajı UI'da döner. `Publish` için ilgili yetki gerekir.
Raporlarda font/karakter bozukluğu (Linux)	`DevExpressFontConfiguration.InstallLinuxFonts` loglarını kontrol edin; konteynerde font paketi eksik olabilir.

23. Bilinen Sınırlar ve Notlar

route.constant.ts içindeki supplychain, maintenance, warehouse, projects, crm, mrp, accounting ve hr yol sabitleri yol sözleşmesidir; bu alanların ekranları fiziksel React sayfaları olarak değil, ListForm konfigürasyonu ile üretilir. hr altında yalnızca organizasyon şeması (OrgChart.tsx) fiziksel bir view'dır.
Telegram bildirim kanalı altyapıda tanımlıdır ancak UI'da kapalıdır.
Depodaki appsettings*.json ve deployment dokümanları geliştirme değerleri/örnek kimlik bilgileri içerir; üretim öncesi tümü değiştirilmelidir.
.github/instructions/ai.instructions.md içinde stack ".NET 9 + ABP 9" olarak yazılıdır; kod tabanı .NET 10 + ABP 10 üzerindedir. Kural bölümleri geçerliliğini korur.
Rol–yetki eşleşmeleri veritabanında müşteri ortamına göre değişir; buradaki yetki kodları tanımın kendisidir, atama değil.

Lisans ve Sahiplik

Bu depo Sozsoft'a aittir. DevExpress/DevExtreme bileşenleri ticari lisans gerektirir (api/DevExpress_License.txt).

45 KiB Raw Blame History Unescape Escape