Capstone metodologiyasi: g'oyadan rejagacha — PRD, MVP, ERD va milestone'lar
Qisqacha: Capstone — kursda o'rganganlaringizni bitta haqiqiy mahsulotga yig'ish. U kod bilan emas, reja bilan boshlanadi: bir sahifali PRD (nima va kim uchun), user story va qabul mezonlari, MVP qamrovi (nimani kesamiz), ERD (ma'lumot modeli), repo tuzilmasi va milestone'lar. Bu qismning har darsi besh bosqichdan o'tadi: talab → qaror (ADR) → qurish → tekshirish → "o'zingiz qiling". Boshlashdan oldin
vazifalar-apini 4.5.0 ga yangilaymiz: ikkinchi API nusxasi uchun poydevor.
Bu darsda
- Capstone darslari qanday tuzilganini va kanon kodidan qanday foydalanishni bilasiz.
jamoauchun bir sahifali PRD yozasiz va user story'ni testga aylantirasiz.- MVP qamrovini ongli kesasiz va kesilganini hujjatga yozasiz.
- ERD, repo tuzilmasi, milestone va "tayyor" mezonini (DoD) tuzasiz.
vazifalar-apini 4.5.0 ga yangilaysiz: ko'p nusxada ishlaydigan Idempotency-Key, qulf ichidagi chegara va logga tushmaydigan OTP.
Oldin bilishingiz kerak: Mahsulot tafakkuri: talablarni tushunish, Estimatsiya va vazifani kichik qismlarga bo'lish, Arxitektura qarorlari: ADR va C4 diagrammalar, Design doc (RFC), runbook va postmortem yozish.
1. Nega bu kerak?
Ko'p o'quvchi kursni tugatib, portfolio'ga "todo ilova" va "ob-havo sayti" qo'yadi. Ishga oluvchi ularni ming marta ko'rgan. Bunday loyihani tutorial klon deyishadi: kimningdir videosini qadamma-qadam takrorlab yozilgan kod. U siz nimani bilishingizni emas, nimani ko'chira olishingizni ko'rsatadi.
Capstone boshqacha. Bu yerda hech kim "endi shu faylni oching" demaydi. Talabni o'zingiz yozasiz, qarorni o'zingiz qilasiz, xatoni o'zingiz topasiz. 37-qismgacha har darsda tayyor yo'l bor edi. Endi yo'lni siz chizasiz, kurs esa yonma-yon namuna beradi.
Hayotiy o'xshatish: to'y oshi. Uyda bir qozon osh pishirish uchun retsept yetadi. To'yga 300 kishilik osh esa rejadan boshlanadi: necha kilo guruch, qaysi qozon, kim sabzi to'g'raydi, soat nechada o't yoqiladi. Oshpaz bilimi o'sha, lekin reja bo'lmasa — mehmonlar xom osh yeydi. Capstone ham shunday: bilim 00–37-qismlarda, bu dars esa reja haqida.
2. Capstone qanday tuziladi
2.1 Qismdagi loyihalar
38-qismda ikkita majburiy va bir nechta ixtiyoriy loyiha bor:
| Loyiha | Darslar | Nima |
|---|---|---|
jamoa (majburiy) |
shu dars va keyingi to'rttasi | jamoalar uchun pullik vazifalar xizmati (SaaS) |
bozor (majburiy) |
e-commerce, bot, Mini App | mahalliy do'kon: katalog, savat, Click/Payme, Telegram |
| realtime (ixtiyoriy) | ikki dars | jamoa ichida chat, presence |
| mikroservis, kutubxona (ixtiyoriy) | ikki dars | xabarchi servisi, npm paket |
SaaS (Software as a Service, "xizmat sifatidagi dastur") — foydalanuvchi o'rnatmaydi, brauzerda ishlatadi va oyma-oy to'laydi. jamoa — vazifalar ipining davomi: bir kishilik ilova endi ko'p jamoaga xizmat qiladi. Uning dizayn hujjatini 36-qismda yozgansiz (C4, yetti ADR, RFC-0001). Endi o'sha hujjat kodga aylanadi.
2.2 Har darsning besh bosqichi
Capstone darslari bir xil qolipda yozilgan. Qolipni bir marta tushunsangiz, qolgan darslarni oson o'qiysiz:
flowchart LR
T["1. Talab<br/>user story, mezon"] --> A["2. Qaror<br/>ADR"]
A --> Q["3. Qurish<br/>kanon kodi"]
Q --> S["4. Tekshirish<br/>test, o'lchov"]
S --> O["5. O'zingiz<br/>o'z repo'ngizda"]
O -.->|"yangi talab"| TDiagrammadagi uzuq strelkaga qarang. "O'zingiz qiling" bosqichida yangi savol chiqadi va u keyingi talabga aylanadi. Bosqichlar:
- Talab — nima qilinadi va qanday tekshiriladi: user story va qabul mezonlari.
- Qaror — muqobillar va tanlov sababi, ADR shaklida. Kichik qaror — bir jadval qatori.
- Qurish — kanon kodining asosiy va qiyin joylari to'liq, oddiy joylari qisqa.
- Tekshirish — testlar va o'lchovlar, xom natija bilan. Kutilganidan boshqacha chiqsa, ochiq aytiladi.
- O'zingiz qiling — o'z repo'ngizda qurasiz. Kanon — namuna va yechim.
2.3 Kanon — namuna, ko'chirma emas
Kursdagi har capstone avval biz tomonimizdan to'liq qurildi va sinaldi. Bu — kanon tajribasi (IlmHamroh, 2026-11): Windows 11, Node 24.21.0, PostgreSQL 18, Redis, S3-mos ombor. Darsdagi har raqam o'sha tajribaning xom chiqishidan olingan.
Lekin darsda hamma kod berilmaydi. Nega? Agar 2 000 qator kodni ko'chirsangiz, yana tutorial klon chiqadi. Shuning uchun:
- To'liq beriladi: arxitektura qarorlari, qiyin joylar (qulf, imzo, holat mashinasi) va kanon topgan xatolar.
- Vazifa sifatida beriladi: oddiy CRUD, marshrutlar, shakllar. Ularni 25–30-qismlarda ko'p yozgansiz.
- Yechim — "O'zingiz qiling" bo'limidagi yashirin bloklarda. Avval o'zingiz yozing, keyin solishtiring.
Tekshirib ko'ring: Capstone darsida nega CRUD marshrutlarining to'liq kodi berilmaydi, holat mashinasi esa to'liq beriladi?
Javob
CRUD marshrutini siz 25-qismdan beri o'nlab marta yozgansiz — uni ko'chirish yangi narsa o'rgatmaydi. Holat mashinasi va qulf esa xato qilish oson bo'lgan joylar: bitta noto'g'ri tartib — ikki marta yechilgan pul yoki chegaradan oshgan ro'yxat. Qiyin joyni namunadan o'rganish arzon, o'zingiz topish esa qimmat. Shuning uchun kanon qiyin joylarga urg'u beradi.
3. G'oyadan bir sahifali PRD'ga
3.1 PRD va RFC farqi
PRD (product requirements document, mahsulot talablari hujjati) — mahsulot nima qiladi va kim uchun degan savolga javob. RFC esa (Design doc (RFC) darsida yozgansiz) — tizim qanday quriladi. Ikkalasini aralashtirish keng tarqalgan xato.
| PRD | RFC | |
|---|---|---|
| Savol | nima va nega | qanday |
| O'quvchi | egasi, sotuvchi, dizayner | dasturchilar |
| Ichida | muammo, foydalanuvchi, metrika, qamrov | arxitektura, muqobillar, xavflar |
| Kod nomlari | yo'q | bor |
Bitta kishilik loyihada ham ikkalasi kerak. PRD sizni "keraksiz funksiya"dan himoya qiladi. RFC esa "noto'g'ri arxitektura"dan.
3.2 jamoa PRD'si — bir sahifa
Kattasi kerak emas. Bir sahifa — o'qiladigan hujjat. Mana jamoa uchun, RFC-0001 ning birinchi ikki bo'limidan yig'ilgan:
| Bo'lim | Mazmun |
|---|---|
| Muammo | 3–15 kishilik jamoalar (o'quv markazi, kichik agentlik, do'kon) umumiy vazifa ro'yxati, tayinlash va eslatma so'raydi; xorijiy xizmatlar dollarda, o'zbek tilisiz, mahalliy to'lovsiz |
| Foydalanuvchilar | jamoa egasi (to'laydi, taklif qiladi), a'zo (vazifa bilan ishlaydi) |
| Muvaffaqiyat | taklifdan kirishgacha ≤ 2 daqiqa; to'lovdan keyin obuna ≤ 10 s da faol |
| Maqsad emas | real-time hamkorlikdagi tahrir, mobil ilova, SSO, ko'p valyuta |
Oxirgi qatorga e'tibor bering. Maqsad emas ro'yxati PRD'ning eng foydali qismi. U keyingi bahslarni yopadi: kimdir "mobil ilova ham qilaylik" desa, javob yozib qo'yilgan.
3.3 User story'dan testgacha
User story va qabul mezonlarini Mahsulot tafakkuri darsida o'rgangansiz. Capstone'da ular bir qadam davom etadi: har mezon — bitta test qatori. Taklif oqimidan misol:
Jamoa egasi sifatida men hamkasbimni email orqali taklif qilmoqchiman, toki u parolini menga aytmasdan jamoaga qo'shilsin.
Qabul mezonlari (Berilgan / Qachonki / Unda) va kanon testidagi mos qator:
| Mezon | Kanon testida |
|---|---|
| Taklif havolasi boshqa odamga o'tib ketsa, u qo'shila olmaydi | boshqa email bilan qabul — 404 |
| Havola bir marta ishlaydi | ikkinchi qabul — 404 |
| Oddiy a'zo taklif yubora olmaydi | a'zo taklifi — 403 |
| Taklif 7 kundan keyin eskiradi | muddat > now() sharti |
Birinchi uchta qator — test/jamoa.test.ts dagi haqiqiy tekshiruvlar, ular yashil o'tdi. To'rtinchisi esa faqat SQL shartida bor, alohida testi yo'q. Bu — halol bo'shliq, uni keyingi darsning "O'zingiz qiling" bo'limida yopasiz.
Qoida oddiy: testga aylanmagan mezon — istak. U bir kun jim buziladi va hech kim sezmaydi.
Tekshirib ko'ring: "Taklif tez ishlasin" — qabul mezonimi?
Javob
Yo'q, uni tekshirib bo'lmaydi: "tez" — necha soniya? PRD'dagi o'lchov — "taklifdan kirishgacha ≤ 2 daqiqa". Bu foydalanuvchi vaqti, server tezligi emas. Uni qo'lda sinov bilan o'lchash mumkin. Server tomonida esa RFC'dagi SLO bor: yozish p99 < 500 ms. Mezon raqam bilan yozilgandagina testga aylanadi.
4. MVP qamrovi: nimani kesamiz
4.1 Kanon nimani kesdi
MVP'ni Mahsulot tafakkuri darsida MoSCoW bilan ajratgansiz. Capstone'da savol aniqroq: "Bir kishi to'rt haftada nimani yaxshi qila oladi?" Kanon jamoa da quyidagilarni ongli ravishda kesdi:
| Kesildi | Nega | Qachon qaytadi |
|---|---|---|
| Google, Telegram bilan kirish, TOTP | vazifalar-api da bor; MVP'ga email + parol yetadi |
birinchi mijoz so'rasa |
| Taklif xatini yuborish | token javobda (faqat dev), production'da xat adapteri kerak | production'dan oldin |
jamoalar jadvalida RLS |
ruxsat kodda (rol()), ma'lumot jadvallarida RLS bor |
tashqi API paydo bo'lsa |
| Grafik veb-interfeys | kirish, jamoalar, vazifalar, chat — MVP | foydalanuvchi fikridan keyin |
Ikkinchi qator muhim. Production'da taklif xati ketmasa, mahsulot ishlamaydi. Demak bu "Won't" emas, "keyingi milestone'dagi Must". Kesish — rad etish emas, navbatga qo'yish.
4.2 Kesilgani ham hujjatda
Kanon README'sida alohida "Halol chegaralar" bo'limi bor. Unda kesilgan hamma narsa yozilgan: haqiqiy Payme/Click sandbox sinalmagan, kartadan avtomatik yechish yo'q, xat hozircha faqat logga yoziladi. Nega bu muhim? Uch oydan keyin siz ham, ishga oluvchi ham README'ni o'qiydi. Yozilmagan chegara — "unutilgan xato" bo'lib ko'rinadi. Yozilgani esa — "o'ylangan qaror".
5. ERD: avval ma'lumot modeli
5.1 Jadvallar va bog'lanishlar
ERD (entity-relationship diagram, mohiyat-bog'lanish diagrammasi) — jadvallar va ular orasidagi bog'lanishlar rasmi. Capstone'da ERD koddan oldin chiziladi. Sabab: marshrutni ertaga o'zgartirish arzon, jadvalni esa ma'lumot to'lgandan keyin o'zgartirish qimmat (Zero-downtime: expand-contract).
jamoa ning asosiy jadvallari (kanon sql/001-jamoa.sql va 002-tolov.sql dan):
erDiagram
foydalanuvchilar ||--o{ sessiyalar : "kiradi"
foydalanuvchilar ||--o{ azoliklar : "a'zo"
jamoalar ||--o{ azoliklar : "a'zolari"
jamoalar ||--o{ takliflar : "taklif"
jamoalar ||--o{ vazifalar : "ichida"
azoliklar |o--o{ vazifalar : "tayinlangan"
vazifalar |o--o{ fayllar : "ilova"
jamoalar ||--|| obunalar : "obuna"
jamoalar ||--o{ hisob_fakturalar : "faktura"Belgilarni shunday o'qing: || — "aynan bitta", o{ — "nol yoki ko'p", |o — "nol yoki bitta". Masalan, jamoalar ||--|| obunalar — har jamoaning aynan bitta obunasi bor.
5.2 Uch qaror jadvalning o'zida
Yaxshi sxema biznes qoidasini bazaga yozadi. Kod xato qilsa ham, baza rad etadi. jamoa da uchta shunday joy bor:
- Bitta egasi.
azoliklarda qisman noyob indeks:UNIQUE (jamoa_id) WHERE rol = 'egasi'. Ikkinchi egasini qo'shishga uringan har qanday kod xato oladi. - Faqat a'zoga tayinlash.
vazifalar (jamoa_id, tayinlangan_id)→azoliklarga kompozit tashqi kalit. Boshqa jamoa a'zosiga vazifa tayinlab bo'lmaydi. A'zo chiqarilsa, tayinlov o'zi bo'shaydi (ON DELETE SET NULL). - Ichki va tashqi id. Jadval kaliti —
bigint, havolalarda esaommaviy_id uuid DEFAULT uuidv7(). Bu 36-qismdagi ADR-0006 qarori (Vaqt, tartib, ID va kelishuv).
Tekshirib ko'ring: Nega "bitta egasi" qoidasini faqat kodda (
if (egasiBormi) throw) tekshirish yetmaydi?
Javob
Ikki parallel so'rov ikkalasi ham "egasi yo'q" deb o'qib, ikkalasi ham yozishi mumkin — bu poyga holati (Biznes mantiq zaifliklari). Noyob indeks esa bazaning o'zida, tranzaksiyalar qanday kesishmasin, ikkinchisini rad etadi. Kod tekshiruvi foydalanuvchiga chiroyli xato matni uchun kerak, kafolat esa indeksda.
6. Repo tuzilmasi va nima ko'chiriladi
6.1 Papkalar
jamoa — bitta repo, ichida ikki ilova (Git va monorepo):
| Papka | Nima |
|---|---|
api/ |
NestJS 12, modular monolit: auth, jamoalar, billing, chat, fayllar, ishchi.ts; sql/ — sxema |
web/ |
React 19 + Vite 8 SPA; e2e/ — Playwright |
deploy/ |
nginx sozlamasi, migratsiya va zaxira skriptlari |
docs/adr/ |
36-qismdagi 0001–0007 va yangi 0008–0010 |
Stek ham qaror, u ADR-0010 da yozilgan: NestJS va pg (Prisma'siz). Sabab — RLS bilan har so'rov tranzaksiya va kontekst talab qiladi. vazifalar-api da Prisma va RLS ikki xil yo'l edi, jamoa da bitta yo'l soddaroq. Narxi: SQL natijasining tiplari qo'lda yoziladi, xato xavfini testlar yopadi.
6.2 Ko'chirish qoidasi
vazifalar-api da yuzlab sinalgan fayl bor. Hammasini ko'chirish vasvasali. Kanon qoidasi: o'zgartirmasdan ishlaydigan va sinalgan narsa ko'chiriladi, qolgani — g'oya sifatida qayta yoziladi.
| Ko'chirildi (kod) | Sabab |
|---|---|
auth/parol.ts (argon2id) |
28-qismda o'lchangan parametrlar |
umumiy/xatolar.ts, problem.ts, tekshir.ts |
Problem Details va Zod — butun kurs shartnomasi |
29-qismdagi tolov/ (Payme, Click, ledger, obuna) |
imzo, holat mashinasi, idempotentlik sinalgan |
| G'oya sifatida | RLS yordamchisi, CSRF, SSE, BullMQ ulanishi — jamoa_id ga moslab qayta yozildi |
Ataylab ko'chirilmaganlar ham yozilgan: Prisma, OIDC, Telegram kirish, TOTP, AI. Har biri uchun sabab bor. Bu jadval sizning README'ingizda ham bo'lsin — ishga oluvchi "qaysi kodni o'zi yozgan?" deb so'raydi.
7. Milestone, issue va "tayyor" mezoni
7.1 To'rt milestone
Milestone (bosqich) — tugaganda demo qilsa bo'ladigan ish to'plami. RFC-0001 dagi reja to'rtta bir haftalik bosqich:
- Jamoa, a'zolik, rollar, taklif — SaaS capstone 1.
- Vazifalar jamoa kontekstida, fayllar, fon ishlar — SaaS capstone 2.
- Obuna va billing — SaaS capstone 3.
- Production: deploy, kuzatuv, zaxira, audit — SaaS capstone 4.
Har bosqich oxirida ikki narsa: demo (brauzerda yoki curl bilan) va ADR yangilanishi. Bosqich ichidagi ishlar — issue'lar. Ularni Estimatsiya va vazifani kichik qismlarga bo'lish darsidagidek vertikal bo'laklang: bitta issue — bitta foydalanuvchi ko'radigan natija.
7.2 "Tayyor" — so'z emas, ro'yxat
"Tayyor" so'zi har kimda har xil. Shuning uchun tayyorlik ta'rifi (Definition of Done, DoD) yoziladi. Kanonda 2-bosqich (jamoa) shu ro'yxat bilan qabul qilindi:
| Tekshiruv | Natija |
|---|---|
npm run check (tip, lint, test, build) |
11/11 test |
| web build va Playwright e2e | 1/1 (ro'yxat → jamoa → vazifa → chat) |
| production Compose lokal | 50 SSE × 20 xabar — 1 000/1 000 yetkazildi |
CI fayli lokal act bilan |
api va web — yashil |
Sizning DoD'ingiz kichikroq bo'lishi mumkin. Lekin u yozilgan bo'lsin va har milestone shu ro'yxatdan o'tsin. 2-mashqda DoD tekshiruvchisini o'zingiz yozasiz.
8. Loyiha yangilandi: vazifalar-api 4.5.0
8.1 Nega capstone'dan oldin
jamoa ning ADR-0001 qarori: nginx ortida ikki API nusxasi, ular stateless — ya'ni hech biri so'rovlar orasida o'z xotirasida muhim holat saqlamaydi. Qaysi nusxaga tushsangiz ham, javob bir xil bo'lishi kerak. Masshtablash: vertikal, gorizontal va stateless darsida esa vazifalar-api da to'rtta joy topilgan edi: holat jarayon xotirasida yashaydi. Ikkinchi nusxa paydo bo'lsa, ular buziladi. 36-qism oxirida ular "ikkinchi nusxadan oldin majburiy" ishlar ro'yxatiga yozildi.
Demak, capstone'ning birinchi ishi — poydevor. Bu kichik "talab → qaror → qurish → tekshirish" sikli, butun qismning namunasi.
8.2 Avval eski kodda yiqilsin
Har tuzatishdan oldin regressiya testi yozildi: test/kop-nusxa.test.ts, 13 ta test. Ular faqat xulqqa tayanadi — ikki nusxani ishga tushirib, birida so'rov yuboradi, boshqasida tekshiradi. Natija 36-qism kodida: Tests 13 failed (13). Bir nechta yiqilish xabari, xom chiqishdan:
AssertionError: Expected values to be strictly equal:
409 !== 201Tarjimasi: "Qiymatlar qat'iy teng bo'lishi kutilgan edi: 409 201 ga teng emas". Test B nusxaga qayta yuborilgan so'rovdan 201 kutgan, 409 olgan. Yana biri — cron testi, sakkiz nusxadan yettitasi bitta xatoni bergan:
'error: relation "vazifa_hodisalari_2027_01" already exists',Tarjimasi: "xato: vazifa_hodisalari_2027_01 jadvali allaqachon bor". Har nusxa bir vaqtda keyingi oy bo'limini yaratishga uringan. 4.5.0 da o'sha fayl: Tests 13 passed (13).
8.3 Ko'p nusxa o'lchovi
Keyin jonli o'lchov: ikki nusxa, nginx round-robin (navbat bilan), 100 operatsiya. Har operatsiya — POST va darhol o'sha Idempotency-Key bilan qayta yuborish (Idempotency-Key):
| 4.4.0 | 4.5.0 | |
|---|---|---|
| qayta yuborish javobi | 409 × 100 | 201 × 100, Idempotency-Replayed × 100 |
| bazadagi vazifalar | 100 | 100 |
| chegara: 995 bor + 20 parallel | 1015 | 1000 (201 × 5, 409 × 15) |
| servis imzosi takrori boshqa nusxada | 200, 200 | 200, 401 |
Sabab — XotiraIdempotentlikOmbori. Kalit jarayon xotirasidagi Map da edi. Birinchi so'rov A nusxaga tushdi, qayta yuborilgani — B ga. B kalitni bilmaydi. Mana shuning modeli:
// 2 api nusxasi, nginx navbat bilan: 1-so'rov A ga, 2-si B ga
function sina(umumiyOmbor, unique = true) {
const baza = []; // vazifalar.matn
const umumiy = new Map(); // Postgres jadvali (4.5.0)
const xotira = [new Map(), new Map()]; // har nusxa o'zida (4.4.0)
let navbat = 0;
const hisob = {};
function post(kalit, matn) {
const ombor = umumiyOmbor ? umumiy : xotira[navbat++ % 2];
if (ombor.has(kalit)) return `${ombor.get(kalit)}+Replayed`;
let holat = 201;
if (unique && baza.includes(matn)) holat = 409; // takror matn
else baza.push(matn);
ombor.set(kalit, holat);
return String(holat);
}
for (let i = 1; i <= 100; i++) {
post(`kalit-${i}`, `vazifa ${i}`); // birinchi yuborish
const javob = post(`kalit-${i}`, `vazifa ${i}`); // qayta
hisob[javob] = (hisob[javob] ?? 0) + 1;
}
return `qayta ${JSON.stringify(hisob)}, bazada ${baza.length}`;
}
console.log("4.4.0:", sina(false));
console.log("4.5.0:", sina(true));
console.log("UNIQUE'siz:", sina(false, false));Konsolda:
4.4.0: qayta {"409":100}, bazada 100
4.5.0: qayta {"201+Replayed":100}, bazada 100
UNIQUE'siz: qayta {"201":100}, bazada 200Birinchi ikki qator kanon o'lchovi bilan aynan. Uchinchisi — 36-qismda kutilgan holat, unga keyingi bo'limda qaytamiz.
Tuzatish — PgIdempotentlikOmbori: kalit endi Postgres jadvalida (idempotentlik_kalitlari), hamma nusxa uchun umumiy. Atomiklik ("yo to'liq bo'ladi, yo umuman bo'lmaydi") birlamchi kalitdan keladi: bir kalitli ikkinchi qatorni baza o'zi yozdirmaydi. Bitta buyruq ham yangi yozuv qo'yadi, ham muddati o'tganini almashtiradi:
INSERT INTO idempotentlik_kalitlari AS k (kalit, izi, tugash)
VALUES ($1, $2,
now() + make_interval(secs => $3::double precision / 1000))
ON CONFLICT (kalit) DO UPDATE
SET izi = EXCLUDED.izi, javob = NULL, tugash = EXCLUDED.tugash
WHERE k.tugash <= now()
RETURNING 1Kanonda bu so'rov bitta TS satri ichida, bu yerda qatorlarga bo'ldik. RETURNING qator qaytarsa — shu chaqiruv birinchi, so'rov bajariladi. Qaytarmasa — boshqa nusxa allaqachon boshlagan, mavjud yozuv o'qiladi:
const [y] = (await this.#pool.query(
"SELECT izi, javob FROM … WHERE kalit = $1", [kalit])).rows;
if (y === undefined) return { tur: "jarayonda" };
if (y.izi !== izi) return { tur: "boshqa-tana" };
if (y.javob === null) return { tur: "jarayonda" };
return { tur: "tayyor", izi: y.izi, javob: y.javob };Bu boshla() metodidan bo'lak, tiplar va jadval nomi qisqartirildi. Natija to'rt xil: yangi (shu chaqiruv bajaradi), jarayonda (boshqa nusxa hali ishlayapti), boshqa-tana (bir kalit bilan boshqa tana — mijoz xatosi) va tayyor (saqlangan javob qaytadi). Bu — 25-qismdagi IdempotentlikOmbori interfeysining o'sha shartnomasi. Middleware o'zgarmadi, faqat ombor almashdi: port qarorining yana bir foydasi.
PostgreSQL hujjati bu xulqni aniq yozadi: RETURNING faqat haqiqatan qo'shilgan yoki yangilangan qatorlarni qaytaradi. ON CONFLICT DO UPDATE … WHERE sharti bajarilmasa, qator qulflanadi, lekin qaytarilmaydi. Kanon aynan shunga tayanadi: "qator qaytdimi?" savoli "men birinchimanmi?" savolining javobi.
Tekshirib ko'ring: Bir mijoz bir kalit bilan so'rovni ikki marta yubordi. Birinchisi hali tugamagan (javob saqlanmagan). Ikkinchi so'rov qaysi natijani oladi va nega u vazifani qayta yaratmaydi?
Javob
jarayonda. Kalit qatori allaqachon bor va muddati o'tmagan, shuning uchun WHERE k.tugash <= now() bajarilmaydi va RETURNING bo'sh qaytadi. Keyin SELECT qatorni topadi: izi mos, javob esa hali NULL. Ikkinchi so'rov ishni boshlamaydi — u "kuting yoki keyinroq qayta urining" javobini oladi. Vazifa bir marta yaratiladi, chunki bajarishga ruxsatni faqat RETURNING qator qaytargan birinchi chaqiruv oladi.
8.4 Biz shunday xato qildik: kutilgan zarar boshqacha chiqdi
Idempotentlik va timeout budjeti darsida biz modelda hisoblagan edik: uch nusxa, 100 qayta yuborish — 100 ortiqcha vazifa. Mantiq to'g'ri edi: B nusxa kalitni bilmaydi, demak yana bitta vazifa yaratadi.
Haqiqiy o'lchov boshqacha chiqdi: ortiqcha vazifa — 0. Sabab — kanonda yana bir himoya bor edi: vazifalar.matn ustidagi UNIQUE (takror matn, 26-qism). B nusxa vazifa yaratishga urindi, baza takror matnni rad etdi, mijoz 409 oldi.
Zarar yo'qolmadi, shakli o'zgardi. Mijoz o'z so'rovini to'g'ri yuborgan, vazifa yaratilgan — lekin ekranda "Bu vazifa ro'yxatda allaqachon bor" degan xato ko'rdi. Mobil ilova bunday 409 dan keyin "saqlanmadi" deb ko'rsatishi mumkin. Foydalanuvchi qayta urinadi — yana 409.
Saboq ikkita. Birinchisi: model — gipoteza, o'lchov uni tasdiqlaydi yoki rad etadi. Ikkinchisi: zarar har doim ham "ortiqcha yozuv" emas. Ba'zan u — halol mijozga noto'g'ri javob. Modeldagi "UNIQUE'siz" qatori aynan 36-qismdagi farazni beradi: bazada 200.
8.5 OTP kodi logda: yopiq yiqilish
Ikkinchi topilma xavfsizlikka oid. 36-qism kodini o'qib topildi va 4.5.0 da regressiya testi bilan isbotlandi. ESKIZ_* o'zgaruvchilari berilmasa, ilova SMS o'rniga LogSms ni tanlardi (SMS provayderlar: Eskiz va PlayMobile). Dasturchi kompyuterida bu qulay: kod konsolda ko'rinadi. Production'da esa bir martalik kirish kodi info darajasida logga tushardi — Loki'ga, Sentry'ga, kim logni o'qisa — o'shaga.
Tuzatish ikki qatlamli. Birinchisi — config.ts dagi Zod qoidasi, SMTP qoidasi yonida (Fail-open va fail-closed):
.refine((e) => (e.VAPID_OCHIQ === undefined) === …
+ .refine(
+ (e) => e.NODE_ENV !== "production"
+ || e.ESKIZ_URL !== undefined,
+ { error: "production'da ESKIZ_URL (SMS provayder) majburiy: …",
+ path: ["ESKIZ_URL"] })Kanonda qoida bitta satr, bu yerda qatorga bo'lindi va xabar qisqartirildi. Ikkinchisi — umumiy/log.ts dagi yashiriladigan maydonlar ro'yxati:
"*.parol",
"*.token",
+ "*.kod",
+ "*.*.kod",
];Endi kod maydoni har qanday logda [Redacted] bo'ladi, hatto dev rejimida ham. Narxi — buzuvchi o'zgarish (BREAKING): SMS provayderisiz production deploy endi ishga tushmaydi. Shuning uchun versiya CHANGELOG'da "BREAKING CHANGES" bo'limida. Muqobil — OTP_YOQ kabi bayroq: SMS kirishni ongli o'chirish. Kanonda u yo'q. Kerak bo'lsa, sukut emas, aniq qaror sifatida qo'shiladi.
8.6 Qolgan tuzatishlar
| Tuzatish | Eski → yangi |
|---|---|
eksport ishlari bazada (eksport_ishlari) |
boshqa nusxada 404 → 200 |
cron: pg_try_advisory_xact_lock |
8 parallel: 7 × already exists → 0 |
MAKS_VAZIFA ombor ichida, egasi qulfi bilan |
995 + 20 → 1015 → 1000 |
servis imzosi nonce — bir_martalik_kalitlar |
takror B da 200 → 401 |
muddat ombor orqali |
ro'yxat versiyasi oshmasdi → +1 |
outbox'da sorov_id |
null → X-Request-Id |
| MFA har birinchi omildan keyin | to'liq — SaaS capstone 1 |
/v1/auth/men 405 Allow |
DELETE qo'shildi |
Yana ikki tozalash. O'lik kod: ZaxiraliSms, PlayMobileProvayder va cheklov() olib tashlandi — chaqiruvchisi nol edi. 36-qismda ularni naqsh misoli sifatida ko'rgan edik. Endi YAGNI (Asosiy tamoyillar) amalda: ishlatilmagan kod — o'qiladigan, lekin hech narsa bermaydigan kod. Nomlash: fallback ma'nosidagi "zaxira" endi "ehtiyot" (EhtiyotliProvayder, AI_EHTIYOT_MODEL). Kursda "zaxira" faqat backup ma'nosida. Eski AI_ZAXIRA_MODEL berilsa — aniq xato, jim e'tiborsizlik emas.
MAKS_VAZIFA poygasi 35-qismdagi webhook limiti xatosining aynan takrori (Biznes mantiq zaifliklari). Sanash xizmatda, yozish omborda edi — orasida boshqa so'rovlar yozib ulgurardi. 3-mashqda uni modelda o'zingiz qayta hosil qilasiz.
8.7 Tekshiruv va commit
Sxema: sql/308-kop-nusxa.sql (Prisma migratsiyasi bilan aynan) — uchta jadval va outbox.sorov_id. To'liq tekshiruv: tip 0, lint 0, build 0; Vitest — 383 test o'tdi, 1 o'tkazib yuborildi; e2e 10/10. Birinchi urinishda lint ikki xato bergan, prisma generate esa unutilgan edi — tuzatib, qayta yurgizildi. Versiya — 4.5.0 (yangi imkoniyat bor, buzuvchi o'zgarishlar CHANGELOG'da alohida). Commit xabari:
feat(kop-nusxa): Idempotency-Key, eksport, nonce — Postgres'da; fix: MAKS_VAZIFA qulf ichida, muddat ombor orqali, cron advisory lock, MFA har omildan keyin, OTP logda emas, 405 Allow; refactor: o'lik kod, ehtiyot nomlash9. Ko'p uchraydigan xatolar
9.1 Koddan boshlash
Birinchi kuni nest new — ikkinchi haftada "jadvalni qayta qilaman". ERD va PRD bir kun oladi, ularsiz qayta yozish — bir hafta.
9.2 Hamma narsa MVP
"Google bilan kirish ham, mobil ilova ham, AI ham" — to'rt hafta o'rniga to'rt oy, oxiri yo'q. MVP'ning har qatori uchun so'rang: "Busiz birinchi mijoz to'laydimi?"
9.3 Kesilganini yozmaslik
Kesilgan funksiya README'da bo'lmasa — u "unutilgan xato" bo'lib ko'rinadi. "Halol chegaralar" bo'limi bitta abzats, foydasi katta.
9.4 "Tayyor" ni his bilan aniqlash
"Ishlayapti-ku" — DoD emas. Test, review, hujjat — ro'yxat bo'lmasa, milestone hech qachon to'liq yopilmaydi.
9.5 Modelga ko'r-ko'rona ishonish
36-qism modeli "100 ortiqcha vazifa" degan edi, o'lchov — 0 ortiqcha, lekin 100 ta noto'g'ri 409. O'lchamagan raqamni README'ga yozmang.
10. Mashqlar
Mashqlar kurs/mashqlar/38/01-capstone-metod/ da. 2- va 3-mashq yechimlari Node 24.21.0 da tekshirilgan (biz ishga tushirdik).
1-mashq (oson): bo'shliqlarni to'ldiring
- Mahsulot nima va kim uchun degan savolga javob beradigan hujjat —
- Har jamoada aynan bitta egasi bo'lishini kafolatlaydigan narsa — qisman noyob
- Milestone tugadi deyish uchun yozilgan ro'yxat — tayyorlik ta'rifi, qisqasi
- 4.4.0 da B nusxaga qayta yuborilgan so'rov javobi —
- 995 ta vazifa va 20 parallel so'rovdan keyin 4.5.0 da bazada — ta vazifa
Yechim
- PRD — RFC esa "qanday quriladi" haqida.
- indeks —
UNIQUE (jamoa_id) WHERE rol = 'egasi'; kod poygasida ham ishlaydi. - DoD — Definition of Done; kanonda tip, lint, test, build, e2e, CI.
- 409 — B nusxa kalitni bilmasdi, baza takror matnni rad etdi.
- 1000 — chegara egasi qulfi ichida tekshiriladi: 5 ta 201, 15 ta 409.
2-mashq (o'rta): milestone hisoboti
Har issue'da bajarildi — DoD'dan bajarilgan bandlar ro'yxati. hisobot(issuelar, milestone) funksiyasini yozing. U shu milestone'dagi tayyor issue'lar sonini, foizini va qolganlari uchun nima yetishmasligini qaytarsin. Tayyor — DoD'ning hamma bandi bajarilgan.
const DOD = ["test", "review", "hujjat"];
const issuelar = [
{ nom: "jamoa ochish", milestone: "M1", bajarildi: DOD },
{ nom: "taklif oqimi", milestone: "M1", bajarildi: ["test"] },
{ nom: "rollar", milestone: "M1", bajarildi: ["test", "review"] },
{ nom: "vazifa CRUD", milestone: "M2", bajarildi: [] },
];Ishora: filter va every bilan "hamma band bajarilgan"ni tekshiring (filter: shart bo'yicha tanlash). Foizni Math.round bilan yaxlitlang.
Yechim
const DOD = ["test", "review", "hujjat"];
const issuelar = [
{ nom: "jamoa ochish", milestone: "M1", bajarildi: DOD },
{ nom: "taklif oqimi", milestone: "M1", bajarildi: ["test"] },
{ nom: "rollar", milestone: "M1", bajarildi: ["test", "review"] },
{ nom: "vazifa CRUD", milestone: "M2", bajarildi: [] },
];
function hisobot(royxat, milestone) {
const bu = royxat.filter((i) => i.milestone === milestone);
const tayyor = bu.filter((i) =>
DOD.every((shart) => i.bajarildi.includes(shart)));
const qoldi = bu.filter((i) => !tayyor.includes(i))
.map((i) => {
const yoq = DOD.filter((s) => !i.bajarildi.includes(s));
return `${i.nom} (${yoq.join(", ")})`;
});
const foiz = Math.round(tayyor.length / bu.length * 100);
return `${milestone}: ${tayyor.length}/${bu.length} (${foiz}%)` +
(qoldi.length ? ` — qoldi: ${qoldi.join("; ")}` : "");
}
console.log(hisobot(issuelar, "M1"));
console.log(hisobot(issuelar, "M2"));Konsolda:
M1: 1/3 (33%) — qoldi: taklif oqimi (review, hujjat); rollar (hujjat)
M2: 0/1 (0%) — qoldi: vazifa CRUD (test, review, hujjat)"Rollar" deyarli tayyor, lekin hujjatsiz — demak tayyor emas. Hisobot "nima yetishmaydi"ni aniq aytadi: haftalik demo oldidan nimani tugatish kerakligi ko'rinadi. Foiz esa faqat ko'rsatkich. Milestone 100 % bo'lmaguncha "yopildi" deyilmaydi.
3-mashq (qiyin): chegara poygasi
Eski versiyadagi MAKS_VAZIFA xatosini (4.4.0) modelda qayta hosil qiling. Bazada 995 ta vazifa, chegara 1000. yarat() avval sonni o'qiydi, keyin "tarmoq" kutadi (setTimeout(…, 0)), keyin chegarani tekshirib yozadi. 20 ta parallel yarat() ni qulfsiz va qulf bilan ishga tushiring. Qulf — oddiy navbat: har keyingi ish oldingisi tugagach boshlanadi.
Ishora: navbatni Promise zanjiri bilan quring — oxirgi = oxirgi.then(ish) (Promise zanjiri). Parallel ishga tushirish — Promise.all (Promise kombinatorlari).
Yechim
const MAKS = 1000;
const kut = () => new Promise((r) => setTimeout(r, 0)); // "tarmoq"
function qulfYasa() {
let oxirgi = Promise.resolve();
return (ish) => {
const natija = oxirgi.then(ish);
oxirgi = natija.catch(() => {});
return natija;
};
}
async function sina(qulfBilan) {
const baza = { soni: 995 };
const qulf = qulfYasa();
async function yarat() {
const n = baza.soni; // SELECT count(*)
await kut(); // so'rovlar orasida boshqalar ishlaydi
if (n >= MAKS) return 409;
baza.soni++; // INSERT
return 201;
}
const bitta = qulfBilan ? () => qulf(yarat) : yarat;
const javoblar = await Promise.all(
Array.from({ length: 20 }, bitta));
const n201 = javoblar.filter((h) => h === 201).length;
return `201 × ${n201}, 409 × ${20 - n201}, bazada ${baza.soni}`;
}
console.log("qulfsiz:", await sina(false));
console.log("qulf bilan:", await sina(true));Konsolda:
qulfsiz: 201 × 20, 409 × 0, bazada 1015
qulf bilan: 201 × 5, 409 × 15, bazada 1000Ikkala qator kanon o'lchovi bilan aynan: 4.4.0 da 1015, 4.5.0 da 1000 (5 × 201, 15 × 409). Qulfsizda yigirmata so'rov ham 995 ni o'qiydi — hammasi "joy bor" deb hisoblaydi. Qulf bilan sanash va yozish bitta navbatda: oltinchisi 1000 ni ko'radi. Kanonda navbat vazifasini egasi qatoridagi FOR UPDATE qulfi bajaradi (Qulflar: row, table va advisory). oxirgi = natija.catch(…) — bitta ish yiqilsa ham navbat to'xtamasligi uchun.
11. O'zingiz qiling: reja hujjatlari
Bu darsning "o'zingiz qiling" topshirig'i — kod emas, reja. jamoa repo'sini oching (36-qismda docs/ papkasi bilan boshlagan edingiz) va quyidagilarni qo'shing:
docs/PRD.md— bir sahifa: muammo, foydalanuvchilar, muvaffaqiyat metrikasi, maqsad emas.docs/talablar.md— 5–8 ta user story, har biriga 2–4 qabul mezoni. Har mezon yonida — qaysi test uni tekshirishi.- README'da "Halol chegaralar" va "Ko'chirilgan kod" jadvallari.
docs/erd.md— mermaiderDiagram, kamida 6 jadval. Har biznes qoidasi uchun: u bazada qanday kafolatlanadi (CHECK, UNIQUE, FK) yoki nega faqat kodda.- Milestone'lar va DoD — GitHub'da milestone va issue'lar (Kanban, vazifa trekerlari va ish oqimi).
vazifalar-apini 4.5.0 ga yangilang: avval 13 testli regressiya fayli (eski kodda yiqilsin), keyin tuzatishlar.
bozor uchun ham qisqa PRD yozing — u keyingi darslarda kerak bo'ladi. Unda mahalliy shartlar muhim: to'lov Click va Payme orqali, mijozlar Telegram'da.
Yechim namunasi: `jamoa` talablaridan bo'lak
| User story | Qabul mezoni | Test |
|---|---|---|
| Egasi sifatida jamoa ochaman | jamoa ochilganda men — egasi, obuna — 14 kunlik sinov | jamoa.test.ts, billing.test.ts |
| A'zo sifatida faqat o'z jamoamni ko'raman | begona jamoa — 404, RLS — 0 qator | jamoa.test.ts "tenant ajratish" |
| Admin sifatida a'zoga vazifa tayinlayman | jamoa a'zosi bo'lmagan odamga — 422 | jamoa.test.ts "rollar va taklif" |
| Egasi sifatida limit nimaligini bilaman | 500 dan keyin — 409 limit-vazifa |
jamoa.test.ts "tarif limiti" |
| Egasi sifatida to'lov qilaman | Payme to'lovidan keyin obuna — faol | billing.test.ts "obuna va Payme" |
Bu jadval kanon jamoa testlaridan yig'ilgan: har qatorga haqiqiy test bor. Sizning jadvalingizda test ustuni hozircha bo'sh bo'lishi mumkin — u keyingi to'rt darsda to'ladi.
12. Real ishda
- Startapda. Birinchi versiya ko'pincha bitta odamning to'rt-olti haftalik ishi. PRD va "maqsad emas" ro'yxati investor yoki egasi bilan suhbatni tejaydi.
- Kompaniyada. Product manager PRD yozadi, dasturchi RFC. Junior'dan kutiladigani — ikkalasini o'qib, savol bera olish: "Bu mezonni qanday tekshiramiz?"
- Intervyuda. "Eng katta loyihangiz haqida gapiring" savoliga eng yaxshi javob — rejadan boshlanadi: nimani qurdingiz, nimani kesdingiz va nega. Portfolio: loyihalarni tanlash va taqdim etish darsida shu hikoyani yozasiz.
- Frilansda. Mijoz bilan PRD'ni kelishib olish — "bu ham kerak edi" degan cheksiz o'zgarishlardan himoya.
Xulosa
- Capstone — tutorial klon emas: talab, qaror va xatoni o'zingiz topasiz; kanon — namuna.
- Har darsning besh bosqichi: talab → ADR → qurish → tekshirish → o'zingiz qiling.
- Reja hujjatlari: PRD (nima va kim uchun), user story → mezon → test, MVP qamrovi va "halol chegaralar", ERD, repo tuzilmasi, milestone va DoD.
- Biznes qoidasi imkon bo'lsa bazada: noyob indeks, kompozit FK, CHECK.
- 4.5.0: ko'p nusxa uchun holat Postgres'da (409 × 100 → 201 + Replayed × 100), chegara qulf ichida (1015 → 1000), cron 7 → 0 xato, OTP logga tushmaydi.
- Regressiya testi avval eski kodda yiqilsin: 36-qism kodida 13/13 yiqildi, 4.5.0 da 13/13 o'tdi.
Keyingi dars: SaaS capstone 1: arxitektura, multi-tenant va auth — jamoa ning poydevori: jamoa_id + RLS, sessiya cookie, rollar va taklif oqimi.
Manbalar
- PostgreSQL 18 — INSERT … ON CONFLICT: https://www.postgresql.org/docs/18/sql-insert.html (tekshirildi, 2026-11:
RETURNINGfaqat qo'shilgan yoki yangilangan qatorlarni qaytaradi;DO UPDATE … WHEREbajarilmasa — qaytarilmaydi) - PostgreSQL 18 — UUID funksiyalari,
uuidv7(): https://www.postgresql.org/docs/18/functions-uuid.html (tekshirildi, 2026-11) - Mermaid — Entity Relationship Diagrams: https://mermaid.js.org/syntax/entityRelationshipDiagram.html (tekshirildi, 2026-11:
||,o{,|obelgilari) - Kurs tajribasi (IlmHamroh, 2026-11):
vazifalar-api4.5.0 — regressiya (13/13 yiqildi → 13/13), ko'p nusxa o'lchovi (2 nusxa, 100 operatsiya). Tekshiruv: Windows 11, Node 24.21.0.jamoa— 11/11 test, e2e 1/1,actyashil. Mashq yechimlari — biz ishga tushirdik (2026-11-10).
Izohlar · 0
Izoh yozish uchun kiring.