tinker_tickets/README.md

# Tinker Tickets

A feature-rich PHP-based ticketing system designed for tracking and managing data center infrastructure issues with enterprise-grade workflow management.

## ✨ Core Features

### 📊 Dashboard & Ticket Management
- **Smart Dashboard**: Sortable columns, advanced filtering by status/priority/category/type
- **Full-Text Search**: Search across tickets, descriptions, and metadata
- **Ticket Assignment**: Assign tickets to specific users with "Assigned To" column
- **Priority Tracking**: P1 (Critical) to P5 (Minimal Impact) with color-coded indicators
- **Custom Categories**: Hardware, Software, Network, Security, General
- **Ticket Types**: Maintenance, Install, Task, Upgrade, Issue, Problem

### 🔄 Workflow Management
- **Status Transitions**: Enforced workflow rules (Open → In Progress → Resolved → Closed)
- **Workflow Validation**: Server-side validation prevents invalid status changes
- **Admin Controls**: Certain transitions can require admin privileges
- **Comment Requirements**: Optional comment requirements for specific transitions
- **Activity Timeline**: Complete audit trail of all ticket changes

### 💬 Collaboration Features
- **Markdown Comments**: Full Markdown support with live preview
- **User Tracking**: Tracks who created, updated, and assigned tickets
- **Activity Timeline**: Shows all ticket events (creates, updates, assignments, comments)
- **Real-time Updates**: AJAX-powered updates without page refreshes

### 🎫 Ticket Templates
- **Quick Creation**: Pre-configured templates for common issues
- **Default Templates**: Hardware Failure, Software Installation, Network Issue, Maintenance
- **Auto-fill**: Templates populate title, description, category, type, and priority

### 👥 User Management & Authentication
- **SSO Integration**: Authelia authentication with LLDAP backend
- **Role-Based Access**: Admin and standard user roles
- **User Display Names**: Support for display names and usernames
- **Session Management**: Secure PHP session handling

### ⚡ Bulk Actions (Admin Only)
- **Bulk Close**: Close multiple tickets at once
- **Bulk Assign**: Assign multiple tickets to a user
- **Bulk Priority**: Change priority for multiple tickets
- **Operation Tracking**: All bulk operations logged in audit trail

### 🔔 Notifications
- **Discord Integration**: Webhook notifications for ticket creation and updates
- **Rich Embeds**: Color-coded priority indicators and ticket links
- **Change Tracking**: Detailed notification of what changed

### 🎨 User Interface
- **Dark Mode**: Full dark mode support with proper contrast
- **Responsive Design**: Works on desktop and mobile devices
- **Clean Layout**: Modern, intuitive interface
- **Hamburger Menu**: Quick access to ticket actions (priority, category, type)

## 🏗️ Technical Architecture

### Backend
- **Language**: PHP 7.4+
- **Database**: MariaDB/MySQL
- **Architecture**: MVC pattern with models, views, controllers
- **ORM**: Custom database abstraction layer

### Frontend
- **HTML5/CSS3**: Semantic markup with modern CSS
- **JavaScript**: Vanilla JS with Fetch API for AJAX
- **Markdown**: marked.js for Markdown rendering
- **Icons**: Unicode emoji icons

### Database Schema
- **tickets**: Core ticket data with user tracking
- **comments**: Markdown-supported comments
- **users**: User accounts synced from LLDAP
- **audit_log**: Complete audit trail with JSON details
- **status_transitions**: Workflow configuration
- **ticket_templates**: Reusable ticket templates
- **bulk_operations**: Tracking for bulk admin operations

### API Endpoints
- `/api/update_ticket.php` - Update ticket with workflow validation
- `/api/assign_ticket.php` - Assign ticket to user
- `/api/add_comment.php` - Add comment to ticket
- `/api/get_template.php` - Fetch ticket template
- `/api/get_users.php` - Get user list for assignments
- `/api/bulk_operation.php` - Perform bulk operations (admin only)

## 🚀 Setup & Configuration

### 1. Environment Configuration

Create `.env` file in project root:
```env
DB_HOST=10.10.10.50
DB_USER=tinkertickets
DB_PASS=your_password
DB_NAME=ticketing_system
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
```

### 2. Database Setup

Run migrations in order:
```bash
# Navigate to project directory
cd /root/code/tinker_tickets

# Run each migration
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system < migrations/001_initial_schema.sql
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system < migrations/007_add_ticket_assignment.sql
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system < migrations/008_add_status_workflows.sql
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system < migrations/009_add_ticket_templates.sql
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system < migrations/010_add_bulk_operations.sql
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system < migrations/011_remove_view_tracking.sql
```

### 3. Web Server Configuration

