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

Bảo mật

Mã	Yêu cầu
NFR-1	Gateway xác thực JWT bằng JWKS (làm mới mỗi 5 phút): chữ ký, hạn, issuer. Không kiểm tra audience. Không gọi Keycloak cho từng yêu cầu.
NFR-2	Gateway chính chỉ nhận token có azp trong danh sách cho phép (operations-portal, weighing-station-app) và có ít nhất một vai trò trong danh sách cho phép; gateway cân xe chỉ nhận truck-scale-data-tracker.
NFR-3	Gateway chỉ định tuyến các đường dẫn và phương thức khai báo trong routing-config.yml; còn lại 404. Gateway không chứa logic nghiệp vụ.
NFR-4	Secret chỉ lấy từ biến môi trường hoặc cấu hình, không ghi trong code.
NFR-5	Tệp đính kèm được kiểm tra kích thước và loại tệp thật (đọc 512 byte đầu) sau khi tải lên; sai thì xoá tệp. Tệp chờ quá 24 giờ bị dọn.

Dữ liệu và thời gian

Mã	Yêu cầu
NFR-6	Ngày nghiệp vụ theo giờ ICT (UTC+07). Lọc theo ngày tính từ 00:00 ICT, cận trên loại trừ ngày kế tiếp.
NFR-7	Ô số để trống lưu null, không lưu 0; không giá trị nào được tính từ ô trống.
NFR-8	Dữ liệu nghiệp vụ xoá mềm (deleted_at). Thay đổi phiếu, kế hoạch, bảng giá, phân bổ phải có lịch sử kèm dữ liệu trước và sau.
NFR-9	Thay đổi CSDL đi bằng migration mới, đánh số tiếp; không sửa migration đã chạy.
NFR-10	Chỗ nhiều người cùng sửa (thẻ phân bổ, nhận về) phải dùng khoá lạc quan theo phiên bản và trả 409 khi lệch.

API

Mã	Yêu cầu
NFR-11	Mọi yêu cầu /api phải có header X-Request-ID dạng UUID; thiếu: 400.
NFR-12	Phản hồi thành công: {requestId, data, pagination?}. Lỗi: {code, message, details?} với code ổn định, thông báo có tiếng Việt và tiếng Anh. Lỗi người dùng gặp được phải có mã riêng, không dùng mã chung BAD_REQUEST. details chỉ có khi cần chỉ ra chỗ lỗi (vị trí dòng, tên trường).
NFR-13	API có kiểu rõ ràng (Swagger). Thay đổi phải tương thích ngược hoặc có phiên bản mới.
NFR-14	Danh sách có phân trang; khoảng ngày tối đa 93 ngày trừ khi ghi khác.

Vận hành

Mã	Yêu cầu
NFR-15	Mỗi dịch vụ có /health, /ready và chỉ số Prometheus ở /metrics. /ready kiểm tra đúng các phụ thuộc dịch vụ dùng (PostgreSQL, Valkey); api-gateway-service không có phụ thuộc nên luôn sẵn sàng. truck-scale-tracker-local (chỉ local) kiểm tra MSSQL, Valkey và không có /metrics.
NFR-16	Log dạng JSON, luôn có request_id. Mọi lỗi phải được log kèm request_id và user_id, không bỏ qua lỗi im lặng.
NFR-17	Cảnh báo qua Telegram: dịch vụ ngừng quá 1 phút, dịch vụ khởi động lại, bộ nhớ > 500 MB trong 5 phút, tracker cân xe không báo trạng thái quá 10 phút (FR-TSC-20).
NFR-18	Thời hạn token truy cập 300 giây; portal tự làm mới token.

Giao diện

Mã	Yêu cầu
NFR-19	Mọi chuỗi hiển thị có cả tiếng Việt và tiếng Anh.
NFR-20	Ứng dụng Thu mua và Ứng dụng Phân bổ sơ chế phải dùng tốt trên điện thoại (chiều rộng 390 px); các màn hình khác cho máy tính và vẫn dùng được trên điện thoại. Vùng chạm tối thiểu 46 px trên điện thoại.
NFR-21	Bộ lọc, tab nằm trên URL; tải lại trang giữ nguyên trạng thái. Đăng nhập không được tạo thêm mục lịch sử trình duyệt.
NFR-22	Tự lưu (phân bổ) phải chờ ngừng gõ và không định dạng lại số dưới con trỏ. Màn hình lưu tay phải báo Có thay đổi chưa lưu và hỏi lại khi rời trang.