Mühitlər: local dev, staging, production + Dev Mode

1. Ümumiyyətlə mühitlər barədə niyə düşünmək lazımdır

Adi veb‑hazırlamada gec-tez üçlük meydana çıxır: lokal inkişaf, test serveri və production mühiti. ChatGPT Apps dünyasında da eynidir, ancaq əlavə bir dönmə ilə: müştəri (ChatGPT) həmişə buluddadır, hətta «lokalda» işləyərkən belə.

Hər şey ancaq noutbukunuzda təsadüfi tunel ünvanı altında fırlananda bir neçə xoşagəlməz effekt yaranır. Birincisi, URL daim dəyişir və Dev Mode-un hazırda məhz hansı endpoint-ə bağlı olduğunu xatırlamırsınız. İkincisi, performans və şəbəkə döyüş şəraitinə oxşamır. Üçüncüsü, lokal mühit tez-tez başqa açarlardan, başqa servislərdən istifadə edir və ümumiyyətlə paralel reallıqda «yaşayır».

Digər tərəfdən, «həmişə prod-da yaşamaq» da pisdir. İstənilən düzəliş gözlənilmədən real istifadəçilərin ssenarilərini poza bilər, xüsusilə Stripe, OAuth və ya ACP vasitəsilə ödəniş kimi inteqrasiyalarınız varsa. Hüquqi və siyasət baxımından da problemlidir: real istifadəçilər üzərində eksperimentlər Store üçün ən yaxşı yol deyil.

Ona görə də bu mühazirənin məqsədi — başınızda sadə, amma sərt bir sxem formalaşdırmaqdır: local dev var, staging var, production var və Dev Mode ChatGPT-ni lazım olan mühitə yönəltməyin yoludur. Və «bəzən qəfil proda çevrilən tunelli noutbukum» deyil.

2. ChatGPT Apps xüsusiyyəti: müştəri həmişə buluddadır

Klassik SPA tətbiqində çox vaxt həm müştərini, həm də serveri lokalda işə salırsınız: brauzer localhost-da, backend localhost-da və hər şey bir maşın daxilində xoşbəxtcəsinə ünsiyyət qurur.

ChatGPT Apps-də bu baş vermir. Müştəri (ChatGPT + vidcetiniz) həmişə OpenAI infrastrukturunda «yaşayır». Hətta tətbiqinizin kodu noutbukunuzda işləsə belə, sorğu belə gedir:

sequenceDiagram
    participant User as Istifadəçi
    participant ChatGPT as ChatGPT (bulud)
    participant Tunnel as HTTPS tuneli
    participant App as Sizin Next.js + MCP

    User->>ChatGPT: Mesaj / vidcetə klik
    ChatGPT->>Tunnel: URL-ə HTTPS sorğusu (App)
    Tunnel->>App: localhost-a proksi
    App-->>Tunnel: Cavab (UI/JSON)
    Tunnel-->>ChatGPT: Cavab
    ChatGPT-->>User: Yenilənmiş çat + vidcet

Hətta «sadəcə lokalda test edəndə» belə siz artıq paylanmış sistemdəsiniz: bulud müştərisi var, şəbəkə var, tunel var, lokal serveriniz var.

Bu vacibdir, çünki:

1. Lokal mühit — heç də «hamısı məndə lokaldır» deyil. Bu «bulud → tunel → lokal server» deməkdir.
2. Sonra staging və production əlavə edəndə sxem yalnız ChatGPT-nin sorğuları hara göndərməsi ilə fərqlənəcək: tunelə, staging domeninə və ya döyüş domeninə.

3. Local dev: mövcud sxeminiz necə görünür

Gəlin bu ümumi sxemin sizdə indi necə göründüyünə baxaq.
2–6-cı modullardan sonra çox güman bu cür şəkil var:

