Կատալոգ, զամբյուղ և checkout

01Կատալոգը՝ ապրանքներ, տարբերակներ և ատրիբուտներ

Պատկերացրեք ապրանքը որպես դարակի պիտակ («Եղունգների լաք»), իսկ տարբերակը (variant)՝ որպես այն իրական իրը, որը դնում եք տուփի մեջ («Եղունգների լաք, կարմիր, 15 ml»)։ Հաճախորդները դիտում են ապրանքները, բայց դուք վաճառում, պահում և գնագոյացնում եք տարբերակները․ յուրաքանչյուր տարբերակ ունի իր SKU-ն (stock-keeping unit՝ եզակի կոդ), գինը և մնացորդը։ Ատրիբուտները նկարագրում են տարբերակները՝ գույն, չափս, քաշ, համ։ Ատրիբուտները ատրիբուտների ընտանիքների մեջ խմբավորելը («հագուստն» ունի չափս և գույն, «կենդանիների կերը»՝ քաշ և համ) ադմինը կարգին է պահում։ Կատեգորիաները կազմում են ծառ (Շներ → Կեր → Չոր կեր)․ պահեք դրանք nested-set-ով կամ parent_id-ով և cache-ավորված ճանապարհով (path), որպեսզի «Շներ-ի տակ գտնվող բոլոր ապրանքները» լինի մեկ query։ Բրենդները, թեգերը և հավաքածուները առանձին many-to-many կապեր են, ոչ թե լրացուցիչ կատեգորիաներ։

• Ապրանք՝ անուն, նկարագրություն, նկարներ, SEO դաշտեր, կապեր կատեգորիաների հետ։
• Տարբերակ՝ SKU, ատրիբուտների արժեքներ, գին, քաշ, շտրիխ-կոդ, կապ մնացորդի հետ։
• Որոշ ապրանքներ վաճառվում են տուփերով կամ քաշով․ վաճառքի միավորը մոդելավորեք բացահայտ՝ քանակների հետ հնարքներ անելու փոխարեն։

02Գումար՝ ամբողջ թվեր, արժույթներ և հարկեր

Երբեք մի պահեք գումարը float-ով։ Երկուական լողացող ստորակետով 0.1 + 0.2-ը 0.3 չէ, և այդ փոքրիկ սխալները գումարվում են ու դառնում հաշվապահական իրական տարբերություններ։ Պահեք գումարները ամբողջ թվերով՝ ամենափոքր միավորով (ցենտեր, կամ ամբողջ դրամներ այն արժույթների համար, որոնք մանր միավոր չունեն), ISO 4217 արժույթի կոդի հետ միասին, և թվաբանությունն արեք money գրադարանով կամ value object-ով։ Մեկ անգամ որոշեք՝ կատալոգի գներն ներառո՞ւմ են հարկը (տարածված է Եվրոպայի, Հայաստանի և Ավստրալիայի սպառողական խանութներում), թե՞ ոչ (տարածված է ԱՄՆ-ում), և հարկը հաշվարկեք յուրաքանչյուր տողի համար՝ կլորացման հստակ կանոնով։ Պատվերի տողի վրա պահեք յուրաքանչյուր գնի, զեղչի և հարկի snapshot-ը․ կատալոգը վաղը կփոխվի, բայց պատվերը դեռ պետք է ցույց տա, թե ինչ է վճարել հաճախորդը։

1// Money as a small value object: integer minor units + currency
2type Money = { amount: number; currency: "USD" | "EUR" | "AMD" };
3 
4const add = (a: Money, b: Money): Money => {
5  if (a.currency !== b.currency) throw new Error("Currency mismatch");
6  return { amount: a.amount + b.amount, currency: a.currency };
7};
8 
9// Tax included in the price: extract it with one explicit rounding rule
10const taxIncluded = (gross: Money, ratePercent: number): Money => ({
11  amount: Math.round((gross.amount * ratePercent) / (100 + ratePercent)),
12  currency: gross.currency,
13});
14 
15const line = { amount: 1999, currency: "USD" } as const; // $19.99
16console.log(taxIncluded(line, 20)); // { amount: 333, currency: "USD" }

03Զամբյուղը՝ հյուրեր, միավորում և վալիդացիա

