From dc9aa0f7694893af4e1e4282d8c1a5df4b592f71 Mon Sep 17 00:00:00 2001 From: Samir Boulahtit Date: Sun, 14 Dec 2025 21:51:05 +0100 Subject: [PATCH] docs: add Vendor Operations expansion migration plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- app/templates/admin/partials/sidebar.html | 2 +- .../migration/vendor-operations-expansion.md | 309 ++++++++++++++++++ mkdocs.yml | 1 + static/admin/js/init-alpine.js | 4 +- 4 files changed, 313 insertions(+), 3 deletions(-) create mode 100644 docs/development/migration/vendor-operations-expansion.md diff --git a/app/templates/admin/partials/sidebar.html b/app/templates/admin/partials/sidebar.html index 47f12dc2..7036713d 100644 --- 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 %} @@ -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') }} diff --git a/docs/development/migration/vendor-operations-expansion.md b/docs/development/migration/vendor-operations-expansion.md new file mode 100644 index 00000000..524e2723 --- /dev/null +++ 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) diff --git a/mkdocs.yml b/mkdocs.yml index c3b69dae..25cd49dc 100644 --- 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 diff --git a/static/admin/js/init-alpine.js b/static/admin/js/init-alpine.js index 241f3aed..78e0b839 100644 --- 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',