orion/docs/development/migration/vendor-operations-expansion.md

Vendor Operations Expansion Migration Plan

Overview

Objective: Expand the admin "Vendor Operations" section to provide comprehensive vendor storefront management capabilities, allowing administrators to manage vendor operations on their behalf.

Scope: Products, Inventory, Orders, Shipping, and Customers management from the admin panel.

Status: In Progress

---

Current State

The admin sidebar has a "Vendor Operations" section (formerly "Product Catalog") with:

Feature	Status	Description
Marketplace Products	✅ Complete	View/manage products from marketplace imports
Vendor Products	✅ Complete	View/manage vendor-specific products
Customers	✅ Complete	Customer management (moved from Platform Admin)
Inventory	🔲 Planned	Stock levels, adjustments, low-stock alerts
Orders	🔲 Planned	Order management, status updates, fulfillment
Shipping	🔲 Planned	Tracking, carriers, shipping rules

---

Target Architecture

Admin Sidebar Structure

Vendor Operations
├── Marketplace Products  (/admin/marketplace-products)
├── Vendor Products       (/admin/vendor-products)
├── Customers             (/admin/customers)
├── Inventory             (/admin/inventory)        [Phase 2]
├── Orders                (/admin/orders)           [Phase 3]
└── Shipping              (/admin/shipping)         [Phase 4]

Design Principles

1. Vendor Selection Pattern: All pages should support vendor filtering/selection
2. Bulk Operations: Admin should be able to perform bulk actions across vendors
3. Audit Trail: All admin actions on behalf of vendors should be logged
4. Permission Granularity: Future support for role-based access to specific features

---

Phase 1: Foundation (Completed)

1.1 Sidebar Restructure ✅

• Rename "Product Catalog" to "Vendor Operations"
• Update section key from productCatalog to vendorOps
• Move Customers from "Platform Administration" to "Vendor Operations"
• Add placeholder comments for future menu items

1.2 Files Modified

File	Changes
app/templates/admin/partials/sidebar.html	Section rename, Customers move
static/admin/js/init-alpine.js	Section key update, page mapping

---

Phase 2: Inventory Management (Planned)

2.1 Features

Feature	Priority	Description
Stock Overview	High	Dashboard showing stock levels across vendors
Stock Adjustments	High	Manual stock adjustments with reason codes
Low Stock Alerts	Medium	Configurable thresholds and notifications
Stock History	Medium	Audit trail of all stock changes
Bulk Import/Export	Low	CSV import/export for stock levels

2.2 Database Changes

-- New table for stock adjustment history
CREATE TABLE inventory_adjustments (
    id SERIAL PRIMARY KEY,
    vendor_id INTEGER NOT NULL REFERENCES vendors(id),
    product_id INTEGER NOT NULL REFERENCES vendor_products(id),
    adjustment_type VARCHAR(50) NOT NULL,  -- 'manual', 'sale', 'return', 'correction'
    quantity_change INTEGER NOT NULL,
    quantity_before INTEGER NOT NULL,
    quantity_after INTEGER NOT NULL,
    reason VARCHAR(500),
    adjusted_by INTEGER REFERENCES users(id),
    created_at TIMESTAMP DEFAULT NOW()
);

