@bytebrand/export-cars 1.26.47 → 1.26.48

package/docs/meinestadt/TRACKING.md

@@ -0,0 +1,107 @@
+# meinestadt.de — measurement design (ADV-327)
+
+Status 13.11.2026: DEV only. Implemented: the listing link (export-cars 1.26.44), the reporting channel
+`CLASSIFIEDS_MEINESTADT` (web-funnel-tracking-health 1.5.5) and the lead source for the VDP enquiry
+(user-actions-contact, ADV-327 fix). Not implemented, by design, until meinestadt confirms a path in
+writing: partner click ids, postbacks / pixels, the daily report import. No production switch.
+
+## 1. Evidence
+
+| Source | Link parameters | Note |
+|---|---|---|
+| Original 32-field workbook (tab `meinestadt`) | `source=meineStadt&medium=cpc&campaign=listing` | historic |
+| export-cars ≤ 1.26.43 / Confluence | `source=classifieds&medium=listing&campaign=meinestadt` | partner only in `campaign` |
+| export-cars ≥ 1.26.44 (current DEV) | `source=meinestadt&medium=listing&campaign=listing` + identical `utm_source/utm_medium/utm_campaign` | partner in `source`; no paid medium |
+
+- ADV-260: fe-main stores `source / medium / campaign / utm_*` + click ids in the `marketing` cookie
+  (`CommonUtils.ts` `MARKETING_PARAM_REGISTRY`, merge per key, 24 h) and the first landing URL / external
+  referrer in `landing_context` (first wins). car-basic-data (VDP), car-search-endpoint (SRL),
+  user-actions-contact (forms, checkout) read both cookies server-side into the BigQuery event rows.
+- Before 1.5.5 every variant fell into generic rules: the workbook variant (`medium=cpc`) as `PAID_OTHER`,
+  the legacy variant as `UNRESOLVED` (`medium=listing` is unmapped). Partner identity was lost.
+- Before the ADV-327 fix the VDP enquiry "Frage zum Fahrzeug" (`VehicleDetailedNextPage.onEnquirySubmit`)
+  sent no `marketing` object, and user-actions-contact built the Odoo message only from the body, so
+  those REQs reached Odoo without utm source / medium / campaign. DEV 09.11.2026, same visit with a
+  Criteo cookie: enquiry → source "(nicht bekannt)", offer request → `criteo / cpc / retargeting`.
+  This affected every channel, not only meinestadt.
+- No meinestadt click id, postback, pixel or reporting API is known. Daily e-mails from
+  auto@meinestadt.de with `meinestadt-daily_reporting_AUTODE_<date>.csv` existed historically; no file was
+  available for this ticket, so its schema is not verified.
+
+## 2. Path
+
+```
+meinestadt listing ──listingUrl──► https://www.auto.de/search/vehicle/<car _id>?source=meinestadt&medium=listing&campaign=listing&utm_*=…
+  → fe-main: marketing cookie + landing_context (ADV-260)        raw values unchanged in every event row
+  → views: reporting_channel CLASSIFIEDS_MEINESTADT, family Classifieds, detail meinestadt.de, publisher MEINESTADT
+  → form (VDP enquiry / offer request / checkout) → REQ → Odoo utm source "meinestadt"   (body marketing, or the cookie)
+  → fact_lead.crm_source → source_resolved_v1 = 'meinestadt' (customer SQL, no change needed for the new link)
+  → rpt_episode_touchpoint → canonical 90-day intent episode (original episode_start_date) → fact_sale / CM
+```
+
+- Grain: VISITOR session (traffic_class VISITOR; KNOWN_CRAWLER / BOT_SUSPECT rules run before attribution).
+- Raw vs normalized: `source / medium / campaign / utm_*` stay as received in the event rows and in Odoo;
+  the channel is derived in the views. Historical rows are not rewritten — the views classify at query
+  time, the producer label (`resolved_channel`, message-schemes) is untouched.
+- Rule (web-funnel-tracking-health `MEINESTADT_UTM`): `source` (legacy or utm, lower-cased) in
+  `meinestadt` / `meinstadt`, or `source = classifieds` and `campaign` in `meinestadt` / `meinstadt`; any
+  medium; after the click-id rules (a Google click id wins), before the paid UTM rules; not `PAID_*`, so
+  the paid click-id health rates are unaffected (paid / free is a contract attribute).
+- Listing-level join without a partner id: feed `listingUrl` car `_id` = VDP id = lead car id.
+- Click reconciliation: platform `meinestadt` in `buildClickReconciliationView`, aggregate only (no click
+  id). Used only once `fact_marketing_media` holds meinestadt rows. No artificial 1:1 mapping.
+- Off-site leads (phone, partner-hosted forms) never create a website session.
+- Consent: the cookie capture is first-party and not consent-gated today (open compliance question noted
+  in fe-main `CookieUtils.getConsentState`); every event row carries `marketingConsent` /
+  `analyticsConsent` from the request headers. Nothing is sent to meinestadt (no pixel / postback).
+  Finance / bank data never leaves auto.de.
+
+## 3. Episodes and sales (customer SQL, prod-only, not applied)
+
+- New link: `crm_source = meinestadt` → `source_resolved_v1/v2 = 'meinestadt'` with the existing rules.
+- Legacy link (`classifieds` + campaign `meinestadt`): resolves to `classifieds` today; proposal D-rule
+  `source_resolved_v2 = 'meinestadt'`, method `PARTNER_PARAM_EXACT` (raw values kept). File:
+  `release-runbooks/adv-327/ADV-327-customer-sql-proposal.sql`.
+- Same person within a fixed 90-day episode → no new acquisition (`rpt_customer_intent_episode`).
+  Sales: distinct `fact_sale` ids per episode, cohort = `episode_start_date`, `sales_reported_at` separate.
+
+## 4. Costs (blocked on the real report and a contract)
+
+- Target: the existing `fact_marketing_media` / `fact_marketing_cost` (no new table, no data mart).
+  `source_system = meinestadt_daily_report`, `channel = meinestadt`, report date (partner timezone →
+  Europe/Berlin), billable / non-billable clicks, spend, currency, credits as negative rows, invoice
+  number, contract version, file name + SHA-256 for idempotent upsert and correction replay, status
+  `actual` / `estimated` / `missing` per day.
+- The feed field `cpc` is a bid / configuration value, never actual cost; no cost from the historic 0.08.
+- `rpt_lead_cost_live.paid_channel_v3` gets `meinestadt` only while a CPC contract is effective.
+- The parser is written against a real CSV only (separator, encoding, decimal comma, timezone, columns).
+
+## 5. QA (DEV)
+
+| Case | Expected | Status |
+|---|---|---|
+| new link, legacy link, workbook link (`meineStadt` + `cpc`) | CLASSIFIEDS_MEINESTADT event + session | ✅ 12.11 real DEV requests + unit tests |
+| other classifieds campaign | not meinestadt | ✅ control → UNRESOLVED |
+| Google click id + meinestadt utm | click id wins | ✅ rule order test |
+| raw values kept | event rows hold `meineStadt` / `classifieds` as sent | ✅ BQ |
+| fe-main capture of the link | cookie = link parameters, no parameterConflict | ✅ fe-main function run on the URLs |
+| health metrics | Classifieds in `channel_family_share`, 0 WARN | ✅ day run 12.11 |
+| VDP enquiry → REQ → Odoo source (no body marketing, cookie only) | utm source from the cookie | ✅ 13.11 DEV: REQ584784 `meinestadt / listing / listing`, REQ584783 `classifieds / listing / meinestadt` (raw); sessions CLASSIFIEDS_MEINESTADT, `develop_web_journey_lead_v1` CONFIRMED |
+| offer request with body marketing | unchanged (body wins) | ✅ unit test |
+| no consent | capture unchanged, consent flag on rows | documented, not changed |
+| bot | KNOWN_CRAWLER / BOT_SUSPECT, not counted | existing rules |
+| new / repeat episode, 2 sales, CSV replay / credit / no-report day, DST | — | prod customer SQL / blocked on CSV |
+
+Note: Odoo `cookieid` is filled only for signed-in senders (user-actions-contact, unchanged); the website
+session ↔ REQ link is `lead_funnel_event` (session id + Pub/Sub messageId → REQ), as for every form.
+
+## 6. Launch blockers
+
+Contract with auto.de GmbH, partner spec and approval of the link parameters, real daily CSV + field
+definitions, legal / privacy sign-off, customer-SQL owner OK, feed and image acceptance (ADV-325/326).
+
+## 7. Rollback
+
+- Link: export-cars ≤ 1.26.43 (dry-run feed only, nothing published).
+- Channel: web-funnel-tracking-health 1.5.4 + view rebuild (event `emubc2hjemu`).
+- Lead source fallback: revert the user-actions-contact commit and rebuild the service.

