persistence-architect

Partial of docs/use-cases/UC-001-create-customer/. Owner: persistence-architect. Inherits the aggregate and ports from 10-dominio.md — doesn't reinvent them. Contains no code. Form references in .claude/skills/persistence-architect/templates/. Rules applied, never reproduced: @.claude/rules/persistence.md.

Paths relative to src/main/java/dev/nerviz/bankapp/ unless they start with src/. Survey: no migration, no @Entity, no idempotency_keys in the project — everything here is NEW.

Table customers — one per aggregate root.

Indexes

No index on name or birth_date: no query filters by them.

Table idempotency_keys — shared by every Idempotency-Key endpoint, NEW, first in the project. Columns, types and index exactly as templates/IdempotencyKeyTable.sql.example — the set is @.claude/rules/api-rest.md § Idempotency's, not redecided here: TTL 24 h (expires_at = created_at + 24 h), IN_PROGRESS lease 5 minutes, caller_identity = anonymous for this public endpoint (30-rest.md § 4).

Personal data at rest — @.claude/rules/personal-data.md § At rest.

Aggregate Customer → entity CustomerEntity in infrastructure/persistence/customer/. Entity, Spring Data interface, mapper and adapter live there, package-private (@.claude/rules/persistence.md § Boundary).

Reconstruction goes through Customer.rehydrate(...), never register — the date rules must not re-run against today (10-dominio.md § 1). Mapper: CustomerPersistenceMapper, static, package-private.

CustomerEntity extends AssignedIdEntity<UUID> — the id is assigned, so the entity is Persistable (@.claude/rules/persistence.md § Identity and keys). AssignedIdEntity is NEW, written once in infrastructure/persistence/shared/AssignedIdEntity.java, public abstract (templates/JpaEntity.java.example, last block); IdempotencyKeyEntity extends it too.

CustomerRepositoryJpaAdapter (blueprint convention <Capability><Technology>Adapter) implements CustomerRepository; CustomerJpaRepository extends JpaRepository<CustomerEntity, UUID>. No @Transactional here — the use case owns the transaction.

Constraint translation. save calls saveAndFlush so the INSERT reaches the database inside the adapter's try. A DataIntegrityViolationException whose constraint name is uq_customers_security_number becomes SecurityNumberAlreadyRegisteredException with the original as cause; any other integrity violation is rethrown as a ConflictException with errorCode CUSTOMER_PERSISTENCE_CONFLICT. The message never carries the security number.

Concurrency: two requests with the same number — both pass existsBySecurityNumber, the second INSERT hits the unique constraint and is translated as above. No collection returned, so no pagination or JOIN FETCH.

Idempotency — NEW, shapes in templates/IdempotencyKeyStore.java.example and templates/IdempotentExecution.java.example, packages per the blueprint's packages.map:

New tables, no expand/contract pair. The executor creates each file verbatim from these blocks, re-checking <N> against the disk.

src/main/resources/db/migration/V1__create_customers.sql

-- Personal data: security_number (national identification number) and birth_date.
-- Retention: life of the customer record (UC-001 20-persistencia.md § 1).
CREATE TABLE customers (
    id              uuid          NOT NULL,
    name            varchar(120)  NOT NULL,
    security_number char(11)      NOT NULL,
    birth_date      date          NOT NULL,
    registered_at   timestamptz   NOT NULL,
    version         bigint        NOT NULL DEFAULT 0,
    CONSTRAINT pk_customers PRIMARY KEY (id),
    CONSTRAINT uq_customers_security_number UNIQUE (security_number)
);

src/main/resources/db/migration/V2__create_idempotency_keys.sql

Added to src/main/resources/application.yml; what is already there (open-in-view: false, ddl-auto: validate, Flyway enabled, datasource variables) stays as is.

Shape in templates/application-persistence.yml.example.

none — spring-boot-starter-data-jpa, postgresql, flyway-database-postgresql and com.fasterxml.uuid:java-uuid-generator are already in pom.xml. The Postgres service exists in docker-compose.yml (postgres:16-alpine): no pending compose service.

none — no force in the spec, no symptom on disk: one aggregate, no existing adapter whose skeleton this one would repeat. The idempotency store is the mandated shared mechanism.

none — UC-001 is the first case.

1. V1__create_customers.sql, V2__create_idempotency_keys.sql
2. infrastructure/persistence/shared/AssignedIdEntity
3. CustomerEntity + CustomerPersistenceMapper + CustomerJpaRepository + CustomerRepositoryJpaAdapter
4. IdempotencyKeyEntity + IdempotencyKeyJpaRepository + IdempotencyKeyStore
5. Properties in application.yml
6. Integration tests against the real database (Testcontainers) — 40-testes.md