UCall App — Bảng Routes & Đề xuất cải thiện

Khảo sát tại: https://dev.app.ucall.vn
Tài khoản: hieuhoang@ucall.asia
Thực hiện: 2026-05-18

1. Phân tích vấn đề hiện tại

1.1 Các vấn đề được phát hiện

Vấn đề	Ví dụ hiện tại	Mức độ
Version lộ trong URL	`call_v3`, `callbot_template_v4`	🔴 Cao
Prefix sai ngữ nghĩa	`/script/` cho module Thư viện	🔴 Cao
Trùng lặp từ	`/history/historycall`	🟡 Trung bình
Không nhất quán số ít/số nhiều	`telesales` vs `messages`	🟡 Trung bình
Tên UI và route lệch nhau	`billing_info` hiển thị “Hồ sơ khách hàng”	🟡 Trung bình
Quá chung chung	`/settings/general/profile`	🟡 Trung bình
UUID lộ trên URL mặc định	`/contacts/contact/{uuid}`	🟠 Cần xem xét
Sub-module lồng không nhất quán	`ticket/` vs `work/tasks/`	🟡 Trung bình
Tất cả settings dưới `general/`	`/settings/general/*` cho mọi thứ	🟡 Trung bình

2. Đề xuất cải thiện Route

2.1 Nguyên tắc thiết kế

Nguyên tắc RESTful + Domain-Driven:
/{workspace}/{domain}/{resource}/{action?}

Quy tắc:
✅ Dùng kebab-case (gạch ngang), không dùng snake_case hay camelCase
✅ Dùng danh từ số nhiều cho collections
✅ Không để version vào route người dùng thấy
✅ Route phản ánh đúng tên UI hiển thị
✅ Nhóm sub-module theo domain rõ ràng

2.2 Bảng so sánh Before / After

📊 Reports

| Trước | Sau | Lý do | |—|—|—| | /report/dashboard/{uuid} | /reports/overview | report sang số nhiều; bỏ UUID khỏi route mặc định | | /report/kpi | /reports/kpi | Nhất quán số nhiều |

👥 Contacts (CRM)

| Trước | Sau | Lý do | |—|—|—| | /contacts/contact/{uuid} | /contacts/people | Bỏ /contact/ lồng thừa, UUID nên là param | | /contacts/enterprise/{uuid} | /contacts/companies | enterprise sang companies (rõ hơn, phổ biến hơn) | | /contacts/list | /contacts/segments | list quá chung; segments rõ nghĩa hơn | | /contacts/ulead | /contacts/leads | Bỏ prefix brand u-, dùng leads chuẩn CRM |

🛒 Sales

| Trước | Sau | Lý do | |—|—|—| | /sales/products | /sales/products | OK, giữ nguyên | | /sales/order/view/0 | /sales/orders | Bỏ /view/0 không cần thiết | | /sales/deal/{uuid} | /sales/deals | Số nhiều cho collection view |

⚙️ Operations

| Trước | Sau | Lý do | |—|—|—| | /ticket/{uuid} | /operations/tickets | Đưa vào namespace operations | | /work/tasks/{uuid} | /operations/tasks | Thống nhất namespace | | /work/meetings/{uuid} | /operations/meetings | Thống nhất namespace | | /work/calendar | /operations/calendar | Thống nhất namespace |

📣 Campaigns

📚 Library

📞 History

| Trước | Sau | Lý do | |—|—|—| | /history/historycall | /history/calls | Bỏ trùng lặp từ history trong sub-route |

🔧 Settings

2.3 Cấu trúc Route mới (tổng thể)

/dashboard/{workspace_id}/
│
├── reports/
│   ├── overview              # Dashboard tổng quan
│   └── kpi                   # KPI
│
├── contacts/
│   ├── people                # Liên hệ
│   ├── companies             # Công ty
│   ├── segments              # Danh sách/Phân khúc
│   └── leads                 # ULead
│
├── sales/
│   ├── products              # Sản phẩm
│   ├── orders                # Đơn hàng
│   └── deals                 # Cơ hội
│
├── operations/
│   ├── tickets               # Phiếu ghi
│   ├── tasks                 # Công việc
│   ├── meetings              # Lịch hẹn
│   └── calendar              # Lịch
│
├── campaigns/
│   ├── callbot               # Chiến dịch Callbot
│   ├── telesale              # Chiến dịch Telesale
│   └── messages              # Chiến dịch Tin nhắn
│
├── library/
│   ├── callbot               # Template Callbot
│   ├── call-agent            # Template Call Agent (v4)
│   ├── messages              # Template Tin nhắn
│   └── email                 # Template Email
│
├── history/
│   └── calls                 # Lịch sử cuộc gọi
│
└── settings/
    ├── account/
    │   ├── profile           # Thông tin tài khoản
    │   ├── billing           # Hồ sơ thanh toán
    │   ├── api-keys          # API Key
    │   └── security          # Đổi mật khẩu / Bảo mật
    ├── team/
    │   ├── permission-sets   # Nhóm quyền
    │   ├── groups            # Nhóm nhân viên
    │   ├── members           # Tài khoản nhân viên
    │   └── work-shifts       # Ca làm việc
    ├── preferences           # Cài đặt cá nhân
    ├── pbx/
    │   └── routing           # Định tuyến PBX
    ├── integrations          # Tích hợp
    └── property/
        ├── contacts          # Thuộc tính Khách hàng
        ├── companies         # Thuộc tính Công ty
        ├── products          # Thuộc tính Sản phẩm
        ├── deals             # Thuộc tính Cơ hội
        ├── orders            # Thuộc tính Đơn hàng
        ├── tickets           # Thuộc tính Ticket
        ├── tasks             # Thuộc tính Công việc
        └── meetings          # Thuộc tính Lịch hẹn

3. Tóm tắt lợi ích khi áp dụng

Tiêu chí	Hiện tại	Sau cải thiện
Đoán được URL	Khó (version, UUID lộ)	Dễ đoán, nhất quán
Nhất quán	snake_case lẫn camelCase lẫn lộn	Toàn bộ kebab-case
SEO-friendly	`/historycall`, `/call_v3`	`/calls`, `/callbot`
Mở rộng được	`general/` chứa tất cả	Nhóm theo domain rõ ràng
Khớp UI vs Route	`billing_info` != “Hồ sơ khách hàng”	Đồng bộ hoàn toàn
Ẩn technical detail	Version v3, v4 lộ rõ	Dùng tên tính năng