cadrumo.application.inventory.service module

Inventory application service: bucket-scoped CRUD over InventoryLedger.

The service persists InventoryLedgerDocument and emits events through the required InventoryServicePorts capability bundle. It does not resolve storage routes or read and write plaintext inventory JSON side stores. Valuation math remains delegated to compute_inventory_valuation().

class InventoryActividadSummary(**data)[source]

Bases: BaseModel

One row in inventory list.

The row summarizes actividad, year, ValuationMethod, opening stock, and movement count without returning the full InventoryLedger.

Parameters:

data (Any)

actividad_id: str
year: int
valuation_method: ValuationMethod
opening_stock: Decimal
movement_count: NonNegativeInt
class InventoryMovementCommand(**data)[source]

Bases: BaseModel

Strict input shape for inventory movement add.

The command is projected into a domain MovementRecord with a closed MovementKind before valuation and persistence.

Parameters:

data (Any)

movement_id: str
movement_date: date
kind: MovementKind
quantity: Decimal
unit_cost: Decimal | None
taxable_base: Decimal | None
acquisition_cost: InventoryAcquisitionCost | None
class InventoryValuationPreview(**data)[source]

Bases: BaseModel

Operator-facing projection of an InventoryValuationResult.

Parameters:

data (Any)

actividad_id: str
year: int
valuation_method: ValuationMethod
derived_closing_value: Decimal
cogs: Decimal
class InventoryLedgerResult(**data)[source]

Bases: BaseModel

Return record from a mutating inventory verb.

ledger is the affected InventoryLedger; bucket_event_ids lists the audit events emitted for the application operation.

Parameters:

data (Any)

ledger: InventoryLedger
bucket_event_ids: tuple[str, ...]
class InventoryValuationPreviewResult(**data)[source]

Bases: BaseModel

Return record from valuation_preview plus emitted event id.

Parameters:

data (Any)

preview: InventoryValuationPreview
bucket_event_ids: tuple[str, ...]
class InventoryService(*, ports)[source]

Bases: object

Bucket-scoped CRUD over per-actividad InventoryLedger records.

The executable composition root supplies the repository factory and event repository through InventoryServicePorts; the service never resolves a storage route or names an adapter implementation.

Parameters:

ports (InventoryServicePorts)

create(*, bucket_id, actividad_id, year, valuation_method, opening_stock=Decimal('0'), actor='cli')[source]

Create a fresh ledger for one actividad/year. Rejects duplicates.

Saves the containing InventoryLedgerDocument, emits a LEDGER_INVENTORY_CREATED bucket event, and returns an InventoryLedgerResult.

Return type:

InventoryLedgerResult

Parameters:
list_all(*, bucket_id)[source]

Return one InventoryActividadSummary per stored ledger.

This is a read-only projection over the bucket’s InventoryLedgerDocument; it emits no bucket event.

Return type:

tuple[InventoryActividadSummary, ...]

Parameters:

bucket_id (str)

show(*, bucket_id, actividad_id, year)[source]

Return the exact InventoryLedger for actividad_id and year.

Raises InventoryActividadNotFoundError when the bucket’s inventory document has no matching actividad/year ledger.

Return type:

InventoryLedger

Parameters:

  • bucket_id (str)

  • actividad_id (str)

  • year (int)

movement_add(*, bucket_id, actividad_id, year, movement, actor='cli')[source]

Append a movement to the named ledger; refuses duplicate movement_id.

The InventoryMovementCommand is converted to a MovementRecord, then the domain valuation guard runs before persistence. Returns an InventoryLedgerResult with the updated ledger after the movement is appended.

Return type:

InventoryLedgerResult

Parameters:
valuation_preview(*, bucket_id, actividad_id, year, actor='cli')[source]

Run the domain-layer valuation engine and report closing stock + COGS.

Returns:

The valuation preview result.

Return type:

InventoryValuationPreviewResult

Parameters:
closing_authority_record(*, bucket_id, actividad_id, year, authority_record)[source]

Atomically validate and persist one complete closing-authority bundle.

Return type:

InventoryLedgerResult

Parameters:
remove(*, bucket_id, actividad_id, year, actor='cli')[source]

Drop the entire ledger for actividad/year.

Raises InventoryActividadNotFoundError on absence. Otherwise saves the remaining InventoryLedgerDocument, emits LEDGER_INVENTORY_REMOVED, and returns the removed InventoryLedger in an InventoryLedgerResult.

Return type:

InventoryLedgerResult

Parameters: