기술 설계 · 양식
데이터 정의서 양식
화면·API 가 공통으로 참조하는 필드의 타입·정의·허용값을 한곳에 고정한다.
이럴 때 써요
- 같은 필드를 화면마다 다르게 계산하거나 다르게 표시할 때
- 서버 구현 직전에 필드 의미·허용값을 확정해야 할 때
- 코드값(enum)이 문서마다 달라 화면·API·DB 가 어긋날 때
양식 구성
7개 절로 이루어져 있습니다.
- 문서 정보
- 버전 · 서비스 · 관련 문서 · 작성자 · 검토자 · 승인자 · 최종 수정일
- 1 엔티티 개요
- 엔티티 자체의 정의는 용어사전을 따르고, 여기서는 어느 테이블과 이어지는지만 남깁니다.
- 2 필드 정의
- 화면·API 어디서든 이 필드가 보이면 여기 뜻을 그대로 따릅니다.
- 3 계산 · 파생 필드
- 저장은 안 하지만 화면·API 응답에 나가는 값. 로직이 두 곳에서 다르게 구현되는 걸 막습니다.
- 4 코드값 (Enum) 정의
- 코드 값과 그 뜻을 적는다. 값이 늘어나면 여기부터 고쳐야 화면·통계가 따라온다.
- 5 개인정보 · 민감정보 필드
- 개인정보가 담기는 필드를 따로 모은다. 마스킹 규칙과 보관 기간은 개인정보처리방침과 같아야 한다.
- 6 변경 이력
- 컬럼 추가·삭제·타입 변경을 남긴다. 운영 중 스키마 변경은 이력이 없으면 원인을 못 찾는다.
바로 써 보기
로그인 없이 바로 쓸 수 있습니다. 다 쓰면 PDF·Word·한글(HWPX)·Markdown 으로 내보냅니다.
기술 설계 단계의 다른 양식
- 상태 전이도 — 상태와 전이 규칙, 금지 전이와 알림 발송까지 표로 확정한다.
- 아키텍처 다이어그램 — 서버·DB·연동 구성 등 시스템 아키텍처를 외부 도구에서 그린 그대로 붙여 보관한다.
- 도메인 모델 정의서 — 엔티티·관계·상태를 개발자 기준으로 정의한다. 엔티티가 수십 개로 늘어도 모듈로 나눠 훑을 수 있게 한다.
- 기술 설계서 (Tech Spec) — 아키텍처, 데이터 모델, API 설계를 개발 착수 전에 합의한다.
- API 명세서 — 엔드포인트별 요청·응답, 공통 에러 코드와 인증 규칙을 계약 수준으로 명세한다.
- 에러 코드 정의서 — 서비스 전체에서 쓰는 에러 코드 체계를 한곳에 고정해, API·배치·화면이 같은 코드를 같은 뜻으로 쓰게 한다.
- 배치 정의서 — 정기적으로 도는 배치·스케줄러 작업의 주기, 처리 로직, 실패 시 대응을 한곳에 정의한다.
- 연동 명세서 — 외부 시스템(파트너사·택배사·PG 등)과 주고받는 데이터의 방식·필드·인증·에러 처리를 계약 수준으로 명세한다.