Oliver/hm_ai_qc_report_tool
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hm_ai_qc_report_tool/MIGRATION_GUIDE.md
nickviljoen 35a15bfe09 Update documentation for unified platform consolidation 
- Rewrite CHANGELOG.md to cover platform v1.0.0 and auth fix,
  with reporting module history preserved as subsection
- Replace stale DOCUMENTATION_SUMMARY.txt with current project
  structure and key decisions
- Rewrite MIGRATION_GUIDE.md to document legacy tool consolidation
  with complete file mappings for hm_qc and video_qc
- Add legacy context headers to module docs (legacy_README,
  legacy_DEV_SETUP, legacy_CLAUDE) pointing to main README

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-25 13:51:21 +02:00

137 lines
6.7 KiB
Markdown
Raw Permalink Blame History

# 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/`)
```python
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/`)
```python
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
Reference in a new issue View git blame Copy permalink