Files
tinker_tickets/Claude.md

727 lines
24 KiB
Markdown
Raw Normal View History

2026-01-01 15:40:32 -05:00
# Tinker Tickets - Project Documentation for AI Assistants
2026-01-01 19:45:49 -05:00
## Project Status (January 2026)
**Current Phase**: All 5 core features implemented and deployed. Ready for ANSI Art redesign.
**Recent Completion**:
- ✅ Activity Timeline (Feature 1)
- ✅ Ticket Assignment (Feature 2)
- ✅ Status Transitions with Workflows (Feature 3)
- ✅ Ticket Templates (Feature 4)
- ✅ Bulk Actions - Admin Only (Feature 5)
**Next Priority**: 🎨 ANSI Art Redesign (major visual overhaul)
2026-01-01 15:40:32 -05:00
## Project Overview
2026-01-01 19:45:49 -05:00
Tinker Tickets is a feature-rich, self-hosted ticket management system built for managing data center infrastructure issues. It features SSO integration with Authelia/LLDAP, workflow management, Discord notifications, and a comprehensive web interface.
2026-01-01 15:40:32 -05:00
**Tech Stack:**
2026-01-01 19:45:49 -05:00
- Backend: PHP 7.4+ with MySQLi
2026-01-01 15:40:32 -05:00
- Frontend: Vanilla JavaScript, CSS3
2026-01-01 19:45:49 -05:00
- Database: MariaDB on separate LXC (10.10.10.50)
- Web Server: Apache on production (10.10.10.45)
- Authentication: Authelia SSO with LLDAP backend
2026-01-01 15:40:32 -05:00
- External Libraries: marked.js (Markdown rendering)
**Production Environment:**
2026-01-01 19:45:49 -05:00
- **Primary URL**: http://t.lotusguild.org
- **Web Server**: Apache at 10.10.10.45 (`/root/code/tinker_tickets`)
- **Database**: MariaDB at 10.10.10.50 (`ticketing_system` database)
- **Authentication**: Authelia provides SSO via headers
2026-01-01 15:40:32 -05:00
## Architecture
2026-01-01 19:45:49 -05:00
### MVC Pattern
```
Controllers → Models → Database
Views
```
### Project Structure (Updated)
2026-01-01 15:40:32 -05:00
```
/tinker_tickets/
2026-01-01 19:45:49 -05:00
├── api/ # API endpoints
│ ├── add_comment.php # POST: Add comment
│ ├── assign_ticket.php # POST: Assign ticket to user (NEW)
│ ├── bulk_operation.php # POST: Bulk operations - admin only (NEW)
│ ├── get_template.php # GET: Fetch ticket template (NEW)
│ ├── get_users.php # GET: Get user list (NEW)
│ └── update_ticket.php # POST: Update ticket (workflow validation)
├── assets/
2026-01-01 15:40:32 -05:00
│ ├── css/
2026-01-01 19:45:49 -05:00
│ │ ├── dashboard.css # Shared + dashboard + bulk actions
│ │ └── ticket.css # Ticket + timeline + dark mode fixes
2026-01-01 15:40:32 -05:00
│ ├── js/
2026-01-01 19:45:49 -05:00
│ │ ├── dashboard.js # Dashboard + hamburger + bulk actions + templates
│ │ └── ticket.js # Ticket + comments + status updates + assignment
2026-01-01 15:40:32 -05:00
│ └── images/
│ └── favicon.png
├── config/
2026-01-01 19:45:49 -05:00
│ └── config.php # Config + .env loading
├── controllers/ # MVC Controllers
│ ├── DashboardController.php # Dashboard with assigned_to column
│ └── TicketController.php # Ticket CRUD + timeline + templates
├── models/ # Data models
│ ├── AuditLogModel.php # Audit logging + timeline
│ ├── BulkOperationsModel.php # Bulk operations tracking (NEW)
│ ├── CommentModel.php # Comment data access
│ ├── TemplateModel.php # Ticket templates (NEW)
│ ├── TicketModel.php # Ticket CRUD + assignment
│ ├── UserModel.php # User management (NEW)
│ └── WorkflowModel.php # Status transition workflows (NEW)
├── views/ # PHP templates
│ ├── CreateTicketView.php # Ticket creation with templates
│ ├── DashboardView.php # Dashboard with bulk actions + assigned column
│ └── TicketView.php # Ticket view with timeline + assignment
├── migrations/ # Database migrations
│ ├── 001_initial_schema.sql
│ ├── 007_add_ticket_assignment.sql # Ticket assignment
│ ├── 008_add_status_workflows.sql # Workflow rules
│ ├── 009_add_ticket_templates.sql # Ticket templates
│ ├── 010_add_bulk_operations.sql # Bulk operations
│ └── 011_remove_view_tracking.sql # Remove view audit logs
├── .env # Environment variables (GITIGNORED)
├── Claude.md # This file
├── README.md # User documentation
├── index.php # Dashboard entry point
└── ticket.php # Ticket view/create router
2026-01-01 15:40:32 -05:00
```
2026-01-01 19:45:49 -05:00
## Database Schema (Updated)
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Database**: `ticketing_system` at 10.10.10.50
**User**: `tinkertickets`
**Connection**: All APIs create their own connections via config.php
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Core Tables
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
#### `tickets` Table (Updated)
2026-01-01 15:40:32 -05:00
```sql
CREATE TABLE tickets (
2026-01-01 19:45:49 -05:00
ticket_id INT AUTO_INCREMENT PRIMARY KEY,
2026-01-01 15:40:32 -05:00
title VARCHAR(255) NOT NULL,
description TEXT,
2026-01-01 19:45:49 -05:00
status VARCHAR(50) DEFAULT 'Open',
priority INT DEFAULT 4,
category VARCHAR(50) DEFAULT 'General',
type VARCHAR(50) DEFAULT 'Issue',
created_by INT, -- User who created
updated_by INT, -- User who last updated
assigned_to INT, -- User assigned to (NEW)
2026-01-01 15:40:32 -05:00
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
2026-01-01 19:45:49 -05:00
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (created_by) REFERENCES users(user_id),
FOREIGN KEY (updated_by) REFERENCES users(user_id),
FOREIGN KEY (assigned_to) REFERENCES users(user_id) ON DELETE SET NULL,
INDEX idx_status (status),
INDEX idx_assigned_to (assigned_to)
) ENGINE=InnoDB;
```
#### `users` Table (SSO Integration)
```sql
CREATE TABLE users (
user_id INT AUTO_INCREMENT PRIMARY KEY,
username VARCHAR(100) UNIQUE NOT NULL,
display_name VARCHAR(255),
email VARCHAR(255),
is_admin BOOLEAN DEFAULT FALSE,
last_login TIMESTAMP NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
2026-01-01 15:40:32 -05:00
) ENGINE=InnoDB;
```
2026-01-01 19:45:49 -05:00
#### `comments` Table
2026-01-01 15:40:32 -05:00
```sql
2026-01-01 19:45:49 -05:00
CREATE TABLE comments (
2026-01-01 15:40:32 -05:00
comment_id INT AUTO_INCREMENT PRIMARY KEY,
2026-01-01 19:45:49 -05:00
ticket_id INT NOT NULL,
user_id INT,
comment_text TEXT NOT NULL,
markdown_enabled BOOLEAN DEFAULT FALSE,
2026-01-01 15:40:32 -05:00
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
2026-01-01 19:45:49 -05:00
FOREIGN KEY (ticket_id) REFERENCES tickets(ticket_id) ON DELETE CASCADE,
FOREIGN KEY (user_id) REFERENCES users(user_id),
INDEX idx_ticket_id (ticket_id)
2026-01-01 15:40:32 -05:00
) ENGINE=InnoDB;
```
2026-01-01 19:45:49 -05:00
#### `audit_log` Table (Activity Timeline)
```sql
CREATE TABLE audit_log (
log_id INT AUTO_INCREMENT PRIMARY KEY,
user_id INT,
action_type VARCHAR(50) NOT NULL, -- 'create', 'update', 'comment', 'assign', etc.
entity_type VARCHAR(50) NOT NULL, -- 'ticket', 'comment'
entity_id INT NOT NULL, -- ticket_id or comment_id
details JSON, -- JSON details of what changed
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(user_id),
INDEX idx_entity (entity_type, entity_id),
INDEX idx_user (user_id),
INDEX idx_action (action_type)
) ENGINE=InnoDB;
```
#### `status_transitions` Table (Workflow Rules)
```sql
CREATE TABLE status_transitions (
transition_id INT AUTO_INCREMENT PRIMARY KEY,
from_status VARCHAR(50) NOT NULL,
to_status VARCHAR(50) NOT NULL,
requires_comment BOOLEAN DEFAULT FALSE, -- Transition requires comment
requires_admin BOOLEAN DEFAULT FALSE, -- Transition requires admin
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY unique_transition (from_status, to_status),
INDEX idx_from_status (from_status)
) ENGINE=InnoDB;
```
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
Default transitions:
```sql
2026-01-12 17:01:38 -05:00
-- Open → Pending → In Progress → Closed
-- In Progress → Closed, Pending
-- Closed → X
2026-01-01 19:45:49 -05:00
```
#### `ticket_templates` Table
```sql
CREATE TABLE ticket_templates (
template_id INT AUTO_INCREMENT PRIMARY KEY,
template_name VARCHAR(100) NOT NULL,
title_template VARCHAR(255) NOT NULL,
description_template TEXT NOT NULL,
category VARCHAR(50),
type VARCHAR(50),
default_priority INT DEFAULT 4,
created_by INT,
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (created_by) REFERENCES users(user_id),
INDEX idx_template_name (template_name)
) ENGINE=InnoDB;
```
Default templates: Hardware Failure, Software Installation, Network Issue, Maintenance Request
#### `bulk_operations` Table
```sql
CREATE TABLE bulk_operations (
operation_id INT AUTO_INCREMENT PRIMARY KEY,
operation_type VARCHAR(50) NOT NULL, -- 'bulk_close', 'bulk_assign', 'bulk_priority'
ticket_ids TEXT NOT NULL, -- Comma-separated ticket IDs
performed_by INT NOT NULL,
parameters JSON, -- Operation parameters
status VARCHAR(20) DEFAULT 'pending',
total_tickets INT,
processed_tickets INT DEFAULT 0,
failed_tickets INT DEFAULT 0,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
completed_at TIMESTAMP NULL,
FOREIGN KEY (performed_by) REFERENCES users(user_id),
INDEX idx_performed_by (performed_by),
INDEX idx_created_at (created_at)
) ENGINE=InnoDB;
```
## API Endpoints (Updated)
### Authentication
All API endpoints check: `$_SESSION['user']['user_id']` for authentication.
Admin-only endpoints check: `$_SESSION['user']['is_admin']`.
2026-01-01 15:40:32 -05:00
### POST `/api/update_ticket.php`
2026-01-01 19:45:49 -05:00
Updates ticket with workflow validation.
2026-01-01 15:40:32 -05:00
**Request:**
```json
{
2026-01-01 19:45:49 -05:00
"ticket_id": 123,
"status": "In Progress", // Validated against workflow rules
"priority": 2,
"title": "Updated title",
"description": "...",
"category": "Software",
"type": "Task"
2026-01-01 15:40:32 -05:00
}
```
**Response:**
```json
{
"success": true,
"status": "In Progress",
"priority": 2,
"message": "Ticket updated successfully"
}
```
**Features:**
2026-01-01 19:45:49 -05:00
- Workflow validation via WorkflowModel
- Partial updates (only send changed fields)
- User tracking (updated_by)
- Discord webhook notifications
- Audit logging
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### POST `/api/assign_ticket.php` (NEW)
Assigns ticket to a user.
2026-01-01 15:40:32 -05:00
**Request:**
```json
{
2026-01-01 19:45:49 -05:00
"ticket_id": 123,
"assigned_to": 5 // user_id, or null to unassign
}
```
**Response:**
```json
{
"success": true
2026-01-01 15:40:32 -05:00
}
```
2026-01-01 19:45:49 -05:00
### GET `/api/get_users.php` (NEW)
Returns list of all users for assignment dropdowns.
2026-01-01 15:40:32 -05:00
**Response:**
```json
{
"success": true,
2026-01-01 19:45:49 -05:00
"users": [
{
"user_id": 1,
"username": "jared",
"display_name": "Jared Vititoe",
"is_admin": true
}
]
2026-01-01 15:40:32 -05:00
}
```
2026-01-01 19:45:49 -05:00
### GET `/api/get_template.php?template_id=1` (NEW)
Fetches a ticket template.
**Response:**
```json
{
"success": true,
"template": {
"template_id": 1,
"template_name": "Hardware Failure",
"title_template": "Hardware Failure: [Device Name]",
"description_template": "Device: \nIssue: \n...",
"category": "Hardware",
"type": "Problem",
"default_priority": 2
}
}
```
### POST `/api/bulk_operation.php` (NEW - ADMIN ONLY)
Performs bulk operations on tickets.
2026-01-01 15:40:32 -05:00
**Request:**
```json
{
2026-01-01 19:45:49 -05:00
"operation_type": "bulk_close", // or 'bulk_assign', 'bulk_priority'
"ticket_ids": [123, 456, 789],
"parameters": { // For bulk_assign or bulk_priority
"assigned_to": 5, // For bulk_assign
"priority": 2 // For bulk_priority
}
2026-01-01 15:40:32 -05:00
}
```
**Response:**
```json
{
"success": true,
2026-01-01 19:45:49 -05:00
"operation_id": 42,
"processed": 3,
"failed": 0,
"message": "Bulk operation completed: 3 succeeded, 0 failed"
}
```
### POST `/api/add_comment.php`
Adds comment to ticket.
**Request:**
```json
{
"ticket_id": 123,
"comment_text": "Comment content",
"markdown_enabled": true
2026-01-01 15:40:32 -05:00
}
```
2026-01-01 19:45:49 -05:00
**Response:**
2026-01-01 15:40:32 -05:00
```json
{
2026-01-01 19:45:49 -05:00
"success": true,
"user_name": "Jared Vititoe",
"created_at": "Jan 01, 2026 12:00"
2026-01-01 15:40:32 -05:00
}
```
2026-01-01 19:45:49 -05:00
## Key Features Implementation
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Feature 1: Activity Timeline
**Location**: Ticket view → Activity tab
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Implementation**:
- `AuditLogModel->getTicketTimeline()` - Fetches all events for a ticket
- Shows: creates, updates, comments, assignments, status changes
- Displays: user, action, timestamp, details
- CSS: timeline-content boxes with icons
- Dark mode: Fully supported
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Code**: `views/TicketView.php:258-282`, `models/AuditLogModel.php:getTicketTimeline()`
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Feature 2: Ticket Assignment
**Location**: Ticket view → "Assigned to" dropdown, Dashboard → "Assigned To" column
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Implementation**:
- Database: `tickets.assigned_to` column
- Models: `TicketModel->assignTicket()`, `TicketModel->unassignTicket()`
- API: `api/assign_ticket.php`
- Dashboard: Shows assigned user in table
- Auto-saves on change
- Audit logged
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Code**: `views/TicketView.php:170-181`, `assets/js/ticket.js:handleAssignmentChange()`
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Feature 3: Status Transitions with Workflows
**Location**: Ticket view → Status dropdown (header)
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Implementation**:
- Database: `status_transitions` table defines allowed transitions
- Models: `WorkflowModel->isTransitionAllowed()`, `WorkflowModel->getAllowedTransitions()`
- Dropdown shows only valid transitions for current status
- Server-side validation prevents invalid changes
- Can require comments or admin privileges
- Removed from hamburger menu (was duplicate)
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Code**: `models/WorkflowModel.php`, `api/update_ticket.php:130-144`, `views/TicketView.php:185-198`
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Feature 4: Ticket Templates
**Location**: Create ticket page → Template selector
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Implementation**:
- Database: `ticket_templates` table
- Models: `TemplateModel->getAllTemplates()`, `TemplateModel->getTemplateById()`
- API: `api/get_template.php`
- JavaScript: `loadTemplate()` in dashboard.js
- Auto-fills: title, description, category, type, priority
- 4 default templates included
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Code**: `views/CreateTicketView.php:27-39`, `assets/js/dashboard.js:loadTemplate()`
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Feature 5: Bulk Actions (Admin Only)
**Location**: Dashboard → Checkboxes + Toolbar (admins only)
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Implementation**:
- Database: `bulk_operations` table tracks operations
- Models: `BulkOperationsModel->processBulkOperation()`
- API: `api/bulk_operation.php`
- UI: Toolbar appears when tickets selected
- Operations: Bulk close, bulk assign, bulk priority
- All operations audit logged
- Server-side admin validation
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Code**: `views/DashboardView.php:176-188`, `assets/js/dashboard.js:bulkClose()`, `models/BulkOperationsModel.php`
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
## Authentication & SSO Integration
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Authelia Integration
User information passed via HTTP headers:
- `Remote-User`: Username
- `Remote-Name`: Display name
- `Remote-Email`: Email
- `Remote-Groups`: Comma-separated groups
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Session Management
```php
$_SESSION['user'] = [
'user_id' => 123,
'username' => 'jared',
'display_name' => 'Jared Vititoe',
'email' => 'jared@lotusguild.org',
'is_admin' => true // true if 'admins' in Remote-Groups
];
2026-01-01 15:40:32 -05:00
```
2026-01-01 19:45:49 -05:00
### Admin Privileges
- Bulk operations (close, assign, priority)
- Future: Admin-only transitions
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
## Frontend Components (Updated)
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Dashboard (`DashboardView.php` + `dashboard.js`)
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Features**:
- Sortable columns including new "Assigned To" column
- Search (title, description, ticket_id, category, type)
- Status filtering (default: Open + In Progress)
- Pagination (configurable)
- Dark mode toggle
- **Bulk Actions Toolbar** (admin only):
- Checkboxes on each ticket
- "Select All" checkbox
- Bulk close, assign, priority buttons
- Shows count of selected tickets
**Hamburger Menu**:
- Category/Type filtering
- Apply/Clear filters
- No status field (removed)
### Ticket View (`TicketView.php` + `ticket.js`)
**Features**:
- **Tabbed Interface**: Description, Comments, Activity
- **Activity Timeline**: Complete audit trail with icons
- **Assignment Dropdown**: Assign to users
- **Status Dropdown**: Workflow-validated status changes (header)
- **Hamburger Menu**: Priority, Category, Type editing
- **Edit Button**: Title and description editing
- **Markdown Comments**: With live preview
- **Dark Mode**: Comprehensive support
**Visual Indicators**:
- Priority colors (P1=Red, P2=Orange, P3=Blue, P4=Green, P5=Gray)
2026-01-12 17:01:38 -05:00
- Status badges (Open=Green, In Progress=Yellow, Closed=Red)
2026-01-01 19:45:49 -05:00
- Priority border colors on ticket container
### Create Ticket (`CreateTicketView.php`)
**Features**:
- **Template Selector**: Quick-fill from templates
- Standard fields: title, description, status, priority, category, type
- Form validation
- Discord webhook on creation
## Dark Mode (Fixed)
### Comprehensive Dark Mode CSS
**Files**: `assets/css/ticket.css`, `assets/css/dashboard.css`
**Colors**:
```css
body.dark-mode {
--bg-primary: #1a202c; /* Main background */
--bg-secondary: #2d3748; /* Cards, inputs */
--bg-tertiary: #4a5568; /* Hover states */
--text-primary: #e2e8f0; /* Main text */
--text-secondary: #cbd5e0; /* Secondary text */
--text-muted: #a0aec0; /* Muted text */
--border-color: #4a5568; /* Borders */
2026-01-01 15:40:32 -05:00
}
```
2026-01-01 19:45:49 -05:00
**Fixed Elements**:
- Timeline boxes (background + text)
- Bulk actions toolbar
- Tables and table rows
- Input fields and textareas
- Dropdowns and selects
- Comment boxes
- Modal dialogs
- All text elements
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Important**: Used `!important` flags to override any conflicting styles.
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
## Configuration
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Environment Variables (`.env`)
```ini
DB_HOST=10.10.10.50
DB_USER=tinkertickets
DB_PASS=password
DB_NAME=ticketing_system
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
```
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**CRITICAL**: `.env` is gitignored! Never commit this file.
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Apache Configuration
**Virtual Host**: Apache serving from `/root/code/tinker_tickets`
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
```apache
<VirtualHost *:80>
ServerName t.lotusguild.org
DocumentRoot /root/code/tinker_tickets
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
<Directory /root/code/tinker_tickets>
Options -Indexes +FollowSymLinks
AllowOverride All
Require all granted
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
RewriteEngine On
RewriteBase /
RewriteRule ^ticket/([0-9]+)$ ticket.php?id=$1 [L,QSA]
RewriteRule ^ticket/create$ ticket.php?action=create [L,QSA]
</Directory>
</VirtualHost>
2026-01-01 15:40:32 -05:00
```
2026-01-01 19:45:49 -05:00
## Deployment
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Git Auto-Deploy
**Repository**: https://code.lotusguild.org/LotusGuild/tinker_tickets
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
**Flow**:
1. Push to `main` branch
2. Auto-deploys to `/root/code/tinker_tickets` on 10.10.10.45
3. `.env` is preserved
4. Migrations must be run manually
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
### Running Migrations
```bash
cd /root/code/tinker_tickets/migrations
mysql -h 10.10.10.50 -u tinkertickets -p'pass' ticketing_system < 007_add_ticket_assignment.sql
mysql -h 10.10.10.50 -u tinkertickets -p'pass' ticketing_system < 008_add_status_workflows.sql
mysql -h 10.10.10.50 -u tinkertickets -p'pass' ticketing_system < 009_add_ticket_templates.sql
mysql -h 10.10.10.50 -u tinkertickets -p'pass' ticketing_system < 010_add_bulk_operations.sql
mysql -h 10.10.10.50 -u tinkertickets -p'pass' ticketing_system < 011_remove_view_tracking.sql
```
2026-01-01 15:40:32 -05:00
## Development Guidelines
### Code Style
2026-01-01 19:45:49 -05:00
- **PHP**: Tabs for indentation, prepared statements, `htmlspecialchars()` for output
- **JavaScript**: Vanilla JS, `fetch()` for AJAX, clear function names
- **CSS**: CSS variables for theming, mobile-responsive
- **Security**: No SQL injection, XSS prevention, session validation
2026-01-01 15:40:32 -05:00
### Error Handling
2026-01-01 19:45:49 -05:00
- APIs return JSON with `{success: bool, error: string}`
- Debug logging to `/tmp/api_debug.log` (update_ticket.php)
- User-friendly error messages
### Adding New Features
1. **Database**: Create migration in `migrations/`
2. **Model**: Add methods to relevant Model class
3. **API**: Create API endpoint in `api/` (with auth check)
4. **Controller**: Update controller to load data
5. **View**: Add UI elements
6. **JavaScript**: Add interactivity
7. **CSS**: Style for light + dark mode
8. **Test**: Test thoroughly before pushing
## ANSI Art Redesign (Next Priority)
### Goal
Transform Tinker Tickets into a retro terminal aesthetic using ANSI art and ASCII characters.
### Design Concept
- **Terminal-style borders**: Use box-drawing characters (┌─┐│└─┘)
- **Monospace fonts**: Courier New, Consolas, Monaco
- **ASCII art headers**: Stylized "TINKER TICKETS" banner
- **Retro color palette**: Green terminal, amber terminal, or custom
- **Template objects**: Reusable border/box components
### Implementation Approach
1. **CSS Variables**: Define ANSI color palette
2. **Border Components**: Create CSS classes for boxes with ASCII borders
3. **Typography**: Monospace fonts throughout
4. **Icons**: Replace emoji with ASCII art
5. **Dashboard**: Terminal-style table with borders
6. **Tickets**: Box-drawing characters for sections
7. **Forms**: Terminal-style input boxes
### Reference Colors (Classic Terminal)
```css
:root {
--ansi-black: #000000;
--ansi-green: #00ff00;
--ansi-amber: #ffb000;
--ansi-blue: #0000ff;
--ansi-cyan: #00ffff;
--ansi-white: #ffffff;
--ansi-bg: #000000;
}
```
### Example Box Template
```
┌─────────────────────────────┐
│ TICKET #123
├─────────────────────────────┤
│ Title: Hardware Failure │
│ Status: [OPEN] │
│ Priority: P1 (CRITICAL) │
└─────────────────────────────┘
```
2026-01-01 15:40:32 -05:00
## Debugging
2026-01-01 19:45:49 -05:00
### Common Issues
2026-01-01 15:40:32 -05:00
```bash
2026-01-01 19:45:49 -05:00
# API debug logs
2026-01-01 15:40:32 -05:00
tail -f /tmp/api_debug.log
2026-01-01 19:45:49 -05:00
# Database connection
mysql -h 10.10.10.50 -u tinkertickets -p ticketing_system
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
# JavaScript console
# Open browser DevTools (F12) → Console tab
2026-01-01 15:40:32 -05:00
2026-01-01 19:45:49 -05:00
# Check dark mode
# localStorage.getItem('theme')
2026-01-01 15:40:32 -05:00
```
2026-01-01 19:45:49 -05:00
### Known Behaviors
- Ticket viewing no longer tracked (011 migration removes view logs)
- Status can only be changed via header dropdown (removed from hamburger)
- Bulk actions only visible to admins
- Templates are optional when creating tickets
- Workflow validation prevents invalid status transitions
2026-01-01 15:40:32 -05:00
## Important Notes for AI Assistants
2026-01-01 19:45:49 -05:00
1. **All 5 features are complete and deployed**
2. **Dark mode is fixed** with comprehensive CSS
3. **Next priority is ANSI Art redesign** (major visual overhaul)
4. **Database at 10.10.10.50**, can't access directly from dev machine
5. **Auto-deploy is active**, test carefully before pushing
6. **Session format**: `$_SESSION['user']['user_id']` (not `$_SESSION['user_id']`)
7. **API auth**: Check `$_SESSION['user']['user_id']` exists
8. **Admin check**: `$_SESSION['user']['is_admin'] ?? false`
9. **Config path**: `config/config.php` (not `config/db.php`)
10. **Migrations**: Must be run manually on database server
2026-01-01 15:40:32 -05:00
## File Reference Quick Guide
| File | Purpose | Key Functions |
|------|---------|---------------|
2026-01-01 19:45:49 -05:00
| `index.php` | Dashboard router | Database connection, routing |
| `ticket.php` | Ticket router | View/create ticket routing |
| `api/update_ticket.php` | Update API | Workflow validation, partial updates |
| `api/assign_ticket.php` | Assignment API | Assign/unassign tickets |
| `api/bulk_operation.php` | Bulk ops API | Admin bulk operations |
| `api/get_template.php` | Template API | Fetch ticket templates |
| `api/get_users.php` | Users API | Get user list |
| `models/TicketModel.php` | Ticket data | CRUD, assignment, filtering |
| `models/WorkflowModel.php` | Workflow rules | Status transition validation |
| `models/AuditLogModel.php` | Audit logging | Timeline, activity tracking |
| `models/TemplateModel.php` | Templates | Template CRUD |
| `models/BulkOperationsModel.php` | Bulk ops | Process bulk operations |
| `controllers/DashboardController.php` | Dashboard logic | Pagination, filters, assigned column |
| `controllers/TicketController.php` | Ticket logic | CRUD, timeline, templates |
| `assets/js/dashboard.js` | Dashboard UI | Filters, bulk actions, templates |
| `assets/js/ticket.js` | Ticket UI | Status updates, assignment, comments |
| `assets/css/dashboard.css` | Dashboard styles | Layout, table, bulk toolbar, dark mode |
| `assets/css/ticket.css` | Ticket styles | Timeline, ticket view, dark mode |
## Repository & Contact
- **Gitea**: https://code.lotusguild.org/LotusGuild/tinker_tickets
- **Production**: http://t.lotusguild.org
- **Infrastructure**: LotusGuild data center management