shapecraft 1.0.0

package/test-data/sql/ecommerce.sql

@@ -0,0 +1,641 @@
+-- ============================================================================
+-- Mock E-commerce Database Schema (PostgreSQL)
+-- ============================================================================
+-- Exercises: extensions, custom types, enums, domains, schemas, inheritance,
+-- partitioning, constraints, indexes (B-tree, GIN, GiST, HNSW), triggers,
+-- functions, views, materialized views, foreign keys, JSONB, arrays, full-text
+-- search, pgvector for semantic similarity, row-level security, and more.
+-- ============================================================================
+
+-- ----------------------------------------------------------------------------
+-- Extensions
+-- ----------------------------------------------------------------------------
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+CREATE EXTENSION IF NOT EXISTS "citext";
+CREATE EXTENSION IF NOT EXISTS "pg_trgm";
+CREATE EXTENSION IF NOT EXISTS "btree_gin";
+CREATE EXTENSION IF NOT EXISTS "vector";       -- pgvector
+CREATE EXTENSION IF NOT EXISTS "postgis";      -- for shipping zone geometry (optional)
+
+-- ----------------------------------------------------------------------------
+-- Schemas (logical separation)
+-- ----------------------------------------------------------------------------
+CREATE SCHEMA IF NOT EXISTS shop;
+CREATE SCHEMA IF NOT EXISTS audit;
+CREATE SCHEMA IF NOT EXISTS analytics;
+
+SET search_path TO shop, public;
+
+-- ----------------------------------------------------------------------------
+-- Custom Types, Domains, and Enums
+-- ----------------------------------------------------------------------------
+CREATE TYPE shop.order_status AS ENUM (
+    'pending', 'paid', 'processing', 'shipped',
+    'delivered', 'cancelled', 'refunded', 'returned'
+);
+
+CREATE TYPE shop.payment_method AS ENUM (
+    'credit_card', 'debit_card', 'paypal', 'stripe', 'crypto', 'bank_transfer'
+);
+
+CREATE TYPE shop.user_role AS ENUM ('customer', 'vendor', 'admin', 'support');
+
+CREATE TYPE shop.address_kind AS ENUM ('billing', 'shipping', 'both');
+
+CREATE TYPE shop.money AS (
+    amount  NUMERIC(14, 4),
+    currency CHAR(3)
+);
+
+CREATE DOMAIN shop.email AS CITEXT
+    CHECK (VALUE ~ '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$');
+
+CREATE DOMAIN shop.positive_numeric AS NUMERIC(14, 4)
+    CHECK (VALUE >= 0);
+
+CREATE DOMAIN shop.sku AS VARCHAR(64)
+    CHECK (VALUE ~ '^[A-Z0-9][A-Z0-9-]{2,63}$');
+
+-- ----------------------------------------------------------------------------
+-- Reusable trigger function: updated_at
+-- ----------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION shop.tg_set_updated_at()
+RETURNS TRIGGER
+LANGUAGE plpgsql AS $$
+BEGIN
+    NEW.updated_at := CURRENT_TIMESTAMP;
+    RETURN NEW;
+END;
+$$;
+
+-- ============================================================================
+-- Core tables
+-- ============================================================================
+
+-- ---- users -----------------------------------------------------------------
+CREATE TABLE shop.users (
+    id              UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    email           shop.email NOT NULL UNIQUE,
+    password_hash   TEXT NOT NULL,
+    full_name       VARCHAR(200) NOT NULL,
+    role            shop.user_role NOT NULL DEFAULT 'customer',
+    phone           VARCHAR(32),
+    date_of_birth   DATE,
+    preferences     JSONB NOT NULL DEFAULT '{}'::JSONB,
+    tags            TEXT[] NOT NULL DEFAULT '{}',
+    is_active       BOOLEAN NOT NULL DEFAULT TRUE,
+    last_login_at   TIMESTAMPTZ,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT users_dob_reasonable CHECK (date_of_birth IS NULL OR date_of_birth > '1900-01-01'),
+    CONSTRAINT users_phone_format CHECK (phone IS NULL OR phone ~ '^\+?[0-9\s\-()]{7,32}$')
+);
+
+CREATE INDEX users_role_active_idx       ON shop.users (role) WHERE is_active;
+CREATE INDEX users_tags_gin_idx          ON shop.users USING GIN (tags);
+CREATE INDEX users_preferences_gin_idx   ON shop.users USING GIN (preferences jsonb_path_ops);
+CREATE INDEX users_email_trgm_idx        ON shop.users USING GIN (email gin_trgm_ops);
+
+CREATE TRIGGER users_set_updated_at
+BEFORE UPDATE ON shop.users
+FOR EACH ROW EXECUTE FUNCTION shop.tg_set_updated_at();
+
+-- ---- addresses (self-contained, linked to users) ---------------------------
+CREATE TABLE shop.addresses (
+    id              BIGSERIAL PRIMARY KEY,
+    user_id         UUID NOT NULL REFERENCES shop.users(id) ON DELETE CASCADE,
+    kind            shop.address_kind NOT NULL DEFAULT 'both',
+    line1           VARCHAR(200) NOT NULL,
+    line2           VARCHAR(200),
+    city            VARCHAR(120) NOT NULL,
+    region          VARCHAR(120),
+    postal_code     VARCHAR(20) NOT NULL,
+    country_code    CHAR(2) NOT NULL,
+    is_default      BOOLEAN NOT NULL DEFAULT FALSE,
+    geo             GEOGRAPHY(POINT, 4326),
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+-- only one default address of a given kind per user
+CREATE UNIQUE INDEX addresses_one_default_per_kind
+    ON shop.addresses (user_id, kind)
+    WHERE is_default;
+
+CREATE INDEX addresses_geo_gix ON shop.addresses USING GIST (geo);
+
+-- ---- vendors (specialization of user) --------------------------------------
+CREATE TABLE shop.vendors (
+    user_id         UUID PRIMARY KEY REFERENCES shop.users(id) ON DELETE CASCADE,
+    business_name   VARCHAR(200) NOT NULL,
+    tax_id          VARCHAR(64),
+    rating          NUMERIC(3, 2) NOT NULL DEFAULT 0
+                    CHECK (rating BETWEEN 0 AND 5),
+    approved_at     TIMESTAMPTZ,
+    metadata        JSONB NOT NULL DEFAULT '{}'::JSONB
+);
+
+-- ---- categories (recursive / nested set via parent_id) ---------------------
+CREATE TABLE shop.categories (
+    id              SERIAL PRIMARY KEY,
+    parent_id       INTEGER REFERENCES shop.categories(id) ON DELETE CASCADE,
+    name            VARCHAR(120) NOT NULL,
+    slug            VARCHAR(140) NOT NULL UNIQUE,
+    path            LTREE, -- materialized hierarchy if ltree is enabled; otherwise leave NULL
+    sort_order      INTEGER NOT NULL DEFAULT 0,
+    CONSTRAINT categories_no_self_parent CHECK (parent_id IS NULL OR parent_id <> id)
+);
+
+CREATE INDEX categories_parent_idx ON shop.categories (parent_id);
+
+-- ---- products ---------------------------------------------------------------
+CREATE TABLE shop.products (
+    id              UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    vendor_id       UUID NOT NULL REFERENCES shop.vendors(user_id) ON DELETE RESTRICT,
+    category_id     INTEGER REFERENCES shop.categories(id) ON DELETE SET NULL,
+    sku             shop.sku NOT NULL UNIQUE,
+    name            VARCHAR(300) NOT NULL,
+    description     TEXT,
+    price           shop.positive_numeric NOT NULL,
+    currency        CHAR(3) NOT NULL DEFAULT 'USD',
+    weight_grams    INTEGER CHECK (weight_grams IS NULL OR weight_grams > 0),
+    dimensions      JSONB,    -- e.g. {"length_cm": 10, "width_cm": 5, "height_cm": 2}
+    attributes      JSONB NOT NULL DEFAULT '{}'::JSONB,
+    tags            TEXT[] NOT NULL DEFAULT '{}',
+    is_published    BOOLEAN NOT NULL DEFAULT FALSE,
+    -- pgvector: 1536-dim OpenAI-style embedding for semantic search
+    description_embedding  VECTOR(1536),
+    -- generated column for full-text search
+    search_doc      TSVECTOR GENERATED ALWAYS AS (
+        setweight(to_tsvector('english', coalesce(name, '')), 'A') ||
+        setweight(to_tsvector('english', coalesce(description, '')), 'B') ||
+        setweight(to_tsvector('english', array_to_string(tags, ' ')), 'C')
+    ) STORED,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX products_vendor_idx        ON shop.products (vendor_id);
+CREATE INDEX products_category_idx      ON shop.products (category_id);
+CREATE INDEX products_price_idx         ON shop.products (price) WHERE is_published;
+CREATE INDEX products_tags_gin_idx      ON shop.products USING GIN (tags);
+CREATE INDEX products_attrs_gin_idx     ON shop.products USING GIN (attributes jsonb_path_ops);
+CREATE INDEX products_search_idx        ON shop.products USING GIN (search_doc);
+CREATE INDEX products_name_trgm_idx     ON shop.products USING GIN (name gin_trgm_ops);
+
+-- pgvector HNSW index for fast approximate nearest neighbour search.
+-- Using cosine distance; alternatives are vector_l2_ops and vector_ip_ops.
+CREATE INDEX products_embedding_hnsw_idx
+    ON shop.products
+    USING hnsw (description_embedding vector_cosine_ops)
+    WITH (m = 16, ef_construction = 64);
+
+CREATE TRIGGER products_set_updated_at
+BEFORE UPDATE ON shop.products
+FOR EACH ROW EXECUTE FUNCTION shop.tg_set_updated_at();
+
+-- ---- product variants -------------------------------------------------------
+CREATE TABLE shop.product_variants (
+    id              UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    product_id      UUID NOT NULL REFERENCES shop.products(id) ON DELETE CASCADE,
+    sku             shop.sku NOT NULL UNIQUE,
+    option_values   JSONB NOT NULL,   -- e.g. {"size":"L","color":"red"}
+    price_override  shop.positive_numeric,
+    stock_qty       INTEGER NOT NULL DEFAULT 0 CHECK (stock_qty >= 0),
+    UNIQUE (product_id, option_values)
+);
+
+-- ---- inventory ledger (append-only) -----------------------------------------
+CREATE TABLE shop.inventory_movements (
+    id              BIGSERIAL PRIMARY KEY,
+    variant_id      UUID NOT NULL REFERENCES shop.product_variants(id) ON DELETE CASCADE,
+    delta           INTEGER NOT NULL,
+    reason          VARCHAR(64) NOT NULL,
+    reference_id    UUID,
+    occurred_at     TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT inventory_delta_nonzero CHECK (delta <> 0)
+);
+
+CREATE INDEX inv_movements_variant_time_idx
+    ON shop.inventory_movements (variant_id, occurred_at DESC);
+
+-- ---- carts and cart items ---------------------------------------------------
+CREATE TABLE shop.carts (
+    id              UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    user_id         UUID REFERENCES shop.users(id) ON DELETE SET NULL,
+    session_token   TEXT,
+    currency        CHAR(3) NOT NULL DEFAULT 'USD',
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    expires_at      TIMESTAMPTZ,
+    CONSTRAINT cart_owner_required CHECK (
+        user_id IS NOT NULL OR session_token IS NOT NULL
+    )
+);
+
+CREATE TABLE shop.cart_items (
+    cart_id         UUID NOT NULL REFERENCES shop.carts(id) ON DELETE CASCADE,
+    variant_id      UUID NOT NULL REFERENCES shop.product_variants(id) ON DELETE RESTRICT,
+    quantity        INTEGER NOT NULL CHECK (quantity > 0),
+    unit_price      shop.positive_numeric NOT NULL,
+    added_at        TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (cart_id, variant_id)
+);
+
+-- ---- orders (range-partitioned by created_at) -------------------------------
+CREATE TABLE shop.orders (
+    id              UUID NOT NULL DEFAULT uuid_generate_v4(),
+    user_id         UUID NOT NULL REFERENCES shop.users(id) ON DELETE RESTRICT,
+    status          shop.order_status NOT NULL DEFAULT 'pending',
+    subtotal        shop.positive_numeric NOT NULL,
+    tax             shop.positive_numeric NOT NULL DEFAULT 0,
+    shipping        shop.positive_numeric NOT NULL DEFAULT 0,
+    total           shop.positive_numeric NOT NULL,
+    currency        CHAR(3) NOT NULL DEFAULT 'USD',
+    billing_address_id  BIGINT REFERENCES shop.addresses(id) ON DELETE SET NULL,
+    shipping_address_id BIGINT REFERENCES shop.addresses(id) ON DELETE SET NULL,
+    metadata        JSONB NOT NULL DEFAULT '{}'::JSONB,
+    placed_at       TIMESTAMPTZ,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (id, created_at),
+    CONSTRAINT orders_total_matches CHECK (total = subtotal + tax + shipping)
+) PARTITION BY RANGE (created_at);
+
+-- Example partitions (extend as needed)
+CREATE TABLE shop.orders_2024 PARTITION OF shop.orders
+    FOR VALUES FROM ('2024-01-01') TO ('2025-01-01');
+CREATE TABLE shop.orders_2025 PARTITION OF shop.orders
+    FOR VALUES FROM ('2025-01-01') TO ('2026-01-01');
+CREATE TABLE shop.orders_2026 PARTITION OF shop.orders
+    FOR VALUES FROM ('2026-01-01') TO ('2027-01-01');
+
+CREATE INDEX orders_user_idx       ON shop.orders (user_id, created_at DESC);
+CREATE INDEX orders_status_idx     ON shop.orders (status) WHERE status <> 'delivered';
+CREATE INDEX orders_metadata_idx   ON shop.orders USING GIN (metadata jsonb_path_ops);
+
+CREATE TRIGGER orders_set_updated_at
+BEFORE UPDATE ON shop.orders
+FOR EACH ROW EXECUTE FUNCTION shop.tg_set_updated_at();
+
+-- ---- order items ------------------------------------------------------------
+CREATE TABLE shop.order_items (
+    id              BIGSERIAL PRIMARY KEY,
+    order_id        UUID NOT NULL,
+    order_created_at TIMESTAMPTZ NOT NULL,
+    variant_id      UUID NOT NULL REFERENCES shop.product_variants(id) ON DELETE RESTRICT,
+    quantity        INTEGER NOT NULL CHECK (quantity > 0),
+    unit_price      shop.positive_numeric NOT NULL,
+    line_total      shop.positive_numeric GENERATED ALWAYS AS (quantity * unit_price) STORED,
+    FOREIGN KEY (order_id, order_created_at)
+        REFERENCES shop.orders(id, created_at) ON DELETE CASCADE
+);
+
+CREATE INDEX order_items_order_idx ON shop.order_items (order_id);
+
+-- ---- payments ---------------------------------------------------------------
+CREATE TABLE shop.payments (
+    id              UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    order_id        UUID NOT NULL,
+    order_created_at TIMESTAMPTZ NOT NULL,
+    method          shop.payment_method NOT NULL,
+    amount          shop.positive_numeric NOT NULL,
+    currency        CHAR(3) NOT NULL DEFAULT 'USD',
+    provider_ref    TEXT,
+    succeeded       BOOLEAN NOT NULL DEFAULT FALSE,
+    raw_response    JSONB,
+    paid_at         TIMESTAMPTZ,
+    FOREIGN KEY (order_id, order_created_at)
+        REFERENCES shop.orders(id, created_at) ON DELETE CASCADE
+);
+
+CREATE INDEX payments_order_idx ON shop.payments (order_id);
+
+-- ---- reviews ----------------------------------------------------------------
+CREATE TABLE shop.reviews (
+    id              UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    product_id      UUID NOT NULL REFERENCES shop.products(id) ON DELETE CASCADE,
+    user_id         UUID NOT NULL REFERENCES shop.users(id) ON DELETE CASCADE,
+    rating          SMALLINT NOT NULL CHECK (rating BETWEEN 1 AND 5),
+    title           VARCHAR(200),
+    body            TEXT,
+    body_embedding  VECTOR(768),  -- smaller embedding for review text
+    helpful_count   INTEGER NOT NULL DEFAULT 0,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE (product_id, user_id)
+);
+
+CREATE INDEX reviews_product_idx ON shop.reviews (product_id, created_at DESC);
+CREATE INDEX reviews_embedding_ivfflat_idx
+    ON shop.reviews
+    USING ivfflat (body_embedding vector_l2_ops)
+    WITH (lists = 100);
+
+-- ---- wishlists (many-to-many) -----------------------------------------------
+CREATE TABLE shop.wishlists (
+    user_id         UUID NOT NULL REFERENCES shop.users(id) ON DELETE CASCADE,
+    product_id      UUID NOT NULL REFERENCES shop.products(id) ON DELETE CASCADE,
+    added_at        TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    note            TEXT,
+    PRIMARY KEY (user_id, product_id)
+);
+
+-- ---- coupons / discounts ----------------------------------------------------
+CREATE TABLE shop.coupons (
+    code            VARCHAR(40) PRIMARY KEY,
+    description     TEXT,
+    percent_off     NUMERIC(5, 2) CHECK (percent_off IS NULL OR percent_off BETWEEN 0 AND 100),
+    amount_off      shop.positive_numeric,
+    valid_from      TIMESTAMPTZ NOT NULL,
+    valid_until     TIMESTAMPTZ NOT NULL,
+    max_redemptions INTEGER,
+    redeemed_count  INTEGER NOT NULL DEFAULT 0,
+    constraints     JSONB NOT NULL DEFAULT '{}'::JSONB,
+    CONSTRAINT coupon_one_discount CHECK (
+        (percent_off IS NOT NULL)::INT + (amount_off IS NOT NULL)::INT = 1
+    ),
+    CONSTRAINT coupon_validity CHECK (valid_until > valid_from)
+);
+
+-- exclusion constraint: no overlapping global "everyone" coupons with same code prefix
+-- (illustrative use of EXCLUDE)
+CREATE TABLE shop.promotions (
+    id              SERIAL PRIMARY KEY,
+    name            VARCHAR(120) NOT NULL,
+    category_id     INTEGER REFERENCES shop.categories(id) ON DELETE CASCADE,
+    during          TSTZRANGE NOT NULL,
+    discount_pct    NUMERIC(5, 2) NOT NULL CHECK (discount_pct BETWEEN 0 AND 100),
+    EXCLUDE USING gist (
+        category_id WITH =,
+        during      WITH &&
+    )
+);
+
+-- ============================================================================
+-- Audit / history
+-- ============================================================================
+CREATE TABLE audit.event_log (
+    id              BIGSERIAL PRIMARY KEY,
+    table_name      TEXT NOT NULL,
+    row_pk          TEXT NOT NULL,
+    operation       CHAR(1) NOT NULL CHECK (operation IN ('I','U','D')),
+    actor           UUID,
+    diff            JSONB,
+    occurred_at     TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE OR REPLACE FUNCTION audit.tg_record_change()
+RETURNS TRIGGER LANGUAGE plpgsql AS $$
+DECLARE
+    v_pk  TEXT;
+    v_op  CHAR(1);
+    v_diff JSONB;
+BEGIN
+    IF (TG_OP = 'INSERT') THEN
+        v_op := 'I';
+        v_pk := COALESCE(NEW.id::TEXT, '');
+        v_diff := to_jsonb(NEW);
+    ELSIF (TG_OP = 'UPDATE') THEN
+        v_op := 'U';
+        v_pk := COALESCE(NEW.id::TEXT, '');
+        v_diff := jsonb_build_object('old', to_jsonb(OLD), 'new', to_jsonb(NEW));
+    ELSE
+        v_op := 'D';
+        v_pk := COALESCE(OLD.id::TEXT, '');
+        v_diff := to_jsonb(OLD);
+    END IF;
+
+    INSERT INTO audit.event_log (table_name, row_pk, operation, diff)
+    VALUES (TG_TABLE_SCHEMA || '.' || TG_TABLE_NAME, v_pk, v_op, v_diff);
+
+    RETURN COALESCE(NEW, OLD);
+END;
+$$;
+
+CREATE TRIGGER orders_audit
+AFTER INSERT OR UPDATE OR DELETE ON shop.orders
+FOR EACH ROW EXECUTE FUNCTION audit.tg_record_change();
+
+CREATE TRIGGER products_audit
+AFTER INSERT OR UPDATE OR DELETE ON shop.products
+FOR EACH ROW EXECUTE FUNCTION audit.tg_record_change();
+
+-- ============================================================================
+-- Views and materialized views
+-- ============================================================================
+CREATE VIEW shop.v_product_listing AS
+SELECT
+    p.id,
+    p.sku,
+    p.name,
+    p.price,
+    p.currency,
+    c.name        AS category,
+    v.business_name AS vendor,
+    COALESCE(AVG(r.rating), 0)::NUMERIC(3,2) AS avg_rating,
+    COUNT(r.id)   AS review_count
+FROM shop.products p
+LEFT JOIN shop.categories c ON c.id = p.category_id
+LEFT JOIN shop.vendors v    ON v.user_id = p.vendor_id
+LEFT JOIN shop.reviews r    ON r.product_id = p.id
+WHERE p.is_published
+GROUP BY p.id, c.name, v.business_name;
+
+CREATE MATERIALIZED VIEW analytics.mv_daily_sales AS
+SELECT
+    DATE_TRUNC('day', o.created_at)::DATE AS sale_day,
+    COUNT(*)                              AS order_count,
+    SUM(o.total)                          AS gross_revenue,
+    SUM(o.tax)                            AS total_tax,
+    SUM(o.shipping)                       AS total_shipping
+FROM shop.orders o
+WHERE o.status NOT IN ('cancelled', 'refunded')
+GROUP BY 1
+WITH NO DATA;
+
+CREATE UNIQUE INDEX mv_daily_sales_day_uidx
+    ON analytics.mv_daily_sales (sale_day);
+
+-- ============================================================================
+-- Functions: business logic and vector search helpers
+-- ============================================================================
+
+-- Compute live stock from the ledger
+CREATE OR REPLACE FUNCTION shop.fn_variant_stock(p_variant_id UUID)
+RETURNS INTEGER LANGUAGE sql STABLE AS $$
+    SELECT COALESCE(SUM(delta), 0)::INTEGER
+    FROM shop.inventory_movements
+    WHERE variant_id = p_variant_id;
+$$;
+
+-- Semantic product search using pgvector
+CREATE OR REPLACE FUNCTION shop.fn_search_products_by_embedding(
+    p_query_embedding VECTOR(1536),
+    p_limit           INTEGER DEFAULT 10,
+    p_min_price       NUMERIC DEFAULT NULL,
+    p_max_price       NUMERIC DEFAULT NULL
+)
+RETURNS TABLE (
+    product_id  UUID,
+    name        VARCHAR,
+    price       NUMERIC,
+    similarity  REAL
+)
+LANGUAGE sql STABLE AS $$
+    SELECT
+        p.id,
+        p.name,
+        p.price,
+        1 - (p.description_embedding <=> p_query_embedding) AS similarity
+    FROM shop.products p
+    WHERE p.is_published
+      AND p.description_embedding IS NOT NULL
+      AND (p_min_price IS NULL OR p.price >= p_min_price)
+      AND (p_max_price IS NULL OR p.price <= p_max_price)
+    ORDER BY p.description_embedding <=> p_query_embedding
+    LIMIT p_limit;
+$$;
+
+-- Hybrid search: combine full-text rank and vector similarity
+CREATE OR REPLACE FUNCTION shop.fn_hybrid_search(
+    p_query_text      TEXT,
+    p_query_embedding VECTOR(1536),
+    p_limit           INTEGER DEFAULT 20,
+    p_alpha           REAL    DEFAULT 0.5   -- weight on vector similarity
+)
+RETURNS TABLE (
+    product_id UUID,
+    name       VARCHAR,
+    score      REAL
+)
+LANGUAGE sql STABLE AS $$
+    WITH ranked AS (
+        SELECT
+            p.id,
+            p.name,
+            ts_rank(p.search_doc, plainto_tsquery('english', p_query_text)) AS text_rank,
+            1 - (p.description_embedding <=> p_query_embedding)             AS vec_sim
+        FROM shop.products p
+        WHERE p.is_published
+          AND p.description_embedding IS NOT NULL
+    )
+    SELECT
+        id,
+        name,
+        ((1 - p_alpha) * text_rank + p_alpha * vec_sim)::REAL AS score
+    FROM ranked
+    ORDER BY score DESC
+    LIMIT p_limit;
+$$;
+
+-- Recommend similar products by a seed product's embedding
+CREATE OR REPLACE FUNCTION shop.fn_similar_products(
+    p_product_id UUID,
+    p_limit      INTEGER DEFAULT 5
+)
+RETURNS TABLE (product_id UUID, name VARCHAR, distance REAL)
+LANGUAGE sql STABLE AS $$
+    WITH seed AS (
+        SELECT description_embedding FROM shop.products WHERE id = p_product_id
+    )
+    SELECT p.id, p.name, (p.description_embedding <=> seed.description_embedding)::REAL
+    FROM shop.products p, seed
+    WHERE p.id <> p_product_id
+      AND p.is_published
+      AND p.description_embedding IS NOT NULL
+    ORDER BY p.description_embedding <=> seed.description_embedding
+    LIMIT p_limit;
+$$;
+
+-- ============================================================================
+-- Row Level Security: customers can only see their own orders
+-- ============================================================================
+ALTER TABLE shop.orders ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY orders_owner_select ON shop.orders
+    FOR SELECT
+    USING (user_id::TEXT = current_setting('app.current_user_id', TRUE));
+
+CREATE POLICY orders_admin_all ON shop.orders
+    FOR ALL
+    USING (current_setting('app.current_user_role', TRUE) = 'admin');
+
+-- ============================================================================
+-- Sample data
+-- ============================================================================
+INSERT INTO shop.users (id, email, password_hash, full_name, role) VALUES
+    ('11111111-1111-1111-1111-111111111111', '[email protected]', crypt('admin', gen_salt('bf')), 'Site Admin', 'admin'),
+    ('22222222-2222-2222-2222-222222222222', '[email protected]',  crypt('hunter2', gen_salt('bf')), 'Alice Andersson', 'customer'),
+    ('33333333-3333-3333-3333-333333333333', '[email protected]',    crypt('secret', gen_salt('bf')), 'Bob Bergman', 'vendor');
+
+INSERT INTO shop.vendors (user_id, business_name, approved_at)
+VALUES ('33333333-3333-3333-3333-333333333333', 'Bergman Gadgets AB', CURRENT_TIMESTAMP);
+
+INSERT INTO shop.categories (id, parent_id, name, slug) VALUES
+    (1, NULL, 'Electronics',    'electronics'),
+    (2, 1,    'Audio',          'audio'),
+    (3, 1,    'Wearables',      'wearables'),
+    (4, NULL, 'Home & Kitchen', 'home-kitchen');
+
+SELECT setval(pg_get_serial_sequence('shop.categories', 'id'), 4);
+
+INSERT INTO shop.products (id, vendor_id, category_id, sku, name, description, price, tags, is_published)
+VALUES
+    ('aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
+     '33333333-3333-3333-3333-333333333333', 2, 'AUD-HP-001',
+     'Noise-Cancelling Headphones',
+     'Over-ear wireless headphones with adaptive noise cancellation and 40-hour battery life.',
+     249.00, ARRAY['audio','bluetooth','wireless'], TRUE),
+    ('bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
+     '33333333-3333-3333-3333-333333333333', 3, 'WEA-WATCH-7',
+     'Smart Fitness Watch',
+     'Heart rate, GPS, and sleep tracking with a 7-day battery in a lightweight titanium body.',
+     399.00, ARRAY['fitness','wearable','gps'], TRUE);
+
+INSERT INTO shop.product_variants (id, product_id, sku, option_values, stock_qty) VALUES
+    ('cccccccc-cccc-cccc-cccc-cccccccccccc',
+     'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', 'AUD-HP-001-BLK',
+     '{"color":"black"}'::JSONB, 25),
+    ('dddddddd-dddd-dddd-dddd-dddddddddddd',
+     'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', 'AUD-HP-001-WHT',
+     '{"color":"white"}'::JSONB, 10),
+    ('eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee',
+     'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb', 'WEA-WATCH-7-42',
+     '{"size":"42mm"}'::JSONB, 15);
+
+INSERT INTO shop.inventory_movements (variant_id, delta, reason)
+VALUES
+    ('cccccccc-cccc-cccc-cccc-cccccccccccc', 25, 'initial_stock'),
+    ('dddddddd-dddd-dddd-dddd-dddddddddddd', 10, 'initial_stock'),
+    ('eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee', 15, 'initial_stock');
+
+-- Example order using the partition for 2026
+INSERT INTO shop.orders (id, user_id, status, subtotal, tax, shipping, total, currency, created_at, placed_at)
+VALUES
+    ('99999999-9999-9999-9999-999999999999',
+     '22222222-2222-2222-2222-222222222222',
+     'paid', 249.00, 24.90, 9.00, 282.90, 'USD',
+     '2026-03-15 10:00:00+00', '2026-03-15 10:01:00+00');
+
+INSERT INTO shop.order_items (order_id, order_created_at, variant_id, quantity, unit_price)
+VALUES ('99999999-9999-9999-9999-999999999999', '2026-03-15 10:00:00+00',
+        'cccccccc-cccc-cccc-cccc-cccccccccccc', 1, 249.00);
+
+-- ============================================================================
+-- Example queries (kept as comments)
+-- ============================================================================
+-- 1. Nearest-neighbour semantic search:
+--    SELECT * FROM shop.fn_search_products_by_embedding('[0.01, 0.02, ...]'::vector, 10);
+--
+-- 2. Hybrid lexical + vector:
+--    SELECT * FROM shop.fn_hybrid_search('wireless headphones', '[0.01,...]'::vector, 20, 0.6);
+--
+-- 3. Recursive category tree:
+--    WITH RECURSIVE tree AS (
+--        SELECT id, parent_id, name, 1 AS depth FROM shop.categories WHERE parent_id IS NULL
+--        UNION ALL
+--        SELECT c.id, c.parent_id, c.name, t.depth + 1
+--        FROM shop.categories c JOIN tree t ON c.parent_id = t.id
+--    ) SELECT * FROM tree ORDER BY depth, name;
+--
+-- 4. Refresh sales rollup:
+--    REFRESH MATERIALIZED VIEW CONCURRENTLY analytics.mv_daily_sales;