hm_ai_qc_report_tool/MIGRATION_GUIDE.md

Migration Guide: Legacy Tools to Unified Platform

This guide documents how the standalone QC tools were consolidated into the unified HM QC Platform (v1.0.0).

What Was Consolidated

Source	Destination	Status
hm_qc/ (standalone CLI tool)	modules/hm_qc/	Complete
hm_qc_video/hm_video_ai_qc_tool/	modules/video_qc/	Complete
Reporting Dashboard (in this repo)	modules/reporting/	Complete
Test files, results, cheat sheets	reference/ (gitignored)	Complete
Censorship training images	data/supporting/censorship_trainset/ (gitignored)	Complete

File Mapping: hm_qc (Image/PDF QC)

Checks

Original Path	New Path
hm_qc/checks/HM_parse.py	modules/hm_qc/checks/legacy/HM_parse.py
hm_qc/checks/HM_filename_parse.py	modules/hm_qc/checks/legacy/HM_filename_parse.py
hm_qc/checks/HM_imprint_check.py	modules/hm_qc/checks/legacy/HM_imprint_check.py
hm_qc/checks/HM_language_validate.py	modules/hm_qc/checks/legacy/HM_language_validate.py
hm_qc/checks/HM_price_currency_check.py	modules/hm_qc/checks/legacy/HM_price_currency_check.py
hm_qc/checks/HM_censorship.py	modules/hm_qc/checks/legacy/HM_censorship.py
hm_qc/checks/HM_image_parse.py	modules/hm_qc/checks/legacy/HM_image_parse.py
hm_qc/checks/HM_image_filename_parse.py	modules/hm_qc/checks/legacy/HM_image_filename_parse.py
hm_qc/checks/HM_image_dimension_check.py	modules/hm_qc/checks/legacy/HM_image_dimension_check.py
hm_qc/checks/html_reporter.py	modules/hm_qc/checks/legacy/html_reporter.py
hm_qc/checks/analyze_with_gpt.py	modules/hm_qc/checks/legacy/analyze_with_gpt.py
hm_qc/checks/unzip_and_verify_check.py	modules/hm_qc/checks/legacy/ford/unzip_and_verify_check.py
hm_qc/checks/image_resolution_check.py	modules/hm_qc/checks/legacy/ford/image_resolution_check.py
hm_qc/checks/file_size_check.py	modules/hm_qc/checks/legacy/ford/file_size_check.py
hm_qc/checks/colour_existence_check.py	modules/hm_qc/checks/legacy/ford/colour_existence_check.py
hm_qc/checks/image_linking_check.py	modules/hm_qc/checks/legacy/ford/image_linking_check.py
hm_qc/checks/missing_images_check.py	modules/hm_qc/checks/legacy/ford/missing_images_check.py
hm_qc/checks/special_requirements_mec_bau.py	modules/hm_qc/checks/legacy/ford/special_requirements_mec_bau.py
hm_qc/checks/business_data_check.py	modules/hm_qc/checks/legacy/ford/business_data_check.py

Other Files

Original Path	New Path
hm_qc/qc_module.py	modules/hm_qc/legacy_orchestrator.py
hm_qc/config.py	modules/hm_qc/legacy_config.py
hm_qc/profiles/*.json	modules/hm_qc/profiles/legacy/
hm_qc/launchers/*.py	modules/hm_qc/launchers/
hm_qc/utils/*	modules/hm_qc/utils/
hm_qc/supporting/censorship_trainset/	data/supporting/censorship_trainset/
hm_qc/README.md	modules/hm_qc/legacy_README.md
hm_qc/DEV_SETUP.md	modules/hm_qc/legacy_DEV_SETUP.md
hm_qc/CLAUDE.md	modules/hm_qc/legacy_CLAUDE.md

File Mapping: hm_qc_video (Video QC)

Checks

Original Path	New Path
hm_video_ai_qc_tool/checks/video_parse.py	modules/video_qc/checks/legacy/video_parse.py
hm_video_ai_qc_tool/checks/video_filename_parse.py	modules/video_qc/checks/legacy/video_filename_parse.py
hm_video_ai_qc_tool/checks/video_technical_check.py	modules/video_qc/checks/legacy/video_technical_check.py
hm_video_ai_qc_tool/checks/video_dimension_check.py	modules/video_qc/checks/legacy/video_dimension_check.py
hm_video_ai_qc_tool/checks/video_duration_check.py	modules/video_qc/checks/legacy/video_duration_check.py
hm_video_ai_qc_tool/checks/video_censorship.py	modules/video_qc/checks/legacy/video_censorship.py
hm_video_ai_qc_tool/checks/analyze_with_gpt.py	modules/video_qc/checks/legacy/analyze_with_gpt.py

Other Files

Original Path	New Path
hm_video_ai_qc_tool/qc_module.py	modules/video_qc/legacy_orchestrator.py
hm_video_ai_qc_tool/config.py	modules/video_qc/legacy_config.py
hm_video_ai_qc_tool/profiles/HM_video.json	modules/video_qc/profiles/legacy/HM_video.json
hm_video_ai_qc_tool/launchers/*.py	modules/video_qc/launchers/
hm_video_ai_qc_tool/utils/*.py	modules/video_qc/utils/
hm_video_ai_qc_tool/web/ (entire app)	modules/video_qc/legacy_web/
hm_video_ai_qc_tool/README.md	modules/video_qc/legacy_README.md

Architecture: Legacy vs New

Legacy Check Pattern (checks/legacy/)

def run_check(config, context, check_id):
    """Each check is a function that receives config, context, and check_id."""
    results = []
    # ... perform check ...
    results.append({"status": "pass", "message": "..."})
    return results

New Check Pattern (checks/)

class MyCheck(BaseCheck):
    """Each check is a class that inherits from BaseCheck."""
    name = "my_check"

    def execute(self, file_path, profile):
        # ... perform check ...
        return CheckResult(score=95, issues=[])

Profile Mapping

Legacy (JSON)	New (YAML)
profiles/legacy/HM.json	profiles/profiles.yaml (HM section)
profiles/legacy/HM_image.json	profiles/profiles.yaml (HM Image section)
profiles/legacy/ford_bnp.json	profiles/profiles.yaml (Ford section)
profiles/legacy/HM_video.json	modules/video_qc/profiles/profiles.yaml

What Was NOT Copied

The following were intentionally excluded from the consolidation:

• .git/ directories (separate repo histories)
• venv/ directories (virtual environments)
• __pycache__/ directories
• .DS_Store files
• .claude/ directories (Claude Code settings)
• reports/ and tmp/ (working data)
• web/uploads/ from video tool (uploaded test videos)
• .env files (contain secrets)

Backup

A full backup of the original HM_QC_Bitbucket/ directory (including all .git histories) was created before consolidation:

~/Desktop/HM_QC_Bitbucket_backup_20260225_113155.tar.gz (3.5 GB)

---

Reporting Module: Box Folder Migration (v2.0 to v2.1)

The Reporting module underwent its own migration when the Box.com folder structure changed. Key details:

• Old folder ID: 303321539397 (flat structure)
• New folder ID: 133295752718 (CAMPAIGNS/{CampaignNumber}/QC/ hierarchy)
• Environment variable: BOX_REPORT_FOLDER_ID=133295752718
• Service account: AutomationUser_2239684_XmNAVhQUsB@boxdevedition.com needs access to CAMPAIGNS folder