Tài Liệu Đặc Tả Kỹ Thuật Hệ Thống ATSA-COS (Master Final)

Luồng nghiệp vụ

Bộ tài liệu Đặc tả Hệ thống (System Specification Document).

Cấu trúc tài liệu Master bao gồm 3 phần chính:

MASTER PART 1: KIẾN TRÚC HỆ THỐNG & CƠ SỞ DỮ LIỆU (System Architecture & Database Schema) - Xương sống của dự án.
MASTER PART 2: ĐẶC TẢ LOGIC NGHIỆP VỤ BACKEND (Business Logic & API Specs) - Cách hệ thống xử lý tiền, lương, marketing.
MASTER PART 3: GIAO DIỆN NGƯỜI DÙNG & TÍCH HỢP (Frontend & Integrations) - Mô tả màn hình, Chatbot, và lộ trình Giai đoạn 2.

Master Part 1

KIẾN TRÚC HỆ THỐNG & CƠ SỞ DỮ LIỆU

1. TỔNG QUAN KỸ THUẬT (TECHNICAL OVERVIEW)

1.1. Công nghệ sử dụng (Tech Stack)

Backend: Laravel 11.x (PHP 8.2+).
Frontend: Vue.js 3 (Composition API) + Tailwind CSS.
Database: MySQL 8.0.
Cache/Queue: Redis.
Màu chủ đạo: #B84E61 (Đỏ).

1.2. Kiến trúc Hệ thống

Sử dụng kiến trúc Modular Monolith. Mã nguồn nằm trong một Repo duy nhất nhưng tổ chức thành các Module độc lập (DDD).

Core Module CRM Module Sales Module HRM Module Finance Module

1.3. PHÂN QUYỀN & VAI TRÒ CHI TIẾT (ROLE DESCRIPTIONS)

Mô tả cụ thể quyền hạn của từng loại tài khoản trong hệ thống để đội Dev cấu hình RBAC (Role-Based Access Control) chính xác.

Super Admin

Quản trị viên cấp cao nhất

Toàn quyền truy cập tất cả module.
Cấu hình hệ thống, tạo tài khoản nhân viên.
Xem tất cả báo cáo tài chính & doanh thu.
Can thiệp xóa/sửa dữ liệu nhạy cảm.

Doctor (Bác sĩ)

Nhân sự chuyên môn

Xem lịch hẹn khám của cá nhân.
Truy cập module Bệnh án/Kê đơn (GĐ2).
Xem danh sách bệnh nhân đã khám.
KHÔNG xem được doanh thu tổng hoặc lương người khác.

Receptionist (Lễ tân)

Vận hành tiền sảnh

Quản lý hàng đợi, Check-in/Check-out.
Tạo Đơn hàng (Order), Thu tiền (Cashier).
Tạo/Sửa hồ sơ khách hàng (Customer Profile).
Đặt lịch hẹn cho khách.

Accountant (Kế toán)

Quản lý tài chính

Duyệt các Phiếu chi (Expense Requests).
Xem báo cáo dòng tiền, chốt sổ quỹ hàng ngày.
Tính lương và xuất Phiếu lương (Payroll).
Quản lý công nợ đối tác (GĐ2).

Marketing

Phát triển thị trường

Quản lý Chiến dịch Quảng cáo (Campaigns).
Sử dụng Design Tool tạo ảnh.
Gửi tin nhắn Broadcast (Zalo/SMS).
Xem báo cáo hiệu quả Marketing (ROI).

Customer (Khách hàng)

Người dùng cuối (App/Web)

Đặt lịch hẹn, xem lịch sử khám.
Xem Ví tích điểm, Ví hoa hồng, Mã giới thiệu.
Không có quyền truy cập trang quản trị (Admin Portal).

2. THIẾT KẾ CƠ SỞ DỮ LIỆU (DATABASE SCHEMA - MASTER)

Đây là thiết kế đầy đủ nhất, bao gồm tất cả các nghiệp vụ từ Marketing, Bán hàng đến Nhân sự và Tài chính.

A. NHÓM ĐỊNH DANH & PHÂN QUYỀN

Table: users

