Apa yang harus terjadi terhadap product milik customer?
Apakah action-nya add, modify, no-change, disconnect, suspend, resume, atau migrate?
Item mana bergantung pada item lain?
Data komersial mana yang sudah dikunci dari quote/catalog?
Apakah order bisa diterima?
Apakah order siap didekomposisi ke service/resource work?
Apa state order saat ini?
Apa bukti transisi state-nya?
Apakah order bisa dibatalkan atau diamandemen?
Jika terjadi fallout, apakah masalahnya business fallout atau technical fallout?
Apa yang boleh dilihat channel/customer care?
Apa yang harus masuk ke downstream system?

order diterima padahal quote expired
order item tidak punya dependency graph
modify order kehilangan product instance target
cancel order mematikan service yang sudah aktif sebagian
billing start sebelum activation selesai
activation jalan dua kali karena retry tidak idempotent
customer care tidak tahu order stuck di mana
manual repair mengubah state tanpa audit
fallout dianggap error teknis padahal constraint bisnis

Diberikan intent dari quote/order capture, Anda bisa mendesain Product Order Management
carrier-grade yang mampu menerima order, memvalidasi, menjaga state, mengelola item graph,
melakukan amendment/cancel secara aman, memproduksi event yang stabil, dan menyiapkan
input untuk fulfillment/orchestration tanpa membuat downstream menjadi tempat sampah data.

Quote menjawab: apa yang dijanjikan secara komersial?
Product Order menjawab: apa yang harus dieksekusi terhadap product customer?
Service Order menjawab: service teknis apa yang harus dibuat/diubah/dimatikan?
Resource Order menjawab: resource apa yang harus dialokasikan/dilepas/dikonfigurasi?
Work Order menjawab: pekerjaan manusia/lapangan apa yang harus dilakukan?

1. dump JSON dari frontend;
2. workflow engine table tanpa domain invariant;
3. task list teknis activation;
4. invoice request;
5. service provisioning command langsung;
6. general-purpose request table untuk semua hal.

commercial intent + target product + order item graph + lifecycle state + evidence + audit trail

Product Order = permintaan perubahan.
Product Inventory = keadaan product customer setelah perubahan.

Customer membeli paket fiber 100 Mbps.
Product Order: ADD productOffering Fiber 100 Mbps, install at site X.
Product Inventory setelah selesai: Product instance Fiber 100 Mbps active untuk customer/account tersebut.

Customer upgrade dari 100 Mbps ke 300 Mbps.
Product Order: MODIFY existing product instance P-123, change speed 100 -> 300.
Product Inventory setelah selesai: product P-123 active dengan speed 300 Mbps atau product baru tergantung policy modeling.

Customer berhenti layanan.
Product Order: DISCONNECT product instance P-123 effective date tertentu.
Product Inventory setelah selesai: product P-123 terminated/disconnected dengan end date.

Order boleh gagal.
Inventory tidak boleh pura-pura sukses.
Order boleh partial.
Inventory harus merepresentasikan state aktual/terkomit.
Order adalah history execution.
Inventory adalah current and historical product ownership.

public enum ProductOrderAction {
    ADD,
    MODIFY,
    DISCONNECT,
    SUSPEND,
    RESUME,
    NO_CHANGE,
    MIGRATE,
    REPLACE
}

swap SIM
change MSISDN
transfer ownership
relocate service
change bill cycle
add add-on
remove add-on
change QoS tier
renew contract
recontract

Action internal boleh lebih kaya daripada action external API.
Tapi action harus punya semantics, invariant, dan allowed transition yang jelas.

Bundle: Postpaid Family Plan
  - Main subscription
  - SIM card
  - MSISDN
  - Data package
  - Voice package
  - Roaming add-on
  - Device installment

Fiber Broadband
  - Access service
  - Internet service
  - CPE rental
  - Static IP add-on
  - Installation appointment

Internet service tidak bisa aktif sebelum access ready.
Static IP tidak bisa assign sebelum internet service exists.
CPE rental mungkin perlu logistics/field work.
Billing recurring charge tidak boleh start sebelum service activation milestone.

