SA Design Refinement Layers¶

2026-04-30

Purpose¶

This note explains how the SA design should be read as a sequence of progressive refinements rather than as contradictory rewrites.

The intended reading order is:

V0 - basic SA setup and stamping
V1 - hierarchy and roll-up
V2 - Odoo object visibility and affiliation
V3 - association-model migration pattern for visibility scope

Each later layer adds complexity and precision on top of the earlier layer.

It does not cancel the earlier layer unless a later document states that a specific earlier shortcut must no longer be used.

1. V0 - Basic SA Setup And Stamping¶

V0 defines the minimum SA-governed operating model.

Its purpose is to make simple PA views and actions possible:

My Quotes
My Sales
My Tickets
other actor-scoped work surfaces

Core ideas of V0:

SA exists as the governance boundary
PA establishes the current {actor, sa} context
records can be filtered by current SA first and by actor second
membership gives a person the right to act inside an SA

This is the minimum model that lets PA users operate with:

my records
my shared-with-SA records

without yet needing hierarchy or complex object-affiliation rules.

Primary V0 truth surfaces:

2. V1 - Hierarchy And Roll-Up¶

V1 adds the hierarchy model on top of V0.

Its purpose is not to replace the basic {actor, sa} model.

Its purpose is to explain how authority, reporting, and metric roll-up expand once members and SAs are arranged in trees.

Core ideas of V1:

membership inside one SA is a tree
each SA also sits inside an SA tree
the current sa_manager is the root member of the current SA
any member with subordinates may get team-level roll-up
only the current sa_manager gets SA-level roll-up into descendant child-SAs

This is the layer that enables managerial and regional views such as:

My Team's Sales
My Team's Tickets
My Regional Sales
other recursive team or child-SA reporting views

So V1 should be read as:

V0 still gives the base actor and SA visibility
V1 explains how that visibility and reporting may expand through hierarchy

Primary V1 truth surfaces:

3. V2 - Odoo Object Visibility And Affiliation¶

V2 is the next refinement layer.

Its purpose is to explain how durable Odoo objects become visible inside SA governance without forcing every model into the same stamp pattern.

This is the layer for questions such as:

which Odoo objects need no SA stamp at all
which objects should use {sa, null}
which objects should use {sa, actor}
which objects should derive visibility from existing Odoo structure
which objects must be explicitly assigned to an SA by SAA
which objects are then managed operationally by SAM

Core ideas of V2:

not every Odoo model should be stamped
no stamp is preferred until a real SA visibility need is known
SAA governs what belongs to an SA at all
SAM manages work and assignments inside that valid SA boundary
durable object visibility may come from:
explicit SA assignment
actor assignment inside SA
implicit affiliation from underlying Odoo structure
existing business anchors such as the partner and SA branch relationship

This layer is where developers should think about:

customer visibility beyond My Customers
location, fleet, and asset visibility
when to extend native Odoo models directly
when a wrapper is justified

Primary V2 truth surfaces:

4. V3 - Association-Model Migration Pattern¶

V3 is the current refinement layer for new SA-governed visibility scope.

Its purpose is to replace direct stamp-first visibility design with explicit association models whenever a visibility relationship has its own governance meaning.

This is the layer for questions such as:

should new visibility scope be modeled as a relationship rather than a stamp
when does assignment need its own lifecycle and audit trail
when should shared access be expressed by a dedicated access record
how should older stamp-based visibility models be migrated forward

Core ideas of V3:

any new visibility scope should default to an explicit association model
the relationship becomes the governance object of record
native Odoo records remain the business object of record
legacy stamp-based visibility should be treated as a migration target, not as the continuing default pattern
migration may be incremental, but new scope should not create more stamp-first debt

Primary V3 truth surfaces:

5. How To Read The Layers Together¶

Use this rule:

V0 defines the minimum working governance pattern
V1 expands reporting and managerial scope through hierarchy
V2 expands object visibility and affiliation rules for durable Odoo objects
V3 replaces stamp-first visibility expansion with explicit association models for new scope and for legacy refactoring

In other words:

V0 answers: how can PA show my work?
V1 answers: how can PA show my team and my region?
V2 answers: how can PA show the right Odoo objects, even when they are not naturally actor-owned work records?
V3 answers: how should new visibility scope and old stamp-based scope be modeled so the governance relationship becomes explicit and migratable?

6. Developer Guidance¶

When implementing a new PA-facing feature, ask in this order:

Is this only a V0 actor-scoped work record?
Does it require V1 hierarchy expansion for team or regional views?
Does it require V2 object-affiliation logic because the underlying Odoo object is durable, shared, or structurally governed?
Does the visibility relationship itself require V3 association modeling rather than another direct stamp?

Do not jump to V2 complexity if V0 or V1 already solves the use case.

Do not introduce new visibility scope with direct stamp-first design when V3 association modeling is the real fit.

7. Executive Guidance¶

For Odoo executive control and PA development governance:

do not read later layers as contradiction by default
read them as refinement and scope expansion
approve the smallest layer that satisfies the business need
move to the next layer only when the previous layer is insufficient
treat V3 as the current default for new visibility-scope design and for refactoring older stamp-based scope