ক্যাপস্টোন — একটি পূর্ণ অনলাইন বাজার: নকশা থেকে deployment

১ · Brief আর scope — বাজারঘর কী, কী নয়

গ্রামের হাটের কথা ভাবুন। একজন দোকানির লাগে চারটি জিনিস: মাল সাজানো, ক্রেতার দেখা আর বাছাই, দাম নেওয়া আর হিসাব খাতা। বাজারঘর ঠিক এমন একটি ছোট দোকান: বিশটি দেশি পণ্য, দুজন মানুষ (একজন ক্রেতা, একজন পরিচালক), আর পুরো পথ, পণ্য খোঁজা থেকে পেমেন্টের রসিদ পর্যন্ত।

এই পর্বটি একটি ক্যাপস্টোন: কোর্সের প্রায় সব মডিউল একটি প্রকল্পে জোড়া লাগে। ধাপে ধাপে কোড নয়; থাকছে brief, ছয়টি milestone, যাচাইয়ের উপায় আর কোন পর্বে ফিরবেন। পাশে আছে আমাদের নিজের একটি reference implementation: প্রায় ১,২৭০ লাইনের একটি আসল Next.js প্রকল্প, যা এই পাতা লেখার আগে বানিয়ে চালানো হয়েছে। পাতার প্রতিটি আউটপুট সেখান থেকে নেওয়া। এটি নকলের জন্য নয়, নিজের উত্তর মেলানোর জন্য।

Product brief — এক পাতায়

Must-have বনাম nice-to-have

বেশিরভাগ শেখার প্রকল্প শেষ হয় না ফিচারের অভাবে নয়, ফিচারের ভারে। প্রতি সপ্তাহে “আর একটা ছোট জিনিস” ঢোকে, যাকে বলে scope creep, আর শেষে কোনোটাই পুরো চলে না। তাই শুরুতেই কাজগুলো MoSCoW পদ্ধতিতে ভাগ করুন: Must (না থাকলে প্রকল্পই নয়), Should (গুরুত্বপূর্ণ, কিন্তু ছাড়া চলে), Could (সময় থাকলে), Won't (এবার নয়, লিখে রাখুন)। এটিই MVP-এর সংজ্ঞা।

লেখার সময়ের version

Reference app-এর সত্যিকারের run-এ ব্যবহার হয়েছে: Node 24.15.0, Next.js 16.4.4 (App Router, Turbopack, create-next-app-এর ডিফল্ট Cache Components চালু), React 19.3.0, TypeScript 5.9.3, Tailwind CSS 4.3.4, Prisma 7.10.1 আর @prisma/adapter-pg, Zod 4.6.7, Nodemailer 10.3.1, smtp-server 3.21.3, Vitest 5.1.0, Playwright 1.64.1 (Microsoft Edge 156-এ), Lighthouse 13.6.0. Database আসল PostgreSQL 18.6, চলেছে npm-এর embedded-postgres 18.6.0-beta.19-এ; এটি beta, শুধু শেখার ল্যাবের জন্য। Prisma-র npm latest এখন 8-এর release candidate, তাই stable 7.10.1. (লেখার দিন 16.4.5-ও এসেছিল; কোর্সের সাথে মেলাতে 16.4.4.) সব server চলেছে শুধু 127.0.0.1-এ, কাজ শেষে নিজের process ID ধরে বন্ধ করা হয়েছে। Docker এই মডিউলে ব্যবহার হয়নি।

শুরুতেই প্রথম আসল বাধা এল। create-next-app @types/node@^20 বসায়, আর Vitest 5.1 চায় 22 বা 24-এর ওপরে, তাই npm থামল:

npm error Could not resolve dependency:
npm error peerOptional @types/node@"^22.0.0 || >=24.0.0" from vitest@5.1.0

সমাধান --force নয়; Node 24 চলছে, তাই @types/node@^24. এমন দ্বন্দ্ব প্রায় প্রতিটি নতুন প্রকল্পে আসে (পর্ব ৫)।

২ · ডেটা মডেল আর folder-এর গঠন

কোডের আগে কাগজে টেবিল আঁকুন: কী আলাদা টেবিল, কী কীভাবে জোড়া, কোন নিয়ম database নিজেই পাহারা দেবে। বাজারঘরের সাতটি টেবিল নিচের ER ডায়াগ্রামে (তত্ত্ব আছে DBMS কোর্সের ER পর্বে, আর দোকানের মডেল পর্ব ৪১-এ):

তিনটি নকশার সিদ্ধান্ত লক্ষ করুন। এক, OrderItem.unitPricePaisa: অর্ডারের সময়ের দাম আলাদা করে রাখা। দুই, Session.id-এ টোকেন নয়, টোকেনের SHA-256. Database ফাঁস হলেও চালু session চুরি হয় না। তিন, WebhookEvent.id হলো gateway-এর পাঠানো event id, primary key হিসেবে। একই event দ্বিতীয়বার ঢোকাতে গেলে database নিজেই আটকায়; এটাই idempotent webhook-এর ভিত্তি। Schema-র দুটি মডেল (সত্যিকারের ফাইল থেকে, অংশ):

enum OrderStatus {
  PENDING_PAYMENT
  PAID
  SHIPPED
  DELIVERED
  CANCELLED
  REFUNDED
}

model Product {
  id         Int         @id @default(autoincrement())
  slug       String      @unique
  name       String
  pricePaisa Int
  stock      Int
  cartItems  CartItem[]
  orderItems OrderItem[]
}

model Order {
  id            Int         @id @default(autoincrement())
  userId        Int
  user          User        @relation(fields: [userId], references: [id])
  status        OrderStatus @default(PENDING_PAYMENT)
  subtotalPaisa Int
  discountPaisa Int
  deliveryPaisa Int
  totalPaisa    Int
  coupon        String?
  phone         String
  address       String
  createdAt     DateTime    @default(now())
  items         OrderItem[]
  @@index([userId])
  @@index([status, createdAt])
}

Prisma-র schema-য় CHECK constraint লেখা যায় না, তাই দ্বিতীয় একটি migration হাতে লেখা হয়েছে (migrate dev --create-only, তারপর SQL). এতে কোডে কোনো ভুল থাকলেও স্টক কখনো শূন্যের নিচে যাবে না:

-- Stock can never go below zero, even if application code has a bug.
ALTER TABLE "Product" ADD CONSTRAINT "Product_stock_nonnegative" CHECK ("stock" >= 0);
ALTER TABLE "CartItem" ADD CONSTRAINT "CartItem_qty_positive" CHECK ("qty" > 0);

খালি database-এ দুটি migration চালানোর সত্যিকারের আউটপুট (Prisma 7.10.1, migrate deploy, যেমন production-এ চলবে):

~/bazarghar$ npx prisma migrate deploy
Loaded Prisma config from prisma7.config.ts.
Datasource "db": PostgreSQL database "bazarghar_capstone", schema "public" at "127.0.0.1:47188"
Applying migration `20261104092755_init`
Applying migration `20261104092809_stock_nonnegative`

The following migration(s) have been applied:

migrations/
  └─ 20261104092755_init/
    └─ migration.sql
  └─ 20261104092809_stock_nonnegative/
    └─ migration.sql

All migrations have been successfully applied.
~/bazarghar$ npx prisma db seed
seeded 2 users, 20 products