parent-child containment
requires dependency
excludes dependency
replaces relationship
depends-on existing product
fulfillment sequencing hint

Internal state machine = kaya, eksplisit, operationally useful.
External state projection = disesuaikan dengan API contract/version.

Product Order state = PartiallyCompleted
Item A = Completed
Item B = InProgress
Item C = Held
Item D = Pending

Order completed hanya jika semua mandatory item completed atau waived dengan reason.
Order failed jika ada mandatory item failed dan tidak ada compensation/retry path.
Order partial jika beberapa item completed tetapi order belum bisa completed.
Order held jika progress tertahan oleh manual/business decision.

Accepted = order valid untuk diproses.
Executed = order sudah menghasilkan perubahan nyata.

customer valid
account valid
quote valid
pricing snapshot valid
catalog version valid
qualification masih valid atau sudah direvalidated
configuration lengkap
agreement/consent lengkap
credit/fraud decision valid
order item graph valid
requested dates valid
existing product target valid untuk modify/disconnect/suspend/resume

dependencies ready
inventory reservation ready
appointment booked jika diperlukan
downstream capability available
service decomposition menghasilkan plan valid
resource allocation feasible
charging/billing hooks prepared

submit -> acceptance validation -> accepted/rejected -> decomposition/dispatch -> execution

product offering resolved
product specification resolved
configuration characteristics resolved
place/site/address resolved
party/customer/account refs valid
target product refs valid for change order
price snapshot linked
qualification refs linked
appointment/logistics requirements marked
resource hints captured
effective date strategy clear
order item graph acyclic or intentionally cyclic with handler

public final class OrderGraphValidator {
    public void validateNoCycles(ProductOrder order) {
        var graph = OrderDependencyGraph.from(order.items(), order.relationships());
        var cycle = graph.findCycle();
        if (cycle.isPresent()) {
            throw new OrderValidationException(
                "ORDER_DEPENDENCY_CYCLE",
                "Order item dependency cycle detected: " + cycle.get()
            );
        }
    }
}

public enum DecompositionReadiness {
    NOT_READY,
    READY,
    READY_WITH_WARNINGS,
    BLOCKED_BY_BUSINESS_RULE,
    BLOCKED_BY_MISSING_DATA,
    BLOCKED_BY_DOWNSTREAM_CAPABILITY
}

public final class ProductOrder {
    private final ProductOrderId id;
    private final ExternalOrderId externalId;
    private final CustomerId customerId;
    private final BillingAccountId billingAccountId;
    private final QuoteId quoteId;
    private ProductOrderState state;
    private final List<ProductOrderItem> items;
    private final List<OrderRelationship> relationships;
    private final List<OrderStateTransition> transitions;
    private final long version;

    public void submit(Actor actor, Instant now) {
        requireState(ProductOrderState.DRAFT);
        transitionTo(ProductOrderState.SUBMITTED, "SUBMITTED_BY_ACTOR", actor, now);
    }

    public void accept(Actor actor, Instant now, AcceptanceDecision decision) {
        requireState(ProductOrderState.SUBMITTED);
        if (!decision.accepted()) {
            reject(actor, now, decision.reasonCode());
            return;
        }
        transitionTo(ProductOrderState.ACCEPTED, "ACCEPTANCE_VALIDATION_PASSED", actor, now);
    }

    public void markDecompositionReady(Actor actor, Instant now) {
        requireState(ProductOrderState.ACCEPTED);
        ensureAllMandatoryItemsAccepted();
        ensureDependencyGraphValid();
        transitionTo(ProductOrderState.DECOMPOSITION_READY, "DECOMPOSITION_READY", actor, now);
    }

    public void startExecution(Actor actor, Instant now) {
        requireState(ProductOrderState.DECOMPOSITION_READY);
        transitionTo(ProductOrderState.IN_PROGRESS, "DISPATCHED_TO_FULFILLMENT", actor, now);
    }

    private void transitionTo(ProductOrderState next, String reason, Actor actor, Instant now) {
        var previous = this.state;
        this.state = next;
        this.transitions.add(OrderStateTransition.of(previous, next, reason, actor, now));
    }
}

