Tài liệu nghiệp vụ on AKAIUNSAN — Tài liệu nghiệp vụ

Giới thiệu

Mon, 01 Jan 0001 00:00:00 +0000

Giới thiệu AKAIUNSAN

1. Nền tảng là gì?

AKAIUNSAN là nền tảng trung gian kết nối Khách hàng có nhu cầu chăm sóc nhà cửa với các Người trợ giúp (Helper) đã được xác minh. Khách hàng đặt lịch theo giờ, hệ thống gợi ý helper phù hợp, theo dõi tiến trình đơn hàng, thanh toán bằng thẻ hoặc tiền mặt và đánh giá sau dịch vụ.

2. Các bề mặt sản phẩm

Bề mặt	Công nghệ	Đối tượng	Mục đích
Ứng dụng di động (`apps/`)	React Native + Expo	Khách hàng	Đặt lịch, thanh toán, theo dõi, đánh giá
Trang web (`frontend/`)	Web	Khách hàng / Tiếp thị	Giới thiệu, landing page dịch vụ
Trang quản trị (`admin/`)	React + Vite	Quản trị viên	Quản lý dịch vụ, helper, đơn hàng, khuyến mãi
API (`backend/`)	Express 5 + Sequelize + MariaDB	Hệ thống	Toàn bộ logic dữ liệu và nghiệp vụ

3. Ai nên đọc tài liệu này?

Ban lãnh đạo / Sản phẩm: mục Tổng quan hệ thống, Danh sách tính năng, Yêu cầu chức năng.
Lập trình viên: toàn bộ mục Nghiệp vụ hệ thống — mỗi quy tắc BL- là hợp đồng hành vi cần triển khai đúng.
Kiểm thử viên: Yêu cầu chức năng (tiêu chí chấp nhận) + Hướng dẫn kiểm thử.
Người dùng cuối: Hướng dẫn sử dụng — ngôn ngữ đời thường, không thuật ngữ kỹ thuật.

4. Nguyên tắc ngôn ngữ

Ứng dụng hỗ trợ đa ngôn ngữ (Tiếng Việt, Tiếng Anh, Tiếng Thái). Tài liệu này viết bằng tiếng Việt là ngôn ngữ chuẩn; thuật ngữ kỹ thuật giữ nguyên tiếng Anh kèm giải thích ở Bảng thuật ngữ.

Tổng quan hệ thống

Mon, 01 Jan 0001 00:00:00 +0000

Tổng quan hệ thống

1. Sơ đồ kiến trúc mức cao

┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
│  Ứng dụng khách  │   │   Trang quản trị │   │    Trang web     │
│  hàng (iOS/      │   │   (admin/)       │   │    (frontend/)   │
│  Android apps/)  │   │                  │   │                  │
└────────┬─────────┘   └────────┬─────────┘   └────────┬─────────┘
         │        HTTPS + JWT│              │
         └──────────────┬────────┴──────────────────────┘
                        ▼
              ┌───────────────────┐        ┌──────────────┐
              │  Backend API      │◄──────►│  MariaDB     │
              │  (Express 5)      │        │  (Dữ liệu)   │
              └─────┬───────┬─────┘        └──────────────┘
                    │       │
        ┌───────────▼──┐  ┌─▼──────────────────────┐
        │ Omise (thẻ)  │  │ Firebase FCM (thông báo)│
        └──────────────┘  └────────────────────────┘

2. Thành phần chính

Thành phần	Vai trò	Ghi chú
API Backend	Mọi nghiệp vụ: tài khoản, đơn hàng, giá, khuyến mãi, thông báo	Bảo vệ bằng JWT
Ứng dụng khách hàng	Điểm chạm chính của khách hàng	Hỗ trợ iOS & Android, đa ngôn ngữ
Trang quản trị	Quản lý nội dung, helper, đơn, khuyến mãi	Dành cho nhân viên vận hành
Omise	Cổng thanh toán thẻ tín dụng/ghi nợ	Lưu thẻ an toàn theo chuẩn PCI
Firebase FCM	Thông báo đẩy realtime	Kèm badge số lượng chưa đọc

3. Môi trường

Môi trường	Dùng để	Dữ liệu
Dev	Phát triển tính năng mới	Dữ liệu giả lập
Staging	Kiểm thử chấp nhận (UAT)	Dữ liệu giống production, đã ẩn danh
Production	Khách hàng thật	Dữ liệu thật — chỉ vận hành mới được vào

4. Vai trò người dùng

