Feature: Tính tổng A + B¶
- Issue: #1 — FE+BE tính tổng A+B
- Trạng thái: Hoàn thành (code + test)
- Spec:
specs/design-spec.md,specs/api-contract.yaml - Test report:
tests/artifacts/1/report.md
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,bkiể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ịsumhoặ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)¶
- Mặc định port
3000; override bằng biến môi trườngPORT, ví dụPORT=4000 node server.js. - Khi chạy thành công, log ra:
backend listening on port 3000.
Frontend (port 8080)¶
- Mặc định port
8080; override bằngPORT, 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ằngDEFAULT_API_BASE_URLtrongfrontend/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):
parseSumQuerytrongbackend/lib.jsdù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,Infinitybị coi là không hợp lệ và trả 400.- Request không phải
GET /api/sumtrả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ằngnode:http, whitelist route cố định (chống path traversal), trả 405 cho method khácGET, 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ầnbuildSumUrl(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 đươngnpm 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.htmlhợ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-TypeJSON. - 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ệnnpm run migrate:upchỉecho 'no db').shortcut: chưa deploy thật— chỉ chạy local (localhost:8080cho FE,localhost:3000cho BE). Chưa có reverse proxy/HTTPS/domain; khi deploy cần đổiDEFAULT_API_BASE_URLtrongfrontend/lib.jshoặ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.