-- Low stock alert configuration
CREATE TABLE low_stock_thresholds (
    id SERIAL PRIMARY KEY,
    vendor_id INTEGER NOT NULL REFERENCES vendors(id),
    product_id INTEGER REFERENCES vendor_products(id),  -- NULL = vendor default
    threshold INTEGER NOT NULL DEFAULT 10,
    notification_enabled BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

2.3 API Endpoints

Method	Endpoint	Description
GET	/api/v1/admin/inventory	List inventory across vendors
GET	/api/v1/admin/inventory/vendors/{id}	Vendor-specific inventory
POST	/api/v1/admin/inventory/adjust	Create stock adjustment
GET	/api/v1/admin/inventory/low-stock	Low stock alerts
PATCH	/api/v1/admin/inventory/thresholds	Update alert thresholds

2.4 Frontend Components

Component	Description
inventory.html	Main inventory page with vendor selector
inventory.js	Alpine.js controller
inventory-table.html	Stock levels table partial
adjustment-modal.html	Stock adjustment form modal

---

Phase 3: Order Management (Planned)

3.1 Features

Feature	Priority	Description
Order List	High	View all orders across vendors
Order Details	High	Full order information and history
Status Updates	High	Change order status on behalf of vendor
Order Notes	Medium	Internal notes for admin/vendor communication
Refund Processing	Medium	Handle refunds and cancellations
Order Export	Low	Export orders to CSV/Excel

3.2 Database Changes

-- Admin notes on orders
CREATE TABLE order_admin_notes (
    id SERIAL PRIMARY KEY,
    order_id INTEGER NOT NULL REFERENCES orders(id),
    admin_id INTEGER NOT NULL REFERENCES users(id),
    note TEXT NOT NULL,
    is_internal BOOLEAN DEFAULT true,  -- false = visible to vendor
    created_at TIMESTAMP DEFAULT NOW()
);

-- Order status change history
CREATE TABLE order_status_history (
    id SERIAL PRIMARY KEY,
    order_id INTEGER NOT NULL REFERENCES orders(id),
    previous_status VARCHAR(50),
    new_status VARCHAR(50) NOT NULL,
    changed_by INTEGER REFERENCES users(id),
    change_reason VARCHAR(500),
    created_at TIMESTAMP DEFAULT NOW()
);

3.3 API Endpoints

Method	Endpoint	Description
GET	/api/v1/admin/orders	List all orders with filters
GET	/api/v1/admin/orders/{id}	Order details
PATCH	/api/v1/admin/orders/{id}/status	Update order status
POST	/api/v1/admin/orders/{id}/notes	Add admin note
POST	/api/v1/admin/orders/{id}/refund	Process refund

---

Phase 4: Shipping Management (Planned)

4.1 Features

Feature	Priority	Description
Shipment Tracking	High	Track shipments across carriers
Carrier Management	Medium	Configure available carriers per vendor
Shipping Rules	Medium	Weight-based, zone-based pricing rules
Label Generation	Low	Integration with carrier APIs
Delivery Reports	Low	Delivery success rates, timing analytics

4.2 Database Changes

-- Shipping carriers
CREATE TABLE shipping_carriers (
    id SERIAL PRIMARY KEY,
    code VARCHAR(50) UNIQUE NOT NULL,  -- 'dhl', 'ups', 'post_lu'
    name VARCHAR(100) NOT NULL,
    tracking_url_template VARCHAR(500),
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Vendor carrier configuration
CREATE TABLE vendor_shipping_carriers (
    id SERIAL PRIMARY KEY,
    vendor_id INTEGER NOT NULL REFERENCES vendors(id),
    carrier_id INTEGER NOT NULL REFERENCES shipping_carriers(id),
    account_number VARCHAR(100),
    is_default BOOLEAN DEFAULT false,
    is_enabled BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(vendor_id, carrier_id)
);

-- Shipping rules
CREATE TABLE shipping_rules (
    id SERIAL PRIMARY KEY,
    vendor_id INTEGER NOT NULL REFERENCES vendors(id),
    name VARCHAR(100) NOT NULL,
    rule_type VARCHAR(50) NOT NULL,  -- 'weight', 'price', 'zone'
    conditions JSONB NOT NULL,
    price DECIMAL(10, 2) NOT NULL,
    is_active BOOLEAN DEFAULT true,
    priority INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT NOW()
);

4.3 API Endpoints

Method	Endpoint	Description
GET	/api/v1/admin/shipping/carriers	List carriers
GET	/api/v1/admin/shipping/vendors/{id}	Vendor shipping config
PATCH	/api/v1/admin/shipping/vendors/{id}	Update vendor shipping
GET	/api/v1/admin/shipping/rules	List shipping rules
POST	/api/v1/admin/shipping/rules	Create shipping rule

---

Implementation Checklist

Phase 1: Foundation ✅

• Sidebar restructure
• Move Customers to Vendor Operations
• Update Alpine.js configuration
• Create migration plan documentation

Phase 2: Inventory

• Database migrations
• Create InventoryService
• API endpoints
• Admin inventory page
• Stock adjustment modal
• Low stock alerts

Phase 3: Orders

• Database migrations
• Create AdminOrderService
• API endpoints
• Admin orders page
• Order detail view
• Status update functionality

Phase 4: Shipping

• Database migrations
• Create ShippingService
• API endpoints
• Admin shipping page
• Carrier configuration
• Shipping rules builder

---

Testing Requirements

Unit Tests

• Service layer tests for each new service
• Model validation tests

Integration Tests

• API endpoint tests with authentication
• Database constraint tests
• Transaction rollback tests

E2E Tests (Future)

• Admin workflow tests
• Vendor operation scenarios

---

Rollback Plan

Each phase is independent and can be rolled back:

1. Database: Each phase has its own migration file with down migration
2. API: New endpoints don't affect existing ones
3. Frontend: Menu items can be hidden by commenting out in sidebar.html

---

Related Documentation

• Database Migrations Guide
• Architecture Rules
• Naming Conventions