Vai trò	Mô tả	Hành động chính
Khách hàng (Customer)	Người đặt dịch vụ	Đăng ký, đặt lịch, thanh toán, đánh giá
Helper (Người trợ giúp)	Người thực hiện dịch vụ	Nhận việc, cập nhật tiến trình
Quản trị viên (Admin)	Nhân viên vận hành nền tảng	Quản lý helper, giá, khuyến mãi, xử lý khiếu nại
Khách (Guest)	Chưa đăng nhập	Xem trang giới thiệu, dịch vụ; phải đăng ký để đặt lịch

API tổng quan

Mon, 01 Jan 0001 00:00:00 +0000

API tổng quan

Backend Express 5 tổ chức API thành 5 nhóm route theo tầng truy cập. Số liệu dưới đây lấy trực tiếp từ backend/routes/ (thay đổi khi backend phát triển — đây là bức tranh định hướng, không phải hợp đồng endpoint chi tiết).

1. Các nhóm route

Nhóm	Tệp	Số endpoint	Xác thực	Dùng bởi
Public	`public.route.ts`	25	Không (công khai)	Đăng ký/đăng nhập, quên mật khẩu, banner, danh mục dịch vụ công khai
Client	`client.route.ts`	43	JWT khách hàng	Đơn hàng, địa chỉ, thẻ, thông báo, hồ sơ, gói, yêu thích
Back-office	`backoffice.route.ts`	127	JWT quản trị + phân quyền	Toàn bộ vận hành: dịch vụ, giá, helper, đơn, khuyến mãi
Agency	`agency.route.ts`	8	JWT đối tác	Tích hợp đối tác
Bot	`bot.route.ts`	3	Khóa riêng	Tích hợp chatbot

2. Quy ước bảo mật chung

