ქვიშის ყუთები და სატესტო გარემო

TL; DR

საიმედო ქვიშის ყუთი = სრული იზოლაცია, სინთეზური/ანონიმური მონაცემები, გარე სისტემების რეალისტური სიმულატორები, პროგნოზირებადი ადგილები და დროის ტრაველი, ჩაშენებული idempotence და ვებჰუკი, გამჭვირვალე ლიმიტები და მეტრიკა. პროდი - მიუწვდომელია, გასაღებები - ვრცელდება, პრომოტიონი - მხოლოდ ჩეკის ფურცლებზე.

1) გარემოს რუკა და მათი როლი

წესი: sandbox. ნებისმიერი კომუნიკაცია - ცალმხრივი სიმულატორების საშუალებით, რეალურ საშუალებებზე/თამაშებზე/პერსონალურ მონაცემებზე წვდომის გარეშე.

2) მონაცემები: სინთეზური, ანონიმიზაცია, სავარძელი

ნაგულისხმევი სინთეტიკა. პასპორტის/ბარათის მონაცემების გენერატორები, ნამდვილი, მაგრამ არაფინანსური PAN (ტესტის BIN), განაკვეთების და ნაშთების „ცოცხალი“ ნიმუშები.
ანონიმიზაცია სცენაზე: იდენტიფიკატორების ტოქსიკაცია, აგრეგატებისთვის დიფერენცირებული კონფიდენციალურობა, იშვიათი კომბინაციების მოხსნა.
ადგილები და დეტერმინიზმი: ერთი გუნდი - ერთი მდგომარეობა.

bash make db-reset && make db-seed ENV=sandbox SEED=2025_11_03

Time-travel: გარემოს გლობალური „საათი“ ვადაგადაცილებული/ექსპორტი ტესტებისთვის.

3) სიმულატორები და დანამატები (stubs)

გადახდები/ბანკები/PSP

Auth/Capture/Refund/Payout со сценариями: `approved`, `declined_insufficient`, `3ds_required`, `timeout`, `duplicate`.
PSP ვებჰუკები: ხელმოწერილი HMAC, retrais, შეფერხებები და „ბინძური ინტერნეტი“.

KYC/AML/Sanctions

Ответы: `clear`, `pep_match`, `sanction_hit`, `doc_mismatch`, `manual_review`.
Idempotents- ისა და rate limits- ის მხარდაჭერა, როგორც news.

თამაშის პროვაიდერები/კატალოგი

ლობი, ფიჩები, RTP/რაუნდი არის ფსევდო შემთხვევითი თაობა, რომელსაც მართავს „გადახდა/წარუმატებლობა“ UX შემთხვევებისთვის.

ვარიანტი: სიმულატორის „სიმძიმის“ შეცვლა (happy-path vs chaos).

4) ვებჰუკი ქვიშის ყუთში

ხელმოწერები HMAC (v1), სათაურები 'X-Event-Id', 'X-Timestamp', ფანჯარა 5 წუთი.
Retrai ექსპონენციალური backoff, DLQ და replay.
კონსოლი „გადაკეთება“ და მცდელობების შეცდომები.

pseudo
POST /psp/webhooks
Headers: X-Signature, X-Timestamp, X-Event-Id
Body: { event_id, type, data, attempt }

5) იდემპოტენტობა და დეტერმინიზმი

ყველა მუტაცია იღებს 'Idempotency-Key'.
სიმულატორები ინახავს შედეგს გასაღებით (TTL 24-72 საათი).
„თესლი-დეტერმინიზმი“: იმავე შეყვანისას - იგივე შედეგი (განმეორებითი ტესტებისთვის).

6) უსაფრთხოება და წვდომა

ქსელების/VPC იზოლაცია, ცალკეული საიდუმლოებები და დომენები ('sandbox. example. com`).
RBAC/ABAC: „partner“, „qa“, „dev“ როლები, ტოქსინების სკოპები მინიმალურია.
Rate-limits და კვოტები: per-tenant/გასაღების სამართლიანი წილი, გასაგები „429 '/' Retry-After“.
საიდუმლოებები მხოლოდ KMS/Vault- ში; რეგულარული როტაცია.
ნამდვილი გადახდების აკრძალვა კოდის/კონფისკაციის დონეზე (feature-flag hard block).

7) API Gateway და დაკვირვება sandbox

იგივე პოლიტიკოსები: OAuth2/OIDC/JWT, CORS, WAF, DDoS პროფილი.
მეტრიკა: p50/p95/p99, 4xx/5xx, ლიმიტების ჰიტ-ვერსია, ლატენტური ვებჰოქსი, იდემპოტენტური ჰიტები.
Logs/traces: PII გარეშე; კორელაცია 'trace _ id'.
დაშბორდი „ქვიშის ყუთის ჯანმრთელობა“: აფთიაქი, ვებჰუკების სტრიქონები, სიმულატორების შეცდომები.

8) Ficha დროშები, ვერსიები და თავსებადობა

Fich- ის ჩართვა sandbox stage- ში.
SemVer for API; Banner Deprecation/Sunset in Swagger/Redoc ქვიშის ყუთები.
Persististed queries GraphQL ფანჯრისთვის (თუ არსებობს).

9) CI/CD и promotion

1. Build/Unit →

2. Contract/Mock tests (OpenAPI/Protobuf/GraphQL SDL) →

3. ინტეგრაცია სიმულატორების წინააღმდეგ

4. Stage Regress (ანონი. Snaphots) -