Lưu trữ toàn bộ người dùng: Admin, Bác sĩ, Nhân viên, Khách hàng. - id: UUID (Primary Key). - phone: VARCHAR(20) (Unique, Index). - password: VARCHAR (Hashed). - full_name: VARCHAR(100). - referral_code: VARCHAR(20) (Unique, Index) - Mã giới thiệu riêng của user. - is_ghost: BOOLEAN (Default: false) - Đánh dấu tài khoản tạm. - tier_level: ENUM('standard', 'silver', 'gold', 'partner'). - status: ENUM('active', 'inactive', 'banned'). - created_at: TIMESTAMP.

Table: user_profiles

Thông tin mở rộng. - user_id: UUID (Foreign Key -> users.id). - birthday: DATE - Dùng để gửi quà sinh nhật tự động. - gender: ENUM('male', 'female', 'other'). - address: TEXT. - province_code: VARCHAR(10). - avatar_url: VARCHAR.

Table: roles & permissions

Sử dụng thư viện Spatie Laravel Permission. - Roles: super_admin, doctor, receptionist, accountant, marketing, sale_agent, customer.

B. NHÓM VÍ ĐIỆN TỬ & AFFILIATE

Table: wallets

Mỗi user có thể có nhiều loại ví. - id: BIGINT (Primary Key). - user_id: UUID (FK). - type: ENUM('cash', 'point', 'commission') - cash: Tiền nạp/hoàn, commission: Tiền hoa hồng. - balance: DECIMAL(15, 2) (Default: 0). - is_locked: BOOLEAN.

Table: transactions

Sổ cái ghi nhận dòng tiền (Immutable Ledger). - id: UUID (PK). - wallet_id: BIGINT (FK). - amount: DECIMAL(15, 2) - Số dương (cộng), số âm (trừ). - type: ENUM('deposit', 'withdraw', 'payment', 'commission_in', 'refund'). - reference_type: VARCHAR (VD: 'App\Models\Order'). - reference_id: UUID. - description: VARCHAR. - created_at: TIMESTAMP.

Table: referral_relationships

Lưu vết ai giới thiệu ai. - id: BIGINT (PK). - referrer_id: UUID (FK) - Người giới thiệu. - referee_id: UUID (FK) - Người được giới thiệu. - campaign_id: INT (Nullable). - created_at: TIMESTAMP.

C. NHÓM KINH DOANH & DỊCH VỤ

Table: services

- id: INT (PK). - category_id: INT (FK). - code: VARCHAR(50). - name: VARCHAR. - price: DECIMAL(15, 2). - is_medical: BOOLEAN. - status: ENUM.

Table: marketing_campaigns

- id: INT (PK). - name: VARCHAR. - budget: DECIMAL(15, 2). - start_date: DATE. - end_date: DATE. - status: ENUM.

Table: appointments

- id: UUID (PK). - customer_id: UUID (FK). - doctor_id: UUID (Nullable). - service_id: INT (Nullable). - appointment_time: DATETIME. - source: VARCHAR (Zalo, Facebook, Web, Hotline). - status: ENUM('pending', 'confirmed', 'checked_in', 'completed', 'cancelled', 'no_show'). - note: TEXT.

Table: orders

- id: UUID (PK). - customer_id: UUID (FK). - campaign_id: INT (Nullable). - total_amount: DECIMAL(15, 2). - discount_amount: DECIMAL(15, 2). - final_amount: DECIMAL(15, 2). - payment_method: ENUM('cash', 'transfer', 'wallet'). - payment_status: ENUM('unpaid', 'paid', 'refunded'). - created_at: TIMESTAMP.

D. NHÓM NHÂN SỰ & CHẤM CÔNG (HRM)

Table: departments

- id: INT (PK). - name: VARCHAR (Lễ tân, Kế toán, Bác sĩ, Marketing).

Table: staff_profiles

- user_id: UUID (FK). - department_id: INT (FK). - base_salary: DECIMAL(15, 2) - Lương cơ bản. - start_date: DATE. - contract_type: ENUM('probation', 'official').

Table: work_shifts

- id: INT (PK). - name: VARCHAR (Sáng, Chiều, Hành chính). - start_time: TIME. - end_time: TIME.

