Đặc tả yêu cầu phần mềm (SRS)

Hệ thống giám sát tàu thủy Fleet Eye — tài liệu yêu cầu cho giai đoạn MVP và mở rộng.

Phiên bản: 1.0.0
Cập nhật: 25/05/2026
Trạng thái: Bản nháp

1. Giới thiệu

1.1 Mục đích tài liệu

Tài liệu SRS (Software Requirements Specification) mô tả yêu cầu chức năng và phi chức năng của hệ thống Fleet Eye — nền tảng giám sát tàu thủy hàng hải theo thời gian thực.

Đối tượng đọc: nhà đầu tư, product owner, đội phát triển, QA và đối tác tích hợp (AIS, cảm biến IoT, nhà mạng vệ tinh).

1.2 Phạm vi sản phẩm

Fleet Eye cung cấp giám sát vị trí và trạng thái hạm đội, cảnh báo bất thường, báo cáo hành trình và giao diện quản lý cho chủ tàu / công ty vận tải biển.

Phiên bản trong phạm vi SRS này: MVP web (Nuxt 4 SSR) + API Nitro + MongoDB; tích hợp Socket real-time và thiết bị AIS/IoT theo lộ trình.

1.3 Định nghĩa, từ viết tắt

AIS: Automatic Identification System — hệ thống nhận dạng tàu tự động.
Hạm đội (Fleet): Tập hợp các tàu thuộc cùng tổ chức quản lý.
Geofence: Vùng địa lý ảo; cảnh báo khi tàu vào/ra khỏi vùng.
SRS: Software Requirements Specification.

2. Mô tả tổng quan

2.1 Bối cảnh sản phẩm

Ngành vận tải biển cần theo dõi liên tục vị trí, tiêu hao nhiên liệu và rủi ro an toàn. Dữ liệu phân tán (AIS, log máy, báo cáo thủ công) khiến quyết định chậm và chi phí vận hành cao.

Fleet Eye tập trung hóa dữ liệu trên một nền tảng web, trực quan hóa trạng thái tàu và đẩy cảnh báo kịp thời tới người quản lý.

2.2 Vai trò người dùng

Quản lý hạm đội (Fleet Manager): Xem toàn bộ tàu, cảnh báo, báo cáo tổng hợp.
Giám sát tàu (Ship Monitor): Theo dõi chi tiết một tàu: động cơ, nhiên liệu, hành trình, thời tiết.
Khách vãng lai (Anonymous): Truy cập demo / xem giới thiệu không bắt buộc đăng nhập.
Quản trị hệ thống: Cấu hình tổ chức, phân quyền, tích hợp thiết bị (giai đoạn sau MVP).

2.3 Ràng buộc và giả định

Hệ thống giả định có kết nối internet (bao gồm Starlink / 4G trên tàu) để đồng bộ dữ liệu.

Dữ liệu thời gian lưu UTC trên server; hiển thị theo timezone người dùng.

Đăng nhập Google OAuth là phương thức chính cho người dùng đã xác thực; hỗ trợ phiên anonymous cho trải nghiệm demo.

3. Yêu cầu chức năng

3.1 Giám sát vị trí & trạng thái (FR-01)

ID	Mô tả	Ưu tiên
FR-01.1	Hiển thị danh sách tàu với vị trí, tốc độ, hướng, ETA và trạng thái (đang hành trình / neo / trong cảng).	Cao
FR-01.2	Cập nhật vị trí real-time qua WebSocket hoặc polling ≤ 30 giây.	Cao
FR-01.3	Lọc tàu theo trạng thái, loại tàu, vùng địa lý.	Trung bình

3.2 Cảnh báo thông minh (FR-02)

ID	Mô tả	Ưu tiên
FR-02.1	Tạo cảnh báo khi tàu vượt ngưỡng tốc độ, ra khỏi geofence, hoặc tín hiệu AIS yếu/mất.	Cao
FR-02.2	Phân loại mức độ: info / warning / danger / success.	Cao
FR-02.3	Lưu lịch sử cảnh báo và cho phép đánh dấu đã xử lý.	Trung bình

3.3 Quản lý hạm đội (FR-03)

ID	Mô tả	Ưu tiên
FR-03.1	Dashboard tổng quan: số tàu hoạt động, cảnh báo trong ngày, tàu trong cảng.	Cao
FR-03.2	Xem chi tiết từng tàu: động cơ, nhiên liệu, hàng hóa, thuyền đoàn (module Ship Monitor).	Cao
FR-03.3	Xuất báo cáo PDF/Excel theo khoảng thời gian.	Thấp

