Files
minicrm/UI_DESIGN_BRIEF.md
phuongtc 887765bbd7 feat: AfterSales CRM - SOP compliant real-estate customer care system
- Departments + cross-department transfer workflow
- Role-based closing (staff→resolved, manager→closed) with proof_of_resolution
- Private file storage with collection system + temporary signed URLs
- Dashboard: resolved tickets table, stats, handler performance bar chart
- Spatie RBAC (admin/manager/staff)
- Notifications: TicketTransferred, TicketClosed (database + mail)
- Pest tests: 8 tests, 21 assertions
- Docker production-ready (Dockerfile + compose + entrypoint)
2026-04-27 05:29:48 +00:00

33 KiB
Raw Blame History

AFTERSALES CRM — UI REDESIGN BRIEF

Mục tiêu: Thiết kế lại toàn bộ giao diện webapp AfterSales CRM. Framework: Laravel 13.6 + Filament 5.6 + Tailwind CSS 4 Yêu cầu chính: Menu ngang (horizontal top bar) thay vì sidebar dọc để tiết kiệm không gian ngang. Đối tượng người dùng: Nhân viên CSKH, Trưởng phòng, Ban quản lý.


1. TỔNG QUAN HỆ THỐNG

AfterSales CRM là hệ thống chăm sóc khách hàng sau bán hàng trong lĩnh vực bất động sản. Luồng hoạt động:

Khách hàng gửi phản ánh → Nhân viên ghi nhận (Feedback) → Phân công xử lý →
Tương tác với khách → Chuyển phòng ban nếu cần → Xử lý xong (Resolved) →
Trưởng phòng kiểm tra bằng chứng → Đóng phiếu (Closed)

Các Role:

Role Quyền chính
Admin Toàn quyền, xem tất cả dashboard, đóng mọi ticket
Manager Quản lý phòng ban của mình, đóng ticket trong phòng mình
Staff Ghi nhận feedback, tương tác, không được đóng ticket

2. YÊU CẦU THIẾT KẾ

2.1 Navigation: MENU NGANG (Horizontal Top Bar)

Thay đổi so với hiện tại: Hiện tại dùng sidebar dọc bên trái. Yêu cầu chuyển thành menu ngang trên cùng.

Cấu trúc menu:

┌─────────────────────────────────────────────────────────────────────────┐
│ [Logo AfterSales CRM]  Dashboard │ Customer Care ▾ │ Management ▾     [🔔] [👤 Admin ▾] │
└─────────────────────────────────────────────────────────────────────────┘

Menu item chính:

STT Item Icon Action Note
1 Dashboard home /admin Trang chính
2 Customer Care (dropdown) chat-bubble-left-right submenu Dropdown xuống
3 Management (dropdown) cog submenu Dropdown xuống
4 Notifications (icon) bell dropdown notifications Badge số lượng chưa đọc
5 User menu (avatar + name) user-circle dropdown: Profile, Logout

Dropdown "Customer Care":

  • Feedbacks (chat-bubble-left-right)

Dropdown "Management":

  • Products (building-storefront)
  • Customers (user-group)
  • Channels (inbox-stack)
  • Tags (tag)

2.2 Layout Tổng Thể

┌──────────────────────────────────────────────────────────────────────────┐
│  TOP BAR (h=56px): Logo | Nav items | Notification bell | User avatar   │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  PAGE HEADER: Tiêu đề trang + Breadcrumb + Action Buttons                │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────────┐│
│  │                         CONTENT AREA                                 ││
│  │  (Form / Table / Widgets / Detail)                                   ││
│  │                                                                      ││
│  └──────────────────────────────────────────────────────────────────────┘│
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

Yêu cầu:

  • Top bar fixed khi scroll (sticky)
  • Responsive: mobile thì menu collapse thành hamburger
  • Content area full-width, padding 24px
  • Sidebar cũ bỏ hoàn toàn

3. TỪNG TRANG CHI TIẾT


3.1 TRANG DASHBOARD (/admin)