Folder-এর গঠন

App Router-এ folder-ই route (পর্ব ৫১)। নিয়মটি সহজ রাখা হয়েছে: app/-এ শুধু পাতা, server action আর route handler; সব ব্যবসার নিয়ম lib/-এ, যাতে test সেগুলো Next.js ছাড়াই ডাকতে পারে (পর্ব ২৯-এর স্তরভাগ)।

bazarghar/
├─ app/
│  ├─ layout.tsx            lang="bn", metadata, নিচে user-এর অংশ Suspense-এ
│  ├─ page.tsx              হোম
│  ├─ products/page.tsx     তালিকা, ?q= আর ?page=
│  ├─ products/[slug]/      পণ্যের পাতা, generateMetadata
│  ├─ login/                পাতা, form, actions.ts
│  ├─ cart/                 পাতা, checkout-form.tsx, actions.ts
│  ├─ pay/[orderId]/        নকল gateway (শুধু ল্যাব)
│  ├─ orders/[id]/          অর্ডারের অবস্থা
│  ├─ admin/orders/         role যাচাই, actions.ts
│  ├─ api/webhooks/payment/route.ts
│  ├─ sitemap.ts · robots.ts · not-found.tsx
├─ components/              quantity-picker.tsx, user-nav.tsx
├─ lib/                     auth, password, db, money, catalogue,
│                           orders, payments, order-state,
│                           webhook, mail, validation
├─ prisma/                  schema.prisma, migrations/, seed.ts
├─ tests/unit · tests/component · tests/integration
├─ e2e/                     buy.spec.ts, admin.spec.ts, helpers.ts
├─ scripts/                 db.mjs, smtp-capture.mjs, webhook-check.mjs
├─ prisma7.config.ts · vitest.config.mts · playwright.config.ts
└─ .env                     নকল মান; .gitignore-এ আছে

৩ · ছয়টি milestone আর acceptance criteria

বড় কাজকে ছোট থামার জায়গায় ভাগ করুন, যাকে বলে milestone. প্রতিটির শেষে প্রকল্পটি চালানো যায় এমন অবস্থায় থাকবে; আর প্রতিটির জন্য আগে লিখুন কখন “শেষ” বলবেন: acceptance criteria, যার প্রতিটি লাইন হ্যাঁ বা না দিয়ে যাচাই করা যায়। “login ভালো কাজ করে” কোনো criterion নয়; “ভুল পাসওয়ার্ড আর অজানা email-এ হুবহু একই বার্তা আসে” একটি criterion. লেখার নিয়মের তত্ত্ব আছে Software Engineering কোর্সের user story পর্বে।

নিচের stepper-এ প্রতিটি milestone-এর শেষে reference app-এ যে প্রমাণ পাওয়া গেছে তা দেখুন। এগুলো সত্যিকারের run-এর আউটপুট, ছোট করা।

db ready bazarghar_capstone port 47188
  PostgreSQL 18.6 ... encoding UTF8
Applying migration `..._init`
Applying migration `..._stock_nonnegative`
seeded 2 users, 20 products

GET /products?page=3   → "পাতা ৩ / ৩"
GET /sitemap.xml       → /, /products, ২০টি পণ্য
GET /robots.txt        → Disallow: /cart /pay/ /admin/ …
GET /products/no-such  → "পাতাটি পাওয়া যায়নি"
                         <meta name="robots" content="noindex">

wrong password -> ইমেইল বা পাসওয়ার্ড ঠিক নয়।
unknown email  -> ইমেইল বা পাসওয়ার্ড ঠিক নয়।
cookie bg_session value length 43
  httpOnly true sameSite Lax secure true days 7
বাকি: login rate limit

✓ sells the last jar exactly once when
  two buyers press at the same time  162ms
phone "12345" → সঠিক মোবাইল নম্বর দিন (01XXXXXXXXX)
বাকি: অপরিশোধিত অর্ডারের মেয়াদ

no signature        401 {"error":"missing"}
forged amount       401 {"error":"bad-signature"}
signed, 10 min old  401 {"error":"stale"}
signed              200 {"outcome":"paid"}
same event again    200 {"outcome":"duplicate"}

Vitest      Tests  21 passed (21)
Playwright  3 passed (4.5s)
next build  ✓ Compiled successfully
Lighthouse  perf 96 · a11y 100 · bp 100 · seo 100
বাকি: CI-তে চালানো

এই হিসাব হাতে না করে একটি ছোট tracker-এ রাখুন। নিচের ব্লকে reference app-এর আসল অবস্থা বসানো আছে। নিজের প্রকল্পের check বসিয়ে চালান:

// Milestone tracker: প্রতিটি acceptance check পাস (true) বা বাকি (false)
// মানগুলো বাজারঘরের reference implementation-এর আসল অবস্থা (৪ নভেম্বর ২০২৬)
const milestones = [
  ["M1 ভিত্তি", { "migrate deploy খালি DB-তে": true, "seed: 2 user, 20 product": true,
    "বাংলা নাম DB-তে ঠিক": true, "README-তে চালানোর ধাপ": false }],
  ["M2 ক্যাটালগ", { "search আর page": true, "অজানা slug -> not found": true,
    "metadata <head>-এ": true, "sitemap.xml": true }],
  ["M3 লগইন", { "scrypt hash": true, "HttpOnly cookie": true,
    "ভুল পাসওয়ার্ডে একই বার্তা": true, "login rate limit": false }],
  ["M4 checkout", { "server-এ Zod যাচাই": true, "শেষ জার একবারই বিক্রি": true,
    "কুপন আর ডেলিভারির নিয়ম test-এ": true, "অপরিশোধিত অর্ডারের মেয়াদ": false }],
  ["M5 পেমেন্ট", { "সই ছাড়া 401": true, "replay -> duplicate": true,
    "email ধরা পড়ল": true, "email ব্যর্থ হলে আবার চেষ্টা": false }],
  ["M6 production", { "next build": true, "২৪টি test পাস": true,
    "Lighthouse a11y >= 90": true, "CI-তে চালানো": false }],
];

let done = 0, all = 0;
for (const [name, checks] of milestones) {
  const vals = Object.values(checks);
  const ok = vals.filter(Boolean).length;
  done += ok; all += vals.length;
  const bar = "█".repeat(ok) + "░".repeat(vals.length - ok);
  const todo = Object.keys(checks).filter((k) => !checks[k]);
  console.log(`${name.padEnd(14)} ${bar} ${Math.round(100 * ok / vals.length)}%` +
    (todo.length ? `  বাকি: ${todo.join(", ")}` : ""));
}
console.log(`মোট: ${done}/${all} = ${Math.round(100 * done / all)}%`);

৪ · টাকার হিসাব আর checkout — পয়সা, কুপন, Zod আর transaction

চায়ের দোকানের হিসাব খাতায় কেউ “সাড়ে বারো টাকা দশমিক শূন্য শূন্য চার” লেখেন না। কম্পিউটার কিন্তু ভগ্নাংশ ঠিকমতো রাখতে পারে না: 0.1 + 0.2 হয় 0.30000000000000004. তাই বাজারঘরে সব টাকা পয়সায়, পূর্ণসংখ্যায়: ৳১,২৫০ মানে 125000. দেখানোর সময় শুধু Intl.NumberFormat('bn-BD') দিয়ে বাংলা অঙ্ক, লাখের কমা আর ৳ (পর্ব ৫৯)। নিয়ম: ডেলিভারি ৳৬০, ছাড়ের পরে ৳২,০০০ বা বেশি হলে ডেলিভারি বিনা মূল্যে; কুপন EID10 মানে ১০% ছাড়, কেবল ৳১,০০০ বা বেশিতে, সর্বোচ্চ ৳২০০. নিচের ব্লকটি lib/money.ts-এর হুবহু একই নিয়ম, শুধু TypeScript-এর type সরানো:

// বাজারঘরের lib/money.ts-এর একই নিয়ম: সব টাকা পয়সায়, পূর্ণসংখ্যায়
const DELIVERY = 6000, FREE_FROM = 200000;                 // ৳60, ৳2,000
const COUPONS = { EID10: { percent: 10, min: 100000, maxOff: 20000 } };

function cartTotal(lines, code) {
  const subtotal = lines.reduce((s, l) => s + l.pricePaisa * l.qty, 0);
  const c = code ? COUPONS[code.trim().toUpperCase()] : undefined;
  let discount = 0, note = "";
  if (code && !c) note = "unknown coupon";
  else if (c && subtotal < c.min) note = "below minimum";
  else if (c) discount = Math.min(Math.floor(subtotal * c.percent / 100), c.maxOff);
  const after = subtotal - discount;
  const delivery = subtotal === 0 || after >= FREE_FROM ? 0 : DELIVERY;
  return { subtotal, discount, delivery, total: after + delivery, note };
}

const taka = new Intl.NumberFormat("bn-BD", {
  style: "currency", currency: "BDT", trailingZeroDisplay: "stripIfInteger" });
const ilish = { pricePaisa: 125000, qty: 1 }, rice = { pricePaisa: 42000, qty: 2 };

const cases = [
  ["rice x2", [rice], ""],
  ["rice x2 + EID10", [rice], "EID10"],
  ["ilish + rice + eid10", [ilish, rice], "eid10"],
  ["ilish x2 + EID10", [{ ...ilish, qty: 2 }], "EID10"],
];
for (const [name, lines, code] of cases) {
  const t = cartTotal(lines, code);
  console.log(name.padEnd(21), JSON.stringify(t), taka.format(t.total / 100));
}
// কেন পয়সা? ভগ্নাংশ টাকায় যোগ করলে:
console.log("0.1 + 0.2 =", 0.1 + 0.2, "| paisa: 10 + 20 =", 10 + 20);

একই function দুই জায়গায়, কিন্তু রায় একটির

কার্টের পাতায় ক্রেতা কুপন লিখতেই মোট বদলায়। এর জন্য client component-এ ঠিক এই cartTotal() চলে, কোনো server অনুরোধ ছাড়াই। কিন্তু যে সংখ্যায় টাকা কাটবে, সেটি আবার হিসাব হয় server-এ, database থেকে পড়া দামে। Browser-এর পাঠানো দাম বা মোট কখনো বিশ্বাস করা হয় না; form-এ দাম পাঠানোই হয় না, শুধু ফোন, ঠিকানা আর কুপন। Server action-এর প্রথম দুটি লাইন তাই login আর Zod (সত্যিকারের ফাইল থেকে):

'use server';
import { redirect } from 'next/navigation';
import { z } from 'zod';
import { prisma } from '@/lib/db';
import { requireUser } from '@/lib/auth';
import { checkoutSchema } from '@/lib/validation';
import { placeOrder, OutOfStockError } from '@/lib/orders';

export type CheckoutState = { errors?: Record<string, string[]>; message?: string };

export async function checkout(_prev: CheckoutState, form: FormData): Promise<CheckoutState> {
  const user = await requireUser('/cart');
  const parsed = checkoutSchema.safeParse(Object.fromEntries(form));
  if (!parsed.success) return { errors: z.flattenError(parsed.error).fieldErrors };
  let orderId: number;
  try {
    const order = await placeOrder(prisma, user.id, parsed.data);
    orderId = order.id;
  } catch (e) {
    if (e instanceof OutOfStockError) return { message: 'একটি পণ্যের স্টক এইমাত্র শেষ হয়েছে। কার্ট দেখে আবার চেষ্টা করুন।' };
    throw e;
  }
  redirect(`/pay/${orderId}`);                                 // to the (fake) gateway
}

Zod 4-এ error.flatten() পুরোনো পথ; z.flattenError() নতুন। Schema-তে ফোনের নিয়ম /^01[3-9]\d{8}$/ আর বাংলা বার্তা। redirect() try-এর বাইরে, কারণ Next.js redirect একটি বিশেষ error ছুড়ে কাজ করে; try-এর ভেতরে থাকলে catch সেটিকে গিলে ফেলতে পারত।

স্টক আটকে রাখা: একটি transaction, একটি শর্ত

শেষ খেজুরের গুড়ের জারটি রহিমা আর আরেকজন একই মুহূর্তে কিনতে চাইলেন। “আগে স্টক পড়ি, তারপর কমাই” লিখলে দুজনেই পড়বেন ১, দুজনেই কিনবেন, স্টক হবে −১; এটাই race condition আর overselling. বাজারঘরের সমাধান পর্ব ৪৩-এর: পড়া আর কমানো একটি শর্তসাপেক্ষ update-এ, “স্টক যদি অন্তত qty থাকে, তবেই কমাও”, আর পুরো অর্ডার একটি transaction-এ:

// Reserve stock and create the order in ONE transaction (পর্ব ৪৩).
export async function placeOrder(db: PrismaClient, userId: number, input: Checkout) {
  return db.$transaction(async (tx) => {
    const cart = await tx.cartItem.findMany({ where: { userId }, include: { product: true } });
    if (cart.length === 0) throw new Error('empty cart');
    for (const item of cart) {
      // Conditional decrement: succeeds only if enough stock is left at this instant.
      const r = await tx.product.updateMany({
        where: { id: item.productId, stock: { gte: item.qty } },
        data: { stock: { decrement: item.qty } },
      });
      if (r.count === 0) throw new OutOfStockError(item.productId); // rolls back everything
    }
    const lines = cart.map((i) => ({ pricePaisa: i.product.pricePaisa, qty: i.qty }));
    const t = cartTotal(lines, input.coupon);
    const order = await tx.order.create({
      data: {
        userId, phone: input.phone, address: input.address, coupon: t.coupon,
        subtotalPaisa: t.subtotal, discountPaisa: t.discount,
        deliveryPaisa: t.delivery, totalPaisa: t.total,
        items: { create: cart.map((i) => ({
          productId: i.productId, qty: i.qty, unitPricePaisa: i.product.pricePaisa,
        })) },
      },
    });
    await tx.cartItem.deleteMany({ where: { userId } });
    return order;
  });
}

PostgreSQL-এর ডিফল্ট READ COMMITTED-এ দ্বিতীয় update প্রথমটির row lock-এর জন্য অপেক্ষা করে, তারপর শর্ত আবার মিলিয়ে দেখে স্টক ০, তাই count === 0, পুরো transaction ফিরে যায়, আর ক্রেতা বাংলা বার্তা পান। দাবিটি একটি integration test-এ আসল database-এ যাচাই করা হয়েছে; আলাদা bazarghar_test database, একই migration দিয়ে বানানো:

it('sells the last jar exactly once when two buyers press at the same time', async () => {
  const results = await Promise.allSettled([placeOrder(prisma, a, addr), placeOrder(prisma, b, addr)]);
  expect(results.filter((r) => r.status === 'fulfilled')).toHaveLength(1);
  const lost = results.find((r) => r.status === 'rejected') as PromiseRejectedResult;
  expect(lost.reason).toBeInstanceOf(OutOfStockError);
  expect((await prisma.product.findUniqueOrThrow({ where: { id: gur } })).stock).toBe(0);
  expect(await prisma.order.count()).toBe(1);
});

৫ · পেমেন্ট, webhook আর email — একটি অর্ডারের পুরো পথ

আসল gateway-তে ক্রেতা আপনার সাইট ছেড়ে gateway-এর পাতায় যান, টাকা দেন, আর gateway আলাদাভাবে আপনার server-কে জানায়: “অর্ডার ৩-এর ২,৩০০ টাকা পেয়েছি”। এই খবরটিই webhook. Browser-এর redirect যে কেউ বানাতে পারেন, তাই বিশ্বাস শুধু সই করা webhook-এ। এই ল্যাবে কোনো আসল gateway নেই। তার বদলে /pay/[orderId] পাতাটি gateway-এর ভূমিকা নেয়: “পরিশোধ করুন” চাপলে একটি server action ঠিক আসল gateway-এর মতো body বানায়, HMAC-SHA256 দিয়ে সই করে আর নিজের webhook-এ POST করে। Header-এর রূপ পর্ব ৬৫-এর BazarPay মডেলের: x-bazarpay-signature: t=<সময়>,v1=<hex>. বাংলাদেশের কোনো আসল gateway-এর API বা নিয়ম এখানে নকল করা হয়নি।

নিচের stepper-এ reference app-এর একটি আসল অর্ডার, #৩, Playwright-এর একটি run থেকে, ধাপে ধাপে:

where: OR [ name contains "ilish" (insensitive),
            slug contains "ilish" ]
skip 0, take 8   +   count
→ ১টি পণ্য · পাতা ১ / ১
  পদ্মার ইলিশ (১ কেজি)  ১,২৫০৳

requireUser()              → রহিমা
addToCartSchema.parse()    → productId 1, qty 2
cartItem.upsert(...)       → qty 2
redirect('/cart')
মোট (client preview): ২,৩০০৳ (EID10)

BEGIN
UPDATE "Product" SET stock = stock - 2
 WHERE id = 1 AND stock >= 2      → 1 row (10 → 8)
INSERT "Order" total 230000, PENDING_PAYMENT → #3
INSERT "OrderItem" ; DELETE "CartItem"
COMMIT

body = {"id":"evt_71a55e6c-…","type":"payment.succeeded",
        "orderId":3,"amountPaisa":230000}
t    = এখনকার Unix সময়
x-bazarpay-signature: t=…,v1=HMAC(secret, t + "." + body)
POST /api/webhooks/payment

সই মেলে, সময় ৩০০ s-এর ভেতরে        ✓
Zod: event-এর রূপ ঠিক                ✓
অঙ্ক 230000 = অর্ডারের মোট          ✓
INSERT "WebhookEvent" (id = evt_…)   ✓ নতুন
PENDING_PAYMENT → PAID
{"msg":"webhook","event":"evt_71a55e6c-…","order":3,"outcome":"paid"}

captured ./mail-out/002.eml to rahima@example.com
Subject: অর্ডার #৩ নিশ্চিত — ২,৩০০৳
Content-Transfer-Encoding: base64
পর্দায় অর্ডারের অবস্থা: পরিশোধিত

Webhook-এর route handler, পুরোটা (সত্যিকারের ফাইল):

import { prisma } from '@/lib/db';
import { verify } from '@/lib/webhook';
import { webhookEventSchema } from '@/lib/validation';
import { applyPaymentEvent } from '@/lib/payments';
import { sendOrderPaidEmail } from '@/lib/mail';

export async function POST(req: Request) {
  const raw = await req.text();                       // verify the exact bytes, before JSON.parse
  if (raw.length > 10_000) return Response.json({ error: 'too large' }, { status: 413 });
  const check = verify(raw, req.headers.get('x-bazarpay-signature'),
    process.env.WEBHOOK_SECRET!, Math.floor(Date.now() / 1000));
  if (!check.ok) return Response.json({ error: check.reason }, { status: 401 });

  let json: unknown;
  try { json = JSON.parse(raw); } catch { return Response.json({ error: 'bad json' }, { status: 400 }); }
  const evt = webhookEventSchema.safeParse(json);
  if (!evt.success) return Response.json({ error: 'bad event' }, { status: 400 });

  const outcome = await applyPaymentEvent(prisma, evt.data);
  console.log(JSON.stringify({ msg: 'webhook', event: evt.data.id, order: evt.data.orderId, outcome }));
  if (outcome === 'no-order' || outcome === 'amount-mismatch') {
    return Response.json({ outcome }, { status: 422 });
  }
  if (outcome === 'paid') {
    // Known gap: sent inline. A failed send is logged, not retried (see the outbox stretch goal).
    await sendOrderPaidEmail(evt.data.orderId).catch((e) => console.error('mail failed', e.message));
  }
  return Response.json({ outcome });                  // 200 also for duplicates: the gateway stops retrying
}

verify() সময়ের পার্থক্য ৩০০ সেকেন্ডের বেশি হলে stale বলে, আর তুলনা করে timingSafeEqual দিয়ে, যাতে উত্তর দেওয়ার সময় দেখে সই অনুমান করা না যায় (Cybersecurity কোর্সের hash ও MAC পর্ব)। applyPaymentEvent() একটি transaction-এ অঙ্ক মেলায়, WebhookEvent লেখে আর অবস্থা বদলায়; একই id আবার এলে Prisma-র P2002 ধরে duplicate. অবস্থার নিয়মটি একটি ছোট state machine. নিচের ব্লকে database ছাড়া একই নিয়ম, চারটি event দিয়ে:

// বাজারঘরের lib/order-state.ts আর lib/payments.ts-এর নিয়ম, database ছাড়া
const NEXT = {
  PENDING_PAYMENT: ["PAID", "CANCELLED"], PAID: ["SHIPPED", "REFUNDED"],
  SHIPPED: ["DELIVERED"], DELIVERED: [], CANCELLED: [], REFUNDED: [],
};
const seen = new Set();                      // আসল app-এ WebhookEvent table-এর primary key
const stock = { ilish: 10 };

function apply(order, e) {
  if (order.total !== e.amount) return "amount-mismatch";
  if (seen.has(e.id)) return "duplicate";
  seen.add(e.id);
  const to = e.type === "payment.succeeded" ? "PAID" : "CANCELLED";
  if (!NEXT[order.status].includes(to)) return "ignored";
  order.status = to;
  if (to === "CANCELLED") stock.ilish += order.qty;   // আটকে রাখা স্টক ফেরত
  return to === "PAID" ? "paid" : "cancelled";
}

