Skip to content

6.2 Domain and Persistence

Sprint: Sprint 06 - Customer Domain
Feature ID: 6.2
Subtasks: 6.2.1, 6.2.2, 6.2.3, 6.2.4

Objective

Deliver "Domain and Persistence" within Sprint 06 - Customer Domain.

Dependencies

Aggregated from the subtasks below (prerequisite task IDs and enablers):

  • 6.1.2
  • 6.1.1
  • 3.2.7
  • 6.2.1

Subtasks

6.2.1 Customer domain model and state machine

  • ID: 6.2.1
  • Title: Implement Customer aggregate with KYC state transitions
  • Description: Customer aggregate (type INDIVIDUAL/CORPORATE) enforcing status transitions PENDING -> ACTIVE / REJECTED (FR-02), with Address and Document entities. Reject illegal transitions with BusinessRuleException. Framework-independent domain (ARC-02).
  • Business Purpose: Enforce the KYC lifecycle as domain invariants (FR-02).
  • Inputs: FR-02, analysis Section 10.1.
  • Outputs: Domain aggregate + child entities.
  • Acceptance Criteria:
  • PENDING->ACTIVE and PENDING->REJECTED succeed; ACTIVE->PENDING throws BusinessRuleException.
  • Dependencies: 6.1.2
  • Complexity: M

6.2.2 TCKN validation

  • ID: 6.2.2
  • Title: Implement TCKN (and VKN) validation
  • Description: A reusable validator implementing the TCKN checksum algorithm (and VKN for corporate), surfaced as a Jakarta Bean Validation constraint used on registration input (FR-01).
  • Business Purpose: Reject invalid national identity numbers at the boundary (FR-01).
  • Inputs: FR-01.
  • Outputs: @ValidTckn constraint + validator + unit tests.
  • Acceptance Criteria:
  • Known-valid TCKNs pass; checksum-invalid and wrong-length values fail with a 400 validation error.
  • Dependencies: 6.1.1
  • Complexity: M

6.2.3 PII encryption converter

  • ID: 6.2.3
  • Title: Implement AES-GCM JPA attribute converter for identity number
  • Description: A JPA AttributeConverter encrypting the identity number with AES-GCM on write and decrypting on read, key sourced from config/secret (NFR-06). Ensure the value is masked in logs (ADR-021) and never returned in full by APIs.
  • Business Purpose: PII-at-rest protection mandated by NFR-06 and KVKK/GDPR.
  • Inputs: NFR-06, ADR-021, analysis Section 13.
  • Outputs: AES-GCM converter + key wiring + tests.
  • Acceptance Criteria:
  • Persisted identity number is ciphertext in the DB and plaintext in the domain; API responses return only a masked form; logs never contain the raw value.
  • Dependencies: 6.1.2, 3.2.7
  • Complexity: M

6.2.4 Repositories with soft-delete

  • ID: 6.2.4
  • Title: Implement customer/address/document repositories honoring soft-delete
  • Description: Spring Data repositories; default queries exclude soft-deleted customers (deleted_at is null); a delete operation sets deleted_at rather than removing the row (FR-04).
  • Business Purpose: KVKK/GDPR-compliant soft-delete (FR-04).
  • Inputs: FR-04.
  • Outputs: Repositories + soft-delete filter.
  • Acceptance Criteria:
  • A deleted customer is excluded from default reads but the row persists with deleted_at set.
  • Dependencies: 6.2.1
  • Complexity: S

Acceptance Criteria

Each subtask above carries its own objective, testable acceptance criteria. This feature is complete when every subtask's acceptance criteria are met.

Deliverables

  • Domain aggregate + child entities.
  • @ValidTckn constraint + validator + unit tests.
  • AES-GCM converter + key wiring + tests.
  • Repositories + soft-delete filter.

Definition of Done

  • All subtasks (6.2.1, 6.2.2, 6.2.3, 6.2.4) completed and their acceptance criteria verified.
  • All listed dependencies satisfied.
  • Build and tests green per the global conventions in ../README.md (Section 3).