Hiển thị cho: Admin, Manager. Staff không thấy widget (chỉ thấy Account info).

Bố cục grid:

┌──────────────────────────────────┬──────────────────────────────────┐
│   STAT CARD 1: Resolved Tickets  │   STAT CARD 2: Avg Time         │
│   (success green)                │   (warning amber)               │
├──────────────────────────────────┼──────────────────────────────────┤
│   STAT CARD 3: Pending Tickets   │   STAT CARD 4: Escalated        │
│   (danger red)                   │   (gray)                        │
└──────────────────────────────────┴──────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────────────┐
│                 BAR CHART: Avg Processing Time by Handler                 │
│                 (Trục Y: phút, Trục X: tên nhân viên)                     │
└──────────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────────────┐
│                    TABLE: Tickets Awaiting Closure                        │
│  # │ Ticket (link) │ Customer │ Handler │ Department │ Resolved Date     │
│  1 │ Leaking...    │ Nguyen A │ Staff   │ Kỹ thuật   │ 15/04/2026       │
│  2 │ AC not cool   │ Tran B   │ Staff   │ Kỹ thuật   │ 12/04/2026       │
└──────────────────────────────────────────────────────────────────────────┘

Manager filter: Manager chỉ thấy dữ liệu của phòng ban mình quản lý.


3.2 TRANG DANH SÁCH FEEDBACK (/admin/feedbacks)

Page Header:

  • Title: "Feedbacks"
  • Breadcrumb: Dashboard > Feedbacks
  • Action button: [+ New Feedback] (primary, góc phải)

Filters Bar (ngang dưới header):

Filter Loại Options
Status Select Pending / Processing / Resolved / Closed
Channel Select Email / Zalo / Phone / Document / In Person
Department Select CSKH / Kỹ thuật / Kế toán / Pháp lý
Handler Select Danh sách user
[Reset Filters] button

Table:

# Title Customer Product Channel Tags Status Dept Handler Escal. Created
(search) (search) "General" nếu null badge list badge màu toggleable toggleable ⚠️/ toggleable

Status badge colors:

  • Pending: amber/yellow #f59e0b
  • Processing: blue #3b82f6
  • Resolved: green #10b981
  • Closed: gray #6b7280

Row hover + clickable: Click row → mở Edit page. Hoặc nút Edit cuối hàng.

Bulk Actions (checkbox đầu hàng):

  • Delete Selected
  • Export (tùy chọn)

3.3 TRANG TẠO FEEDBACK (/admin/feedbacks/create)

Form layout 2 cột:

┌──────────────────────────────────┬──────────────────────────────────┐
│ Customer * (search dropdown)     │ Kênh tiếp nhận *                 │
├──────────────────────────────────┼──────────────────────────────────┤
│ ☐ General feedback              │                                  │
├──────────────────────────────────┼──────────────────────────────────┤
│ Product (chỉ hiện nếu bỏ chọn   │                                  │
│ "General", lọc theo customer)   │                                  │
├──────────────────────────────────┴──────────────────────────────────┤
│ Title *                                                             │
├─────────────────────────────────────────────────────────────────────┤
│ Content * (textarea 6 dòng, full width)                             │
├─────────────────────────────────────────────────────────────────────┤
│ Attachment Collection: [General ▾]                                  │
│ 📎 Upload files (drag & drop, multiple, max 20MB)                   │
├─────────────────────────────────────────────────────────────────────┤
│ Tags (multi-select, có thể tạo mới tag inline)                      │
├──────────────────────────────────┬──────────────────────────────────┤
│ Status * (mặc định: Pending)     │ Assign To                        │
├──────────────────────────────────┼──────────────────────────────────┤
│ Department                       │ ☐ Escalated (chỉ admin/manager   │
│                                  │     mới thấy)                    │
└──────────────────────────────────┴──────────────────────────────────┘

          [Cancel]                          [Create Feedback]

Attachment Collection options:

  • General (mặc định)
  • Proof of Resolution (bằng chứng xử lý)
  • Customer Evidence (bằng chứng khách hàng cung cấp)

