sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add Vendor Operations expansion migration plan

Browse Source 
- 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>
This commit is contained in:
Samir Boulahtit
2025-12-14 21:51:05 +01:00
parent 2287204bfd
commit dc9aa0f769
4 changed files with 313 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

309
docs/development/migration/vendor-operations-expansion.md Normal file
View File

@@ -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)