package/docs/ooyyo/AUDIT.md

@@ -0,0 +1,81 @@
+# OOYYO feed — audit and contract (ADV-331)
+
+Status 13.11.2026: DEV only, dry-run by default. Nothing is hosted, sent or submitted; OOYYO's
+crawler is not enabled. Export type `ooyyo`, export-cars ≥ 1.26.48.
+
+## Sources
+
+| What | Where |
+|---|---|
+| Official XSD / XML template | `test/fixtures/ooyyo/OoyyoFormat.{xsd,xml}` — downloaded 13.11.2026 from the links on ooyyo.com/c=CDA31D7114F5854F111BFE6F9D671453 (d10y2oj5s0rxih.cloudfront.net/ooyyo_format/), 4,883 / 5,595 bytes = the attachments of Aleksandar Ciric's mail of 16.10.2026. sha256 xsd `58947bf2…ac07c3`, xml `08b3e74a…adefd` |
+| Importer rules (binding) | Aleksandar Ciric (OOYYO), 16.10. and 19.10.2026, quoted in ADV-331 / ADV-333 |
+| Legacy exporter | `OoyyoExporter` / `OoyyoTransformer` / `OoyyoXmlBuilder` before 1.26.48; DEV Cronicle `6.0 Export Ooyyo - part 1` (ejtpmrpb002) → `6.1 … part 2` (ejtpmsrmw03, shell `ftp put` of `autode-ooyyo.tar.gz` to the legacy Jelastic FTP) |
+
+## What the XSD does and does not enforce
+
+`<ooyyo>` = `xsd:choice minOccurs=0 maxOccurs=unbounded` of `<ad>`; `<ad>` = choice of 25 optional
+elements; all values `xsd:string`; `price`, `engine_size`, `mileage`, `power` need a `unit` attribute
+(any string). So the XSD accepts an empty file, an ad without price / photo / year, and `unit="euro"`.
+The partner's real acceptance rules are therefore implemented separately (`validateOoyyoItem`) and
+applied twice: to every item before it is written and to the finished file when it is read back
+(`verifyOoyyoXml`). The test suite re-derives the element names and required-unit list from the XSD
+file, so a schema change fails the build.
+
+## Partner acceptance rules (19.10.2026) → implementation
+
+| Rule | Implementation |
+|---|---|
+| `<price unit="EUR">` exactly; missing / other unit = rejected | builder writes `unit="EUR"`; verifier allows only `EUR` |
+| price = integer vehicle purchase price | `price.currentSalesPrice` only, whole euros; never `rate.*` (leasing) or `price.purchasePrice` (dealer cost) |
+| rejected without photo | ≥ 1 validated clean photo (ADV-336 selection: 3/4 hero first, URL check), else `no_valid_image` |
+| rejected without year | first-registration year, else stored construction year; nothing defaulted, else `no_valid_year` |
+| rejected when make / model not recognisable | empty / `SONSTIGE` / `Andere` / `selector_unknown` … → `no_make` / `no_recognisable_model` |
+| vehicle URL and picture URLs ≤ 1,500 chars, HTTPS | `url_too_long` / `no_valid_image`; all URLs `https://` |
+| partly valid file REPLACES the whole OOYYO inventory | FeedGuard (complete + fresh snapshot, min / drop vs last good, lock) + read-back verify of every ad + count equality; temp → atomic rename; blocked run keeps the last good `.xml` / `.xml.gz` and exits 1 |
+| download failure / 0 readable ads: OOYYO keeps old inventory | not relied upon — an empty file is never published (`published_too_small`) |
+| one XML at a fixed HTTPS URL, plain or gzip ending `.gz`, FTP discouraged | outputs `ooyyo.xml` + `ooyyo.xml.gz` (real gzip of the XML, round-trip checked); the legacy `autode-ooyyo.tar.gz` (tar, FTP) is no longer produced. Hosting is NOT set up |
+
+## Field mapping (source → XML)
+
+| Element | Source | Rule |
+|---|---|---|
+| `url` | `_id` | `https://www.<domain>/search/vehicle/<id>?source=ooyyo&medium=listing&campaign=listing&utm_source=ooyyo&utm_medium=listing&utm_campaign=listing` (ADV-333) |
+| `title` | `mainData.make model subModel` | German, missing parts left out (legacy prefixed `constructionYear`, also for used cars) |
+| `content` | `offer.offerDescription` | plain text: mobile.de `\\` → line break, `**` dropped; nothing added; empty → left out |
+| `price unit="EUR"` | `price.currentSalesPrice` | integer > 0 |
+| `make` / `model` / `trim` | `mainData.make` / `model` / `subModel` | as stored |
+| `engine_size unit="cc"` | `engineData.cubicCapacity` | > 0 else left out (BEV) |
+| `body_type` / `color` / `fuel_type` / `transmission` | selectors | German labels (`de` dictionary), `Außenfarbe ` prefix removed, unknown → left out |
+| `year` | `mainData.firstRegistration` / `constructionYear` | see rules |
+| `mileage unit="km"` | `mainData.mileage` | ≥ 0 (0 for new cars is real) |
+| `euronorm` | `environmentEmissions.emissionClass` | `1`…`6`, `6b`, `6c`, `6d`, `6d-TEMP` (legacy values); unknown left out (legacy wrote `default`) |
+| `power unit="kw"` | `engineData.powerKW` | > 0 |
+| `doors` / `seats` / `gears` | `mainData.doors` / `seats`, `driveSuspension.gears` | > 0 |
+| `location/city` | `location.city` | as stored |
+| `location/postcode` | `location.zipCode` | STRING; DE 4-digit → leading zero restored (`4103` → `04103`); invalid → left out |
+| `location/region` | postal code table (`DePostalCodesService`) | Bundesland of the postcode (legacy wrote the country code `DE`) |
+| `pictures/picture` | Imbo images | validated clean list, hero first, no cap (20 is a ranking recommendation), never `noimage` |
+| `vin` | `metaData.vin` | only a valid ISO 3779 VIN |
+| `is_new` | `mainData.condition` | `1` new, `0` used |
+| `date` / `time` | `metaData.creationDate` | `DD/MM/YYYY` / `HH:MM` 24 h, Europe/Berlin (legacy `hh:mm:ss`, 12 h, host TZ) |
+
+Empty optional elements are left out entirely (all are optional in the XSD); the legacy builder wrote
+`<engine_size/>` / `<power/>` without the required `unit`, which made the file schema-invalid.
+Values are CDATA-wrapped as in the template; `]]>` is split, XML-invalid control characters removed.
+
+Excluded cars (counted in `last-run-report.json.excluded`): `duplicate_id`, `filtered` (Cronicle
+rules, no images), `reserved_or_sold`, `no_valid_price`, `no_make`, `no_recognisable_model`,
+`no_valid_year`, `no_valid_image`, `url_too_long`.
+
+## Legacy DEV output (last run 09.11.2026 09:01, 1,771 ads) — defects found
+
+- `price unit="euro"` on every ad (rejected by the current importer).
+- 5,001 `…/carimage/noimage/…` placeholder pictures (the template forbids "No image available" images).
+- `region` = `DE` (country code, not a region); 415 of 3,094 DEV cars have a 4-digit postcode
+  (leading zero lost because CBD stores a number).
+- `euronorm` = `default` on 65 ads; empty `<engine_size/>` / `<power/>` without `unit` → XSD-invalid.
+- `time` as `hh:mm:ss` (12-hour clock); year invented for new cars without a year (`now - 2 months`).
+- Output directory emptied before the run (an outage published an empty / partial file); tar.gz built
+  with the external `zip` tooling.
+
+DEV dry-run results with 1.26.48: see `RUNBOOK.md` → "DEV runs".

