사람함께에이전트▾

사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.

함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.

에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.

소개▾

시작하기 작동원리 실습하기

튜토리얼▾

상세하게 보여주기 상태 변경하기 서비스 내에서 상호작용 슬라이스로 표시하기 페이지를 통한 UX 스칼라 사용하기 인사이트 사용하기 데이터 연결하기

시스템 아키텍처▾

개요 백엔드 시스템 프론트엔드 시스템 환경변수 기본 스칼라 타입 도메인 기반 모듈 CSS

모듈 규칙▾

개요 model.constant.ts model.dictionary.ts model.document.ts model.service.ts model.signal.ts model.store.ts Model.Template.tsx Model.Unit.tsx Model.Util.tsx Model.View.tsx Model.Zone.tsx

스칼라 규칙▾

개요 scalar.constant.ts scalar.dictionary.ts scalar.document.ts

상태 변경하기

고객들이 아이스크림 주문을 생성하고 볼 수 있게 되었으니, 이제 가게 직원이 주문 생명주기를 관리할 수 있는 기능을 추가해봅시다. 실제 아이스크림 가게에서는 주문이 다양한 단계를 거쳐야 합니다: "활성"(새로 접수됨)에서 "처리중"(준비 중)으로, "서빙완료"(완료됨)로, 필요시 "취소됨"으로 말입니다.

상태 수정을 실제 아이스크림 가게의 워크플로우처럼 생각해보세요. 고객이 주문을 하면 "활성" 상태로 시작됩니다 - 주문판에 붙은 티켓처럼요. 그 다음 직원이 준비를 시작하고("처리중"), 마지막으로 고객에게 서빙합니다("서빙완료"). 이 튜토리얼에서는 적절한 검증과 사용자 친화적인 제어를 통해 이러한 자연스러운 워크플로우를 구현하는 방법을 보여드립니다.

기능을 구현하기 전에, 아이스크림 주문 상태 전환의 비즈니스 로직을 이해해봅시다:

🟢Active → Processing

고객이 주문을 하면 "활성" 상태로 시작됩니다. 직원이 "작업시작"을 클릭하여 처리를 시작할 수 있습니다.

🔵Processing → Served

주문이 준비되는 동안은 "처리중" 상태입니다. 준비가 완료되면 직원이 "서빙완료"로 표시할 수 있습니다.

⚫Active → Canceled

활성 상태의 주문만 취소할 수 있습니다. 처리가 시작되면 더 이상 취소할 수 없습니다.

⚠️비즈니스 규칙

활성 상태의 주문만 처리하거나 취소할 수 있습니다
처리중인 주문만 서빙할 수 있습니다
서빙완료와 취소됨은 최종 상태입니다

도큐먼트 비즈니스 로직 구현하기

실제 아이스크림 가게에 주문을 언제 처리하거나 취소할 수 있는지에 대한 규칙이 있는 것처럼, 우리도 코드에서 이러한 비즈니스 규칙을 구현해야 합니다. 도큐먼트 레이어는 이러한 규칙을 정의하는 곳입니다 - 누가 일하고 있든, 얼마나 바쁘든 관계없이 주문이 올바르게 처리되도록 보장하는 "가게 정책"이라고 생각하면 됩니다.

apps/koyo/lib/icecreamOrder/icecreamOrder.document.ts

이러한 메서드들은 비즈니스 규칙을 데이터 모델에 직접 구현합니다:

🔄

process(): '처리중'으로 변경하기 전에 상태가 '활성'인지 확인합니다

✅

serve(): '서빙완료'로 표시하기 전에 상태가 '처리중'인지 검증합니다

❌

cancel(): '활성' 상태의 주문만 취소될 수 있도록 보장합니다

검증이 실패하면 사용자 친화적인 오류 메시지를 위해 dictionary 키와 함께 Revert를 던집니다. 이러한 오류 메시지를 dictionary에 추가해봅시다:

apps/koyo/lib/icecreamOrder/icecreamOrder.dictionary.ts

서비스 레이어 구현하기

이제 가게 매니저처럼 역할하는 서비스 메서드가 필요합니다 - 비즈니스 규칙(도큐먼트 레이어)과 실제 데이터 저장(데이터베이스) 사이를 조율하는 것이죠. 직원이 주문을 처리하려고 할 때, 서비스 레이어는 주문을 가져오고, 비즈니스 규칙을 적용하고, 변경사항을 안전하게 저장합니다.

