feat(docs, integration): update integration documentation and redirect legacy paths

Introduced a new public documentation site for client integration at `/docs` and `/docs/integration`, removing the need for admin login. Updated the integration guide to redirect from the old admin path to the new documentation site. Added localization support for the integration documentation in English, Nepali, and Chinese. Enhanced the layout structure and improved the handling of currency display in settlement bills.
This commit is contained in:
2026-06-15 11:08:19 +08:00
parent e7b72cfdca
commit 17335cb47a
35 changed files with 2668 additions and 436 deletions

View File

@@ -0,0 +1,372 @@
{
"shell": {
"title": "Integration API",
"admin": "Admin"
},
"nav": {
"overview": "अवलोकन",
"api": "API",
"ship": "लाइभ",
"home": "सारांश",
"quickstart": "छिटो सुरु",
"fundamentals": "रकम मोडेल",
"setup": "सेटअप",
"sso": "SSO",
"iframe": "iframe प्रोटोकल",
"wallet": "वालेट गेटवे",
"transfer": "स्थानान्तरण (सन्दर्भ)",
"errors": "त्रुटि कोड",
"golive": "लाइभ सूची"
},
"headers": {
"component": ["कम्पोनेन्ट", "भूमिका", "मालिक"],
"convention": ["वस्तु", "नियम"],
"claim": ["Claim", "Type", "Req", "Note"],
"param": ["प्यारामिटर", "उद्देश्य"],
"methodPath": ["Method", "Path", ""],
"query": ["Query", "Type", ""],
"field": ["Field", "Type", "Note"],
"code": ["Code", "Message"],
"http": ["Status", "message", "Cause"],
"message": ["Dir", "type", "Payload"],
"balance": ["फिल्ड", "खाता", "नोट"],
"call": ["दिशा", "API", "Auth"],
"sequence": ["चरण", "अभिनेता", "कार्य"],
"envMap": ["वस्तु", "Admin साइट", "मुख्य .env", "नोट"],
"account": ["प्रयोगकर्ता", "पासवर्ड", "site_player_id"],
"contract": ["परिदृश्य", "HTTP", "Body"],
"adminField": ["फिल्ड", "नोट", "उदाहरण"]
},
"pages": {
"overview": {
"title": "Integration",
"description": "मुख्य साइट SSO + वालेट गेटवे। पहिचान JWT; रकम मुख्य वालेट र लटरी भित्रको ब्यालेन्समा विभाजित।",
"roles": "भूमिका",
"flow": "प्रवाह",
"e2eSequence": "End-to-end क्रम",
"conventions": "सम्झौता",
"readingOrder": "पढ्ने क्रम",
"matrix": [
["मुख्य साइट", "JWT जारी; वालेट गेटवे कार्यान्वयन", "साझेदार"],
["लटरी API", "JWT प्रमाणीकरण, खेल, स्थानान्तरण, बेट", "हामी"],
["लटरी H5", "H5 / iframe", "हामी"]
],
"flowItems": [
"मुख्य साइट लगइन → JWT जारी",
"लटरी प्रवेश (URL वा iframe)",
"transfer-in → मुख्य डेबिट + लटरी क्रेडिट",
"बेट / सेटल (लटरी ब्यालेन्स)",
"transfer-out → लटरी डेबिट + मुख्य क्रेडिट"
],
"e2eRows": [
["1", "मुख्य साइट", "लगइन; JWT जारी"],
["2", "मुख्य साइट", "iframe वा ?token= प्रवेश"],
["3", "लटरी H5", "token + GET /api/v1/player/me"],
["4", "प्लेयर", "H5 मा transfer-in"],
["5", "लटरी API", "POST /wallet/debit-for-lottery"],
["6", "साझेदार वालेट", "main_balance घटाउने"],
["7", "लटरी API", "लटरी भित्र क्रेडिट"],
["8", "प्लेयर", "H5 मा बेट"],
["9", "प्लेयर", "(वैकल्पिक) H5 transfer-out"],
["10", "लटरी API", "POST /wallet/credit-from-lottery"]
],
"conventionRows": [
["रकम", "Minor इकाई (पूर्णांक), जस्तै 2000 = 20.00"],
["एन्कोडिङ", "UTF-8 JSON"],
["समय", "JWT: Unix सेकेन्ड (iat / exp)"],
["Auth", "प्लेयर API: Bearer JWT; गेटवे: Bearer wallet_api_key"]
],
"readingItems": ["छिटो सुरु → सेटअप → SSO → iframe → वालेट → त्रुटि → लाइभ"]
},
"quickstart": {
"title": "छिटो सुरु",
"description": "स्थानीय इन्टिग्रेसन। repo मा main-site/ सन्दर्भ कार्यान्वयन; गोप्य कुञ्जी admin वा lottery .env सँग मिल्नुपर्छ।",
"prereq": "पूर्वशर्त",
"steps": "इन्टिग्रेसन चरण",
"testAccounts": "परीक्षण खाता (main-site)",
"reference": "सन्दर्भ कार्यान्वयन",
"note": "प्रोडक्सनमा HTTPS र अलग site_code/गोप्य। स्थानीयमा wallet_api_url बिना lottery API stub हुन सक्छ (non-production)।",
"prereqItems": [
"लटरी API (lotterLaravel) र lotteryfront चलिरहेको",
"main-site चलिरहेको (http://localhost:5173)",
"admin मा इन्टिग्रेसन साइट, वा lottery .env MAIN_SITE_* मिलेको"
],
"stepItems": [
"सुपर एडमिनले admin मा इन्टिग्रेसन साइट सिर्जना",
"गोप्य .env मा; admin मा wallet_api_url र iframe_allowed_origins",
"लगइन → iframe मा लटरी H5",
"LOTTERY_READY पछि MAIN_INIT_TOKEN",
"H5 मा transfer-in → debit-for-lottery कलब्याक",
"H5 मा बेट",
"(वैकल्पिक) H5 transfer-out",
"acceptance curl जाँच"
],
"accountRows": [
["alice", "alice123", "10001"],
["bob", "bob123", "10002"],
["demo", "demo123", "10003"]
],
"referenceItems": [
"कोड: monorepo मा main-site/",
"मुख्य: http://localhost:5173; लटरी H5: http://localhost:3800",
"main-site README: env र postMessage",
"सेटअप पृष्ठमा config mapping तालिका"
],
"acceptance": "स्वीकृति सूची",
"acceptanceItems": [
"JWT → curl /player/me code=0",
"debit self-test success:true",
"idempotent_key replay एउटै नतिजा",
"iframe: LOTTERY_READY → MAIN_INIT_TOKEN",
"H5 transfer-in: debit लग"
]
},
"fundamentals": {
"title": "Money model",
"balances": "दुई तह ब्यालेन्स",
"calls": "कल दिशा",
"note": "सबै रकम minor पूर्णांक। क्रेडिट-लाइन प्लेयर यो दस्तावेज बाहिर।",
"balanceRows": [
["main_balance", "मुख्य वालेट", "साझेदार गेटवे; लटरी कलब्याक"],
["lottery balance", "लटरी भित्रको ब्यालेन्स", "transfer-in पछि बेटिङ"]
],
"callRows": [
["लटरी → मुख्य", "balance / debit / credit", "wallet_api_key"],
["लटरी H5 → लटरी API", "me / transfer / bet", "प्लेयर JWT (मुख्य होइन)"]
]
},
"setup": {
"title": "Setup",
"description": "इन्टिग्रेसन साइट सिर्जना पछि गोप्य कुञ्जी एक पटक मात्र देखाइन्छ। तुरुन्त सुरक्षित राख्नुहोस्।",
"weProvide": "हामी दिन्छौं",
"youProvide": "साझेदारले दिन्छ",
"defaultPaths": "पूर्वनिर्धारित वालेट पथ",
"envMapping": "Config mapping",
"note": "परीक्षण/प्रोडक्सन अलग। गोप्य मुख्य साइट .env मा म्यानुअल। स्थानीयमा lottery .env MAIN_SITE_* fallback।",
"receiveRows": [
["site_code", "साइट कोड"],
["sso_jwt_secret", "JWT हस्ताक्षर गोप्य (मुख्य साइट)"],
["wallet_api_key", "वालेट कलब्याक auth (मुख्य साइट जाँच)"],
["lottery_h5_base_url", "लटरी प्रवेश URL"]
],
"provideRows": [
["wallet_api_url", "HTTPS वालेट आधार URL"],
["परीक्षण खाता", "site_player_id + सुरु ब्यालेन्स"],
["iframe origin", "एम्बेड गर्दा मुख्य origin"]
],
"pathRows": [
["GET", "/wallet/balance", "ब्यालेन्स"],
["POST", "/wallet/debit-for-lottery", "डेबिट"],
["POST", "/wallet/credit-from-lottery", "क्रेडिट"]
],
"envMappingRows": [
["site_code", "site_code", "MAIN_SITE_CODE", "JWT + प्लेयर; मिल्नुपर्छ"],
["SSO गोप्य", "sso_jwt_secret", "MAIN_SITE_SSO_JWT_SECRET", "मुख्य हस्ताक्षर; लटरी जाँच"],
["वालेट auth", "wallet_api_key", "MAIN_SITE_WALLET_API_KEY", "लटरी कलब्याक; मुख्य जाँच"],
["वालेट URL", "wallet_api_url", "—", "साझेदार HTTPS आधार"],
["लटरी प्रवेश", "lottery_h5_base_url", "NEXT_PUBLIC_LOTTERY_IFRAME_URL", "redirect/iframe"],
["iframe allowlist", "iframe_allowed_origins", "NEXT_PUBLIC_LOTTERY_ORIGIN", "एम्बेड origin"],
["लटरी API", "—", "LOTTERY_API_BASE_URL", "सन्दर्भ कार्यान्वयन मात्र"]
],
"adminSop": "Admin provisioning",
"adminSopSteps": [
"सुपर एडमिन → Config → Integration sites",
"साइट सिर्जना: code, name, currency",
"wallet_api_url, lottery_h5_base_url, iframe_allowed_origins",
"sso_jwt_secret, wallet_api_key एक पटक सुरक्षित",
"connectivity test (GET /wallet/balance)",
"प्रोडक्सन: सार्वजनिक HTTPS wallet_api_url"
],
"adminFieldRows": [
["code", "JWT site_code", "demo"],
["wallet_api_url", "HTTPS wallet base", "https://wallet.partner.com"],
["lottery_h5_base_url", "H5 entry", "https://lottery.partner.com"],
["iframe_allowed_origins", "Parent origins", "https://www.partner.com"],
["sso_jwt_secret", "एक पटक", "—"],
["wallet_api_key", "एक पटक", "—"]
],
"network": "Network",
"networkItems": [
"वालेट कलब्याक server-to-server",
"प्रोडक्सन: HTTPS सार्वजनिक मात्र",
"पथ: /wallet/balance, debit, credit",
"timeout ≤ 10s"
]
},
"sso": {
"title": "SSO",
"description": "HS256 JWT। मुख्य साइट हस्ताक्षर; लटरी प्रमाणीकरण। प्रवेश: URL वा iframe postMessage।",
"claims": "Claims",
"sign": "Sign",
"entryA": "Entry A — redirect",
"entryB": "Entry B — iframe",
"noExchangeNote": "लटरीमा token-exchange login API छैन। मुख्य साइट लगइन पछि JWT जारी गर्नुहोस्; player API मा Authorization: Bearer। पहिलो वैध GET /api/v1/player/me ले प्लेयर auto-provision गर्छ।",
"entryApi": "Entry API (लटरी)",
"entryApiNote": "वैकल्पिक: लगइन पछि मुख्य साइटले एक पटक server-side कल गर्न सक्छ (main-site हेर्नुहोस्)। दैनिक play API लटरी H5 ले कल गर्छ।",
"publicApis": "सार्वजनिक API (token बिना)",
"h5ScopeNote": "स्थानान्तरण, बेट, लटरी ब्यालेन्स हाम्रो H5 ले JWT सँग कल गर्छ — मुख्य साइट इन्टिग्रेसन दायरा बाहिर। तपाईंले JWT जारी र वालेट गेटवे मात्र।",
"partnerApis": "मुख्य साइट API (साझेदार कार्यान्वयन)",
"refreshNote": "iframe refresh: LOTTERY_TOKEN_NEEDED मा नयाँ JWT जारी गरी MAIN_REFRESH_TOKEN पठाउनुहोस्। main-site POST /api/auth/refresh हेर्नुहोस्।",
"authResponse": "Auth असफल response",
"errors": "Errors",
"iframeNote": "iframe_allowed_origins सेट गर्नुहोस्। token पछि LOTTERY_READY दोहोर्याउनुहोस्।",
"claimRows": [
["site_code", "string", "Y", "इन्टिग्रेसन साइट कोड"],
["site_player_id", "string", "Y", "स्थिर मुख्य साइट प्रयोगकर्ता ID"],
["iat", "number", "Y", "जारी समय (सेकेन्ड)"],
["exp", "number", "Y", "म्याद (सेकेन्ड); ≤ 300s"]
],
"messageRows": [
["→ मुख्य", "LOTTERY_READY", "चाइल्ड तयार"],
["→ मुख्य", "LOTTERY_TOKEN_NEEDED", "रिफ्रेस अनुरोध"],
["→ लटरी", "MAIN_INIT_TOKEN", "{ token }"],
["→ लटरी", "MAIN_REFRESH_TOKEN", "{ token }"]
],
"publicApiRows": [
["GET", "/api/v1/player/ping", "Player API connectivity"],
["GET", "/api/v1/integration/runtime-origins", "iframe allowlist origins"]
],
"partnerApiRows": [
["POST", "/api/auth/refresh", "(सन्दर्भ) JWT re-issue → MAIN_REFRESH_TOKEN"]
],
"errorRows": [
["8001", "Authorization छैन"],
["8002", "JWT अमान्य वा म्याद सकियो"],
["8003", "प्लेयर छैन"],
["8004", "SSO गोप्य सेट छैन"],
["8005", "खाता निलम्बित"]
]
},
"iframe": {
"title": "iframe protocol",
"description": "H5 embed गर्दा postMessage। URL redirect मात्र भए यो अध्याय छोड्न सकिन्छ।",
"sequence": "क्रम",
"envelope": "सन्देश संरचना",
"childMessages": "लटरी → मुख्य",
"parentMessages": "मुख्य → लटरी",
"targetOrigin": "targetOrigin",
"envelopeNote": "JSON। लटरी LOTTERY_*; मुख्य MAIN_*। timestamp र source सिफारिस।",
"targetOriginNote": "targetOrigin ठोस origin हुनुपर्छ, * होइन। iframe_allowed_origins मा मात्र।",
"timingNote": "MAIN_INIT_TOKEN पछि LOTTERY_READY दोहोर्याउनुहोस्। LOTTERY_TOKEN_NEEDED / LOTTERY_TOKEN_REFRESH_REQUEST → MAIN_REFRESH_TOKEN।",
"sequenceSteps": [
"iframe embed",
"LOTTERY_READY",
"MAIN_INIT_TOKEN",
"/player/me",
"LOTTERY_TOKEN_NEEDED → MAIN_REFRESH_TOKEN"
],
"childMessageRows": [
["→ मुख्य", "LOTTERY_READY", "तयार"],
["→ मुख्य", "LOTTERY_TOKEN_NEEDED", "रिफ्रेस"],
["→ मुख्य", "LOTTERY_TOKEN_REFRESH_REQUEST", "सक्रिय रिफ्रेस"],
["→ मुख्य", "LOTTERY_HEARTBEAT", "हार्टबिट"],
["→ मुख्य", "LOTTERY_TOKEN_REFRESHED", "रिफ्रेस सफल"]
],
"parentMessageRows": [
["→ लटरी", "MAIN_INIT_TOKEN", "{ token }"],
["→ लटरी", "MAIN_REFRESH_TOKEN", "{ token }"],
["→ लटरी", "MAIN_REQUEST_STATUS", "स्थिति"],
["→ लटरी", "MAIN_NAVIGATE", "{ path }"]
]
},
"wallet": {
"title": "Wallet gateway",
"description": "साझेदारले कार्यान्वयन। लटरी server-to-server। Auth: Bearer wallet_api_key।",
"balance": "GET balance",
"debit": "POST debit",
"credit": "POST credit",
"response": "Response",
"httpContract": "HTTP contract",
"httpErrors": "HTTP errors",
"creditNote": "Body debit जस्तै; transfer-out वा refund।",
"idempotentNote": "idempotent_key: एउटै key + operation ले पहिलो JSON (HTTP 200); दोहोरो लेखा निषेध।",
"queryRows": [
["site_code", "string", ""],
["site_player_id", "string", ""],
["currency_code", "string", ""]
],
"fieldRows": [
["site_code", "string", ""],
["site_player_id", "string", ""],
["player_id", "number", "लटरी प्लेयर ID"],
["currency_code", "string", ""],
["amount_minor", "integer", "धनात्मक minor"],
["idempotent_key", "string", "इडेम्पोटेन्सी"]
],
"httpErrorRows": [
["401", "unauthorized", "API Key गलत"],
["422", "invalid request", "फिल्ड/रकम गलत"],
["409", "main balance insufficient", "व्यापार अस्वीकार; data.main_balance हुन सक्छ"]
],
"httpContractRows": [
["डेबिट/क्रेडिट सफल", "200", "success: true; external_ref_no + data.main_balance"],
["ब्यालेन्स सफल", "200", "success: true; data.main_balance + currency_code"],
["अमान्य params", "422", "success: false; message: invalid request"],
["Unauthorized", "401", "success: false; message: unauthorized"],
["व्यापार अस्वीकार", "409", "success: false; message"],
["इडेम्पोटेन्ट replay", "200", "पहिलो response जस्तै JSON"]
]
},
"transfer": {
"title": "स्थानान्तरण (सन्दर्भ)",
"description": "आन्तरिक: लटरी H5 ले कल गर्छ, साझेदार इन्टिग्रेसन होइन।",
"outOfScopeNote": "साझेदारले यी API कार्यान्वयन गर्नुपर्दैन। transfer हाम्रो H5 ले JWT सँग कल गर्छ; तपाईंले वालेट गेटवे debit/credit मात्र।",
"requestFields": "अनुरोध फिल्ड",
"transferIn": "transfer-in",
"transferOut": "transfer-out",
"transferResponse": "सफल response",
"errors": "सामान्य त्रुटि",
"inNote": "लटरी debit-for-lottery → लटरी भित्र क्रेडिट।",
"outNote": "लटरी डेबिट → credit-from-lottery।",
"responseNote": "transfer-in/out एउटै संरचना; direction in/out। इडेम्पोटेन्ट replay एउटै data।",
"requestFieldRows": [
["amount", "integer", "धनात्मक minor"],
["currency", "string", "वैकल्पिक; default_currency"],
["idempotent_key", "string", "अद्वितीय; retry एउटै नतिजा"]
],
"errorRows": [
["1001", "लटरी ब्यालेन्स अपर्याप्त (transfer-out)"],
["1009", "मुख्य वालेट असफल"],
["1010", "इडेम्पोटेन्सी द्वन्द्व"],
["2003", "पहिले transfer-in"]
]
},
"errors": {
"title": "Errors",
"sso": "SSO",
"lotteryWallet": "Lottery wallet",
"gateway": "Wallet gateway (HTTP)",
"idempotentNote": "एउटै idempotent_key ले एउटै नतिजा; फरक रकम → 1010।",
"ssoRows": [
["8001", "Authorization छैन"],
["8002", "JWT अमान्य वा म्याद सकियो"],
["8003", "प्लेयर छैन"],
["8004", "SSO गोप्य सेट छैन"],
["8005", "खाता निलम्बित"]
],
"lotteryRows": [
["1001", "लटरी ब्यालेन्स अपर्याप्त"],
["1009", "मुख्य वालेट असफल"],
["1010", "इडेम्पोटेन्सी द्वन्द्व"],
["2003", "पहिले transfer-in"]
],
"gatewayRows": [
["401", "unauthorized", "API Key गलत"],
["422", "invalid request", "फिल्ड/रकम गलत"],
["409", "—", "व्यापार अस्वीकार"]
]
},
"golive": {
"title": "Go-live",
"checklist": "Checklist",
"items": [
"परीक्षण/प्रोडक्सन site_code, गोप्य, डोमेन अलग",
"JWT सर्वर-साइड मात्र, TTL ≤ 5min",
"वालेट HTTPS, timeout ≤ 10s",
"idempotent_key इडेम्पोटेन्सी",
"iframe: iframe_allowed_origins",
"पूर्ण: transfer-in → bet → settle → transfer-out"
]
}
}
}