const order = { id: 3, status: "PENDING_PAYMENT", total: 230000, qty: 2 };
stock.ilish -= order.qty;                    // checkout-এর transaction: 10 -> 8
const events = [
  { id: "evt_a", type: "payment.succeeded", amount: 1 },        // জাল অঙ্ক
  { id: "evt_b", type: "payment.succeeded", amount: 230000 },
  { id: "evt_b", type: "payment.succeeded", amount: 230000 },   // gateway আবার পাঠাল
  { id: "evt_c", type: "payment.failed", amount: 230000 },      // দেরিতে আসা ব্যর্থতা
];
for (const e of events) {
  const out = apply(order, e);
  console.log(`${e.id} ${e.type.padEnd(17)} -> ${out.padEnd(15)} status=${order.status} stock=${stock.ilish}`);
}
console.log("admin: PAID -> SHIPPED", NEXT[order.status].includes("SHIPPED"));
console.log("admin: PAID -> PENDING_PAYMENT", NEXT[order.status].includes("PENDING_PAYMENT"));

ধরা পড়া email

উন্নয়নে কোনো আসল email provider নেই; smtp-server দিয়ে বানানো ৩০ লাইনের একটি capture server শুধু 127.0.0.1-এ শোনে আর প্রতিটি মেইল .eml ফাইলে রাখে, কাউকে পাঠায় না (পর্ব ৬৩)। অর্ডার #৩-এর মেইল (কাঁচা header সত্যিকারের, body base64 থেকে decode করা):

From: =?UTF-8?B?4Kas4Ka+4Kac4Ka+4Kaw4KaY4Kaw?= <orders@bazarghar.example>
To: rahima@example.com
Subject: =?UTF-8?B?4KaF4Kaw4KeN4Kah4Ka+4KawICPgp6kg4Kao4Ka/?=
 =?UTF-8?B?4Ka24KeN4Kaa4Ka/4KakIOKAlCDgp6gs4Kep4Kem?= =?UTF-8?B?4Kem4Kez?=
Content-Transfer-Encoding: base64
Content-Type: text/plain; charset=utf-8
                                   (মোট ১,০০৮ byte)
── decode করার পরে ──
Subject: অর্ডার #৩ নিশ্চিত — ২,৩০০৳

প্রিয় রহিমা,
আপনার অর্ডার #৩ পরিশোধিত হয়েছে।

পদ্মার ইলিশ (১ কেজি) × ২ = ২,৫০০৳
ছাড়: ২০০৳  ডেলিভারি: ০৳
মোট: ২,৩০০৳

অর্ডারের অবস্থা দেখুন: http://127.0.0.1:47130/orders/3
— বাজারঘর

Subject-এর তিনটি encoded word আলাদা decode করলে একটি বাংলা অক্ষর মাঝখানে কেটে যায়, আমাদের প্রথম চেষ্টায় যেমন হয়েছিল; আগে byte জোড়া দিন, তারপর UTF-8. আর link-এর ঠিকানা আসে APP_URL থেকে; production-এ এটি https-এর আসল domain না হলে রসিদের link ভুল জায়গায় যাবে।

৬ · লগইন, role, বাংলা UI আর metadata

হোটেলের রিসেপশন অতিথিকে একটি চাবির কার্ড দেয়, আর খাতায় লেখে কোন কার্ড কোন ঘরের, কবে পর্যন্ত। কার্ড হারালে খাতা থেকে মুছে দিলেই কার্ড অচল। Session-ভিত্তিক login ঠিক এমন (পর্ব ৪৫): cookie-তে ৩২ byte এলোমেলো টোকেন, database-এ তার SHA-256, মেয়াদ ৭ দিন। পাসওয়ার্ড রাখা হয় scrypt দিয়ে, scrypt$N$r$p$salt$hash রূপে, যাতে পরে cost বাড়ানো যায় (Cybersecurity কোর্সের password storage পর্ব)। মূল অংশ:

import 'server-only';
const COOKIE = 'bg_session';
const MAX_AGE = 60 * 60 * 24 * 7; // 7 days
const digest = (token: string) => createHash('sha256').update(token).digest('hex');

export async function createSession(userId: number) {
  const token = randomBytes(32).toString('base64url');
  await prisma.session.create({
    data: { id: digest(token), userId, expiresAt: new Date(Date.now() + MAX_AGE * 1000) },
  });
  (await cookies()).set(COOKIE, token, {
    httpOnly: true, sameSite: 'lax', path: '/', maxAge: MAX_AGE,
    secure: process.env.COOKIE_SECURE !== '0' && process.env.NODE_ENV === 'production',
  });
}

// Admin pages answer 404 to everyone else, so their existence is not advertised.
export async function requireRole(role: Role) {
  const user = await requireUser('/admin/orders');
  if (user.role !== role) notFound();
  return user;
}

import 'server-only' থাকায় ফাইলটি ভুলে client-এ import করলে build ভাঙে। Login-এর action-এ আরও দুটি অভ্যাস: অজানা email আর ভুল পাসওয়ার্ডে একই বার্তা, আর ?next= শুধু / দিয়ে শুরু হলে এবং // দিয়ে নয়, তবেই সেখানে ফেরা, যাতে কেউ link বানিয়ে ক্রেতাকে অন্য সাইটে পাঠাতে না পারে (open redirect).

Role যাচাই: পাতায় আর action-এ, দুই জায়গাতেই

Admin পাতা requireRole('ADMIN') ডাকে, আর “পাঠানো হয়েছে চিহ্নিত করুন”-এর server action আবার ডাকে। কেন দুবার? Server action আসলে একটি সাধারণ POST endpoint; পাতা না খুলেও কেউ action-এর id জোগাড় করে সরাসরি ডাকতে পারে। বোতাম লুকানো নিরাপত্তা নয়, শুধু সুবিধা (পর্ব ৪৮, তত্ত্ব broken access control পর্বে)। একই কারণে অর্ডারের পাতা আর নকল gateway-এর পাতা দেখে অর্ডারটি এই ক্রেতারই কি না; অন্যের অর্ডার হলে “পাতাটি পাওয়া যায়নি”, যেন অর্ডারটিই নেই। RBAC-এর এই ছোট রূপে মাত্র দুটি role; দোকান বড় হলে অনুমতির ছক লাগবে।

বাংলা UI

<html lang="bn">, next/font/google থেকে Noto Sans Bengali, body-তে স্থির line-height: 1.6 (font বদলের সময় লেখা যাতে না লাফায়, পর্ব ৮৪)। সংখ্যা সব জায়গায় একটি function দিয়ে: formatTaka(125000) দেয় ১,২৫০৳, আর formatTaka(12345650) দেয় ১,২৩,৪৫৬.৫০৳; দুটোই unit test-এ বাঁধা। পাতার নম্বর, কার্টের সংখ্যা, অর্ডারের নম্বরও বাংলা অঙ্কে। ফলে test-কেও বাংলা অঙ্ক পড়তে হয় (অংশ ৭)।

Metadata আর sitemap — একটি আসল ভুল আর তার সংশোধন

generateMetadata নাম আর দাম দিয়ে title আর description বানায়; sitemap.ts সব slug পড়ে, robots.ts ব্যক্তিগত পাতা বাদ দেয় (পর্ব ৫৮)। প্রথম Lighthouse run-এ পণ্যের পাতার SEO এল ৯১, কারণ “Document does not have a meta description”. অথচ description ছিল! HTML খুলে দেখা গেল, </head> শেষ হয়েছে ৯৬০ অক্ষরে, আর description এসেছে ১৩,১৪৭ অক্ষরে, body-র ভেতরে। Cache Components চালু থাকায় database থেকে পড়া metadata অন্য dynamic অংশের মতো পরে stream হচ্ছিল (streaming metadata); Googlebot user agent দিয়ে চাইলেও একই ফল।