File validation: Chỉ chấp nhận jpg, png, pdf, mp4, mov. Max 20MB/file.

Lưu ý: Sau khi tạo, tự động ghi 1 interaction "Feedback created via [kênh]".


3.4 TRANG EDIT FEEDBACK (/admin/feedbacks/{id}/edit)

QUAN TRỌNG: Đây là trang phức tạp nhất, gồm 3 phần + 2 tab.

Page Header (sticky khi scroll):

┌─ Breadcrumb: Dashboard > Feedbacks > [Title] ──────────────────────────┐
│                                                                         │
│  [← Back]  Status: [PENDING ●]  Dept: CSP  Handler: Staff              │
│                                                                         │
│  [Transfer Dept]  [Close Ticket]  [Save]  [Delete]                     │
└─────────────────────────────────────────────────────────────────────────┘

3 Action buttons quan trọng ở header:

Action 1: Transfer Department (chỉ Admin, Manager thấy)

┌─────────────────────────────────────────┐
│           Transfer Department           │
│                                         │
│  Target Department *  [Kỹ thuật ▾]     │
│  Assign To            [── select ──▾]  │
│  Reason *             [___________]    │
│  Attachments          📎 Upload files   │
│                                         │
│            [Cancel]  [Transfer]         │
└─────────────────────────────────────────┘
  • Reason bắt buộc (nếu để trống: báo lỗi)
  • Sau khi transfer: gửi notification cho Manager phòng nhận, cập nhật department, reset handler

Action 2: Close Ticket (chỉ Admin, Manager thấy, và status ≠ closed)

┌─────────────────────────────────────────┐
│  ⚠️ Bạn có chắc muốn đóng phiếu này?   │
│  Hành động này KHÔNG thể hoàn tác.      │
│                                         │
│            [Cancel]  [Close]            │
└─────────────────────────────────────────┘
  • Chỉ đóng được nếu có ít nhất 1 file trong collection "proof_of_resolution"
  • Manager chỉ đóng được ticket thuộc phòng mình quản lý
  • Nếu thiếu bằng chứng: hiển thị lỗi "Yêu cầu cung cấp tài liệu bằng chứng"
  • Nếu sai phòng ban: hiển thị lỗi "Bạn chỉ có thể đóng phiếu thuộc phòng ban mình quản lý"

Action 3: Delete


Body: 3 TAB layout

┌──────────────────────────────────────────────────────┐
│ [📝 Edit Details] [💬 Interaction History (5)]       │
└──────────────────────────────────────────────────────┘

TAB 1: Edit Details

Form giống hệt Create Page, có thêm pre-fill dữ liệu hiện có.

TAB 2: Interaction History (Timeline)

Đây là tab QUAN TRỌNG NHẤT. Thiết kế dạng timeline dọc.

Header của tab:

┌──────────────────────────────────────────────────────────────┐
│  Interaction History                          [+ Add Note ▾] │
│                                                              │
│  Dropdown khi click "Add Note":                              │
│    • 📝 Add Note                                             │
│    • 🔄 Change Status                                        │
│    • 👤 Assign / Forward                                     │
└──────────────────────────────────────────────────────────────┘

Modal "Add Interaction" (mở khi chọn 1 trong 3 action trên):

┌──────────────────────────────────────────────────────────┐
│  Type: [📝 Note ▾ | 🔄 Status Change | 👤 Assignment]   │
│                                                          │
│  Title (chỉ hiện khi type=Note)  [___________]          │
│                                                          │
│  Content * (Rich Editor, full width)                     │
│  ┌────────────────────────────────────────────────────┐  │
│  │  B  I  U  • ≡  🔗  🖼                              │  │
│  │                                                    │  │
│  │                                                    │  │
│  └────────────────────────────────────────────────────┘  │
│                                                          │
│  --- Các field theo type ---                             │
│                                                          │
│  Nếu Status Change:                                      │
│    New Status * [Pending ▾]                              │
│    (Staff chỉ thấy: Pending/Processing/Resolved)         │
│    (Admin/Manager thấy thêm: Closed)                     │
│                                                          │
│  Nếu Assignment:                                         │
│    Assign To * [── chọn user ──▾]                       │
│    Target Department  [── chọn phòng ──▾]               │
│                                                          │
│  📎 Attachments (luôn hiện, mọi type)                    │
│  [Upload files...]                                       │
│                                                          │
│                          [Cancel]    [Add Interaction]   │
└──────────────────────────────────────────────────────────┘

