# Alışveriş Rehberi

**"Siyah ceket almak istiyorum" de, gerisini o halletsin.**

Alışveriş Rehberi, yapay zekâ asistanına (Claude, Codex, OpenCode vb.) eklenen bir yetenektir. Sen ne aradığını kendi cümlelerinle anlatırsın. O da seni biraz tanır, sade sorularla tam neye ihtiyacın olduğunu bulur, **11 giyim mağazasında** arar ve bulduklarını telefonda da rahat kullanılan, kartlarla gezilen bir sayfada önüne koyar.

Moda terimlerini bilmen gerekmez. "Blazer nedir?" diye sorman gerekmez, çünkü rehber her seçeneği kendisi anlatır.

---

## Neler yapabilir?

- **Seni tanır.** Bedenini, tarzını, sevdiğin renkleri bir kez sorar ve hatırlar. Bir daha sormaz.
- **Ne istediğini bulur.** "Hafif bir mont" dersin. Hangi havada giyeceksin, spor görünmesi sorun olur mu, kapüşon ister misin gibi kısa sorular sorar. **"Yeter, daha fazla sorma"** dediğin an sormayı bırakır.
- **Cinsiyete saygı duyar.** Erkek, kadın ya da ikisi birden seçersin. Sana kendi bölümünün ürünlerini ve **unisex** ürünleri gösterir. Karşı cinsiyetin ve çocukların ürünlerini göstermez.
- **11 mağazada birden arar:** Zara, Bershka, Pull&Bear, H&M, Mango, Mudo, Levi's, DeFacto, LTB Jeans, Les Benjamins, Trendyol Milla.
- **Ürün sayfasına girip kontrol eder.** Ürünün adına ya da markasına bakıp tahmin yürütmez. "Kaz tüyü dolgulu" bir mont istediysen sayfadaki açıklamayı ve içerik bilgisini okur. Sayfada yazmıyorsa "belirtilmemiş" der, varmış gibi göstermez. Sayfada tersi yazıyorsa (örneğin "dolgu: %100 polyester") o ürünü önermez.
- **Rapor hazırlar.** Ürünler **kaydırmalı kartlar** olarak gelir. Sağa kaydırırsan beğendin, sola kaydırırsan geçtin demektir. Beğendiklerin "Seçtiklerim" listesinde toplanır ve tek tıkla **PDF** olarak kaydedilir. Telefonda da çalışır.

**Yapmadıkları:** Satın almaz, sepete eklemez, hesabına girmez. Sadece bulur ve karşılaştırır. Fiyat ve stok arama anındaki bilgidir, mağazada bir kez daha kontrol et.

---

## Nasıl görünür?

1. Sen: *"Kışın giyebileceğim hafif bir kaz tüylü mont arıyorum, çok sportif olmasın."*
2. Rehber, cümlenden anladıklarını yazar ve eksikleri sorar. Örneğin: "Kimin için? Erkek, kadın, ikisi de?", "Kapüşonlu olsun mu?", "En fazla ne kadar harcamayı düşünüyorsun?". Her seçeneğin yanında ne demek olduğu yazar.
3. Bir Chrome penceresi **gözünün önünde** açılır ve mağazalar tek tek gezilir. Bu 1-2 dakika sürer.
4. En iyi adayların sayfalarına girilip kontrol edilir.
5. Sana kısa bir özet ve bir **rapor dosyası** verilir. Dosyayı tarayıcıda açıp kartları gezersin.

Örnek bir rapor bu klasörde `ornekler/` altındadır. Tarayıcıda açıp bakabilirsin.

---

## Kurmadan önce

Bilgisayarında şunlar olmalı:

| Ne | Neden | Nereden |
|---|---|---|
| **Google Chrome** | Mağazalar bu pencerede gezilir | https://www.google.com/chrome |
| **Node.js 20 ya da üstü** | Eklentiyi çalıştırır | https://nodejs.org (LTS sürümü) |
| **Bir yapay zekâ asistanı** | Rehberi kullanacağın program | Aşağıya bak |

Hangisini kullanıyorsan aşağıdaki bölümü oku.