Թույլ տվեք մարդկանց գնումներ անել առանց հաշվի։ Հյուրի զամբյուղն ապրում է սերվերում և նույնականացվում է պատահական token-ով, որը պահվում է cookie-ում (վեբ) կամ secure storage-ում (հավելված)։ Սերվերում պահելը նշանակում է, որ գներն ու կանոնները հաշվարկվում են մեկ տեղում, և login-ից հետո զամբյուղը հետևում է օգտատիրոջը տարբեր սարքերում։ Երբ հյուրը մուտք է գործում, միավորեք՝ հյուրի տողերը ավելացրեք հաշվի զամբյուղին, նույն տարբերակի քանակները գումարեք, ապա ջնջեք հյուրի զամբյուղը։ Զամբյուղին վերաբերվեք որպես ցանկության, ոչ թե խոստման։ Ամեն անգամ, երբ այն կարդացվում է, և միշտ checkout-ի ժամանակ, նորից վալիդացրեք այն․ տարբերակը դեռ ակտի՞վ է, մնացորդը բավարա՞ր է, գինը փոխվե՞լ է, մասնաճյուղը բա՞ց է, նվազագույն պատվերի գումարը ապահովվա՞ծ է։ Վերադարձրեք հստակ հաղորդագրություններ («Գինը փոխվել է 12.00-ից 13.50»)՝ լուռ ուղղելու փոխարեն։

• Զամբյուղում պահեք տարբերակների ID-ներն ու քանակները, երբեք մի վստահեք client-ից եկած գներին։
• Յուրաքանչյուր response-ի համար ընդհանուր գումարները վերահաշվարկեք սերվերում։
• Առաջարկեք կրկնել պատվերը՝ անցյալ պատվերի տողերը պատճենեք զամբյուղ, ապա վալիդացրեք սովորականի պես։

04Checkout և պատվերի state machine

Checkout-ը հավաքում է այն, ինչ պետք է պատվերին՝ կոնտակտ, հասցե կամ վերցնելու կետ, առաքման ժամային միջակայք, վճարման եղանակ, ապա ստեղծում է պատվերը մեկ տվյալների բազայի transaction-ում՝ պատճենում է զամբյուղի տողերը գների snapshot-ներով, ռեզերվում է մնացորդը, պահում ընդհանուր գումարները և կարգավիճակը դնում «սպասում է վճարման»։ Այդ պահից պատվերը շարժվում է բացահայտ state machine-ով։ State machine-ը պարզապես թույլատրված կարգավիճակների և դրանց միջև թույլատրված անցումների ցուցակ է։ Այն գրի առնելը կանխում է անհեթեթություններ, օրինակ՝ չեղարկված պատվերը դառնում է առաքված, և յուրաքանչյուր անցում գրանցվում է status history աղյուսակում՝ ով և երբ։ Կողմնակի էֆեկտները՝ email-ներ, push, խոհանոցի էկրաններ, ERP export, կախված են անցումներից, իդեալում՝ queue-ի job-երի միջոցով։

1const transitions = {
2  pending_payment: ["paid", "cancelled"],
3  paid: ["preparing", "refunded"],
4  preparing: ["ready", "cancelled"],
5  ready: ["out_for_delivery", "picked_up"],
6  out_for_delivery: ["delivered", "failed_delivery"],
7  delivered: ["refunded"],
8} as const;
9 
10type Status = keyof typeof transitions | "cancelled" | "refunded" | "picked_up" | "failed_delivery";
11 
12export function canMove(from: Status, to: Status): boolean {
13  const allowed = (transitions as Record<string, readonly string[]>)[from] ?? [];
14  return allowed.includes(to);
15}

05Առաքում, վերցնում տեղից և ժամային միջակայքեր

Fulfilment-ն այն տեղն է, որտեղ խանութներն ամենաշատն են տարբերվում։ Առաքման համար պետք է հասցե, գոտի և վճար։ Գոտիները սովորաբար քարտեզի վրա պոլիգոններ են․ geocode արեք հասցեն կոորդինատների, ապա ստուգեք, թե որ պոլիգոնն է պարունակում կետը, որպեսզի ստանաք վճարը, նվազագույն պատվերը և սպասարկող մասնաճյուղը։ Տեղից վերցնելու (takeaway) համար պետք է մասնաճյուղ և գուցե ապրանքների ցուցակ, որը տարբերվում է ըստ մասնաճյուղի։ Ժամային միջակայքերը աշխատանքային ժամերը վերածում են ընտրելի պատուհանների՝ «հնարավորինս շուտ» կամ պլանավորված՝ 15 կամ 30 րոպե քայլով, հաշվի առնելով պատրաստման ժամանակը, փակման ժամը և «աշխատանքային օրը», որը կարող է ավարտվել կեսգիշերից հետո։ Միջակայքերը գեներացրեք սերվերում՝ խանութի ժամային գոտով, և ընտրված միջակայքը checkout-ում նորից վալիդացրեք․ միջակայքը, որն ազատ էր էջը բեռնելիս, մեկ րոպե անց կարող է արդեն զբաղված լինել։