Table: attendances

- id: BIGINT (PK). - user_id: UUID (FK). - date: DATE. - check_in: DATETIME. - check_out: DATETIME. - status: ENUM('on_time', 'late', 'absent').

Table: salary_slips

- id: UUID (PK). - user_id: UUID (FK). - month: INT. - year: INT. - work_days: FLOAT. - base_salary_total: DECIMAL. - commission_bonus: DECIMAL. - deductions: DECIMAL. - net_income: DECIMAL (Thực lĩnh). - status: ENUM('draft', 'finalized', 'paid').

E, F, G. TÀI CHÍNH, KHÁCH ĐOÀN & ASSETS

Nhóm Tài chính (E): expense_categories, expenses, daily_closings (Chốt sổ quỹ).
Nhóm Khách đoàn (F - Prep GĐ2): corporate_partners, corporate_contracts, corporate_employees.
Nhóm Design (G): design_templates, user_designs.

3. QUY TẮC DATABASE

Collation: utf8mb4_unicode_ci.
Timezone: Asia/Ho_Chi_Minh.
Foreign Keys: ON DELETE RESTRICT (Bảo vệ dữ liệu).
Indexing: phone, referral_code, created_at, name.

Master Part 2

ĐẶC TẢ LOGIC NGHIỆP VỤ BACKEND & API

4. ĐẶC TẢ MODULE AFFILIATE & LOYALTY

4.1. Logic Tính Thưởng Giới Thiệu

Quy tắc: Mức thưởng cố định 10% giá trị hóa đơn thực thu.

Luồng xử lý (Trigger khi Order = PAID):

Kiểm tra users.referral_code của Customer.
Tính toán: Commission = Order.final_amount * 0.10
Tạo Transaction (type: commission_in).
Cộng tiền vào ví Commission của người giới thiệu.
Gửi thông báo Realtime.

4.2. Logic Khách Hàng Thân Thiết

Logic: Khách đã từng sử dụng dịch vụ (count > 0) -> Tự động giảm 10% cho lần sau. Thẻ VIP giảm theo cấu hình.

5. MODULE MARKETING & AUTOMATION

Design Tool: Server render ảnh (vẽ text, QR lên Template ID) -> Trả về URL.
Ads ROI: Job chạy cuối ngày tính Profit = TotalRevenue (theo CampaignID) - Budget.
Cron Jobs:
- Sinh nhật (08:00 AM): Query user có birthday = today -> Gửi thiệp Zalo.
- Nhắc lịch (30 phút/lần): Query appointment sắp tới -> Gửi SMS/Zalo.

6. MODULE NHÂN SỰ & LƯƠNG

// 6.2. Logic Tính Lương Hợp Nhất (Algorithm)

$finalSalary = 0;

// 1. Lương cứng theo ngày công

$workDays = Attendance::where('user_id', $id)->count();

$dailyRate = $baseSalary / 26; // Giả sử 26 công chuẩn

$finalSalary += $workDays * $dailyRate;

// 2. Cộng hoa hồng Affiliate & Thưởng Sale KPI

$commission = Transaction::sum('amount');

$finalSalary += $commission + $kpiBonus;

// 3. Trừ phạt

$finalSalary -= $penalties;

7. MODULE TÀI CHÍNH

Chốt sổ quỹ (Daily Closing):

Backend tính: SystemCash = Thu - Chi.
So sánh với InputCash (Thực tế đếm). Nếu lệch -> Yêu cầu nhập Note -> Lưu vào DB.

8. DANH SÁCH API QUAN TRỌNG

Auth & User

POST /api/auth/login

POST /api/auth/register-guest

GET /api/user/profile

Wallet & Affiliate

GET /api/wallet/balance

GET /api/wallet/transactions

GET /api/affiliate/network

Booking

GET /api/services

POST /api/appointments

POST /api/appointments/check-in

HRM & Tools

POST /api/design/render

POST /api/attendance/check

GET /api/payroll/my-slip

Master Part 3

GIAO DIỆN NGƯỜI DÙNG & TÍCH HỢP

9. ĐẶC TẢ GIAO DIỆN (FRONTEND)

