CSV Export

Overview

Produce a Casestry-format CSV for a specified date range — a workflow (ProcedureExecution) that queries warehouse data, generates an export document, and stores it in R2 as a downloadable file (R2 object).

Goal: Generate a downloadable export file and a durable export record.

API endpoints

Method	Path	Spec	Description
POST	/creative-ops/exports	creative-ops.yaml	Create an export job (async, returns pending)
GET	/creative-ops/exports	creative-ops.yaml	List export jobs with status
GET	/creative-ops/exports/{export_id}	creative-ops.yaml	Export detail + signed download URL
POST	/creative-ops/exports/{export_id}/regenerate	creative-ops.yaml	Re-run export with same parameters

Schema tables

Table	Module	Role
macrodata_artifact (kind: document_export)	Macrodata	Write: export record with status + download URL
order_header	Order	Read: source data for CSV rows
order_line_item	Order	Read: line-item detail for CSV
link_product_macrodata_artifact	Macrodata	Read: design asset bearer URLs for join

Infrastructure

Resource	Type	Purpose
internal	Worker	API validation, export record creation, job enqueue
ingest	Worker	Workflow executor: query, format, upload
CF Queue	Queue	DOCUMENT_ARTIFACT_GENERATE job delivery
R2 bucket	Object storage	Stores generated CSV file

Participants

Actor	Role
Staff user	Requests export with date range
Dashboard API Worker	Creates export record, enqueues job
Ingest Worker	Queries data, generates CSV, uploads to R2
PlanetScale	Data source + export records
R2	Stores generated export file

Main success scenario

1. Staff calls POST /creative-ops/exports with date range and format
2. API validates Access, writes macrodata_artifact row (kind: document_export) as pending
3. API enqueues DOCUMENT_ARTIFACT_GENERATE(export_id, date_range)
4. Step: Query — Worker queries order_header / order_line_item for the range
5. Step: Join — Worker joins with link_product_macrodata_artifact for design asset bearer URLs
6. Step: Format — Worker formats Casestry CSV (34 columns including vendor resolution)
7. Step: Store — Worker uploads file to R2 and stores download URL in macrodata_artifact.file_url
8. Step: Finalize — Worker updates macrodata_artifact.status = 'completed' with counts and metadata

Exception flows

Error condition	Recovery
Missing product-artifact link	Include placeholder value; record count in metadata.error_count
PlanetScale limits	Chunk reads; stream CSV generation; stay under 64 MiB result sets
Export creation fails	Set status = 'failed', store error_message

Queue contract

{
  "job_type": "DOCUMENT_ARTIFACT_GENERATE",
  "job_id": "uuid",
  "export_id": "uuid",
  "date_range_start": "YYYY-MM-DD",
  "date_range_end": "YYYY-MM-DD"
}

Acceptance criteria

• PASS: CSV rows match expected order count; download URL resolves; export record transitions pending → completed
• FAIL: Incorrect formatting; missing required columns; data mismatch vs order_header