- Approx. {{ app(\Core\Commerce\Services\CurrencyService::class)->format($this->baseTotal, $this->baseCurrency) }} + Approx. {{ app(\Core\Mod\Commerce\Services\CurrencyService::class)->format($this->baseTotal, $this->baseCurrency) }} at current rates
@endif diff --git a/View/Modal/Admin/CouponManager.php b/View/Modal/Admin/CouponManager.php index 0e78854..b106e45 100644 --- a/View/Modal/Admin/CouponManager.php +++ b/View/Modal/Admin/CouponManager.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Core\Commerce\View\Modal\Admin; +namespace Core\Mod\Commerce\View\Modal\Admin; use Core\Mod\Tenant\Models\Package; use Livewire\Attributes\Computed; @@ -10,8 +10,8 @@ use Livewire\Attributes\Layout; use Livewire\Attributes\Title; use Livewire\Component; use Livewire\WithPagination; -use Core\Commerce\Models\Coupon; -use Core\Commerce\Services\CouponService; +use Core\Mod\Commerce\Models\Coupon; +use Core\Mod\Commerce\Services\CouponService; #[Layout('hub::admin.layouts.app')] #[Title('Coupons')] diff --git a/View/Modal/Admin/CreditNoteManager.php b/View/Modal/Admin/CreditNoteManager.php index d1b5215..8c1cb55 100644 --- a/View/Modal/Admin/CreditNoteManager.php +++ b/View/Modal/Admin/CreditNoteManager.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Core\Commerce\View\Modal\Admin; +namespace Core\Mod\Commerce\View\Modal\Admin; use Core\Mod\Tenant\Models\User; use Core\Mod\Tenant\Models\Workspace; @@ -10,8 +10,8 @@ use Livewire\Attributes\Computed; use Livewire\Attributes\Title; use Livewire\Component; use Livewire\WithPagination; -use Core\Commerce\Models\CreditNote; -use Core\Commerce\Services\CreditNoteService; +use Core\Mod\Commerce\Models\CreditNote; +use Core\Mod\Commerce\Services\CreditNoteService; #[Title('Credit Notes')] class CreditNoteManager extends Component diff --git a/View/Modal/Admin/Dashboard.php b/View/Modal/Admin/Dashboard.php index 7cf84d0..662598d 100644 --- a/View/Modal/Admin/Dashboard.php +++ b/View/Modal/Admin/Dashboard.php @@ -2,11 +2,11 @@ declare(strict_types=1); -namespace Core\Commerce\View\Modal\Admin; +namespace Core\Mod\Commerce\View\Modal\Admin; -use Core\Commerce\Models\Coupon; -use Core\Commerce\Models\Order; -use Core\Commerce\Models\Subscription; +use Core\Mod\Commerce\Models\Coupon; +use Core\Mod\Commerce\Models\Order; +use Core\Mod\Commerce\Models\Subscription; use Illuminate\Contracts\View\View; use Illuminate\Support\Facades\DB; use Livewire\Attributes\Computed; diff --git a/View/Modal/Admin/EntityManager.php b/View/Modal/Admin/EntityManager.php index 34abb52..15cd03c 100644 --- a/View/Modal/Admin/EntityManager.php +++ b/View/Modal/Admin/EntityManager.php @@ -2,9 +2,9 @@ declare(strict_types=1); -namespace Core\Commerce\View\Modal\Admin; +namespace Core\Mod\Commerce\View\Modal\Admin; -use Core\Commerce\Models\Entity; +use Core\Mod\Commerce\Models\Entity; use Core\Mod\Tenant\Models\Workspace; use Livewire\Attributes\Layout; use Livewire\Component; diff --git a/View/Modal/Admin/OrderManager.php b/View/Modal/Admin/OrderManager.php index 936c717..f680188 100644 --- a/View/Modal/Admin/OrderManager.php +++ b/View/Modal/Admin/OrderManager.php @@ -2,9 +2,9 @@ declare(strict_types=1); -namespace Core\Commerce\View\Modal\Admin; +namespace Core\Mod\Commerce\View\Modal\Admin; -use Core\Commerce\Models\Order; +use Core\Mod\Commerce\Models\Order; use Core\Mod\Tenant\Models\Workspace; use Livewire\Attributes\Computed; use Livewire\Attributes\Title; diff --git a/View/Modal/Admin/PermissionMatrixManager.php b/View/Modal/Admin/PermissionMatrixManager.php index d978d00..bb4ce23 100644 --- a/View/Modal/Admin/PermissionMatrixManager.php +++ b/View/Modal/Admin/PermissionMatrixManager.php @@ -2,13 +2,13 @@ declare(strict_types=1); -namespace Core\Commerce\View\Modal\Admin; +namespace Core\Mod\Commerce\View\Modal\Admin; -use Core\Commerce\Models\Entity; -use Core\Commerce\Models\PermissionMatrix; -use Core\Commerce\Models\PermissionRequest; -use Core\Commerce\Services\PermissionLockedException; -use Core\Commerce\Services\PermissionMatrixService; +use Core\Mod\Commerce\Models\Entity; +use Core\Mod\Commerce\Models\PermissionMatrix; +use Core\Mod\Commerce\Models\PermissionRequest; +use Core\Mod\Commerce\Services\PermissionLockedException; +use Core\Mod\Commerce\Services\PermissionMatrixService; use Livewire\Attributes\Layout; use Livewire\Component; use Livewire\WithPagination; diff --git a/View/Modal/Admin/ProductManager.php b/View/Modal/Admin/ProductManager.php index f7b71d4..89e3f40 100644 --- a/View/Modal/Admin/ProductManager.php +++ b/View/Modal/Admin/ProductManager.php @@ -2,12 +2,12 @@ declare(strict_types=1); -namespace Core\Commerce\View\Modal\Admin; +namespace Core\Mod\Commerce\View\Modal\Admin; -use Core\Commerce\Models\Entity; -use Core\Commerce\Models\Product; -use Core\Commerce\Models\ProductAssignment; -use Core\Commerce\Services\ProductCatalogService; +use Core\Mod\Commerce\Models\Entity; +use Core\Mod\Commerce\Models\Product; +use Core\Mod\Commerce\Models\ProductAssignment; +use Core\Mod\Commerce\Services\ProductCatalogService; use Illuminate\Contracts\View\View; use Livewire\Attributes\Computed; use Livewire\Attributes\Url; diff --git a/View/Modal/Admin/ReferralManager.php b/View/Modal/Admin/ReferralManager.php index 4c2e88b..bf41f20 100644 --- a/View/Modal/Admin/ReferralManager.php +++ b/View/Modal/Admin/ReferralManager.php @@ -2,18 +2,18 @@ declare(strict_types=1); -namespace Core\Commerce\View\Modal\Admin; +namespace Core\Mod\Commerce\View\Modal\Admin; use Livewire\Attributes\Computed; use Livewire\Attributes\Layout; use Livewire\Attributes\Title; use Livewire\Component; use Livewire\WithPagination; -use Core\Commerce\Models\Referral; -use Core\Commerce\Models\ReferralCode; -use Core\Commerce\Models\ReferralCommission; -use Core\Commerce\Models\ReferralPayout; -use Core\Commerce\Services\ReferralService; +use Core\Mod\Commerce\Models\Referral; +use Core\Mod\Commerce\Models\ReferralCode; +use Core\Mod\Commerce\Models\ReferralCommission; +use Core\Mod\Commerce\Models\ReferralPayout; +use Core\Mod\Commerce\Services\ReferralService; /** * Admin dashboard for managing referrals, commissions, and payouts. diff --git a/View/Modal/Admin/SubscriptionManager.php b/View/Modal/Admin/SubscriptionManager.php index f4bff74..afbbdca 100644 --- a/View/Modal/Admin/SubscriptionManager.php +++ b/View/Modal/Admin/SubscriptionManager.php @@ -2,10 +2,10 @@ declare(strict_types=1); -namespace Core\Commerce\View\Modal\Admin; +namespace Core\Mod\Commerce\View\Modal\Admin; -use Core\Commerce\Models\Subscription; -use Core\Commerce\Services\SubscriptionService; +use Core\Mod\Commerce\Models\Subscription; +use Core\Mod\Commerce\Services\SubscriptionService; use Core\Mod\Tenant\Models\Workspace; use Livewire\Attributes\Computed; use Livewire\Attributes\Title; diff --git a/View/Modal/Web/ChangePlan.php b/View/Modal/Web/ChangePlan.php index d7dde8c..8a7e2eb 100644 --- a/View/Modal/Web/ChangePlan.php +++ b/View/Modal/Web/ChangePlan.php @@ -1,6 +1,6 @@ + +Example: +ORGORG-WBUTS-WB500L # Original Organics → Waterbutts → 500L Water Butt +ORGORG-PHONE-WB500L # Same product, telephone channel +DRPSHP-THEIR1-WB500L # Dropshipper's storefront selling our product +``` + +This tracks: +- Where the sale originated +- Which facade/channel +- Back to master SKU + +--- + +## The Permission Matrix (Top-Down Immutable) + +### The Core Concept + +``` +If M1 says "NO" → Everything below is "NO" +If M1 says "YES" → M2 can say "NO" for itself +If M2 says "YES" → M3 can say "NO" for itself + +Permissions cascade DOWN, restrictions are IMMUTABLE from above. +``` + +### Visual Model + +``` + M1 (Master) + ├── can_sell_alcohol: NO ──────────────┐ + ├── can_discount: YES │ + └── can_export: YES │ + │ │ + ┌────────────┼────────────┐ │ + ▼ ▼ ▼ │ + M2-Web M2-Phone M2-Voucher │ + ├── can_sell_alcohol: [LOCKED NO] ◄──────────────┘ + ├── can_discount: NO (restricted self) + └── can_export: YES (inherited) + │ + ▼ + M3-Dropshipper + ├── can_sell_alcohol: [LOCKED NO] (from M1) + ├── can_discount: [LOCKED NO] (from M2) + └── can_export: YES (can restrict to NO) +``` + +### The 3D Matrix + +``` +Dimension 1: Entity Hierarchy (M1 → M2 → M3) +Dimension 2: Permission Keys (can_sell, can_discount, can_export, can_view_cost...) +Dimension 3: Resource Scope (products, orders, customers, reports...) + +Permission = Matrix[Entity][Key][Scope] +``` + +--- + +## The Internal WAF (Request-Level Enforcement) + +> **EXTRACTED:** This section moved to `CORE_BOUNCER_PLAN.md` as a framework-level concern. +> The training mode / request whitelisting system applies to all modules, not just commerce. + +### Every Request is Gated + +```php +// Not just "can user do X" +// But "can THIS REQUEST from THIS ENTITY do THIS ACTION on THIS RESOURCE" + +POST /orders +├── Entity: M2-Web (waterbutts.com) +├── Action: order.create +├── Resource: order +├── Context: { customer_id: 123, products: [...] } +│ +└── Matrix Check: + ├── Does M1 allow M2-Web to create orders? ✓ + ├── Does M2-Web allow this product combination? ✓ + ├── Does customer region allow these products? ✓ + └── ALLOW +``` + +### Training Mode (Dev Mode Learning) + +``` +1. Developer goes to /admin/products +2. Clicks "Create Product" +3. System: "BLOCKED - No permission defined for:" + - Entity: M1-Admin + - Action: product.create + - Route: POST /admin/products + +4. Developer clicks [Allow for M1-Admin] +5. Permission recorded in matrix +6. Continue working + +Result: Complete map of every action in the system +``` + +### Production Mode (Strict Enforcement) + +``` +If permission not in matrix → 403 Forbidden +No exceptions. No fallbacks. No "default allow". + +If it wasn't trained, it doesn't exist. +``` + +--- + +## Laravel Implementation + +### 1. The Entity Hierarchy + +```php +// database/migrations/create_commerce_entities_table.php + +Schema::create('commerce_entities', function (Blueprint $table) { + $table->id(); + $table->string('code', 32)->unique(); // ORGORG, WBUTS, DRPSHP + $table->string('name'); + $table->string('type'); // m1, m2, m3 + + // Hierarchy + $table->foreignId('parent_id')->nullable()->constrained('commerce_entities'); + $table->string('path')->index(); // ORGORG/WBUTS/DRPSHP (materialized path) + $table->integer('depth')->default(0); + + // Settings + $table->json('settings')->nullable(); + $table->boolean('is_active')->default(true); + + $table->timestamps(); +}); + +// Entity types +const TYPE_M1_MASTER = 'm1'; // Master company +const TYPE_M2_FACADE = 'm2'; // Storefront/channel +const TYPE_M3_DROPSHIP = 'm3'; // Dropshipper (inherits, doesn't manage) +``` + +### 2. The Permission Matrix + +```php +// database/migrations/create_permission_matrix_table.php + +Schema::create('permission_matrix', function (Blueprint $table) { + $table->id(); + $table->foreignId('entity_id')->constrained('commerce_entities'); + + // Permission definition + $table->string('key'); // product.create, order.refund + $table->string('scope')->nullable(); // Resource type or specific ID + + // The value + $table->boolean('allowed')->default(false); + $table->boolean('locked')->default(false); // Set by parent, cannot override + + // Audit + $table->string('source'); // 'inherited', 'explicit', 'trained' + $table->foreignId('set_by_entity_id')->nullable(); + $table->timestamp('trained_at')->nullable(); // When it was learned + $table->string('trained_route')->nullable(); // Which route triggered training + + $table->timestamps(); + + $table->unique(['entity_id', 'key', 'scope']); + $table->index(['key', 'scope']); +}); +``` + +### 3. The Request Log (Training Data) + +```php +// database/migrations/create_permission_requests_table.php + +Schema::create('permission_requests', function (Blueprint $table) { + $table->id(); + $table->foreignId('entity_id')->constrained('commerce_entities'); + + // Request details + $table->string('method'); // GET, POST, PUT, DELETE + $table->string('route'); // /admin/products + $table->string('action'); // product.create + $table->string('scope')->nullable(); + + // Context + $table->json('request_data')->nullable(); // Sanitized request params + $table->string('user_agent')->nullable(); + $table->string('ip_address')->nullable(); + + // Result + $table->string('status'); // allowed, denied, pending + $table->boolean('was_trained')->default(false); + + $table->timestamps(); + + $table->index(['entity_id', 'action', 'status']); + $table->index(['status', 'created_at']); +}); +``` + +### 4. The Matrix Service + +```php +// app/Services/Commerce/PermissionMatrixService.php + +namespace App\Services\Commerce; + +use App\Models\Commerce\Entity; +use App\Models\Commerce\PermissionMatrix; +use Illuminate\Http\Request; + +class PermissionMatrixService +{ + protected bool $trainingMode; + + public function __construct() + { + $this->trainingMode = config('commerce.matrix.training_mode', false); + } + + /** + * Check if an entity can perform an action + */ + public function can(Entity $entity, string $key, ?string $scope = null): PermissionResult + { + // Build the hierarchy path (M1 → M2 → M3) + $hierarchy = $this->getHierarchy($entity); + + // Check from top down (M1 first) + foreach ($hierarchy as $ancestor) { + $permission = PermissionMatrix::where('entity_id', $ancestor->id) + ->where('key', $key) + ->where(function ($q) use ($scope) { + $q->whereNull('scope')->orWhere('scope', $scope); + }) + ->first(); + + if ($permission) { + // If locked and denied at this level, everything below is denied + if ($permission->locked && !$permission->allowed) { + return PermissionResult::denied( + reason: "Locked by {$ancestor->name}", + locked_by: $ancestor + ); + } + + // If explicitly denied (not locked), continue checking + if (!$permission->allowed && !$permission->locked) { + return PermissionResult::denied( + reason: "Denied by {$ancestor->name}" + ); + } + } + } + + // Check the entity itself + $ownPermission = PermissionMatrix::where('entity_id', $entity->id) + ->where('key', $key) + ->where(function ($q) use ($scope) { + $q->whereNull('scope')->orWhere('scope', $scope); + }) + ->first(); + + if ($ownPermission) { + return $ownPermission->allowed + ? PermissionResult::allowed() + : PermissionResult::denied(reason: "Denied by own policy"); + } + + // No permission found + return PermissionResult::undefined(key: $key, scope: $scope); + } + + /** + * Gate a request through the matrix + */ + public function gateRequest(Request $request, Entity $entity, string $action): PermissionResult + { + $scope = $this->extractScope($request); + $result = $this->can($entity, $action, $scope); + + // Log the request + $this->logRequest($request, $entity, $action, $scope, $result); + + // Training mode: undefined permissions become pending for approval + if ($result->isUndefined() && $this->trainingMode) { + return PermissionResult::pending( + key: $action, + scope: $scope, + training_url: route('commerce.matrix.train', [ + 'entity' => $entity->id, + 'key' => $action, + 'scope' => $scope, + ]) + ); + } + + // Production mode: undefined = denied + if ($result->isUndefined()) { + return PermissionResult::denied( + reason: "No permission defined for {$action}" + ); + } + + return $result; + } + + /** + * Train a permission (dev mode) + */ + public function train(Entity $entity, string $key, ?string $scope, bool $allow, ?string $route = null): void + { + // Check if parent has locked this + $hierarchy = $this->getHierarchy($entity); + foreach ($hierarchy as $ancestor) { + $parentPerm = PermissionMatrix::where('entity_id', $ancestor->id) + ->where('key', $key) + ->where('locked', true) + ->first(); + + if ($parentPerm && !$parentPerm->allowed) { + throw new PermissionLockedException( + "Cannot train permission '{$key}' - locked by {$ancestor->name}" + ); + } + } + + PermissionMatrix::updateOrCreate( + ['entity_id' => $entity->id, 'key' => $key, 'scope' => $scope], + [ + 'allowed' => $allow, + 'source' => 'trained', + 'trained_at' => now(), + 'trained_route' => $route, + ] + ); + } + + /** + * Lock a permission (cascades down) + */ + public function lock(Entity $entity, string $key, bool $allowed, ?string $scope = null): void + { + // Set on this entity + PermissionMatrix::updateOrCreate( + ['entity_id' => $entity->id, 'key' => $key, 'scope' => $scope], + [ + 'allowed' => $allowed, + 'locked' => true, + 'source' => 'explicit', + 'set_by_entity_id' => $entity->id, + ] + ); + + // Cascade to all descendants + $descendants = Entity::where('path', 'like', $entity->path . '/%')->get(); + foreach ($descendants as $descendant) { + PermissionMatrix::updateOrCreate( + ['entity_id' => $descendant->id, 'key' => $key, 'scope' => $scope], + [ + 'allowed' => $allowed, + 'locked' => true, + 'source' => 'inherited', + 'set_by_entity_id' => $entity->id, + ] + ); + } + } + + protected function getHierarchy(Entity $entity): Collection + { + // Return ancestors from root to parent (not including self) + $path = explode('/', trim($entity->path, '/')); + array_pop(); // Remove self + + return Entity::whereIn('code', $path) + ->orderBy('depth') + ->get(); + } +} +``` + +### 5. The Middleware (WAF Integration) + +```php +// app/Http/Middleware/CommerceMatrixGate.php + +namespace App\Http\Middleware; + +use App\Services\Commerce\PermissionMatrixService; +use Closure; + +class CommerceMatrixGate +{ + public function __construct( + protected PermissionMatrixService $matrix + ) {} + + public function handle(Request $request, Closure $next) + { + $entity = $this->resolveEntity($request); + $action = $this->resolveAction($request); + + if (!$entity || !$action) { + return $next($request); // Not a commerce route + } + + $result = $this->matrix->gateRequest($request, $entity, $action); + + if ($result->isDenied()) { + return response()->json([ + 'error' => 'permission_denied', + 'message' => $result->reason, + 'key' => $action, + ], 403); + } + + if ($result->isPending()) { + // Training mode - show the training UI + if ($request->wantsJson()) { + return response()->json([ + 'error' => 'permission_undefined', + 'message' => 'Permission not yet trained', + 'training_url' => $result->training_url, + 'key' => $result->key, + 'scope' => $result->scope, + ], 428); // Precondition Required + } + + return response()->view('commerce.matrix.train-prompt', [ + 'result' => $result, + 'request' => $request, + 'entity' => $entity, + ], 428); + } + + return $next($request); + } + + protected function resolveAction(Request $request): ?string + { + // Option 1: Route-based action mapping + $route = $request->route(); + if ($route && $action = $route->getAction('matrix_action')) { + return $action; + } + + // Option 2: Controller@method convention + if ($route) { + $controller = class_basename($route->getControllerClass()); + $method = $route->getActionMethod(); + return Str::snake($controller) . '.' . $method; + // ProductController@store → product_controller.store + } + + // Option 3: REST convention + $method = $request->method(); + $resource = $request->segment(2); // /api/products → products + + return match($method) { + 'GET' => "{$resource}.view", + 'POST' => "{$resource}.create", + 'PUT', 'PATCH' => "{$resource}.update", + 'DELETE' => "{$resource}.delete", + default => null, + }; + } +} +``` + +### 6. Route Definition with Matrix Actions + +```php +// routes/commerce.php + +Route::middleware(['auth', 'commerce.matrix'])->prefix('commerce')->group(function () { + + // Explicit action mapping + Route::get('/products', [ProductController::class, 'index']) + ->matrixAction('product.list'); + + Route::post('/products', [ProductController::class, 'store']) + ->matrixAction('product.create'); + + Route::post('/orders/{order}/refund', [OrderController::class, 'refund']) + ->matrixAction('order.refund'); + + // Or use conventions and let middleware figure it out + Route::apiResource('customers', CustomerController::class); + // GET /customers → customer.index + // POST /customers → customer.store + // etc. +}); +``` + +### 7. The Training UI + +```blade +{{-- resources/views/commerce/matrix/train-prompt.blade.php --}} + +Training Mode Active
+| Location | +SKU | +Product | +Qty | +Picked | +
|---|---|---|---|---|
| {{ $item->product->warehouseLocation->full_location }} | +{{ $item->sku }} | +{{ $item->product->name }} | +{{ $item->quantity }} | +☐ | +
{{ $batch->orders->count() }} orders | Generated {{ now()->format('Y-m-d H:i') }}
+ +| Pick Seq | +Location | +SKU | +Product | +Total Qty | +For Orders | +
|---|---|---|---|---|---|
| {{ $item['location']->pick_sequence }} | +{{ $item['location']->full_location }} | +{{ $item['product']->master_sku }} | +{{ $item['product']->name }} | +{{ $item['quantity'] }} | +{{ implode(', ', array_map(fn($id) => "#{$id}", $item['orders'])) }} | +