DN-003 — Đăng nhập (Login)

1.Tổng quan & phạm vi

Mục đích: Cho phép mọi user thuộc tenant DN (Owner / Admin / Staff) đăng nhập app.pccctrace.vn bằng email + mật khẩu truyền thống (auth model chốt 2026-06-09). Backend so khớp bcrypt.compare(password, password_hash) → phát hành JWT với sub = user_id (không phải email — email là login identifier, cố định sau đăng ký: chức năng đổi email đã loại bỏ 03/07/2026, trường hợp cần đổi liên hệ hỗ trợ xử lý thủ công).

Trong phạm vi (In scope)

• Form đăng nhập: email + mật khẩu (toggle 👁) + "Ghi nhớ đăng nhập 30 ngày".
• Chống brute-force: sai 5 lần / 15 phút → khoá tạm 30 phút (FR-7); thông báo lỗi generic.
• Điều hướng theo trạng thái tenant: active → app (DN-039 Home) · pending_kyc → DN-002.
• Link "Quên mật khẩu?" → DN-004 (self-service reset).

Ngoài phạm vi (Out of scope)

• SSO / OAuth bên thứ ba — không có trong lộ trình (định hướng simple/minimum, 30 DN).
• OTP SMS — không bao giờ: SĐT chỉ là contact data, không tham gia auth.
• Đăng nhập Dealer trên web — Dealer chỉ dùng mobile app (xem EC-05).

2.User story & Acceptance criteria

3.Luồng nghiệp vụ

4.UI elements

Layout: card căn giữa, max-width 440px, nền --neutral. Tham chiếu trực tiếp prototype DN-003 — dùng đúng design tokens trong tokens.css.

5.Validation & thông báo lỗi

Validate client (on submit) + server (nguồn chân lý cuối). Thông báo lỗi 100% tiếng Việt, luôn generic với lỗi thông tin đăng nhập.

6.Business rules

7.API contract (đề xuất)

7.1 · Đăng nhập

POST /api/v1/auth/login
{
  "email": "anhtuan@hathanhpccc.vn",   // lowercase, trim
  "password": "********",
  "remember": true                      // LG-03 — phát hành refresh token 30d
}

// 200 OK
{
  "access_token": "eyJ...",            // JWT sub=user_id, exp 1h
  "refresh_token": "rt_...",           // chỉ khi remember=true, exp 30d
  "user": { "user_id": "us_01H...", "role": "owner" },
  "kyc_status": "active"               // client điều hướng theo BR-05
}

// Lỗi
401 INVALID_CREDENTIALS → "Email hoặc mật khẩu không đúng" // generic — BR-04
423 ACCOUNT_LOCKED      → { "retry_after_seconds": 1800 }
403 PLATFORM_NOT_ALLOWED → role Dealer — "Vui lòng dùng ứng dụng di động"
429 RATE_LIMITED        → theo IP (lớp hạ tầng)

7.2 · Làm mới phiên

POST /api/v1/auth/refresh
{ "refresh_token": "rt_..." }
// 200 → access_token mới · 401 → hết hạn, đăng nhập lại

8.Trạng thái màn hình (UI states)

9.Yêu cầu phi chức năng

• Bảo mật: HTTPS bắt buộc; bcrypt cost 12; constant-time compare; không log mật khẩu; CSRF protection; refresh token lưu httpOnly cookie (không localStorage).
• Hiệu năng: đăng nhập hoàn tất <2s trên mạng 3G nhanh; trang tải <1s.
• Accessibility: label gắn for/id; lỗi đọc được bởi screen reader (aria-describedby, aria-invalid); toggle mắt có aria-label; focus ring rõ.
• Ngôn ngữ: 100% tiếng Việt.
• Đơn giản hoá: quy mô 30 DN — không cần captcha ở MVP; rate limit theo email + IP là đủ (đồng bộ DN-001).

10.Edge cases

11.Câu hỏi mở — cần chốt trước khi dev

12.Changelog