이번엔 소프트웨어 설계를 위한 개발 요구사항 문서, 시퀀스 다이어그램, 클래스 다이어그램, ERD 문서 4가지를 작성해보는 시간을 가져보았다.
설계 문서는 유비쿼터스 언어로 작성해야 한다는데, 실제로 업무 내의 모든 협업자가 동일한 언어로 도메인을 이해하고 소통하기 위해 동일한 언어 체계를 사용하는 것이 중요하다.
실제로 이전 회사 업무 체계에서 언어 체계가 달라 자주 혼동이 있었던 부분이 있는데, AI 검수, 실제 데이터 검수 등을 OCR, AI 프로세스 등으로 혼재해서 사용하는 것 때문에 중복 작업 등의 문제가 있었던 적이 있었다.
이번에 설계 문서를 작성하면서 앞으로의 개발을 위한 표준 언어를 정해놓고 작성하도록 노력하였다.
고려사항 1. Soft-delete vs Hard-delete
ERD 문서 작성 중 ADMIN에서 Brand와 Product에 대한 삭제·등록 처리 부분이 있었고, 사용자가 주문을 등록할 때 주문 수량이 재고를 초과하는 경우 예외를 처리하는 방식을 사용하려고 하였다.
그중 Brand와 Product에 대한 판매 여부를 Soft-delete와 Hard-delete 중 어떤 방식을 적용할지 고민하게 되었는데, 이커머스 특성상 판매 중지가 되더라도 이후 판매를 재개하거나 브랜드를 복구하는 경우가 생길 수 있으므로, 실제로 레코드를 삭제하기보다는 비활성 상태를 표시하는 컬럼으로 관리하는 것이 낫다고 판단하였다. 이에 suspended_at, sold_out_at 컬럼을 두어 상태를 명시하고 데이터를 보존하되, 비활성 상태로 전환된 지 1년이 지난 데이터는 일괄 삭제하는 Soft-delete 방식을 채택하였다.
고려사항 2. 시퀀스 다이어그램 흐름의 디테일 수준
처음에 시퀀스 다이어그램을 작성하면서, 주문 등록 API에서 여러 주문이 동시에 처리될 때 product.stock의 동시성 문제를 고민하게 되었다. 이에 따라 Optimistic Lock(버전 락) 또는 Pessimistic Lock 중 어떤 방식을 선택할지, 그리고 동시성 충돌 발생 시 어느 지점에서 예외를 처리할지 고민하였다.
그러나 문서 표현에 있어 좀 더 간략하게 작성하는 것이 좋겠다는 피드백을 받아, 다시 단순하게 접근하기로 했다. 실제로 설계 문서에 맞추어 개발을 진행하더라도 구체적인 구현 방식이나 정책은 언제든지 변경될 수 있기 때문에 문서에 지나치게 상세히 표현할 필요가 없다고 판단하였고, 전체적인 흐름 위주로 작성하기로 하였다.
고려사항 3. ERD 설계 시 Order의 상태값 표현 방법
Order의 각 row 데이터에 PAYMENT_PENDING(결제 대기), PAID(결제 완료), PAYMENT_FAILED(결제 실패), EXPIRED(결제 대기 만료) 등과 같은 상태값 컬럼을 두어 결제 상태를 명시적으로 관리하는 방식을 고려할 때, 이를 ERD에 어떻게 표현하면 좋을지 고민하였다.
결국 이 부분도 고려사항 2번과 마찬가지로, 실제 요구사항과 구현이 확정된 시점에 작성해도 늦지 않다고 판단하였다. 추후 작성 시에는 flowchart보다 State Diagram(상태 다이어그램) 을 활용하면 상태 간의 전환 흐름을 더 명확하게 표현할 수 있다.
고려사항 4. 변경되는 코드와 설계 문서의 Sync는 어떻게 조율할지
코드는 PR과 배포를 통해 변경 이력이 자연스럽게 추적되지만, 요구사항 정의서나 시퀀스 다이어그램 같은 기획·설계 문서는 코드 변경과 동기화되지 않으면 오히려 혼란을 야기하는 "잘못된 레퍼런스"가 될 수 있다고 생각했다. 스펙 변경이 발생했을 때 관련 문서 업데이트를 누락 없이 반영하기 위한 구체적인 방안이 있을지 멘토님께 문의해 보았다.
답변은, 실무적으로는 어렵지만 AI를 활용해 문서 업데이트를 보조하고, Git Hook 또는 GitHub Actions와 같은 CI/CD 파이프라인을 트리거로 삼아 코드 변경 시 관련 문서를 자동으로 갱신하는 방식이 가장 이상적으로 보인다는 것이었다. 해당 답변과 유사하게, 실제로 이전 직장에서 문서 자동화 프로세스를 구현한 경험이 있었다.
https://truthful-gallium-f2b.notion.site/2f6fdb9bd2ee80198e18dad2e5573652
서비스 매뉴얼 문서화 및 자동화 솔루션 구축 | Notion
Overview
truthful-gallium-f2b.notion.site
마무리 하면서
소프트웨어 설계 문서 작성 시 모두가 알아볼 수 있는 언어 사용과 적절한 표현 수준을 유지하고, 코드 변경과의 자동 동기화 방안까지 고려한다면 더 좋다. 이러한 문서들은 차후 협업에 큰 도움이 될 것이다.