package/docs/ooyyo/PARTNER-QUESTIONS.md

@@ -0,0 +1,32 @@
+# OOYYO — open partner questions (ADV-331 / ADV-333)
+
+Contact: Aleksandar Ciric (OOYYO). `submission@ooyyo.net` is dead. Draft only — nothing is sent from
+engineering; Marketing sends after review.
+
+Already answered (16.10. / 19.10.2026): OOYYO XML only; fixed HTTPS URL, plain or `.gz`; daily pull
+shortly after midnight; full replacement (partly valid file replaces everything, failed download / 0
+readable ads keeps the old inventory); `unit="EUR"` mandatory; photo / year / price / recognisable
+make + model mandatory; URLs ≤ 1,500 chars; UTMs allowed and kept, direct link without redirect; free
+listing has no click reporting and no click id; Featured Vehicles is a separate paid product.
+
+Open:
+
+1. Time zone of the daily pull ("shortly after midnight") — asked by Marketing on 19.10., no answer yet.
+   We need it to schedule our export so the file is fresh but never mid-write (we publish atomically).
+2. How should the 20-car test sample reach the importer for the non-live test: file attachment or a
+   temporary URL? If a URL: may it carry a secret token in the path / query (the partner mentioned an
+   optional token), and does the importer accept a self-signed / basic-auth protected URL?
+3. Retry behaviour when the URL answers 5xx / times out at the pull time: one retry later the same
+   night, or next day only? Any alerting on their side we can subscribe to?
+4. Grace period for deletions: a car missing in one file — removed immediately at that import?
+5. Make / model recognition: is there a reference list (or a report of unmatched values after the
+   test import) so we can map our values (e.g. "Mercedes-Benz", "Škoda", sub-brands) up front?
+6. Accepted values for `fuel_type`, `transmission`, `body_type`, `color`: German labels OK (we send
+   e.g. `Benzin`, `Elektro`, `Automatik`, `SUV/Geländewagen`), or English keywords preferred?
+7. `euronorm`: are our values `6`, `6d`, `6d-TEMP` OK, or `Euro 6` style?
+8. `date` / `time`: listing creation date in Europe/Berlin — correct meaning ("date of the ad")?
+9. Electric cars: is an ad without `engine_size` fine (we leave it out rather than send 0)?
+10. Crawler: User-Agent and source IPs of the feed fetcher and of any page crawler, so we can classify
+    them as automation in our traffic reporting (ADV-333) and allow-list them at Cloudflare.
+11. Does OOYYO ever request our vehicle pages itself (link checking / crawling) after the import?
+12. Rejection report after each production import (counts + reasons) — available beyond the test?

