기술 설계 · 양식
상태 전이도 양식
상태와 전이 규칙, 금지 전이와 알림 발송까지 표로 확정한다.
이럴 때 써요
- 주문·결제·승인처럼 상태가 있는 기능을 만들 때
- "이 상태에서 저 상태로 갈 수 있나" 가 자주 문제될 때
양식 구성
8개 절로 이루어져 있습니다.
- 문서 정보
- 버전 · 대상 · 관련 정책 · 작성자 · 검토자 · 승인자 · 최종 수정일
- 1 상태 목록 정의
- 상태마다 "언제 이 상태인가" 를 한 문장으로 정의한다. 사용자에게 보이는 말과 코드 값은 다를 수 있으니 둘 다 적는다.
- 2 전이 규칙
- 어떤 이벤트로 어느 상태에서 어느 상태로 가는지 적는다. 이 표에서 그림이 자동으로 그려지니 빈칸을 남기지 않는다.
- 3 금지 전이 · 예외 처리
- 일어나면 안 되는 전이와, 시도했을 때 시스템이 무엇을 하는지 적는다. 동시에 들어온 요청 처리도 여기서 정한다.
- 4 상태별 화면 · 기능 노출
- 상태마다 사용자와 운영자가 무엇을 할 수 있는지 적는다. 화면과 상태가 어긋나면 문의가 늘어난다.
- 5 알림 발송 규칙
- 어떤 전이에서 누구에게 알릴지 적는다. 같은 알림이 두 번 가지 않게 재발송 규칙도 정한다.
- 6 이력 · 감사 로그
- 나중에 "왜 이 상태가 됐나" 를 답하려면 무엇을 남겨야 하는지 적는다.
- 7 변경 이력
- 문서를 고칠 때마다 한 줄 남긴다. 승인 뒤에 바뀐 것은 특히 빠짐없이 적는다.
바로 써 보기
로그인 없이 바로 쓸 수 있습니다. 다 쓰면 PDF·Word·한글(HWPX)·Markdown 으로 내보냅니다.
기술 설계 단계의 다른 양식
- 아키텍처 다이어그램 — 서버·DB·연동 구성 등 시스템 아키텍처를 외부 도구에서 그린 그대로 붙여 보관한다.
- 도메인 모델 정의서 — 엔티티·관계·상태를 개발자 기준으로 정의한다. 엔티티가 수십 개로 늘어도 모듈로 나눠 훑을 수 있게 한다.
- 데이터 정의서 — 화면·API 가 공통으로 참조하는 필드의 타입·정의·허용값을 한곳에 고정한다.
- 기술 설계서 (Tech Spec) — 아키텍처, 데이터 모델, API 설계를 개발 착수 전에 합의한다.
- API 명세서 — 엔드포인트별 요청·응답, 공통 에러 코드와 인증 규칙을 계약 수준으로 명세한다.
- 에러 코드 정의서 — 서비스 전체에서 쓰는 에러 코드 체계를 한곳에 고정해, API·배치·화면이 같은 코드를 같은 뜻으로 쓰게 한다.
- 배치 정의서 — 정기적으로 도는 배치·스케줄러 작업의 주기, 처리 로직, 실패 시 대응을 한곳에 정의한다.
- 연동 명세서 — 외부 시스템(파트너사·택배사·PG 등)과 주고받는 데이터의 방식·필드·인증·에러 처리를 계약 수준으로 명세한다.