docs: add Vendor Operations expansion migration plan

- Create comprehensive migration plan for Vendor Operations expansion - Document planned phases: Inventory, Orders, Shipping management - Include database schema designs and API endpoint specifications - Move Customers from Platform Administration to Vendor Operations - Update mkdocs navigation with new migration document 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-14 21:51:05 +01:00
parent 2287204bfd
commit dc9aa0f769
4 changed files with 313 additions and 3 deletions
--- a/app/templates/admin/partials/sidebar.html
+++ b/app/templates/admin/partials/sidebar.html
@@ -72,7 +72,6 @@
        {{ menu_item('companies', '/admin/companies', 'office-building', 'Companies') }}
        {{ menu_item('vendors', '/admin/vendors', 'shopping-bag', 'Vendors') }}
        {{ menu_item('users', '/admin/users', 'users', 'Users') }}
-        {{ menu_item('customers', '/admin/customers', 'user-group', 'Customers') }}
    {% endcall %}

    <!-- Vendor Operations Section -->
@@ -80,6 +79,7 @@
    {% call section_content('vendorOps') %}
        {{ menu_item('marketplace-products', '/admin/marketplace-products', 'database', 'Marketplace Products') }}
        {{ menu_item('vendor-products', '/admin/vendor-products', 'cube', 'Vendor Products') }}
+        {{ menu_item('customers', '/admin/customers', 'user-group', 'Customers') }}
        {# Future items - uncomment when implemented:
        {{ menu_item('inventory', '/admin/inventory', 'archive', 'Inventory') }}
        {{ menu_item('orders', '/admin/orders', 'clipboard-list', 'Orders') }}
--- a/docs/development/migration/vendor-operations-expansion.md
+++ b/docs/development/migration/vendor-operations-expansion.md
@@ -0,0 +1,309 @@
+# 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 ✅
+
+- [x] Rename "Product Catalog" to "Vendor Operations"
+- [x] Update section key from `productCatalog` to `vendorOps`
+- [x] Move Customers from "Platform Administration" to "Vendor Operations"
+- [x] 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
+
+```sql
+-- 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
+
+```sql
+-- 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
+
+```sql
+-- 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 ✅
+- [x] Sidebar restructure
+- [x] Move Customers to Vendor Operations
+- [x] Update Alpine.js configuration
+- [x] 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](database-migrations.md)
+- [Architecture Rules](../architecture-rules.md)
+- [Naming Conventions](../naming-conventions.md)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -132,6 +132,7 @@ nav:
      - Vendor Contact Inheritance: development/migration/vendor-contact-inheritance.md
      - Multi-Marketplace Product Architecture: development/migration/multi-marketplace-product-architecture.md
      - Product Migration Database Changes: development/migration/product-migration-database-changes.md
+      - Vendor Operations Expansion: development/migration/vendor-operations-expansion.md
    - Seed Scripts Audit: development/seed-scripts-audit.md
    - Database Seeder:
      - Documentation: development/database-seeder/database-seeder-documentation.md
--- a/static/admin/js/init-alpine.js
+++ b/static/admin/js/init-alpine.js
@@ -63,10 +63,10 @@ function data() {
    companies: 'platformAdmin',
    vendors: 'platformAdmin',
    users: 'platformAdmin',
-    customers: 'platformAdmin',
-    // Vendor Operations (Products, Inventory, Orders, Shipping)
+    // Vendor Operations (Products, Customers, Inventory, Orders, Shipping)
    'marketplace-products': 'vendorOps',
    'vendor-products': 'vendorOps',
+    customers: 'vendorOps',
    // Future: inventory, orders, shipping will map to 'vendorOps'
    // Marketplace
    'marketplace-letzshop': 'marketplace',