Milliy maktab tizimi integratsiya qatlami uchun boshqaruv paneli va jonli API hujjatlari

Kontekst

Milliy maktab axborot tizimi boshqa davlat va korporativ xizmatlar bilan integratsiya API orqali ma’lumot almashadi: o‘quvchilar yozuvlari, qabul tarixi, tashkilot ma’lumotlari. Hamkor tashkilotlar akkaunt, endpoint va chegaralar oladi; har bir chaqiruv logga yoziladi. Buni yuritadigan jamoaga kirishni boshqarish, trafikni kuzatish va hamkorlarga har bir endpointni qanday chaqirishni ko‘rsatish uchun bitta joy kerak edi. Bu panelni Uzinfocomda 2026-yil maydan boshlab noldan qurdim va yuritaman.

Muammo

Panelgacha hamkorlarni boshqarish ma’lumotlarni qo‘lda tahrirlash va serverdagi loglarni o‘qish edi. Hamkorlarda haqiqiy API bilan sinab ko‘rish mumkin bo‘lgan hujjat yo‘q edi. Panelning PrimeNG admin shabloni asosidagi birinchi versiyasi esa kirish formasi ko‘ringunicha 2 MB JavaScript yuklardi.

Cheklovlar

O‘zbek lotin, o‘zbek kirill va rus tillaridagi davlat operatorlari va hamkor dasturchilar. G‘ayrioddiy shartnomali backend: har bir chaqiruv POST, o‘qishlar ham, parametrlar query stringda, har bir javob bitta konvertga o‘ralgan. Panel qat’iy va oldindan aytib bo‘ladigan bo‘lishi kerak edi, toki kichik jamoa uni ekranma-ekran kengaytira olsin.

Nima qildim

Ilovani Angular 21 asosida zoneless o‘zgarishlarni aniqlash, holat uchun Signals va to‘liq standalone komponentlar bilan qurdim, jadvallar, dialoglar va formalar uchun PrimeNG 21, joylashuv uchun Tailwind CSS 4. Har bir ekran bitta qolipga amal qiladi: yuklanish, saqlash va jadval holati uchun signalli ro‘yxat komponenti, paginator, yuklanish, bo‘sh va xato holatlariga egalik qiluvchi umumiy jadval o‘rami, reaktiv formalardagi qo‘shni dialog saved hodisasini chiqaradi, @Confirmable dekoratori esa halokatli amallarni tarjima qilingan tasdiqlash dialogi ortiga oladi. Backendning to‘liq POST shartnomasini har bir ob’yekt uchun tipli API xizmatlariga o‘radim, bitta javob konverti bir joyda ochiladi, tipli xato interceptori har qanday backend xato shaklini bitta xabarga keltiradi va 401 da foydalanuvchini tizimdan chiqaradi.

Ekranlar: rollar va ruxsatlar, foydalanuvchilar va ularning rollari, tashkilotlar, API endpointlari, endpoint loglari, har bir endpoint uchun chastota chegaralari, har bir foydalanuvchi uchun IP ruxsat qoidalari va interaktiv API hujjatlari. Hammasi Transloco bilan tarjima qilingan; kalitlar skript bilan ajratib olinadi va tekshiriladi, shuning uchun tarjima qilinmagan satr chiqib ketmaydi, tekshiruvda qoladi.

API hujjatlari generatorini yozdim: Node skripti backendning OpenAPI spetsifikatsiyasini o‘qiydi va panel ko‘rsatadigan hujjat ma’lumotlarini chiqaradi, kontrollerlar bo‘yicha guruhlangan, so‘rov tanasi sxemaga qarab forma, xom JSON yoki fayl yuklashga xaritalangan, taniqli parametrlar uchun namuna qiymatlar oldindan to‘ldirilgan. Xaritalash Node ning o‘rnatilgan test ishga tuvchisida 161 ta test bilan qoplangan sof kod, shuning uchun backend shartnomasi o‘zgarsa, bu qayta generatsiya va diff, bir kunlik tahrir emas. Hozir 20 ta kontroller va 144 ta endpointni qamrab oladi.

Unumdorlik bo‘yicha ish o‘tkazdim va uni nazorat nuqtalari bilan reja sifatida yozdim: joylashuv barqarorligi uchun o‘z serverimizdagi shriftlar va o‘lchami belgilangan logotip, qobiq, dashboard va topilmadi sahifasi uchun kechiktirib yuklanadigan chegaralar, talab bo‘yicha yuklanadigan mavzu presetlari, shablonning demo kodi fayl almashtirish orqali ishlab chiqarish buildidan chiqarilgan va marshrut byudjetdan oshsa buildni to‘xtatadigan bandl o‘lchami nazorati.

Build va reliz

Panel statik bir sahifali ilova sifatida chiqadi. npm run build:prod avval app-version.json ga paket versiyasi, avtomatik oshadigan build raqami, qisqa commit xeshi, branch va vaqt tamg‘asini yozadi, shuning uchun ishlayotgan har qanday buildni aniq aniqlash mumkin. So‘ng Angularning application builderi ikkita fayl almashtirish bilan ishlab chiqarish bandlini yaratadi: ishlab chiqarish muhiti va shablonning demo sahifalarini bandldan butunlay chiqarib tashlaydigan demo marshrut konfiguratsiyasi. Byudjetlar boshlang‘ich bandl 700 kB dan yoki biror komponent stili 4 kB dan oshsa buildni to‘xtatadi; npm run build:analyze statistikani chiqaradi va o‘z unit testlariga ega bandl hisobotini ishga tushiradi. Relizdan oldin tarjima kalitlari skript bilan ajratib olinadi va tekshiriladi, backend shartnomasi o‘zgarganda hujjat ma’lumotlari npm run docs:generate bilan OpenAPI spetsifikatsiyasidan qayta generatsiya qilinadi. Hosting: index.html ga bitta rewrite qiladigan har qanday statik server; repozitoriyda Vercel uslubidagi hostlar uchun shu konfiguratsiya bor.

Natija

Operatorlar hamkorlar, chegaralar va IP qoidalarini bitta interfeysdan boshqaradi va so‘rov loglarini server o‘rniga shu yerda o‘qiydi. Hamkor dasturchilar spetsifikatsiyadan generatsiya qilingan, shuning uchun hech qachon eskirmaydigan hujjat oladi va 144 ta endpointning har biri aynan nima kutishini ko‘radi. Bandl nazorati boshlang‘ich yuklamaning yana o‘sib ketishiga yo‘l qo‘ymaydi.