Timeline hiển thị (dạng dọc, newest first):

┌── 15/04/2026 ──────────────────────────────────────────────────────┐
│                                                                     │
│  ● 14:30  👤 Staff                                                 │
│  │  ┌─────────────────────────────────────────────────────────┐    │
│  │  │ [Status Change] 🔵                                       │    │
│  │  │ Technician visited site. AC repaired.                    │    │
│  │  │ Status: processing → resolved                             │    │
│  │  │ 📎 2 files  [View ▾]                                     │    │
│  │  └─────────────────────────────────────────────────────────┘    │
│  │                                                                  │
│  ● 10:15  👤 Manager                                               │
│  │  ┌─────────────────────────────────────────────────────────┐    │
│  │  │ [Assignment] 🟡                                          │    │
│  │  │ Chuyển sang Phòng Kỹ thuật để kiểm tra điều hòa.         │    │
│  │  │ Assignment: Staff → Manager                               │    │
│  │  │ Department: CSKH → Kỹ thuật                               │    │
│  │  │ 📎 1 file  [View ▾]                                      │    │
│  │  └─────────────────────────────────────────────────────────┘    │
│                                                                     │
└── 14/04/2026 ──────────────────────────────────────────────────────┘
│
│  ● 09:00  👤 Admin
│  │  ┌─────────────────────────────────────────────────────────┐
│  │  │ [Note] ⚪                                                │
│  │  │ Feedback received via Email.                             │
│  │  │ Status: — → pending                                      │
│  │  └─────────────────────────────────────────────────────────┘

Type badge colors:

  • Note: gray #6b7280
  • Status Change: blue #3b82f6
  • Assignment: amber/orange #f59e0b

Khi click [View ▾] trên file attachment:

┌───────────────────────────────────────────────┐
│                Attachments                    │
│                                               │
│  File         │ Collection       │ Size │     │
│  repair.pdf   │ proof_of_resol.  │200KB │[⬇] │
│  photo.jpg    │ customer_evid.   │500KB │[⬇] │
│                                               │
│  Links expire after 60 minutes.               │
└───────────────────────────────────────────────┘
  • Collection badge: proof_of_resolution → green, customer_evidence → blue, general → gray
  • Download button → mở signed URL (có thời hạn 60 phút) trong tab mới

Below tabs: Similar Cases section

┌──────────────────────────────────────────────────────────────────┐
│  🔗 Similar Cases (shared tags)                                   │
│                                                                   │
│  Title              │ Customer │ Status    │ Handler  │ Date     │
│  Leaking bathroom   │ Tran B   │ Processing│ Manager │10/04/26  │
│  Water damage       │ Le Van C │ Pending   │ Staff   │08/04/26  │
│                                                                   │
│  (Chỉ hiện nếu có ≥1 feedback cùng tag, khác ID hiện tại, max 5) │
└──────────────────────────────────────────────────────────────────┘

3.5 TRANG SẢN PHẨM (/admin/products)

Table:

Name Status Description Owners Created
(search) badge: active🟢 / inactive / sold out🔴 toggleable, limit 50 count toggleable

Form (2 cột):

Name *              Status * [Active ▾]
Description (textarea full width)

3.6 TRANG KHÁCH HÀNG (/admin/customers)

Table:

Name Email Phone Status Products Feedbacks Created
(search) toggleable toggleable badge count count toggleable

Form (2 cột):

Name *                    Email
Phone                     Status * [Active ▾]
Address (textarea full width)

── Owned Products ──
Products (multi-select) [Sunrise A1 ✕] [Green Valley ✕] [ add]