সংশোধন: নাম আর দাম কম বদলায়, তাই সেগুলো "use cache" দিয়ে cache, আর generateStaticParams দিয়ে build-এর সময়েই সব slug জানানো। স্টকের সংখ্যা আগের মতোই প্রতি অনুরোধে আসে, Suspense-এর ভেতরে।

// Name and price change rarely: cache them so metadata can be prerendered into <head>.
async function getProductMeta(slug: string) {
  'use cache';
  cacheLife('hours');
  cacheTag('products');
  return prisma.product.findUnique({ where: { slug }, select: { slug: true, name: true, pricePaisa: true } });
}

export async function generateStaticParams() {
  return prisma.product.findMany({ select: { slug: true } });
}

export async function generateMetadata({ params }: PageProps<'/products/[slug]'>): Promise<Metadata> {
  const p = await getProductMeta((await params).slug);
  if (!p) return { title: 'পণ্য পাওয়া যায়নি' };
  return {
    title: p.name,
    description: `${p.name} — দাম ${formatTaka(p.pricePaisa)}। বাজারঘরে অর্ডার করুন।`,
    alternates: { canonical: `/products/${p.slug}` },
  };
}

পরের build-এ description চলে এল ৯৩৮ অক্ষরে, </head>-এর (১,৭৯০) আগে, আর title হলো পদ্মার ইলিশ (১ কেজি) | বাজারঘর; Lighthouse-এর SEO ১০০. দাম বদলের কোনো admin পাতা এখনো নেই; যেদিন হবে, সেদিন সেই action-এ revalidateTag('products') না ডাকলে পুরোনো দাম কয়েক ঘণ্টা metadata-য় থেকে যাবে (পর্ব ৫৩)। Build-এর সময় এখন database লাগে; deploy-এর ধাপে এর প্রভাব অংশ ৯-এ।

৭ · প্রতিটি স্তরে test

মডিউল ১১-এর কৌশল (পর্ব ৭২) এখানে ছোট করে: যে নিয়মে টাকা বা স্টক জড়িত, তার জন্য অনেক দ্রুত unit test; ক্রেতার হাতে যে component, তার জন্য component test; database-এর আচরণ, যেমন lock আর unique key, শুধু আসল database-এ প্রমাণ হয়, তাই integration test; আর পুরো পথের জন্য দুটি end-to-end যাত্রা। Vitest-এর তিনটি project একটি config-এ: unit (node), component (jsdom), integration (node, আলাদা test database, শুরুতে migrate deploy, ফাইল একটির পর একটি)। সত্যিকারের run (ছোট করা):

~/bazarghar$ npx vitest run --reporter=verbose
 ✓ |unit| tests/unit/order-and-webhook.test.ts > order state machine > PENDING_PAYMENT -> PAID is true
 ✓ |unit| tests/unit/order-and-webhook.test.ts > order state machine > PAID -> PENDING_PAYMENT is false
 …
 ✓ |unit| tests/unit/order-and-webhook.test.ts > webhook signature > rejects a changed amount
 ✓ |unit| tests/unit/order-and-webhook.test.ts > webhook signature > rejects a replay after 5 minutes
 ✓ |unit| tests/unit/money.test.ts > cartTotal > applies EID10 and caps it at ৳200
 ✓ |unit| tests/unit/money.test.ts > cartTotal > rejects EID10 below ৳1,000 and says why
 ✓ |unit| tests/unit/money.test.ts > formatTaka > uses Bangla digits, lakh grouping and ৳
 ✓ |component| tests/component/quantity-picker.test.tsx > QuantityPicker > counts up in Bangla digits and stops at the stock limit 159ms
 ✓ |component| tests/component/quantity-picker.test.tsx > QuantityPicker > sends the number as a hidden form field 51ms
 ✓ |integration| tests/integration/checkout.test.ts > … > sells the last jar exactly once when two buyers press at the same time 162ms
 ✓ |integration| tests/integration/checkout.test.ts > … > marks an order paid once, ignores the replay, refuses a wrong amount 33ms
 ✓ |integration| tests/integration/checkout.test.ts > … > gives the stock back when payment fails 26ms

 Test Files  4 passed (4)
      Tests  21 passed (21)
   Duration  2.55s

২১টির মধ্যে ১৬টি unit, ২টি component, ৩টি integration. পুরো চক্র আড়াই সেকেন্ড। Component test (পর্ব ৭৪) বোতাম খোঁজে role আর বাংলা নাম দিয়ে, যেভাবে ক্রেতা দেখেন।

দুটি Playwright যাত্রা

Playwright চলে কম্পিউটারে ইনস্টল করা Edge-এ (channel: 'msedge'), workers: 1, কারণ সব যাত্রা একটি database ভাগ করে (পর্ব ৭৬)। প্রথম যাত্রা ক্রেতার, দ্বিতীয়টি দুই ভাগে admin-এর: customer admin পাতা পান না, আর admin একটি পরিশোধিত অর্ডার পাঠানো হিসেবে চিহ্নিত করেন। প্রথম যাত্রার চূড়ান্ত রূপ:

import { expect, test } from '@playwright/test';
import { latestMail, login, resetCart } from './helpers';

test.beforeEach(() => resetCart('rahima@example.com'));

test('a customer finds ilish, pays, and gets the email', async ({ page }) => {
  await login(page, 'rahima@example.com', 'example-password-1');

  await page.getByRole('searchbox').fill('ilish');
  await page.getByRole('button', { name: 'খুঁজুন' }).click();
  await page.getByRole('link', { name: 'পদ্মার ইলিশ (১ কেজি)' }).click();
  await page.getByRole('button', { name: 'এক বাড়ান' }).click();
  await page.getByRole('button', { name: 'কার্টে যোগ করুন' }).click();
  await expect(page).toHaveURL(/\/cart$/);

  await page.getByLabel('মোবাইল নম্বর').fill('01712345678');
  await page.getByLabel('ঠিকানা').fill('বাড়ি ১২, রোড ৪, রাজশাহী');
  await page.getByLabel('কুপন (ঐচ্ছিক)').fill('EID10');
  await expect(page.getByTestId('total')).toHaveText('২,৩০০৳');   // what a Bangla reader sees

  await page.getByRole('button', { name: 'অর্ডার দিন ও পেমেন্টে যান' }).click();
  await expect(page).toHaveURL(/\/pay\/\d+$/);
  await page.getByRole('button', { name: 'পরিশোধ করুন' }).click();
  await expect(page.getByTestId('status')).toHaveText('পরিশোধিত');

  const id = page.url().split('/').at(-1);
  await expect.poll(latestMail).toContain(`${process.env.APP_URL ?? 'http://127.0.0.1:47130'}/orders/${id}`);
});

এই রূপে পৌঁছানোর আগে পাঁচটি run ব্যর্থ হয়েছে, আর প্রায় প্রতিটি কিছু শিখিয়েছে। নিচে আসল run-গুলো, ক্রমানুসারে:

Error: locator.fill: Test timeout of 30000ms exceeded.
  - waiting for getByRole('searchbox')

app-এ ছিল: <input id="q" name="q" placeholder="…">
type নেই → implicit role = textbox, searchbox নয়

