QR-master/docs/automations/social-milestone-worker.md

Social milestone worker

The app detects QR-code scan milestones and stores customer consent. It does not hold X or LinkedIn credentials. An external X worker can use the internal queue after the test rollout is approved.

Test setup (manual SQL only)

1. Apply sql/2026-08-13_social_milestones.sql to qrmaster_test.
2. Set distinct CRON_SECRET and INTERNAL_API_SECRET values in .env.test. For an end-to-end test without 1,000 scans, also set SOCIAL_MILESTONE_THRESHOLDS=1 (or 1,2). Do not set this on production. Publishing is immediate after consent by default. Set SOCIAL_MILESTONE_POST_DELAY_HOURS=24 only if a revocation window is desired.
3. Deploy using the documented test compose command. CRON_SECRET is forwarded to the web service by docker-compose.yml.
4. Trigger detection manually:

curl -H "Authorization: Bearer $CRON_SECRET" \
  https://testmodul.qrmaster.net/api/cron/social-milestones

The detector creates records at 1,000 and 10,000 unique scans only. It is safe to call repeatedly because (qrId, kind) is unique.

X worker contract

After an explicit rollout approval, the existing QRMaster X worker may poll:

curl -H "Authorization: Bearer $INTERNAL_API_SECRET" \
  https://qrmaster.net/api/internal/social-milestones

It receives at most one approved item per 24 hours. The worker must post milestone.text without altering it, then report its result:

curl -X PATCH -H "Authorization: Bearer $INTERNAL_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"id":"<milestone-id>","result":"posted"}' \
  https://qrmaster.net/api/internal/social-milestones

Do not configure this worker against testmodul. LinkedIn has no approved brand-posting integration in this project. Customers can self-share: X opens a prefilled intent; the same text is copied for a LinkedIn post.