JavaScript Full-stackCapstone metodologiyasi: g'oyadan rejagacha — PRD, MVP, ERD va milestone'lar
JavaScript Full-stack · 38-qism. Yakuniy loyihalar (capstone)

Capstone metodologiyasi: g'oyadan rejagacha — PRD, MVP, ERD va milestone'lar

26 daqiqa1/14-dars

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-api ni 4.5.0 ga yangilaymiz: ikkinchi API nusxasi uchun poydevor.

Bu darsda

  • Capstone darslari qanday tuzilganini va kanon kodidan qanday foydalanishni bilasiz.
  • jamoa uchun 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-api ni 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"| T

Diagrammadagi uzuq strelkaga qarang. "O'zingiz qiling" bosqichida yangi savol chiqadi va u keyingi talabga aylanadi. Bosqichlar:

  1. Talab — nima qilinadi va qanday tekshiriladi: user story va qabul mezonlari.
  2. Qaror — muqobillar va tanlov sababi, ADR shaklida. Kichik qaror — bir jadval qatori.
  3. Qurish — kanon kodining asosiy va qiyin joylari to'liq, oddiy joylari qisqa.
  4. Tekshirish — testlar va o'lchovlar, xom natija bilan. Kutilganidan boshqacha chiqsa, ochiq aytiladi.
  5. 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. azoliklar da 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) → azoliklar ga 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 esa ommaviy_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:

  1. Jamoa, a'zolik, rollar, taklif — SaaS capstone 1.
  2. Vazifalar jamoa kontekstida, fayllar, fon ishlar — SaaS capstone 2.
  3. Obuna va billing — SaaS capstone 3.
  4. 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:

text
AssertionError: Expected values to be strictly equal:

409 !== 201

Tarjimasi: "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:

text
'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:

js
// 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:

text
4.4.0: qayta {"409":100}, bazada 100
4.5.0: qayta {"201+Replayed":100}, bazada 100
UNIQUE'siz: qayta {"201":100}, bazada 200

Birinchi 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:

sql
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 1

Kanonda 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:

ts
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):

diff
   .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:

diff
   "*.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:

text
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 nomlash

9. 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.

js
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
js
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:

text
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
js
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:

text
qulfsiz: 201 × 20, 409 × 0, bazada 1015
qulf bilan: 201 × 5, 409 × 15, bazada 1000

Ikkala 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:

  1. docs/PRD.md — bir sahifa: muammo, foydalanuvchilar, muvaffaqiyat metrikasi, maqsad emas.
  2. docs/talablar.md — 5–8 ta user story, har biriga 2–4 qabul mezoni. Har mezon yonida — qaysi test uni tekshirishi.
  3. README'da "Halol chegaralar" va "Ko'chirilgan kod" jadvallari.
  4. docs/erd.md — mermaid erDiagram, kamida 6 jadval. Har biznes qoidasi uchun: u bazada qanday kafolatlanadi (CHECK, UNIQUE, FK) yoki nega faqat kodda.
  5. Milestone'lar va DoD — GitHub'da milestone va issue'lar (Kanban, vazifa trekerlari va ish oqimi).
  6. vazifalar-api ni 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

38-qism. Yakuniy loyihalar (capstone) · 1-dars yakunlandi

Capstone metodologiyasi: g'oyadan rejagacha — PRD, MVP, ERD va milestone'lar

26 daqvaqt
0belgi
Keyingi dars: SaaS capstone 1: arxitektura, multi-tenant va auth — jamoaid, RLS, sessiya va rollar
Telegram'da
Darsda xato koʻrdingizmi?

Izohlar · 0