Developer Menu 4/4

4. Stock Project Customization Flow

This flow is tailored for stoqio inventory architecture. It focuses on safe changes across database, API, stock movement, invoice impact, and React frontend synchronization.

Golden Rule Before Any Change

  1. Understand tenant scope (company_id) and warehouse scope first.
  2. Check impact on inventory, inventory_items, invoices, and invoice_items.
  3. If endpoint is feature-controlled, verify feature.access middleware requirement.
  4. Update backend and frontend-source/src/api together.

Standard Customization Lifecycle (Recommended)

  1. Schema update (migration)
  2. Model update (fillable/casts/relations)
  3. Validation update (Form Request)
  4. Service logic update (app/Services/Api/*)
  5. Controller + route wiring (routes/api.php)
  6. Frontend API + page integration (frontend-source/src/api, src/pages)
  7. End-to-end stock/invoice regression test

Scenario A: Add New Product Field (Example: hsn_code)

1. Migration

php artisan make:migration add_hsn_code_to_product_table
Schema::table('product', function (Blueprint $table) {
    $table->string('hsn_code', 64)->nullable()->after('code');
});

2. Backend Update

  • Model: app/Models/Product.php include hsn_code in fillable.
  • Request: product store/update validation rules.
  • Service: write/read in product create and update flow.
  • Controller: no heavy logic; delegate to service.

3. Frontend Update

  • Add field to product create/edit forms in frontend-source/src/pages/product-setup.
  • Map payload in API client under src/api/products*.
  • Add column/filter only if business needs listing/search support.

Scenario B: New Stock Rule / Guard Policy

Use stock guard APIs already present in routes:

GET    /api/v1/stockguard/options
PUT    /api/v1/stockguard/rules
GET    /api/v1/stockguard/requests
POST   /api/v1/stockguard/requests
POST   /api/v1/stockguard/requests/{id}/approve
POST   /api/v1/stockguard/requests/{id}/reject
  • Keep approval trail for any stock override request.
  • Do not directly mutate stock quantities bypassing service flow.
  • Ensure request approval action logs user/timestamp for audit.

Scenario C: Invoice Logic Customization

  • Header table: invoices
  • Line table: invoice_items
  • Payment traces: transactions
  • Inventory impact: inventory + inventory_items + history

When customizing discount/VAT/total behavior:

  1. Apply formula change in service layer (purchase/sale service path).
  2. Preserve backward compatibility for old invoice reads.
  3. Retest sale, purchase, return, draft, and quotation flows.

Scenario D: Add New Report Endpoint

1. Route

// routes/api.php inside protected group
Route::get('/reports/my-new-report', [ReportController::class, 'myNewReport']);

2. Controller and Query

  • Always filter by company_id.
  • Use indexed filters (date range, warehouse, product, supplier).
  • Return normalized response for React chart/table binding.

3. Frontend

  • Add API client in src/api/reports*.
  • Create or extend report page under src/pages.
  • Keep export/filter UI consistent with existing reports.

Scenario E: Waitlist Flow Customization

Existing route group:

GET    /api/v1/waitlists
GET    /api/v1/waitlists/{id}
POST   /api/v1/waitlists/{id}/claim
POST   /api/v1/waitlists/{id}/release
POST   /api/v1/waitlists/{id}/cancel
  • Reflect state transitions correctly: pending -> reserved/notified -> completed/cancelled.
  • Maintain consistency with customer_waitlist_reservations records.
  • Prevent over-claim above reserved quantity.

Feature-Gated Customization Checklist

  • UNIT_SETUP for units module.
  • BUNDLE_PRODUCT for bundles.
  • PURCHASE_RETURN for purchase return APIs.
  • SELL_RETURN for sales return APIs and reports.
  • WAREHOUSE_STOCK_TRANSFER for stock transfer.
  • PRODUCT_BARCODE for barcode store.
  • CUSTOMER_WAITLIST for waitlist routes.
  • SHIFT_AND_CASH_HANDOVER for timesheet endpoints.

Regression Test Matrix (Must Run)

  1. Stock In: purchase creates inventory/inventory_items correctly.
  2. Stock Out: sale reduces stock by expected method (FIFO/LIFO/RANDOM logic path).
  3. Return: reversal updates invoice item flags and stock recovery path.
  4. Transfer: from/to warehouse quantity reconciliation passes.
  5. Waitlist: reserve/claim/release/cancel state integrity.
  6. Reports: values match transactional source tables.
  7. Backoffice: feature toggles properly lock/unlock routes.

Production Safety Notes

  • Prefer additive schema changes; avoid destructive column drops in live release.
  • Wrap multi-table write operations in transactions.
  • Do not bypass service layer for stock-affecting operations.
  • Update docs and frontend contract in same release.

Source of Truth

This guide is aligned to current routes/api.php and SQL schema in database/sql/database.sql.