Warehouse App Reference¶

The Warehouse app manages inventory tracking, stock transactions, product sales, and warehouse locations for beekeeping operations.

Overview¶

Location: app/warehouse/

Purpose: Inventory management, transaction tracking, product sales

Key Models: InventoryItem, InventoryTransaction, ProductSale, ProductSaleItem, WarehouseLocation

File Structure¶

warehouse/
├── models.py              # 5 models
├── views/                 # Views package (4 modules)
│   ├── __init__.py
│   ├── inventory_views.py # 5 views
│   ├── transaction_views.py # 5 views
│   ├── sale_views.py      # 3 views
│   └── location_views.py  # 5 views
├── forms.py               # 5 model forms + 3 filter forms
├── urls.py                # 18 URL patterns
├── admin.py               # Django admin config (5 admin classes)
├── templatetags/
│   └── warehouse_tags.py  # can_edit, can_delete filters
├── tests/
│   ├── test_models.py
│   ├── test_sales.py
│   └── test_transactions.py
└── templates/warehouse/   # 15 HTML templates

Models¶

See Database Models - Warehouse App for complete field reference.

InventoryItem¶

Equipment, products, and supplies with quantity tracking.

Categories: equipment, product, supply (static choices, not configurable via SystemConfig)

System Item Types: none, bucket, jar, feeding_material (TextChoices enum for reliable cross-app identification)

Key Fields: name, category, item_type (ConfigurableChoice), system_item_type, quantity, unit (ConfigurableChoice), min_quantity, warehouse_location, unit_cost, total_value (auto-calculated), description

Property: is_low_stock -- True when quantity < min_quantity (strictly less than)

Validation: can_be_deleted() checks for ProductSaleItem references before deletion. The delete() method raises a ValidationError if the item is referenced in any sales.

InventoryTransaction¶

Complete audit trail of all inventory movements.

Transaction Types: Configurable via SystemConfig (transaction_type category)

Auto-calculations on save:

Records quantity_before and quantity_after
Updates item.quantity
Calculates total_amount from |quantity_change| * unit_price
Handles location transfers (moves item warehouse_location to to_location for 'transfer' type)

Links to: hive, sale_item, feeding, from_location, to_location

Auto-created by: ProductSaleItem.save() creates 'sale' transactions, HiveFeeding signals create 'usage' transactions, HoneyBatchService creates 'usage' transactions for buckets.

ProductSale¶

Sales records with customer info, payment method (configurable via SystemConfig), and payment status.

ProductSaleItem¶

Individual line items in sales. On creation, auto-creates an InventoryTransaction to reduce stock with a back-reference to the sale item. The inventory_item FK uses PROTECT to prevent deletion of sold items.

WarehouseLocation¶

Named storage locations per organization. Unique constraint on (organization, name). Includes is_active flag for soft-disable. The can_be_deleted() method checks for both inventory items stored at the location and transaction references before allowing deletion.

Views¶

Uses shared mixins from home.mixins: ViewPermissionMixin, EditPermissionMixin, DeletePermissionMixin, SortableListMixin.

Inventory Management¶

View	Purpose
InventoryListView	List with org/category/location/stock status/name search/item type/system item type filters, paginate 50
InventoryDetailView	Item details
InventoryCreateView	Create item, assign created_by, pass organization to form
InventoryUpdateView	Edit item (quantity excluded from update form)
InventoryDeleteView	Delete with reference validation

Transaction Management¶

View	Purpose
TransactionListView	List with org/type/item/item type/item category/date range filters, paginate 50
TransactionCreateView	Record movement, update item quantity, filter items and locations by organization
TransactionDetailView	Transaction details
TransactionUpdateView	Update, recalculate quantity delta between old and new values
TransactionDeleteView	Delete, reverse quantity changes on the inventory item

Sales Management¶

View	Purpose
SaleListView	List with org/payment method/paid status/date range filters, paginate 20
SaleDetailView	Sale details with line items
SaleCreateView	Create sale, assign recorded_by

Warehouse Locations¶

View	Purpose
WarehouseLocationListView	List active locations with item quantity annotations, paginate 50
WarehouseLocationDetailView	Location details with items stored at this location
WarehouseLocationCreateView	Create location, assign created_by
WarehouseLocationUpdateView	Update location (name, description, active status)
WarehouseLocationDeleteView	Delete with reference validation (items and transactions)

Forms¶

Model Forms¶

Form	Purpose
InventoryItemForm	Create item with configurable dropdowns for item_type, unit, and warehouse_location
InventoryItemUpdateForm	Update item (excludes quantity to enforce transaction-based changes)
InventoryTransactionForm	Create transaction with configurable transaction_type dropdown
InventoryTransactionUpdateForm	Update transaction (excludes item field)
ProductSaleForm	Create sale with configurable payment_method dropdown

All model forms accept an organization keyword argument to filter ConfigurableChoice dropdowns and warehouse location options.

Filter Forms¶

InventoryListFilterForm

Filters: organization, category, warehouse_location, stock_status (ok/low), name_search, item_type, system_item_type

TransactionListFilterForm (extends DateRangeFilterMixin)

Filters: organization, transaction_type, item, item_type, item_category, start_date, end_date

SaleListFilterForm (extends DateRangeFilterMixin)

Filters: organization, payment_method, is_paid (paid/unpaid), start_date, end_date

URL Patterns¶

warehouse/                              → InventoryListView
warehouse/<int:pk>/                     → InventoryDetailView
warehouse/new/                          → InventoryCreateView
warehouse/<int:pk>/edit/                → InventoryUpdateView
warehouse/<int:pk>/delete/              → InventoryDeleteView
warehouse/transactions/                 → TransactionListView
warehouse/transaction/new/              → TransactionCreateView
warehouse/transaction/<int:pk>/         → TransactionDetailView
warehouse/transaction/<int:pk>/edit/    → TransactionUpdateView
warehouse/transaction/<int:pk>/delete/  → TransactionDeleteView
warehouse/sales/                        → SaleListView
warehouse/sale/<int:pk>/                → SaleDetailView
warehouse/sale/new/                     → SaleCreateView
warehouse/locations/                    → WarehouseLocationListView
warehouse/location/new/                 → WarehouseLocationCreateView
warehouse/location/<int:pk>/            → WarehouseLocationDetailView
warehouse/location/<int:pk>/edit/       → WarehouseLocationUpdateView
warehouse/location/<int:pk>/delete/     → WarehouseLocationDeleteView

Template Tags¶

Location: app/warehouse/templatetags/warehouse_tags.py

Filter	Usage
`can_edit`	`{% if item\\|can_edit:user %}`
`can_delete`	`{% if item\\|can_delete:user %}`

These filters delegate to organizations.utils.user_can_edit and organizations.utils.user_can_delete.

Admin Configuration¶

Admin Class	Key Features
InventoryItemAdmin	Inline transactions, fieldsets (Basic Info/Inventory/Cost), quantity readonly on edit
InventoryTransactionAdmin	Date hierarchy on transaction_date, readonly calculated fields
ProductSaleAdmin	Inline sale items, fieldsets (Sale Details/Payment/Notes), date hierarchy
ProductSaleItemAdmin	Basic list display with sale, item, quantity, price, subtotal
WarehouseLocationAdmin	Fieldsets (Basic Info/Status/Timestamps), collapsible timestamps

Signals¶

The warehouse app has no signal handlers. All inventory updates are handled through model save hooks and view logic.