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

Store Operations Expansion Migration Plan

Overview

Objective: Expand the admin "Store Operations" section to provide comprehensive store storefront management capabilities, allowing administrators to manage store 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 "Store Operations" section (formerly "Product Catalog") with:

Feature	Status	Description
Marketplace Products	✅ Complete	View/manage products from marketplace imports
Store Products	✅ Complete	View/manage store-specific products
Customers	✅ Complete	Customer management (moved from Platform Admin)
Inventory	✅ Complete	Admin API + UI with stock adjustments
Orders	✅ Complete	Order management, status updates, fulfillment
Shipping	🔲 Planned	Tracking, carriers, shipping rules

---

Target Architecture

Admin Sidebar Structure

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

Design Principles

1. Store Selection Pattern: All pages should support store filtering/selection
2. Bulk Operations: Admin should be able to perform bulk actions across stores
3. Audit Trail: All admin actions on behalf of stores 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 "Store Operations"
• Update section key from productCatalog to storeOps
• Move Customers from "Platform Administration" to "Store 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 stores
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,
    store_id INTEGER NOT NULL REFERENCES stores(id),
    product_id INTEGER NOT NULL REFERENCES store_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,
    store_id INTEGER NOT NULL REFERENCES stores(id),
    product_id INTEGER REFERENCES store_products(id),  -- NULL = store 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 stores
GET	/api/v1/admin/inventory/stores/{id}	Store-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 store 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 stores
Order Details	High	Full order information and history
Status Updates	High	Change order status on behalf of store
Order Notes	Medium	Internal notes for admin/store 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 store
    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 store
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()
);

-- Store carrier configuration
CREATE TABLE store_shipping_carriers (
    id SERIAL PRIMARY KEY,
    store_id INTEGER NOT NULL REFERENCES stores(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(store_id, carrier_id)
);

-- Shipping rules
CREATE TABLE shipping_rules (
    id SERIAL PRIMARY KEY,
    store_id INTEGER NOT NULL REFERENCES stores(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/stores/{id}	Store shipping config
PATCH	/api/v1/admin/shipping/stores/{id}	Update store 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 Store Operations
• Update Alpine.js configuration
• Create migration plan documentation

Phase 2: Inventory ✅

• Database migrations (inventory table exists)
• Create InventoryService
• API endpoints
• Admin inventory page
• Stock adjustment modal
• Low stock alerts (via filtering)

Phase 3: Orders ✅

• Database migrations (orders table exists)
• Add admin methods to OrderService
• 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
• Store 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