06Overselling-ի կանխում և ճիշտ email-ների ուղարկում

Overselling-ը տեղի է ունենում, երբ երկու հաճախորդ նույն պահին գնում են վերջին ապրանքը։ Լուծումը մնացորդի փոփոխությունն ատոմար դարձնելն է։ Կամ lock արեք տողը (SELECT … FOR UPDATE transaction-ի ներսում), կամ օգտագործեք պայմանական update, որը հաջողվում է միայն այն դեպքում, երբ բավարար մնացորդ կա, և ստուգեք ազդված տողերի քանակը։ Ռեզերվեք մնացորդը պատվերը ստեղծելիս և ազատեք այն, եթե վճարումը ձախողվի կամ ժամանակը լրանա․ պլանավորված job-ը չեղարկում է լքված, վճարման սպասող պատվերները։ Transactional email-ները՝ պատվերն ընդունված է, վճարված է, ուղարկված է, գումարը վերադարձված է, պետք է ուղարկվեն queue-ից transaction-ի commit-ից հետո, որպեսզի դանդաղ mail սերվերը երբեք չարգելափակի checkout-ը, և email չուղարկվի rollback արված պատվերի համար։

1-- Atomic decrement: succeeds only when enough stock is left
2UPDATE stock_levels
3SET quantity = quantity - 2
4WHERE variant_id = 42
5  AND warehouse_id = 1
6  AND quantity >= 2;
7-- 1 row affected → reserved; 0 rows → out of stock, tell the customer

07Idempotent պատվերի ստեղծում. երկակի սեղմումներից և retry-ներից պաշտպանություն

Հաճախորդը երկու անգամ սեղմում է «Պատվիրել», mobile app-ը timeout-ից հետո կրկնում է հարցումը, load balancer-ը նորից է ուղարկում request-ը։ Առանց պաշտպանության դրանցից յուրաքանչյուրը կարող է ստեղծել երկրորդ պատվեր և երկու անգամ ռեզերվել մնացորդը։ Լուծումը checkout key-ն է. client-ը checkout-ի էկրանը բացելիս գեներացնում է պատահական UUID և ուղարկում այն submit հարցման հետ։ Սերվերը պահում է այն պատվերի վրա unique constraint-ով։ Առաջին հարցումը ստեղծում է պատվերը, իսկ նույն key-ով ցանկացած կրկնություն վերադարձնում է արդեն գոյություն ունեցող պատվերը՝ նորը չստեղծելով։ Key-ը պահեք checkout-ի այդ փորձի ողջ ընթացքում և նորը գեներացրեք միայն այն ժամանակ, երբ զամբյուղը փոխվում է։ Սրան ավելացրեք կարճ lock յուրաքանչյուր զամբյուղի համար (Redis lock կամ advisory lock), որպեսզի երկու զուգահեռ հարցումներ միաժամանակ չանցնեն վալիդացիան, մինչև դրանցից որևէ մեկը կգրանցի պատվերը։

1-- One order per checkout attempt, enforced by the database
2ALTER TABLE orders ADD COLUMN checkout_key UUID;
3CREATE UNIQUE INDEX orders_checkout_key_uq ON orders (checkout_key);
4 
5-- Inside the checkout transaction
6INSERT INTO orders (checkout_key, customer_id, status, total_amount, currency)
7VALUES ($1, $2, 'pending_payment', $3, $4)
8ON CONFLICT (checkout_key) DO NOTHING
9RETURNING id;
10-- No row returned → a previous request already created it:
11-- SELECT id FROM orders WHERE checkout_key = $1 and return that order.

08Զեղչերի բաշխում և կլորացում առանց մեկ ցենտ կորցնելու

Զամբյուղի մակարդակի զեղչը («5.00 զեղչ ամբողջ պատվերից») պետք է բաշխվի տողերի միջև, որովհետև հարկը, refund-ները և ERP export-ները աշխատում են տող առ տող։ Բաշխեք այն յուրաքանչյուր տողի արժեքին համամասնորեն, յուրաքանչյուր բաժին կլորացրեք ներքև, ապա մնացած ցենտերը տվեք ամենամեծ մնացորդ ունեցող տողերին։ Բաժինների գումարը միշտ ճշգրիտ հավասար է զեղչին, և հետագայում մեկ տողի մասնակի refund-ը վերադարձնում է հենց այն գումարը, որը գանձվել է այդ տողի համար։ Հաշվի առեք նաև արժույթի minor unit-ը ըստ ISO 4217-ի. արժույթների մեծ մասն ունի 2 տասնորդական նիշ, ճապոնական իենը՝ 0, իսկ քուվեյթական դինարը՝ 3։ Երբեք hard-code մի արեք «բաժանել 100-ի»։ Բազմարժույթ խանութների համար պատվերի վրա պահեք փոխարժեքի snapshot-ը և որոշեք՝ արդյոք միայն փոխարկում եք գները (ցուցադրման արժույթ), թե իրականում գանձում եք այդ արժույթով (settlement-ի արժույթ)։

