ford_qc/documentation/05-reporting.md

Reports & Output

Report Types

The system produces two types of reports:

Report	Generator	When
QC Report	checks/html_reporter.py	After successful QC processing
Error Report	checks/html_error_reporter.py	When processing fails at any stage

JSON Results Structure

Before HTML generation, QC results are stored as JSON. This is the intermediate format between the check pipeline and the HTML reporter.

Top-Level Schema

{
    "profile": "ford_bnp_temp.json",
    "timestamp": "2025-11-07T16:45:42.017547Z",
    "checks": [
        {
            "index": 1,
            "script": "checks.unzip_and_verify_check",
            "config": { "working_dir": "/path/to/working", ... },
            "result": {
                "status": "passed",
                "details": { ... }
            }
        }
    ]
}

Per-Check Result Schema

Every check result has:

Field	Type	Description
status	string	"passed", "failed", "error", or "skipped"
details	object	Check-specific details (varies by check)
error_message	string	Present only on "error" status

Common detail fields across checks:

Field	Found In	Description
message	All checks	Human-readable summary
pack_type	Resolution, format, size	"MEC" or "BAU"
failed_images	Resolution, format	List of images that failed validation
missing_files	Colour, missing images	List of files not found on disk
skipped_types	Many checks	ViewType/ImageType combinations the check didn't have rules for
advisory_warnings	File size	Files slightly over limit (101-125%)
size_violations	File size	Files significantly over limit (126%+)

HTML QC Report

Generation

from checks.html_reporter import HTMLReporter

report_path = HTMLReporter.generate_report(
    json_data=qc_results_dict,
    reports_dir="reports/",
    input_filename="asset_pack.zip"
)

Or via CLI:

python -m checks.html_reporter reports/20251107_164544/qc_results.json reports/

Output Filename

{input_filename}_{ISO_timestamp}_QC.html

Example: pv_waedx_cgw07_yyi_24072024_1530_image_2025-11-07T164544_QC.html

Report Layout

flowchart TD
    A[Header: filename, profile, timestamp] --> B[Summary Panel]
    B --> C[Error/Failed Checks - expanded by default]
    C --> D[Skipped Checks - collapsed]
    D --> E[Passed Checks - collapsed]

The report uses Bootstrap 5.1.3 with accordion components. Checks are grouped by status:

Group	Color	Default State
Failed / Error	Red badge	Expanded
Skipped	Yellow badge	Collapsed
Passed	Green badge	Collapsed

Check Name Display

Module paths are converted to friendly names in the report:

Module Path	Display Name
checks.unzip_and_verify_check	Archive Extraction Verification
checks.colour_existence_check	Color Chips Verification
checks.missing_images_check	Missing Images Check
checks.image_resolution_check	Image Resolution Validation
checks.image_format_check	Image Format Validation
checks.file_size_check	File Size Validation
checks.special_requirements_mec_bau	MEC/BAU Special Requirements
checks.mec_powertrain_validation	MEC Powertrain Validation
checks.lifestyle_inventory_validation	Lifestyle & Inventory Validation
checks.image_linking_check	Image Link References Check
checks.layer_depth_check	Layer Depth Validation

Checks not in this map get their module name auto-formatted (underscores replaced with spaces, title-cased).

Detail Rendering

The HTML reporter has specialized rendering for each check's detail fields:

• Skipped types → Table with viewtype/imagetype columns
• Unauthorized file types / case violations → Tables with file paths and locations
• Extraneous files → Table with paths and file sizes
• Missing files → Grouped by directory with sub-accordions
• Resolution failures → Tabbed view: grouped by resolution mismatch OR by image type
• Format failures → Tabbed view: grouped by format mismatch OR by image type
• Size failures → Tabbed view: grouped by severity (% over), asset type, OR directory
• Layer failures → Grouped by issue type and image type
• Unreferenced files → Grouped by directory and file extension
• Extra carousel → Per-record coverage with passed/failed breakdown, missing WERS codes listed

HTML Error Report

When It's Generated

Error reports are generated when processing fails at any stage — before, during, or after QC checks. Each error report includes actionable fix instructions for the end user.

Generation

from checks.html_error_reporter import HTMLErrorReporter

report_path = HTMLErrorReporter.generate_error_report(
    error_type='zip_extraction',
    error_message='Failed to extract ZIP file',
    filename='asset_pack.zip',
    reports_dir='reports/',
    error_details={'file_size': 12345},
    exception_info=traceback.format_exc()
)

Convenience functions are also available:

from checks.html_error_reporter import (
    generate_zip_error_report,
    generate_json_error_report,
    generate_file_access_error_report,
    generate_qc_check_error_report,
    generate_network_error_report
)

Or via CLI:

python -m checks.html_error_reporter zip_extraction corrupted_file.zip reports/

Output Filename

{input_filename}_{ISO_timestamp}_ERROR.html

Error Types

Error Type	Trigger	User Fix Instructions
zip_extraction	ZIP file is corrupted or can't be extracted	Re-create ZIP, verify compression, test locally
json_parsing	linkingrecord.json has syntax errors	Use a JSON validator, check for common syntax issues
file_access	File permission or existence issues	Verify file permissions and existence
qc_profile	QC profile configuration error	Contact support (system configuration issue)
check_execution	A QC check raised an unhandled exception	Review asset pack contents, validate file structure
network_upload	Box API or network connectivity failure	Check connectivity, verify upload service
unknown	Any unexpected error	Try again, verify ZIP integrity, contact support

Error Report Layout

The report includes:

1. Red gradient header with error icon
2. Alert banner with the error message
3. Two-column body:
   • Left: "How to Fix This Issue" — error-type-specific step-by-step instructions
   • Right: "Re-upload Instructions" — guidance on resubmitting
4. Technical Details accordion (collapsed) — error type badge, file info, timestamp, exception traceback
5. "Need Help?" footer — support guidance

Fallback

If HTML generation itself fails, the reporter falls back to a plain text error report (.txt extension) with basic error details.

Report Destinations

Mode	QC Reports	Error Reports
CLI	reports/YYYYMMDD_HHMMSS/qc_results.json (JSON only by default)	reports/ directory
Box Hotfolder	Uploaded to BOX_REPORT_FOLDER_ID (both JSON and HTML)	Uploaded to BOX_REPORT_FOLDER_ID

In the Box hotfolder flow, local report files are cleaned up after successful upload.