Bỏ qua

Feature: Tính tổng A + B

1. Mục đích

Cho phép người dùng nhập hai số A, B trên giao diện web và nhận về tổng A + B.

  • Frontend: UI tối giản gồm 2 ô nhập A, B, nút "Tính tổng" và vùng hiển thị kết quả.
  • Backend: endpoint nhận a, b kiểu number, trả về a + b.
  • Luồng: người dùng bấm "Tính tổng" → FE gọi GET /api/sum?a=<A>&b=<B> → BE validate và trả kết quả → FE hiển thị sum hoặc thông báo lỗi.

Tham chiếu Acceptance Criteria: AC-001 (UI), AC-002 (FE gọi API và hiển thị), AC-003 (BE validate + trả 200/400).

2. Cách chạy

Yêu cầu: Node.js (repo dùng script node, không cần cài dependency — không có dependencies trong cả hai package.json).

Backend (port 3000)

cd backend
npm start          # tương đương: node server.js
  • Mặc định port 3000; override bằng biến môi trường PORT, ví dụ PORT=4000 node server.js.
  • Khi chạy thành công, log ra: backend listening on port 3000.

Frontend (port 8080)

cd frontend
npm start          # tương đương: node server.js
  • Mặc định port 8080; override bằng PORT, ví dụ PORT=9090 node server.js.
  • Mở http://localhost:8080 để dùng UI.
  • FE gọi BE qua base URL http://localhost:3000 (hằng DEFAULT_API_BASE_URL trong frontend/lib.js), nên cần chạy backend trước/đồng thời.

Test

# từ repo root — e2e + contract/AC của tester (27 test)
npm run test:e2e

# unit test backend
cd backend && npm run test:unit

# unit test frontend
cd frontend && npm run test:unit

3. API

Endpoint duy nhất của feature: GET /api/sum (theo specs/api-contract.yaml).

Thành phần Giá trị
Method + path GET /api/sum
Query params a (number, required), b (number, required)
Response 200 {"sum": <number>} — Content-Type: application/json; charset=utf-8
Response 400 Thiếu a/b, hoặc a/b không phải số. Body dạng {"error": "<reason>"} với reason là missing_params hoặc invalid_params
CORS Access-Control-Allow-Origin: * trên mọi response

Ví dụ:

curl 'http://localhost:3000/api/sum?a=1&b=2'
# 200 {"sum":3}

curl 'http://localhost:3000/api/sum?a=1.5&b=2.25'
# 200 {"sum":3.75}

curl -i 'http://localhost:3000/api/sum?a=foo&b=2'
# 400 {"error":"invalid_params"}

Ghi chú triển khai (khớp code thật):

  • parseSumQuery trong backend/lib.js dùng regex số thập phân đầy đủ (cho phép dấu, phần lẻ, exponent) nên các giá trị như 1abc, chuỗi rỗng, Infinity bị coi là không hợp lệ và trả 400.
  • Request không phải GET /api/sum trả 404 {"error":"not_found"} (vẫn kèm header CORS).

4. Kiến trúc ngắn

Browser (index.html + app.js + lib.js)
        │  fetch GET /api/sum?a=..&b=..
        ▼
Frontend static server (node:http, port 8080)
        │  chỉ phục vụ /, /index.html, /app.js, /lib.js
        ▼
Backend API (node:http, port 3000) — stateless
        │  lib.parseSumQuery() → lib.sum()
        ▼
{"sum": number} | 400
  • Frontend — vanilla HTML/JS, không dependency, không build step:
  • frontend/server.js: static server bằng node:http, whitelist route cố định (chống path traversal), trả 405 cho method khác GET, 404 cho path lạ.
  • frontend/index.html: form 2 input số + nút "Tính tổng" + vùng kết quả (aria-live="polite").
  • frontend/app.js: gắn sự kiện submit, disable nút khi đang gọi, hiển thị kết quả/lỗi.
  • frontend/lib.js: hàm thuần buildSumUrl(baseUrl, a, b) và parseSumResult(json); export cho cả browser (global) và Node (CommonJS) để unit test.
  • Backend — node:http, stateless, không database:
  • backend/server.js: router tối giản, set CORS *, gọi handler và trả JSON.
  • backend/lib.js: sum(a, b) và parseSumQuery(url) (validate + parse), không dependency.
  • Không có state: mỗi request độc lập, không lưu lịch sử tính toán.

5. Test coverage

Kết quả: 27/27 PASS, 0 FAIL (tester, ngày 2026-11-21, Node v26.13.1 trên linux/WSL2).

  • Chi tiết + traceability AC ↔ test + log chạy thật: tests/artifacts/1/report.md
  • Runner: node --test tests/issue-001/ (tương đương npm run test:e2e ở repo root).
  • Phủ AC:
  • AC-001 — UI có 2 ô nhập A/B, nút "Tính tổng", vùng kết quả, index.html hợp lệ.
  • AC-002 — buildSumUrl đúng contract, parseSumResult đúng/sai contract, tích hợp gọi BE thật.
  • AC-003 — BE trả 200 {"sum":a+b} (số nguyên, thập phân), 400 cho param sai/thiếu/rỗng, Content-Type JSON.
  • Bonus e2e — FE + BE cùng chạy, CORS cho phép request từ origin FE, luồng UI → BE → sum.

6. Hạn chế / shortcut

  • shortcut: chưa có database/persistence — feature thuần stateless theo spec; nếu cần lưu lịch sử tính toán thì bổ sung storage + migration (hiện npm run migrate:up chỉ echo 'no db').
  • shortcut: chưa deploy thật — chỉ chạy local (localhost:8080 cho FE, localhost:3000 cho BE). Chưa có reverse proxy/HTTPS/domain; khi deploy cần đổi DEFAULT_API_BASE_URL trong frontend/lib.js hoặc cấu hình base URL theo môi trường.
  • shortcut: FE gọi BE qua localhost + CORS * — backend mở CORS cho mọi origin (Access-Control-Allow-Origin: *) để FE khác origin gọi được. Phù hợp sandbox, không phù hợp production; khi lên thật nên giới hạn origin cụ thể và/hoặc phục vụ FE/BE cùng origin.
  • shortcut: frontend base URL hard-code — DEFAULT_API_BASE_URL = 'http://localhost:3000' là hằng số trong code; chưa có cơ chế config runtime theo môi trường.
  • shortcut: UI dùng input type=number + validate ở BE — FE không tự validate trước khi gọi; giá trị sai được phát hiện bởi BE (400) và FE hiển thị thông báo lỗi chung.
  • Chưa kiểm thử trên browser thật — AC-001 được kiểm trên markup tĩnh vì môi trường test không có browser; hành vi click/hiển thị runtime được phủ gián tiếp qua test tầng lib + tích hợp BE thật (xem ghi chú trong report).
  • Precision — dùng phép cộng số thực JavaScript (a + b), có thể gặp sai số floating-point với số thập phân lớn (ví dụ 0.1 + 0.2); chưa xử lý làm tròn/thư viện decimal.