Apa boundary transaksi?
Apa aggregate yang boleh dimutasi bersama?
Apa data yang immutable?
Apa data yang hanya projection?
Apa query yang boleh memakai entity graph?
Apa query yang harus memakai read model?
Apa yang harus dikunci dengan optimistic locking?
Apa yang tidak boleh lazy-load keluar dari transaction boundary?
Apa yang harus tetap bisa dibuktikan lima tahun lagi?

Satu command = satu transaction boundary utama.

Cari semua quote enterprise customer yang pending approval > 2 hari.
Cari order yang fulfillment step-nya stuck di external inventory reservation.
Cari quote accepted yang belum punya primary order.
Cari order dengan last failure reason tertentu.
Cari semua quote dengan discount override di atas threshold.

Aggregate table untuk command correctness.
Projection/read model untuk operational query.

<property name="eclipselink.weaving" value="true"/>
<property name="eclipselink.logging.level" value="WARNING"/>

public class QuoteDomainService {
    private org.eclipse.persistence.sessions.Session session;
}

<persistence xmlns="https://jakarta.ee/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="https://jakarta.ee/xml/ns/persistence https://jakarta.ee/xml/ns/persistence/persistence_3_1.xsd"
             version="3.1">

  <persistence-unit name="quote-service-pu" transaction-type="JTA">
    <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>

    <jta-data-source>jdbc/QuoteServiceDS</jta-data-source>

    <class>com.acme.cpq.quote.persistence.entity.QuoteEntity</class>
    <class>com.acme.cpq.quote.persistence.entity.QuoteRevisionEntity</class>
    <class>com.acme.cpq.quote.persistence.entity.QuoteLineEntity</class>
    <class>com.acme.cpq.quote.persistence.entity.PriceResultEntity</class>
    <class>com.acme.cpq.quote.persistence.entity.PriceComponentEntity</class>
    <class>com.acme.cpq.quote.persistence.entity.ApprovalDecisionEntity</class>
    <class>com.acme.cpq.quote.persistence.entity.OutboxEventEntity</class>
    <class>com.acme.cpq.quote.persistence.entity.AuditLogEntity</class>

    <exclude-unlisted-classes>true</exclude-unlisted-classes>

    <properties>
      <property name="eclipselink.target-database" value="PostgreSQL"/>
      <property name="eclipselink.weaving" value="true"/>
      <property name="eclipselink.logging.level" value="WARNING"/>
      <property name="eclipselink.ddl-generation" value="none"/>
    </properties>
  </persistence-unit>
</persistence>

@ApplicationScoped
public class QuoteCommandService {

    @Inject
    QuoteRepository quoteRepository;

    @Inject
    AuditWriter auditWriter;

    @Inject
    OutboxWriter outboxWriter;

    @Transactional
    public PriceQuoteResult priceQuote(PriceQuoteCommand command) {
        QuoteRevision quote = quoteRepository.loadRevisionForUpdateIntent(
            command.quoteId(),
            command.revision(),
            command.expectedVersion()
        );

        quote.ensureCanBePriced();

        PriceResult price = pricingEngine.price(quote.toPricingInput());
        quote.applyPrice(price);

        auditWriter.record("QUOTE_PRICED", quote.auditSubject(), command.actor());
        outboxWriter.append(QuotePricedEvent.from(quote, price));

        return PriceQuoteResult.from(quote, price);
    }
}

public PriceQuoteResult priceQuote(PriceQuoteCommand command) {
    EntityManager em = emf.createEntityManager();
    EntityTransaction tx = em.getTransaction();

    try {
        tx.begin();

        QuoteJpaRepository repo = new QuoteJpaRepository(em);
        JpaAuditWriter audit = new JpaAuditWriter(em);
        JpaOutboxWriter outbox = new JpaOutboxWriter(em);

        QuoteRevision quote = repo.loadRevisionForUpdateIntent(
            command.quoteId(),
            command.revision(),
            command.expectedVersion()
        );

        quote.ensureCanBePriced();
        PriceResult price = pricingEngine.price(quote.toPricingInput());
        quote.applyPrice(price);

        audit.record("QUOTE_PRICED", quote.auditSubject(), command.actor());
        outbox.append(QuotePricedEvent.from(quote, price));

        tx.commit();
        return PriceQuoteResult.from(quote, price);
    } catch (RuntimeException e) {
        if (tx.isActive()) tx.rollback();
        throw e;
    } finally {
        em.close();
    }
}

