예쁜계약에서 배운 것: 화면보다 계약의 상태가 먼저였다

21앤에서 전자계약 플랫폼을 만들 때 사용자 앱, 병원 관리자 웹, 통합 관리자 웹을 함께 다뤘다. 세 화면은 목적이 달랐지만 같은 계약을 보고 있었다. 어느 한 화면만 자연스럽게 만드는 것으로는 전체 흐름이 맞지 않았다.

한 계약을 세 역할이 다르게 본다

사용자는 자신이 서명해야 하는지 알고 싶다. 병원 관리자는 진행 상황과 필요한 문서를 확인해야 한다. 통합 관리자는 여러 계약과 정산 흐름을 살펴야 한다. 각 화면에 필요한 표현은 달라도 계약 상태의 의미가 서로 달라지면 안 된다.

당시에는 계약과 포인트, 정산이 맞물리는 도메인을 풀스택으로 담당했다. 이 경험을 돌아보면 API 개수를 정하는 것보다 중요한 것은 상태가 바뀌는 조건을 한곳에서 설명하는 일이었다. 버튼의 이름이 같아도 역할에 따라 실행할 수 있는 시점이 다르기 때문이다.

상태 이름보다 전환 조건

상태 목록을 만드는 것만으로 충분하지 않다. 누가 어떤 상태에서 다음 상태로 옮길 수 있는지, 외부 서명이 완료되어야 하는지, 실패했을 때 이전 상태를 유지하는지까지 필요하다. 지금 다시 설계한다면 각 전환에 실행 주체, 전제 조건, 부수 효과를 붙여 검토하겠다.

예를 들어 계약 완료와 정산 완료를 같은 의미로 취급하면 후속 처리의 실패를 표현하기 어렵다. 문서가 완성된 것과 돈의 처리가 끝난 것은 다른 사건이다. 이 둘이 연결되어야 한다는 요구와 같은 상태여야 한다는 요구를 구분해야 한다.

프론트의 편의와 서버의 최종 판단

프론트는 사용 가능한 버튼을 보여 주고 다음 행동을 안내해야 한다. 서버는 요청이 실제로 허용되는지 다시 판단해야 한다. 오래 열어 둔 화면이 최신 상태를 모를 수 있기 때문이다. 지금이라면 이미 다른 관리자가 상태를 바꾼 경우를 정상적인 충돌 상황으로 취급하고 사용자에게 새 상태를 보여 주겠다.

이 프로젝트는 풀스택의 장점을 분명히 느끼게 했다. 같은 사람이 여러 화면과 API를 볼 수 있어 용어의 어긋남을 찾기 쉬웠다. 동시에 머릿속으로만 규칙을 공유하기 쉬운 위험도 있었다. 다음에는 상태 전이 표를 구현의 부속 문서가 아니라 화면과 서버가 함께 보는 출발점으로 두겠다.

관련 기록: 21앤 전자계약 플랫폼 사례