Skip to content

2.1 platform-common

Sprint: Sprint 02 - Platform Core Libraries
Feature ID: 2.1
Subtasks: 2.1.1, 2.1.2, 2.1.3

Objective

Deliver "platform-common" within Sprint 02 - Platform Core Libraries.

Dependencies

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

  • none (Sprint 01 build available)

Subtasks

2.1.1 API response contract

  • ID: 2.1.1
  • Title: Implement ApiResult, ApiError, ApiMeta, PageResult, CursorPage
  • Description: In package com.telco.platform.common.api, implement ApiResult<T>(success, data, error, meta) with ok(...)/failure(...) factories; ApiError(code, message, details, traceId); ApiMeta(traceId, correlationId, timestamp, service, path); PageResult<T> (offset); CursorPage<T> (cursor). Annotate with @JsonInclude(NON_NULL).
  • Business Purpose: Universal external response envelope (NFR-14, ADR-015).
  • Inputs: PLATFORM-SPEC Section 2.1, ADR-015.
  • Outputs: Records under common.api.
  • Acceptance Criteria:
  • ApiResult.ok(data, meta).success() is true and error() is null; failure(...) inverse.
  • Serializing a result omits null fields (unit test asserts JSON has no null keys).
  • Dependencies: none (Sprint 01 build available)
  • Complexity: S

2.1.2 Exception hierarchy and error codes

  • ID: 2.1.2
  • Title: Implement sealed PlatformException hierarchy and ErrorCode
  • Description: In com.telco.platform.common.exception, sealed PlatformException extends RuntimeException carrying ErrorCode code and optional Map<String,Object> details. Permitted subtypes: ResourceNotFoundException, ValidationException, ConflictException, UnauthenticatedException, AccessDeniedException, BusinessRuleException, DependencyFailureException. ErrorCode interface (String code()) plus CommonErrorCode enum (RESOURCE_NOT_FOUND, VALIDATION_FAILED, CONFLICT, UNAUTHENTICATED, ACCESS_DENIED, BUSINESS_RULE_VIOLATION, DEPENDENCY_FAILURE, INTERNAL_ERROR). HTTP mapping lives in starter-api, not here.
  • Business Purpose: Consistent, typed domain failures mapped to stable error codes.
  • Inputs: PLATFORM-SPEC Section 2.2.
  • Outputs: Sealed exception types, ErrorCode, CommonErrorCode.
  • Acceptance Criteria:
  • Hierarchy compiles as sealed with exactly the listed permitted subtypes.
  • ValidationException carries field violations in details.
  • Dependencies: none
  • Complexity: M

2.1.3 Context and correlation primitives

  • ID: 2.1.3
  • Title: Implement UserContext, CorrelationContext, holders, and constants
  • Description: In com.telco.platform.common.context: UserContext(userId, roles, tenantId) with hasRole(String) and anonymous(); UserContextHolder (ThreadLocal set/get/clear); CorrelationContext(traceId, correlationId) and CorrelationContextHolder; CurrentUserProvider interface defaulting to anonymous; CorrelationConstants (header and MDC key names). Pure ThreadLocal, no Spring.
  • Business Purpose: Carry identity and correlation across the request without framework coupling (NFR-13).
  • Inputs: PLATFORM-SPEC Section 2.3.
  • Outputs: Context records, holders, provider interface, constants.
  • Acceptance Criteria:
  • Setting then clearing a holder leaves get() empty; anonymous() has no roles.
  • Constant values match PLATFORM-SPEC (X-Correlation-Id, X-User-Id, X-User-Roles, MDC keys).
  • Dependencies: none
  • 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

  • Records under common.api.
  • Sealed exception types, ErrorCode, CommonErrorCode.
  • Context records, holders, provider interface, constants.

Definition of Done

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