public final class TransactionalCommandExecutor {
    private final EntityManagerFactory emf;

    public <T> T execute(Function<EntityManager, T> work) {
        EntityManager em = emf.createEntityManager();
        EntityTransaction tx = em.getTransaction();
        try {
            tx.begin();
            T result = work.apply(em);
            tx.commit();
            return result;
        } catch (RuntimeException e) {
            if (tx.isActive()) tx.rollback();
            throw e;
        } finally {
            em.close();
        }
    }
}

Satu request command = satu persistence context = satu transaction boundary utama.

@Singleton
public class BadRepository {
    private final EntityManager em; // bahaya kalau dipakai lintas thread/request
}

QuoteRevisionEntity entity = quoteRepository.find(id);
return QuoteResponse.from(entity); // lazy load bisa meledak setelah transaction selesai

@Transactional
public QuoteDetailView getQuoteDetail(QuoteId id) {
    QuoteRevisionEntity entity = quoteQueryRepository.loadDetail(id);
    return quoteAssembler.toDetailView(entity);
}

public interface QuoteRepository {
    QuoteRevision loadEditableRevision(
        QuoteId quoteId,
        int revision,
        long expectedVersion
    );

    void save(QuoteRevision quoteRevision);

    boolean existsAcceptedRevision(QuoteId quoteId);
}

public final class JpaQuoteRepository implements QuoteRepository {

    private final EntityManager em;
    private final QuoteMapper mapper;

    public QuoteRevision loadEditableRevision(
        QuoteId quoteId,
        int revision,
        long expectedVersion
    ) {
        QuoteRevisionEntity entity = em.createQuery("""
            select qr
            from QuoteRevisionEntity qr
            left join fetch qr.lines
            where qr.quoteId = :quoteId
              and qr.revisionNumber = :revision
        """, QuoteRevisionEntity.class)
        .setParameter("quoteId", quoteId.value())
        .setParameter("revision", revision)
        .getSingleResult();

        if (entity.getVersion() != expectedVersion) {
            throw new ConcurrencyConflictException("Quote revision version mismatch");
        }

        return mapper.toDomain(entity);
    }

    public void save(QuoteRevision quoteRevision) {
        QuoteRevisionEntity entity = mapper.toEntity(quoteRevision);
        em.merge(entity);
    }
}

public void applyPrice(QuoteId quoteId, int revision, PriceResult price) {
    QuoteRevisionEntity entity = loadManagedRevision(quoteId, revision);

    entity.ensureStatusAllowsPricing();
    entity.replacePriceResult(PriceResultEntity.from(price));
    entity.markPriced(price.pricedAt());
}

@Entity
public class QuoteRevision {
    public void submitForApproval() {
       // invariant here
    }
}

public final class QuoteRevision {
    // pure domain object
}

@Entity
public class QuoteRevisionEntity {
    // persistence mapping
}

Semakin tinggi nilai business invariant dan lifecycle complexity,
semakin besar alasan memisahkan domain object dari persistence entity.

@Entity
@Table(name = "quote_revision")
public class QuoteRevisionEntity {

    @Id
    @Column(name = "quote_revision_id")
    private UUID id;

    @Column(name = "quote_id", nullable = false)
    private UUID quoteId;

    @Column(name = "revision_number", nullable = false)
    private int revisionNumber;

    @Version
    @Column(name = "version", nullable = false)
    private long version;

    @Enumerated(EnumType.STRING)
    @Column(name = "status", nullable = false)
    private QuoteRevisionStatus status;
}

{
  "quoteId": "...",
  "revision": 3,
  "expectedVersion": 17,
  "reason": "Customer requested new bundle option"
}

if (entity.getVersion() != command.expectedVersion()) {
    throw new VersionConflictException(
        entity.getVersion(),
        command.expectedVersion()
    );
}

QuoteRevisionEntity entity = em.find(
    QuoteRevisionEntity.class,
    id,
    LockModeType.PESSIMISTIC_WRITE
);

em.createQuery("""
    select qr
    from QuoteRevisionEntity qr
    where qr.quoteId = :quoteId
      and qr.revisionNumber = :revision
""", QuoteRevisionEntity.class)
.setLockMode(LockModeType.PESSIMISTIC_WRITE)
.setParameter("quoteId", quoteId)
.setParameter("revision", revision)
.getSingleResult();