> **Önemli fark:** *Claude Code*'da kurulum bir paket olarak gelir ve soru sorma, doğrulama, raporlama akışını yöneten **rehber (skill)** de kendiliğinden yüklenir. Diğer programlarda (Codex, OpenCode, Claude Desktop vb.) araçlar aynı şekilde çalışır ve akışın özeti araçların içinde yazılıdır, ama rehber o kadar titiz davranmayabilir. Gerekirse ilk mesajında şunu yaz: *"Alışveriş araçlarını kullan: önce beni tanı, sade sorularla ne istediğimi netleştir, ürün sayfalarını doğrula, sonunda rapor üret."*

---

## 1. Claude Code (en kolay yol)

Terminalde şu iki satırı çalıştır:

```bash
claude plugin marketplace add Atanur/alisveris
claude plugin install alisveris@alisveris-market
```

Claude Code'u kapatıp yeniden aç ve ne istediğini yaz. Bu kadar.

Güncellemek için:

```bash
claude plugin marketplace update alisveris-market
claude plugin update alisveris@alisveris-market
```

---

## Diğer programlar için ortak hazırlık

Claude Code dışındaki programlarda önce projeyi bilgisayarına indirip bir kez hazırlaman gerekir. Terminalde:

```bash
git clone git@github.com:Atanur/alisveris.git
cd alisveris
npm install --omit=dev
pwd
```

Son komut klasörün tam yolunu yazar (örneğin `/Users/ayse/alisveris`). **Bu yolu not et.** Aşağıdaki örneklerde `/TAM/YOL/alisveris` yazan yere bunu koyacaksın.

Eklentinin çalışacağı komut her programda aynıdır:

```
node /TAM/YOL/alisveris/dist/index.js
```

Programlar arasındaki fark, bu komutu hangi ayar dosyasına yazdığındır.

---

## 2. Codex (OpenAI)

Terminalde tek komutla ekleyebilirsin:

```bash
codex mcp add alisveris -- node /TAM/YOL/alisveris/dist/index.js
```

Ya da ayar dosyasını elle düzenle: `~/.codex/config.toml` dosyasının sonuna şunu ekle:

```toml
[mcp_servers.alisveris]
command = "node"
args = ["/TAM/YOL/alisveris/dist/index.js"]
```

Codex'i yeniden başlat.

---

## 3. OpenCode