/client/* yêu cầu Authorization: Bearer <JWT> (clientValidator) — JWT hết hạn → 401 → ứng dụng tự đăng xuất (FR-ACC-05).
/back-office/* yêu cầu JWT quản trị, middleware recordHistory và kiểm tra quyền checkPermission theo từng phân hệ.

3. Nhóm endpoint client hay dùng nhất

Đường dẫn	Phương thức	Mục đích	FR liên quan
`/auth/signin`, `/auth/signup`, `/auth/forget-password`, `/auth/reset-password`	POST	Xác thực	FR-ACC-01..03
`/client/user`, `/client/user/language`	GET / PUT	Hồ sơ, ngôn ngữ	FR-PRO-01, FR-ACC-06
`/client/addresses`	GET / POST / PUT / DELETE	Sổ địa chỉ	FR-PRO-02
`/client/jobs`	GET	Danh sách đơn (lọc `orderStatus`, `page`)	FR-BOOK-05
`/booking/detail`, `/booking/detail/edit`	GET / PUT	Chi tiết / sửa đơn	FR-BOOK-04/06
`/orders/*`	POST	Tạo đơn từng loại dịch vụ, hủy, đánh giá	FR-BOOK-04/06
`/client/credit-cards`	GET / POST / PUT / DELETE	Thẻ thanh toán	FR-PAY-01/02
`/charges`, `/charges-card`, `/charges-plan`	POST	Thực hiện thanh toán	FR-PAY-02/03
`/promotion/*`	GET / POST	Khuyến mãi (áp mã, chi tiết)	FR-PAY-04
`/client/subscriptions`	GET / PUT	Gói dịch vụ	FR-SUB-01..04
`/client/notifications`	GET / POST / DELETE	Thông báo (danh sách, đọc tất cả, xóa)	FR-NOTI-01
`/favourite/services`, `/favourite/service-providers`	GET / POST	Yêu thích	FR-FAV-01
`/services-management*`, `/config-price`, `/config-point`	GET	Dịch vụ, bảng giá, điểm	FR-SVC-02/03

Quản trị & vận hành

Mon, 01 Jan 0001 00:00:00 +0000

Trang quản trị & vận hành

1. Trang quản trị (admin)

Xây bằng React 19 + Vite + TanStack Router, chia theo phân hệ:

Phân hệ	Nội dung chính
Dashboard	Tổng quan hoạt động
Apps	Quản lý ứng dụng/dịch vụ hiển thị cho khách
Tasks	Công việc/việc theo dõi
Users	Quản lý người dùng và helper
Chats	Trao đổi/hỗ trợ
Settings	Cấu hình hệ thống, phân quyền

Mọi thao tác quản trị đi qua /back-office/* với JWT + recordHistory (ghi vết) + checkPermission (phân quyền theo phân hệ).

Bảng thuật ngữ

Mon, 01 Jan 0001 00:00:00 +0000

Bảng thuật ngữ

Thuật ngữ	Giải thích
AKAIUNSAN	Nền tảng trung gian dịch vụ chăm sóc nhà cửa
Helper	Người trợ giúp thực hiện dịch vụ cho khách hàng
Đơn (Order/Job)	Một lần đặt dịch vụ của khách hàng, có trạng thái riêng
PENDING / MATCH / …	Các mã trạng thái đơn — xem BL-ORD-01
Maid / Nany / Elder / AC / Petcare	Năm nhóm dịch vụ: dọn nhà, chăm bé, chăm người cao tuổi, vệ sinh máy lạnh, chăm thú cưng
Extra service	Dịch vụ thêm mua kèm (ủi đồ, dắt chó đi dạo…)
Flexible plan	Gói linh hoạt: mua giờ dùng dần cho một loại dịch vụ
Fix plan	Gói cố định: lịch lặp theo tuần, ưu đãi giá
Giờ còn lại (hour remain)	Số giờ của gói chưa được sử dụng
Điểm (Point)	Điểm thưởng tích từ đơn thành công, quy đổi được thành tiền giảm giá
Khuyến mãi (Promotion)	Mã giảm giá: giảm tiền mặt hoặc giảm phần trăm
Helper yêu thích	Helper được khách đánh dấu để đặt lại nhanh
Helper đặc biệt	Yêu cầu chỉ định một helper cụ thể cho đơn
Badge	Số chưa đọc hiển thị trên tab thông báo
Deep link	Chạm thông báo mở thẳng màn hình chi tiết tương ứng
JWT	Phiên đăng nhập dạng token, kèm mọi gọi API
Omise	Cổng thanh toán thẻ tín dụng/ghi nợ mà nền tảng sử dụng
FCM	Dịch vụ thông báo đẩy của Google (Firebase Cloud Messaging)
UAT	Kiểm thử chấp nhận trên môi trường staging trước khi ra mắt

Chỉ số tra cứu

Mon, 01 Jan 0001 00:00:00 +0000

Chỉ số tra cứu mã định danh

Một trang duy nhất để tra mọi mã yêu cầu/quy tắc đã dùng trong tài liệu. Chọn mã để nhảy tới trang định nghĩa.

Tính năng (F)

Mã	Tên	Trang
`F-ACC-01..06`	Đăng ký, đăng nhập, quên mật khẩu, đổi mật khẩu, phiên, đa ngôn ngữ	Tính năng — Tài khoản
`F-HOME-01`	Trang chủ	Tính năng — Khám phá
`F-SVC-01..03`	Danh mục, tùy chọn, bảng giá động	Tính năng — Khám phá
`F-BOOK-01..07`	Chọn ngày giờ, helper, địa chỉ, tạo đơn, theo dõi, hủy, yêu cầu đặc biệt	Tính năng — Đặt lịch
`F-PAY-01..05`	Thẻ, thanh toán thẻ/tiền mặt, khuyến mãi, điểm	Tính năng — Thanh toán
`F-NOTI-01..03`	Inbox, badge, deep link	Tính năng — Thông báo
`F-PRO-01..02`	Hồ sơ, sổ địa chỉ	Tính năng — Hồ sơ
`F-FAV-01` / `F-HIST-01` / `F-SUB-01` / `F-REF-01`	Yêu thích / Lịch sử & đánh giá / Gói dịch vụ / Giới thiệu	Tính năng — Hồ sơ
`F-ADM-01..04`	Quản trị: dịch vụ & giá, helper, đơn, khuyến mãi	Tính năng — Quản trị

Yêu cầu chức năng (FR)

Nhóm	Các mã	Trang chi tiết
Tài khoản & xác thực	`FR-ACC-01` → `FR-ACC-06`	FR-ACC
Trang chủ	`FR-HOME-01`	FR-HOME/SVC
Dịch vụ	`FR-SVC-01` → `FR-SVC-03`	FR-HOME/SVC
Đặt lịch & đơn	`FR-BOOK-01` → `FR-BOOK-07`	FR-BOOK
Thanh toán	`FR-PAY-01` → `FR-PAY-05`	FR-PAY
Thông báo	`FR-NOTI-01` → `FR-NOTI-03`	FR-NOTI
Hồ sơ & tiện ích	`FR-PRO-01/02`, `FR-FAV-01`, `FR-HIST-01`, `FR-SUB-01`, `FR-REF-01`	FR-PRO & tiện ích

Yêu cầu phi chức năng (NFR)

NFR-01 Hiệu năng · NFR-02 Bảo mật · NFR-03 Sẵn sàng · NFR-04 Đa ngôn ngữ · NFR-05 Giao diện nhất quán · NFR-06 Tương thích · NFR-07 Khả năng kiểm thử · NFR-08 Quan sát · NFR-09 Khả năng truy cập · NFR-10 Dữ liệu cá nhân