project initialization

docs/api/README.md

@@ -0,0 +1,119 @@
+# API Documentation
+
+This directory contains comprehensive API documentation for the Multi-Tenant SaaS Platform for Malaysian SMEs.
+
+## Table of Contents
+
+- [Core API](./core/README.md) - Authentication, tenants, users, subscriptions
+- [Retail Module API](./retail/README.md) - Products, sales, inventory, customer management
+- [Healthcare Module API](./healthcare/README.md) - Patients, appointments, medical records
+- [Education Module API](./education/README.md) - Students, classes, enrollment
+- [Logistics Module API](./logistics/README.md) - Shipments, vehicles, tracking
+- [Beauty Module API](./beauty/README.md) - Clients, services, appointments
+
+## API Standards
+
+### Base URL
+```
+https://api.yourplatform.com/v1
+```
+
+### Authentication
+All API endpoints require authentication using Bearer tokens:
+```
+Authorization: Bearer <your-access-token>
+```
+
+### Response Format
+All responses follow this standard format:
+
+```json
+{
+  "success": true,
+  "data": {},
+  "message": "Success message",
+  "timestamp": "2024-01-01T00:00:00Z",
+  "request_id": "req_123456789"
+}
+```
+
+### Error Handling
+```json
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Detailed error message",
+    "details": {}
+  },
+  "timestamp": "2024-01-01T00:00:00Z",
+  "request_id": "req_123456789"
+}
+```
+
+### HTTP Status Codes
+- `200` - Success
+- `201` - Created
+- `400` - Bad Request
+- `401` - Unauthorized
+- `403` - Forbidden
+- `404` - Not Found
+- `422` - Validation Error
+- `429` - Rate Limited
+- `500` - Internal Server Error
+
+### Multi-Tenant Headers
+All requests must include the tenant identifier:
+```
+X-Tenant-ID: <tenant-id>
+```
+
+### Rate Limiting
+- Standard endpoints: 100 requests per minute
+- Auth endpoints: 10 requests per minute
+- File upload endpoints: 20 requests per minute
+
+## Malaysian Market Features
+
+### SST (Sales and Service Tax)
+All pricing-related endpoints include SST calculation and display:
+```json
+{
+  "subtotal": 100.00,
+  "sst_rate": 0.06,
+  "sst_amount": 6.00,
+  "total": 106.00
+}
+```
+
+### Malaysian Phone Validation
+Phone numbers are validated according to Malaysian formats:
+- `+60123456789` or `0123456789`
+- Mobile numbers: `01[2-46-9]`
+
+### Business Registration
+All tenant endpoints validate Malaysian business registration numbers.
+
+### Malaysian Timezone
+All timestamps are in `Asia/Kuala_Lumpur` timezone.
+
+## Getting Started
+
+1. [Obtain API credentials](./core/authentication.md)
+2. [Create your first tenant](./core/tenants.md)
+3. [Set up your modules](./core/modules.md)
+4. [Explore module-specific APIs](./retail/README.md)
+
+## SDKs
+
+We provide official SDKs for:
+- [Python SDK](../sdks/python/README.md)
+- [JavaScript SDK](../sdks/javascript/README.md)
+- [PHP SDK](../sdks/php/README.md)
+
+## Support
+
+For API support:
+- Email: api-support@yourplatform.com
+- Documentation: https://docs.yourplatform.com
+- Status Page: https://status.yourplatform.com

docs/api/beauty/README.md

