Blueforce-Linux/docs/20-FIELD-TECHNICIAN-RUNBOOK.md

# 20 — Saha Teknisyeni Runbook

> Kısa özet: Sahada cihaz başına giden teknisyenin el kitabı. Tek akış: USB'yi tak → Ubuntu'yu kur → `sudo bf` → bayi numarasını gir → sonucu gör. Komut ezberi istenmez: kurulum, durum ve destek paketi grafik arayüzdeki düğmelerle yapılır; her adımda "ne göreceksin, ne yazacaksın" vardır.

- Dosya: `docs/20-FIELD-TECHNICIAN-RUNBOOK.md`
- İlgili kararlar: `24-DECISION-LOG.md#K-09` (USB → kurucu → bayi no), `#K-12` (bayi no → `BF-<no>`), `#K-14` (`bf-status`, support-bundle), `#K-16` (offline kurulum)
- İlgili dokümanlar: `33-OPERATOR-CONSOLE.md` (arayüz rehberi), `27-OFFLINE-PROVISIONING.md` (paket deposu)
- Durum: [ ] Taslak

---

## 1. Amaç

Teknisyenin sahada tek başına, telefonsuz bile cihazı teslim edilebilir hale getirmesi. Bu dosya "neden" anlatmaz, "ne yap" söyler. Neden merak eden 01'e bakar.

## 2. Kapsam

- Kapsam içi: USB ile sıfır kurulum, grafik arayüzü açma, bayi no girişi, kurulum sonucunu doğrulama, arızalı cihazda ilk 3 hareket, merkeze ne zaman telefon açılacağı.
- Kapsam dışı: merkez onayları (21), arıza teşhis tablosu detayı (19 — sadece yönlendirme), update dalgaları (10).

## 3. Kararlar

```text
KARAR:    Teknisyen akışı 4 adımdır: USB → Ubuntu kur → `sudo bf` ile kurulum (bayi no) → sonucu gör. Grafik arayüz tek giriş noktasıdır; terminal konsolu (`sudo bf --tui`) yalnız grafik ekran veya tkinter yoksa kullanılan yedektir. Teknisyen hostname, IP, anahtar, paket yolu veya config dosyası ile uğraşmaz; paketler depoyla gelir ve kurulumda internet gerekmez.
GEREKÇE:  K-09/K-16'nın hedef akışı; insan hatası en çok elle config ve ezberlenen komutta olur. Teknisyenin tek manuel girdisi 8 haneli bayi numarasıdır (K-12).
ALTERNATİF: Teknisyene tam Linux eğitimi + manuel kurulum — 700 cihazda standardizasyon bozulur; elendi. Yalnız bash menülü kurulum — grafik arayüz varken gereksiz terminal bilgisi ister; yedek yol olarak korundu.
RİSK:     Depo kopyası eski sürüm kalır; azaltma: repo sürüm etiketi + merkezden "şu sürümden eski kopyayı kullanma" duyurusu.
MALİYET:  Ücretsiz.
LİSANS:   Yok.
```

## 4. Neden Bu Karar?

Teknisyenin işi "bilgisayarcılık" değil "bayi cihazını çalışır teslim etmek"tir. Karar, teknisyenin dikkatini tek kritik noktaya toplar: bayi numarasını doğru girmek. Geri kalan her şey uygulama + merkez otomasyonudur. Bu yüzden bu dosya kısa cümlelerle, emir kipiyle yazılır.

## 5. Alternatifler

| Alternatif | Artı | Eksi | Sonuç |
|---|---|---|---|
| Grafik arayüz (`sudo bf`) | Tek düğme, komut ezberi yok, onay görünür | Grafik katman gerekir | **Seçildi** |
| Detaylı Linux kılavuzu | Bilgili teknisyen | Uzun, hata açık, herkes okumaz | Elendi |
| Merkezden uzaktan kurulum (teknisyensiz) | Saha maliyeti yok | İlk kurulumda cihazda internet/VPN yok | Elendi (ilk kurulum sahada) |

## 6. Avantajlar

- Yeni teknisyen 1 saatlik eğitimle sahaya çıkar.
- Her cihaz aynı adımla kurulur; "ustalık farkı" kapanır.
- Kurulum internetsiz çalışır: paket seti depodan gelir, hiçbir şey indirilmez.

## 7. Dezavantajlar

- Uygulamanın yapmadığını teknisyen de yapamaz; olağandışı durumda merkeze bağımlıdır (bilerek böyle).
- Depo kopyası (paket setiyle birlikte ~888 MB) fiziksel/lojistik takip ister.