Design System: Vue.js 3 + Tailwind. Màu chủ đạo #B84E61.

Màn hình Lễ tân (Dashboard)

Check-in nhanh bằng SĐT/QR. Popup hiển thị "Hồ sơ 360 độ" (Tên, Hạng thẻ, Số dư ví, Gợi ý giảm giá). Trạng thái khám Realtime.

Màn hình Khách hàng (WebApp Mobile-first)

Trang chủ có Banner KM, Nút đặt lịch. Ví hiển thị số dư hoa hồng to rõ. Center hiển thị QR cá nhân và danh sách bạn bè đã mời.

Công cụ Thiết kế (Design Editor)

Chọn mẫu -> Nhập text/giá -> Live Preview -> Tải về/Gửi Zalo.

10. TÍCH HỢP HỆ THỐNG BÊN NGOÀI

Chatbot AI (RAG): Tìm kiếm trong Vector DB (Services, Chính sách) -> OpenAI/Gemini -> Trả lời khách.
Đa kênh (Zalo OA/Facebook): Tập trung tin nhắn về một mối. Dùng ZNS gửi thông báo lịch hẹn, biến động số dư.

11. LỘ TRÌNH PHÁT TRIỂN (ROADMAP)

Giai đoạn 2: Chuyên sâu Y tế (Clinical Core)

Chuyển từ CRM sang HIS. EMR (Bệnh án điện tử), Đơn thuốc, LIS/PACS (Kết nối xét nghiệm), Khám đoàn (Corporate Import).

Giai đoạn 3: Hệ sinh thái (Ecosystem)

Sàn giao dịch Y tế, Cổng việc làm, Telehealth.

12. YÊU CẦU VẬN HÀNH & BẢO MẬT

Hạ tầng: Docker, CI/CD (GitLab/GitHub), Backup tự động 6h/lần.
Bảo mật: Data Audit (Ghi log truy cập), RBAC (Phân quyền chặt chẽ - Sale không xem Bệnh án).

MÔ TẢ GIAI ĐOẠN 2 (CHI TIẾT)

Mục tiêu: Chuyển đổi từ "Kiếm khách" (GĐ1) sang "Giữ khách bằng chuyên môn" (GĐ2).

1. Quản lý Khám Chữa Bệnh (Medical)

Quản lý dịch vụ BHYT, Hồ sơ sức khỏe chuyên sâu, Bệnh án điện tử chuẩn hóa, Liên thông đơn thuốc.

2. Phân hệ Khám Đoàn (Corporate)

Quản lý đầu mối doanh nghiệp, Tự động hóa quy trình khám đoàn, Chuyển đổi nhân viên công ty thành khách lẻ.

3. Quản lý Tài sản

Quản lý trang thiết bị, vật tư y tế.

HỎI ĐÁP (Q&A) - CHIẾN LƯỢC DỰ ÁN

Q1: Bản thiết kế trên có phù hợp để phát triển giai đoạn 2 và mở rộng không?

CÓ. Bản thiết kế này đã xây dựng nền móng sẵn (Database Tables chờ sẵn cho Khám đoàn và Y tế). Kiến trúc "Định danh Nhất thể" (Unified Identity) và UUID giúp mở rộng chuỗi phòng khám dễ dàng. Modular Monolith giúp thêm tính năng mới mà không đập đi xây lại.

Q2: Tài liệu Master này để làm cho giai đoạn nào?

Phục vụ trực tiếp việc LẬP TRÌNH GIAI ĐOẠN 1 (Business & Operation). Tuy nhiên, Database đã bao gồm cấu trúc hạ tầng chờ sẵn cho Giai đoạn 2 để tránh rủi ro sửa DB sau này.

Q3: Chỉ làm Giai đoạn 1 có vận hành được ngay không?

CHẮC CHẮN CÓ. Đây là sản phẩm MVP hoàn chỉnh theo hướng "Business-First". Phòng khám có thể đón khách, thu tiền, tính lương, làm Marketing ngay lập tức. Quy trình chuyên môn y tế tạm thời quản lý theo mô hình dịch vụ (như Spa/Phòng khám tư) trước khi nâng cấp GĐ2.