DN-001 — Đăng ký tài khoản doanh nghiệp (Signup & KYC Submission)

1.Tổng quan & phạm vi

Mục đích: Cho phép DN Owner (doanh nghiệp PCCC nhập khẩu / sản xuất tier 1) tự đăng ký tài khoản tenant trên app.pccctrace.vn. Người dùng khai thông tin doanh nghiệp, tạo mật khẩu, upload Giấy đăng ký kinh doanh (ĐKKD), xác thực quyền sở hữu email qua OTP, sau đó hồ sơ chuyển sang trạng thái pending_kyc chờ Platform Admin duyệt thủ công (SLA 24h — FR-18).

Trong phạm vi (In scope)

• Form đăng ký 1 trang: tên DN, MST, email, SĐT, mật khẩu, upload ĐKKD.
• Xác thực email bằng OTP 6 số qua modal (OTP chỉ để verify email, không dùng để đăng nhập).
• Tạo tenant (trạng thái pending_kyc) + user DN Owner khi OTP hợp lệ.
• Điều hướng sang DN-002 (KYC Pending) sau khi gửi hồ sơ thành công.

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

• Duyệt KYC (thuộc Platform Admin — FR-18, web platform).
• Tự động đối soát MST qua API Tổng cục Thuế (FR-1b — Phase 2).
• Đăng nhập (DN-003), mời thành viên, quên mật khẩu.
• Chỉnh sửa thông tin DN sau khi duyệt (DN-007 — Tenant Settings).

2.User story & Acceptance Criteria

Acceptance Criteria

3.Luồng nghiệp vụ

Điều kiện vào / ra

Luồng chính (Main flow)

Luồng thay thế (Alternate flows)

4.Đặc tả thành phần UI

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

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

Validate 2 lớp: client (on blur + on submit, hiển thị inline dưới field, viền đỏ --error) và server (nguồn chân lý cuối cùng). Thông báo lỗi 100% tiếng Việt.

5.1 · Chỉ báo độ mạnh mật khẩu (cơ bản)

Thanh 3 vạch + nhãn chữ hiển thị dưới field Mật khẩu (SU-05), cập nhật realtime theo mỗi ký tự nhập; ẩn khi field trống. Chỉ mang tính gợi ý — không chặn submit (điều kiện bắt buộc vẫn là ≥8 ký tự theo mục 5).

6.Business rules

7.Modal OTP xác thực email

Hiện đè lên form (overlay rgba(17,24,39,0.55)) sau khi bấm SU-09 và server đã gửi OTP thành công.

8.API contract (đề xuất — backend chốt cuối)

8.1 · Gửi hồ sơ & yêu cầu OTP

// Tạo bản ghi đăng ký tạm + gửi OTP. Files upload multipart cùng request (đơn giản, phù hợp scale 30 DN).
POST /api/v1/auth/signup
Content-Type: multipart/form-data

company_name : string(≤200)
tax_code     : string(10|13 digits)
email        : string(email, lowercase)
phone        : string(VN phone)
password     : string(≥8)
consent      : boolean — bắt buộc true; server lưu consent_at (FR-75)
documents[]  : file × 1–5 (pdf|jpg|jpeg|png, ≤10MB/file)

// 200 OK
{ "registration_id": "reg_8f2k...", "otp_expires_in": 300, "resend_cooldown": 60 }

// Lỗi
409 TAX_CODE_EXISTS   → "Tài khoản đã tồn tại, vui lòng đăng nhập"
409 EMAIL_EXISTS      → "Email đã được sử dụng..."
422 VALIDATION_ERROR  → { "errors": { "tax_code": "..." } }
413 FILE_TOO_LARGE / 415 FILE_TYPE_INVALID
429 RATE_LIMITED      → { "retry_after_seconds": 1800 }

8.2 · Xác thực OTP → tạo tenant

POST /api/v1/auth/signup/verify
{ "registration_id": "reg_8f2k...", "otp": "387265" }

// 200 OK — tenant + user đã tạo, trạng thái pending_kyc
{ "tenant_id": "tn_01H...", "user_id": "us_01H...", "kyc_status": "pending_kyc" }

// Lỗi
400 OTP_INVALID   → { "attempts_left": 3 }
400 OTP_EXPIRED
423 OTP_LOCKED    → { "retry_after_seconds": 1800 }
410 REGISTRATION_EXPIRED  // bản ghi tạm quá TTL — yêu cầu đăng ký lại

8.3 · Gửi lại OTP

POST /api/v1/auth/signup/resend-otp
{ "registration_id": "reg_8f2k..." }

200 { "otp_expires_in": 60 }
429 RATE_LIMITED   // >5 OTP/giờ/email (FR-7)

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

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

• Bảo mật: HTTPS bắt buộc; bcrypt cost 12 (BR-07); OTP hash + constant-time compare; rate limit theo BR-05; không log mật khẩu/OTP; CSRF protection cho form.
• Hiệu năng: Trang tải <2s trên mạng 3G nhanh; upload 5 file 10MB không block UI (upload song song hoặc tuần tự có progress).
• Responsive: Mobile ≤560px chuyển grid 2 cột → 1 cột (đã có trong prototype); modal OTP dùng được trên mobile.
• Accessibility: Label gắn for/id đúng field; lỗi đọc được bởi screen reader (aria-describedby + aria-invalid); toggle mắt có aria-label; focus ring rõ (đã có --focus-ring).
• Ngôn ngữ: 100% tiếng Việt, kể cả thông báo lỗi từ server.
• Đơn giản hoá: Quy mô 30 DN — không cần queue/CDN/captcha phức tạp ở MVP; rate limit đơn giản theo email + IP là đủ.

11.Edge cases

12.Câu hỏi mở — đã chốt (03/07/2026)

13.Lịch sử thay đổi