1// Split an integer amount across weights; parts always sum to the total
2export function allocate(total: number, weights: number[]): number[] {
3  const sum = weights.reduce((a, b) => a + b, 0);
4  const raw = weights.map((w) => (total * w) / sum);
5  const parts = raw.map(Math.floor);
6  let rest = total - parts.reduce((a, b) => a + b, 0);
7  const order = raw
8    .map((r, i) => ({ i, frac: r - Math.floor(r) }))
9    .sort((a, b) => b.frac - a.frac);
10  for (const { i } of order) {
11    if (rest-- <= 0) break;
12    parts[i] += 1;
13  }
14  return parts;
15}
16 
17allocate(500, [1999, 999, 2]); // [333, 167, 0] → sums to 500

09Read model-ներ կատալոգի արագ էջերի համար

Կատեգորիայի էջը, որն ամեն հարցման ժամանակ join է անում ապրանքները, տարբերակները, գները, մնացորդը, նկարները և ակցիաները, կատալոգի աճին զուգընթաց դառնում է դանդաղ։ Սովորական պատասխանը read model-ն է. denormalized աղյուսակ (կամ search index-ի document), որտեղ յուրաքանչյուր ապրանքի համար մեկ տող է՝ ճիշտ այն տվյալներով, որոնք պետք են ցուցակին. նվազագույն գինը, «առկա է» դրոշը, գլխավոր նկարը, ֆիլտրերի համար ատրիբուտների արժեքները, վարկանիշը։ Background job-երը թարմացնում են այն, երբ աղբյուր տվյալները փոխվում են, իսկ storefront-ը կարդում է միայն այս աղյուսակը։ Render արված ֆրագմենտները կամ API պատասխանները cache արեք tag-երով, որպեսզի գնի փոփոխությունը invalidate անի միայն համապատասխան ապրանքները։ Write model-ը (normalized աղյուսակներ, transaction-ներ) թողեք որպես ճշմարտության աղբյուր. read model-ը միշտ կարելի է նորից կառուցել դրանից։ Այս բաժանումը, որը երբեմն կոչվում է CQRS (command query responsibility segregation), թույլ է տալիս scale անել ընթերցումները՝ առանց checkout-ը բարդացնելու։

• Գնի, մնացորդի կամ բովանդակության փոփոխությունից հետո ապրանքի read տողը նորից կառուցեք queue-ի job-ում։
• Խորը էջերի համար ցուցակները paginate արեք keyset pagination-ով (WHERE id > last_id)։
• Ցուցակի յուրաքանչյուր ապրանքի համար երբեք live մի հաշվեք ակցիոն գները. badge-երը նախապես հաշվարկեք։

10Անվտանգության եզրային դեպքեր զամբյուղներում և պատվերներում

Զամբյուղներն ու պատվերները insecure direct object reference-ի (IDOR) դասական թիրախ են. /orders/1042-ը փոխում ես /orders/1043-ի և տեսնում ուրիշի պատվերը։ URL-ներում օգտագործեք չգուշակվող հանրային իդենտիֆիկատորներ (UUID-ներ կամ պատահական token-ներ) և միշտ սահմանափակեք query-ները ըստ սեփականատիրոջ։ Օգտատիրոջ login-ի պահին փոխեք guest զամբյուղի token-ը, որպեսզի մինչև login-ը որսացված token-ով հնարավոր չլինի կարդալ account-ի զամբյուղը։ Քանակները վալիդացրեք որպես դրական ամբողջ թվեր՝ վերին սահմանով. վատ կառուցված խանութներում բացասական քանակները իրական refund-ների են հանգեցրել։ Rate limit դրեք կուպոնի և checkout-ի endpoint-ների վրա՝ դանդաղեցնելու brute force-ը և card testing-ը, երբ հարձակվողները գողացված քարտերը փորձարկում են փոքր պատվերներով։ Եվ վերջապես, պատվերներում անձնական տվյալները պահեք նվազագույն ծավալով և պլանավորեք, թե որքան ժամանակ եք դրանք պահելու, որովհետև պատվերների աղյուսակները աննկատ դառնում են անձնական տվյալների ձեր ամենամեծ պահոցը։