Skip to content

Domain Rules

These rules are the accepted product decisions for future business implementation. They are not implemented in the current scaffold.

Collections

Collection Purpose
projects Project/work-order aggregate documents
products Product master data discovered from payloads
machines Existing machine catalog used for resolution
users Employee/user catalog used for resolution
erp_inbound_messages Raw inbound request archive

Planned inbound endpoint

text POST /api/v1/inbound/work-orders

This endpoint is planned and must not be treated as implemented in the scaffold.

Payload wrapper

ERP always sends a wrapper payload:

json { "projects": [ {} ] }

  • A single project still uses an array.
  • One request may contain one or more projects.
  • Each project is processed independently.
  • Failure of one project does not stop processing of other projects.

Planned project result statuses

  • completed
  • completed_with_warnings
  • failed

Uniqueness rules

Project

text company_id + organization_id + project_code

Production

production_code is unique within the same project.

Production stage

production_stage_code is unique within the same production.

stage_number may change; the same stage is updated by production_stage_code.

New stage defaults

json { "stage_sequential": false, "allow_parallel_machines": true, "employees": [], "machines": [], "file_urls": [], "status": 0 }

When an existing stage is updated, the existing status value is preserved.

Stage type

stage_type accepts only:

  • yeni
  • revize

Values are normalized to lowercase.

Merge behavior

  • Unsent project child records are not deleted.
  • Unsent productions are not deleted.
  • Unsent production stages are not deleted.
  • Unsent fields are preserved.
  • Sent fields are updated.
  • Integration messages are treated as POST upsert/merge messages.
  • The API decides create, update, and merge internally.
  • Idempotency-Key is mandatory.
  • Deletion is not available to normal integration clients.
  • Deletion will require a separate endpoint, separate scope, and additional security later.

Products

Unique scope:

text company_id + organization_id + product_code

product_name is not unique.

Required fields:

  • product_name
  • product_code
  • ideal_cycle_time
  • unit
  • company_id
  • organization_id

ideal_cycle_time rules:

  • Unit is seconds.
  • Must be an integer.
  • May be zero.
  • Must not be negative.

ERP integration does not persist product status.

There is no separate product create endpoint. Products are discovered from:

  • productions.input_products
  • productions.final_products
  • production_stages.input_products
  • production_stages.output_products
  • production_stages.machines.output_products

Within one project payload, all distinct products are processed uniquely.

If the same product_code appears with conflicting values for any of:

  • product_name
  • ideal_cycle_time
  • unit

the project fails with:

text PRODUCT_DATA_CONFLICT

Conflicting ideal_cycle_time values for the same product code are never accepted.

Machines

machine_code is treated as unique across the machines collection.

ERP sends machine_code. The API will resolve:

  • _id
  • machine_name
  • machine_code

Transient production fields on the machine document are ignored during matching:

  • products
  • input_products
  • project_code
  • project_id
  • project_name
  • production_code
  • production_name
  • production_stage_code
  • production_stage_name
  • has_active_production

If a machine is not found:

  • It is not created.
  • It is not added to the stage machines list.
  • Project processing continues.
  • A MACHINE_NOT_FOUND warning is returned.
  • Project status may become completed_with_warnings.

Employees

Employees are resolved from the users collection.

username is treated as unique across the collection.

ERP sends username. The API will resolve:

  • _id
  • username
  • full_name

These fields are never copied into the project document:

  • password
  • email
  • phone
  • role

If a user is not found:

  • The user is not created.
  • The user is not added to stage employees.
  • Project processing continues.
  • An EMPLOYEE_NOT_FOUND warning is produced.

Raw archive

Every inbound request will later be archived in erp_inbound_messages with fields such as:

  • request_id
  • idempotency_key
  • client_id
  • raw_payload
  • payload_hash
  • processing_status
  • validation_status
  • timestamps
  • created/updated/unchanged IDs
  • warnings and errors
  • project result IDs
  • expires_at

Retention:

Class Retention
Successful archive 180 days
Failed / partial failure archive 365 days
Audit and authentication security logs 2 years

If a product is created and a later project write fails, the product is not rolled back/deleted. Archive status may become partially_failed.

Tenant scope

Planned authentication will derive company_id and organization_id from the authenticated client definition. If the payload includes these fields, they must match the authenticated client scope.