226 lines
14 KiB
Markdown
226 lines
14 KiB
Markdown
# Sozsoft Platform - Claude Instructions
|
||
|
||
This file provides Claude-specific operating rules for this repository.
|
||
Primary source of truth for platform behavior is:
|
||
|
||
- `.github/instructions/ai.instructions.md`
|
||
|
||
If there is any conflict, follow `.github/instructions/ai.instructions.md`.
|
||
|
||
## Communication Rules (apply to every response)
|
||
|
||
1. **Never introduce or summarize the platform.** Assume the user knows what this
|
||
application is, how it is built, and which technologies it uses. Do not open a response
|
||
with "Sozsoft Platform is a multi-tenant low-code engine…" or any equivalent framing.
|
||
2. **Answer the request, nothing more.** No unsolicited architecture overviews, no
|
||
restating the decision order, no re-explaining ListForm/DeveloperKit concepts unless
|
||
the user actually asked about them.
|
||
3. **No preamble, no epilogue.** Skip "Great question", "I reviewed the codebase",
|
||
summaries of what you are about to do, and closing recaps of what you just did.
|
||
4. **Match the question's size.** A yes/no question gets a sentence. A config question
|
||
gets the config. Only a full feature request gets a full proposal.
|
||
5. **Respond in the language the user writes in** (Turkish → Turkish).
|
||
6. Mention a rule from this file only when it changes the answer — never as boilerplate.
|
||
|
||
## Purpose
|
||
|
||
- Maximize delivery through runtime configuration.
|
||
- Minimize custom code.
|
||
- Preserve platform consistency, security, and tenant isolation.
|
||
|
||
Primary principle: Configuration first, code last.
|
||
|
||
## Mandatory Decision Order
|
||
|
||
For every request, evaluate in this order — internally. State the chosen step only when the
|
||
user is asking how to build something, and state it in one line, not as a walkthrough of the
|
||
options you rejected.
|
||
|
||
1. Dynamic configuration with existing ListForm ecosystem
|
||
2. SQL Query Manager + Custom Endpoint
|
||
3. Dynamic Service
|
||
4. Code change (last resort, justification required)
|
||
|
||
## Non-Negotiable Rules
|
||
|
||
1. Do not propose new custom React component/page development for standard feature requests.
|
||
2. Build new screens using platform configuration mechanisms.
|
||
3. Every implementation proposal must include tenant and permission design.
|
||
4. Never bypass platform authorization patterns.
|
||
5. Never hardcode secrets, tenant IDs, or connection strings.
|
||
6. Never step outside the framework without explicit approval (standing default 10).
|
||
|
||
Exception:
|
||
|
||
- Custom React/backend code is allowed only when the user explicitly requests implementation
|
||
and configuration is insufficient.
|
||
- In such cases, explain why configuration-first options are not enough — in a sentence or two.
|
||
|
||
## Architecture Guardrails
|
||
|
||
- Backend: Respect ABP module boundaries and explicit, auditable permissions.
|
||
- Frontend: Use existing dynamic view infrastructure and metadata-driven behavior.
|
||
- Data: Use parameterized SQL patterns and enforce tenant-safe access.
|
||
|
||
## Dynamic Platform Expectations
|
||
|
||
- Menus and routes are database-driven.
|
||
- Dynamic List/Form/Component infrastructure is the default solution path.
|
||
- Keep route, menu, permission, and datasource mappings coherent.
|
||
|
||
## Security and Compliance
|
||
|
||
- Enforce RBAC and permission-driven visibility in all layers.
|
||
- Never output real credentials, tokens, keys, or secrets.
|
||
- Use placeholders in examples.
|
||
- Maintain tenant isolation in every query and action.
|
||
|
||
## Response Contract
|
||
|
||
The list below applies **only** to a full implementation proposal for a new screen, module,
|
||
or integration. It is not a template for questions, debugging, code review, refactors,
|
||
explanations, or small changes.
|
||
|
||
Even for a full proposal: include only the items that carry real content for that request,
|
||
and drop the rest. An empty or obvious heading is noise.
|
||
|
||
1. Goal
|
||
2. Decision flow result (which step used)
|
||
3. Artifacts to configure
|
||
4. SQL/query/endpoint design (if needed)
|
||
5. Menu + route + component mapping
|
||
6. Permission and role mapping
|
||
7. Tenant isolation notes
|
||
8. Validation and test checklist
|
||
9. Rollback strategy
|
||
|
||
---
|
||
|
||
## Standing Context (read this before proposing anything)
|
||
|
||
These sections encode expectations the user will **not** repeat in every prompt.
|
||
`README.md` is the technical map of the platform; this file is how to act on it.
|
||
|
||
### Where the truth lives
|
||
|
||
| Konu | Kaynak |
|
||
| --- | --- |
|
||
| Platform davranışı, karar sırası, çıktı sözleşmesi | `.github/instructions/ai.instructions.md` |
|
||
| **Artefakt üretimi**: seed şemaları, enum değerleri, çalışan örnekler | `.github/instructions/lowcode.instructions.md` |
|
||
| **Yetenek envanteri**: JSON kolonlarının alan alan sözleşmesi, grafik/pivot/tasarımcı/mail modülü, Saas + Administration menüsündeki hazır ekranlar | `.github/instructions/lowcode-reference.instructions.md` |
|
||
| `api/` kod standardı (sürüm, nullable, ölü kod, modern C#, ABP katmanları) | `.github/instructions/dotnet.instructions.md` |
|
||
| Modül/liste ekleme prosedürü, seeder dosya sorumlulukları | `.github/instructions/list.instructions.md` |
|
||
| Ne nerede yaşıyor, hangi ekran ne yapıyor | `README.md` |
|
||
| Yetki kodları | `PlatformConsts.AppCodes` (backend) + `constants/permission.constant.ts` (UI) |
|
||
| Seed yolları | `SeedPathResolver` |
|
||
|
||
Bir çelişki varsa sıra: `ai.instructions.md` → `dotnet.instructions.md` → bu dosya → `README.md`.
|
||
|
||
### Standing defaults — do not ask again
|
||
|
||
1. **Yeni tablo** → tenant + tam audit kolonları varsayılan gelir (`Id`, `TenantId`,
|
||
`CreationTime`, `CreatorId`, `LastModificationTime`, `LastModifierId`, `IsDeleted`,
|
||
`DeletionTime`, `DeleterId`). Kullanıcı açıkça "tenant yok / audit yok" demedikçe çıkarma.
|
||
2. **Yeni ekran** → Wizard yolu. `Definitions` altına otomatik yerleştirme yok; modüle ait yeni
|
||
bir kök menü oluştur, `Order = max(Order) + 1`.
|
||
3. **Yeni ekran/menü** → yetki sözleşmesi olmadan önerilmez. Menü ve route aynı ekran
|
||
sözleşmesini göstermeli.
|
||
4. **Kullanıcıya görünen her metin** → dil anahtarı üzerinden, EN + TR birlikte. Koda gömülü
|
||
metin önerme.
|
||
5. **Runtime'da üretilen her artefakt** (wizard, custom component, crud endpoint) → ilgili seed
|
||
dosyası da yazılır/güncellenir. Veritabanı sıfırlandığında geri gelmeyen bir şey üretme.
|
||
6. **Yeni ekran/komponent talebi — yazılı ya da görsel** → dosya yazmadan önce **keşif turu**:
|
||
toplu sorularla (tur başına en fazla 4, seçenekli, önerilen varsayılanlı) ekran türü, veri
|
||
kaynağı, modül, kapsam ve yolun soru setini al; tarifi kur ve **onaylat**, sonra
|
||
`configs/seeds/` altına üret. Şüphede Wizard. Kullanıcı "sorma / sen seç" derse
|
||
varsayılanlarla üret ve sonunda listele. Depodan okunabilen şeyi sorma; tabloya yazma hedefi,
|
||
onaycı ve hesap formülü asla varsayılmaz. Ekran görüntüsü piksel sözleşmesi değildir;
|
||
görsel Tur 2'nin çoğunu cevaplar, yalnızca görselden okunamayanlar sorulur.
|
||
Bu kural yalnızca **yeni üretim** içindir; düzeltme/alan ekleme/debug doğrudan yapılır.
|
||
Ayrıntı: `lowcode.instructions.md` §0.6–§0.7.
|
||
7. **Ekran içi hesap/koşul ihtiyacı** → önce `EditorScript` (Script Builder tarifleri), sonra
|
||
`EditorOptions`; kod yazmak son çare.
|
||
8. **SQL** → her zaman parametreli. String birleştirme ile sorgu kurma.
|
||
9. **Silme** → `DeleteCommand = DefaultDeleteCommand("{Tablo}")`; ham SQL string'i yazma.
|
||
10. **Çerçeve sınırı** → uygulama kendini kendi mekanizmalarıyla geliştirir (seed artefaktları;
|
||
var olan `ui` bileşenine eksik olay/prop/küçük yetenek ekleme — komponentin %70'i hazır
|
||
araçlarla kuruluyorsa kalanı bu eklemelerle tamamlanır, yeni bileşen yazılmaz; geriye dönük
|
||
uyumlu tarif/seçenek/token ekleme).
|
||
Bunun dışına çıkan her şey — yeni React bileşeni/sayfası, çekirdek motor, yeni entity/
|
||
migration, platform tablosu şeması, yeni paket, `Routes`, dış entegrasyon — **önce sorulur,
|
||
yalnızca onayla yapılır**; onay talebe özeldir. Çerçeve içinde yapılabilen kısım sorudan önce
|
||
bitirilir. "Yapılamaz" cevabı yoktur. Listeler: `lowcode.instructions.md` §0.8.
|
||
|
||
### Cross-cutting: touching one thing means touching these too
|
||
|
||
- **`scriptRecipes.ts` (TS) ↔ `Domain.Shared/Editors/*.cs`** — biri değişirse diğeri de değişir.
|
||
İkisinin çıktısı **birebir aynı** olmak zorundadır; aksi hâlde seeder ile basılan script
|
||
dialogda "elle düzenlenmiş" sayılır ve kural editörü kapanır.
|
||
- **Wizard seed dosyasında tekrar yok** → `Wizard` bölümü yalnızca ekrandan üretilemeyen bilgileri
|
||
taşır. `ListForm`/`Fields` içinde karşılığı olan her alan (veri kaynağı, select, anahtar alan,
|
||
kırılım/düzen/düzenleme bayrakları, görünüm option blokları, alt form, widget, iş akışı, alan
|
||
tanımları) dosyaya yazılmadan çıkarılır (`WizardSeedFileDto.ToSeedJson`) ve okurken geri
|
||
doldurulur (`FromSeedJson`). Wizard'a yeni bir alan eklerken karşılığı ListForm'da varsa listeye ekle.
|
||
Dosyada kalan wizard alanları üç başlık altında toplanır — `Menu`, `Language`, `Groups` — ve
|
||
`ListFormCode` → `WizardCode`, `MenuParentModuleId` → `ModuleId` adıyla yazılır; varsayılanı olan
|
||
alanlar (`CreateMenu: true`, boş `DataSourceConnectionString`) hiç yazılmaz. Bu yalnızca dosya biçimidir; C#
|
||
sözleşmesi düzdür, dönüşüm `WizardSeedFileDto.ToSeedJson` / `FromSeedJson` içindedir. **Wizard
|
||
seed dosyası her zaman bu iki metotla okunup yazılır**; düz `JsonSerializer` çağrısı bloklu
|
||
bölümleri sessizce düşürür.
|
||
- **Wizard ile üretilen ekran** → seed dosyası (`configs/seeds/{kapsam}/wizard/{WizardName}.json`)
|
||
wizard cevaplarının yanında ekranın `GridOptionsEditDto` (`ListForm`) ve alanların
|
||
`ColumnFormatEditDto` (`Fields`) sözleşmesini taşır. ListForm detayından yapılan her kayıt
|
||
(`ListFormsAppService`, `ListFormFieldsAppService`, `ListFormJsonRowAppService`) bu bölümleri
|
||
ve `Wizard` bölümündeki karşılıklarını geri yazar (`WizardSeedSynchronizer`). Bu üçlüden birine
|
||
yeni bir kayıt yolu eklenirse senkronizasyon çağrısı da eklenir; yoksa dosya bayatlar.
|
||
- **Wizard girdisinden ekran üretimi** → tek kaynak `ListFormWizardDto.BuildListForm/BuildFields`,
|
||
entity'ye yazma `GridOptionsEditDto.ApplyTo` / `ColumnFormatEditDto.ApplyTo`. Deploy, seeder ve
|
||
senkronizasyon aynı metotları çağırır; ikinci bir üretim kopyası yazma.
|
||
- **Katman sınırı (DDD)** → `DbMigrator` Application'a referans vermez. Seeder ile AppService'in
|
||
paylaştığı dönüşüm `Application.Contracts`'ta DTO metodudur; entity'ye yazma Domain.Shared'deki
|
||
`IListFormArtifact` / `IListFormFieldArtifact` sözleşmeleri üzerinden yapılır.
|
||
Ayrıntı: `dotnet.instructions.md` §5.
|
||
- **Yeni bir yetki** → `PlatformConsts.AppCodes` + `PermissionsData.json` + (UI'da kullanılacaksa)
|
||
`permission.constant.ts` + `LanguagesData.json`.
|
||
- **Yeni bir dil anahtarı** → `LanguagesData.json`; eklemeden önce anahtarın zaten var olup
|
||
olmadığını kontrol et.
|
||
- **Custom component kaydı/silinmesi** → `custom/{Name}.json`; kullandığı endpoint'ler
|
||
`crud/{Entity}.json`.
|
||
- **Wizard dosyası** → tek başına taşınmaz; export zip'i `wizard/`, `custom/`, `crud/` ve
|
||
`{sql|postgres}/{object|execute}/` bağımlılıklarını da içerir.
|
||
- **`ListForm.SeedFilePath` dolu bir ekran** → `SeedSyncInsert/SeedSyncUpdate/SeedSyncDelete`
|
||
bayraklarından işaretli olan işlemler kapsam klasöründeki `data/{ListFormCode}.json` dosyasına
|
||
yansır (`ListFormSeedDataSynchronizer`); migrate/seed sırasında `ListFormSeedDataApplier` dosyayı
|
||
geri uygular (kayıt yoksa ekler, varsa dokunmaz). Yeni bir kayıt yolu (yeni endpoint, toplu işlem)
|
||
eklenirse senkronizasyon çağrısı da eklenir; yoksa dosya bayatlar.
|
||
- **`MenusData.json`** → `Routes` bölümüne dokunma; yalnızca `Modules` ve `Menus`.
|
||
- **Çok değerli alan (`dxTagBox` / çoklu `dxGridBox`)** → tek metin kolonunda `|` ile saklanır.
|
||
Ekran varsayılan `list-form-data/*` ucundan kaydediyorsa birleştirmeyi `QueryHelper` yapar;
|
||
tipli DTO alan bir uca (`list-form-dynamic-api/...`, Custom Endpoint, Dynamic Service)
|
||
bağlıysa DTO alanına `[JsonConverter(typeof(MultiValueStringJsonConverter))]` eklenir —
|
||
yoksa istek `400` ile düşer. Ayrıntı: `lowcode.instructions.md` §4.3.2.1.
|
||
|
||
### Definition of done
|
||
|
||
- Ölü kod bırakma: kullanılmayan `using`, private üye, alan, DTO, hook, servis, tip. Bir tip
|
||
silinmeden önce **repo geneli** (api + ui + configs) referans taraması yapılır; DI ile çözülen
|
||
tipler düz metin aramasında referanssız görünür.
|
||
- Yorum satırına alınmış kod bloğu bırakılmaz.
|
||
- `api/` değişikliğinden sonra: `dotnet build -p:EnforceCodeStyleInBuild=true` — 0 hata, yeni
|
||
`IDE00xx` yok.
|
||
- `ui/` değişikliğinden sonra: `npm run typecheck` ve `npm run lint`.
|
||
- Yorumlar **neden**i anlatır, ne yaptığını değil. Kod zaten ne yaptığını söylüyor.
|
||
- **Dokümantasyon kodla birlikte güncellenir.** Platformun davranışını değiştiren her değişiklik
|
||
(yeni/kaldırılan seeder, seed klasörü ya da dosya biçimi, ListForm sözleşmesine alan ekleme,
|
||
yeni yetki/dil anahtarı, katman sınırı, yeni mekanizma) aynı commit içinde ilgili `.md`
|
||
dosyasına yansıtılır: `README.md` (ne nerede yaşıyor, klasör düzeni, tablolar),
|
||
`.github/instructions/lowcode*.instructions.md` (artefakt/yetenek sözleşmesi),
|
||
`dotnet.instructions.md` (kod standardı, katman kuralı), `CLAUDE.md` (çalışma kuralı).
|
||
Değişiklik hangi md'de karşılığı olduğu bilinmiyorsa önce grep ile eski anlatım aranır ve
|
||
düzeltilir; bayat kalan bir satır bırakma. Doküman güncellemesi "sonraya" bırakılmaz.
|
||
|
||
### Tone
|
||
|
||
- Türkçe soruya Türkçe cevap.
|
||
- Platformu tanıtma, mimariyi özetleme, ne yapacağını anlatıp sonra bir de ne yaptığını özetleme.
|
||
- Cevabın boyutu sorunun boyutu kadar olsun.
|