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

feat: add inventory transaction audit trail (Phase 2)

Browse Source 
Adds complete audit trail for all stock movements:
- InventoryTransaction model with transaction types (reserve, fulfill,
  release, adjust, set, import, return)
- Alembic migration for inventory_transactions table
- Transaction logging in order_inventory_service for all order operations
- Captures quantity snapshots, order references, and timestamps

Each inventory operation now creates a transaction record for
accountability and debugging.

🤖 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
2026-01-01 18:12:09 +01:00
parent 871f52da80
commit 049e3319c3
5 changed files with 468 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
alembic/versions/o3c4d5e6f7a8_add_inventory_transactions_table.py Normal file
View File

@@ -0,0 +1,144 @@
"""Add inventory_transactions table
Revision ID: o3c4d5e6f7a8
Revises: n2c3d4e5f6a7
Create Date: 2026-01-01
Adds an audit trail for inventory movements:
- Track all stock changes (reserve, fulfill, release, adjust, set)
- Link transactions to orders for traceability
- Store quantity snapshots for historical analysis
"""
from alembic import op
import sqlalchemy as sa
# revision identifiers, used by Alembic.
revision = "o3c4d5e6f7a8"
down_revision = "n2c3d4e5f6a7"
branch_labels = None
depends_on = None
def upgrade() -> None:
# Create transaction type enum
transaction_type_enum = sa.Enum(
"reserve",
"fulfill",
"release",
"adjust",
"set",
"import",
"return",
name="transactiontype",
)
op.create_table(
"inventory_transactions",
sa.Column("id", sa.Integer(), nullable=False),
sa.Column("vendor_id", sa.Integer(), nullable=False),
sa.Column("product_id", sa.Integer(), nullable=False),
sa.Column("inventory_id", sa.Integer(), nullable=True),
sa.Column("transaction_type", transaction_type_enum, nullable=False),
sa.Column("quantity_change", sa.Integer(), nullable=False),
sa.Column("quantity_after", sa.Integer(), nullable=False),
sa.Column("reserved_after", sa.Integer(), nullable=False, server_default="0"),
sa.Column("location", sa.String(), nullable=True),
sa.Column("warehouse", sa.String(), nullable=True),
sa.Column("order_id", sa.Integer(), nullable=True),
sa.Column("order_number", sa.String(), nullable=True),
sa.Column("reason", sa.Text(), nullable=True),
sa.Column("created_by", sa.String(), nullable=True),
sa.Column(
"created_at",
sa.DateTime(timezone=True),
nullable=False,
server_default=sa.func.now(),
),
sa.ForeignKeyConstraint(["vendor_id"], ["vendors.id"]),
sa.ForeignKeyConstraint(["product_id"], ["products.id"]),
sa.ForeignKeyConstraint(["inventory_id"], ["inventory.id"]),
sa.ForeignKeyConstraint(["order_id"], ["orders.id"]),
sa.PrimaryKeyConstraint("id"),
)
# Create indexes
op.create_index(
"ix_inventory_transactions_id",
"inventory_transactions",
["id"],
)
op.create_index(
"ix_inventory_transactions_vendor_id",
"inventory_transactions",
["vendor_id"],
)
op.create_index(
"ix_inventory_transactions_product_id",
"inventory_transactions",
["product_id"],
)
op.create_index(
"ix_inventory_transactions_inventory_id",
"inventory_transactions",
["inventory_id"],
)
op.create_index(
"ix_inventory_transactions_transaction_type",
"inventory_transactions",
["transaction_type"],
)
op.create_index(
"ix_inventory_transactions_order_id",
"inventory_transactions",
["order_id"],
)
op.create_index(
"ix_inventory_transactions_created_at",
"inventory_transactions",
["created_at"],
)
op.create_index(
"idx_inv_tx_vendor_product",
"inventory_transactions",
["vendor_id", "product_id"],
)
op.create_index(
"idx_inv_tx_vendor_created",
"inventory_transactions",
["vendor_id", "created_at"],
)
op.create_index(
"idx_inv_tx_type_created",
"inventory_transactions",
["transaction_type", "created_at"],
)
def downgrade() -> None:
op.drop_index("idx_inv_tx_type_created", table_name="inventory_transactions")
op.drop_index("idx_inv_tx_vendor_created", table_name="inventory_transactions")
op.drop_index("idx_inv_tx_vendor_product", table_name="inventory_transactions")
op.drop_index(
"ix_inventory_transactions_created_at", table_name="inventory_transactions"
)
op.drop_index(
"ix_inventory_transactions_order_id", table_name="inventory_transactions"
)
op.drop_index(
"ix_inventory_transactions_transaction_type", table_name="inventory_transactions"
)
op.drop_index(
"ix_inventory_transactions_inventory_id", table_name="inventory_transactions"
)
op.drop_index(
"ix_inventory_transactions_product_id", table_name="inventory_transactions"
)
op.drop_index(
"ix_inventory_transactions_vendor_id", table_name="inventory_transactions"
)
op.drop_index("ix_inventory_transactions_id", table_name="inventory_transactions")
op.drop_table("inventory_transactions")
# Drop enum
sa.Enum(name="transactiontype").drop(op.get_bind(), checkfirst=True)

