[feat] Revision management

[buzzy84]

Problem / motivation

OpenMES currently identifies the item to be manufactured through a product type and supports versioned process templates.

However, the manufactured part or product itself does not have a formal revision entity.

This creates ambiguity when the same product code changes over time because of modifications to:

• geometry;
• materials;
• BOM;
• manufacturing process;
• technical documents;
• quality requirements;
• work instructions.

A work order currently stores the selected product type and a process snapshot, but it cannot explicitly state that it is producing, for example:

Product: PART-1000
Revision: C

Without product revision management:

• two different technical configurations may share the same product code;
• BOM and process revisions cannot be grouped under one released product revision;
• technical documents cannot be tied reliably to a specific manufactured revision;
• historical production records cannot clearly identify which revision was produced;
• changes made after work-order creation may create inconsistencies between product, BOM, process and documents;
• ERP or external integrations cannot refer to a stable product-code and revision pair.

Proposed solution

Introduce a formal product revision entity associated with the existing product type.

Suggested relationship:

Product type
└── Product revision
    ├── BOM or hierarchical BOM
    ├── Process template
    ├── Technical documents
    ├── Quality requirements
    └── Effectivity and lifecycle status

Each product revision should include:

• product type;
• revision code, such as A, B, C or 01, 02;
• description;
• lifecycle status;
• creation date;
• release date;
• obsolete date;
• created-by user;
• released-by user;
• optional change reason;
• optional external reference;
• optional validity or effectivity dates.

Suggested lifecycle statuses:

DRAFT
RELEASED
OBSOLETE

Only released revisions should normally be selectable for new production orders.

The combination of product type and revision code must be unique.

A product revision should reference the exact:

• process template version;
• BOM version or hierarchical BOM structure;
• technical-document revisions;
• quality or inspection configuration.

Work-order integration

Each work order should reference a specific product revision.

When the order is created or released, OpenMES should snapshot:

• product code;
• product revision;
• BOM structure and quantities;
• process template and steps;
• relevant technical documents;
• quality requirements.

The snapshot must remain immutable for historical production records, even when a newer product revision is later released.

The work-order interface should clearly display:

Product: PART-1000
Revision: C

The revision should also be available in:

• work-order lists;
• operator pages;
• reports;
• labels;
• exports;
• REST API responses;
• webhook payloads;
• genealogy records.

Revision changes before production

For work orders in PENDING or ACCEPTED status, an authorized user may change the selected product revision.

Changing the revision should:

• regenerate or update the work-order snapshot;
• recalculate material requirements;
• update the associated process;
• update the applicable technical documents;
• create an audit record containing old revision, new revision, user, timestamp and reason.

Revision changes after production has started

A product revision must not be silently changed on an IN_PROGRESS, PAUSED or BLOCKED work order.

A revision change after production has started should require the controlled production-change workflow described in the related production-stop requirement.

The system must preserve which quantities, batches or serial units were produced under each revision.

REST API support

Suggested endpoint concepts:

GET    /api/v1/product-types/{productType}/revisions
POST   /api/v1/product-types/{productType}/revisions
GET    /api/v1/product-revisions/{revision}
PATCH  /api/v1/product-revisions/{revision}
POST   /api/v1/product-revisions/{revision}/release
POST   /api/v1/product-revisions/{revision}/obsolete

Suggested work-order payload:

{
  "order_no": "WO-2026-0105",
  "product_type_id": 12,
  "product_revision_id": 37,
  "planned_qty": 100
}

Suggested acceptance criteria:

• multiple revisions can exist for the same product code;
• product type and revision code form a unique combination;
• only released revisions are selectable for normal production;
• each revision can reference a specific process, BOM and document set;
• a work order references one exact product revision;
• work-order snapshots preserve the revision used at release;
• releasing a new revision does not alter existing work orders;
• revision changes before production are audited;
• revision changes after production starts require a controlled change workflow;
• reports, APIs and genealogy expose the produced revision;
• existing products and work orders without revision data remain compatible through a migration or default legacy revision.

Affected roles

• Operator
• Supervisor
• Admin

Alternatives considered

Store the revision in the product name

Using names such as:

PART-1000 REV-A
PART-1000 REV-B

was considered.

This creates separate products rather than revisions of the same product and makes it difficult to:

• compare revision history;
• manage lifecycle status;
• preserve a stable product code;
• associate revisions with BOMs, processes and documents consistently;
• synchronize with external systems.

Store the revision in work-order extra data

Using the existing work-order extra_data field was considered.

This could store a revision label, but it would not enforce:

• uniqueness;
• release status;
• valid product-revision relationships;
• links to BOM, process and documents;
• controlled revision changes;
• consistent reporting and API behavior.

Use only the process-template version

The existing process-template version was considered as a substitute for product revision.

A process revision is not equivalent to a product revision. The product may change because of a BOM, drawing, material or quality change while the routing remains unchanged.

The product revision should therefore be the released configuration that groups the applicable process, BOM and technical documents.

Additional context

OpenMES already provides useful foundations:

• process templates have a numeric version;
• work orders contain a process_snapshot;
• work orders are auditable;
• product, process and attachment APIs already exist.

The requested feature should extend these foundations rather than replace them.

Example:

PART-1000
├── Revision A — OBSOLETE
│   ├── Process template v1
│   ├── BOM v1
│   └── Drawing revision A
├── Revision B — RELEASED
│   ├── Process template v2
│   ├── BOM v2
│   └── Drawing revision B
└── Revision C — DRAFT
    ├── Process template v3
    ├── BOM v3
    └── Drawing revision C

Example work-order display:

Work order: WO-2026-0105
Product: PART-1000
Revision: B
Configuration snapshot: 2026-07-15 10:35

This requirement is related to hierarchical BOMs and revision-controlled technical attachments, because the product revision should act as the released configuration that binds those elements together.