**Apache Configuration** (recommended):
```apache
<VirtualHost *:80>
    ServerName t.lotusguild.org
    DocumentRoot /root/code/tinker_tickets

    <Directory /root/code/tinker_tickets>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted

        # Enable mod_rewrite for clean URLs
        RewriteEngine On
        RewriteBase /

        # Route ticket URLs
        RewriteRule ^ticket/([0-9]+)$ ticket.php?id=$1 [L,QSA]

        # Route ticket create
        RewriteRule ^ticket/create$ ticket.php?action=create [L,QSA]
    </Directory>
</VirtualHost>
```

### 4. Authelia Integration

Tinker Tickets uses Authelia for SSO. User information is passed via headers:
- `Remote-User`: Username
- `Remote-Name`: Display name
- `Remote-Email`: Email address
- `Remote-Groups`: User groups (comma-separated)

Admin users must be in the `admins` group in LLDAP.

## 📁 Project Structure

```
tinker_tickets/
├── api/                    # API endpoints
│   ├── add_comment.php
│   ├── assign_ticket.php
│   ├── bulk_operation.php
│   ├── get_template.php
│   ├── get_users.php
│   └── update_ticket.php
├── assets/                 # Static assets
│   ├── css/
│   │   ├── dashboard.css
│   │   └── ticket.css
│   └── js/
│       ├── dashboard.js
│       └── ticket.js
├── config/                 # Configuration
│   └── config.php
├── controllers/            # MVC Controllers
│   ├── DashboardController.php
│   └── TicketController.php
├── models/                 # Data models
│   ├── AuditLogModel.php
│   ├── BulkOperationsModel.php
│   ├── CommentModel.php
│   ├── TemplateModel.php
│   ├── TicketModel.php
│   ├── UserModel.php
│   └── WorkflowModel.php
├── views/                  # View templates
│   ├── CreateTicketView.php
│   ├── DashboardView.php
│   └── TicketView.php
├── migrations/             # Database migrations
│   ├── 001_initial_schema.sql
│   ├── 007_add_ticket_assignment.sql
│   ├── 008_add_status_workflows.sql
│   ├── 009_add_ticket_templates.sql
│   ├── 010_add_bulk_operations.sql
│   └── 011_remove_view_tracking.sql
├── index.php              # Dashboard entry point
├── ticket.php             # Ticket view/create entry point
└── .env                   # Environment configuration
```

## 🔐 Security Features

- **SQL Injection Prevention**: All queries use prepared statements
- **XSS Protection**: All output is properly escaped with `htmlspecialchars()`
- **Session Security**: Secure PHP session handling
- **Admin Validation**: Server-side admin checks for privileged operations
- **Workflow Enforcement**: Status transitions validated server-side
- **Audit Logging**: Complete audit trail of all actions

## 🎯 Workflow States

### Default Workflow
```
Open → In Progress → Resolved → Closed
  ↓         ↓          ↓
  └─────────┴──────────┘
        (can reopen)
```

### Workflow Configuration
Status transitions are defined in the `status_transitions` table:
- `from_status`: Current status
- `to_status`: Target status
- `requires_comment`: Whether transition requires a comment
- `requires_admin`: Whether transition requires admin privileges
- `is_active`: Whether transition is enabled

## 📝 Usage Examples

### Creating a Ticket
1. Click "New Ticket" button
2. Select template (optional) - auto-fills common fields
3. Fill in title, description, category, type, priority
4. Click "Create Ticket"

### Updating Ticket Status
1. Open ticket
2. Click status dropdown (next to priority badge)
3. Select allowed status (workflow-validated)
4. Confirm if comment is required

### Assigning Tickets
1. Open ticket or use dashboard bulk actions
2. Select user from "Assigned to" dropdown
3. Changes are auto-saved

### Bulk Operations (Admin Only)
1. Check multiple tickets on dashboard
2. Select bulk action (Close, Assign, Change Priority)
3. Complete operation
4. All actions are logged in audit trail

## 🔮 Roadmap

- ✅ Activity Timeline
- ✅ Ticket Assignment
- ✅ Status Transitions with Workflows
- ✅ Ticket Templates
- ✅ Bulk Actions (Admin Only)
- 🎨 **ANSI Art Redesign** (Next Priority)
- 🔗 Ticket Dependencies (blocks/blocked by)
- 📊 Custom Dashboard Widgets
- 🔧 Custom Fields per Category

## 🤝 Contributing

This is an internal tool for LotusGuild infrastructure management. For feature requests or bug reports, contact the infrastructure team.

## 📄 License

Internal use only - LotusGuild Infrastructure

## 🙏 Credits

Built with ❤️ for the LotusGuild community
Powered by PHP, MariaDB, and lots of coffee ☕