Locator: getByText('৳2,300')
Expected: visible
Error: element(s) not found
error-context.md-এর পাতার ছবি:
  - term: মোট
  - definition: ২,৩০০৳

Expected substring: "http://127.0.0.1:47130/orders/1"
Received string:    "From: =?UTF-8?B?4Kas…?= …
    Content-Transfer-Encoding: base64·
    4Kaq4KeN4Kaw4Ka/4Kav4Ka8IOCmsOCm…"
মেইল এসেছে, কিন্তু base64-এ

ok 1 admin.spec.ts › a customer cannot see the admin page
x  2 admin.spec.ts › an admin ships a paid order (30.1s)
   waiting for getByRole('row').filter({ hasText: 'পরিশোধিত' })
x  3 buy.spec.ts   › …
admin ফাইল নামের ক্রমে আগে চলল: তখনো কোনো পরিশোধিত অর্ডার নেই

Running 3 tests using 1 worker
  ok 1 e2e\admin.spec.ts:4:5 › a customer cannot see the admin page (492ms)
  ok 2 e2e\admin.spec.ts:11:5 › an admin ships a paid order (746ms)
  ok 3 e2e\buy.spec.ts:6:5 › a customer finds ilish, pays, and gets the email (2.6s)

  3 passed (4.5s)

৮ · Build, Lighthouse আর review checklist

Production build চালানো হয়েছে database চালু রেখে, কারণ পণ্যের পাতার slug আর metadata build-এর সময়েই database থেকে পড়া হয়। সত্যিকারের route table (Next.js 16.4.4, Turbopack):

~/bazarghar$ npx next build
▲ Next.js 16.4.4 (Turbopack)
- Environments: .env
- Cache Components enabled
- Partial Prefetching enabled
✓ Compiled successfully
✓ Generating static pages using 15 workers (34/34)

Route (app)
┌ ◐ /
├ ◐ /_not-found
├ ◐ /admin/orders
├ ƒ /api/webhooks/payment
├ ◐ /cart
├ ◐ /login
├   /orders/[id]
│ └ ◐ /orders/[id]
├   /pay/[orderId]
│ └ ◐ /pay/[orderId]
├ ◐ /products
├   /products/[slug]
│ ├ ◐ /products/[slug]
│ ├ ◐ /products/miniket-rice-5kg
│ ├ ◐ /products/mustard-oil-1l
│ └ ◐ [+18 more paths]
├ ○ /robots.txt
└ ƒ /sitemap.xml

○  (Static)             prerendered as static content
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content
ƒ  (Dynamic)            server-rendered on demand

প্রায় সব পাতা ◐, অর্থাৎ partial prerender: স্থির খোলস build-এ তৈরি, আর user-নির্ভর অংশ (header-এর নাম আর কার্ট, স্টক, অর্ডার) প্রতি অনুরোধে Suspense-এর ভেতরে stream হয় (পর্ব ৫৫)। কারণ root layout-এর header প্রতিটি পাতায় cookie পড়ে। এরপর server চালানো হয়েছে সাধারণভাবে, কোনো reverse proxy ছাড়া: next start -H 127.0.0.1 -p 47130.

Lighthouse — মোবাইল, Edge-এ

পণ্যের পাতায় তিনবার আর তালিকার পাতায় একবার, Lighthouse 13.6.0-এর ডিফল্ট মোবাইল throttling-এ (পর্ব ৮৪)। Metadata সংশোধনের পরের সত্যিকারের ফল:

product-1  perf  95  a11y 100  bp 100  seo 100 | FCP 0.8 s  LCP 2.9 s  TBT 50 ms  CLS 0 | 306 KiB
product-2  perf 100  a11y 100  bp 100  seo 100 | FCP 0.8 s  LCP 0.8 s  TBT 20 ms  CLS 0 | 306 KiB
product-3  perf  96  a11y 100  bp 100  seo 100 | FCP 0.8 s  LCP 2.9 s  TBT 60 ms  CLS 0 | 306 KiB
list-1     perf  95  a11y 100  bp 100  seo 100 | FCP 0.8 s  LCP 3.0 s  TBT 50 ms  CLS 0 | 307 KiB
   বাকি audit: Reduce unused JavaScript (Est savings of 29 KiB) · Legacy JavaScript (14 KiB)
               Render-blocking requests (Est savings of 140 ms) · bf-cache: 2 failure reasons

মাঝের মান: performance ৯৬, LCP ২.৯ সেকেন্ড, যা “ভালো”-র সীমা ২.৫-এর ওপরে। LCP element হলো পণ্যের নামের <h1>, কোনো ছবি নয়। Network-এর তালিকায় সবচেয়ে বড় জিনিস একটি font ফাইল, ১,০৮,১৮৬ byte-এর বাংলা woff2. যে run-এ font প্রথম আঁকার আগেই চলে এসেছিল, সেখানে LCP ০.৮ সেকেন্ড; বাকি দুটিতে font পরে এসে লেখা আবার আঁকা হয়েছে, আর ধীর নেটওয়ার্কের হিসাবে তা ২.৯ সেকেন্ড। এটি আমাদের ব্যাখ্যা, Lighthouse-এর নিজের রায় নয়; পরীক্ষার উপায় হলো font subset বা display: 'optional' দিয়ে আবার মাপা। আর bfcache কাজ করে না; Lighthouse-এর দেওয়া কারণ, মূল HTML-এ Cache-Control: no-store. সংখ্যাগুলো একটি কম্পিউটারের একদিনের run, সাধারণ ফল নয়।

Review checklist — reference app কেমন করল

Code review-এর নিয়মিত তালিকা (Software Engineering কোর্সের code review পর্ব, নিরাপত্তার পূর্ণ তালিকা পর্ব ৫০) থেকে পাঁচটি ভাগ। প্রতিটি ঘরে যা যাচাই করা হয়েছে আর যা হয়নি, দুটোই লেখা।

Login ছাড়া curl দিয়ে /admin/orders চাইলে উত্তর HTTP/1.1 200 OK, আর body-তে <meta id="__next-page-redirect" http-equiv="refresh" content="1;url=/login?next=%2Fadmin%2Forders"/>; admin-এর কোনো ডেটা (অর্ডার পরিচালনা-এর heading পর্যন্ত) পাঠানো হয়নি, browser login পাতায় চলে যায়। কারণ খোলস আগেই ২০০ দিয়ে পাঠানো শুরু হয়ে গিয়েছিল, redirect এসেছে পরে stream হওয়া অংশে। অজানা পণ্যের পাতাও ২০০ দেয়, সাথে noindex, অনেকটা soft 404. নিরাপত্তার ক্ষতি নেই, কিন্তু monitoring ভুল ছবি দেবে। যেখানে ঠিক status জরুরি, সেখানে পর্ব ৫৭-এর মতো আগে, request-এর স্তরে যাচাই ভাবুন।

৯ · Deploy-এর পরিকল্পনা, stretch goal, portfolio আর rubric

এই পর্বে কোথাও deploy করা হয়নি; কোনো hosting, domain বা আসল gateway-এর account লাগেনি। নিচের ধাপগুলো পরিকল্পনা, পর্ব ৮২-এর পথ ধরে। দুই পথেই একটি নিয়ম এক: migration আগে, নতুন কোড পরে। বাজারঘরের build নিজেও database থেকে slug পড়ে, তাই এখানে migrate deploy build-এরও আগে।

