Katkıda bulunma

Multica, bir Go arka ucu ve pnpm monorepo'sudur. Yerelde başlamanın en basit yolu make dev'dir; bu komut geçerli checkout için ortamı, veritabanını ve migration'ları hazırlar, ardından Web ve API'yi başlatır.

Gereksinimler

• Node.js 22
• pnpm 10.28.2
• Go 1.26.6
• Docker Engine veya Docker Desktop
• Git ve Make

Sürümler için kök package.json, server/go.mod ve CI workflow'larını tek gerçek kaynak olarak kabul edin.

İlk başlatma

git clone https://github.com/multica-ai/multica.git
cd multica
make dev

Birincil checkout .env kullanır. Dosya yoksa, make dev onu .env.example'dan oluşturur, ardından paylaşımlı PostgreSQL örneğini başlatır, bağımlılıkları kurar, migration'ları çalıştırır ve API ile Web'i başlatır.

Varsayılan adresler:

Web: http://localhost:3000
API: http://localhost:8080

Sabit yerel doğrulama kodu, geliştirme yapılandırmasından gelir. İnternete açık bir dağıtım için yerel bir .env kullanmayın.

Bir worktree içinde geliştirme

Depo, birincil checkout'u ve birden fazla worktree'yi aynı anda çalıştırmayı destekler. Bunlar tek bir PostgreSQL container'ını paylaşır ancak ayrı veritabanları ve portlar kullanır.

git worktree add ../multica-feature -b feat/my-change main
cd ../multica-feature
make setup-worktree
make start-worktree

make setup-worktree, .env.worktree'yi üretir; veritabanı adı ve portlar yoldan türetilir. Tekrar başlatmak için:

make start-worktree

Geçerli worktree için Web ve API'yi durdurmak için:

make stop-worktree

make dev'i doğrudan da çalıştırabilirsiniz. Betik, bir worktree'yi .git dosyası üzerinden algılar ve .env.worktree'yi seçer.

Sık kullanılan komutlar

Tam iş akışı

make up               # Bu checkout'un ortamını başlatır (C=api,web,daemon,desktop)
make status           # Neyin çalıştığını gösterir ve bu ortam olduğunu kanıtlar
make list             # Bu makinedeki her ortamı listeler
make down             # Süreçleri durdurur, veritabanını korur
make destroy          # Durdurur, ardından veritabanını siler ve slotu boşaltır
make gc               # Süresi dolmuş veya dizini olmayan ortamları toplar
make dev              # Geçerli checkout'u ön planda hazırlar ve başlatır
make check            # Tam yerel doğrulama iş akışını çalıştırır
make build            # server, CLI ve migrate ikili dosyalarını derler

make up, bir ortamı adlandırılmış bir nesne olarak ele alır: API, Web ve Desktop renderer portlarını, veritabanı adını ve CLI profilini bir kilit altında ayırır ve bunları ~/.multica/dev/ içine kaydeder, böylece iki checkout, biri bilgilendirilmeden aynı slota düşemez. Veritabanını DATABASE_URL üzerinden, arka ucu ise pid, commit ve started_at bildiren GET /health üzerinden doğrular — yalnızca 200 dönmesi, aynı porttaki kalıntı bir süreçten de gelebilir. make destroy, veritabanını, CLI profilini, daemon çalışma alanlarını, Desktop userData'sını ve kayıt defteri girdisini kaldırır; başarısız bir silme, yeniden deneme için kayıt defteri girdisini korur. Geçici ortamlar, TTL'lerinden sonraki bir sonraki make up çağrısında best-effort olarak toplanır.

Ön yüz

pnpm install
pnpm dev:web
pnpm dev:desktop
pnpm build
pnpm typecheck
pnpm lint
pnpm test

Kök komutlar varsayılan olarak Mobile'ı hariç tutar. Mobile'ın ayrı betikleri ve CI'ı vardır; değiştirmeden önce apps/mobile/CLAUDE.md'yi okuyun.

Arka uç

make server
make daemon
make test
make migrate-up
make migrate-down
make sqlc

Kaynaktan bir CLI komutu çalıştırmak için:

make cli ARGS="issue list"