Proje klasöründeki ya da `~/.config/opencode/` altındaki `opencode.json` dosyasına ekle:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "alisveris": {
      "type": "local",
      "command": ["node", "/TAM/YOL/alisveris/dist/index.js"],
      "enabled": true
    }
  }
}
```

OpenCode'u yeniden başlat.

---

## 4. Claude Desktop (Claude uygulaması)

Uygulamada **Ayarlar → Geliştirici → Yapılandırmayı düzenle** yolunu izle. Açılan `claude_desktop_config.json` dosyasına ekle:

```json
{
  "mcpServers": {
    "alisveris": {
      "command": "node",
      "args": ["/TAM/YOL/alisveris/dist/index.js"]
    }
  }
}
```

Uygulamayı tamamen kapatıp yeniden aç.

---

## 5. Gemini CLI

`~/.gemini/settings.json` dosyasına ekle:

```json
{
  "mcpServers": {
    "alisveris": {
      "command": "node",
      "args": ["/TAM/YOL/alisveris/dist/index.js"]
    }
  }
}
```

---

## 6. Cursor, Windsurf ve benzerleri

Bu programların çoğu aynı biçimi kullanır. Cursor için `~/.cursor/mcp.json` dosyasına, diğerleri için kendi "MCP sunucuları" ayarına şunu yaz:

```json
{
  "mcpServers": {
    "alisveris": {
      "command": "node",
      "args": ["/TAM/YOL/alisveris/dist/index.js"]
    }
  }
}
```

> Ayar dosyalarının yeri ve biçimi program sürümlerine göre değişebilir. Bir örnek çalışmazsa programın kendi belgelerinde "MCP sunucusu ekleme" bölümüne bak ve yukarıdaki `node .../dist/index.js` komutunu oraya yaz. Bu komut her yerde aynıdır.

---

## Çalıştığını nasıl anlarım?

Programda yeni bir konuşma aç ve şunu yaz:

> **Alışveriş araçlarını gösterir misin?**

`alisveris_profil`, `alisveris_gorusme`, `alisveris_ara`, `alisveris_detay`, `alisveris_rapor` adlı beş aracı sayıyorsa kurulum tamamdır. Sonra asıl isteğini yaz:

> **Kadın için siyah, ince bir blazer ceket arıyorum, 3000 TL'yi geçmesin.**

---

## Sık sorulan sorular

**Bir Chrome penceresi açıldı, normal mi?**
Evet. Her şey gözünün önünde olsun diye mağazalar görünür bir pencerede gezilir. İş bitince sekmeler kapanır, boşta kalırsa pencere 5 dakika sonra kendiliğinden kapanır. Arama sürerken pencerede tıklama ya da yazma yapma, aramayı bozabilir.

**Bir mağaza "hata verdi" dedi.**
Mağaza siteleri bazen yavaşlar ya da değişir. O mağaza atlanır ve raporun uyarılar kısmında yazar. Diğerleri etkilenmez.

**Bir sitede "robot değil misin?" sorusu çıkarsa?**
Rehber bu kontrolleri aşmaya çalışmaz. O mağaza atlanır.

**Kişisel bilgilerim nereye gidiyor?**
Hiçbir yere. Bedenin, tarzın ve renk tercihlerin yalnızca bilgisayarındaki `~/.alisveris/profil.json` dosyasında durur. Kaydetmeden önce izin sorulur. Silmek için o dosyayı silmen yeter. Kullandığın yapay zekâ programı, konuşmada yazdıklarını kendi kurallarına göre işler.

**Raporlar nerede?**
`~/.alisveris/raporlar` klasöründe. Oradaki `index.html` bütün raporlarını listeler.

**Neden bazı ürünlerde renk ya da beden stoğu yok?**
Bazı mağazalar bu bilgiyi liste sayfasında vermiyor. Rehber bunu "doğrulanamadı" diye belirtir, uydurmaz.

**Erkek mi, kadın mı, unisex mi olduğunu nasıl anlıyor?**
Önce mağazanın kendi erkek/kadın bölümünde arar. DeFacto, Mudo ve Levi's gibi ürün kartında cinsiyet yazmayan mağazalarda ürün sayfasına girip kontrol eder.

---

## Geliştirenler için

```bash
pnpm install
pnpm test        # birim testleri
pnpm typecheck
pnpm build       # dist/ klasörü bilerek commit'lenir
pnpm e2e         # canlı deneme: görünür Chrome açar, gerçek mağazalarda arar
```

- `src/gorusme/`: soru bankası ve görüşme motoru
- `src/magazalar/`: mağaza bağlayıcıları (Shopify, Inditex/Zara, genel sayfa okuyucu)
- `src/detay/`: ürün sayfası okuma ve kanıt arama
- `src/rapor/`: HTML rapor
- `skills/alisveris-rehberi/`: Claude Code için rehber (skill)

Yeni mağaza eklemek için `src/magazalar/` altına bir bağlayıcı yazıp `index.ts` listesine ekle.

### Ayarlar (isteğe bağlı)

Aşağıdaki ayarların **hiçbirini doldurman gerekmez**; hepsinin çalışan bir varsayılanı var. Bunlar gizli bilgi (parola, API anahtarı) değil, yalnızca klasör yolları, süre ve sekme sayısıdır.

| Değişken | Varsayılan | Anlamı |
|---|---|---|
| `ALISVERIS_PROFIL` | `~/.alisveris/chrome-profil` | Chrome profil klasörü |
| `ALISVERIS_BOSTA_KAPAT_MS` | `300000` | Boşta kalınca Chrome'u kapatma süresi |
| `ALISVERIS_ESZAMANLI` | `3` | Aynı anda açık mağaza sekmesi |
| `ALISVERIS_RAPOR_DIZINI` | `~/.alisveris/raporlar` | Rapor klasörü |
| `ALISVERIS_PROFIL_DOSYASI` | `~/.alisveris/profil.json` | Kişisel profil |

---

## Sınırlar ve not

- Mağaza siteleri değişirse bağlayıcılar bozulabilir. Hata veren mağaza raporda görünür.
- Bu proje **kişisel kullanım** içindir: düşük hızda ve yalnızca görünür tarayıcıyla çalışır. Mağazaların kullanım koşullarına uymak senin sorumluluğundadır.
- Anılan mağazalarla bir bağlantısı yoktur.
- Lisans: MIT