Container-এ চালাতে চাইলে পর্ব ৮০-এর multi-stage Dockerfile প্রায় হুবহু খাটে; এই মডিউলে Docker চালানো হয়নি। Deploy-এর পরে পর্ব ৮৩-এর error tracking আর uptime check.

Stretch goal — মূল কাজ শেষ হলে

Portfolio আর ইন্টারভিউতে উপস্থাপন

একটি ক্যাপস্টোন চাকরি এনে দেবে, এমন কোনো নিশ্চয়তা নেই। তবে এটি আপনার কাজের যাচাইযোগ্য প্রমাণ আর ইন্টারভিউতে কথা বলার ভিত্তি:

• README-ই আপনার প্রথম পরিচয়। এক অনুচ্ছেদে সমস্যা আর ব্যবহারকারী; ER ডায়াগ্রাম আর একটি architecture-এর ছবি; চালানোর ধাপ; test-এর ফল; আর “জানা সীমাবদ্ধতা” অংশে উপরের checklist-এর ফাঁকগুলো।
• সিদ্ধান্ত আর বিকল্প। “কেন পয়সায়”, “কেন checkout-এ স্টক কমে, পেমেন্টে নয়”, “কেন session, JWT নয়”: প্রতিটির জন্য দুই লাইনে কারণ আর কী ছেড়ে দিলেন।
• একটি কঠিন bug-এর গল্প। STAR কাঠামোয়: অবস্থা (seed-এ বাংলা নাম ঢুকছিল না), দায়িত্ব (কারণ খোঁজা), কাজ (error code পড়ে database-এর encoding দেখা, cluster UTF8-এ নতুন করে বানানো, একটি acceptance check যোগ), ফল (আর কখনো হয়নি, check-টি নতুন milestone-এ আছে)।
• নিজের লেখা বুঝে বলা। যেকোনো লাইন দেখিয়ে “এটা কেন?” জিজ্ঞেস করা হতে পারে; AI দিয়ে লেখানো অংশও ব্যাখ্যা করতে পারলে তবেই সেটি আপনার কাজ। প্রশ্নের ধরন মডিউল ১৪-এ (পর্ব ৯৩ · ফুল-স্ট্যাক ইন্টারভিউ)।

নিজেকে মূল্যায়ন — rubric

একটি rubric আগে থেকে বলে দেয় কোন মানদণ্ডের কত ওজন, আর প্রতিটি মাত্রায় কী দেখা গেলে কত নম্বর। এতে “ভালো হয়েছে মনে হচ্ছে”-র জায়গায় আসে প্রমাণ। বাজারঘরের rubric, ০ থেকে ৩ মাত্রায়:

নিচের scorer-এ reference app-এর নিজের মাত্রা বসানো, প্রতিটির ছোট প্রমাণসহ। নিজের মাত্রা বসিয়ে চালান; ওজনের যোগ ১০০ না হলে এটি নিজেই থামবে:

// নিজের ক্যাপস্টোনের rubric scorer: প্রতিটি মানদণ্ডে ০–৩ মাত্রা, ওজন মিলিয়ে ১০০-তে
const rubric = [
  // [মানদণ্ড, ওজন, মাত্রা ০–৩, ছোট প্রমাণ]
  ["কার্যকারিতা (must-have সব)", 25, 3, "browse থেকে email পর্যন্ত Playwright পাস"],
  ["নিরাপত্তা", 20, 2, "hash, cookie, role, webhook সই আছে; rate limit, CSP নেই"],
  ["ডেটার সঠিকতা", 15, 3, "পয়সা, transaction, CHECK, idempotent webhook"],
  ["Test", 15, 2, "২১ Vitest + ৩ Playwright; CI-তে চালানো হয়নি"],
  ["Performance ও accessibility", 10, 2, "a11y 100; LCP 2.9 s (মোবাইল lab)"],
  ["Deployment প্রস্তুতি ও README", 15, 1, "build পাস; README, health check নেই"],
];

function score(rows, show = true) {
  const weights = rows.reduce((s, r) => s + r[1], 0);
  if (weights !== 100) throw new Error(`weights add to ${weights}, not 100`);
  let total = 0;
  for (const [name, w, level, why] of rows) {
    const pts = (w * level) / 3;
    total += pts;
    if (show) console.log(`${name.padEnd(30)} ${level}/3  ${pts.toFixed(1).padStart(5)}  ${why}`);
  }
  const blockers = rows.filter((r) => r[2] === 0).map((r) => r[0]);
  const band = blockers.length ? "দেখানোর আগে ০ মাত্রার ঘর ঠিক করুন"
    : total >= 85 ? "দেখানোর মতো প্রস্তুত" : total >= 70 ? "ভালো, ফাঁকগুলো লিখে রাখুন"
    : total >= 50 ? "আরেকটি milestone লাগবে" : "মূল কাজ আগে";
  console.log(`মোট ${total.toFixed(1)}/100 → ${band}`);
}
score(rubric);
// একই প্রকল্প, শুধু README লেখা হলে (deployment-এর ঘর ১ → ২):
score(rubric.map((r) => (r[0].startsWith("Deployment") ? [r[0], r[1], 2, "README যোগ"] : r)), false);

১০ · AI-এর যুগে ক্যাপস্টোন

ক্যাপস্টোনের আসল ফল কোড নয়, আপনার বোঝা। AI-এর সবচেয়ে ভালো ব্যবহার হলো ছোট, যাচাইযোগ্য টুকরো চাওয়া, আর প্রতিটি টুকরো acceptance check দিয়ে মেলানো। এই প্রকল্প বানাতে গিয়ে যে ভুলগুলো ধরা পড়েছে (@types/node-এর দ্বন্দ্ব, WIN1252, body-তে metadata, base64 মেইল, test-এর নির্ভরতা), AI-এর লেখা কোডেও এমন ভুল সহজে থাকে: কোড চলে, কিন্তু ঠিকভাবে নয়। AI দিয়ে কাজের পুরো পদ্ধতি পর্ব ৮৬-এ (AI দিয়ে ফুল-স্ট্যাক)।

AI-এর লেখা কোড মেলানোর চেকলিস্ট

• প্রতিটি API আমার version-এর docs-এ আছে: params Promise কি না, Prisma-র generator আর adapter, Zod 4-এর নাম, পুরোনো pages router-এর getServerSideProps নয়
• প্রতিটি server action আর route handler-এর প্রথম লাইনে login, role আর যাচাই আছে; শুধু বোতাম লুকানো হয়নি
• টাকা পয়সায়, দাম server-এ database থেকে; client-এর পাঠানো দাম বা মোট কোথাও ব্যবহার হয়নি
• AI যে package-এর নাম দিয়েছে তা npm-এ আছে, সত্যিই দরকার, আর তার version আমার বাকি package-এর সাথে মেলে
• catch করে error চুপচাপ গিলে ফেলা হয়নি; ব্যর্থ হলে log বা বার্তা আছে
• নিজে চালিয়েছি, diff পড়েছি, আর অন্তত একটি test আগে ব্যর্থ হতে দেখে তারপর পাস করিয়েছি
• Prompt-এ কোনো আসল secret, connection string বা ক্রেতার তথ্য দিইনি