Skip to main content

Functional Specification: Service Configuration Upgrades — Tip (Commission), VAT, and Buffer Mechanics

Last Updated: 16/07/2026
Type: Functional Specification Upgrade — Service Settings
Scope: CMS Admin Panel (Service Creation/Edit Form) & POS Sync Integration
Severity: 🔴 High — Necessary for payroll calculations (KTV commission/tip) and tax compliance (VAT calculations)

Chat Transcript Reference:

1. Overview & Requirements​

Following alignment on POS sync and financial policies, the Spa Service schema needs to be upgraded with three additional parameters:

  1. KTV Tip (Commission): The fixed cash amount extracted from the service price to pay the therapist (Kỹ thuật viên - KTV) who performs the service.
  2. VAT (%): Value Added Tax percentage to be added to the service price.
  3. Clarification of Buffer Time: Understanding the mechanics of pre-service and post-service buffer times for scheduling synchronization.

2. Parameter Specifications & Calculations​

2.1 KTV Tip (Commission)​

  • Field Name: ktvCommission / ktvTip (Tiền tip/hoa hồng KTV)
  • Input Type: Number (Currency in VND)
  • Description: The fixed value allocated to the therapist's payroll per service completed.
  • Logic: Does not affect the price paid by the customer; it is an internal operational payout extracted from the net service revenue.

2.2 VAT (%)​

  • Field Name: vatRate (Thuế suất VAT)
  • Input Type: Number (Percentage, e.g. 8 or 10)
  • Description: Tax percentage added on top of the net service price.
  • Logic:
    • If a value is entered (e.g. 10): Gross Price (Giá thanh toán) = Net Price * (1 + 10/100).
    • If empty or 0: No tax is added; Gross Price = Net Price.

2.3 Buffer Time Mechanics (Pre-buffer & Post-buffer)​

When scheduling an appointment for a service (e.g., 90 minutes duration, 10 minutes pre-buffer, 10 minutes post-buffer):

┌─────────────────┬─────────────────────────────────┬─────────────────┐
│   Pre-Buffer    │        Service Duration         │   Post-Buffer   │
│   (10 mins)     │           (90 mins)             │   (10 mins)     │
├─────────────────┼─────────────────────────────────┼─────────────────┤
│ Room / tools    │ Hands-on massage therapy        │ Room cleanup,   │
│ setup by KTV    │                                 │ KTV rest, prep  │
│                 │                                 │ for next client │
└─────────────────┴─────────────────────────────────┴─────────────────┘
◄─────────────────────────── Total Blocked Time ──────────────────────►
                         (10 + 90 + 10 = 110 mins)
  • Pre-Buffer: Time reserved immediately before the client arrival to clean the room, layout oils/tools, and prepare the therapist.
  • Post-Buffer: Time reserved immediately after the service for room sanitation, therapist rest, and resetting the room for the next booking.
  • Scheduling Rule: The total blocked time on the branch calendar for a booking is Pre-buffer + Duration + Post-buffer.

3. CMS Form Redesign (Updated Fields)​

These fields should be integrated into the Service Modal (refactored in cms-popup-modal-width-increase.md):

┌────────────────────────────────────────────────────────────────────────┐
│  numerical attributes                                                  │
│                                                                        │
│  Giá trước thuế (VND)    Thuế VAT (%)           Tiền Tip KTV (VND)     │
│  [ 495000         ]      [ 10        ]          [ 50000            ]   │
│                                                                        │
│  Thời lượng (Phút)       Buffer trước (Phút)    Buffer sau (Phút)      │
│  [ 90             ]      [ 10        ]          [ 10               ]   │
└────────────────────────────────────────────────────────────────────────┘

4. Database & API Payload (Backend Schema)​

Update the Service DB model to accept the new financial and timing attributes:

interface SpaService {
  id: string;
  name: string;
  sku: string;
  basePrice: number;       // Net price before tax
  vatRate: number;         // Percentage (0, 8, 10, etc.)
  ktvTipAmount: number;    // Fixed VND payout to KTV
  durationMinutes: number; // Active service duration
  preBufferMinutes: number;
  postBufferMinutes: number;
  // ...other fields
}

API Save Payload Example:​

{
  "name": "Body Massage 90 phút",
  "sku": "GL-BODY-MASSAGE-90",
  "basePrice": 495000,
  "vatRate": 10,
  "ktvTipAmount": 50000,
  "durationMinutes": 90,
  "preBufferMinutes": 10,
  "postBufferMinutes": 10
}

Technical Checklist​

  • Add vatRate and ktvTipAmount to the database schema for the Spa Service entity.
  • Update the CMS Service edit modal view:
    • Add Thuế VAT (%) input field (numeric, accepts 0-100).
    • Add Tiền Tip KTV (VND) input field (currency mask / numeric input).
  • Implement price calculation helper on the frontend/backend:
    • Gross Price = basePrice * (1 + vatRate / 100).
  • Sync scheduling calendar logic: block room & therapist time slots as durationMinutes + preBufferMinutes + postBufferMinutes.
  • Verify validation: ensure vatRate defaults to 0 if left blank, and ktvTipAmount does not exceed basePrice.
  • Confirm POS Sync protocol is ready to transfer the new vatRate and ktvTipAmount parameters.