Samsung Daily Sync

Status

Operational procedure for BC-047.

Purpose

This procedure activates one durable Samsung merchant-feed synchronization per day without introducing business logic into the scheduler.

The scheduler calls the canonical WP-CLI entry point. The existing Sync Runner remains responsible for ingestion, Stage persistence, classification, projection, locking, retries, metrics and spool cleanup.

Architecture

systemd timer
    ↓
ccx-samsung-sync.service
    ↓
docker exec ccx-platform-worker
    ↓
wp ccx sync start --feed=samsung
    ↓
CCX Sync Runner

The timer MUST NOT download the feed directly and MUST NOT write to the database.

Runtime contract

Project path:

/mnt/data/cmonchoix-platform

WordPress container:

ccx-platform-worker

Canonical command:

docker exec -i ccx-platform-worker \
  wp --allow-root --path=/var/www/html \
  ccx sync start --feed=samsung

Do not pass --force from the scheduled service. Without --force, the API resumes an existing resumable Samsung run before creating a new run. Feed locks prevent concurrent Samsung executions.

Schedule

The versioned timer runs daily at 03:15 UTC with a randomized delay of up to ten minutes.

OnCalendar=*-*-* 03:15:00 UTC
Persistent=true
RandomizedDelaySec=10m

Persistent=true catches up a missed execution after a server restart.

Installation

The files in operations/systemd/ are the source of truth. Install copies into systemd; do not edit installed units as the canonical source.

cd /mnt/data/cmonchoix-platform || exit 1

sudo install -m 0644 operations/systemd/ccx-samsung-sync.service /etc/systemd/system/
sudo install -m 0644 operations/systemd/ccx-samsung-sync.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now ccx-samsung-sync.timer

Validation

Validate the unit definitions before enabling them:

systemd-analyze verify \
  operations/systemd/ccx-samsung-sync.service \
  operations/systemd/ccx-samsung-sync.timer

Check the timer:

systemctl list-timers ccx-samsung-sync.timer --all
systemctl status ccx-samsung-sync.timer --no-pager

Run one controlled execution:

sudo systemctl start ccx-samsung-sync.service
sudo systemctl status ccx-samsung-sync.service --no-pager
journalctl -u ccx-samsung-sync.service -n 100 --no-pager

Confirm the latest Samsung run through the official CLI:

docker exec -i ccx-platform-worker \
  wp --allow-root --path=/var/www/html \
  ccx sync status --feed=samsung --limit=1

A valid run has status=success, zero error_rows, no active residual lock and a completed ingestion.

Failure handling

The service retries a failed process up to three times within thirty minutes. The Sync Runner remains authoritative for run state and lock handling.

Operational diagnosis:

docker exec -i ccx-platform-worker \
  wp --allow-root --path=/var/www/html \
  ccx sync doctor --feed=samsung

General maintenance and resumable-run recovery remain available through:

docker exec -i ccx-platform-worker \
  wp --allow-root --path=/var/www/html \
  ccx sync tick

tick does not create a new scheduled feed run. It performs maintenance and resumes existing resumable runs.

Rollback

Disable and remove the scheduler without touching feed data or the Sync Runner:

sudo systemctl disable --now ccx-samsung-sync.timer
sudo rm -f /etc/systemd/system/ccx-samsung-sync.timer
sudo rm -f /etc/systemd/system/ccx-samsung-sync.service
sudo systemctl daemon-reload
sudo systemctl reset-failed

Security

Merchant source URLs may contain credentials. Operator-facing Sync Runner results redact sensitive URL path segments, query parameters and explicit secret fields. Secrets remain available only to the internal runtime context required for ingestion and recovery.

The AWIN credential must never be committed to Git, copied into unit files or placed in documentation.