5. Canary в prod.

Gate-check ჩამონათვალი promotion: ქვემოთ 12.

10) UAT სცენარები პარტნიორებისთვის (ქვიშის ყუთში)

გადახდები: aut/capture/refund/payout ვებჰუკებით და PSP შეცდომებით.
KYC/AML: ყველა სტატუსი + სახელმძღვანელო ესკალაცია.
Idempotence: განმეორებითი „Idempotency-Key“ - იგივე შედეგი.
Rate-limit: სწორი დამუშავება '429'.
დროებითი ფანჯრები: ნიშნების გაფართოება, 'Retry-After', დროის მოგზაურობის შემთხვევები.
Webhooks: ხელმოწერები/retrai/DLQ, სახელმძღვანელო replay და დედაპლატი.

11) მონაცემთა პოლიტიკა და კონფიდენციალურობა

არასოდეს შეინახოთ ნამდვილი PAN/KYC დოქები sandbox/stage.
ანონიმიზაცია: შენიღბვა, პირდაპირი იდენტიფიკატორების მოხსნა, სინთეზური კორელაცია.
TTL შენახვა ლოგებისა და ვებჰუკების ორგანოების მარეგულირებელი.

12) ჩეკის ფურცლები

12. 1 ახალი ქვიშის ყუთის გაშვება

• იზოლირებული ქსელი/ბაზა/ქეში/ობიექტის საცავი
• საიდუმლოებები შეიქმნა KMS/Vault- ში, როლებზე წვდომა
• PSP/KYC/თამაშები უკანა პლანზე და ვერსიონირებულია
• Swagger/Redoc + Postman კოლექცია (sandbox endpoints)
• ვებჰუკი: HMAC, retry, DLQ, კონსოლი
• Rate/Quta პროფილები, Banners Deprecation/Sunset (თუ არსებობს)
• დაშბორდები და ალერტები (ლატენცია, 5xx, 429, DLQ)

12. 2 Promotion release (stage→prod)

• კონტრაქტის შემოწმება (გადახდის გარეშე)
• დატვირთვა p95/p99 ჩვეულებრივ სცენაზე
• ვებჰუკებმა გაიარეს UAT, idempotenty ok
• მომზადებულია Ficha დროშები, არსებობს დაბრუნების გეგმა
• Changelog, მიგრაციის სახელმძღვანელო და პარტნიორების გაგზავნა

13) ანტიპატერები

ქვიშის ყუთი, „ფარულად“ შეხების სერვისები/ბაზა.
ნამდვილი კარტის/პასპორტის მონაცემები stage/sandbox.
Webhuk/retray- ის გარეშე სიმულატორები - „ბედნიერი ბილიკი“ მხოლოდ.
იდემპოტენტურობის არარსებობა - გადახდის/განაკვეთების დუბლიკატები.
ერთი საერთო HMAC საიდუმლო ყველა პარტნიორისთვის.
არ არსებობს ლიმიტები და გამჭვირვალე 429/Retry-After.

14) მინი snippets

.env. sandbox (მაგალითი)

dotenv
API_BASE=https://sandbox.api.example.com
OAUTH_ISS=https://sandbox.idp.example.com
PSP_SIM_URL=https://sandbox.psp-sim.example.com
KYC_SIM_URL=https://sandbox.kyc-sim.example.com
WEBHOOK_SECRET_ROTATION_DAYS=90
FEATURE_FORCE_SANDBOX_PAYMENTS=1

OpenAPI ფრაგმენტი (sandbox სერვერი)

yaml servers:
- url: https://sandbox.api.example.com/v1 description: Public Sandbox

იდემპოტენტობის ფსევდო კოდი

pseudo if store.exists(idem_key): return store.get(idem_key)
res = do_business()
store.set(idem_key, res, ttl=72h)
return res

PSP სიმულატორის გამომწვევები

json
{ "scenario": "payout", "case": "declined_insufficient", "payout_id": "p_123" }

15) დაკვირვება და SLO ქვიშის ყუთები

Uptime sandbox API ≥ 99. 5% (ინტეგრაციის ვიტრინა არ უნდა დაეცეს).
Webhooks p95-3 2xxx- მდე ნორმალური დატვირთვით.
Error budget 5xx კარიბჭე 0. 1%.
დოქის პორტალი ხელმისაწვდომია და სინქრონიზებულია ხელშეკრულებით.

16) Governance

გარემოს მფლობელი (SRE/Platform) და steward API (კონტრაქტები).
RFC პროცესი სარეკრეაციო ცვლილებებისთვის, Deprecation/Sunset კალენდარი.
საზოგადოებრივი ქვიშის ყუთისთვის ცალკეული ლიმიტები/კვოტები და პრაიმერი „სამართლიანი სახლი“.

რეზიუმე

ქვიშის ყუთი არის პროდუქტი დეველოპერებისთვის და არა „ბაზის ასლი“. მიეცით: მკაცრი იზოლაცია, სინთეზური მონაცემები, სრულფასოვანი სიმულატორები ვებჰუკებითა და რელიეფებით, დეტერმინიზმი სავარძლებისა და დროის ბილიკების საშუალებით, წინსაფარი დროშები და გამჭვირვალე ლიმიტები. დააკისრეთ ყველა კონტრაქტი, დაკვირვება და მთავრობა - და თქვენი ინტეგრაცია გახდება სწრაფი, უსაფრთხო და პროგნოზირებადი, ხოლო გამოშვებები უმტკივნეულოა.