비즈니스 서비스 아키텍처

Akan 비즈니스 서비스는 비즈니스 동작이 서버 측에서 실행되는 계층입니다. 고객이 주문하고, 관리자가 재고를 추가하고, 예약 상태가 바뀌고, 야간 리포트가 생성될 때 비즈니스 서비스는 지금 실행할 작업, 저장 데이터를 바꿀 작업, 백그라운드로 넘길 작업, 다른 클라이언트에 알려야 할 변경을 결정합니다.

요청 액션: 사용자가 버튼을 누르고 주문 제출, 재고 추가, 요청 승인처럼 명확한 결과를 기대하는 작업입니다.

비즈니스 서비스: 재고 규칙, 결제 상태, 예약 충돌, 외부 API 연동 같은 규칙과 조율이 여기에 놓입니다.

백그라운드 작업: 느리거나 반복되거나 예약되었거나 화면을 막을 필요가 없는 작업은 빠른 응답 후 실행할 수 있습니다.

실시간 업데이트: 대시보드, 장비, 다른 사용자가 변경을 봐야 할 때 비즈니스 서비스는 변경된 결과를 전달합니다.

요청에서 비즈니스 액션까지

가장 흔한 비즈니스 서비스 경로는 UI 액션에서 시작합니다. 생성된 클라이언트 헬퍼가 signal endpoint를 호출하고, endpoint는 비즈니스 판단을 service에 맡기며, 결과는 저장 데이터를 바꾸거나 화면에 필요한 응답으로 돌아갑니다.

예시: Article 서버 모듈

비즈니스 서비스 모듈은 오른쪽에서 왼쪽으로 읽으면 이해하기 쉽습니다. 트래픽이 API 포트에 도달하고, signal이 호출 가능한 endpoint와 auth 경계를 노출하고, service가 비즈니스 판단을 하며, document가 저장 세부사항을 처리합니다.

Article.document.ts

문서고의 처리 규칙을 정의합니다. schema, query filter, sort option, document-level helper를 담당합니다.

schema from Article.constant.ts

title
authors

methods

addAuthor

statics

findAllByAuthorName

Article.service.ts

게시글을 누가 바꿀 수 있는지, 작성자를 어떻게 추가할지, 어떤 document method를 호출할지 같은 비즈니스 로직을 가집니다.

Article.signal.ts

8282/api를 통해 호출 가능한 endpoint를 노출하고, service 로직에 위임하기 전에 auth 경계를 적용합니다.

endpoint
slice
internal

API endpoint port

Signal endpoint는 API 포트를 통해 노출되므로, 생성된 client는 같은 surface로 비즈니스 액션을 호출할 수 있습니다.

8282/api

signal: 전화 상담원: 특정 요청을 하는 연락을 받고, 스팸전화나 위험한 요청을 필터링하며, 전화가 너무 많이 몰릴 때 운영적으로 조절하고, 유효한 일을 알맞은 service에 전달합니다.

service: 업무 담당자: 실제 일을 수행하고, 일을 어떻게 처리할지 정리하며, 필요하면 다른 도메인 담당자와 업무를 주고받습니다.

document: 문서고와 처리 규칙: 일을 진행하는 문서 양식, 처리 순서, 문서 정리 방법을 정해둔 문서고와 같습니다.

서비스 계층

service는 실제 일을 하는 업무 담당자입니다. 일이 어떻게 수행되어야 하는지 결정하고, 규칙, 저장 데이터, 다른 서비스, 외부 API, 부수 효과를 하나의 의미 있는 비즈니스 액션으로 조합합니다.

상품 재고: 재고를 추가, 예약, 차감해도 되는지 확인한 뒤 재고를 업데이트합니다.

결제 흐름: 결제 제공자, 주문 상태, 영수증 기록, 알림을 함께 조율합니다.

예약 규칙: 예약 시간이 겹치지 않도록 막고, 해당 시간대를 확정할 수 있는지 판단합니다.

리포트 생성: 여러 모델의 데이터를 모아 화면에서 보거나 내보낼 수 있는 요약을 준비합니다.

간단한 기준은 이렇습니다. 코드가 비즈니스 질문에 답한다면 service 로직에 두고, 화면을 그리거나 임시 UI 상태만 다룬다면 UI 쪽에 둡니다.

의존성 주입

service는 필요한 도구를 직접 만들지 않고 주입받을 수 있습니다. 이는 한 업무 담당자가 다른 도메인 담당자, 공유 API, signal, 런타임 adaptor에게 도움을 요청하는 방식입니다.

service: admin이 security를 쓰거나 ticket이 notification을 쓰는 것처럼 다른 도메인 service를 주입합니다.

use / env: storage, email, payment, device API 같은 설정값이나 외부 API를 주입합니다.

signal: service 로직이 signal 수준의 동작을 publish하거나 호출해야 할 때 server signal을 주입합니다.

plug: plug는 service나 runtime 객체를 queue, cache, storage, scheduler, websocket 같은 adaptor role에 연결합니다.