Jangan pernah menahan database transaction saat memanggil external service.

Quote
  Revision
    Lines
      Selected Options
      Price Components
      Validation Errors
    Price Result
      Price Components
      Discount Trace
    Approval Decisions
    Documents

select distinct qr
from QuoteRevisionEntity qr
left join fetch qr.lines l
left join fetch l.characteristics c
where qr.quoteId = :quoteId
  and qr.revisionNumber = :revision

select new com.acme.cpq.quote.query.QuoteSummaryRow(
    q.quoteId,
    q.customerId,
    qr.revisionNumber,
    qr.status,
    qr.totalAmount,
    qr.updatedAt
)
from QuoteEntity q
join q.currentRevision qr
where q.customerId = :customerId
order by qr.updatedAt desc

@Entity
@Cacheable(false)
@Table(name = "quote_revision")
public class QuoteRevisionEntity {
    // ...
}

Current quote/order state adalah data yang sering berubah,
bernilai tinggi,
dan menjadi dasar keputusan lifecycle.
Correctness lebih penting daripada cache hit.

@Entity
public class QuoteLineDtoEventVariableEverything {
    // JPA annotations
    // JSON annotations
    // Kafka annotations
    // Camunda serialization assumptions
    // business methods
}

{
  "quoteId": "Q-2026-000123",
  "quoteRevision": 4,
  "approvalRequestId": "APR-9912",
  "tenantId": "enterprise-id",
  "businessSegment": "B2B_ENTERPRISE"
}

@Transactional
public void acceptQuote(AcceptQuoteCommand command) {
    QuoteRevisionEntity quote = quoteRepo.loadForAccept(command);
    quote.accept(command.acceptedBy(), command.acceptedAt());

    OrderCreationRequestedEvent event = OrderCreationRequestedEvent.from(quote);

    outbox.append(
        OutboxEventEntity.pending(
            "quote-service",
            "quote.accepted",
            quote.getQuoteId().toString(),
            event.eventId(),
            json.write(event)
        )
    );

    audit.record(...);
}

create table outbox_event (
    outbox_event_id uuid primary key,
    aggregate_type text not null,
    aggregate_id text not null,
    event_type text not null,
    event_id uuid not null unique,
    payload jsonb not null,
    status text not null,
    attempt_count integer not null default 0,
    next_attempt_at timestamptz,
    created_at timestamptz not null,
    published_at timestamptz
);

public interface AuditWriter {
    void record(AuditRecord record);
}

Who?
Did what?
To what subject?
When?
Why?
From where?
Based on what version?
With what result?

AuditLogEntity audit = new AuditLogEntity(
    UUID.randomUUID(),
    "QUOTE",
    quote.getQuoteId().toString(),
    "QUOTE_ACCEPTED",
    actor.userId(),
    command.reason(),
    json.write(AuditDelta.from(quote.before(), quote.after())),
    clock.instant()
);

em.persist(audit);

Command repository:
- load aggregate
- mutate aggregate
- enforce concurrency
- minimal query semantics

Query repository:
- read optimized
- projection DTO
- pagination
- filter/search
- operational dashboard

public interface QuoteCommandRepository {
    QuoteRevisionEntity loadManagedForCommand(QuoteId id, int revision);
}

public interface QuoteQueryRepository {
    Page<QuoteSummaryRow> search(QuoteSearchCriteria criteria, PageRequest page);
    QuoteDetailView getDetail(QuoteId id, int revision);
}

@PrePersist
void onCreate() {
    this.createdAt = Instant.now();
    this.updatedAt = this.createdAt;
}

@PreUpdate
void onUpdate() {
    this.updatedAt = Instant.now();
}

@PostUpdate
void publishKafkaEvent() {
    kafkaProducer.send(...); // jangan
}

quote.apply(command);
outbox.append(event);
audit.record(record);

// optional: force flush when you want DB constraint violation now
em.flush();

Transaction 1:
- create approval request record
- update quote state = PENDING_APPROVAL
- write audit
- write outbox QuoteSubmittedForApproval
commit

Then:
- start Camunda process with business key
- update workflow correlation record with processInstanceId