Tab "Feedback History" trên Edit Customer:

┌─────────────────┬─────────┬────────┬──────┬─────────┬────────────┬────────┐
│ Title (link ▶)  │ Product │ Status │ Tags │ Channel │Interactions│ Created │
└─────────────────┴─────────┴────────┴──────┴─────────┴────────────┴────────┘
  • Title là clickable link → mở Edit Feedback
  • Filters: Status, Tags

3.7 TRANG KÊNH TIẾP NHẬN (/admin/channels)

Table:

Name Slug Active Feedbacks Created
(search) (search) / count toggleable

Form (2 cột):

Name *           Slug *
Icon [________]  ☑ Active (toggle, default true)

3.8 TRANG TAGS (/admin/tags)

Table:

Name Slug Color Created Updated
(search) (search) (search) toggleable toggleable

Form:

Name *     Slug *     Color [________]

4. HỆ THỐNG THÔNG BÁO

Notification Bell (góc phải top bar)

Khi có thông báo mới → badge đỏ hiển thị số lượng.

Dropdown notifications:

┌─────────────────────────────────────────────────────┐
│  🔔 Notifications                       Mark all read│
│─────────────────────────────────────────────────────│
│  🔵 Ticket #3 "AC not cooling" đã được chuyển       │
│     đến phòng của bạn bởi Manager.                  │
│     ⏱ 5 phút trước                    [Xem ▶]      │
│─────────────────────────────────────────────────────│
│  ⚪ Ticket #5 "Kitchen hinge" đã được đóng           │
│     bởi Staff.                                      │
│     ⏱ 1 giờ trước                      [Xem ▶]     │
│─────────────────────────────────────────────────────│
│            [Xem tất cả thông báo]                    │
└─────────────────────────────────────────────────────┘
  • Chưa đọc: background xanh nhạt, có chấm 🔵
  • Đã đọc: background trắng
  • [Xem ▶] → mở ticket trong tab mới

5. MÀU SẮC & DESIGN TOKENS

Bảng màu chính

Token Màu Dùng cho
Primary #3b82f6 (blue-500) Buttons chính, links, menu active
Success #10b981 (emerald-500) Status resolved, badges proof
Warning #f59e0b (amber-500) Status pending, assignment badges
Danger #ef4444 (red-500) Delete buttons, escalated flags
Info #3b82f6 (blue-500) Status processing, status_change badges
Gray #6b7280 (gray-500) Note badges, closed status, muted text
Background #f9fafb (gray-50) Page background
Card #ffffff Card/panel backgrounds
Border #e5e7eb (gray-200) Dividers, table borders

Typography

  • Font: System font stack (Inter hoặc SF Pro)
  • Headings: font-semibold
  • Body: font-normal, text-sm (14px)
  • Small: text-xs (12px)

Shadows

  • Card: shadow-sm (0 1px 2px)
  • Modal: shadow-xl (0 20px 25px)
  • Top bar: shadow-sm + border-b

6. RESPONSIVE BREAKPOINTS

Breakpoint Width Layout
Mobile <640px Menu hamburger, form 1 cột, table scroll ngang
Tablet 640-1024px Menu rút gọn, form 2 cột
Desktop >1024px Full layout, menu đầy đủ

Lưu ý mobile:

  • Top bar: logo + hamburger menu
  • Table: scroll ngang (horizontal scroll)
  • Form: chuyển 2 cột thành 1 cột
  • Stat cards: chuyển 4 cột → 2 cột → 1 cột
  • Modal: full-screen trên mobile

7. DARK MODE

Hỗ trợ dark mode toggle (nút ☀️/🌙 trong top bar).

Element Light Dark
Background bg-gray-50 bg-gray-950
Card bg-white bg-gray-900
Text chính text-gray-900 text-gray-100
Text phụ text-gray-500 text-gray-400
Border border-gray-200 border-gray-800
Top bar bg-white border-b bg-gray-900 border-gray-800

8. CÁC LƯU Ý QUAN TRỌNG KHI THIẾT KẾ

