Skip to content

Operations - Manual Operator Tools And Legacy Entrypoints

Overview

This document specifies legacy non-cron operational tooling that is currently used for manual interventions, wrappers, and maintenance procedures.

Checklist coverage: - OR-011 Manual tracking upload utility for invoices - OR-012 Manual single-order forward-to-Odoo utility (voerdoor) - OP-013 Shopupdating wrapper entrypoints for supplier/export jobs - OP-014 Manual maintenance scripts for 3D and image generation pipelines

Primary legacy evidence: - _shopupdating/upload-tracking.php - _shopupdating/upload-tracking.phtml - _core/model/classes/atx/orders/Tracking.php - _core/model/dbclasses/atx/invoices/InvoiceDAO.php - _shopupdating/voerdoor.php - src/Odoo/Service/UploadOrders.php - _shopupdating/index_checkAllLevs.php - _shopupdating/index_checkLevFile.php - _shopupdating/index_stockForExport.php - _shopupdating/maintenance/scan3d.php - _shopupdating/maintenance/scan3dScreenshots.php - _shopupdating/maintenance/scan3dWheels.php - _shopupdating/maintenance/renderNumberplates.php - _shopupdating/maintenance/renderAlcarWheels.php - _shopupdating/maintenance/createImages.php - _shopupdating/maintenance/copyupstepstooptions.php - _shopupdating/maintenance/getAllAccProperties.php

Legacy Capabilities (As-Is)

1. Manual Tracking Upload Utility (OR-011)

Entry point: - _shopupdating/upload-tracking.php + HTML form _shopupdating/upload-tracking.phtml.

Purpose: - Bulk upload parcel tracking values from CSV-like input into invoice package-link fields.

Flow: 1. Operator uploads a file and chooses delimiter, row offset, and column mappings. 2. Script validates each row: - minimum column count, - tracking number max length 16, - courier must contain DPD or GLS, - package position must be <= 20. 3. For valid rows, script builds Tracking objects and maps them to setPackageLink{position}. 4. Invoice tracking columns Packagelink1..Packagelink20 are updated via InvoiceDAO::updateTracking.

Notable behavior: - Invalid rows are skipped with inline output messages. - File is deleted (unlink) after processing.

2. Manual Single-Order Forward To Odoo (OR-012)

Entry point: - _shopupdating/voerdoor.php?order={orderId}.

Purpose: - Force upload of one order to Odoo middleware on demand.

Flow: 1. Validates query parameter order exists. 2. Bootstraps legacy runtime as updating user session. 3. Calls UploadOrders::uploadSingle(order). 4. Prints success/failure guidance as plain HTML text.

3. Wrapper Entrypoints For Cron Scripts (OP-013)

Entrypoints: - _shopupdating/index_checkAllLevs.php - _shopupdating/index_checkLevFile.php - _shopupdating/index_stockForExport.php

Purpose: - Thin wrapper aliases that simply include the underlying cron scripts.

Behavior: - No additional validation, locking, or auth layer. - Effective runtime behavior equals included cron script behavior.

4. Manual Maintenance Scripts (OP-014)

Core 3D/image maintenance scripts: - scan3d.php: scans 3D models with optional --new, --start, --startat, --count. - scan3dScreenshots.php: iterates processed models and regenerates screenshots. - scan3dWheels.php: scans/synchronizes 3D wheel assets. - renderNumberplates.php: bulk-renders numberplates for 3D models. - renderAlcarWheels.php: regenerates wheel images in batches via BatchImageService. - createImages.php: generates image variants/thumbnails/watermarks and writes JSON crop metadata.

Additional operator scripts in same maintenance surface: - copyupstepstooptions.php: copies upstep data into option data for a chassis. - getAllAccProperties.php: regenerates/refreshes accessory category property data.