Ön yüz özelliklerini değiştirme

Hem Web hem de Desktop tarafından ihtiyaç duyulan özellikleri sorumluluğa göre yerleştirin:

1. API tiplerini, sorguları, mutasyonları ve platformdan bağımsız mantığı packages/core/ içine koyun.
2. Temel arayüzü packages/ui/ içine koyun; iş koduna bağımlı olmamalıdır.
3. İş sayfalarını ve bileşenlerini packages/views/ içine koyun.
4. Next.js, Electron ve yönlendirme adaptörlerini ilgili uygulamada tutun.
5. Paylaşımlı sayfaları hem Web hem de Desktop'a bağlayın.

TanStack Query sunucu verisine sahiptir. Zustand, filtreler, taslaklar ve yerleşim gibi istemci durumuna sahiptir. Kesin sınır için bkz. Proje mimarisi ve kök CLAUDE.md.

Bir API ekler veya değiştirirken, packages/core/api/ içindeki zod şemasını güncelleyin ve eksik alanlar, bilinmeyen enum değerleri ve bozuk veri için ayrıştırma testleri ekleyin.

Veritabanını değiştirme

Migration'lar server/migrations/ içinde, sorgular ise server/pkg/db/queries/ içinde yaşar.

1. Kullanılmayan bir sonraki sayısal öneki kullanın ve hem .up.sql hem de .down.sql oluşturun.
2. Veritabanı yabancı anahtarları, cascade delete veya cascade update eklemeyin. İlişkileri ve temizliği uygulama katmanında zorunlu kılın.
3. Her yeni index, CREATE INDEX CONCURRENTLY veya CREATE UNIQUE INDEX CONCURRENTLY kullanmalıdır.
4. Her concurrent index'i, yalnızca o ifadeyi içeren bir migration dosyasına koyun.
5. Sorguları değiştirdikten sonra make sqlc'yi çalıştırın ve üretilen değişiklikleri server/pkg/db/generated/ içinde commit'leyin.
6. sqlc tarafından üretilen dosyaları doğrudan düzenlemeyin.

Birden fazla yazmanın birlikte başarılı olması veya geri alınması gerektiğinde servis katmanında bir uygulama transaction'ı kullanın.

Test konumları

Önce değişikliğe en yakın kontrolü çalıştırın, ardından kapsamı genişletin. Yalnızca Dokümantasyon değişikliği için:

pnpm --filter @multica/docs typecheck

Paylaşımlı ön yüz değişiklikleri için:

pnpm typecheck
pnpm test

Arka uç değişiklikleri için:

make test

Göndermeden önce:

make check

make check, TypeScript tip kontrolünü ve birim testlerini, Go testlerini ve Playwright E2E'sini çalıştırır. CI ayrıca değişen kapsama göre derleme ve lint yapar ve platforma veya yükleyiciye özgü testleri çalıştırır.

Geçerli geliştirme veritabanını sıfırlama

Temiz veriye ihtiyaç duyduğunuzda, geçerli checkout'un ortam dosyasının adlandırdığı veritabanını sıfırlayın:

make stop
make db-reset
make start

make db-reset, geçerli POSTGRES_DB'yi düşürür ve yeniden oluşturur, uzak bir veritabanına bağlanmayı reddeder. Çalıştırmadan önce .env veya .env.worktree'yi kontrol edin ve hedef veritabanını doğrulayın.

Göndermeden önce

• Kök CLAUDE.md'yi ve ilgili iç içe talimatları okuyun.
• Yalnızca işin gerektirdiği kapsamı değiştirin.
• Kod yorumlarını İngilizce yazın.
• .env, token, derleme çıktısı veya yerel yolları commit'lemeyin.
• feat(scope), fix(scope) veya docs gibi conventional commit'ler kullanın.
• Davranış değişikliklerini ve gerçekten çalıştırılan doğrulama komutlarını PR'da açıklayın.

Sonraki adımlar

• Geliştirme kuralları — Adlandırma, terminoloji ve Çince metin için depo sözleşmeleri.
• Proje mimarisi — Katmanlar, paylaşımlı paketler ve tek bir çalıştırma için kod yolu.