# Customer Support Ticketing System

## Overview
This document provides documentation for the customer support ticketing system implemented for the StoreWeb e-commerce platform. The system enables customers, support agents, and administrators to submit, manage, and resolve issues related to orders, products, and services.

## Features

### Customer Features
- Create support tickets with various types (Return Request, Exchange, Complaint, etc.)
- Associate tickets with existing orders
- Upload attachments (images, documents)
- View ticket status and history
- Receive email notifications
- Rate satisfaction after ticket resolution

### Support Agent Features
- View and manage assigned tickets
- Update ticket status
- Assign tickets to agents
- Add public replies and internal notes
- View customer attachments

### Administrator Features
- View all tickets across the system
- Analytics dashboard with ticket statistics
- View ticket distribution by status and type
- Monitor average resolution time

## Database Schema

The system uses the following tables:

1. `ticket_types` - Predefined ticket types
2. `tickets` - Main ticket table with status, priority, and associations
3. `ticket_attachments` - File attachments for tickets
4. `ticket_replies` - Replies to tickets (public and internal)

## Installation

1. Execute the SQL schema in `tickets/schema.sql` to create the necessary tables
2. Ensure the `tickets/attachments` directory exists and is writable
3. Configure email settings in `includes/email_config.php`

## File Structure

```
tickets/
├── attachments/              # Storage for ticket attachments
├── create.php               # Customer ticket creation page
├── my_tickets.php           # Customer ticket listing page
├── view.php                 # Customer ticket view page
├── agent_dashboard.php      # Support agent dashboard
├── agent_view.php           # Support agent ticket view page
├── admin_dashboard.php      # Admin analytics dashboard
├── schema.sql               # Database schema

includes/
├── ticket_functions.php     # Ticket management functions
├── email_functions.php      # Email notification functions
├── email_config.php         # Email configuration
```

## Security Features

- Role-based access control (customers, agents, admins)
- Input validation and sanitization
- File upload validation (type, size)
- Rate limiting for ticket creation
- SQL injection prevention through prepared statements
- XSS prevention through output encoding

## Email Notifications

The system sends automated email notifications for:
- New ticket creation
- Ticket status updates
- New replies to tickets
- Assignment of tickets to agents

## API Endpoints

The system uses direct PHP functions rather than a RESTful API:
- `createTicket()` - Create a new ticket
- `updateTicketStatus()` - Update ticket status
- `addTicketReply()` - Add a reply to a ticket
- `assignTicketToAgent()` - Assign ticket to support agent

## Customization

### Ticket Types
Modify the `ticket_types` table to add or remove ticket types.

### Email Templates
Edit the email template functions in `includes/email_config.php`.

### Status Workflow
The default status workflow is: New → In Review → Resolved → Closed
Modify the status validation in the agent view page to customize this workflow.

## Testing

To test the system:
1. Create a customer account and submit a ticket
2. Log in as admin and view the agent dashboard
3. Update ticket status and add replies
4. Check email notifications (requires mail server configuration)
5. Test file uploads with various file types
6. Verify security measures (try to access other users' tickets)

## Troubleshooting

### Email Issues
- Ensure PHP's mail() function is configured correctly
- Check spam folders for notifications
- Verify email addresses in `includes/email_config.php`

### File Upload Issues
- Check directory permissions for `tickets/attachments`
- Verify file size limits in PHP configuration
- Confirm allowed file types in `ticket_functions.php`

### Access Issues
- Verify user roles in the `users` table
- Check session management in `includes/functions.php`
- Ensure proper redirects in page headers

## Future Enhancements

1. Implement a RESTful API for mobile applications
2. Add ticket escalation features
3. Implement SLA tracking
4. Add knowledge base integration
5. Implement chat functionality
6. Add multi-language support
7. Implement ticket merging
8. Add automated ticket routing