adaptor: adaptor는 교체 가능한 런타임 연결자입니다. 같은 service가 solid, redis, local, cloud 기반 구현을 사용할 수 있습니다.

memory: memory는 service가 소유하는 런타임 상태를 로컬 또는 cache adaptor를 통해 보관할 때 사용합니다.

Signal 표면

signal은 비즈니스 서비스의 전화 상담원과 비슷합니다. page와 생성된 client의 연락을 받고, 유효하지 않거나 위험한 요청을 필터링하고, 호출 가능한 표면을 관리하며, 유효한 일을 알맞은 service에 전달합니다.

endpoint: API surface를 통해 사용자가 호출할 수 있는 액션입니다. endpoint는 HTTP 성격의 query/mutation 또는 WebSocket 성격의 message/pubsub로 나뉩니다.

slice: 화면이 읽는 목록/상세 데이터 surface입니다. slice는 guard, param, search, document filter를 묶어 UI가 일관된 화면 데이터를 불러오게 합니다.

internal: 공개 UI 액션으로 노출하지 않고 schedule, queue, internal process로 실행할 수 있는 서버 전용 작업입니다.

Endpoint 전송 방식

요청-응답 API 작업에는 query/mutation을 사용합니다. 화면에 WebSocket 동작, 실시간 메시지, room 기반 publish/subscribe가 필요하면 message/pubsub를 사용합니다.

운영 제어

signal은 request guard, parameter, search input, message input, cache hint, throttling 성격의 운영 경계를 설명하는 위치이기도 합니다.

Signal 형태 선택하기

제품 동작에서 시작하세요. 사용자가 지금 답을 받아야 하는지, 열린 연결로 대화해야 하는지, 여러 화면에 알림을 보내야 하는지, 나중에 끝나는 백그라운드 작업인지에 따라 선택합니다.

Signal shape choice

지금 답하기

화면이 한 번 요청하고 한 번의 결과를 기대한다면 query 또는 mutation을 사용합니다. 목록 불러오기, 폼 저장, 요청 승인, 재고 추가에 적합합니다.

screen calls 8282/api, business service returns result

연결을 유지하며 대화

열려 있는 화면이 서버와 WebSocket 방식으로 대화해야 한다면 message를 사용합니다. 장비 제어, 실시간 운영 패널, 단계형 작업 흐름에 적합합니다.

open connection, send message, receive reply

여러 화면에 알림

하나의 비즈니스 변경을 여러 열린 화면, 대시보드, 장비, 사용자에게 밀어줘야 한다면 pubsub를 사용합니다.

service changes data, publish, subscribers update

나중에 끝내기

작업이 queue에 들어가거나, 예약되거나, 반복되거나, 서버 생명주기와 연결된다면 process, cron, interval, timeout, initialize, destroy를 사용합니다.

request or schedule, worker, save or publish result

비즈니스 서비스 시나리오

제품 상황에서 비즈니스 서비스 경로를 고르세요. 어떤 화면은 즉시 답이 필요하고, 어떤 작업은 백그라운드 worker가 필요하며, 어떤 변경은 데이터가 바뀐 뒤 열린 화면에 알려야 합니다.

단순 요청/응답

사용자가 한 번 클릭하고 지금 결과를 기대할 때 사용합니다. 재고 추가, 요청 승인, 예약 취소, 프로필 저장이 여기에 해당합니다.

endpoint(query/mutation), service, document, response

Signal은 액션을 endpoint로 노출합니다. Service는 규칙을 확인하고 데이터를 변경합니다. 화면은 결과를 즉시 받습니다.

단순 요청/응답

백그라운드 작업

오래된 예약 만료, 파트너 데이터 동기화, 실패한 장비 작업 재시도처럼 일정에 따라 반복 실행해야 하는 작업에 사용합니다.

cron signal, batch runtime, service checks targets, saved result

Internal signal이 cron 일정을 선언합니다. Batch runtime이 이를 반복 실행합니다. Service는 처리 시점이 된 대상을 찾고 비즈니스 규칙을 적용합니다.

백그라운드 작업

리포트 생성

사용자가 무거운 내보내기, 월간 요약, 정산 파일, 분석 리포트를 요청할 때 사용합니다.

endpoint starts report, process builds file, slice shows status

Endpoint가 리포트 작업을 시작합니다. Internal process가 파일이나 요약을 생성합니다. Slice는 화면이 진행률, 상태, 다운로드 결과를 읽게 합니다.

리포트 생성

실시간 채팅

한 사용자가 보낸 메시지가 다른 사용자의 열린 채팅 화면에 즉시 보여야 할 때 사용합니다.

message/mutation saves chat, pubsub publishes to room, open chat screens update

Endpoint가 채팅 액션을 받고 service가 메시지를 저장합니다. Pubsub는 저장된 채팅을 채팅방에 전달해 열린 화면들이 메시지를 바로 추가할 수 있게 합니다.