A. Không được bỏ sót

  1. Form Feedback có toggle "General feedback" — khi bật, ẩn field Product, set customer_product_id = null
  2. Form Edit Feedback có field is_escalated — chỉ admin/manager mới thấy
  3. Dropdown status trong Interaction — staff KHÔNG thấy option "Closed"
  4. Collection selector cho file upload — 3 lựa chọn: General / Proof of Resolution / Customer Evidence
  5. Similar Cases — chỉ hiện khi có tag chung, max 5 items
  6. View Attachments modal — có collection badge màu, download link hết hạn 60 phút

B. Điều kiện hiển thị

  • Transfer Department button: Chỉ admin + manager
  • Close Ticket button: Chỉ admin + manager, và status ≠ closed
  • Dashboard widgets: Chỉ admin + manager
  • Escalated toggle: Chỉ admin + manager
  • Role-based status options: Staff không thấy "Closed"

C. Validation

  • Transfer yêu cầu reason (không được để trống)
  • Close ticket yêu cầu có proof_of_resolution attachment
  • Manager chỉ đóng được ticket phòng mình quản lý
  • File upload: jpg/png/pdf/mp4/mov, max 20MB

D. Tương tác ngầm

  • Khi chọn Customer → Product dropdown tự lọc theo customer đó
  • Khi chọn type="Status Change" → hiện New Status dropdown
  • Khi chọn type="Assignment" → hiện Assign To + Department dropdown
  • Sau khi Transfer Department → tự động gán handler = Manager của phòng mới (nếu không chọn ai)

E. SEO/Meta

  • Title: "AfterSales CRM"
  • Favicon: icon phù hợp

9. FILE STRUCTURE (để A.I agent biết code ở đâu)

app/Filament/
  Resources/
    Feedback/
      Pages/EditFeedback.php     ← Header actions (Transfer, Close, Delete)
      Schemas/FeedbackForm.php   ← Form 13 fields
      Tables/FeedbackTable.php   ← Table 10 columns
      RelationManagers/
        InteractionsRelationManager.php  ← Timeline + View Attachments
    Customers/
      CustomerResource.php       ← Form + Table
      RelationManagers/
        FeedbacksRelationManager.php  ← Feedback history tab
    Products/ProductResource.php
    FeedbackChannels/FeedbackChannelResource.php
    FeedbackTags/FeedbackTagResource.php
  Widgets/
    ResolvedTicketsWidget.php
    AvgProcessingTimeWidget.php
    HandlerPerformanceWidget.php
  Providers/Filament/AdminPanelProvider.php  ← Panel config, nav groups

resources/views/filament/resources/feedback/
  similar-cases.blade.php       ← Similar Cases HTML
  attachment-links.blade.php    ← Attachment links modal HTML

10. TÓM TẮT CÁC MÀN HÌNH

# Màn hình Route Thành phần chính
1 Dashboard /admin 4 stat cards + chart + resolved table
2 Login /admin/login Email + Password + Login button
3 Feedback List /admin/feedbacks Table 10 cột + 4 filters + Create button
4 Create Feedback /admin/feedbacks/create Form 13 fields, 2 cột
5 Edit Feedback /admin/feedbacks/{id}/edit Form + 3 header actions + Timeline tab + Similar Cases
6 Product List /admin/products Table 5 cột + status filter
7 Create/Edit Product /admin/products/... Form 3 fields
8 Customer List /admin/customers Table 7 cột + status filter
9 Create/Edit Customer /admin/customers/... Form 6 fields + Feedback History tab
10 Channel List /admin/channels Table 5 cột
11 Create/Edit Channel /admin/channels/... Form 4 fields
12 Tag List /admin/tags Table 5 cột
13 Create/Edit Tag /admin/tags/... Form 3 fields

Tổng số màn hình: 13 màn hình | 5 Resource | 3 Widget | 2 Relation Manager | 2 Blade View

File này đủ chi tiết để một AI Agent khác thiết kế lại toàn bộ giao diện mà không bỏ sót tính năng nào.