---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-19
name: User_Manual
status: active
tags:
- client/ford
- domain/devops
- status/active
- tech/python
- type/sop
type: sop
---

# Ford BnP QC System User Manual

## What This Tool Does
The Ford BnP (Build and Price) QC System is an automated quality control tool designed to validate automotive asset packs before they are deployed to customer-facing applications. It ensures that images, metadata, and configuration files meet strict Ford quality standards.

**Key Capabilities:**
*   **Automated Validation:** Runs 13 specialized checks on asset packs (MEC, BAU, Color Chips, Lifestyle, etc.) to detect errors in image format, metadata correctness, and business rules.
*   **Cloud Integration:** Automatically monitors a Box cloud folder for new `.zip` asset packs, downloads them, processes them, and uploads detailed HTML and JSON reports back to a designated Box folder.
*   **Detailed Reporting:** Generates rich, Bootstrap-styled HTML reports that clearly list issues found, their severity, and actionable steps to fix them. JSON reports are also generated for programmatic consumption.
*   **Error Recovery:** Includes robust error handling for network timeouts, file access issues, and QC failures, with automatic fallback mechanisms.

## Who Uses It
*   **Asset Managers & Creators:** Submitting new vehicle imagery or configuration data and needing confirmation that their uploads are valid.
*   **DevOps/IT Operations:** Monitoring the health and status of the asset upload pipeline via logs and Box folder contents.
*   **Developers/QA Engineers:** Debugging specific validation failures or adding new QC rules.

## How to Access
### Production Access (Automated Workflow)
For most users, interaction is indirect. You upload asset packs to a specific Box folder (`BOX_SOURCE_FOLDER_ID`), and the system processes them automatically.

*   **Source Folder (Upload Here):** `332861865120`
*   **Reports Folder (View Results Here):** `332864939558`
*   **Processed Folder (Archived Files):** `332861653811`

### Local/Development Access (Manual Workflow)
Developers and QA engineers can run the system locally to test changes or validate specific files.

**Prerequisites:**
1.  Python 3.8+
2.  A valid Ford Box JWT Configuration file (`ford_box_config.json`)
3.  The project codebase cloned.

## Main Workflows (Step-by-Step)

### Workflow 1: Manual QC Check (Local Development)
Use this to test a specific asset pack file locally.

1.  **Prepare your environment:**
    ```bash
    # Clone the repository
    git clone <repo_url>
    cd ford_qc_system

    # Set up virtual environment (recommended)
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
    pip install -r requirements.txt
    ```

2.  **Create a local configuration:**
    ```bash
    cp .env.example .env.dev
    # Edit .env.dev and ensure FORD_QC_ENV=development
    # You may not need Box credentials for local testing if not using Box, 
    # but BOX_CONFIG_FILE should still point to a valid (or dummy) file if required by imports.
    ```

3.  **Run the QC Engine:**
    ```bash
    # Basic usage with the default profile
    python qc_engine.py profiles/ford_bnp.json --input_file /path/to/your/asset_pack.zip --reports_dir ./local_reports
    ```

4.  **Review Results:**
    Check the `./local_reports` directory for `qc_report.html` and `qc_report.json`.

5.  **Generate a specific HTML report from existing JSON (Optional):**
    ```bash
    python -m checks.html_reporter ./local_reports/qc_report.json
    ```

### Workflow 2: Monitoring the Box Cloud Folder (Production/Dev Server)
The system runs as a background service to monitor Box.

1.  **Configuration:**
    Ensure `.env.prod` is correctly set up with:
    *   `FORD_QC_ENV=production`
    *   Correct `BOX_SOURCE_FOLDER_ID`, `BOX_REPORT_FOLDER_ID`, etc.
    *   Valid `BOX_CONFIG_FILE` path.

2.  **Start the Process:**
    ```bash
    python ford_qc_box_hotfolder_process.py
    ```
    *For systemd deployment, use the provided service file.*

3.  **Check Logs:**
    ```bash
    journalctl -u ford_qc_system -f
    ```

4.  **Monitor Box:**
    *   Upload `.zip` files to `BOX_SOURCE_FOLDER_ID`.
    *   Wait for processing.
    *   Check `BOX_REPORT_FOLDER_ID` for new HTML/JSON reports.
    *   Original `.zip` files are moved to `BOX_PROCESSED_FOLDER_ID`.

## FAQ

**Q: Where do I find the list of QC checks?**
A: The checks are defined in `profiles/ford_bnp.json`. Each entry specifies a script and configuration.

**Q: How do I fix a failed QC check?**
A: Open the generated HTML report in `BOX_REPORT_FOLDER_ID` or your local `reports_dir`. The report provides specific details and "Fix Instructions" for each error.

**Q: What if the Box API connection fails?**
A: The system includes retry logic (`MAX_RETRIES`, `RETRY_BACKOFF_BASE`). If it exceeds retries, it logs the error and moves the file to an error state (often a specific error report folder or leaving it in place with a logged error) depending on configuration. Check logs for details.

**Q: Can I add custom QC checks?**
A: Yes. The system is modular. Create a new Python script in the `checks/` directory, define it in `profiles/ford_bnp.json` with the appropriate `script` name and `config` parameters, and restart the service.

**Q: Where are the logs stored?**
A:
*   **Production:** Systemd Journal (`journalctl -u ford_qc_system`)
*   **Local/Dev:** Standard output or log files configured in the logging setup section of `ford_qc_box_hotfolder_process.py`.

## Related
- [[01 Projects/ford_qc/DEVELOPER_MANUAL]]
- [[01 Projects/ford_qc/DEVELOPER_MANUAL.md]]