@@ -0,0 +1,804 @@
+# Beauty Module API Documentation
+
+## Overview
+
+The Beauty Module API provides comprehensive functionality for beauty salons and spas including client management, service catalog, appointment scheduling, and Malaysian beauty industry compliance.
+
+## Clients
+
+### Create Client
+```http
+POST /api/v1/beauty/clients/
+```
+
+**Request Body:**
+```json
+{
+  "first_name": "Siti",
+  "last_name": "Aminah",
+  "email": "siti.aminah@example.com",
+  "phone_number": "+60123456789",
+  "ic_number": "900101-01-1234",
+  "date_of_birth": "1990-01-01",
+  "gender": "female",
+  "address": {
+    "street": "123 Client Street",
+    "city": "Kuala Lumpur",
+    "state": "Wilayah Persekutuan",
+    "postal_code": "50050",
+    "country": "Malaysia"
+  },
+  "emergency_contact": {
+    "name": "Hassan Ibrahim",
+    "relationship": "husband",
+    "phone_number": "+60123456788"
+  },
+  "skin_type": "combination",
+  "hair_type": "colored",
+  "allergies": ["fragrance", "nuts"],
+  "medical_conditions": ["eczema"],
+  "preferred_services": ["facial", "manicure", "hair_treatment"],
+  "frequency": "monthly",
+  "membership_level": "gold",
+  "loyalty_points": 1250,
+  "notes": "Prefers organic products, sensitive to strong fragrances",
+  "marketing_consent": true,
+  "pdpa_consent": true
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "cli_123456",
+    "first_name": "Siti",
+    "last_name": "Aminah",
+    "email": "siti.aminah@example.com",
+    "phone_number": "+60123456789",
+    "ic_number": "900101-01-1234",
+    "date_of_birth": "1990-01-01",
+    "gender": "female",
+    "address": {
+      "street": "123 Client Street",
+      "city": "Kuala Lumpur",
+      "state": "Wilayah Persekutuan",
+      "postal_code": "50050",
+      "country": "Malaysia"
+    },
+    "emergency_contact": {
+      "name": "Hassan Ibrahim",
+      "relationship": "husband",
+      "phone_number": "+60123456788"
+    },
+    "skin_type": "combination",
+    "hair_type": "colored",
+    "allergies": ["fragrance", "nuts"],
+    "medical_conditions": ["eczema"],
+    "preferred_services": ["facial", "manicure", "hair_treatment"],
+    "frequency": "monthly",
+    "membership_level": "gold",
+    "loyalty_points": 1250,
+    "notes": "Prefers organic products, sensitive to strong fragrances",
+    "marketing_consent": true,
+    "pdpa_consent": true,
+    "pdpa_consent_date": "2024-01-01T00:00:00Z",
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### Get Client
+```http
+GET /api/v1/beauty/clients/{client_id}/
+```
+
+### Update Client
+```http
+PUT /api/v1/beauty/clients/{client_id}/
+```
+
+### List Clients
+```http
+GET /api/v1/beauty/clients/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `membership_level` - Filter by membership level
+- `skin_type` - Filter by skin type
+- `hair_type` - Filter by hair type
+- `search` - Search in name, email, phone
+- `frequency` - Filter by visit frequency
+
+### Delete Client
+```http
+DELETE /api/v1/beauty/clients/{client_id}/
+```
+
+### Get Client History
+```http
+GET /api/v1/beauty/clients/{client_id}/history/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+
+## Services
+
+### Create Service
+```http
+POST /api/v1/beauty/services/
+```
+
+**Request Body:**
+```json
+{
+  "name": "Premium Anti-Aging Facial",
+  "description": "Advanced facial treatment with anti-aging properties",
+  "category": "facial",
+  "subcategory": "anti_aging",
+  "duration_minutes": 90,
+  "price": 350.00,
+  "tax_rate": 6.0,
+  "staff_level_required": "senior",
+  "room_requirements": ["facial_bed", "steamer", "extractor"],
+  "products_used": ["serum", "moisturizer", "mask"],
+  "target_skin_types": ["all"],
+  "contraindications": ["active_acne", "pregnancy", "recent_surgery"],
+  "pre_care_instructions": "Avoid sun exposure 24 hours before treatment",
+  "post_care_instructions": "Use gentle skincare products for 48 hours",
+  "membership_discount": 15.0,
+  "promotion_discount": 10.0,
+  "is_active": true,
+  "kkm_approved": true,
+  "kkm_approval_number": "KKM-BEAUTY-12345",
+  "halal_certified": true,
+  "halal_certification_number": "JAKIM-1234-5678",
+  "notes": "Popular treatment for mature skin"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "svc_123456",
+    "name": "Premium Anti-Aging Facial",
+    "description": "Advanced facial treatment with anti-aging properties",
+    "category": "facial",
+    "subcategory": "anti_aging",
+    "duration_minutes": 90,
+    "price": 350.00,
+    "tax_rate": 6.0,
+    "staff_level_required": "senior",
+    "room_requirements": ["facial_bed", "steamer", "extractor"],
+    "products_used": ["serum", "moisturizer", "mask"],
+    "target_skin_types": ["all"],
+    "contraindications": ["active_acne", "pregnancy", "recent_surgery"],
+    "pre_care_instructions": "Avoid sun exposure 24 hours before treatment",
+    "post_care_instructions": "Use gentle skincare products for 48 hours",
+    "membership_discount": 15.0,
+    "promotion_discount": 10.0,
+    "is_active": true,
+    "kkm_approved": true,
+    "kkm_approval_number": "KKM-BEAUTY-12345",
+    "halal_certified": true,
+    "halal_certification_number": "JAKIM-1234-5678",
+    "notes": "Popular treatment for mature skin",
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### Get Service
+```http
+GET /api/v1/beauty/services/{service_id}/
+```
+
+### Update Service
+```http
+PUT /api/v1/beauty/services/{service_id}/
+```
+
+### List Services
+```http
+GET /api/v1/beauty/services/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `category` - Filter by category
+- `subcategory` - Filter by subcategory
+- `min_price` - Minimum price
+- `max_price` - Maximum price
+- `is_active` - Filter by active status
+- `halal_certified` - Filter by halal certification
+
+### Delete Service
+```http
+DELETE /api/v1/beauty/services/{service_id}/
+```
+
+## Appointments
+
+### Create Appointment
+```http
+POST /api/v1/beauty/appointments/
+```
+
+**Request Body:**
+```json
+{
+  "client_id": "cli_123456",
+  "services": [
+    {
+      "service_id": "svc_123456",
+      "staff_id": "stf_123456",
+      "start_time": "2024-01-15T10:00:00Z",
+      "end_time": "2024-01-15T11:30:00Z"
+    },
+    {
+      "service_id": "svc_789012",
+      "staff_id": "stf_789012",
+      "start_time": "2024-01-15T11:45:00Z",
+      "end_time": "2024-01-15T12:30:00Z"
+    }
+  ],
+  "total_price": 550.00,
+  "total_duration_minutes": 135,
+  "status": "confirmed",
+  "payment_status": "paid",
+  "payment_method": "credit_card",
+  "notes": "Client prefers morning appointments",
+  "special_requests": "Use fragrance-free products",
+  "reminder_preferences": {
+    "email": true,
+    "sms": true,
+    "reminder_hours_before": 24
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "apt_123456",
+    "client_id": "cli_123456",
+    "services": [
+      {
+        "service_id": "svc_123456",
+        "service_name": "Premium Anti-Aging Facial",
+        "staff_id": "stf_123456",
+        "staff_name": "Nurul Aminah",
+        "start_time": "2024-01-15T10:00:00Z",
+        "end_time": "2024-01-15T11:30:00Z",
+        "price": 350.00
+      },
+      {
+        "service_id": "svc_789012",
+        "service_name": "Classic Manicure",
+        "staff_id": "stf_789012",
+        "staff_name": "Farah Ibrahim",
+        "start_time": "2024-01-15T11:45:00Z",
+        "end_time": "2024-01-15T12:30:00Z",
+        "price": 200.00
+      }
+    ],
+    "total_price": 550.00,
+    "total_duration_minutes": 135,
+    "status": "confirmed",
+    "payment_status": "paid",
+    "payment_method": "credit_card",
+    "notes": "Client prefers morning appointments",
+    "special_requests": "Use fragrance-free products",
+    "reminder_preferences": {
+      "email": true,
+      "sms": true,
+      "reminder_hours_before": 24
+    },
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### Get Appointment
+```http
+GET /api/v1/beauty/appointments/{appointment_id}/
+```
+
+### Update Appointment
+```http
+PUT /api/v1/beauty/appointments/{appointment_id}/
+```
+
+### List Appointments
+```http
+GET /api/v1/beauty/appointments/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `client_id` - Filter by client
+- `staff_id` - Filter by staff
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+- `status` - Filter by status (pending, confirmed, in_progress, completed, cancelled, no_show)
+
+### Cancel Appointment
+```http
+POST /api/v1/beauty/appointments/{appointment_id}/cancel/
+```
+
+**Request Body:**
+```json
+{
+  "reason": "Client unable to attend",
+  "cancelled_by": "client",
+  "refund_amount": 0.00
+}
+```
+
+### Check-in Client
+```http
+POST /api/v1/beauty/appointments/{appointment_id}/check-in/
+```
+
+### Start Service
+```http
+POST /api/v1/beauty/appointments/{appointment_id}/start/
+```
+
+### Complete Appointment
+```http
+POST /api/v1/beauty/appointments/{appointment_id}/complete/
+```
+
+**Request Body:**
+```json
+{
+  "services_rendered": [
+    {
+      "service_id": "svc_123456",
+      "notes": "Good skin condition, minimal blackheads",
+      "products_used": ["anti-aging serum", "moisturizer"],
+      "recommendations": ["Continue with home care routine"]
+    }
+  ],
+  "total_amount": 550.00,
+  "payment_received": 550.00,
+  "payment_method": "credit_card",
+  "staff_notes": "Client satisfied with results",
+  "follow_up_required": true,
+  "follow_up_date": "2024-02-15"
+}
+```
+
+## Staff
+
+### Create Staff
+```http
+POST /api/v1/beauty/staff/
+```
+
+**Request Body:**
+```json
+{
+  "first_name": "Nurul",
+  "last_name": "Aminah",
+  "email": "nurul.aminah@beautysalon.com",
+  "phone_number": "+60123456789",
+  "ic_number": "900101-01-1234",
+  "date_of_birth": "1990-01-01",
+  "gender": "female",
+  "address": {
+    "street": "123 Staff Street",
+    "city": "Kuala Lumpur",
+    "state": "Wilayah Persekutuan",
+    "postal_code": "50050",
+    "country": "Malaysia"
+  },
+  "position": "senior_beauty_therapist",
+  "specializations": ["facial", "massage", "waxing"],
+  "certifications": [
+    {
+      "name": "CIDESCO Diploma",
+      "issuing_body": "CIDESCO International",
+      "certificate_number": "CID-123456",
+      "issue_date": "2020-01-01",
+      "expiry_date": "2025-01-01"
+    },
+    {
+      "name": "Malaysian Beauty Therapy Certificate",
+      "issuing_body": "KKM",
+      "certificate_number": "KKM-BT-123456",
+      "issue_date": "2019-06-01",
+      "expiry_date": "2024-06-01"
+    }
+  ],
+  "experience_years": 8,
+  "hourly_rate": 50.00,
+  "commission_rate": 15.0,
+  "employment_status": "full_time",
+  "working_hours": {
+    "monday": ["09:00-18:00"],
+    "tuesday": ["09:00-18:00"],
+    "wednesday": ["09:00-18:00"],
+    "thursday": ["09:00-18:00"],
+    "friday": ["09:00-18:00"],
+    "saturday": ["10:00-17:00"],
+    "sunday": []
+  },
+  "skills": ["advanced_facial", "microdermabrasion", "chemical_peel"],
+  "languages": ["english", "malay", "mandarin"],
+  "emergency_contact": {
+    "name": "Aminah Hassan",
+    "relationship": "mother",
+    "phone_number": "+60123456788"
+  },
+  "status": "active",
+  "notes": "Excellent customer service skills"
+}
+```
+
+### Get Staff
+```http
+GET /api/v1/beauty/staff/{staff_id}/
+```
+
+### Update Staff
+```http
+PUT /api/v1/beauty/staff/{staff_id}/
+```
+
+### List Staff
+```http
+GET /api/v1/beauty/staff/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `position` - Filter by position
+- `specialization` - Filter by specialization
+- `status` - Filter by status
+- `employment_status` - Filter by employment status
+
+### Delete Staff
+```http
+DELETE /api/v1/beauty/staff/{staff_id}/
+```
+
+### Get Staff Schedule
+```http
+GET /api/v1/beauty/staff/{staff_id}/schedule/
+```
+
+**Query Parameters:**
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+
+## Products
+
+### Create Product
+```http
+POST /api/v1/beauty/products/
+```
+
+**Request Body:**
+```json
+{
+  "name": "Anti-Aging Serum",
+  "brand": "GlowBeauty",
+  "description": "Advanced anti-aging serum with hyaluronic acid",
+  "category": "skincare",
+  "subcategory": "serum",
+  "sku": "GB-AS-001",
+  "barcode": "9555123456789",
+  "volume_ml": 30,
+  "price": 180.00,
+  "tax_rate": 6.0,
+  "stock_quantity": 50,
+  "minimum_stock": 10,
+  "ingredients": ["hyaluronic_acid", "vitamin_c", "retinol"],
+  "skin_types": ["all"],
+  "age_groups": ["adult", "mature"],
+  "expiry_date": "2026-01-01",
+  "batch_number": "GB-2024-001",
+  "supplier": "GlowBeauty Supplies Sdn Bhd",
+  "kkm_approved": true,
+  "kkm_notification_number": "NOT202400123456",
+  "halal_certified": true,
+  "halal_certification_number": "JAKIM-1234-5678",
+  "cruelty_free": true,
+  "vegan": false,
+  "organic": false,
+  "is_active": true
+}
+```
+
+### Get Product
+```http
+GET /api/v1/beauty/products/{product_id}/
+```
+
+### Update Product
+```http
+PUT /api/v1/beauty/products/{product_id}/
+```
+
+### List Products
+```http
+GET /api/v1/beauty/products/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `category` - Filter by category
+- `subcategory` - Filter by subcategory
+- `brand` - Filter by brand
+- `min_price` - Minimum price
+- `max_price` - Maximum price
+- `halal_certified` - Filter by halal certification
+- `low_stock` - Show low stock items
+
+### Delete Product
+```http
+DELETE /api/v1/beauty/products/{product_id}/
+```
+
+## Packages and Memberships
+
+### Create Package
+```http
+POST /api/v1/beauty/packages/
+```
+
+**Request Body:**
+```json
+{
+  "name": "Beauty Queen Package",
+  "description": "Complete beauty treatment package",
+  "services": [
+    {
+      "service_id": "svc_123456",
+      "frequency": "monthly",
+      "duration_months": 12
+    },
+    {
+      "service_id": "svc_789012",
+      "frequency": "bi_weekly",
+      "duration_months": 12
+    }
+  ],
+  "total_price": 4800.00,
+  "original_price": 6000.00,
+  "discount_percentage": 20.0,
+  "validity_months": 12,
+  "payment_plan": "full_payment",
+  "terms_and_conditions": "Non-refundable, non-transferable",
+  "is_active": true,
+  "membership_discount": 5.0
+}
+```
+
+### Create Membership
+```http
+POST /api/v1/beauty/memberships/
+```
+
+**Request Body:**
+```json
+{
+  "client_id": "cli_123456",
+  "membership_type": "gold",
+  "start_date": "2024-01-01",
+  "end_date": "2025-01-01",
+  "annual_fee": 500.00,
+  "benefits": [
+    {
+      "benefit": "15% discount on all services",
+      "type": "percentage_discount",
+      "value": 15.0
+    },
+    {
+      "benefit": "Free birthday facial",
+      "type": "free_service",
+      "service_id": "svc_123456"
+    },
+    {
+      "benefit": "Priority booking",
+      "type": "priority"
+    }
+  ],
+  "payment_method": "credit_card",
+  "auto_renew": true,
+  "status": "active"
+}
+```
+
+## Reports and Analytics
+
+### Sales Report
+```http
+GET /api/v1/beauty/reports/sales/
+```
+
+**Query Parameters:**
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+- `group_by` - Group by (service, staff, client, day)
+- `format` - Output format (json, csv, pdf)
+
+### Client Analytics
+```http
+GET /api/v1/beauty/reports/clients/
+```
+
+**Query Parameters:**
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+- `group_by` - Group by (membership_level, frequency, demographics)
+- `format` - Output format (json, csv, pdf)
+
+### Staff Performance
+```http
+GET /api/v1/beauty/reports/staff-performance/
+```
+
+**Query Parameters:**
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+- `staff_id` - Filter by staff
+- `format` - Output format (json, csv, pdf)
+
+### Inventory Report
+```http
+GET /api/v1/beauty/reports/inventory/
+```
+
+**Query Parameters:**
+- `category` - Filter by category
+- `low_stock` - Show low stock items
+- `format` - Output format (json, csv, pdf)
+
+## Malaysian Beauty Industry Features
+
+### KKM Compliance
+Full integration with Malaysian Ministry of Health (KKM) requirements:
+```json
+{
+  "kkm_compliance": {
+    "premise_license": "KKM-PREMISE-12345",
+    "notification_number": "NOT202400123456",
+    "last_inspection_date": "2024-01-01",
+    "next_inspection_date": "2025-01-01",
+    "inspection_result": "passed",
+    "certificates": ["beauty_therapy", "massage_therapy"]
+  }
+}
+```
+
+### Halal Certification
+Support for JAKIM halal certification:
+```json
+{
+  "halal_certification": {
+    "certified": true,
+    "certificate_number": "JAKIM-1234-5678",
+    "issue_date": "2024-01-01",
+    "expiry_date": "2025-01-01",
+    "certifying_body": "JAKIM",
+    "products_covered": ["skincare", "haircare", "cosmetics"]
+  }
+}
+```
+
+### Malaysian Cultural Preferences
+Support for Malaysian cultural and religious preferences:
+```json
+{
+  "cultural_considerations": {
+    "gender_specific_services": true,
+    "female_therapists_for_female_clients": true,
+    "prayer_room_access": true,
+    "halal_products_only": true,
+    "modest_attire_policy": true
+  }
+}
+```
+
+### Malaysian Beauty Standards
+Alignment with Malaysian beauty preferences:
+```json
+{
+  "malaysian_beauty_preferences": {
+    "popular_services": ["facial", "hair_treatment", "manicure", "pedicure"],
+    "preferred_products": ["halal_certified", "suitable_for_tropical_climate"],
+    "peak_hours": ["evening", "weekends"],
+    "seasonal_promotions": ["hari_raya", "chinese_new_year", "deepavali"]
+  }
+}
+```
+
+### Malaysian Time and Holidays
+Respect for Malaysian time and holidays:
+```json
+{
+  "operating_considerations": {
+    "timezone": "Asia/Kuala_Lumpur",
+    "prayer_times": true,
+    "public_holidays": ["hari_raya", "chinese_new_year", "deepavali"],
+    "ramadan_hours": true,
+    "friday_prayer_break": true
+  }
+}
+```
+
+### Malaysian Language Support
+Multi-language support for Malaysian clients:
+```json
+{
+  "language_support": {
+    "primary_languages": ["malay", "english", "mandarin"],
+    "staff_languages": ["malay", "english", "mandarin", "tamil"],
+    "marketing_materials": ["malay", "english", "mandarin"]
+  }
+}
+```
+
+### Malaysian Payment Methods
+Support for Malaysian payment preferences:
+```json
+{
+  "payment_methods": {
+    "cash": true,
+    "credit_card": true,
+    "debit_card": true,
+    "ewallet": ["touch_n_go", "grabpay", "boost"],
+    "online_banking": ["maybank2u", "cimb_clicks", "rhbb"]
+  }
+}
+```
+
+### Malaysian Staff Requirements
+Compliance with Malaysian beauty industry staff requirements:
+```json
+{
+  "staff_requirements": {
+    "minimum_certification": "KKM_Beauty_Therapy_Certificate",
+    "foreign_worker_permits": true,
+    "epf_contribution": true,
+    "socso_coverage": true,
+    "medical_checkup_required": true
+  }
+}
+```
+
+### Malaysian Marketing Compliance
+Compliance with Malaysian advertising regulations:
+```json
+{
+  "marketing_compliance": {
+    "kkm_advertising_guidelines": true,
+    "no_false_claims": true,
+    "halal_certification_display": true,
+    "price_transparency": true,
+    "pdpa_compliance": true
+  }
+}
+```

docs/api/core/README.md

@@ -0,0 +1,463 @@
+# Core API Documentation
+
+## Overview
+
+The Core API provides fundamental functionality for multi-tenant management, authentication, and platform administration.
+
+## Authentication
+
+### Login
+```http
+POST /api/v1/auth/login/
+```
+
+**Request Body:**
+```json
+{
+  "username": "your_username",
+  "password": "your_password",
+  "tenant_id": "your_tenant_id"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
+    "user": {
+      "id": 1,
+      "username": "your_username",
+      "email": "user@example.com",
+      "role": "admin",
+      "tenant_id": "your_tenant_id"
+    }
+  }
+}
+```
+
+### Register
+```http
+POST /api/v1/auth/register/
+```
+
+**Request Body:**
+```json
+{
+  "username": "newuser",
+  "email": "user@example.com",
+  "password": "SecurePass123!",
+  "first_name": "John",
+  "last_name": "Doe",
+  "phone_number": "+60123456789",
+  "ic_number": "900101-01-1234"
+}
+```
+
+### Refresh Token
+```http
+POST /api/v1/auth/refresh/
+```
+
+**Request Body:**
+```json
+{
+  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
+}
+```
+
+### Logout
+```http
+POST /api/v1/auth/logout/
+```
+
+**Headers:**
+```
+Authorization: Bearer <access-token>
+```
+
+## Tenants
+
+### Create Tenant
+```http
+POST /api/v1/tenants/
+```
+
+**Request Body:**
+```json
+{
+  "name": "My Business Sdn Bhd",
+  "schema_name": "my_business",
+  "domain": "mybusiness.com",
+  "business_type": "retail",
+  "registration_number": "202401000123",
+  "business_address": {
+    "street": "123 Business Street",
+    "city": "Kuala Lumpur",
+    "state": "Wilayah Persekutuan",
+    "postal_code": "50050",
+    "country": "Malaysia"
+  },
+  "contact_email": "contact@mybusiness.com",
+  "contact_phone": "+60312345678"
+}
+```
+
+### Get Tenant
+```http
+GET /api/v1/tenants/{tenant_id}/
+```
+
+### Update Tenant
+```http
+PUT /api/v1/tenants/{tenant_id}/
+```
+
+### List Tenants
+```http
+GET /api/v1/tenants/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `business_type` - Filter by business type (retail, healthcare, education, logistics, beauty)
+- `is_active` - Filter by active status
+
+### Delete Tenant
+```http
+DELETE /api/v1/tenants/{tenant_id}/
+```
+
+## Users
+
+### Create User
+```http
+POST /api/v1/users/
+```
+
+**Request Body:**
+```json
+{
+  "username": "newuser",
+  "email": "user@example.com",
+  "password": "SecurePass123!",
+  "first_name": "John",
+  "last_name": "Doe",
+  "phone_number": "+60123456789",
+  "ic_number": "900101-01-1234",
+  "role": "staff",
+  "permissions": ["view_products", "manage_sales"]
+}
+```
+
+### Get User
+```http
+GET /api/v1/users/{user_id}/
+```
+
+### Update User
+```http
+PUT /api/v1/users/{user_id}/
+```
+
+### List Users
+```http
+GET /api/v1/users/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `role` - Filter by role (admin, manager, staff, user)
+- `is_active` - Filter by active status
+
+### Delete User
+```http
+DELETE /api/v1/users/{user_id}/
+```
+
+### Change Password
+```http
+POST /api/v1/users/{user_id}/change-password/
+```
+
+**Request Body:**
+```json
+{
+  "current_password": "old_password",
+  "new_password": "NewSecurePass123!"
+}
+```
+
+## Subscriptions
+
+### Create Subscription
+```http
+POST /api/v1/subscriptions/
+```
+
+**Request Body:**
+```json
+{
+  "tenant_id": "tenant_id",
+  "plan_id": "plan_id",
+  "modules": ["retail", "inventory"],
+  "billing_cycle": "monthly",
+  "payment_method_id": "payment_method_id"
+}
+```
+
+### Get Subscription
+```http
+GET /api/v1/subscriptions/{subscription_id}/
+```
+
+### Update Subscription
+```http
+PUT /api/v1/subscriptions/{subscription_id}/
+```
+
+### List Subscriptions
+```http
+GET /api/v1/subscriptions/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `tenant_id` - Filter by tenant
+- `status` - Filter by status (active, cancelled, expired)
+
+### Cancel Subscription
+```http
+POST /api/v1/subscriptions/{subscription_id}/cancel/
+```
+
+## Modules
+
+### List Available Modules
+```http
+GET /api/v1/modules/
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "retail",
+      "name": "Retail Management",
+      "description": "Complete retail and inventory management solution",
+      "features": [
+        "Product catalog management",
+        "Sales order processing",
+        "Inventory tracking",
+        "Customer management",
+        "Loyalty programs"
+      ],
+      "pricing": {
+        "monthly": 299.00,
+        "yearly": 2990.00
+      }
+    }
+  ]
+}
+```
+
+### Enable Module
+```http
+POST /api/v1/modules/{module_id}/enable/
+```
+
+**Request Body:**
+```json
+{
+  "tenant_id": "tenant_id",
+  "configuration": {
+    "retail": {
+      "enable_loyalty_program": true,
+      "enable_inventory_alerts": true
+    }
+  }
+}
+```
+
+### Disable Module
+```http
+POST /api/v1/modules/{module_id}/disable/
+```
+
+### Get Module Configuration
+```http
+GET /api/v1/modules/{module_id}/configuration/
+```
+
+## Payment Methods
+
+### Add Payment Method
+```http
+POST /api/v1/payment-methods/
+```
+
+**Request Body:**
+```json
+{
+  "type": "credit_card",
+  "card_number": "4111111111111111",
+  "expiry_month": 12,
+  "expiry_year": 2025,
+  "cvv": "123",
+  "cardholder_name": "John Doe",
+  "billing_address": {
+    "street": "123 Billing Street",
+    "city": "Kuala Lumpur",
+    "state": "Wilayah Persekutuan",
+    "postal_code": "50050",
+    "country": "Malaysia"
+  }
+}
+```
+
+### List Payment Methods
+```http
+GET /api/v1/payment-methods/
+```
+
+### Delete Payment Method
+```http
+DELETE /api/v1/payment-methods/{payment_method_id}/
+```
+
+## Payment Transactions
+
+### Create Payment
+```http
+POST /api/v1/payments/
+```
+
+**Request Body:**
+```json
+{
+  "amount": 299.00,
+  "currency": "MYR",
+  "payment_method_id": "payment_method_id",
+  "description": "Monthly subscription",
+  "metadata": {
+    "subscription_id": "sub_123456",
+    "tenant_id": "tenant_123456"
+  }
+}
+```
+
+### Get Payment
+```http
+GET /api/v1/payments/{payment_id}/
+```
+
+### List Payments
+```http
+GET /api/v1/payments/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `tenant_id` - Filter by tenant
+- `status` - Filter by status (pending, completed, failed, refunded)
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+
+### Refund Payment
+```http
+POST /api/v1/payments/{payment_id}/refund/
+```
+
+**Request Body:**
+```json
+{
+  "amount": 100.00,
+  "reason": "Customer request"
+}
+```
+
+## Malaysian Features
+
+### Validate Malaysian Phone Number
+```http
+POST /api/v1/utils/validate-phone/
+```
+
+**Request Body:**
+```json
+{
+  "phone_number": "+60123456789"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "is_valid": true,
+    "normalized_format": "+60123456789",
+    "type": "mobile",
+    "carrier": "Maxis"
+  }
+}
+```
+
+### Calculate SST
+```http
+POST /api/v1/utils/calculate-sst/
+```
+
+**Request Body:**
+```json
+{
+  "amount": 100.00,
+  "service_type": "retail"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "subtotal": 100.00,
+    "sst_rate": 0.06,
+    "sst_amount": 6.00,
+    "total": 106.00
+  }
+}
+```
+
+### Validate Business Registration
+```http
+POST /api/v1/utils/validate-registration/
+```
+
+**Request Body:**
+```json
+{
+  "registration_number": "202401000123"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "is_valid": true,
+    "company_name": "My Business Sdn Bhd",
+    "registration_date": "2024-01-01",
+    "status": "active"
+  }
+}
+```

docs/api/education/README.md

@@ -0,0 +1,642 @@
+# Education Module API Documentation
+
+## Overview
+
+The Education Module API provides comprehensive functionality for educational institutions including student management, class scheduling, enrollment, and Malaysian education system compliance.
+
+## Students
+
+### Create Student
+```http
+POST /api/v1/education/students/
+```
+
+**Request Body:**
+```json
+{
+  "first_name": "Ahmad",
+  "last_name": "Bin Hassan",
+  "ic_number": "080101-01-1234",
+  "date_of_birth": "2008-01-01",
+  "gender": "male",
+  "email": "ahmad.hassan@student.edu.my",
+  "phone_number": "+60123456789",
+  "address": {
+    "street": "123 Student Street",
+    "city": "Kuala Lumpur",
+    "state": "Wilayah Persekutuan",
+    "postal_code": "50050",
+    "country": "Malaysia"
+  },
+  "parent_guardian": {
+    "name": "Hassan Bin Ibrahim",
+    "relationship": "father",
+    "phone_number": "+60123456788",
+    "email": "hassan.ibrahim@example.com",
+    "occupation": "Engineer"
+  },
+  "emergency_contact": {
+    "name": "Siti Aminah",
+    "relationship": "mother",
+    "phone_number": "+60123456787"
+  },
+  "previous_school": "SK Taman Desa",
+  "previous_grade": "Standard 5",
+  "admission_date": "2024-01-01",
+  "current_grade": "Standard 6",
+  "stream": "academic",
+  "subjects": ["mathematics", "science", "english", "bahasa_malaysia"],
+  "special_needs": [],
+  "medical_conditions": ["asthma"],
+  "allergies": ["peanuts"],
+  "blood_type": "O+",
+  "religion": "islam",
+  "nationality": "malaysian",
+  "scholarship_info": {
+    "has_scholarship": false,
+    "scholarship_name": null,
+    "scholarship_percentage": 0
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "stu_123456",
+    "first_name": "Ahmad",
+    "last_name": "Bin Hassan",
+    "ic_number": "080101-01-1234",
+    "date_of_birth": "2008-01-01",
+    "gender": "male",
+    "email": "ahmad.hassan@student.edu.my",
+    "phone_number": "+60123456789",
+    "address": {
+      "street": "123 Student Street",
+      "city": "Kuala Lumpur",
+      "state": "Wilayah Persekutuan",
+      "postal_code": "50050",
+      "country": "Malaysia"
+    },
+    "parent_guardian": {
+      "name": "Hassan Bin Ibrahim",
+      "relationship": "father",
+      "phone_number": "+60123456788",
+      "email": "hassan.ibrahim@example.com",
+      "occupation": "Engineer"
+    },
+    "emergency_contact": {
+      "name": "Siti Aminah",
+      "relationship": "mother",
+      "phone_number": "+60123456787"
+    },
+    "previous_school": "SK Taman Desa",
+    "previous_grade": "Standard 5",
+    "admission_date": "2024-01-01",
+    "current_grade": "Standard 6",
+    "stream": "academic",
+    "subjects": ["mathematics", "science", "english", "bahasa_malaysia"],
+    "special_needs": [],
+    "medical_conditions": ["asthma"],
+    "allergies": ["peanuts"],
+    "blood_type": "O+",
+    "religion": "islam",
+    "nationality": "malaysian",
+    "scholarship_info": {
+      "has_scholarship": false,
+      "scholarship_name": null,
+      "scholarship_percentage": 0
+    },
+    "pdpa_consent": true,
+    "pdpa_consent_date": "2024-01-01T00:00:00Z",
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### Get Student
+```http
+GET /api/v1/education/students/{student_id}/
+```
+
+### Update Student
+```http
+PUT /api/v1/education/students/{student_id}/
+```
+
+### List Students
+```http
+GET /api/v1/education/students/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `current_grade` - Filter by current grade
+- `stream` - Filter by stream (academic, vocational, technical)
+- `search` - Search in name, IC number, email
+- `gender` - Filter by gender
+- `religion` - Filter by religion
+- `nationality` - Filter by nationality
+- `has_scholarship` - Filter by scholarship status
+
+### Delete Student
+```http
+DELETE /api/v1/education/students/{student_id}/
+```
+
+### Get Student Academic Record
+```http
+GET /api/v1/education/students/{student_id}/academic-record/
+```
+
+## Classes
+
+### Create Class
+```http
+POST /api/v1/education/classes/
+```
+
+**Request Body:**
+```json
+{
+  "name": "6 Bestari",
+  "grade_level": "Standard 6",
+  "stream": "academic",
+  "academic_year": "2024",
+  "room_number": "A-101",
+  "capacity": 30,
+  "current_enrollment": 28,
+  "teacher_id": "tch_123456",
+  "assistant_teacher_id": "tch_789012",
+  "schedule": {
+    "monday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
+    "tuesday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
+    "wednesday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
+    "thursday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
+    "friday": ["08:00-09:30", "10:00-11:30", "12:30-13:30"]
+  },
+  "subjects": [
+    {
+      "name": "Mathematics",
+      "teacher_id": "tch_123456",
+      "hours_per_week": 5
+    },
+    {
+      "name": "Science",
+      "teacher_id": "tch_345678",
+      "hours_per_week": 3
+    }
+  ],
+  "special_requirements": ["air_conditioned", "projector"],
+  "notes": "Advanced mathematics class"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "cls_123456",
+    "name": "6 Bestari",
+    "grade_level": "Standard 6",
+    "stream": "academic",
+    "academic_year": "2024",
+    "room_number": "A-101",
+    "capacity": 30,
+    "current_enrollment": 28,
+    "teacher_id": "tch_123456",
+    "assistant_teacher_id": "tch_789012",
+    "schedule": {
+      "monday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
+      "tuesday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
+      "wednesday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
+      "thursday": ["08:00-09:30", "10:00-11:30", "12:30-14:00"],
+      "friday": ["08:00-09:30", "10:00-11:30", "12:30-13:30"]
+    },
+    "subjects": [
+      {
+        "name": "Mathematics",
+        "teacher_id": "tch_123456",
+        "hours_per_week": 5
+      },
+      {
+        "name": "Science",
+        "teacher_id": "tch_345678",
+        "hours_per_week": 3
+      }
+    ],
+    "special_requirements": ["air_conditioned", "projector"],
+    "notes": "Advanced mathematics class",
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### Get Class
+```http
+GET /api/v1/education/classes/{class_id}/
+```
+
+### Update Class
+```http
+PUT /api/v1/education/classes/{class_id}/
+```
+
+### List Classes
+```http
+GET /api/v1/education/classes/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `grade_level` - Filter by grade level
+- `stream` - Filter by stream
+- `academic_year` - Filter by academic year
+- `teacher_id` - Filter by teacher
+- `has_space` - Filter by available space (true/false)
+
+### Delete Class
+```http
+DELETE /api/v1/education/classes/{class_id}/
+```
+
+### Get Class Students
+```http
+GET /api/v1/education/classes/{class_id}/students/
+```
+
+### Get Class Schedule
+```http
+GET /api/v1/education/classes/{class_id}/schedule/
+```
+
+## Enrollment
+
+### Enroll Student
+```http
+POST /api/v1/education/enrollment/
+```
+
+**Request Body:**
+```json
+{
+  "student_id": "stu_123456",
+  "class_id": "cls_123456",
+  "enrollment_date": "2024-01-01",
+  "enrollment_type": "new",
+  "fees": {
+    "tuition_fee": 1200.00,
+    "registration_fee": 100.00,
+    "material_fee": 200.00,
+    "total_fee": 1500.00,
+    "payment_plan": "full_payment"
+  },
+  "scholarship_info": {
+    "has_scholarship": false,
+    "scholarship_amount": 0.00
+  },
+  "previous_results": {
+    "upsr_result": "5A",
+    "previous_school": "SK Taman Desa"
+  },
+  "documents": [
+    {
+      "type": "birth_certificate",
+      "file_id": "doc_123456"
+    },
+    {
+      "type": "ic_copy",
+      "file_id": "doc_789012"
+    }
+  ],
+  "notes": "Excellent mathematics student"
+}
+```
+
+### Get Enrollment
+```http
+GET /api/v1/education/enrollment/{enrollment_id}/
+```
+
+### Update Enrollment
+```http
+PUT /api/v1/education/enrollment/{enrollment_id}/
+```
+
+### List Enrollments
+```http
+GET /api/v1/education/enrollment/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `student_id` - Filter by student
+- `class_id` - Filter by class
+- `enrollment_type` - Filter by enrollment type (new, transfer, returning)
+- `status` - Filter by status (active, inactive, graduated)
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+
+### Withdraw Student
+```http
+POST /api/v1/education/enrollment/{enrollment_id}/withdraw/
+```
+
+**Request Body:**
+```json
+{
+  "withdrawal_date": "2024-06-01",
+  "reason": "Family relocation",
+  "destination_school": "SK Putrajaya",
+  "refund_amount": 750.00,
+  "notes": "Student family moving to Putrajaya"
+}
+```
+
+## Attendance
+
+### Record Attendance
+```http
+POST /api/v1/education/attendance/
+```
+
+**Request Body:**
+```json
+{
+  "student_id": "stu_123456",
+  "class_id": "cls_123456",
+  "date": "2024-01-15",
+  "status": "present",
+  "time_in": "08:00:00",
+  "time_out": "14:00:00",
+  "remarks": "Student present and on time",
+  "recorded_by": "tch_123456"
+}
+```
+
+### Get Attendance Record
+```http
+GET /api/v1/education/attendance/{attendance_id}/
+```
+
+### Update Attendance
+```http
+PUT /api/v1/education/attendance/{attendance_id}/
+```
+
+### List Attendance
+```http
+GET /api/v1/education/attendance/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `student_id` - Filter by student
+- `class_id` - Filter by class
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+- `status` - Filter by status (present, absent, late, excused)
+
+### Get Student Attendance Summary
+```http
+GET /api/v1/education/students/{student_id}/attendance-summary/
+```
+
+**Query Parameters:**
+- `start_date` - Start date (YYYY-MM-DD)
+- `end_date` - End date (YYYY-MM-DD)
+
+## Grades and Assessments
+
+### Record Grade
+```http
+POST /api/v1/education/grades/
+```
+
+**Request Body:**
+```json
+{
+  "student_id": "stu_123456",
+  "subject_id": "sub_123456",
+  "assessment_type": "midterm",
+  "assessment_name": "Mathematics Midterm Exam",
+  "score": 85.5,
+  "max_score": 100.0,
+  "grade": "A",
+  "remarks": "Excellent performance",
+  "teacher_id": "tch_123456",
+  "assessment_date": "2024-03-15"
+}
+```
+
+### Get Grade
+```http
+GET /api/v1/education/grades/{grade_id}/
+```
+
+### Update Grade
+```http
+PUT /api/v1/education/grades/{grade_id}/
+```
+
+### List Grades
+```http
+GET /api/v1/education/grades/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `student_id` - Filter by student
+- `subject_id` - Filter by subject
+- `assessment_type` - Filter by assessment type
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+
+### Get Student Report Card
+```http
+GET /api/v1/education/students/{student_id}/report-card/
+```
+
+**Query Parameters:**
+- `term` - Academic term
+- `year` - Academic year
+
+## Fees and Payments
+
+### Create Fee Structure
+```http
+POST /api/v1/education/fees/
+```
+
+**Request Body:**
+```json
+{
+  "grade_level": "Standard 6",
+  "fee_type": "tuition",
+  "amount": 1200.00,
+  "currency": "MYR",
+  "payment_frequency": "annually",
+  "academic_year": "2024",
+  "description": "Annual tuition fee for Standard 6",
+  "is_mandatory": true,
+  "scholarship_applicable": true
+}
+```
+
+### Record Payment
+```http
+POST /api/v1/education/payments/
+```
+
+**Request Body:**
+```json
+{
+  "student_id": "stu_123456",
+  "fee_id": "fee_123456",
+  "amount": 1200.00,
+  "payment_method": "bank_transfer",
+  "payment_date": "2024-01-15",
+  "transaction_id": "TXN123456789",
+  "receipt_number": "REC20240001",
+  "notes": "Full payment for annual tuition"
+}
+```
+
+### Get Payment
+```http
+GET /api/v1/education/payments/{payment_id}/
+```
+
+### List Payments
+```http
+GET /api/v1/education/payments/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `student_id` - Filter by student
+- `fee_id` - Filter by fee
+- `payment_method` - Filter by payment method
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+
+## Reports and Analytics
+
+### Student Performance Report
+```http
+GET /api/v1/education/reports/student-performance/
+```
+
+**Query Parameters:**
+- `class_id` - Filter by class
+- `subject_id` - Filter by subject
+- `assessment_type` - Filter by assessment type
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+- `format` - Output format (json, csv, pdf)
+
+### Attendance Report
+```http
+GET /api/v1/education/reports/attendance/
+```
+
+**Query Parameters:**
+- `class_id` - Filter by class
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+- `group_by` - Group by (student, class, grade)
+- `format` - Output format (json, csv, pdf)
+
+### Financial Report
+```http
+GET /api/v1/education/reports/financial/
+```
+
+**Query Parameters:**
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+- "report_type" - Report type (revenue, expenses, profit_loss)
+- `format` - Output format (json, csv, pdf)
+
+## Malaysian Education Features
+
+### Malaysian Grade System
+Support for Malaysian education grade levels:
+- Primary: Standard 1-6
+- Lower Secondary: Form 1-3
+- Upper Secondary: Form 4-5
+- Pre-University: Form 6 / Matriculation
+
+### Malaysian Curriculum
+Alignment with Malaysian National Curriculum (KSSR/KSSM):
+```json
+{
+  "malaysian_curriculum": {
+    "kssr_level": "standard_6",
+    "core_subjects": ["bahasa_malaysia", "english", "mathematics", "science"],
+    "elective_subjects": ["arabic", "chinese", "tamil"],
+    "moral_education": "islamic_education",
+    "physical_education": true,
+    "arts_education": true
+  }
+}
+```
+
+### Malaysian Assessment System
+Support for Malaysian assessment methods:
+- UPSR (Primary School Assessment)
+- PT3 (Lower Secondary Assessment)
+- SPM (Malaysian Certificate of Education)
+- STPM (Malaysian Higher School Certificate)
+
+### Malaysian IC Validation
+All student IC numbers are validated according to Malaysian format with age verification.
+
+### PDPA Compliance
+All student data handling follows Malaysian Personal Data Protection Act 2010.
+
+### Malaysian Education Ministry Integration
+Integration with Malaysian Ministry of Education requirements:
+- Student registration
+- Teacher qualifications
+- School accreditation
+- Annual reporting
+
+### Malaysian School Calendar
+Support for Malaysian school calendar:
+- Academic year structure
+- School holidays
+- Public holidays
+- Examination periods
+
+### Malaysian Languages Support
+Multi-language support for Malaysian education:
+- Bahasa Malaysia
+- English
+- Chinese (Mandarin)
+- Tamil
+- Arabic
+
+### Religious Education
+Support for religious education requirements:
+- Islamic Education for Muslim students
+- Moral Education for non-Muslim students
+- Religious holiday considerations
+
+### Special Needs Education
+Support for Malaysian special education requirements:
+- Inclusive education programs
+- Special education schools
+- Learning disabilities support
+- Individualized Education Plans (IEP)

docs/api/healthcare/README.md

@@ -0,0 +1,551 @@
+# Healthcare Module API Documentation
+
+## Overview
+
+The Healthcare Module API provides comprehensive functionality for healthcare providers including patient management, appointment scheduling, medical records, and Malaysian healthcare compliance.
+
+## Patients
+
+### Create Patient
+```http
+POST /api/v1/healthcare/patients/
+```
+
+**Request Body:**
+```json
+{
+  "first_name": "Muhammad",
+  "last_name": "Abdullah",
+  "ic_number": "900101-01-1234",
+  "date_of_birth": "1990-01-01",
+  "gender": "male",
+  "email": "muhammad.abdullah@example.com",
+  "phone_number": "+60123456789",
+  "emergency_contact": {
+    "name": "Aminah Abdullah",
+    "relationship": "spouse",
+    "phone_number": "+60123456788"
+  },
+  "address": {
+    "street": "123 Patient Street",
+    "city": "Kuala Lumpur",
+    "state": "Wilayah Persekutuan",
+    "postal_code": "50050",
+    "country": "Malaysia"
+  },
+  "blood_type": "O+",
+  "allergies": ["penicillin", "peanuts"],
+  "chronic_conditions": ["hypertension", "diabetes"],
+  "medications": ["metformin 500mg", "lisinopril 10mg"],
+  "insurance_info": {
+    "provider": "Great Eastern",
+    "policy_number": "GE-123456789",
+    "expiry_date": "2024-12-31"
+  },
+  "notes": "Prefers morning appointments"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "pat_123456",
+    "first_name": "Muhammad",
+    "last_name": "Abdullah",
+    "ic_number": "900101-01-1234",
+    "date_of_birth": "1990-01-01",
+    "gender": "male",
+    "email": "muhammad.abdullah@example.com",
+    "phone_number": "+60123456789",
+    "emergency_contact": {
+      "name": "Aminah Abdullah",
+      "relationship": "spouse",
+      "phone_number": "+60123456788"
+    },
+    "address": {
+      "street": "123 Patient Street",
+      "city": "Kuala Lumpur",
+      "state": "Wilayah Persekutuan",
+      "postal_code": "50050",
+      "country": "Malaysia"
+    },
+    "blood_type": "O+",
+    "allergies": ["penicillin", "peanuts"],
+    "chronic_conditions": ["hypertension", "diabetes"],
+    "medications": ["metformin 500mg", "lisinopril 10mg"],
+    "insurance_info": {
+      "provider": "Great Eastern",
+      "policy_number": "GE-123456789",
+      "expiry_date": "2024-12-31"
+    },
+    "pdpa_consent": true,
+    "pdpa_consent_date": "2024-01-01T00:00:00Z",
+    "notes": "Prefers morning appointments",
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### Get Patient
+```http
+GET /api/v1/healthcare/patients/{patient_id}/
+```
+
+### Update Patient
+```http
+PUT /api/v1/healthcare/patients/{patient_id}/
+```
+
+### List Patients
+```http
+GET /api/v1/healthcare/patients/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `search` - Search in name, IC number, email
+- `date_of_birth` - Filter by date of birth
+- `gender` - Filter by gender
+- `blood_type` - Filter by blood type
+- `has_insurance` - Filter by insurance status
+
+### Delete Patient
+```http
+DELETE /api/v1/healthcare/patients/{patient_id}/
+```
+
+### Get Patient Medical History
+```http
+GET /api/v1/healthcare/patients/{patient_id}/medical-history/
+```
+
+## Appointments
+
+### Create Appointment
+```http
+POST /api/v1/healthcare/appointments/
+```
+
+**Request Body:**
+```json
+{
+  "patient_id": "pat_123456",
+  "doctor_id": "doc_789012",
+  "appointment_type": "consultation",
+  "scheduled_date": "2024-01-15",
+  "scheduled_time": "09:00:00",
+  "duration_minutes": 30,
+  "reason": "Routine check-up",
+  "symptoms": ["headache", "fatigue"],
+  "priority": "normal",
+  "status": "scheduled",
+  "notes": "Patient prefers morning appointments"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "apt_123456",
+    "patient_id": "pat_123456",
+    "doctor_id": "doc_789012",
+    "appointment_type": "consultation",
+    "scheduled_date": "2024-01-15",
+    "scheduled_time": "09:00:00",
+    "duration_minutes": 30,
+    "reason": "Routine check-up",
+    "symptoms": ["headache", "fatigue"],
+    "priority": "normal",
+    "status": "scheduled",
+    "check_in_time": null,
+    "start_time": null,
+    "end_time": null,
+    "doctor_notes": null,
+    "prescriptions": [],
+    "follow_up_required": false,
+    "follow_up_date": null,
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### Get Appointment
+```http
+GET /api/v1/healthcare/appointments/{appointment_id}/
+```
+
+### Update Appointment
+```http
+PUT /api/v1/healthcare/appointments/{appointment_id}/
+```
+
+### List Appointments
+```http
+GET /api/v1/healthcare/appointments/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `patient_id` - Filter by patient
+- `doctor_id` - Filter by doctor
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+- `status` - Filter by status (scheduled, confirmed, in_progress, completed, cancelled, no_show)
+- `appointment_type` - Filter by appointment type
+
+### Cancel Appointment
+```http
+POST /api/v1/healthcare/appointments/{appointment_id}/cancel/
+```
+
+**Request Body:**
+```json
+{
+  "reason": "Patient unable to attend",
+  "cancelled_by": "patient"
+}
+```
+
+### Check-in Patient
+```http
+POST /api/v1/healthcare/appointments/{appointment_id}/check-in/
+```
+
+### Start Appointment
+```http
+POST /api/v1/healthcare/appointments/{appointment_id}/start/
+```
+
+### Complete Appointment
+```http
+POST /api/v1/healthcare/appointments/{appointment_id}/complete/
+```
+
+**Request Body:**
+```json
+{
+  "doctor_notes": "Patient shows improvement. Continue current medication.",
+  "diagnosis": "Essential hypertension",
+  "treatment_plan": "Continue current medication, lifestyle modifications",
+  "follow_up_required": true,
+  "follow_up_date": "2024-02-15",
+  "prescriptions": [
+    {
+      "medication": "Metformin 500mg",
+      "dosage": "1 tablet twice daily",
+      "duration": "30 days",
+      "instructions": "Take with meals"
+    }
+  ]
+}
+```
+
+### Get Doctor Schedule
+```http
+GET /api/v1/healthcare/doctors/{doctor_id}/schedule/
+```
+
+**Query Parameters:**
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+
+## Medical Records
+
+### Create Medical Record
+```http
+POST /api/v1/healthcare/medical-records/
+```
+
+**Request Body:**
+```json
+{
+  "patient_id": "pat_123456",
+  "doctor_id": "doc_789012",
+  "appointment_id": "apt_123456",
+  "record_type": "consultation",
+  "diagnosis": "Essential hypertension",
+  "symptoms": ["headache", "dizziness", "fatigue"],
+  "vitals": {
+    "blood_pressure": "140/90",
+    "heart_rate": 72,
+    "temperature": 36.8,
+    "weight": 75.5,
+    "height": 175
+  },
+  "notes": "Patient reports occasional headaches. BP elevated.",
+  "treatment_plan": "Lifestyle modifications, monitor BP",
+  "follow_up_instructions": "Return in 2 weeks for BP check",
+  "attachments": ["file_123456"]
+}
+```
+
+### Get Medical Record
+```http
+GET /api/v1/healthcare/medical-records/{record_id}/
+```
+
+### Update Medical Record
+```http
+PUT /api/v1/healthcare/medical-records/{record_id}/
+```
+
+### List Medical Records
+```http
+GET /api/v1/healthcare/medical-records/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `patient_id` - Filter by patient
+- `doctor_id` - Filter by doctor
+- `record_type` - Filter by record type
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+
+## Prescriptions
+
+### Create Prescription
+```http
+POST /api/v1/healthcare/prescriptions/
+```
+
+**Request Body:**
+```json
+{
+  "patient_id": "pat_123456",
+  "doctor_id": "doc_789012",
+  "appointment_id": "apt_123456",
+  "medication": "Metformin 500mg",
+  "dosage": "1 tablet twice daily",
+  "frequency": "twice daily",
+  "duration": "30 days",
+  "quantity": 60,
+  "instructions": "Take with meals",
+  "refills_allowed": 3,
+  "refills_used": 0,
+  "notes": "Monitor for side effects"
+}
+```
+
+### Get Prescription
+```http
+GET /api/v1/healthcare/prescriptions/{prescription_id}/
+```
+
+### Update Prescription
+```http
+PUT /api/v1/healthcare/prescriptions/{prescription_id}/
+```
+
+### List Prescriptions
+```http
+GET /api/v1/healthcare/prescriptions/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `patient_id` - Filter by patient
+- `doctor_id` - Filter by doctor
+- `status` - Filter by status (active, completed, expired)
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+
+### Refill Prescription
+```http
+POST /api/v1/healthcare/prescriptions/{prescription_id}/refill/
+```
+
+## Vaccinations
+
+### Record Vaccination
+```http
+POST /api/v1/healthcare/vaccinations/
+```
+
+**Request Body:**
+```json
+{
+  "patient_id": "pat_123456",
+  "vaccine_type": "influenza",
+  "vaccine_name": "Vaxigrip",
+  "batch_number": "FLU2024-1234",
+  "administration_date": "2024-01-15",
+  "administered_by": "doc_789012",
+  "dose_number": 1,
+  "total_doses": 1,
+  "next_due_date": null,
+  "notes": "Annual flu vaccine"
+}
+```
+
+### Get Vaccination Record
+```http
+GET /api/v1/healthcare/patients/{patient_id}/vaccinations/
+```
+
+### List Vaccinations
+```http
+GET /api/v1/healthcare/vaccinations/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `patient_id` - Filter by patient
+- `vaccine_type` - Filter by vaccine type
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+
+## Billing and Insurance
+
+### Create Bill
+```http
+POST /api/v1/healthcare/billing/
+```
+
+**Request Body:**
+```json
+{
+  "patient_id": "pat_123456",
+  "appointment_id": "apt_123456",
+  "items": [
+    {
+      "description": "Consultation fee",
+      "quantity": 1,
+      "unit_price": 100.00,
+      "tax_rate": 0.0
+    },
+    {
+      "description": "Blood test",
+      "quantity": 1,
+      "unit_price": 50.00,
+      "tax_rate": 0.0
+    }
+  ],
+  "payment_method": "cash",
+  "insurance_claim": true,
+  "insurance_provider": "Great Eastern",
+  "policy_number": "GE-123456789"
+}
+```
+
+### Get Bill
+```http
+GET /api/v1/healthcare/billing/{bill_id}/
+```
+
+### List Bills
+```http
+GET /api/v1/healthcare/billing/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `patient_id` - Filter by patient
+- "status" - Filter by status (pending, paid, partially_paid, overdue)
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+
+## Reports and Analytics
+
+### Patient Demographics Report
+```http
+GET /api/v1/healthcare/reports/patient-demographics/
+```
+
+**Query Parameters:**
+- `group_by` - Group by (age_group, gender, location)
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+- `format` - Output format (json, csv, pdf)
+
+### Appointment Statistics
+```http
+GET /api/v1/healthcare/reports/appointment-stats/
+```
+
+**Query Parameters:**
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+- `group_by` - Group by (doctor, appointment_type, status)
+- `format` - Output format (json, csv, pdf)
+
+### Revenue Report
+```http
+GET /api/v1/healthcare/reports/revenue/
+```
+
+**Query Parameters:**
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+- `group_by` - Group by (service_type, doctor, payment_method)
+- `format` - Output format (json, csv, pdf)
+
+## Malaysian Healthcare Features
+
+### Malaysian IC Validation
+All patient IC numbers are validated according to Malaysian format:
+- `YYMMDD-PB-XXXX` format
+- Age and gender verification
+- Basic checksum validation
+
+### PDPA Compliance
+All patient data handling follows Malaysian Personal Data Protection Act 2010:
+```json
+{
+  "pdpa_consent": true,
+  "pdpa_consent_date": "2024-01-01T00:00:00Z",
+  "data_retention_period": "7_years"
+}
+```
+
+### Malaysian Healthcare Providers
+Integration with Malaysian healthcare systems:
+```json
+{
+  "malaysian_healthcare": {
+    "provider_type": "general_practitioner",
+    "mmc_registration": "MMC-12345",
+    "kkm_license": "KKM-12345",
+    "clinic_registration": "KKM-CLINIC-12345"
+  }
+}
+```
+
+### Malaysian Vaccination Schedule
+Support for Malaysian National Immunisation Program:
+- Childhood vaccinations
+- Adult booster shots
+- Travel vaccinations
+- COVID-19 vaccinations
+
+### Malaysian Insurance Integration
+Support for major Malaysian insurance providers:
+- Great Eastern
+- Prudential
+- AIA
+- Allianz
+- Etiqa
+
+### Malaysian Time and Holidays
+All scheduling respects Malaysian public holidays and business hours:
+- Malaysian timezone (UTC+8)
+- Public holiday awareness
+- Prayer time considerations for Muslim patients
+
+### Emergency Services
+Integration with Malaysian emergency services:
+- Hospital referrals
+- Ambulance services
+- Emergency contact protocols

docs/api/logistics/README.md

@@ -0,0 +1,723 @@
+# Logistics Module API Documentation
+
+## Overview
+
+The Logistics Module API provides comprehensive functionality for logistics management including shipment tracking, vehicle management, delivery scheduling, and Malaysian logistics compliance.
+
+## Shipments
+
+### Create Shipment
+```http
+POST /api/v1/logistics/shipments/
+```
+
+**Request Body:**
+```json
+{
+  "tracking_number": "MYL-2024-001",
+  "origin": {
+    "company_name": "Warehouse A",
+    "address": {
+      "street": "123 Warehouse Street",
+      "city": "Port Klang",
+      "state": "Selangor",
+      "postal_code": "42000",
+      "country": "Malaysia"
+    },
+    "contact_person": "Mr. Lee",
+    "phone_number": "+60312345678"
+  },
+  "destination": {
+    "company_name": "Customer B",
+    "address": {
+      "street": "456 Customer Street",
+      "city": "Johor Bahru",
+      "state": "Johor",
+      "postal_code": "80000",
+      "country": "Malaysia"
+    },
+    "contact_person": "Ms. Aminah",
+    "phone_number": "+60712345678"
+  },
+  "package_details": {
+    "weight_kg": 5.5,
+    "dimensions_cm": {
+      "length": 30,
+      "width": 20,
+      "height": 15
+    },
+    "package_type": "box",
+    "description": "Electronics equipment",
+    "value_myr": 1500.00,
+    "is_fragile": true,
+    "special_instructions": "Handle with care"
+  },
+  "service_type": "express",
+  "delivery_date": "2024-01-15",
+  "delivery_time_window": {
+    "start": "09:00:00",
+    "end": "17:00:00"
+  },
+  "customer_reference": "PO-2024-001",
+  "insurance_required": true,
+  "insurance_amount": 1500.00,
+  "payment_method": "cash_on_delivery",
+  "payment_amount": 1850.00,
+  "notes": "Urgent delivery - customer waiting"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "shp_123456",
+    "tracking_number": "MYL-2024-001",
+    "status": "pending",
+    "origin": {
+      "company_name": "Warehouse A",
+      "address": {
+        "street": "123 Warehouse Street",
+        "city": "Port Klang",
+        "state": "Selangor",
+        "postal_code": "42000",
+        "country": "Malaysia"
+      },
+      "contact_person": "Mr. Lee",
+      "phone_number": "+60312345678"
+    },
+    "destination": {
+      "company_name": "Customer B",
+      "address": {
+        "street": "456 Customer Street",
+        "city": "Johor Bahru",
+        "state": "Johor",
+        "postal_code": "80000",
+        "country": "Malaysia"
+      },
+      "contact_person": "Ms. Aminah",
+      "phone_number": "+60712345678"
+    },
+    "package_details": {
+      "weight_kg": 5.5,
+      "dimensions_cm": {
+        "length": 30,
+        "width": 20,
+        "height": 15
+      },
+      "package_type": "box",
+      "description": "Electronics equipment",
+      "value_myr": 1500.00,
+      "is_fragile": true,
+      "special_instructions": "Handle with care"
+    },
+    "service_type": "express",
+    "delivery_date": "2024-01-15",
+    "delivery_time_window": {
+      "start": "09:00:00",
+      "end": "17:00:00"
+    },
+    "customer_reference": "PO-2024-001",
+    "insurance_required": true,
+    "insurance_amount": 1500.00,
+    "payment_method": "cash_on_delivery",
+    "payment_amount": 1850.00,
+    "total_distance_km": 350.5,
+    "estimated_delivery_time": "4 hours",
+    "actual_delivery_time": null,
+    "driver_id": null,
+    "vehicle_id": null,
+    "notes": "Urgent delivery - customer waiting",
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### Get Shipment
+```http
+GET /api/v1/logistics/shipments/{shipment_id}/
+```
+
+### Update Shipment
+```http
+PUT /api/v1/logistics/shipments/{shipment_id}/
+```
+
+### List Shipments
+```http
+GET /api/v1/logistics/shipments/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `status` - Filter by status (pending, in_transit, delivered, cancelled, returned)
+- `service_type` - Filter by service type (express, standard, economy)
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+- `origin_state` - Filter by origin state
+- `destination_state` - Filter by destination state
+
+### Track Shipment
+```http
+GET /api/v1/logistics/shipments/tracking/{tracking_number}/
+```
+
+### Update Shipment Status
+```http
+POST /api/v1/logistics/shipments/{shipment_id}/update-status/
+```
+
+**Request Body:**
+```json
+{
+  "status": "in_transit",
+  "location": {
+    "latitude": 3.1390,
+    "longitude": 101.6869,
+    "address": "Kuala Lumpur, Malaysia",
+    "timestamp": "2024-01-15T10:00:00Z"
+  },
+  "notes": "Shipment picked up from warehouse",
+  "driver_id": "drv_123456",
+  "vehicle_id": "veh_123456"
+}
+```
+
+## Vehicles
+
+### Create Vehicle
+```http
+POST /api/v1/logistics/vehicles/
+```
+
+**Request Body:**
+```json
+{
+  "registration_number": "WXY 1234",
+  "vehicle_type": "van",
+  "make": "Toyota",
+  "model": "Hiace",
+  "year": 2022,
+  "color": "white",
+  "chassis_number": "MR0HE3CD100123456",
+  "engine_number": "2TR1234567",
+  "capacity_kg": 1000,
+  "dimensions_cm": {
+    "length": 400,
+    "width": 170,
+    "height": 180
+  },
+    "features": ["air_conditioning", "gps_tracking", "refrigeration"],
+  "fuel_type": "diesel",
+  "current_mileage": 45000,
+  "insurance_policy": "Great Eastern Policy #GE-123456",
+  "insurance_expiry": "2024-12-31",
+  "road_tax_expiry": "2024-06-30",
+  "inspection_expiry": "2024-09-30",
+  "puspakom_expiry": "2024-03-31",
+  "status": "active",
+  "assigned_driver_id": "drv_123456",
+  "location": {
+    "latitude": 3.1390,
+    "longitude": 101.6869,
+    "last_updated": "2024-01-15T10:00:00Z"
+  },
+  "maintenance_schedule": {
+    "next_service_date": "2024-02-15",
+    "next_service_mileage": 50000,
+    "service_type": "major"
+  },
+  "notes": "Company van for local deliveries"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "veh_123456",
+    "registration_number": "WXY 1234",
+    "vehicle_type": "van",
+    "make": "Toyota",
+    "model": "Hiace",
+    "year": 2022,
+    "color": "white",
+    "chassis_number": "MR0HE3CD100123456",
+    "engine_number": "2TR1234567",
+    "capacity_kg": 1000,
+    "dimensions_cm": {
+      "length": 400,
+      "width": 170,
+      "height": 180
+    },
+    "features": ["air_conditioning", "gps_tracking", "refrigeration"],
+    "fuel_type": "diesel",
+    "current_mileage": 45000,
+    "insurance_policy": "Great Eastern Policy #GE-123456",
+    "insurance_expiry": "2024-12-31",
+    "road_tax_expiry": "2024-06-30",
+    "inspection_expiry": "2024-09-30",
+    "puspakom_expiry": "2024-03-31",
+    "status": "active",
+    "assigned_driver_id": "drv_123456",
+    "location": {
+      "latitude": 3.1390,
+      "longitude": 101.6869,
+      "last_updated": "2024-01-15T10:00:00Z"
+    },
+    "maintenance_schedule": {
+      "next_service_date": "2024-02-15",
+      "next_service_mileage": 50000,
+      "service_type": "major"
+    },
+    "notes": "Company van for local deliveries",
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### Get Vehicle
+```http
+GET /api/v1/logistics/vehicles/{vehicle_id}/
+```
+
+### Update Vehicle
+```http
+PUT /api/v1/logistics/vehicles/{vehicle_id}/
+```
+
+### List Vehicles
+```http
+GET /api/v1/logistics/vehicles/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `vehicle_type` - Filter by vehicle type
+- `status` - Filter by status (active, maintenance, retired)
+- "make" - Filter by make
+- `model` - Filter by model
+- `assigned_driver_id` - Filter by assigned driver
+
+### Delete Vehicle
+```http
+DELETE /api/v1/logistics/vehicles/{vehicle_id}/
+```
+
+### Update Vehicle Location
+```http
+POST /api/v1/logistics/vehicles/{vehicle_id}/update-location/
+```
+
+**Request Body:**
+```json
+{
+  "latitude": 3.1390,
+  "longitude": 101.6869,
+  "address": "Kuala Lumpur, Malaysia",
+  "timestamp": "2024-01-15T10:00:00Z",
+  "mileage": 45050
+}
+```
+
+### Get Vehicle Maintenance History
+```http
+GET /api/v1/logistics/vehicles/{vehicle_id}/maintenance-history/
+```
+
+## Drivers
+
+### Create Driver
+```http
+POST /api/v1/logistics/drivers/
+```
+
+**Request Body:**
+```json
+{
+  "first_name": "Mohamed",
+  "last_name": "Ibrahim",
+  "ic_number": "850101-01-1234",
+  "date_of_birth": "1985-01-01",
+  "gender": "male",
+  "email": "mohamed.ibrahim@example.com",
+  "phone_number": "+60123456789",
+  "address": {
+    "street": "123 Driver Street",
+    "city": "Shah Alam",
+    "state": "Selangor",
+    "postal_code": "40000",
+    "country": "Malaysia"
+  },
+  "license_number": "123456789012",
+  "license_class": "GDL",
+  "license_expiry": "2025-12-31",
+  "license_type": "professional",
+  "psv_license": "PSV123456",
+  "psv_expiry": "2025-06-30",
+  "experience_years": 8,
+  "employment_status": "full_time",
+  "hourly_rate": 25.00,
+  "monthly_salary": 3500.00,
+  "emergency_contact": {
+    "name": "Fatimah Ibrahim",
+    "relationship": "spouse",
+    "phone_number": "+60123456788"
+  },
+  "medical_checkup_date": "2024-01-01",
+  "medical_checkup_expiry": "2025-01-01",
+  "status": "active",
+  "notes": "Experienced driver with good safety record"
+}
+```
+
+### Get Driver
+```http
+GET /api/v1/logistics/drivers/{driver_id}/
+```
+
+### Update Driver
+```http
+PUT /api/v1/logistics/drivers/{driver_id}/
+```
+
+### List Drivers
+```http
+GET /api/v1/logistics/drivers/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `status` - Filter by status (active, inactive, suspended)
+- `license_class` - Filter by license class
+- `employment_status` - Filter by employment status
+- `search` - Search in name, IC number, email
+
+### Delete Driver
+```http
+DELETE /api/v1/logistics/drivers/{driver_id}/
+```
+
+### Assign Vehicle to Driver
+```http
+POST /api/v1/logistics/drivers/{driver_id}/assign-vehicle/
+```
+
+**Request Body:**
+```json
+{
+  "vehicle_id": "veh_123456",
+  "assignment_date": "2024-01-15",
+  "notes": "Regular delivery route assignment"
+}
+```
+
+## Routes
+
+### Create Route
+```http
+POST /api/v1/logistics/routes/
+```
+
+**Request Body:**
+```json
+{
+  "name": "KL to JB Express Route",
+  "description": "Daily express delivery from Kuala Lumpur to Johor Bahru",
+  "origin": {
+    "address": "123 Warehouse Street, Port Klang, Selangor",
+    "latitude": 3.0000,
+    "longitude": 101.4000
+  },
+  "destination": {
+    "address": "456 Customer Street, Johor Bahru, Johor",
+    "latitude": 1.4927,
+    "longitude": 103.7414
+  },
+  "waypoints": [
+    {
+      "address": "Transit Point A, Seremban, Negeri Sembilan",
+      "latitude": 2.7253,
+      "longitude": 101.9380,
+      "stop_duration_minutes": 15
+    },
+    {
+      "address": "Transit Point B, Melaka Tengah, Melaka",
+      "latitude": 2.1892,
+      "longitude": 102.2501,
+      "stop_duration_minutes": 20
+    }
+  ],
+  "estimated_distance_km": 350.5,
+  "estimated_duration_minutes": 240,
+  "vehicle_type": "van",
+  "driver_requirements": ["GDL license", "experience_2_years"],
+  "operating_hours": {
+    "start": "08:00:00",
+    "end": "18:00:00"
+  },
+  "frequency": "daily",
+  "active_days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
+  "priority": "high",
+  "notes": "Priority route for urgent deliveries"
+}
+```
+
+### Get Route
+```http
+GET /api/v1/logistics/routes/{route_id}/
+```
+
+### Update Route
+```http
+PUT /api/v1/logistics/routes/{route_id}/
+```
+
+### List Routes
+```http
+GET /api/v1/logistics/routes/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `origin_state` - Filter by origin state
+- `destination_state` - Filter by destination state
+- "vehicle_type" - Filter by vehicle type
+- `priority` - Filter by priority
+- `frequency` - Filter by frequency
+
+### Optimize Route
+```http
+POST /api/v1/logistics/routes/{route_id}/optimize/
+```
+
+**Request Body:**
+```json
+{
+  "shipments": ["shp_123456", "shp_789012"],
+  "vehicle_id": "veh_123456",
+  "optimization_criteria": ["distance", "time", "fuel"]
+}
+```
+
+## Delivery Schedule
+
+### Create Delivery Schedule
+```http
+POST /api/v1/logistics/schedules/
+```
+
+**Request Body:**
+```json
+{
+  "shipment_id": "shp_123456",
+  "driver_id": "drv_123456",
+  "vehicle_id": "veh_123456",
+  "route_id": "route_123456",
+  "scheduled_date": "2024-01-15",
+  "scheduled_time": "09:00:00",
+  "estimated_duration_minutes": 240,
+  "priority": "high",
+  "status": "scheduled",
+  "special_instructions": "Customer requires morning delivery",
+  "contact_preferences": {
+    "phone": true,
+    "sms": true,
+    "email": false
+  }
+}
+```
+
+### Get Delivery Schedule
+```http
+GET /api/v1/logistics/schedules/{schedule_id}/
+```
+
+### Update Delivery Schedule
+```http
+PUT /api/v1/logistics/schedules/{schedule_id}/
+```
+
+### List Delivery Schedules
+```http
+GET /api/v1/logistics/schedules/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `driver_id` - Filter by driver
+- `vehicle_id` - Filter by vehicle
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+- `status` - Filter by status (scheduled, in_progress, completed, cancelled)
+
+## Reports and Analytics
+
+### Shipment Analytics
+```http
+GET /api/v1/logistics/reports/shipments/
+```
+
+**Query Parameters:**
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+- `group_by` - Group by (status, service_type, origin_state, destination_state)
+- `format` - Output format (json, csv, pdf)
+
+### Vehicle Performance
+```http
+GET /api/v1/logistics/reports/vehicle-performance/
+```
+
+**Query Parameters:**
+- `vehicle_id` - Filter by vehicle
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+- `format` - Output format (json, csv, pdf)
+
+### Driver Performance
+```http
+GET /api/v1/logistics/reports/driver-performance/
+```
+
+**Query Parameters:**
+- `driver_id` - Filter by driver
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+- `format` - Output format (json, csv, pdf)
+
+### Route Efficiency
+```http
+GET /api/v1/logistics/reports/route-efficiency/
+```
+
+**Query Parameters:**
+- `route_id` - Filter by route
+- `date_from` - Filter by start date (YYYY-MM-DD)
+- `date_to` - Filter by end date (YYYY-MM-DD)
+- `format` - Output format (json, csv, pdf)
+
+## Malaysian Logistics Features
+
+### Malaysian Registration Plates
+Support for Malaysian vehicle registration plates:
+```json
+{
+  "registration_number": "WXY 1234",
+  "plate_type": "private",
+  "state_code": "W",  // Kuala Lumpur
+  "registration_details": {
+    "jpj_reference": "JPJ-W-123456",
+    "registration_date": "2022-01-01"
+  }
+}
+```
+
+### Malaysian Driver Licenses
+Support for Malaysian driver license validation:
+- Competent Driving License (CDL)
+- Professional Driving License (PDL)
+- Public Service Vehicle (PSV) License
+
+### PUSPAKOM Compliance
+Integration with PUSPAKOM inspection requirements:
+```json
+{
+  "puspakom_compliance": {
+    "last_inspection_date": "2024-01-01",
+    "next_inspection_date": "2025-01-01",
+    "inspection_center": "PUSPAKOM Shah Alam",
+    "inspection_result": "pass",
+    "certificate_number": "PC202401123456"
+  }
+}
+```
+
+### Malaysian Road Tax
+Support for Malaysian road tax calculation and renewal:
+```json
+{
+  "road_tax_details": {
+    "amount": 350.00,
+    "expiry_date": "2024-12-31",
+    "vehicle_category": "private_vehicle",
+    "engine_capacity_cc": 2500
+  }
+}
+```
+
+### Malaysian Fuel Prices
+Integration with Malaysian fuel pricing:
+```json
+{
+  "fuel_consumption": {
+    "fuel_type": "diesel",
+    "current_price_per_liter": 2.15,
+    "average_consumption_l_per_100km": 12.5,
+    "monthly_fuel_cost": 750.00
+  }
+}
+```
+
+### Toll Integration
+Support for Malaysian toll calculation:
+```json
+{
+  "toll_information": {
+    "route": "PLUS Highway KL-JB",
+    "total_toll_cost": 45.50,
+    "toll_plazas": ["Sungai Besi", "Nilai", "Seremban", "Ayer Keroh"],
+    "electronic_toll": true,
+    "touch_n_go_card": "1234567890"
+  }
+}
+```
+
+### Malaysian Time Zones
+All scheduling uses Malaysian time zone (UTC+8).
+
+### Malaysian Public Holidays
+Integration with Malaysian public holidays for scheduling:
+```json
+{
+  "holiday_aware_scheduling": {
+    "excludes_public_holidays": true,
+    "regional_holidays": ["hari_raya", "chinese_new_year", "deepavali"],
+    "operating_hours_adjustment": true
+  }
+}
+```
+
+### Weather Integration
+Integration with Malaysian weather services:
+```json
+{
+  "weather_considerations": {
+    "monsoon_season": true,
+    "flood_prone_areas": ["Kuala Lumpur", "Johor Bahru"],
+    "weather_alerts": true,
+    "alternative_routes": true
+  }
+}
+```
+
+### Malaysian States Support
+Full support for all Malaysian states and territories:
+```json
+{
+  "malaysian_states": [
+    "Johor", "Kedah", "Kelantan", "Melaka", "Negeri Sembilan",
+    "Pahang", "Perak", "Perlis", "Pulau Pinang", "Sabah",
+    "Sarawak", "Selangor", "Terengganu", "Wilayah Persekutuan"
+  ]
+}
+```

docs/api/retail/README.md

@@ -0,0 +1,516 @@
+# Retail Module API Documentation
+
+## Overview
+
+The Retail Module API provides comprehensive functionality for retail management including product catalog, sales processing, inventory management, and customer loyalty programs.
+
+## Products
+
+### Create Product
+```http
+POST /api/v1/retail/products/
+```
+
+**Request Body:**
+```json
+{
+  "sku": "PRD-2024-001",
+  "name": "Premium Bluetooth Speaker",
+  "description": "High-quality wireless speaker with noise cancellation",
+  "category": "electronics",
+  "brand": "AudioTech",
+  "barcode": "9555123456789",
+  "unit": "piece",
+  "current_stock": 50,
+  "minimum_stock": 10,
+  "maximum_stock": 200,
+  "purchase_price": 150.00,
+  "selling_price": 299.00,
+  "tax_rate": 6.0,
+  "is_active": true,
+  "attributes": {
+    "color": ["black", "white", "blue"],
+    "warranty_months": 24,
+    "weight_kg": 0.8,
+    "dimensions_cm": {
+      "length": 15,
+      "width": 8,
+      "height": 8
+    }
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "prod_123456",
+    "sku": "PRD-2024-001",
+    "name": "Premium Bluetooth Speaker",
+    "description": "High-quality wireless speaker with noise cancellation",
+    "category": "electronics",
+    "brand": "AudioTech",
+    "barcode": "9555123456789",
+    "unit": "piece",
+    "current_stock": 50,
+    "minimum_stock": 10,
+    "maximum_stock": 200,
+    "purchase_price": 150.00,
+    "selling_price": 299.00,
+    "tax_rate": 6.0,
+    "is_active": true,
+    "attributes": {
+      "color": ["black", "white", "blue"],
+      "warranty_months": 24,
+      "weight_kg": 0.8,
+      "dimensions_cm": {
+        "length": 15,
+        "width": 8,
+        "height": 8
+      }
+    },
+    "created_at": "2024-01-01T00:00:00Z",
+    "updated_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### Get Product
+```http
+GET /api/v1/retail/products/{product_id}/
+```
+
+### Update Product
+```http
+PUT /api/v1/retail/products/{product_id}/
+```
+
+### List Products
+```http
+GET /api/v1/retail/products/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `category` - Filter by category
+- `brand` - Filter by brand
+- `is_active` - Filter by active status
+- `search` - Search in name, description, SKU
+- `min_price` - Minimum selling price
+- `max_price` - Maximum selling price
+- `low_stock` - Show only low stock items (true/false)
+
+### Delete Product
+```http
+DELETE /api/v1/retail/products/{product_id}/
+```
+
+### Update Stock
+```http
+POST /api/v1/retail/products/{product_id}/update-stock/
+```
+
+**Request Body:**
+```json
+{
+  "quantity": 25,
+  "operation": "add",
+  "reason": "New stock received",
+  "reference": "PO-2024-001"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "product_id": "prod_123456",
+    "previous_stock": 50,
+    "quantity_changed": 25,
+    "new_stock": 75,
+    "operation": "add",
+    "timestamp": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+## Sales
+
+### Create Sale
+```http
+POST /api/v1/retail/sales/
+```
+
+**Request Body:**
+```json
+{
+  "customer_id": "cust_123456",
+  "items": [
+    {
+      "product_id": "prod_123456",
+      "quantity": 2,
+      "unit_price": 299.00,
+      "discount_rate": 10.0
+    },
+    {
+      "product_id": "prod_789012",
+      "quantity": 1,
+      "unit_price": 150.00
+    }
+  ],
+  "payment_method": "credit_card",
+  "payment_details": {
+    "card_last_four": "1234",
+    "transaction_id": "txn_123456789"
+  },
+  "notes": "Customer loyalty discount applied"
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "id": "sale_123456",
+    "customer_id": "cust_123456",
+    "items": [
+      {
+        "product_id": "prod_123456",
+        "quantity": 2,
+        "unit_price": 299.00,
+        "discount_rate": 10.0,
+        "tax_rate": 6.0,
+        "subtotal": 538.20,
+        "tax_amount": 32.29,
+        "total": 570.49
+      }
+    ],
+    "payment_method": "credit_card",
+    "payment_status": "completed",
+    "subtotal": 748.00,
+    "discount_amount": 59.80,
+    "tax_amount": 44.88,
+    "total": 733.08,
+    "status": "completed",
+    "created_at": "2024-01-01T00:00:00Z"
+  }
+}
+```
+
+### Get Sale
+```http
+GET /api/v1/retail/sales/{sale_id}/
+```
+
+### List Sales
+```http
+GET /api/v1/retail/sales/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `customer_id` - Filter by customer
+- `status` - Filter by status (pending, completed, cancelled, refunded)
+- `payment_method` - Filter by payment method
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+
+### Update Sale Status
+```http
+PUT /api/v1/retail/sales/{sale_id}/status/
+```
+
+**Request Body:**
+```json
+{
+  "status": "refunded",
+  "reason": "Customer return"
+}
+```
+
+### Refund Sale
+```http
+POST /api/v1/retail/sales/{sale_id}/refund/
+```
+
+**Request Body:**
+```json
+{
+  "items": [
+    {
+      "product_id": "prod_123456",
+      "quantity": 1,
+      "reason": "Defective product"
+    }
+  ],
+  "refund_method": "credit_card",
+  "notes": "Partial refund for defective item"
+}
+```
+
+## Customers
+
+### Create Customer
+```http
+POST /api/v1/retail/customers/
+```
+
+**Request Body:**
+```json
+{
+  "first_name": "Ahmad",
+  "last_name": "Ibrahim",
+  "email": "ahmad.ibrahim@example.com",
+  "phone_number": "+60123456789",
+  "ic_number": "900101-01-1234",
+  "address": {
+    "street": "123 Customer Street",
+    "city": "Kuala Lumpur",
+    "state": "Wilayah Persekutuan",
+    "postal_code": "50050",
+    "country": "Malaysia"
+  },
+  "loyalty_tier": "bronze",
+  "loyalty_points": 0,
+  "notes": "VIP customer"
+}
+```
+
+### Get Customer
+```http
+GET /api/v1/retail/customers/{customer_id}/
+```
+
+### Update Customer
+```http
+PUT /api/v1/retail/customers/{customer_id}/
+```
+
+### List Customers
+```http
+GET /api/v1/retail/customers/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `loyalty_tier` - Filter by loyalty tier (bronze, silver, gold, platinum)
+- `search` - Search in name, email, phone
+- `is_active` - Filter by active status
+
+### Delete Customer
+```http
+DELETE /api/v1/retail/customers/{customer_id}/
+```
+
+### Get Customer Purchase History
+```http
+GET /api/v1/retail/customers/{customer_id}/purchase-history/
+```
+
+**Query Parameters:**
+- `page` - Page number (default: 1)
+- `page_size` - Items per page (default: 20, max: 100)
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+
+## Inventory Management
+
+### Stock Adjustment
+```http
+POST /api/v1/retail/inventory/adjust/
+```
+
+**Request Body:**
+```json
+{
+  "product_id": "prod_123456",
+  "quantity": -5,
+  "reason": "Damaged items",
+  "reference": "ADJ-2024-001",
+  "notes": "5 items damaged during delivery"
+}
+```
+
+### Stock Transfer
+```http
+POST /api/v1/retail/inventory/transfer/
+```
+
+**Request Body:**
+```json
+{
+  "product_id": "prod_123456",
+  "quantity": 10,
+  "from_location": "Warehouse A",
+  "to_location": "Store B",
+  "reference": "TRANSFER-2024-001",
+  "notes": "Transfer for weekend promotion"
+}
+```
+
+### Stock Alert
+```http
+GET /api/v1/retail/inventory/alerts/
+```
+
+**Query Parameters:**
+- `type` - Alert type (low_stock, overstock, expiry)
+- `severity` - Severity level (low, medium, high)
+
+### Inventory Report
+```http
+GET /api/v1/retail/inventory/report/
+```
+
+**Query Parameters:**
+- `category` - Filter by category
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+- `format` - Output format (json, csv)
+
+## Loyalty Program
+
+### Update Loyalty Points
+```http
+POST /api/v1/retail/loyalty/update-points/
+```
+
+**Request Body:**
+```json
+{
+  "customer_id": "cust_123456",
+  "points": 50,
+  "operation": "add",
+  "reason": "Purchase reward",
+  "reference": "sale_123456"
+}
+```
+
+### Get Loyalty Tiers
+```http
+GET /api/v1/retail/loyalty/tiers/
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "name": "Bronze",
+      "min_points": 0,
+      "max_points": 999,
+      "discount_rate": 0.0,
+      "benefits": ["Basic membership"]
+    },
+    {
+      "name": "Silver",
+      "min_points": 1000,
+      "max_points": 4999,
+      "discount_rate": 5.0,
+      "benefits": ["5% discount", "Birthday voucher"]
+    },
+    {
+      "name": "Gold",
+      "min_points": 5000,
+      "max_points": 9999,
+      "discount_rate": 10.0,
+      "benefits": ["10% discount", "Priority support", "Free shipping"]
+    },
+    {
+      "name": "Platinum",
+      "min_points": 10000,
+      "max_points": null,
+      "discount_rate": 15.0,
+      "benefits": ["15% discount", "VIP support", "Exclusive events"]
+    }
+  ]
+}
+```
+
+### Redeem Loyalty Points
+```http
+POST /api/v1/retail/loyalty/redeem/
+```
+
+**Request Body:**
+```json
+{
+  "customer_id": "cust_123456",
+  "points": 100,
+  "reward_type": "discount",
+  "reference": "sale_123456"
+}
+```
+
+## Reports and Analytics
+
+### Sales Report
+```http
+GET /api/v1/retail/reports/sales/
+```
+
+**Query Parameters:**
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+- `group_by` - Group by (day, week, month, category, product)
+- `format` - Output format (json, csv, pdf)
+
+### Inventory Report
+```http
+GET /api/v1/retail/reports/inventory/
+```
+
+**Query Parameters:**
+- `category` - Filter by category
+- `location` - Filter by location
+- `format` - Output format (json, csv, pdf)
+
+### Customer Analytics
+```http
+GET /api/v1/retail/reports/customers/
+```
+
+**Query Parameters:**
+- `date_from` - Filter by date (YYYY-MM-DD)
+- `date_to` - Filter by date (YYYY-MM-DD)
+- `segment_by` - Segment by (loyalty_tier, location, purchase_frequency)
+- `format` - Output format (json, csv, pdf)
+
+## Malaysian Features
+
+### SST Calculation
+All price-related endpoints include automatic SST calculation:
+```json
+{
+  "subtotal": 299.00,
+  "sst_rate": 0.06,
+  "sst_amount": 17.94,
+  "total": 316.94
+}
+```
+
+### Malaysian Currency
+All amounts are in Malaysian Ringgit (MYR).
+
+### Malaysian Address Format
+Customer addresses follow Malaysian address format with states and postal codes.
+
+### Halal Certification Support
+Products can include halal certification information:
+```json
+{
+  "attributes": {
+    "halal_certified": true,
+    "halal_certification_number": "JAKIM-1234-5678",
+    "halal_expiry_date": "2025-12-31"
+  }
+}
+```