# 05 — Yol Haritası ve AI Geliştirme Rehberi

> **AI'lere sorulacak:** Faz sırası doğru mu? Hangi görevi önce almalıyız? TASK şablonu yeterli mi?

**Versiyon:** 1.0 · **2026-07-05**

---

## 1. Faz özeti

| Faz | Ad | Süre | Gate |
|-----|-----|------|------|
| **0** | Proje çıkarımı & docs | 1–2 gün | D1–D3 onayı |
| **1** | Birleşik Android shell | ~1 hafta | Tek APK smoke |
| **2** | Mağaza ↔ manifest | ~1 hafta | Deep link çalışır |
| **3** | Device Agent Seviye A | ~2 hafta | 3 komut + audit |
| **4** | Shizuku / Root opt-in | 2+ hafta | Güvenlik review |

```mermaid
flowchart LR
  P0[Faz 0] --> P1[Faz 1]
  P1 --> P2[Faz 2]
  P1 --> P3[Faz 3]
  P2 --> P3
  P3 --> P4
```

**Tamamlanan:** Web mağaza canlı · Docs (5 MD) · Asistan v2.3.x

---

## 2. Faz detayları

### Faz 0 — Proje çıkarımı 🟡
- [x] 5 MD dokümantasyon
- [ ] D1–D5 karar onayı
- [ ] `Emare superapp` → `superapp/android/` taşıma
- [ ] CI taslağı

### Faz 1 — Birleşik shell
- [ ] Asistan modülleri taşı
- [ ] Tek SessionManager, ApiClient (OkHttp pattern)
- [ ] Birleşik bottom nav
- [ ] RegisterActivity → provision API
- [ ] `./gradlew assembleRelease` + ProGuard smoke

### Faz 2 — Mağaza ↔ manifest
- [ ] `GET /api/v1/tenant/workspace-manifest`
- [ ] `GET /api/v1/superapp/catalog`
- [ ] App Links + launcher grid
- [ ] Mağaza "Aç" deep link

### Faz 3 — Device Agent A
- [ ] Device entity + API
- [ ] `DeviceAgentService` Android
- [ ] Komutlar: open_app, open_url, show_notification, start_ai_call
- [ ] AI Action → device mapping
- [ ] Audit log

### Faz 4 — Shizuku / Root
- [ ] Shizuku SDK + install_apk (onaylı)
- [ ] `root` flavor (ayrı applicationId)
- [ ] Tenant policy: max seviye cap

---

## 3. Riskler

| Risk | Azaltma |
|------|---------|
| İki APK karmaşası | Faz 1 deadline + OTA |
| Gson/ProGuard | OkHttp+JSONObject |
| Root Play red | Opt-in flavor |
| Device abuse | Policy + audit + rate limit |

---

## 4. AI ajan kuralları (pre-flight)

```
✓ 01-VIZYON-VE-KARARLAR.md
✓ İlgili teknik MD (02–04)
✓ Aktif faz checklist (yukarı)
```

**Scope:** Tek issue = tek faz görevi · minimal diff · sır yazma · commit yalnızca kullanıcı isteğiyle · root kodu Faz 4 onaysız yasak.

**Kod konumları:**
| Görev | Path |
|-------|------|
| Android | `superapp/android/` (hedef) |
| Asistan modül | `Mobile App/` → taşınacak |
| Web mağaza | `tenant-sites/superapp/` |
| Backend device API | `src/EmareTicket.API/` (onay gerekir) |

---

## 5. Görev şablonu (AI'lere kopyala-yapıştır)

```markdown
## TASK_SA-XXX — [Başlık]
**Faz:** [0–4] | **Branch:** feat/superapp/phaseN-açıklama

### Amaç
[1–2 cümle]

### Kapsam
Dahil: ...
Hariç: ...

### Okunacak
- 01-VIZYON-VE-KARARLAR.md (D1–D5)
- [02|03|04 ilgili bölüm]

### DoD
- [ ] Build geçer
- [ ] Smoke test (listele)
- [ ] Doküman güncellendi (gerekirse)

### AI'den çıktı iste
- Uygulama planı (adım adım)
- Risk listesi
- Alternatif yaklaşım
- Test senaryoları
```

---

## 6. AI iş akışı

```
READY → Agent 1 implement → WAITING_QA → Agent 2 QA (kod yazmaz) → PASS/DONE
```

Paralel ajan: aynı faz checkbox'ta tek WIP · Android/web/API ayrı PR.

Commit: `feat(superapp): açıklama — SA-X-XX`

---

## 7. AI'lere paylaşım paketi

Tüm fikir almak için **5 dosyayı birlikte** gönderin:

| # | Dosya | Soru odağı |
|---|--------|------------|
| 1 | `01-VIZYON-VE-KARARLAR.md` | Vizyon, D1–D5 |
| 2 | `02-MIMARI-VE-ENTEGRASYON.md` | Mimari, API, güvenlik |
| 3 | `03-MOBIL-ANDROID-ASISTAN.md` | Birleşme, nav, runtime |
| 4 | `04-WEB-MAGAZA-CIHAZ-KONTROLU.md` | Mağaza, device agent |
| 5 | `05-YOL-HARITASI-AI-GELISTIRME.md` | Faz sırası, süreç |

### Örnek prompt (AI'lere)

```
Emare Superapp projesi için 5 MD dosyasını oku.
1) En büyük mimari risk nedir?
2) MVP için scope kesimi öner (Faz 0–1).
3) D1–D5 kararlarına alternatif.
4) Device control için güvenli minimum komut seti.
5) İlk sprint'te 3 somut task öner (TASK_SA formatında).
Türkçe, maddeli, kısa cevap ver.
```

---

## 8. Metrikler (hedef)

| Metrik | Hedef |
|--------|-------|
| Crash-free sessions | > %99 |
| Login → first app | < 5 sn |
| Device command latency | < 2 sn (A) |
| Mağaza LCP | < 2.5 sn |

---

## 9. Dış referanslar

- `docs/workspaces/WORKSPACE_MANIFEST.md`
- `docs/AI_ACTION_ENGINE.md`
- `docs/kalan-eksikler/09-mobil-superapp.md`
- `scripts/deploy/deploy-superapp-site.sh`

**Önceki:** [04-WEB-MAGAZA-CIHAZ-KONTROLU.md](./04-WEB-MAGAZA-CIHAZ-KONTROLU.md)