3.4 Xác thực & tài khoản (FR-04)

ID	Mô tả	Ưu tiên
FR-04.1	Đăng nhập Google OAuth; đồng bộ JWT cookie cho API và Socket.	Cao
FR-04.2	Phiên anonymous tự tạo cho truy cập không đăng nhập.	Trung bình
FR-04.3	Cập nhật hồ sơ (tên, timezone) qua API.	Trung bình

3.5 Tích hợp dữ liệu (FR-05) — lộ trình

ID	Mô tả	Ưu tiên
FR-05.1	Nhận feed AIS từ nhà cung cấp hoặc gateway IoT trên tàu.	Cao
FR-05.2	API REST/Webhook cho ERP/TMS đối tác.	Trung bình
FR-05.3	Push notification (Web Push) cho cảnh báo khẩn.	Trung bình

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

4.1 Hiệu năng

ID	Mô tả	Ưu tiên
NFR-01	Thời gian phản hồi API (P95) < 500ms cho truy vấn danh sách tàu (< 500 tàu).	Cao
NFR-02	Tải trang dashboard LCP < 2.5s trên mạng 4G.	Trung bình

4.2 Bảo mật

ID	Mô tả	Ưu tiên
NFR-03	HTTPS bắt buộc production; cookie HttpOnly cho JWT.	Cao
NFR-04	Phân quyền theo tổ chức — user chỉ xem tàu thuộc fleet được gán.	Cao
NFR-05	Tuân thủ lưu trữ dữ liệu hành trình theo chính sách privacy đã công bố.	Cao

4.3 Khả dụng & vận hành

ID	Mô tả	Ưu tiên
NFR-06	Uptime mục tiêu 99.5% (MVP); kế hoạch mở rộng 99.9%.	Trung bình
NFR-07	Giao diện responsive: desktop ưu tiên, hỗ trợ tablet/mobile.	Cao
NFR-08	Logging API và health check (/ping, /healty).	Trung bình

5. Kiến trúc hệ thống

5.1 Thành phần

Frontend: Nuxt 4 (Vue 3), Nuxt UI, Pinia, Socket.IO client.

Backend: Nitro server routes, Valibot validation, Mongoose (MongoDB), Redis/BullMQ (queue), MinIO (file), dịch vụ Socket riêng.

Auth: NextAuth (Google) + JWT cookie song song (user-token / anonymous-token).

5.2 Luồng dữ liệu chính

Thu thập: AIS / IoT → gateway → API ingest → MongoDB + Redis cache.
Phát real-time: Socket server broadcast vị trí & cảnh báo tới client đã subscribe fleet/ship.
Hiển thị: Client gọi POST /api/* và lắng nghe socket; timezone convert phía client.

6. Giao diện bên ngoài

6.1 Giao diện người dùng

Trang công khai: / (landing), /login, /fleet-manager, /ship-monitor.

Trang nội bộ tài liệu: /docs (SRS), /presentation (pitch nhà đầu tư).

6.2 API (hiện có / kế hoạch)

ID	Mô tả	Ưu tiên
API-01	POST /api/user/detail, update-profile, update-timezone	Đã có
API-02	POST /api/auth/* — anonymous-info, refresh-token, logout	Đã có
API-03	POST /api/fleet/, /api/vessel/ — CRUD tàu, telemetry (kế hoạch)	Kế hoạch

7. Phụ lục

7.1 Lịch sử thay đổi

Phiên bản	Ngày	Mô tả	Tác giả
1.0.0	25/05/2026	Khởi tạo SRS từ product steering	Fleet Eye Team

7.2 Tài liệu tham chiếu

product.md: .kiro/steering/product.md — tổng quan sản phẩm.
structure.md: .kiro/steering/structure.md — quy ước code & API pattern.
tech.md: .kiro/steering/tech.md — stack & biến môi trường.

7.3 Ghi chú chỉnh sửa

Nội dung trên là khung SRS — chỉnh sửa trực tiếp trong file app/pages/docs/index.vue hoặc tách sang markdown khi cần phiên bản hóa.

Mỗi yêu cầu FR/NFR nên được liên kết với ticket/issue và test case tương ứng khi triển khai.