96
app/services/order_inventory_service.py
View File

@@ -9,6 +9,8 @@ This service orchestrates inventory operations for orders:
This is the critical link between the order and inventory systems
that ensures stock accuracy.
All operations are logged to the inventory_transactions table for audit trail.
"""
import logging
@@ -22,6 +24,7 @@ from app.exceptions import (
)
from app.services.inventory_service import inventory_service
from models.database.inventory import Inventory
from models.database.inventory_transaction import InventoryTransaction, TransactionType
from models.database.order import Order, OrderItem
from models.schema.inventory import InventoryReserve
@@ -84,6 +87,51 @@ class OrderInventoryService:
# Check if it's the placeholder product (GTIN 0000000000000)
return order_item.product.gtin == "0000000000000"
def _log_transaction(
self,
db: Session,
vendor_id: int,
product_id: int,
inventory: Inventory,
transaction_type: TransactionType,
quantity_change: int,
order: Order,
reason: str | None = None,
) -> InventoryTransaction:
"""
Create an inventory transaction record for audit trail.
Args:
db: Database session
vendor_id: Vendor ID
product_id: Product ID
inventory: Inventory record after the operation
transaction_type: Type of transaction
quantity_change: Change in quantity (positive = add, negative = remove)
order: Order associated with this transaction
reason: Optional reason for the transaction
Returns:
Created InventoryTransaction
"""
transaction = InventoryTransaction.create_transaction(
vendor_id=vendor_id,
product_id=product_id,
inventory_id=inventory.id if inventory else None,
transaction_type=transaction_type,
quantity_change=quantity_change,
quantity_after=inventory.quantity if inventory else 0,
reserved_after=inventory.reserved_quantity if inventory else 0,
location=inventory.location if inventory else None,
warehouse=inventory.warehouse if inventory else None,
order_id=order.id,
order_number=order.order_number,
reason=reason,
created_by="system",
)
db.add(transaction)
return transaction
def reserve_for_order(
self,
db: Session,
@@ -142,9 +190,23 @@ class OrderInventoryService:
location=location,
quantity=item.quantity,
)
inventory_service.reserve_inventory(db, vendor_id, reserve_data)
updated_inventory = inventory_service.reserve_inventory(
db, vendor_id, reserve_data
)
reserved_count += 1
# Log transaction for audit trail
self._log_transaction(
db=db,
vendor_id=vendor_id,
product_id=item.product_id,
inventory=updated_inventory,
transaction_type=TransactionType.RESERVE,
quantity_change=0, # Reserve doesn't change quantity, only reserved_quantity
order=order,
reason=f"Reserved for order {order.order_number}",
)
logger.info(
f"Reserved {item.quantity} units of product {item.product_id} "
f"for order {order.order_number}"
@@ -242,9 +304,23 @@ class OrderInventoryService:
location=location,
quantity=item.quantity,
)
inventory_service.fulfill_reservation(db, vendor_id, reserve_data)
updated_inventory = inventory_service.fulfill_reservation(
db, vendor_id, reserve_data
)
fulfilled_count += 1
# Log transaction for audit trail
self._log_transaction(
db=db,
vendor_id=vendor_id,
product_id=item.product_id,
inventory=updated_inventory,
transaction_type=TransactionType.FULFILL,
quantity_change=-item.quantity, # Negative because stock is consumed
order=order,
reason=f"Fulfilled for order {order.order_number}",
)
logger.info(
f"Fulfilled {item.quantity} units of product {item.product_id} "
f"for order {order.order_number}"
@@ -335,9 +411,23 @@ class OrderInventoryService:
location=inventory.location,
quantity=item.quantity,
)
inventory_service.release_reservation(db, vendor_id, reserve_data)
updated_inventory = inventory_service.release_reservation(
db, vendor_id, reserve_data
)
released_count += 1
# Log transaction for audit trail
self._log_transaction(
db=db,
vendor_id=vendor_id,
product_id=item.product_id,
inventory=updated_inventory,
transaction_type=TransactionType.RELEASE,
quantity_change=0, # Release doesn't change quantity, only reserved_quantity
order=order,
reason=f"Released for cancelled order {order.order_number}",
)
logger.info(
f"Released {item.quantity} units of product {item.product_id} "
f"for cancelled order {order.order_number}"

62
docs/implementation/stock-management-integration.md
View File

@@ -188,9 +188,63 @@ INFO: Fulfilled 2 units of product 123 for order ORD-1-20260101-ABC123
WARNING: Order ORD-1-20260101-ABC123 inventory operation failed: No inventory found
```
## Audit Trail (Phase 2)
All inventory operations are logged to the `inventory_transactions` table.
### Transaction Types
| Type | Description |
|------|-------------|
| `reserve` | Stock reserved for order |
| `fulfill` | Reserved stock consumed (shipped) |
| `release` | Reserved stock released (cancelled) |
| `adjust` | Manual adjustment (+/-) |
| `set` | Set to exact quantity |
| `import` | Initial import/sync |
| `return` | Stock returned from customer |
### Transaction Record
```python
class InventoryTransaction:
id: int
vendor_id: int
product_id: int
inventory_id: int | None
transaction_type: TransactionType
quantity_change: int # Positive = add, negative = remove
quantity_after: int # Snapshot after transaction
reserved_after: int # Snapshot after transaction
location: str | None
warehouse: str | None
order_id: int | None # Link to order if applicable
order_number: str | None
reason: str | None # Human-readable reason
created_by: str | None # User/system identifier
created_at: datetime
```
### Example Transaction Query
```python
from models.database import InventoryTransaction, TransactionType
# Get all transactions for an order
transactions = db.query(InventoryTransaction).filter(
InventoryTransaction.order_id == order_id
).order_by(InventoryTransaction.created_at).all()
# Get recent stock changes for a product
recent = db.query(InventoryTransaction).filter(
InventoryTransaction.product_id == product_id,
InventoryTransaction.vendor_id == vendor_id,
).order_by(InventoryTransaction.created_at.desc()).limit(10).all()
```
## Future Enhancements
1. **Inventory Transaction Log** - Audit trail for all stock movements
2. **Multi-Location Selection** - Choose which location to draw from
3. **Backorder Support** - Handle orders when stock is insufficient
4. **Return Processing** - Increase stock when orders are returned
1. **Multi-Location Selection** - Choose which location to draw from
2. **Backorder Support** - Handle orders when stock is insufficient
3. **Return Processing** - Increase stock when orders are returned
4. **Transaction API** - Endpoint to view inventory history

3
models/database/__init__.py
View File

@@ -21,6 +21,7 @@ from .customer import Customer, CustomerAddress
from .email import EmailCategory, EmailLog, EmailStatus, EmailTemplate
from .feature import Feature, FeatureCategory, FeatureCode, FeatureUILocation
from .inventory import Inventory
from .inventory_transaction import InventoryTransaction, TransactionType
from .invoice import (
Invoice,
InvoiceStatus,
@@ -127,6 +128,8 @@ __all__ = [
"MarketplaceImportError",
# Inventory
"Inventory",
"InventoryTransaction",
"TransactionType",
# Invoicing
"Invoice",
"InvoiceStatus",

170
models/database/inventory_transaction.py Normal file
View File

@@ -0,0 +1,170 @@
# models/database/inventory_transaction.py
"""
Inventory Transaction Model - Audit trail for all stock movements.
This model tracks every change to inventory quantities, providing:
- Complete audit trail for compliance and debugging
- Order-linked transactions for traceability
- Support for different transaction types (reserve, fulfill, adjust, etc.)
All stock movements should create a transaction record.
"""
from datetime import UTC, datetime
from enum import Enum
from sqlalchemy import (
Column,
DateTime,
Enum as SQLEnum,
ForeignKey,
Index,
Integer,
String,
Text,
)
from sqlalchemy.orm import relationship
from app.core.database import Base
class TransactionType(str, Enum):
"""Types of inventory transactions."""
# Order-related
RESERVE = "reserve" # Stock reserved for order
FULFILL = "fulfill" # Reserved stock consumed (shipped)
RELEASE = "release" # Reserved stock released (cancelled)
# Manual adjustments
ADJUST = "adjust" # Manual adjustment (+/-)
SET = "set" # Set to exact quantity
# Imports
IMPORT = "import" # Initial import/sync
# Returns
RETURN = "return" # Stock returned from customer
class InventoryTransaction(Base):
"""
Audit log for inventory movements.
Every change to inventory quantity creates a transaction record,
enabling complete traceability of stock levels over time.
"""
__tablename__ = "inventory_transactions"
id = Column(Integer, primary_key=True, index=True)
# Core references
vendor_id = Column(Integer, ForeignKey("vendors.id"), nullable=False, index=True)
product_id = Column(Integer, ForeignKey("products.id"), nullable=False, index=True)
inventory_id = Column(
Integer, ForeignKey("inventory.id"), nullable=True, index=True
)
# Transaction details
transaction_type = Column(
SQLEnum(TransactionType), nullable=False, index=True
)
quantity_change = Column(Integer, nullable=False) # Positive = add, negative = remove
# Quantities after transaction (snapshot)
quantity_after = Column(Integer, nullable=False)
reserved_after = Column(Integer, nullable=False, default=0)
# Location context
location = Column(String, nullable=True)
warehouse = Column(String, nullable=True)
# Order reference (for order-related transactions)
order_id = Column(Integer, ForeignKey("orders.id"), nullable=True, index=True)
order_number = Column(String, nullable=True)
# Audit fields
reason = Column(Text, nullable=True) # Human-readable reason
created_by = Column(String, nullable=True) # User/system that created
created_at = Column(
DateTime(timezone=True),
default=lambda: datetime.now(UTC),
nullable=False,
index=True,
)
# Relationships
vendor = relationship("Vendor")
product = relationship("Product")
inventory = relationship("Inventory")
order = relationship("Order")
# Indexes for common queries
__table_args__ = (
Index("idx_inv_tx_vendor_product", "vendor_id", "product_id"),
Index("idx_inv_tx_vendor_created", "vendor_id", "created_at"),
Index("idx_inv_tx_order", "order_id"),
Index("idx_inv_tx_type_created", "transaction_type", "created_at"),
)
def __repr__(self) -> str:
return (
f"<InventoryTransaction {self.id}: "
f"{self.transaction_type.value} {self.quantity_change:+d} "
f"for product {self.product_id}>"
)
@classmethod
def create_transaction(
cls,
vendor_id: int,
product_id: int,
transaction_type: TransactionType,
quantity_change: int,
quantity_after: int,
reserved_after: int = 0,
inventory_id: int | None = None,
location: str | None = None,
warehouse: str | None = None,
order_id: int | None = None,
order_number: str | None = None,
reason: str | None = None,
created_by: str | None = None,
) -> "InventoryTransaction":
"""
Factory method to create a transaction record.
Args:
vendor_id: Vendor ID
product_id: Product ID
transaction_type: Type of transaction
quantity_change: Change in quantity (positive = add, negative = remove)
quantity_after: Total quantity after this transaction
reserved_after: Reserved quantity after this transaction
inventory_id: Optional inventory record ID
location: Optional location
warehouse: Optional warehouse
order_id: Optional order ID (for order-related transactions)
order_number: Optional order number for display
reason: Optional human-readable reason
created_by: Optional user/system identifier
Returns:
InventoryTransaction instance (not yet added to session)
"""
return cls(
vendor_id=vendor_id,
product_id=product_id,
inventory_id=inventory_id,
transaction_type=transaction_type,
quantity_change=quantity_change,
quantity_after=quantity_after,
reserved_after=reserved_after,
location=location,
warehouse=warehouse,
order_id=order_id,
order_number=order_number,
reason=reason,
created_by=created_by,
)