# Product Updates Diagnostic Tools Documentation

**Last Updated**: 2025-11-20  
**Status**: Production Ready ✅

## Overview

This document describes all diagnostic tools and endpoints available for troubleshooting, monitoring, and analyzing the Product Updates CMS system. These tools help identify issues, verify configurations, and ensure system health.

## Authentication

### Admin Diagnostic Endpoints

Most admin diagnostic endpoints support two authentication methods:

1. **Session Authentication**: Log in to admin panel first, then access endpoint
2. **Direct Password Authentication**: Append `?password=vXbTz6PqdY6UdexSxlp5` to URL

### Public Diagnostic Endpoints

Some endpoints are public (no authentication required) but may have rate limiting.

## Diagnostic Tools

### 1. Discover Writable Directories

**Endpoint**: `/v2/admin/produkt-updates/discover-writable-directories.php`

**Purpose**: Comprehensive test of all possible writable directories across the entire project structure

**Authentication**: Required (admin session or password parameter)

**Request**:

```
GET /v2/admin/produkt-updates/discover-writable-directories.php
GET /v2/admin/produkt-updates/discover-writable-directories.php?password=vXbTz6PqdY6UdexSxlp5
```

**Response**:

```json
{
  "timestamp": "2025-11-20 10:30:00",
  "base_directory": "/var/www/lexikon",
  "tested_directories": 29,
  "writable_directories": [
    {
      "path": "/var/www/lexikon/wp-content/uploads/",
      "type": "images",
      "exists": true,
      "writable": true,
      "persistent": true,
      "priority": 1,
      "description": "WordPress uploads directory"
    }
  ],
  "summary": {
    "total_tested": 29,
    "total_writable": 4,
    "persistent_writable": 4,
    "volatile_writable": 0
  }
}
```

**What It Tests**:

- 29 directories across entire project structure
- Root-level directories (`/data/`, `/temp/`, `/writable/`)
- WordPress uploads directories (`/wp-content/uploads/`)
- V2-level directories (`/v2/data/`, `/v2/temp/`, etc.)
- Admin-specific directories
- System temp directory (`/tmp/`)

**Use Cases**:

- Finding persistent writable directories
- Diagnosing permission issues
- Planning storage migration
- Verifying directory accessibility

---

### 2. Analyze Production Setup

**Endpoint**: `/v2/admin/produkt-updates/analyze-production-setup.php`

**Purpose**: Analyze production environment and provide setup recommendations

**Authentication**: Required (admin session or password parameter)

**Request**:

```
GET /v2/admin/produkt-updates/analyze-production-setup.php?password=vXbTz6PqdY6UdexSxlp5
```

**Response**:

```json
{
  "timestamp": "2025-11-20 10:30:00",
  "current_setup": {
    "data_file": {
      "location": "/wp-content/uploads/produkt-updates/produkt_updates.json",
      "persistent": true,
      "writable": true
    },
    "images_directory": {
      "location": "/wp-content/uploads/produkt-updates/",
      "persistent": true,
      "writable": true
    }
  },
  "recommendations": [],
  "status": "optimal"
}
```

**What It Analyzes**:

- Current data file location and persistence
- Current image directory location and persistence
- Storage health status
- Recommendations for optimization

**Use Cases**:

- Quick health check
- Storage status verification
- Setup optimization recommendations

---

### 3. List Images

**Endpoint**: `/v2/admin/produkt-updates/list-images.php`

**Purpose**: List all images and compare with JSON data to identify missing or unreferenced images

**Authentication**: Required (admin session or password parameter)

**Request**:

```
GET /v2/admin/produkt-updates/list-images.php?password=vXbTz6PqdY6UdexSxlp5
```

**Response**:

```json
{
  "timestamp": "2025-11-20 10:30:00",
  "status": "success",
  "writable_image_directory": "/wp-content/uploads/produkt-updates/",
  "images_in_writable_dir": {
    "img_123.webp": {
      "full_path": "/var/www/lexikon/wp-content/uploads/produkt-updates/img_123.webp",
      "url": "/v2/api/serve-produkt-updates-image.php?file=img_123.webp",
      "size": 512000,
      "last_modified": "2025-11-20 10:00:00"
    }
  },
  "images_in_json": {
    "img_123.webp": "/v2/api/serve-produkt-updates-image.php?file=img_123.webp"
  },
  "missing_images": {},
  "unreferenced_images": {},
  "statistics": {
    "total_referenced_images": 5,
    "total_found_images": 5,
    "total_missing_images": 0,
    "images_in_writable_dir": 5,
    "total_unreferenced_images": 0
  }
}
```

**What It Does**:

- Lists all images in writable directory
- Lists all images referenced in JSON data
- Compares the two lists
- Identifies missing images (referenced but not found)
- Identifies unreferenced images (found but not referenced)
- Tests path resolution for each image

**Use Cases**:

- Diagnosing image display issues
- Finding orphaned images
- Identifying missing images
- Verifying image storage location

---

### 4. Migrate Missing Images

**Endpoint**: `/v2/admin/produkt-updates/migrate-missing-images.php`

**Purpose**: Find and migrate images from old locations to primary persistent storage

**Authentication**: Required (admin session or password parameter)

**Request**:

```
GET /v2/admin/produkt-updates/migrate-missing-images.php?action=migrate&password=vXbTz6PqdY6UdexSxlp5
```

**Response**:

```json
{
  "timestamp": "2025-11-20 10:30:00",
  "status": "completed",
  "message": "Image migration process finished. 3 images migrated, 3 JSON paths updated.",
  "summary": {
    "total_referenced_images": 5,
    "total_missing_images_before_migration": 3,
    "total_migrated_images": 3,
    "total_failed_migrations": 0,
    "total_json_path_updates": 3,
    "total_missing_after_migration": 0
  },
  "details": [
    {
      "item_id": "feature_123",
      "title": "Feature Title",
      "status": "migrated",
      "old_path": "/tmp/produkt-updates-images/img_123.webp",
      "new_path": "/wp-content/uploads/produkt-updates/img_123.webp",
      "new_json_path": "/v2/api/serve-produkt-updates-image.php?file=img_123.webp",
      "message": "Image successfully copied and JSON path updated."
    }
  ]
}
```

**Actions**:

- `action=check`: Check status without migrating (default)
- `action=migrate`: Start migration process

**What It Does**:

- Identifies images referenced in JSON but missing from primary location
- Searches all known image directories (including old locations)
- Copies found images to primary persistent location
- Updates JSON `featured_image` paths to new location
- Reports migration statistics

**Use Cases**:

- Recovering images after server restart
- Migrating images from volatile to persistent storage
- Fixing broken image references

---

### 5. Test Production Endpoints

**Endpoint**: `/v2/admin/produkt-updates/test-production-endpoints.php`

**Purpose**: Test all diagnostic endpoints on production to verify deployment and accessibility

**Authentication**: Required (admin session or password parameter)

**Request**:

```
GET /v2/admin/produkt-updates/test-production-endpoints.php?password=vXbTz6PqdY6UdexSxlp5
```

**Response**:

```json
{
  "timestamp": "2025-11-20 10:30:00",
  "endpoints_tested": [
    {
      "url": "/v2/api/produkt-updates-diagnostics.php",
      "status_code": 200,
      "accessible": true,
      "response_time_ms": 45
    }
  ],
  "summary": {
    "total_tested": 5,
    "successful": 5,
    "failed": 0
  }
}
```

**What It Tests**:

- All diagnostic API endpoints
- Response codes
- Response times
- Accessibility

**Use Cases**:

- Verifying endpoint deployment
- Testing endpoint accessibility
- Performance monitoring

---

### 6. Comprehensive Production Test

**Endpoint**: `/v2/admin/produkt-updates/comprehensive-production-test.php`

**Purpose**: End-to-end testing suite for production environment

**Authentication**: Required (admin session or password parameter)

**Request**:

```
GET /v2/admin/produkt-updates/comprehensive-production-test.php?password=vXbTz6PqdY6UdexSxlp5
```

**Response**:

```json
{
  "timestamp": "2025-11-20 10:30:00",
  "status": "pass",
  "tests": [
    {
      "name": "Data file accessibility",
      "status": "pass",
      "message": "Data file is readable and writable"
    },
    {
      "name": "Image directory writability",
      "status": "pass",
      "message": "Image directory is writable"
    },
    {
      "name": "Storage persistence",
      "status": "pass",
      "message": "Using persistent storage locations"
    }
  ],
  "summary": {
    "total_tests": 10,
    "passed": 10,
    "failed": 0,
    "warnings": 0
  }
}
```

**What It Tests**:

- Data file accessibility and writability
- Image directory writability
- Storage persistence
- Path resolution correctness
- JSON data validity
- Image proxy functionality

**Use Cases**:

- Comprehensive system health check
- Pre-deployment verification
- Post-deployment validation
- Troubleshooting system issues

---

### 7. Test Discovery Deployment

**Endpoint**: `/v2/admin/produkt-updates/test-discovery-deployment.php`

**Purpose**: Simple test to verify discovery script is deployed and accessible

**Authentication**: Required (admin session or password parameter)

**Request**:

```
GET /v2/admin/produkt-updates/test-discovery-deployment.php?password=vXbTz6PqdY6UdexSxlp5
```