Jangan taruh state transition utama di service class sebagai if/else panjang.
Letakkan invariant domain di aggregate/state machine, lalu service mengorkestrasi dependency eksternal.

public final class SubmitProductOrderUseCase {
    private final ProductOrderRepository repository;
    private final OrderIntentReader orderIntentReader;
    private final ProductOrderFactory factory;
    private final OrderAcceptanceValidator acceptanceValidator;
    private final IdempotencyService idempotencyService;
    private final Outbox outbox;

    public SubmitProductOrderResult submit(SubmitProductOrderCommand command) {
        return idempotencyService.execute(command.idempotencyKey(), () -> {
            var intent = orderIntentReader.read(command.orderIntentId());
            var order = factory.createFrom(intent, command.actor());
            order.submit(command.actor(), command.now());

            var decision = acceptanceValidator.validate(order);
            order.accept(command.actor(), command.now(), decision);

            repository.save(order);
            outbox.append(ProductOrderEvents.from(order));

            return SubmitProductOrderResult.from(order);
        });
    }
}

user double click
mobile app retry
payment gateway callback retry
partner timeout lalu submit ulang
channel tidak menerima response karena network error
message redelivery

channelId + externalOrderId
atau
channelId + orderIntentId + submissionAttemptId

idempotency_key
request_hash
result_type
result_ref
status: PROCESSING / SUCCEEDED / FAILED_RETRYABLE / FAILED_FINAL
created_at
expires_at

same key + same request hash -> return same result
same key + different request hash -> reject as idempotency conflict
processing too long -> expose safe retry semantics
failed retryable -> allow controlled retry
failed final -> return same failure

fulfillment callback
manual fallout repair
cancel request
amendment request
timer/job
customer care note update
partner status query

public interface ProductOrderRepository {
    Optional<ProductOrder> findById(ProductOrderId id);
    void save(ProductOrder order, ExpectedVersion expectedVersion);
}

reload order
re-evaluate command against latest state
apply jika masih valid
reject jika state sudah berubah

UPDATE product_order SET state = 'COMPLETED' WHERE id = ?;

UPDATE product_order
SET state = ?, version = version + 1
WHERE id = ? AND version = ?;

Apakah order belum dieksekusi?
Apakah sebagian item sudah completed?
Apakah perubahan hanya metadata atau memengaruhi fulfillment?
Apakah harga berubah?
Apakah agreement/consent perlu ulang?
Apakah downstream sudah menerima service order?
Apakah compensation diperlukan?

Draft/Submitted: amend usually allowed.
Accepted: amend allowed with revalidation.
DecompositionReady: amend carefully; may reset readiness.
InProgress: amendment becomes change order or compensation.
Completed: amendment becomes new order.
Cancelled/Failed/Rejected: amendment usually not allowed; create new order.

Amendment is a command with diff, not direct patch.

public record AmendProductOrderCommand(
    ProductOrderId orderId,
    AmendmentId amendmentId,
    Actor actor,
    List<OrderItemChange> itemChanges,
    String reasonCode,
    Instant requestedAt
) {}

Apakah order sudah accepted?
Apakah item sudah dispatched?
Apakah item sudah completed?
Apakah resource sudah allocated?
Apakah activation sudah committed?
Apakah billing sudah started?
Apakah field technician sudah assigned?
Apakah cancellation fee berlaku?
Apakah customer consent diperlukan?

cancel request record
assessment decision
affected item list
compensation plan jika perlu
customer-visible reason
internal reason
audit evidence

hapus order row
ubah state langsung ke cancelled tanpa assessment
membatalkan completed item tanpa compensation
menghilangkan price/quote/evidence

public record OrderFallout(
    FalloutId id,
    ProductOrderId orderId,
    ProductOrderItemId itemId,
    FalloutCategory category,
    String reasonCode,
    String diagnosticMessage,
    FalloutSeverity severity,
    boolean customerVisible,
    Instant occurredAt
) {}

INFO: warning, order can continue
WARN: repair recommended, order may continue
BLOCKING: item cannot continue
CRITICAL: order-level failure or customer impact