create table workflow_command (
    workflow_command_id uuid primary key,
    command_type text not null,
    business_key text not null,
    payload jsonb not null,
    status text not null,
    attempt_count integer not null default 0,
    next_attempt_at timestamptz,
    created_at timestamptz not null,
    completed_at timestamptz
);

quote-service/
  src/main/java/com/acme/cpq/quote/
    api/
      QuoteResource.java
      mapper/
    application/
      QuoteCommandService.java
      QuoteQueryService.java
      command/
      result/
    domain/
      model/
      policy/
      exception/
    persistence/
      entity/
        QuoteEntity.java
        QuoteRevisionEntity.java
        QuoteLineEntity.java
        PriceResultEntity.java
        PriceComponentEntity.java
        ApprovalDecisionEntity.java
        OutboxEventEntity.java
        AuditLogEntity.java
      repository/
        JpaQuoteCommandRepository.java
        JpaQuoteQueryRepository.java
      mapper/
        QuotePersistenceMapper.java
      tx/
        TransactionalCommandExecutor.java
    integration/
      workflow/
      event/
      catalog/
      pricing/

api -> application -> domain
application -> persistence interface
persistence adapter -> JPA entity
integration -> external system adapter

noClasses()
  .that().resideInAPackage("..api..")
  .should().dependOnClassesThat().resideInAPackage("..persistence.entity..");

alter table quote_revision
add constraint uq_quote_revision unique (quote_id, revision_number);

try {
    em.flush();
} catch (PersistenceException e) {
    if (constraintDetector.isUniqueViolation(e, "uq_quote_revision")) {
        throw new ConflictException("Quote revision already exists");
    }
    throw e;
}

{
  "type": "https://errors.acme.com/conflict/duplicate-quote-revision",
  "title": "Quote revision already exists",
  "status": 409,
  "code": "QUOTE_REVISION_DUPLICATE",
  "correlationId": "..."
}

@Entity
@Table(name = "idempotency_record")
public class IdempotencyRecordEntity {
    @Id
    @Column(name = "idempotency_key")
    private String key;

    @Column(name = "operation", nullable = false)
    private String operation;

    @Column(name = "request_hash", nullable = false)
    private String requestHash;

    @Column(name = "status", nullable = false)
    private String status;

    @Column(name = "response_payload", columnDefinition = "jsonb")
    private String responsePayload;

    @Column(name = "created_at", nullable = false)
    private Instant createdAt;
}

Same idempotency key + same request hash must not execute command twice.
Same idempotency key + different request hash is a client error.

Given quote revision with line tree and price result
When persisted and reloaded
Then structure, ordering, amounts, and status remain identical

Given quote revision already exists
When inserting same quote_id + revision_number
Then unique constraint violation is translated to ConflictException

Given two transactions load same quote revision version
When transaction A commits update
And transaction B commits update
Then transaction B fails with optimistic lock conflict

Given command mutates quote and appends event
When transaction commits
Then quote state and outbox event both exist

Given command fails after mutation but before commit
Then neither quote mutation nor outbox event exists

Given quote detail endpoint returns DTO
When transaction is closed
Then serializing DTO does not trigger lazy loading

[ ] Semua aggregate root punya @Version atau concurrency strategy eksplisit.
[ ] Semua command punya transaction boundary jelas.
[ ] Tidak ada JPA entity di API DTO/event/workflow variable.
[ ] DDL generation disabled di production.
[ ] Migration tool adalah sumber schema change.
[ ] Constraint violation diterjemahkan ke error model stabil.
[ ] Outbox insert terjadi dalam transaction yang sama dengan state mutation.
[ ] Audit insert terjadi dalam transaction yang sama dengan state mutation.
[ ] Query repository tidak memakai aggregate graph untuk search page besar.
[ ] Lazy loading tidak keluar dari transaction boundary.
[ ] Mutable aggregate tidak mengandalkan shared ORM cache untuk correctness.
[ ] Idempotency record tersedia untuk command bernilai tinggi.
[ ] Integration test memakai PostgreSQL nyata.
[ ] Optimistic lock conflict diuji.
[ ] Duplicate accept/order creation diuji.
[ ] Workflow correlation failure punya reconciliation path.

API contract protects external compatibility.
Domain model protects business invariants.
JPA adapter maps aggregate state to relational schema.
PostgreSQL protects durable correctness.
Outbox protects event consistency.
Audit protects evidence.
Camunda correlation protects workflow traceability.
Query model protects operational usability.