Current Gaps And Risks To Resolve In Migration

  1. Most tools are file-based scripts with limited access control assumptions (typically internal-host trust).
  2. No standardized audit trail for who ran what, when, with which parameters.
  3. Error handling and output are ad-hoc (plain echoes/HTML), not structured logs.
  4. No consistent locking/idempotency guarantees for manual reruns.
  5. High-impact filesystem mutations (image pipelines) have no built-in dry-run mode.
  6. Wrapper entrypoints duplicate cron entry paths and increase accidental trigger surface.

Target Migration Specification (Symfony)

Scope

In-scope: - Replace manual scripts with controlled Symfony commands and/or admin jobs. - Preserve all required operator capabilities currently used in practice. - Centralize logging, permission checks, and execution audit metadata.

Out-of-scope: - Rebuilding image processing algorithms themselves (separate technical stream).

Required Operating Rules

  1. No direct HTTP script execution for operator jobs in the target architecture.
  2. Every operator action must require authenticated staff identity and authorization policy.
  3. Every run must emit structured logs with:
  4. command name,
  5. actor,
  6. parameters,
  7. start/end timestamps,
  8. success/failure status.
  9. High-impact commands must support --dry-run when feasible.
  10. Commands must be idempotent or explicitly document non-idempotent behavior.

Proposed Command Map

Legacy Capability Proposed Command Owner Notes
Tracking upload ops:invoices:import-tracking Webshop + Ops Accept CSV mapping args, validate, and produce run report.
Single order force upload ops:orders:push-odoo --order={id} ERP Middleware + Webshop Enforce permission and write result/event log.
Cron wrappers Removed (replaced by scheduler commands only) Shared Ops No direct wrapper endpoint in target.
3D model scan ops:3d:scan-models Vehicle Data Preserve scoped options (--new, --start, etc.).
3D screenshots ops:3d:render-screenshots Vehicle Data Batch execution with resumable cursor.
3D wheel scan ops:3d:scan-wheels Vehicle Data Maintain current sync semantics.
Numberplate render ops:3d:render-numberplates Vehicle Data Queue-based execution preferred.
Wheel image render ops:images:render-wheel-batch Webshop Admin Batch + checkpointing.
Generic image generation ops:images:generate-variants Webshop Admin Replace hardcoded path filters with typed options.
Upsteps to options ops:vehicles:copy-upsteps --chassis={id} Vehicle Data Keep chassis-scoped execution.
Accessory properties refresh ops:accessories:refresh-properties Webshop Admin Deterministic rerun behavior.

Data And Migration Notes

  1. Capture and document all currently used operational scripts before cutover, including call frequency and owners.
  2. Preserve CSV column mapping flexibility for tracking import to avoid blocking operations.
  3. Replace plain-text operator feedback with run summaries persisted in logs and/or admin activity tables.
  4. For image and 3D tasks, add checkpointing to resume long jobs safely.

Acceptance Scenarios (Gherkin)

Feature: Manual operator tooling replacement

  Scenario: Staff imports tracking file safely
    Given a staff user with operations permission
    When they run tracking import with a valid CSV file
    Then invoice package links should be updated for valid rows
    And invalid rows should be reported without aborting the full run

  Scenario: Force push a single order to Odoo
    Given a staff user with ERP operations permission
    When they run order push for order 12345
    Then one upload attempt should be executed for order 12345
    And the run result should be audit logged

  Scenario: Wrapper endpoints are removed
    Given the Symfony migration is active
    When someone attempts to call legacy wrapper entrypoints
    Then the call path should not exist in production
    And scheduler should invoke commands directly

  Scenario: 3D maintenance jobs are resumable
    Given a long-running 3D screenshot batch job fails mid-run
    When the operator restarts with resume parameters
    Then processing should continue from a safe checkpoint

  Scenario: Image generation supports dry-run
    Given a staff user wants to preview impact of image regeneration
    When they execute the command with --dry-run
    Then no files should be modified
    And the command should report planned changes

Open Decisions

  1. Which operator tooling should be exposed in admin UI versus CLI-only.
  2. Whether tracking import remains a manual operation or moves to integration-level automation.
  3. Whether legacy direct filesystem image writes are replaced with object storage + worker pipelines.
  4. Which scripts can be retired after confirming no operational usage in the last 6-12 months.