who submitted
when submitted
which channel
which quote version
which catalog version
which price snapshot
which qualification result
which agreement/consent
which validation decision
who amended/cancelled
who repaired fallout
which downstream callback changed state
which automated job changed state

order_id
from_state
to_state
reason_code
actor_type
actor_id
correlation_id
causation_id
evidence_ref
occurred_at

Ini bagian dari flow bisnis mana?

Event/command mana yang menyebabkan perubahan ini?

ProductOrderSubmitted
ProductOrderRejected
ProductOrderAccepted
ProductOrderHeld
ProductOrderDecompositionReady
ProductOrderExecutionStarted
ProductOrderItemCompleted
ProductOrderPartiallyCompleted
ProductOrderCompleted
ProductOrderFailed
ProductOrderCancellationRequested
ProductOrderCancelled
ProductOrderAmended
ProductOrderFalloutOpened
ProductOrderFalloutResolved

punya eventId
punya eventType
punya eventVersion
punya occurredAt
punya aggregateId
punya aggregateVersion
punya correlationId
punya causationId
membawa business key seperlunya
menghindari payload raksasa penuh PII

public record ProductOrderAcceptedEvent(
    UUID eventId,
    String eventVersion,
    ProductOrderId orderId,
    long orderVersion,
    CustomerId customerId,
    BillingAccountId billingAccountId,
    QuoteId quoteId,
    Instant occurredAt,
    CorrelationId correlationId,
    CausationId causationId
) {}

POST /internal/product-orders:submit
POST /internal/product-orders/{id}:accept
POST /internal/product-orders/{id}:hold
POST /internal/product-orders/{id}:release-hold
POST /internal/product-orders/{id}:mark-decomposition-ready
POST /internal/product-orders/{id}:start-execution
POST /internal/product-orders/{id}:request-cancel
POST /internal/product-orders/{id}:amend
POST /internal/product-orders/{id}/items/{itemId}:complete
POST /internal/product-orders/{id}/fallouts

GET /product-orders/{id}
GET /product-orders?customerId=&state=&createdAfter=
GET /product-orders/{id}/timeline
GET /product-orders/{id}/items
GET /product-orders/{id}/fallouts

POST /tmf-api/productOrderingManagement/vX/productOrder
GET  /tmf-api/productOrderingManagement/vX/productOrder/{id}
PATCH/command style depending on chosen API contract and governance

External compatibility tidak berarti internal model harus sama persis dengan external DTO.

product_order
  id
  external_id
  channel_id
  customer_id
  billing_account_id
  quote_id
  state
  requested_start_date
  requested_completion_date
  created_at
  submitted_at
  accepted_at
  completed_at
  version

product_order_item
  id
  order_id
  parent_item_id
  action
  state
  product_offering_id
  product_specification_id
  target_product_id
  quantity
  effective_date
  sequence
  version

product_order_item_characteristic
  order_item_id
  name
  value_type
  value

product_order_relationship
  id
  order_id
  source_item_id
  target_item_id
  relationship_type

product_order_price_snapshot
  id
  order_item_id
  price_type
  amount
  currency
  recurring_period
  source_quote_line_id

product_order_transition
  id
  order_id
  order_item_id nullable
  from_state
  to_state
  reason_code
  actor_type
  actor_id
  correlation_id
  causation_id
  occurred_at

order_fallout
  id
  order_id
  order_item_id
  category
  severity
  reason_code
  state
  created_at
  resolved_at

external_id + channel_id unique
customer_id + created_at
billing_account_id + created_at
state + created_at
order_item.target_product_id
correlation_id

payload terlalu besar
single transaction terlalu lama
UI tidak bisa render semua item
state aggregation mahal
partial completion dominan
retry item-level kompleks

Order header tetap aggregate root secara business.
Order item dapat diproses dalam shard/batch.
State aggregation dihitung incremental.
Timeline dipisah dari current state.
Payload detail bisa disimpan sebagai document/snapshot dengan checksum.

Jangan mengorbankan invariant hanya demi scale.
Pisahkan write model item-level tetapi jaga order-level state policy.

Customer-facing state adalah product experience, bukan stack trace internal.

order accepted
product instance created pending active
activation completed
effective date reached
suspension/resume/disconnect completed
chargeable event ready

