Tuition iBanking – SOA Microservices

Hệ thống mô phỏng thanh toán học phí theo kiến trúc hướng dịch vụ (SOA).
Sinh viên A có thể thanh toán cho chính mình hoặc cho người khác (C).
Frontend là các trang HTML/JS thuần; backend là các service Node.js + SQL Server (MSSQL).

1) Kiến trúc

[Browser] --(HTTP)-> [API Gateway/Reverse Proxy (optional)]
   |                             |
   |                             +--> [Auth-Service] -> SQL Server (auth schema)
   |                             +--> [Tuition-Service] -> SQL Server (students schema)
   |                             +--> [Payment-Service] -> SQL Server (payments schema)
   |                             +--> [Account-Ledger-Service] -> SQL Server (ledger schema)
   |                             +--> [Email-Service] (SMTP)

Điểm mấu chốt về bảo mật phiên:

• Frontend mặc định không gửi cookie (credentials: "omit") và chỉ dùng Authorization: Bearer <token>.
• “Khoá danh tính người nộp” bằng payerSnapshot trong sessionStorage để tránh “đánh tráo phiên” sau khi A thanh toán cho C.

2) Tech stack

• Node.js (Express)
• SQL Server (MSSQL) — chạy qua Docker hoặc local
• DBeaver / SSMS — quản trị cơ sở dữ liệu
• SMTP (Gmail/any) — gửi OTP / log email (tuỳ cấu hình)
• Vanilla HTML/CSS/JS — các trang payment.html, login.html, …

3) Cấu trúc thư mục gợi ý

.
├─ services/
│  ├─ auth-service/
│  ├─ tuition-service/
│  ├─ payment-service/
│  ├─ account-ledger-service/
│  └─ email-service/
├─ public/             # các trang HTML, css, js (payment.js, login.js, ...)
├─ scripts/            # seed, migrate, util
├─ docker-compose.yml
├─ .env                # giá trị thật (không commit)
├─ .env.example        # mẫu biến môi trường (được commit)
└─ README.md

4) Biến môi trường

Tạo file .env từ mẫu .env.example:

cp .env.example .env

Các biến tối thiểu:

• PORT, NODE_ENV, APP_URL
• DB_SERVER, DB_USER, DB_PASS, DB_NAME, DB_PORT
• JWT_SECRET, JWT_EXPIRES_IN
• CORS_ORIGIN (ví dụ: http://localhost:4000)
• SMTP (nếu dùng Email-Service)

Gợi ý: tạo JWT_SECRET bằng openssl rand -hex 32.

5) Khởi chạy nhanh

A. Chạy DB (Docker)

docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=YourStrong!Passw0rd" \
  -p 1433:1433 --name mssql -d mcr.microsoft.com/mssql/server:2019-latest

B. Kết nối DB (DBeaver)

• Host: localhost
• Port: 1433
• User: sa
• Pass: YourStrong!Passw0rd

Import script schema/seed (nếu có) tại scripts/.

C. Chạy services (local dev)

Mỗi service một terminal:

cd services/auth-service     && npm i && npm run dev
cd services/tuition-service  && npm i && npm run dev
cd services/payment-service  && npm i && npm run dev
cd services/account-ledger-service && npm i && npm run dev
cd services/email-service    && npm i && npm run dev

Hoặc dùng docker-compose (nếu đã cấu hình sẵn):

docker compose up -d --build

D. Frontend (static)

Dùng bất kì static server nào (hoặc service “web” của bạn).
Ví dụ:

npx serve public -l 4000
# Mở: http://localhost:4000/pages/login.html

6) Luồng nghiệp vụ thanh toán

A đăng nhập → Payment

1. GET /api/auth/me → tạo payerSnapshot (lock người nộp = A).
2. Nhập MSSV của C → GET /api/tuition/{mssv}/semesters → GET /api/tuition/{mssv}/{semester}.
3. POST /api/payments/intent → tạo payment_intent (payer = A, payee = C).
4. POST /api/payments/verify-otp (nếu có OTP).
5. POST /api/payments/confirm → trừ tiền A, cập nhật hoá đơn C, ghi ledger.
6. Dọn biến tạm của C, giữ payerSnapshot của A → quay lại payment.html vẫn là A.

Tất cả request kèm Bearer token của A. mssv của C chỉ là tham số nghiệp vụ, không “đăng nhập hộ C”.

7) Quy ước endpoint (tham khảo)

• Auth-Service
  • POST /api/auth/login — trả JWT
  • GET /api/auth/me — thông tin người đang đăng nhập
• Tuition-Service
  • GET /api/tuition/:mssv/semesters
  • GET /api/tuition/:mssv/:semester — hoá đơn, môn nợ
• Payment-Service
  • POST /api/payments/intent
  • POST /api/payments/verify-otp
  • POST /api/payments/confirm
  • POST /api/payments/cancel — huỷ khi OTP hết hạn
• Ledger-Service
  • GET /api/ledger/history?account_id=... — lịch sử bút toán
• Email-Service
  • POST /api/email/send (nếu cần)

8) Bảo mật & ổn định phiên (điểm đã FIX)

• Bearer-only fetch: wrapper authFetch mặc định credentials: "omit", chỉ bật useCookies: true khi thật sự cần cookie cũ.
• Khoá danh tính người nộp:
  • Lúc vào payment.html: gọi /api/auth/me → setPayerSnapshot(userA).
  • Trước khi tạo intent/verify/confirm: ensurePayerIdentity(meNow); mismatch ⇒ ép quay lại login.
  • Sau khi confirm thành công: cleanupPaymentTemp() (giữ nguyên snapshot A).
• Backend: Các endpoint của Tuition/Payment/OTP không được Set-Cookie: token=.... Chỉ Auth-Service mới phát hành cookie (nếu dùng cookie), hoặc tốt nhất chỉ dùng JWT Bearer.

9) Lỗi thường gặp & cách xử lý

• ENOTFOUND khi proxy tới auth-service:4001
  → Kiểm tra docker-compose network name, service name; hoặc dùng URL tuyệt đối http://localhost:4001.
• ports are not available ... 0.0.0.0:4004
  → Port đã bị chiếm. Đổi port hoặc stop tiến trình đang dùng (netstat/lsof), sửa docker-compose.yml.
• Cannot find module '../db/mssql'
  → Sai đường dẫn require. Đặt module db/mssql.js đúng vị trí, hoặc sửa require cho phù hợp.
• bcrypt.compare luôn false
  → Lệch lib (bcrypt vs bcryptjs) hoặc salt/round khác. Dùng một lib thống nhất & re-hash dữ liệu seed cho đúng.
• Sau khi A thanh toán cho C, quay lại bị thành C
  → Đảm bảo frontend đã Bearer-only + payerSnapshot; backend không set cookie ở các API thanh toán.

10) Scripts hữu ích

• Seed/migrate (tuỳ dự án):
  node scripts/seed.js hoặc .sql trong scripts/
• Lint/format:
  npm run lint / npm run format
• Dev:
  npm run dev cho từng service

11) Kiểm thử chấp nhận (UAT)

• A đăng nhập → vào payment.html lần đầu: snapshot được tạo.
• A thanh toán cho C thành công → quay lại payment.html: UI vẫn là A.
• Giả lập đổi phiên (sửa token thành C) trước khi confirm → hệ thống chặn, điều hướng về login.
• Kiểm tra Ledger: bút toán debit A, credit tuition/invoice của C chính xác.
• Kiểm tra Email/OTP (nếu bật): log gửi thành công, không leak token.

---

License

Internal coursework / learning project.