apps/koyo/lib/icecreamOrder/icecreamOrder.service.ts

각 서비스 메서드는 동일한 패턴을 따릅니다:

1️⃣

가져오기: getIcecreamOrder()를 사용하여 데이터베이스에서 주문을 가져옵니다

2️⃣

실행: 비즈니스 로직 메서드를 호출합니다 (process(), serve(), 또는 cancel())

3️⃣

저장: save()로 변경사항을 데이터베이스에 저장합니다

이 패턴은 서비스가 데이터베이스 트랜잭션을 안전하게 처리하는 동안 비즈니스 규칙이 도큐먼트 레벨에서 강제되도록 보장합니다.

시그널 엔드포인트 생성하기

시그널 엔드포인트를 프론트엔드(가게의 주문 표시 화면 같은)와 백엔드(주방과 관리 시스템) 사이의 의사소통 시스템이라고 생각해보세요. 직원이 화면의 "작업시작" 버튼을 클릭하면, 실제로 주문을 업데이트하기 위해 백엔드와 통신해야 합니다. Akan.js는 이러한 엔드포인트의 REST와 GraphQL 버전을 자동으로 생성하므로, 시스템의 다른 부분들이 원하는 방식으로 통신할 수 있습니다.

apps/koyo/lib/icecreamOrder/icecreamOrder.signal.ts

각 시그널 엔드포인트는 @Mutation.Public()으로 장식되고 주문 ID를 매개변수로 받습니다. resolve() 함수는 반환된 데이터가 두 API 형식 모두에 대해 적절하게 형식화되도록 보장합니다.

이러한 API 엔드포인트가 UI에서 제대로 표시되도록 dictionary 항목도 추가해야 합니다:

apps/koyo/lib/icecreamOrder/icecreamOrder.dictionary.ts

프론트엔드 스토어 액션 생성하기

스토어 레이어는 직원이 실제로 상호작용하는 제어판과 같습니다. 복잡한 API 통신을 가져와서 컴포넌트가 쉽게 사용할 수 있는 "processOrder()"와 같은 간단한 액션으로 변환합니다. 버튼을 클릭하면 스토어가 API 호출과 화면 업데이트를 자동으로 처리합니다 - 가게 POS 시스템의 버튼을 누르면 백엔드와 화면이 모두 업데이트되는 것처럼요.

apps/koyo/lib/icecreamOrder/icecreamOrder.store.ts

각 스토어 액션은 이 패턴을 따릅니다:

📡

API 호출: fetch 메서드를 통해 시그널 엔드포인트로 API 요청을 만듭니다

🔄

상태 업데이트: setIcecreamOrder()를 사용하여 새 주문 데이터로 로컬 스토어 상태를 업데이트합니다

이렇게 하면 상태 변경이 발생할 때 페이지 새로고침 없이도 UI가 자동으로 업데이트된 상태를 반영합니다.

유틸리티 컴포넌트 생성하기

실제 아이스크림 가게에 다른 주문 단계를 위한 라벨이 붙은 버튼이나 스탬프가 있는 것처럼, 각 액션에 대한 재사용 가능한 버튼 컴포넌트를 만들어봅시다. 이러한 "디지털 버튼"은 인터페이스의 어디든 배치할 수 있습니다 - 주문 카드, 상세 뷰, 직원 대시보드에 말이죠. 유틸리티 컴포넌트로 한 번 만들어두면 전체 애플리케이션에서 일관된 동작과 스타일링을 보장할 수 있습니다.

apps/koyo/lib/icecreamOrder/IcecreamOrder.Util.tsx

각 버튼 컴포넌트는 다음을 포함합니다:

🎨일관된 스타일링

각 버튼은 적절한 스타일링을 가집니다: Process는 primary, Serve는 secondary, Cancel은 outlined warning

🔒비활성화 상태

현재 상태에 따라 작업이 허용되지 않을 때 버튼을 비활성화할 수 있습니다

🌍국제화

버튼 레이블은 적절한 다국어 지원을 위해 dictionary 항목에서 가져옵니다