package/docs/ooyyo/RUNBOOK.md

@@ -0,0 +1,67 @@
+# OOYYO feed — runbook (ADV-331)
+
+## Parameters (Cronicle event, export-cars plugin, `exportType=ooyyo`)
+
+| Param | Default | Meaning |
+|---|---|---|
+| `String` / `Number` / `Date` | — | Cronicle filter rules (DEV 6.0: none) |
+| `ooyyoDryRun` | dry-run | only the exact text `false` makes a live run |
+| `ooyyoMaxImages` | no cut | cut the picture list (OOYYO accepts all; 20 is a ranking recommendation) |
+| `ooyyoImageConcurrency` | 16 | parallel image URL checks |
+| `feedGuardMinSourceItems` | 1000 | DEV snapshot ~3,100 cars |
+| `feedGuardMinPublishedItems` | 1 | set a real minimum from a PROD dry-run before going live |
+| `feedGuardMaxDropPercent` | 20 | max drop of source / ads against the last good run |
+| `feedGuardMaxSourceAgeHours` | 26 | newest base export chunk must be younger |
+| `feedGuardMaxStaleHours` | 48 | last good file reported STALE after this |
+| `feedGuardAcceptDrop` | off | `true` for ONE run after a real, approved stock reduction |
+
+No new parameter is needed for a run: the defaults give a safe dry-run.
+
+## Files
+
+| Mode | Output | State |
+|---|---|---|
+| dry-run | `resources/ooyyo-dryrun/ooyyo.xml` + `ooyyo.xml.gz` | `resources/ooyyo-state/dryrun/` |
+| live | `resources/ooyyo-export/ooyyo.xml` + `ooyyo.xml.gz` | `resources/ooyyo-state/export/` |
+
+State dir: `last-good.json`, `last-run-report.json` (guard code, exclusions, verify issues, missing
+optional fields, padded postcodes, bytes + sha256, image stats), `run.lock`. A blocked run leaves
+`ooyyo.xml.rejected`; the published files and their `.prev` copies stay.
+
+## Run order inside one run
+
+source snapshot check → map + partner rules + image check per car → temp XML → read back + verify
+every ad and the count → count guard vs last good → gzip + round-trip check → rename `.xml.gz`, then
+`.xml` (both atomic) → report. Any failure: exit 1, nothing replaced.
+
+## Exit codes and the chain
+
+Blocked or failed runs exit 1, so the chained `6.1 … part 2` does not run. A dry-run exits 0 and DEV
+`6.1` then uploads `resources/ooyyo-export/autode-ooyyo.tar.gz` — the LEGACY file from 09.11.2026,
+which 1.26.48 no longer writes — to the legacy Jelastic FTP (as `autode-ooyyo-develop.tar.gz`). `6.1`
+is not changed (same decision as meinestadt `5.1`). To run 6.0 alone use the API with `chain: ""`:
+
+```
+# on the DEV Cronicle host; the key never leaves the host
+K=$(sudo -n node bin/storage-cli.js get global/api_keys/0 | node -e '…print .key…')
+curl -s -X POST 127.0.0.1:<WebServer.http_port>/api/app/run_event/v1 \
+  -d '{"api_key":"'$K'","id":"ejtpmrpb002","chain":""}'
+```
+
+## Before anything goes live (not done; each step needs explicit OK)
+
+1. Marketing approval; 20-car sample (from a PROD dry-run, not DEV data) to Aleksandar for the
+   NON-LIVE importer test; accepted / rejected counts and reasons reconciled (target: 0 rejected).
+2. Answers to `PARTNER-QUESTIONS.md` (pull time zone, retry, sample transport, value lists).
+3. Hosting: a fixed HTTPS URL serving `resources/ooyyo-export/ooyyo.xml(.gz)` read-only, optional
+   secret token kept out of logs; replace / disable `6.1` (legacy FTP, credentials in the script).
+4. Schedule the export so it finishes well before the partner's midnight pull; monitoring on
+   `last-run-report.json` (status, stale) and on the served file's age.
+5. `feedGuardMinPublishedItems` from a PROD dry-run; only then `ooyyoDryRun=false`.
+6. Stop-poll / rollback: serve the `.prev` file or an HTTP 5xx (OOYYO keeps the old inventory on a
+   failed download) — never an empty or partial file.
+7. Tracking: `web-funnel-tracking-health` ≥ 1.5.7 (CLASSIFIEDS_OOYYO) on the target Cronicle.
+
+## DEV runs
+
+(filled in after the DEV run, see below)