**Response**:

```json
{
  "timestamp": "2025-11-20 10:30:00",
  "discovery_script": {
    "path": "/var/www/lexikon/v2/admin/produkt-updates/discover-writable-directories.php",
    "exists": true,
    "readable": true,
    "size": 55300,
    "last_modified": "2025-11-20 09:00:00"
  },
  "status": "deployed"
}
```

**What It Checks**:

- Discovery script file existence
- File readability
- File size
- Last modification time

**Use Cases**:

- Verifying script deployment
- Debugging "File not found" errors
- Checking file accessibility

---

## API Diagnostic Endpoints

### 8. Diagnostics

**Endpoint**: `/v2/api/produkt-updates-diagnostics.php`

**Purpose**: Comprehensive system diagnostics

**Authentication**: Optional (public endpoint, but may have rate limiting)

**Request**:

```
GET /v2/api/produkt-updates-diagnostics.php
GET /v2/api/produkt-updates-diagnostics.php?password=vXbTz6PqdY6UdexSxlp5
```

**Response**: See [API Reference](./PRODUCT_UPDATES_API_REFERENCE.md#3-diagnostics)

**What It Checks**:

- PHP version and extensions
- File system permissions
- External resource availability (CDN libraries)
- JSON data validity
- Storage locations

---

### 9. Storage Health Check

**Endpoint**: `/v2/api/produkt-updates-storage-health.php`

**Purpose**: Quick health check for storage status

**Authentication**: Optional (public endpoint, but may have rate limiting)

**Request**:

```
GET /v2/api/produkt-updates-storage-health.php
GET /v2/api/produkt-updates-storage-health.php?password=vXbTz6PqdY6UdexSxlp5
```

**Response**: See [API Reference](./PRODUCT_UPDATES_API_REFERENCE.md#4-storage-health-check)

**What It Checks**:

- Data file location and persistence
- Image directory location and persistence
- Server restart impact
- Storage warnings

---

## Usage Workflow

### Initial Troubleshooting

1. **Check Storage Status**:

   ```
   GET /v2/api/produkt-updates-storage-health.php
   ```

2. **Discover Writable Directories**:

   ```
   GET /v2/admin/produkt-updates/discover-writable-directories.php?password=...
   ```

3. **Analyze Production Setup**:
   ```
   GET /v2/admin/produkt-updates/analyze-production-setup.php?password=...
   ```

### Image Issues

1. **List Images**:

   ```
   GET /v2/admin/produkt-updates/list-images.php?password=...
   ```

2. **Migrate Missing Images** (if needed):
   ```
   GET /v2/admin/produkt-updates/migrate-missing-images.php?action=migrate&password=...
   ```

### Comprehensive Testing

1. **Run Comprehensive Test**:

   ```
   GET /v2/admin/produkt-updates/comprehensive-production-test.php?password=...
   ```

2. **Test All Endpoints**:
   ```
   GET /v2/admin/produkt-updates/test-production-endpoints.php?password=...
   ```

## Rate Limiting

### Limits

- **Image Proxy**: 100 requests/minute per IP
- **Diagnostic Endpoints**: 10 requests/minute per IP
- **Migration Scripts**: 1 request/5 minutes per session

### Rate Limit Response

```json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded",
  "retry_after": 60
}
```

## Error Handling

### Common Errors

**401 Unauthorized**:

- Missing authentication
- Invalid password
- Session expired

**403 Forbidden**:

- IP whitelist restriction
- Token authentication failed

**429 Too Many Requests**:

- Rate limit exceeded
- Check `Retry-After` header

**500 Internal Server Error**:

- Server-side error
- Check error logs
- Review diagnostic output

## Best Practices

### 1. Use Password Parameter for Direct Access

When accessing diagnostic endpoints directly (not via admin panel), use password parameter:

```
?password=vXbTz6PqdY6UdexSxlp5
```

### 2. Check Storage Status Regularly

Run storage health check periodically to monitor system health:

```
GET /v2/api/produkt-updates-storage-health.php
```

### 3. Run Comprehensive Tests After Deployment

After deploying changes, run comprehensive test:

```
GET /v2/admin/produkt-updates/comprehensive-production-test.php?password=...
```

### 4. Monitor Diagnostic Output

Check diagnostic output for:

- Warnings about volatile storage
- Permission issues
- Missing files or directories
- Data inconsistencies

## Related Documentation

- [API Reference](./PRODUCT_UPDATES_API_REFERENCE.md) - Complete API documentation
- [Storage System](./PRODUCT_UPDATES_STORAGE.md) - Storage architecture
- [Troubleshooting Guide](./PRODUCT_UPDATES_TROUBLESHOOTING.md) - Common issues and solutions