Skip to content

Fleet Model Justification

This page explains why dirac-odoo sometimes needs a separate fleet layer instead of using only native Odoo location models.

Read this page as onboarding guidance for ADR 0004 - Fleet And Item Governance Layer.

Short Version

The key distinction is:

  • stock.location answers:
  • where an ITEM is physically now
  • ov.fleet answers:
  • which operational or governance grouping the ITEM belongs to

Those questions may align in simple cases, but they do not always align in real operations.

Why This Matters

Examples:

  • a battery belongs to customer fleet A but is currently at a repair warehouse
  • a motorcycle belongs to rental fleet B but is temporarily held by a technician
  • an item belongs to swap pool C but is physically in transit

If fleet were modeled purely as stock.location, then ordinary logistics movement could accidentally rewrite governance meaning.

That would make normal operations imply the wrong semantics:

  • moving an item for repair would appear to remove it from its fleet
  • temporary custody would appear to redefine operational belonging
  • warehouse semantics would become overloaded with stewardship semantics

Native Odoo Still Owns Physical Truth

Native Odoo inventory remains the source of truth for:

  • current physical location
  • stock position
  • movement history
  • inventory execution

Relevant native models include:

  • stock.location
  • stock.quant
  • stock.move.line
  • stock.production.lot

This page does not argue for replacing native Odoo inventory semantics.

What The Fleet Layer Adds

The fleet layer adds a different dimension:

  • operational grouping
  • governance containment
  • SA-facing stewardship scope

In the current repo direction, that means:

  • ITEM identity remains native on stock.production.lot
  • fleet membership is explicit on ov.fleet_item
  • SA governance over fleet is explicit on ov.sa_fleet

Default scope then derives through the fleet path rather than by stamping the native item directly.

When ov.fleet Is Justified

Use ov.fleet when the grouping must remain stable even if the item moves between physical locations.

Typical examples:

  • customer rental fleet
  • delivery fleet
  • maintenance reserve fleet
  • battery circulation pool

Do not use ov.fleet merely because assets exist.

If the physical location itself is the real governed boundary, a governed stock.location is usually simpler and more appropriate.

Why Not Just Add fleet_id To The Native Item

The repo's current design bias is to keep governance overlays external to native Odoo business objects whenever that governance relationship has its own meaning.

Using:

  • ov.fleet_item

instead of:

  • stock.production.lot.fleet_id

preserves:

  • separation of concerns
  • upgrade safety
  • optional participation in fleet governance
  • compatibility with the V3 association-model direction

Not all serialized items participate in fleets, so a separate overlay remains a better fit than pushing fleet semantics into every lot record.

Structural Rule

The fleet layer introduces one important current-state rule:

One ITEM belongs to only one current FLEET at a time.

That rule is about operational governance grouping.

It is not a claim about physical place, which Odoo inventory already governs separately.

If history matters, the implementation should preserve historical membership while still enforcing one current fleet membership.

Boundary Protection

This design keeps four concerns separate:

Concern Responsible layer
Physical inventory truth Native Odoo inventory
Governance grouping Fleet layer
SA stewardship/access Association layer
Service lifecycle ABS

That separation is intentional.

It keeps:

  • logistics in Odoo inventory
  • governance in explicit association records
  • service lifecycle in ABS

Pointers