Hujjatlar va qo'llab-quvvatlash

# Onlayn do'kon

Kichik va o'rta biznes uchun onlayn savdo platformasi.

[![Testlar](https://github.com/.../actions/workflows/ci.yml/badge.svg)](...)
[![Qoplama](https://codecov.io/.../badge.svg)](...)

## Nima qiladi?

- Mahsulotlar katalogi va qidiruv
- Savat va buyurtma berish
- To'lov tizimlari bilan integratsiya
- Admin panel va hisobotlar

## Tez boshlash

    git clone [email protected]:kompaniya/dokon.git
    cd dokon
    cp .env.example .env
    docker compose up -d
    docker compose exec ilova php tools/migrate.php
    docker compose exec ilova php tools/seed.php

Sayt: http://localhost:8080
Admin: [email protected] / admin123

## Talablar

| Dastur | Versiya |
|--------|---------|
| PHP | 8.2+ |
| MySQL | 8.0+ |
| Redis | 7.0+ |
| Node.js | 20+ |

## Loyiha tuzilishi

    manba/
      Modullar/       - biznes modullar
      Umumiy/         - umumiy kod
    public/           - veb-ildiz
    database/         - migratsiyalar va seedlar
    testlar/          - testlar
    hujjatlar/        - batafsil hujjatlar

## Hujjatlar

- [Arxitektura](hujjatlar/arxitektura.md)
- [API](hujjatlar/api.md)
- [Ishlab chiqish](hujjatlar/ishlab-chiqish.md)
- [Deploy](hujjatlar/deploy.md)
- [Hissa qo'shish](CONTRIBUTING.md)

## Litsenziya

Xususiy. Barcha huquqlar himoyalangan.

/**
 * Buyurtmani bekor qiladi va omborni qaytaradi.
 *
 * Bekor qilish faqat "yangi" va "tolangan" holatlarida mumkin.
 * "Yolda" yoki "yetkazilgan" buyurtmani bekor qilib bo'lmaydi -
 * bunday holatda qaytarish jarayoni ishlatiladi.
 *
 * To'langan buyurtma bekor qilinganda pul avtomatik qaytarilmaydi -
 * bu buxgalteriya qo'lda tasdiqlashini talab qiladi (VZM-2024/17).
 *
 * @throws BuyurtmaTopilmadi
 * @throws BekorQilishMumkinEmas Holat ruxsat bermasa
 * @throws RuxsatYoq Foydalanuvchi huquqi bo'lmasa
 */
public function bekorQiling(BuyurtmaId $id, Foydalanuvchi $kim, string $sabab): void

// YOMON: kod takrori
/**
 * Foydalanuvchi identifikatorini qaytaradi.
 * @return int Foydalanuvchi identifikatori
 */
public function idOling(): int
{
    return $this->id;
}

// YAXSHI: sababni tushuntiradi
/**
 * Narxni 100 ga bo'lmasdan qaytaradi.
 *
 * To'lov provayderi summani tiyinda kutadi. Bu API ning
 * o'zgartirib bo'lmaydigan talabi.
 */
public function tiyindaNarx(): int

# Arxitektura ko'rigi

## Umumiy manzara

Tizim modulli monolit sifatida qurilgan. Har bir modul o'z
domeniga ega va boshqalar bilan faqat ochiq API orqali gaplashadi.

## Modullar

| Modul | Javobgarligi | Egasi |
|-------|--------------|-------|
| Katalog | Mahsulotlar, kategoriyalar, qidiruv | @jasur |
| Savat | Savat holati, hisob-kitob | @husanboy |
| Buyurtma | Buyurtma hayotiy tsikli | @husanboy |
| To'lov | To'lov provayderlari integratsiyasi | @aziz |
| Xabarnoma | Email, SMS, push | @malika |

## Modullararo aloqa

    Buyurtma  ──►  Katalog     (mahsulot ma'lumoti)
    Buyurtma  ──►  To'lov      (to'lov yaratish)
    Buyurtma  ──►  Xabarnoma   (hodisa orqali)

Sinxron chaqiruvlar - faqat o'qish uchun.
Yozish amallari - hodisalar orqali.

## Ma'lumot oqimi

1. Foydalanuvchi savatga mahsulot qo'shadi (Savat moduli)
2. Buyurtma yaratiladi (Buyurtma moduli)
3. `BuyurtmaYaratildi` hodisasi e'lon qilinadi
4. Xabarnoma moduli email yuboradi
5. Katalog moduli omborni kamaytiradi

## Texnologiyalar

| Qatlam | Texnologiya | Sabab |
|--------|-------------|-------|
| Backend | PHP 8.3 | Jamoa tajribasi |
| Baza | MySQL 8.0 | Hosting qo'llab-quvvatlaydi |
| Kesh | Redis 7 | Savat va sessiyalar |
| Navbat | Redis | Qo'shimcha infratuzilma kerak emas |
| Frontend | Vanilla JS | Sodda, freymvork ortiqcha |

## Cheklovlar

- Barcha ma'lumot O'zbekiston hududida saqlanishi kerak (qonun talabi)
- To'lov ma'lumotlari saqlanmaydi - provayderga yo'naltiriladi
- Sayt 3G tarmoqda ham ishlashi kerak

## Ma'lum muammolar

Qarang: [Texnik qarz reyestri](texnik-qarz.md)

# ADR-012: Savat uchun Redis

**Sana:** 2026-08-20
**Holat:** Qabul qilindi
**Ishtirokchilar:** @husanboy (arxitektor), @jasur, @aziz

## Kontekst

Savat ma'lumoti MySQL da saqlanadi. Cho'qqi paytida (soat 19:00-22:00)
`savat_elementlari` jadvaliga yozish sekinlashmoqda.

O'lchovlar (2026-08-15, cho'qqi):
- Savatga qo'shish, o'rtacha: 180 ms
- 95-protsentil: 900 ms
- MySQL yozish operatsiyalarining 40% - savat

Savat ma'lumotining hayoti:
- 78% savat 24 soat ichida tashlab yuboriladi
- 15% buyurtmaga aylanadi
- 7% 7 kundan ko'proq saqlanadi

## Ko'rib chiqilgan variantlar

### 1. MySQL da qoldirish, indekslarni optimallashtirish
- (+) Yangi infratuzilma kerak emas
- (-) Yozish yuki qoladi
- (-) Taxminiy foyda: 30-40%

### 2. Redis (tanlandi)
- (+) Yozish 5-10 ms
- (+) TTL bilan avtomatik tozalash
- (+) Sessiyalar uchun ham ishlatiladi
- (-) Yangi infratuzilma komponenti
- (-) Redis o'chsa savatlar yo'qoladi

### 3. Brauzer localStorage
- (+) Server yuki umuman yo'q
- (-) Qurilmalar orasida sinxronlashmaydi
- (-) Analitika uchun ma'lumot yo'qoladi

## Qaror

Savat ma'lumotini **Redis** da saqlaymiz.

- TTL: 30 kun
- Kalit formati: `savat:{mijoz_id}` yoki `savat:mehmon:{sessiya_id}`
- Buyurtma berilganda MySQL ga ko'chiriladi
- `SavatOmborInterfeysi` orqali - MySQL ga qaytish mumkin

## Oqibatlari

**Ijobiy:**
- Savat amallari 5-10 ms
- MySQL yozish yuki 40% kamayadi
- Eski savatlar avtomatik tozalanadi

**Salbiy:**
- Redis klasteri kerak (oyiga ~$40)
- Jamoa Redis ni o'rganishi kerak
- Redis o'chsa savatlar yo'qoladi - bu **qabul qilinadi**

**Kuzatiladigan xavflar:**
- Redis xotirasi to'lishi - monitoring qo'shildi
- Ma'lumot yo'qolishi - 5 daqiqada bir marta snapshot

## Qayta ko'rib chiqish

2026-11-01 da: qaror kutilgan natija berdimi?

# Ish daftarchasi: Yuqori xato darajasi

## Ogohlantirish
`YuqoriXatoDarajasi` - 5xx xatolar 5% dan yuqori

## Ta'siri
Foydalanuvchilar sahifa ocha olmaydi yoki buyurtma bera olmaydi.
**Jiddiylik:** kritik

## Birinchi qadamlar (5 daqiqa)

1. Grafana panelini oching: https://grafana.dokon.uz/d/asosiy
2. Qaysi endpoint xato berayotganini aniqlang
3. Xato boshlangan vaqtni toping

    # Oxirgi deploy vaqtini tekshiring
    kubectl rollout history deployment/ilova

## Tekshirish ro'yxati

### Deploy dan keyin boshlangan bo'lsa
    kubectl rollout undo deployment/ilova
Bu 30 soniyada oldingi versiyaga qaytaradi.

### Baza bilan bog'liq bo'lsa
    # Faol ulanishlar
    SHOW STATUS LIKE 'Threads_connected';

    # Sekin so'rovlar
    SHOW FULL PROCESSLIST;

    # Qulflar
    SELECT * FROM performance_schema.data_locks;

Sekin so'rov topilsa: `KILL <id>`

### Redis bilan bog'liq bo'lsa
    redis-cli INFO memory
    redis-cli INFO stats

Xotira to'lgan bo'lsa: `maxmemory-policy` ni tekshiring.

### Tashqi xizmat bilan bog'liq bo'lsa
    curl -w "%{time_total}\n" -o /dev/null -s https://api.tolov.uz/salomatlik

Javob bermasa: zanjir uzgich yoqilganini tekshiring, zaxira
rejimga o'ting.

## Eskalatsiya

30 daqiqada hal bo'lmasa:
1. @husanboy (texnik yetakchi) - +998 90 xxx-xx-xx
2. @aziz (infratuzilma) - +998 91 xxx-xx-xx

## Hodisadan keyin

- [ ] Hodisa hisobotini yozing
- [ ] Vaqt jadvalini to'ldiring
- [ ] Harakatlar ro'yxatini tuzing
- [ ] Ish daftarchasini yangilang

# O'zgarishlar jurnali

Ushbu fayl [Keep a Changelog](https://keepachangelog.com/) formatiga
amal qiladi va [SemVer](https://semver.org/) versiyalashni ishlatadi.

## [Chiqarilmagan]

### Qo'shildi
- Buyurtmani bekor qilish imkoniyati (#142)

## [2.3.0] - 2026-08-20

### Qo'shildi
- Mahsulotlarni Excel ga eksport qilish (#128)
- Kategoriya bo'yicha filtrlash (#131)

### O'zgartirildi
- Savat ma'lumoti Redis da saqlanadi - tezlik 10 barobar oshdi (#135)
- Katalog sahifasi 2.1s dan 0.4s ga tezlashdi

### Tuzatildi
- Bo'sh savatda buyurtma berishga urinilganda xato (#138)
- Narx yaxlitlashda tiyin yo'qolishi (#140)

### Xavfsizlik
- IDOR zaifligi: boshqa mijozning buyurtmasini ko'rish yopildi (#141)

### Eskirdi
- `/api/v1/products` - `/api/v1/mahsulotlar` ni ishlating.
  v1 2027-01-01 da o'chiriladi.

// Hujjatdagi misolni test bilan tekshirish
public function test_readme_dagi_misol_ishlaydi(): void
{
    // README.md dagi "Tez boshlash" bo'limidan
    $savat = new Savat();
    $savat->qoshing(mahsulotId: 1, narx: Pul::somdan(100_000), soni: 2);

    $this->assertEquals(200_000, $savat->jami()->som());
}

# Bilim xaritasi

| Soha | Asosiy | Zaxira | Hujjat |
|------|--------|--------|--------|
| Deploy jarayoni | @aziz | @husanboy | hujjatlar/deploy.md |
| To'lov integratsiyasi | @aziz | — | ❌ **XAVF** |
| Baza migratsiyalari | @husanboy | @jasur | hujjatlar/baza.md |
| Frontend qurish | @malika | @jasur | README.md |
| Monitoring | @aziz | @husanboy | hujjatlar/monitoring.md |

YOMON:
Ushbu modul foydalanuvchi tomonidan yuborilgan so'rovlarni qabul
qilish va ularni tegishli xizmatlarga yo'naltirish orqali tizimning
umumiy ishlashini ta'minlash uchun mo'ljallangan bo'lib, u turli
xil holatlarda turlicha xatti-harakat qilishi mumkin.

YAXSHI:
Bu modul so'rovlarni qabul qiladi va tegishli xizmatga yo'naltiradi.

Xatti-harakati so'rov turiga bog'liq:
- `GET` - keshdan javob beradi
- `POST` - navbatga qo'yadi
- Boshqalar - to'g'ridan-to'g'ri uzatadi

# Loyihani topshirish ro'yxati

## Kirish huquqlari
- [ ] Git repozitoriysi
- [ ] Ishlab chiqarish serveri (SSH)
- [ ] Baza (o'qish va yozish)
- [ ] Monitoring panellari
- [ ] Domen va DNS boshqaruvi
- [ ] SSL sertifikatlari
- [ ] Tashqi xizmatlar hisoblari (to'lov, SMS, email)
- [ ] Bulut provayderi

## Hujjatlar
- [ ] README - ishga tushirish
- [ ] Arxitektura ko'rigi
- [ ] Deploy jarayoni
- [ ] Ish daftarchalari
- [ ] ADR lar
- [ ] Texnik qarz reyestri
- [ ] Ma'lum muammolar ro'yxati

## Bilim uzatish
- [ ] Kod ko'rigi sessiyasi (2-4 soat)
- [ ] Deploy ni birgalikda bajarish
- [ ] Odatiy muammolarni ko'rib chiqish
- [ ] Savol-javob sessiyasi
- [ ] Bir hafta parallel ishlash

## Texnik
- [ ] Zaxira nusxa ishlayotgani tekshirildi
- [ ] Tiklash sinovdan o'tkazildi
- [ ] Monitoring ogohlantirishlari yangi jamoaga
- [ ] Sirlar almashtirildi
- [ ] Eski a'zolar huquqlari olib tashlandi