package/docs/ooyyo/TRACKING.md

@@ -0,0 +1,54 @@
+# OOYYO — measurement (ADV-333)
+
+Status 13.11.2026: DEV only. Implemented: the feed `<url>` scheme (export-cars 1.26.48) and the
+reporting channel `CLASSIFIEDS_OOYYO` (web-funnel-tracking-health 1.5.7). No partner click id, cost,
+postback or pixel exists for the free listing, so none is modelled.
+
+## Evidence
+
+- Partner, 19.10.2026: OOYYO links DIRECTLY to the `<url>` of the XML, no redirect, query parameters
+  (our UTMs) unchanged; URL ≤ 1,500 chars; free listing = no click reporting, no click id.
+- Historic ACF-6139 link: `?source=classifieds&medium=listing&campaign=ooyyo` (Confluence tag
+  "ooyyo [organic]"). Before 1.5.7 that resolved to generic classifieds / UTM rules — the partner
+  identity was lost, same finding as AutoUncle (ADV-324).
+- ADV-260: fe-main keeps `source/medium/campaign/utm_*` in the marketing cookie (first external
+  context wins, internal navigation does not overwrite it) and sends it with every lead.
+
+## Path
+
+```
+OOYYO result ──(direct link, no redirect)──► https://www.auto.de/search/vehicle/<car _id>
+    ?source=ooyyo&medium=listing&campaign=listing&utm_source=ooyyo&utm_medium=listing&utm_campaign=listing
+  → fe-main marketing cookie (ADV-260)        → visitor session, landing_url keeps the raw query
+  → views: reporting_channel CLASSIFIEDS_OOYYO, family Classifieds, detail OOYYO, publisher OOYYO
+    (historic source=classifieds&campaign=ooyyo resolves to the same channel)
+  → form → REQ → Odoo crm_source "ooyyo" (VDP enquiries need the user-actions-contact ADV-327 cookie
+    fallback — DEV since 13.11, not on PROD)
+  → rpt_episode_touchpoint → canonical 90-day episode (original episode_start_date) → sale / CM
+```
+
+- Legacy and utm pairs carry identical values, so fe-main's `getUtmQueryParameter` sees no
+  parameter conflict; GA4 sees `ooyyo / listing`.
+- Not PAID_*: the listing is free; it stays out of the paid click-id health rates and gets no cost.
+  Spend for OOYYO is "verified no fee" only for the free XML listing; any Featured Vehicles test needs
+  its own cost import first.
+- Reconciliation view: platform `ooyyo`, but there are no media rows → sessions only, no exact join.
+
+## Crawler / bot filtering
+
+Sessions are VISITOR / KNOWN_CRAWLER / INTERNAL by published crawler IP ranges and proven automation
+signatures (ADV-371). OOYYO publishes no ranges; its feed fetch reads the XML file only and creates
+no tracking event. No OOYYO rule is guessed — partner question 10 asks for UA / IPs; once known, add
+them as verified automation with evidence.
+
+## Not done (by design)
+
+- No `ooyyo_clickid` or similar parameter, no postback, no conversion upload.
+- No retroactive rewrite of historic `crm_source` values.
+- Customer SQL (`source_resolved_v1 = LOWER(crm_source)`) already yields `ooyyo` for the new link; the
+  historic `classifieds` + campaign `ooyyo` rows stay `classifieds` until the data owner applies the
+  classifieds-campaign rule proposed for ADV-324 / ADV-327 / ADV-330.
+
+## QA
+
+See `RUNBOOK.md` → "DEV runs" for the DEV test (link → VDP → enquiry → Odoo REQ → views).

