# title
Shared schema definitions for storis-api-utils

# description
Primitive types and enums referenced by every other schema in this directory. Keeps vocabulary consistent across fusion outputs, config files, and any future contracts. Treat this as the canonical type registry for the project — if a concept is reused, it lives here.

# $defs.storisStoreId.description
The five canonical STORIS store identifiers. 001-004 are physical; 777 is the online (ASHCOMM) channel.

# $defs.physicalStoreId.description
Physical store identifiers only — excludes 777 (online).

# $defs.physicalLocationId.description
Groups co-located stores. Stores 003 and 004 share the Decatur outlet location; stores 001 and 002 each have their own physical location. Store 777 (online) has no physical_location and uses null instead of this enum.

# $defs.trakwellStoreIdNumeric.description
Trakwell's numeric store identifier (which it confusingly calls 'store_name' in the v3 countDetail and v1 action_customer_api responses). Matches STORIS for stores with their own door. Both STORIS 003 and 004 map to Trakwell '004' (the shared Decatur door). 777 has none.

# $defs.trakwellStoreNameText.description
Trakwell's human-readable location name (used in v2 UserSummaryCountNew and v3 salestatsemp). Three values; 003 and 004 share the third.

# $defs.isoDate.description
Local business-day date in YYYY-MM-DD form. Always use this format for the 'date' partition key on fusion outputs; any STORIS or Trakwell native date format must be normalized here first.

# $defs.isoDateTime.description
Used for provenance fields (loaded_at) and any timestamp that crosses system boundaries. Must include explicit timezone or trailing Z.

# $defs.salesLogRunDir.description
Local timestamped directory name produced by the daily pipelines. Format: YYYY-MM-DD_HH-MM-SS. Used as a provenance pointer back to raw responses.

# $defs.storisOrderItemId.description
Format is <orderId>*<lineNumber>, e.g. '00266359*5'. Primary key in the STORIS line-item-granularity model.

# $defs.storisOrderId.description
The order-level identifier. STORIS encodes the originating store in the leading three digits (003-prefixed for Ashley Outlet, 004-prefixed for Bestbrands, etc.).

# $defs.storisCustomerCode.description
The space-delimited first token of 'Customer Code / Name' in STORIS CSV exports. Used as the dedup key for close-ratio math (a customer with multiple tickets across co-located stores collapses to one close).

# $defs.storisSalespersonCode.description
Short alphabetic code (2-4 chars) like 'AW1', 'KB', 'TC', 'ZZZ', 'ASH'. Distinct from Trakwell's longer employee_code form.

# $defs.trakwellEmployeeCode.description
Trakwell's longer-form employee identifier, like 'TCROSIER', 'AWELLS', 'KBEAVERS'. Mapped to a STORIS short code via docs/salesperson_map.json.

# $defs.rsaRole.title
RSA role per upstream config/managers.yaml semantics + system accounts

# $defs.rsaRole.description
Drives report scoping — see external_research/jupyter/weekly_score_card/config/managers.yaml. Upper managers and inactive RSAs are excluded from all reporting; managers are excluded from Wall-of-Shame style negative reports only. The 'system' role is for non-human accounts (ZZZ house account, ASH ecommerce); they're excluded from RSA analysis but present in org-level totals. 'guest_services' (front-desk / customer-service) and 'warehouse' (logistics) are non-sales staff the resolver still tracks so STORIS codes belonging to them don't trip every unmapped-code check; both are excluded from RSA-level reporting.

# $defs.closeRatio.description
Stored as a decimal (not percent). [0, 1] is the expected range; values up to ~5 can occur with hygiene anomalies and should be flagged but not rejected. Anything above 5 is almost certainly a bug — schema rejects.