국내 대형 온라인 서점의 전자도서관을 다시 만들고 있습니다.

데이터를 소유하는 도메인 API는 자기 테이블만 다루고, 업무 API는 여러 도메인을 조합해 화면이 필요로 하는 흐름을 만듭니다. 프론트마다 BFF를 두어 브라우저는 BFF만 알고, 세션과 토큰은 BFF 안에서만 다룹니다. 서비스 간 호출은 공통 HTTP 클라이언트 하나로 통일했습니다. 서킷브레이커와 재시도, 추적 ID 전파, M2M 토큰 발급이 내장되어 있어 서비스가 각자 구현하지 않습니다.

• 모든 응답은 같은 봉투를 씁니다. 추적 ID, 업무 코드, 페이지네이션이 한 형식입니다.
• 오류 계약은 프레임워크 독립 모듈(Problem Details 모델, 오류 코드 레지스트리)로 분리해 모든 서비스가 같은 코드 체계를 공유합니다.
• 서비스별 OpenAPI 계약을 저장소 안에 배포해, 개발자는 자기 서비스 문서만 보고 구현합니다.

모든 API 서버는 domain, usecase, data, api 네 모듈로 나뉩니다. 의존은 api → usecase → domain, data → domain 두 방향만 허용하고, api는 data를 런타임에만 조립합니다. 도메인 모듈에는 프레임워크와 DB 드라이버 의존을 두지 않습니다. 식별자는 raw 타입 대신 값 객체로 다루고, 읽기와 쓰기 저장소를 분리하며, 트랜잭션 경계는 유스케이스 하나에 하나입니다. Handler는 HTTP 경계만, UseCase는 단일 Command 입력과 Model 출력, 비동기는 Kotlin Coroutines와 Flow로 통일합니다.

• 자체 린터가 101개 규칙으로 계층 의존, DI 위치, 응답 봉투, ID 누수를 정적으로 판정합니다. 결과는 FAIL / NEEDS_REVIEW / SOURCE_CONFLICT로 구분합니다.
• 신규 서버는 스타터 생성기 한 명령으로 4모듈 구조와 컨벤션 테스트를 갖고 시작합니다.
• 기준 저장소 16개의 커밋 해시를 고정한 참조 매니페스트로 "표준이 실제 코드와 일치하는지"를 추적합니다.

OAuth2 Authorization Code + PKCE로 사용자를, 외부 IdP와의 OIDC 연동으로 직원을, Client Credentials로 서비스 간 호출(M2M)을 인증합니다. JWT는 비대칭 키로 서명하고 공개키는 로컬(L1)과 분산(L2) 2단 캐시로 검증합니다. 리프레시 토큰은 패밀리 단위로 회전시켜 재사용이 감지되면 패밀리 전체를 폐기하고, 접속 환경이 급격히 바뀌면 이상 징후로 처리합니다.

• 4단계 RBAC(최고 관리자, 운영사 관리자, 총판 관리자, 기관 관리자)를 OpenAPI 계약에 명시하고 scope와 audience를 토큰 검증에 포함합니다.
• 멀티테넌시: 기관 식별자 없이는 저장소에 진입할 수 없습니다.
• 모든 관리자 행동은 감사 로그에 남기고, 개인정보는 저장 전에 마스킹합니다.

CMS에 올라온 PDF · EPUB은 정규화 도구가 챕터 단위로 분절하고 이미지 · 오디오 · 비디오를 추출합니다. 문서는 Readium LCP 기반 DRM으로, 미디어는 별도 패키징으로, 이미지는 자체 암호화로 각각 fan-out 처리한 뒤 객체 저장소에 발행하고 최종 메타데이터를 확정합니다. 상위 작업은 DB 상태 기반 오케스트레이터가 추적하고, 병목 구간에만 메시지 큐를 도입하는 2단계 전략을 택했습니다.

• 키는 기관 · 콘텐츠 · 버전별로 키 관리 서비스에서 생성하며 외부 키 등록 API를 두지 않습니다. 암호화기는 평문 키를 일시 사용 후 폐기합니다.
• 작업은 claim / lease / attempt 모델로 재시도와 멱등성을 보장합니다. 같은 결과를 다시 보내면 같은 응답이고, 다른 결과면 409로 거절합니다.
• 뷰어는 iOS(PDFium / PDFKit 듀얼 엔진, SPM 패키지), Android(Readium Kotlin 기반), Web 세 플랫폼을 분절 문서 포맷에 맞춰 직접 구현합니다.