## 8. Riskler

| Risk | Olasılık | Etki | Azaltma |
|---|---|---|---|
| Bayi no yanlış girilir | Orta | Yüksek | Arayüz `BF-<no>`'yu gösterir, teknisyen bayiye onaylatır |
| Eski depo kopyası ile kurulum | Orta | Orta | Repo sürüm etiketi + kurucu başlangıçta depoyu ve paket sayısını söyler |
| Grafik arayüz açılmaz (ekran/tkinter) | Orta | Orta | `sudo bf --tui` yedeği; sorun merkeze bildirilir |
| Sonuç görülmeden sahadan çıkılır | Düşük | Yüksek | Kontrol listesi imzalanmadan iş kapanmaz |

## 9. Uygulama Planı

### A. Sıfır kurulum (yeni cihaz) — 4 adım

**ADIM 1 — USB'yi tak, bilgisayarı aç.**

1. Kurulum USB'sini tak.
2. Bilgisayarı aç, USB'den başlat (açılışta genelde F12/F8/F2 — ekranda yazar).
3. Ubuntu kurulum ekranı gelene kadar bekle.

> Göreceğin: Ubuntu kurulum ekranı. Bunu görmüyorsan: USB tam takılı mı, BIOS boot sırası USB mi? Olmazsa merkeze telefon aç.

**ADIM 2 — Ubuntu'yu kur ve depo kopyasını getir.**

1. Ekrandaki kurulumu varsayılanlarla tamamla (dil: Türkçe, disk: tamamını kullan).
2. Kurulum bitince USB'yi çıkarma, bilgisayarı yeniden başlat.
3. Repo kopyasını cihaza getir (merkezin söylediği yolla: `git clone` — paketler Git LFS ile birlikte gelir — veya hazır kopya `/opt/blueforce/offline-repo` altına konur).

> Paketler repoyla birlikte gelir; **internetten hiçbir şey indirilmez**.

**ADIM 3 — Grafik arayüzü aç, bayi numarasını gir, kurulumu başlat.**

1. Terminali aç, şunu yaz:

```bash
sudo bf
```

2. Pencere açılır: başlık **Blueforce Field OS — Yönetim**. (Ekran yoksa veya tkinter yoksa uygulama Türkçe uyarı verir; o zaman `sudo bf --tui` yaz — §D.)
3. Üst çubuktaki **Hedef > Bayi no (8 hane)** alanına **8 haneli bayi numarasını** yaz. Faturadaki/sistemdeki numarayı kullan. Örnek: `12010193`.
4. **Kurulum** sekmesi → **`Bu cihazı kur`**.
5. Arayüz komutu ekranda gösterir ve onay ister. `BF-12010193` görünüyor mu? Doğruysa onayla; yanlışsa iptal et ve numarayı düzelt.

```text
Arayüzden:  sudo bf  →  Hedef: Bayi no (8 hane)  →  Kurulum  →  "Bu cihazı kur"
Komutla (yedek):
            sudo bf --tui            # terminal konsolu; Kurulum menüsünden aynı akış
            sudo ./scripts/install/blueforce-install.sh --dealer-id 12010193
```

6. Numarayı bayiye sesli onaylat: "Cihaz numaranız BF-12010193, doğru mu?"

**ADIM 4 — Sonucu gör, çık.**

1. Kurulum bitene kadar bekle (kapatma, fişi çekme). Cihazın açık kalması şart.
2. Sonucu gör:

```text
Arayüzden:  `Durum` düğmesi (basit mod) → Durum özeti   ya da Kurulum sekmesi → "Kurulum modül durumu"
Komutla (yedek):  bf-status
```

3. **`PROVISIONED_OFFLINE`** görmen normaldir: kurulum yerelde tamamlandı, cihaz internetsiz kuruldu. Bu durumda cihaz `READY` değildir.
4. İnternet geldiğinde merkezden tek-kullanımlık enrollment token iste ve 29'daki adımı uygula.
5. Token sonrası **ENROLLED** görünür; WireGuard, remote ve monitoring merkezi doğrulaması bitince **READY** görürsün.
6. READY sonrası kontrol listesini doldur (§12), sahadan çık.

### B. Arızalı cihaza gittin — ilk 3 hareket

1. Durumu oku:

```text
Arayüzden:  sudo bf  →  `Durum` düğmesi (Durum özeti)
Komutla (yedek):  bf-status
```

Kırmızı satır hangisi? Not al.
2. Bilgisayarı bir kez yeniden başlat. Düzelirse READY'yi gör, çık.
3. Düzelmezse destek paketini al, merkeze gönder:

```text
Arayüzden:  sudo bf  →  Detaylı mod  →  Araçlar sekmesi  →  "Destek paketi oluştur"
Komutla (yedek):  bf-support-bundle --out /tmp/bf-<bayi-no>-bundle.tar.gz
```

Paketi merkeze ilet (telefonla nasıl göndereceğin söylenir), merkez sana söylemeden başka komut çalıştırma.

### C. Merkeze telefon açma kuralları

Hemen ara: sonucu alamıyorsan, aynı arıza 2 cihazda üst üste çıktıysa, donanım kırık/yanık kokusu varsa, bayi numarasından emin değilsen.
Arama: cihaz başında ol, `BF-<no>`'yu ve durum özetini/`bf-status` çıktısını hazır tut.

### D. Grafik arayüz açılmıyor — yedek yol

| Belirti | Ne yap |
|---|---|
| "Grafik ekran bulunamadı" / SSH oturumu | `sudo bf --tui` yaz; aynı işlemler terminal menüsünde numaralarla yürür |
| "tkinter bulunamadı" | `sudo bf --tui` ile devam et ve merkeze bildir; `python3-tk` paketi kurulum depounda pinlidir (19 §T-10) |
| Pencere açıldı ama dondu | Pencereyi kapat, `sudo bf --tui` ile devam et, merkeze bildir |

## 10. Test Planı

| Test | Beklenen sonuç | Ortam |
|---|---|---|
| Sıfır teknisyen 4 adımı desteksiz yapar | Hedef teslim durumu < hedef süre | LAB(2) |
| Yanlış bayi no girilir | Uygulama uyarır, komut üretilmez/çalışmaz | LAB(2) |
| Ekransız oturumda `sudo bf` | Türkçe yönlendirme + `sudo bf --tui` önerisi, exit 3 | LAB(2) |
| Depo kopyası olmayan cihazda kurulum | Türkçe hata + aranan yollar + çıkış nedeni, sistem değişmez | LAB(2) |
| Elektrik kesintisi simülasyonu sonrası durum | Kurulum kaldığı yerden tamamlanır; durum doğru raporlanır | LAB(2) |

## 11. Rollback

Teknisyen rollback yapmaz. Kurulum yarıda kesildiyse: `sudo bf` → Kurulum sekmesi → **`Başarısız kuruluma devam et (--resume)`** (komutla yedek: aynı kurucu `--resume` bayrağıyla). İkinci denemede de olmazsa merkeze telefon aç — merkez 17-RECOVERY'den seviyeyi seçer.

## 12. Kontrol Listesi

- [ ] Depo kopyası/checkout sürümü güncel (etiket + merkez duyurusu eşleşiyor).
- [ ] `BF-<no>` bayiye onaylatıldı.
- [ ] Kurulum sonucu görüldü (`PROVISIONED_OFFLINE` normaldir; READY için §A/ADIM 4-5).
- [ ] Cihaz fişe + internete bağlı bırakıldı.
- [ ] İş formu dolduruldu (bayi no, tarih, teknisyen adı).

## 13. Açık Sorular

- [ ] Depo kopyasının sahaya taşınma/sürüm takip yöntemi (git clone + LFS mı, hazır kopya mı) (sahibi: merkezi admin, 21).
- [ ] İş formu kağıt mı mobil mi (sahibi: 25-ROADMAP).
- [ ] Hedef kurulum süresi (öneri: P2'de ölçülecek).

---

## Ek: Mermaid — teknisyen akışı

```mermaid
flowchart TB
    USB["USB tak → aç"] --> KUR["Ubuntu kur"]
    KUR --> DEPO["Depo kopyasını getir<br/>(paketler LFS ile gelir, indirme yok)"]
    DEPO --> BF["sudo bf"]
    BF --> EKRAN{"Grafik ekran +<br/>python3-tk var mı?"}
    EKRAN -->|Hayır| TUI["sudo bf --tui<br/>(yedek terminal konsolu)"]
    EKRAN -->|Evet| NO["Hedef: Bayi no (8 hane)"]
    TUI --> NO
    NO --> ONAY["Arayüz komutu gösterir + onay<br/>BF-no'yu bayiye onaylat"]
    ONAY --> BEKLE["Kurulum bitsin<br/>(kapatma / fişi çekme)"]
    BEKLE --> DURUM["Durum: PROVISIONED_OFFLINE / ENROLLED / READY"]
    DURUM -->|"READY"| CIK["Formu doldur → çık"]
    DURUM -->|"sorun var"| TEL["Destek paketi + merkeze telefon aç"]
```