package/package.json

@@ -1,65 +1,66 @@
-{
-  "name": "@bytebrand/export-cars",
-  "version": "1.26.47",
-  "description": "",
-  "author": "bytebrand",
-  "license": "UNLICENSED",
-  "scripts": {
-    "prebuild": "rimraf dist",
-    "build": "nest build",
-    "prepublishOnly": "npm run build",
-    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
-    "lint": "eslint -c .eslintrc.js --ext .ts src/",
-    "start:dev": "nest start --watch",
-    "test": "ts-node --transpile-only test/google-feed-envkv.test.ts && ts-node --transpile-only test/google-feed-item-row.test.ts && ts-node --transpile-only test/publication-gate.test.ts && ts-node --transpile-only test/images-regression.test.ts && ts-node --transpile-only test/clean-images.test.ts && ts-node --transpile-only test/image-url-validator.test.ts && ts-node --transpile-only test/openai-image-fields.test.ts && ts-node --transpile-only test/openai-ads-mapping.test.ts && ts-node --transpile-only test/openai-ads-feed-run.test.ts && ts-node --transpile-only test/openai-ads-finance.test.ts && ts-node --transpile-only test/openai-ads-price-cap.test.ts && ts-node --transpile-only test/meinstadt-mapping.test.ts && ts-node --transpile-only test/meinstadt-feed-run.test.ts && ts-node --transpile-only test/autouncle-mapping.test.ts && ts-node --transpile-only test/autouncle-feed-run.test.ts && ts-node --transpile-only test/mapping-csv.test.ts && ts-node --transpile-only test/marktde-mapping.test.ts && ts-node --transpile-only test/marktde-feed-run.test.ts && ts-node --transpile-only test/criteo-images.test.ts && ts-node --transpile-only test/criteo-mapping.test.ts && ts-node --transpile-only test/criteo-feed-run.test.ts"
-  },
-  "dependencies": {
-    "@bytebrand/autode-request": "^1.19.2",
-    "@bytebrand/bigquery-logger": "^2.1.2",
-    "@bytebrand/car-basic-data-scope": "^9.11.24",
-    "@bytebrand/car-description": "^1.17.20",
-    "@bytebrand/car-schema": "^3.14.15",
-    "@bytebrand/chunkable": "^5.19.8",
-    "@bytebrand/cronicle-helper": "^1.21.8",
-    "@bytebrand/fe-financing": "^5.14.19",
-    "@bytebrand/i18n-dictionaries": "^1.5.0",
-    "@bytebrand/import-helper": "^0.45.0",
-    "@bytebrand/schema-tools": "^3.18.8",
-    "@bytebrand/zipper": "^2.2.0",
-    "@nestjs/cache-manager": "^2.1.0",
-    "@nestjs/common": "^10.2.7",
-    "@nestjs/core": "^10.2.7",
-    "adm-zip": "0.5.5",
-    "axios": "^1.5.1",
-    "bottleneck": "^2.19.5",
-    "cache-manager": "^5.2.4",
-    "csv-write-stream": "^2.0.0",
-    "google-spreadsheet": "^3.3.0",
-    "lodash": "^4.17.21",
-    "moment": "^2.29.4",
-    "nest-commander": "~3.15.0",
-    "reflect-metadata": "^0.1.13",
-    "vin-generator": "^1.0.1"
-  },
-  "devDependencies": {
-    "@nestjs/cli": "^10.1.18",
-    "@types/google-spreadsheet": "^3.3.0",
-    "@types/inquirer": "^8.2.4",
-    "@types/lodash": "^4.14.186",
-    "@types/node": "^16.18.58",
-    "@typescript-eslint/eslint-plugin": "^6.8.0",
-    "@typescript-eslint/parser": "^6.8.0",
-    "eslint": "^8.0.1",
-    "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-prettier": "^4.0.0",
-    "gts": "^3.1.1",
-    "prettier": "^2.3.2",
-    "ts-node": "^10.0.0",
-    "tsconfig-paths": "4.1.0",
-    "typescript": "^5.2.2"
-  },
-  "engines": {
-    "node": ">=14.0.0"
-  },
-  "gitHead": "e827f35865032821bf3a081f03a026d3d3f8a540"
-}
+{
+  "name": "@bytebrand/export-cars",
+  "version": "1.26.48",
+  "description": "",
+  "author": "bytebrand",
+  "license": "UNLICENSED",
+  "scripts": {
+    "prebuild": "rimraf dist",
+    "build": "nest build",
+    "prepublishOnly": "npm run build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint": "eslint -c .eslintrc.js --ext .ts src/",
+    "start:dev": "nest start --watch",
+    "test": "ts-node --transpile-only test/google-feed-envkv.test.ts && ts-node --transpile-only test/google-feed-item-row.test.ts && ts-node --transpile-only test/publication-gate.test.ts && ts-node --transpile-only test/images-regression.test.ts && ts-node --transpile-only test/clean-images.test.ts && ts-node --transpile-only test/image-url-validator.test.ts && ts-node --transpile-only test/openai-image-fields.test.ts && ts-node --transpile-only test/openai-ads-mapping.test.ts && ts-node --transpile-only test/openai-ads-feed-run.test.ts && ts-node --transpile-only test/openai-ads-finance.test.ts && ts-node --transpile-only test/openai-ads-price-cap.test.ts && ts-node --transpile-only test/meinstadt-mapping.test.ts && ts-node --transpile-only test/meinstadt-feed-run.test.ts && ts-node --transpile-only test/autouncle-mapping.test.ts && ts-node --transpile-only test/autouncle-feed-run.test.ts && ts-node --transpile-only test/mapping-csv.test.ts && ts-node --transpile-only test/marktde-mapping.test.ts && ts-node --transpile-only test/marktde-feed-run.test.ts && ts-node --transpile-only test/ooyyo-mapping.test.ts && ts-node --transpile-only test/ooyyo-feed-run.test.ts && ts-node --transpile-only test/criteo-images.test.ts && ts-node --transpile-only test/criteo-mapping.test.ts && ts-node --transpile-only test/criteo-feed-run.test.ts"
+  },
+  "dependencies": {
+    "@bytebrand/autode-request": "^1.19.2",
+    "@bytebrand/bigquery-logger": "^2.1.2",
+    "@bytebrand/car-basic-data-scope": "^9.11.24",
+    "@bytebrand/car-description": "^1.17.20",
+    "@bytebrand/car-schema": "^3.14.15",
+    "@bytebrand/chunkable": "^5.19.8",
+    "@bytebrand/cronicle-helper": "^1.21.8",
+    "@bytebrand/fe-financing": "^5.14.19",
+    "@bytebrand/i18n-dictionaries": "^1.5.0",
+    "@bytebrand/import-helper": "^0.45.0",
+    "@bytebrand/schema-tools": "^3.18.8",
+    "@bytebrand/zipper": "^2.2.0",
+    "@nestjs/cache-manager": "^2.1.0",
+    "@nestjs/common": "^10.2.7",
+    "@nestjs/core": "^10.2.7",
+    "adm-zip": "0.5.5",
+    "axios": "^1.5.1",
+    "bottleneck": "^2.19.5",
+    "cache-manager": "^5.2.4",
+    "csv-write-stream": "^2.0.0",
+    "fast-xml-parser": "4.2.5",
+    "google-spreadsheet": "^3.3.0",
+    "lodash": "^4.17.21",
+    "moment": "^2.29.4",
+    "nest-commander": "~3.15.0",
+    "reflect-metadata": "^0.1.13",
+    "vin-generator": "^1.0.1"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^10.1.18",
+    "@types/google-spreadsheet": "^3.3.0",
+    "@types/inquirer": "^8.2.4",
+    "@types/lodash": "^4.14.186",
+    "@types/node": "^16.18.58",
+    "@typescript-eslint/eslint-plugin": "^6.8.0",
+    "@typescript-eslint/parser": "^6.8.0",
+    "eslint": "^8.0.1",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-prettier": "^4.0.0",
+    "gts": "^3.1.1",
+    "prettier": "^2.3.2",
+    "ts-node": "^10.0.0",
+    "tsconfig-paths": "4.1.0",
+    "typescript": "^5.2.2"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "gitHead": "e827f35865032821bf3a081f03a026d3d3f8a540"
+}

package/src/configs/marktde.config.ts

@@ -1,70 +1,70 @@
-import { toNumber } from 'lodash';
-
-import { ExportType, FileType, ImageType } from '../enums';
-import { Params } from '../interfaces/params.interface';
-import { FeedGuardOptions } from '../services/feed-guard';
-import { Config } from './config';
-
-const text = (value: unknown): string => (typeof value === 'string' ? value.trim() : '');
-
-const positiveNumber = (value: unknown, fallback: number): number => {
-  const parsed = toNumber(text(value));
-  return text(value) && Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
-};
-
-// Guard defaults (same as AutoUncle). The DEV job exports one dealer via the Cronicle rules, so the
-// published count is far below the base snapshot: minPublishedItems only forbids an empty file.
-export const MARKTDE_DEFAULTS = {
-  imageConcurrency: 16,
-  minSourceItems: 1000,
-  minPublishedItems: 1,
-  maxDropPercent: 20,
-  maxSourceAgeHours: 26,
-  maxStaleHours: 48,
-};
-
-/**
- * markt.de vehicle feed (ADV-328): the legacy mobile.de-style CSV (mapping sheet `mobile_yescar`,
- * ACF-4370) plus a ZIP of it, with clean ADV-336 images. There is no current markt.de spec yet, so
- * the format (columns, file names, no header row, `;` separator, UTF-8) stays as it was.
- * Dry-run is the default: the files go to resources/marktde-dryrun, which no Cronicle step reads.
- * Only marktdeDryRun=false writes resources/marktde-export (the directory `9c.1 … part 2` uploads
- * from). Each mode has its own guard state.
- */
-export class MarktdeConfig extends Config {
-  dryRun: boolean;
-  imageConcurrency: number;
-  // 0 = no limit (no partner limit known)
-  maxImages: number;
-  stateDir: string;
-  feedGuard: FeedGuardOptions;
-
-  constructor(params: Params) {
-    super(params);
-    this.campaign = ExportType.MARKTDE;
-    this.dryRun = text(params.marktdeDryRun).toLowerCase() !== 'false';
-    const mode = this.dryRun ? 'dryrun' : 'export';
-    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.MARKTDE}-${mode}`;
-    this.stateDir = `resources/${ExportType.MARKTDE}-state/${mode}`;
-    this.imageUrl = `https://images.${this.domain}/carimage`;
-    this.mappingSpreadsheetTitle = 'mobile_yescar';
-    // MobileTransformer still builds its legacy `image` column; marktde.transformer replaces it with
-    // the validated clean list.
-    this.imageType = ImageType.default;
-    this.imageConcurrency = positiveNumber(params.marktdeImageConcurrency, MARKTDE_DEFAULTS.imageConcurrency);
-    this.maxImages = Math.floor(positiveNumber(params.marktdeMaxImages, 0));
-    this.feedGuard = {
-      stateDir: this.stateDir,
-      minSourceItems: positiveNumber(params.feedGuardMinSourceItems, MARKTDE_DEFAULTS.minSourceItems),
-      minPublishedItems: positiveNumber(params.feedGuardMinPublishedItems, MARKTDE_DEFAULTS.minPublishedItems),
-      maxDropPercent: positiveNumber(params.feedGuardMaxDropPercent, MARKTDE_DEFAULTS.maxDropPercent),
-      maxSourceAgeHours: positiveNumber(params.feedGuardMaxSourceAgeHours, MARKTDE_DEFAULTS.maxSourceAgeHours),
-      maxStaleHours: positiveNumber(params.feedGuardMaxStaleHours, MARKTDE_DEFAULTS.maxStaleHours),
-      acceptDrop: text(params.feedGuardAcceptDrop).toLowerCase() === 'true',
-    };
-    this.outputFiles = [
-      `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.MARKTDE}.${FileType.CSV}`,
-      `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.MARKTDE}.${FileType.ZIP}`,
-    ];
-  }
-}
+import { toNumber } from 'lodash';
+
+import { ExportType, FileType, ImageType } from '../enums';
+import { Params } from '../interfaces/params.interface';
+import { FeedGuardOptions } from '../services/feed-guard';
+import { Config } from './config';
+
+const text = (value: unknown): string => (typeof value === 'string' ? value.trim() : '');
+
+const positiveNumber = (value: unknown, fallback: number): number => {
+  const parsed = toNumber(text(value));
+  return text(value) && Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+// Guard defaults (same as AutoUncle). The DEV job exports one dealer via the Cronicle rules, so the
+// published count is far below the base snapshot: minPublishedItems only forbids an empty file.
+export const MARKTDE_DEFAULTS = {
+  imageConcurrency: 16,
+  minSourceItems: 1000,
+  minPublishedItems: 1,
+  maxDropPercent: 20,
+  maxSourceAgeHours: 26,
+  maxStaleHours: 48,
+};
+
+/**
+ * markt.de vehicle feed (ADV-328): the legacy mobile.de-style CSV (mapping sheet `mobile_yescar`,
+ * ACF-4370) plus a ZIP of it, with clean ADV-336 images. There is no current markt.de spec yet, so
+ * the format (columns, file names, no header row, `;` separator, UTF-8) stays as it was.
+ * Dry-run is the default: the files go to resources/marktde-dryrun, which no Cronicle step reads.
+ * Only marktdeDryRun=false writes resources/marktde-export (the directory `9c.1 … part 2` uploads
+ * from). Each mode has its own guard state.
+ */
+export class MarktdeConfig extends Config {
+  dryRun: boolean;
+  imageConcurrency: number;
+  // 0 = no limit (no partner limit known)
+  maxImages: number;
+  stateDir: string;
+  feedGuard: FeedGuardOptions;
+
+  constructor(params: Params) {
+    super(params);
+    this.campaign = ExportType.MARKTDE;
+    this.dryRun = text(params.marktdeDryRun).toLowerCase() !== 'false';
+    const mode = this.dryRun ? 'dryrun' : 'export';
+    this.pathesConfig.localConvertedDirectory = `resources/${ExportType.MARKTDE}-${mode}`;
+    this.stateDir = `resources/${ExportType.MARKTDE}-state/${mode}`;
+    this.imageUrl = `https://images.${this.domain}/carimage`;
+    this.mappingSpreadsheetTitle = 'mobile_yescar';
+    // MobileTransformer still builds its legacy `image` column; marktde.transformer replaces it with
+    // the validated clean list.
+    this.imageType = ImageType.default;
+    this.imageConcurrency = positiveNumber(params.marktdeImageConcurrency, MARKTDE_DEFAULTS.imageConcurrency);
+    this.maxImages = Math.floor(positiveNumber(params.marktdeMaxImages, 0));
+    this.feedGuard = {
+      stateDir: this.stateDir,
+      minSourceItems: positiveNumber(params.feedGuardMinSourceItems, MARKTDE_DEFAULTS.minSourceItems),
+      minPublishedItems: positiveNumber(params.feedGuardMinPublishedItems, MARKTDE_DEFAULTS.minPublishedItems),
+      maxDropPercent: positiveNumber(params.feedGuardMaxDropPercent, MARKTDE_DEFAULTS.maxDropPercent),
+      maxSourceAgeHours: positiveNumber(params.feedGuardMaxSourceAgeHours, MARKTDE_DEFAULTS.maxSourceAgeHours),
+      maxStaleHours: positiveNumber(params.feedGuardMaxStaleHours, MARKTDE_DEFAULTS.maxStaleHours),
+      acceptDrop: text(params.feedGuardAcceptDrop).toLowerCase() === 'true',
+    };
+    this.outputFiles = [
+      `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.MARKTDE}.${FileType.CSV}`,
+      `${this.pathesConfig.localConvertedDirectory}/api_export_cars_${ExportType.MARKTDE}.${FileType.ZIP}`,
+    ];
+  }
+}