billing recurring charge dibuat saat order submitted
billing start saat technician assigned
billing start karena row product_order exists

Product inventory/subscription lifecycle emits billable lifecycle event.
Billing consumes billable event with idempotency.

create product instance as Pending/Provisioning after order accepted or execution started
mark Active after fulfillment completion

create pending change record or versioned product configuration
apply when fulfillment milestone completed

mark pending disconnect
terminate on effective completion
preserve historical record

submitted order can be accepted
submitted order can be rejected
accepted order can be held
held order can be released
accepted order can be marked decomposition ready
in-progress order can become partial
partial order can become completed
completed order cannot be amended directly
cancel in-progress requires assessment

order cannot complete if mandatory item failed
order cannot start execution if graph has cycle
modify item must target existing product
cancelled order cannot emit activation request
same idempotency key returns same result

external TMF-style DTO maps to internal command
internal state projects to external state consistently
events keep backward compatibility

Scenario: Customer cancels fiber order after appointment booked but before activation
  Given a product order is in progress
  And appointment is booked
  And no service activation has completed
  When the customer requests cancellation
  Then cancellation assessment is required
  And appointment cancellation command is emitted
  And order becomes cancelled after compensation succeeds

PATCH /orders/{id} can update state, price, item, customer, and target product freely.

no lifecycle audit
no transition invariant
manual repair causes hidden corruption

model commands and state transitions explicitly.

frontend JSON saved as order and sent to fulfillment.

stale catalog, bad eligibility, missing agreement, broken decomposition.

use order intent -> acceptance validation -> product order aggregate.

ProductOrderService calls HLR/UDM/OLT adapter directly.

BSS becomes network adapter spaghetti.

POM delegates to service/resource fulfillment boundaries.

order only has header state.

partial completion impossible to explain
retry all-or-nothing
customer care blind

model order item state and aggregate header from item progress.

cancel removes order or hides it.

dispute impossible
billing/provisioning mismatch
regulatory audit weak

cancel is lifecycle command with evidence and compensation.

Customer membeli fiber broadband 300 Mbps + static IP + CPE rental + installation.

order item list
action setiap item
parent-child relationship
dependency relationship
mandatory vs optional
state awal

cancel before appointment booked
cancel after appointment booked
cancel after technician dispatched
cancel after access activated but internet not active
cancel after all completed

boolean canTransition(ProductOrderState from, ProductOrderState to, CommandContext context)

completed tidak bisa kembali inProgress
inProgress tidak bisa langsung rejected
cancel inProgress harus lewat CancellationRequested
failed bisa closed tapi tidak completed tanpa repair decision

ProductOrderCompleted

event id
event version
order id
order version
customer id
billing account id
completed item summary
occurred at
correlation id
causation id

credit check failed
catalog item not found
UDM timeout
address no longer serviceable
missing SIM ICCID
activation adapter returned duplicate subscription
field technician no access

[ ] order submission idempotent
[ ] external id unique per channel/partner
[ ] state machine explicit
[ ] illegal transition blocked
[ ] order item graph validated
[ ] item-level state tracked
[ ] audit transition stored
[ ] event outbox implemented
[ ] cancellation is command, not delete
[ ] amendment has policy by state
[ ] fallout has classification and lifecycle
[ ] customer-visible state projection exists
[ ] inventory update does not fake active before fulfillment
[ ] billing starts from billable lifecycle event, not order creation
[ ] retry and duplicate callback safe
[ ] correlation/causation id propagated
[ ] manual repair audited
[ ] query API supports care/operations needs

Quote = commercial promise.
Product Order = execution contract.
Product Inventory = resulting product ownership/state.
Service Order = technical service execution.
Resource Order = resource allocation/configuration execution.

explicit lifecycle
item graph
state transition audit
idempotency
amendment policy
cancellation assessment
fallout lifecycle
event contract
safe projection to customer/channel/downstream

customer retry submit
partner duplicate order
quote expired
catalog berubah
eligibility berubah
field work gagal
network activation timeout
cancel datang saat provisioning berjalan
manual repair dilakukan jam 2 pagi
audit bertanya kenapa customer ditagih