• npm run dev komandası ilə işə salınmış Next.js dev‑serveri (adətən http://localhost:3000).
• Lokal MCP serveri (tez-tez ayrıca proses, məsələn, http://localhost:2091).
• HTTPS tuneli (ngrok, Cloudflare Tunnel və s.), Next.js/HTTP endpoint-inizi https://abc123.ngrok.app kimi ünvanda çölə çıxarır.

ChatGPT-də Dev Mode vasitəsilə bu publik URL-i göstərirsiniz və ChatGPT tətbiqinizə müraciət etməyə başlayır. Bunların hamısı — local dev mühitidir.

Local dev-in əsas xüsusiyyətləri:

• Lokal mühit çox sürətli feedback loop verir. VS Code-da kodu dəyişirsiniz, Next.js hot reload edir, vidcet bir neçə saniyəyə yenilənir.
• Burada istənilən şeyi sındırmaq olar, mock məlumatlardan, test açarlarından, qəribə konfiqlərdən istifadə etmək olar.
• Burada real istifadəçilər yoxdur, sizdən başqa az adam ümumiyyətlə bu URL-i bilir.

Adətən bu belə görünür:

graph LR
    subgraph Dev Laptop
      Next[Next.js dev server]
      MCP[MCP server]
    end

    ChatGPT((ChatGPT Cloud))
    Tunnel[[HTTPS tuneli]]

    ChatGPT --> Tunnel --> Next
    Next --> MCP

Local/staging/production arasında qarışmamaq üçün tətbiqin özünün «harada işlədiyini» bilməsi faydalıdır. Tətbiqinizin kodu baxımından indi dev mühitində olduğunuzu açıq şəkildə sabitləşdirmək faydalıdır. Ən sadə addım — kiçik bir mühit konfiqurasiya modulu daxil etməkdir.

Məsələn, app/config/env.ts faylını yaradaq:

// app/config/env.ts
export type AppEnv = 'local' | 'staging' | 'production';

export const APP_ENV: AppEnv =
  (process.env.NEXT_PUBLIC_APP_ENV as AppEnv) ?? 'local';

export const isProd = APP_ENV === 'production';

Burada biz:

1. Mühitlərin tipləndirilmiş siyahısını (enumeration) daxil edirik.
2. NEXT_PUBLIC_APP_ENV dəyişənini oxuyuruq (sonra dev/staging/prod üçün fərqli dəyərlər verəcəksiniz).
3. Susmaya görə 'local'-da olduğumuzu qəbul edirik ki, lokal inkişaf «qutudan çıxan kimi» işləsin.

Hələ heç nə deploy edilmir, amma artıq dayaq nöqtəsi yaranır: kodunuz hansı mühitdə icra olunduğunu başa düşür.

Daha sonra, məsələn, qarışıqlıq olmasın deyə mühiti birbaşa vidcetdə göstərə bilərsiniz.

// app/components/EnvBadge.tsx
import { APP_ENV } from '../config/env';

export function EnvBadge() {
  return <span>ENV: {APP_ENV}</span>;
}

Bu cür kiçik nişan («badge») «indi staging-dəyəm, ya prod-da?» sualını qarışdırmamağa ciddi kömək edir, xüsusilə vidcet zahirən eyni olanda.

4. Staging: production mühitinin general repitisiyası

Staging mühiti — «production mühitinin repitisiyası»dır. Bu artıq dev‑serverli noutbukunuz deyil, yığılmış kodun yerləşdirildiyi uzaq server və ya Vercel deployudur.

ChatGPT baxımından staging demək olar ki, production kimidir: bu, https://staging.giftgenius.app kimi domenlə rahat, stabil HTTPS endpoint-dir, burada:

• kod artıq yığılır (npm run build uğurla keçib);
• döyüşə bənzər mühit dəyişənlərindən istifadə olunur (eyni adlar, eyni format), amma test açarları ilə;
• eyni xarici servislər əlçatandır (Stripe sandbox, test OAuth hesabları);
• şəbəkə topologiyası döyüşə bənzəyir (məsələn, eyni tip DB və eyni region).

ChatGPT Apps kontekstində staging nə üçün lazımdır:

Birincisi, məhz staging-də end‑to‑end ssenariləri işlətmək rahatdır. Məsələn: istifadəçi ChatGPT-də → ChatGPT tətbiqinizi işə salır → vidcet istifadəçidən soruşur → xarici API-yə gedən MCP tool çağırılır → tövsiyələr qaytarılır → vidcet nəticəni göstərir. Belə ssenari lokalda təsadüfi tunel üzərindən bir cür davrana bilər. Staging mühitində isə fərqli: orada gecikmə, şəbəkə və resurslar reallığa daha yaxındır.

İkincisi, staging lokalda çevirməkdən çəkinilən inteqrasiyaları test etməyə imkan verir. Məsələn, ödənişlər: Stripe, ACP/Instant Checkout və s. Staging-də test açarları, test webhook-ları konfiqurasiya edirsiniz və ssenariləri «ciddi» şəkildə, amma real pul olmadan keçirirsiniz.

Üçüncüsü, staging — komandavi yoxlama yeridir. Bir neçə developer, dizayner, QA, product varsa — onlara kimin noutbuku açıqdır, kimin tuneli çöküb kimi amillərdən asılı olmayan ortaq URL lazımdır.

Staging-i belə təsəvvür etmək rahatdır:

graph LR
    ChatGPT((ChatGPT Cloud))
    AppStaging["GiftGenius Staging  https://staging.giftgenius.app"]

    ChatGPT --> AppStaging

Və artıq https://staging.giftgenius.app daxilində Next.js, MCP serveri, staging DB və qalan hər şey işləyə bilər.

Bu mühazirədə Vercel-ə deploy detalları ilə məşğul olmuruq, bu, növbəti mövzuların vəzifəsidir. İndi sadəcə belə qəbul etmək vacibdir: staging — konfiqurasiya və ChatGPT-nin ona necə çatması baxımından production-a maksimum oxşar ayrıca bir mühitdir.

5. Production: döyüş serveri və real istifadəçilər

Production mühiti — real istifadəçilərin və real pulların gəldiyi yerdir. Artıq «indi main-də tez düzəldim, baxım nə olacaq» yoxdur — istənilən dəyişiklik şüurlu, test edilmiş və imkan daxilində geri alma imkanı ilə olmalıdır.

Production domeni stabil olmalıdır. Bu, təsadüfi ngrok URL-i deyil, https://giftgenius.app kimi normal addır. Store üçün App ayarlarında məhz bu ünvanı göstərirsiniz: istifadəçi tətbiqinizi ChatGPT Store-da tapıb işə salanda, ChatGPT məhz bu endpoint-i çağıracaq.

Production mühitinə adətən yüksəldilmiş tələblər qoyulur:

• Sabitlik. Aşağı xəta faizi, proqnozlaşdırılan cavab vaxtı, yük altında düzgün iş. Sonrakı modullarda SLO/SLI barədə danışacağıq, amma intuitiv olaraq bu «tətbiq “demək olar həmişə” işləməli və “demək olar həmişə” tez cavab verməlidir» deməkdir.
• Təhlükəsizlik. Yalnız lazım olan sirlər, minimal zəruri icazələr, PII və pulla diqqətli iş.
• Eksperimentlərin məhdudlaşdırılması. İş gününün ortasında «yenə dev serveri restart etdim» yoxdur; eksperimentlər feature flag-lər, A/B və ya ayrıca dev/staging mühiti ilə, döyüş serverini birbaşa «qurdalamaqla» yox.

ChatGPT terminlərində production — artıq Dev Mode haqqında deyil, dərc olunmuş App haqqındadır: istifadəçilərə Store və ya təşkilat ayarları vasitəsilə əlçatandır, review-dan keçir və moderatoriya qarşısında utanmamaq üçün kifayət qədər etibarlı olmalıdır.

6. Dev Mode vs prod‑istifadə App: nə nəyə bağlıdır

İndi ən çox qarışıqlıq yaradan məqam: ChatGPT-də Dev Mode «ayrı mühit» deyil. Bu daha çox marşrutlaşdırma keçididir: tətbiqi test edəndə ChatGPT hansı URL-ə baxır.

Dev Mode-da siz bunları edə bilərsiniz:

• lokal tətbiqi tunel vasitəsilə qoşmaq;
• staging mühitini qoşmaq;
• hətta müvəqqəti olaraq Dev Mode-u production-a yönəltmək (adətən etmək məsləhət deyil).

Formal olaraq Dev Mode ChatGPT-yə deyir: «Budur mənim App manifestim, budur mənim MCP/Apps SDK endpoint URL-im. Bu tətbiqi işə salanda ondan istifadə et». Və bu URL-i dəyişə bilərsiniz.

Store-da dərcdən sonra App üçün rəsmi production endpoint yaranır. Real istifadəçilər üçün məhz o istifadə olunacaq və onu elə-belə dəyişmək olmaz: yeni versiya, review və s. lazımdır.

Praktikada sizin tədris tətbiqiniz üçün məntiqli sxem belə görünə bilər:

graph TD
    subgraph Dev Mode
      DevApp["GiftGenius Dev App
(Dev Mode)"]
    end

    subgraph Store
      ProdApp["GiftGenius
(Store App)"]
    end

    UserDev[Siz / komanda] --> DevApp
    UserProd[Real istifadəçilər] --> ProdApp

    DevApp -->|Tunel URL-i| LocalEnv[Local dev
https://abc123.ngrok.app]
    DevApp -->|staging URL| StagingEnv[Staging
https://staging.giftgenius.app]

    ProdApp -->|prod URL| ProdEnv[Production
https://giftgenius.app]

GiftGenius Dev Dev Mode tətbiqini adətən local dev-ə (tunel vasitəsilə) baxacaq şəkildə qurursunuz, lazım olduqda isə staging-ə yönəldirsiniz. GiftGenius Store tətbiqi isə ciddi şəkildə production URL-ə bağlıdır.

Bəzən QA üçün ayrıca App da edirlər, məsələn, yalnız staging URL-ə baxan GiftGenius Staging. Bu, böyük testçi komandanız varsa rahatdır; kurs çərçivəsində bir dev App kifayətdir.

Belə düşünməyə alışmaq vacibdir: Dev Mode — URL-i dəyişmək, metadata düzəltmək, tuneli yenidən başlatmaq üçün sizin və komandanız üçün şəxsi qum qutusu (sandbox)dur. Store-dakı production App isə yalnız production-a baxır və daha sərt qaydalarla «yaşayır».

7. Git budaqlarının, domenlərin və ChatGPT App-ın əlaqələndirilməsi

Mühitlər — təkcə serverlər deyil. Bu həm də kod budaqları və ChatGPT-də App konfiqurasiyalarıdır. Tez-gec elə istəyəcəksiniz ki, URL-ə və ya App adına bir baxışdan orada hansı kod versiyasının işlədiyi anlaşılsın.

Sadə minimal yanaşma belədir.

Ayrı feature-ların hazırlanması üçün feature/* budaqlarından istifadə edirsiniz, məsələn, feature/new-recommendation-algo. Kodu lokalda + tunel ilə işlədirsiniz. ChatGPT-də Dev Mode adətən eyni dev endpoint-ə baxır, siz isə növbə ilə lokal versiyaları işə salırsınız. Hər feature budağı üçün ayrıca App — artıqdır.

Relizdən əvvəl fitchaların inteqrasiyası üçün develop və ya staging budağı aça bilərsiniz. Bu budaqdakı hər şey avtomatik olaraq staging mühitinə deploy olunur, məsələn, https://giftgenius-staging.vercel.app formatlı Vercel preview URL-ə. Onun üçün ayrıca Dev Mode App aça və ya ümumi Dev App-ı vaxtaşırı bu URL-ə yenidən qurşandıra bilərsiniz.

main (və ya master) budağı — yalnız test edilmiş koddur. Məhz o production URL-ə deploy olunur və GiftGenius Store tətbiqinə bağlıdır.

Təxminən belə görünə bilər:

feature/*

https://abc123.ngrok.app

develop / staging

https://staging.gift...

main

https://giftgenius.app

app/config/env.ts-dəki APP_ENV-i xatırlayırsınız? 'local'/'staging'/'production' dəyərləri burada «Mühit» sütununa birbaşa uyğun gəlir: local dev-də tətbiqi APP_ENV=local ilə işə salırsınız, staging deploy — APP_ENV=staging ilə, production isə APP_ENV=production ilə.

Belə cədvəl — bürokratiya deyil, «bu domendə indi ümumiyyətlə hansı versiya işləyir?» sxemi ilə sazlama aparmamaq üçün yoldur.

Bir az da bu əlaqəni kodun özündə gücləndirmək olar. Məsələn, vidcetin debug rejimində təkcə ENV deyil, həm də commit/budağı göstərmək:

// app/config/buildInfo.ts
export const BUILD_COMMIT = process.env.NEXT_PUBLIC_BUILD_COMMIT ?? 'dev';
export const BUILD_ENV = process.env.NEXT_PUBLIC_APP_ENV ?? 'local';

// app/components/BuildInfo.tsx
import { BUILD_COMMIT, BUILD_ENV } from '../config/buildInfo';

export function BuildInfo() {
  return <small>Build: {BUILD_ENV}@{BUILD_COMMIT}</small>;
}

Əgər deploy zamanı NEXT_PUBLIC_BUILD_COMMIT-ə commit-in SHA-sını qoyursunuzsa, vidcetdə indi konkret hansı kodun işlədiyi dürüst yazılacaq. Bəzən bu, staging/prod-da saatlarla sazlamadan xilas edir.

8. Mini‑praktika: öz mühitlərinizin sxemini çəkək

Vercel və loglara keçməzdən əvvəl mühitlərinizin sxemini sözün əsl mənasında «salfetdə çəkmək» faydalıdır. Bu, README.md-də mermaid diaqramı, lövhədə eskiz və ya dəftərdə şəkil ola bilər.

Bizim tədris GiftGenius-u üçün sxem belə görünə bilər:

graph TD
    subgraph ChatGPT
      DevMode["Dev Mode
(siz və komanda)"]
      Store["Store
(real istifadəçilər)"]
    end

    subgraph Servers
      Local[Local dev
Tunel → localhost]
      Staging[Staging
staging.giftgenius.app]
      Prod[Production
giftgenius.app]
    end

    DevMode --> Local
    DevMode --> Staging
    Store --> Prod

Mühazirədən dərhal sonra sizin üçün faydalı məşq:

1. Artıq mövcud olan bütün mühitləri yazın: tunelli lokal, bəlkə hansısa erkən Vercel deployu, başqa nə varsa.
2. Yaxınlıqda ora hansı Git budaqlarının deploy olunduğunu qeyd edin.
3. Bir də — hansı ChatGPT Apps (və ya konnektorlar) hara baxır.
4. Oxlarla qeyd edin ki, ChatGPT hər serverə haradan gedir.

Tək işləmirsinizsə, repozitoriyada architecture/environments.md kimi fayl yaradın. Bu, «bizdə staging yıxılıb, amma heç kim onun URL-inin nə olduğunu bilmir» ehtimalını dərhal azaldacaq.

Bunu tətbiqinizlə əlaqələndirmək üçün, elə indi Dev Mode-da bir App — GiftGenius Dev — yaradın və qərar verin: susmaya görə o, lokal mühitin tunelinə baxır, bütün relizi test etmək istəyəndə isə müvəqqəti olaraq onu staging URL-ə yenidən qurursunuz. Növbəti mühazirələrdə staging/prod-u Vercel-ə necə deploy etməyi və bunu mühit dəyişənləri ilə necə bağlamağı öyrənəcəksiniz.

Bütün bunları bir fikirdə toplasaq: mühitlərə və Dev Mode-a App-ınız üçün koordinatlar sistemi kimi yanaşın. Lokal — sürətli inkişaf üçün, staging — general repitisiya üçün, production — real istifadəçilər üçün, Dev Mode isə onların arasında keçidinizdir, ayrıca sehrli mühit deyil.

9. Mühitlərlə və Dev Mode ilə işləyərkən tipik səhvlər

Səhv №1: yalnız localhost + tuneldə yaşamaq və bunu prod hesab etmək.
Belə yanaşma rahat görünür: «staging və prod nəyə lazımdır, axı tunelim işləyir, ChatGPT qoşulur». Amma tunelin URL-i qeyri-sabitdir, şəbəkə xüsusiyyətləri fərqlidir və bütün sxem bir noutbuka bağlıdır. OAuth callback, Stripe webhook-ları və ya MCP Gateway kimi nəsə lazım olan kimi normal staging/prod-un olmaması ağrıya səbəb olacaq.

Səhv №2: Dev Mode-u ayrıca mühitlə qarışdırmaq.
Çoxları düşünür: «Məndə Dev Mode var, deməli dev mühitim var». Əslində Dev Mode sadəcə ChatGPT-yə hara getməyi deyir: tunelə, staging-ə və ya hətta prod-a. Dev Mode — müştəri ayarıdır, server yox. Server mühitlərini (local/staging/prod) siz özünüz yaradırsınız: kodu deploy edirsiniz, domenləri, mühit dəyişənlərini qurursunuz.

Səhv №3: Dev Mode-u production-a yönəldib «bir az test etmək».
Texniki cəhətdən mümkündür: Dev Mode-da production URL yaza və App ilə sanki lokaldaymış kimi oynaya bilərsiniz. Problem ondadır ki, siz qəfildən real istifadəçilər, real məlumatlar və bəlkə də real pullar üzərində test etməyə başlayırsınız. Alət və ya vidcetin istənilən xətası döyüş istifadəçiləri üçün nasazlıqlara gətirə bilər və siz bunun haradan gəldiyini dərhal anlamayacaqsınız. Dev Mode-u dev/staging-də saxlayın və production üçün Store App-dan istifadə edin.

Səhv №4: «budaq ↔ mühit ↔ URL ↔ App» xəritəsinin aydın olmaması.
Komandada heç kim birinci cəhddə hansı budağın staging-ə deploy olunduğunu, onun URL-inin nə olduğunu və hansı ChatGPT App-ın ona baxdığını deyə bilmirsə, bu, qarantiya edilmiş xaos mənbəyidir. «Məndə hər şey işləyir, staging-də yox, prod-da isə üçüncü nəsə» kimi hekayələr başlayır. Bu xəritə ilə sadə cədvəl və ya markdown faylı özünü dəfələrlə doğruldur.

Səhv №5: local dev ilə staging arasındakı fərqi kiçiltmək.
Lokalda dev serveri işlədirsiniz, bir açar dəsti, bir servis dəsti və bir şəbəkəniz var. Staging-də isə kod artıq yığılıb, başqa mühitdə, başqa limitlər, taymautlar və marşrutlarla işləyir. Hər şeyi yalnız lokalda test edib, staging-i «adət xatirinə» saxlayırsınızsa, kritik bug-lar artıq prod-da üzə çıxacaq. Bu zəncirə öyrəşmək vacibdir: əvvəl lokal inkişaf, sonra staging-də yoxlama və yalnız bundan sonra production-a reliz.

Səhv №6: mühit sxemini nəzərə almadan bütün problemləri ChatGPT ilə həll etməyə çalışmaq.
Bəzən problemlərdə tərtibatçılar «nə baş verdiyini ChatGPT-dən soruşmağa» başlayırlar, mühit şəkilinə baxmaq əvəzinə: hansı App hansı URL-ə bağlıdır, hansı mühitdə düşüb, loglar haradadır. Bugünkü mühit sxemimiz — növbəti mühazirənin əsasıdır: sistemli sazlama edəcəyik, loglara baxacağıq, MCP inspektordan istifadə edəcəyik və yalnız sonra modeli günahlandıracağıq.