2/24(화) SA문서 작성하기

dev_joo·2026년 2월 24일

스파르타 Java 단기심화 6기 TIL

목록 보기

23/61

AI 검증 비즈니스 프로젝트

오늘부터 3/12일까지 팀 프로젝트를 하게되었다.
새로 만난 팀원들과 자기소개를 하고, 팀 규칙과 컨벤션을 작성하고 프로젝트 구현을 위한 기능 리스트와 ERD를 작성했다.

광화문 근처에서 운영될 음식점들의 배달 주문 관리, 결제, 그리고 주문 내역 관리 기능을 제공하는 플랫폼 개발

기술 스택
Spring Boot 3.x
PostgreSQL
Gradle
Git을 이용한 버전 관리 (GitHub)

API 문서: 제시된 작성 툴이나 양식에 맞추어 작성

프론트엔드 개발자가 API문서만 보고도 개발 할 수 있게 작성할 것!

컨벤션

Code Convention

네이밍 규칙

클래스: PascalCase → UserService, OrderController
메서드/변수: camelCase → getUserById(), orderList
상수: UPPER_SNAKE_CASE → MAX_RETRY_COUNT
패키지: 소문자 → com.company.project.domain

네이밍 규칙

레이어	관점
Controller	HTTP 동작 중심 (get/create/update/delete)
Service	비즈니스 의도 중심 (도메인 용어 사용)
Domain	객체 스스로의 행위 중심

네이밍 규칙 예시

레이어	접두사/패턴	예시
Controller	`get` / `create` / `update` / `delete`	`getUser()`, `createUser()`, `updateUser()`, `deleteUser()`
Service	`find` / `register` / `modify` / `withdraw` / `check` / `send`	`findUser()`, `registerUser()`, `modifyUserInfo()`, `withdrawUser()`
Domain	동사 원형 (상태 변경)	`activate()`, `suspend()`, `changePassword()`
Domain	`is` / `has` / `can` (상태 확인)	`isActive()`, `hasRole()`, `canOrder()`
Domain	`add` / `remove` (연관관계)	`addOrder()`, `removeTag()`

응답 타입

ResponseEntity

DTO

record 객체 사용

Git 컨벤션

커밋

커밋은 주어진 예시를 보고 각 타입에 맞는 이슈를 템플릿에 맞춰 발행해 사용하기로 했다.
Git issue는 처음 사용해보는데, Jira 외의 커밋 컨벤션을 경험해보면 좋을 것 같아 찬성했다.

작업 타입	작업내용
✨ update	해당 파일에 새로운 기능이 생김
🎉 add	없던 파일을 생성함, 초기 세팅
🐛 bugfix	버그 수정
♻️ refactor	코드 리팩토링
🩹 fix	코드 수정
🚚 move	파일 옮김/정리
🔥 del	기능/파일을 삭제
🍻 test	테스트 코드를 작성
💄 style	css
🙈 gitfix	gitignore 수정
🔨script	package.json 변경(npm 설치 등)
💫temp	임시수정

git issue 템플릿 팀원분께서 기존에 사용하던 템플릿을 친절하게 공유해주셨다!🥰

name: "🐞 Bug Report"
  
description: "버그 해결을 위한 이슈 템플릿"
labels: ["bug", "priority:high"]
title: "[BUG] "
body:
  - type: textarea
    id: bug-summary
    attributes:
      label: 💡 버그 설명
      description: 발생한 버그에 대해 간결하게 설명해 주세요.
      placeholder:
        e.g.
        로그인 시도 시 화면이 멈춥니다.
    validations:
      required: true

  - type: textarea
    id: reproduction-steps
    attributes:
      label: 📝 재현 경로 및 상황 설명
      description: 어떤 상황에서, 어떤 행동을 했을 때, 어떤 문제가 발생했는지 순서대로 적어주세요.
      placeholder: |
        e.g.
        - 상황: 사용자가 앱을 실행하고 로그아웃 상태입니다.
        - 시기: 로그인 버튼을 누르고 이메일과 비밀번호를 입력합니다.
        - 문제: 버튼이 비활성화되며 화면 전환이 이루어지지 않습니다.
    validations:
      required: true

  - type: textarea
    id: expected-result
    attributes:
      label: 🎯 예상 결과
      description: 예상했던 정상 결과는 무엇이었는지 설명해주세요.
      placeholder: e.g. 로그인 성공 후 메인 페이지로 이동해야 합니다.
    validations:
      required: true

  - type: textarea
    id: additional-info
    attributes:
      label: 📋 추가 정보 (로그, 스크린샷, 환경 등)
      description: 스크린샷, 에러 로그, 사용 환경(OS, 브라우저/앱 버전) 등 참고할만한 자료를 첨부해주세요.

name: "✨ Feature Issue"
description: "새로운 기능 개발을 위한 이슈 템플릿"
labels: ["feature"]
title: "[FEAT] "
body:
  - type: textarea
    id: summary
    attributes:
      label: 📄 이슈 내용 (기능 요약)
      description: 구현하고자 하는 기능에 대해 간단하게 요약 설명해 주세요.
    validations:
      required: true

  - type: textarea
    id: details
    attributes:
      label: 📝 상세 내용 및 요구사항
      description: 기능 추가와 관련된 추가 정보(배경, 필요성, 구체적인 요구사항 등)를 작성해 주세요.

  - type: textarea
    id: todo-list
    attributes:
      label: ✅ 체크리스트 (구현할 내용)
      description: 구현 항목을 체크박스로 작성해주세요.
      placeholder: |
        e.g.
        - [ ] API 설계 및 엔드포인트 구현 (/api/v1/new-feature)
        - [ ] 데이터베이스 스키마 수정 (Table 추가)
        - [ ] 프론트엔드 UI/UX 작업
    validations:
      required: true

  - type: textarea
    id: references
    attributes:
      label: 📍 레퍼런스
      description: 참고할만한 자료(링크, 문서 등)가 있다면 작성해 주세요.
      placeholder: |
        e.g.
        - [Figma 디자인] (https://...)
        - [관련 외부 문서] (https://...)

경험상 이렇게 이쁘게 짜져있으면 개발할 맛이 나는 것 같다. (마감기한에 다다랐을 때 빼고 ㅎㅎ)

SA 문서 작성

SA : System Analysis 또는 Solution Architecture

시스템의 전체 구조를 설명하는 설계 문서로,
“이 시스템이 어떻게 구성되어 있고, 어떻게 동작하는지”를 큰 그림에서 정리한 문서이다.

일반적인 SA 문서 내용:

1️⃣ 시스템 전체 구조

클라이언트 - 서버 구조
모놀리식 / MSA
계층 구조 (Controller → Service → Repository 등)

2️⃣ 기술 스택

Backend: Spring Boot
DB: MySQL, Redis
배포: AWS, Docker 등

3️⃣ 서버 구성도

웹 서버 / WAS / DB 서버 / 캐시 서버 / 로드밸런서 ...

4️⃣ 데이터 흐름

요청이 어떻게 들어오고
어떤 컴포넌트를 거쳐
어디로 저장되는지

5️⃣ 외부 연동 시스템

결제 API / OAuth / 외부 메시지 서버 등

또 양식에 워크 플로우가 있었는데 큰 비중은 아니어서 그런지 생략이 가능하다고 하셨다.
여태 워크 플로우를 작성 한 후에 ERD를 작성해왔어서 나에겐 조금 색다른 경험이었다.

SA 문서에 들어가는 워크플로우는 다음 내용이고,
👉 기술 동작 흐름:

로그인 인증 흐름
JWT 발급 및 검증 흐름
AI API 호출 흐름
주문 생성 처리 흐름

내가 여태 경험해본 워크플로우는 기획서 / 요구사항 정의서에 작성하는 사용자 시나리오 워크플로였다는 것을 알게 되었다.

기술 동작 중심의 SA문서에 집중하기 위해서 워크플로우 작성을 생략하는 것을 추천해주셨나보다.

작성한 SA 문서 (초안)

시스템 전체 구조

Monolithic Application
Layered Architecture

데이터 흐름

클라이언트 요청 → Controller → Service → Repository → DB 저장
응답 생성 후 Response DTO 반환

기술 스택

Spring Boot 3.5.11 (SNAPSHOT 아닌 가장 최신 3.x)
PostgreSQL
Gradle
Git을 이용한 버전 관리 (GitHub)

설계 원칙

Entity와 DTO를 분리하여 계층 간 의존성 최소화
RESTful API 원칙을 준수하여 URI 및 HTTP Method 설계
Global ExceptionHandler를 통해 예외 일괄 처리

외부 연동 시스템 (core구현 후 추가 구현)

결제 API
AI활용 편의 기능

기능 리스트

기존에 기능 도메인 기준으로 작성되었던 기능 리스트를 좀 더 잘 파악하기 위해 역할 기준으로 다시 정리해보았다.

👤 고객(일반 사용자)

1️⃣ 계정 관리

회원가입 / 로그인 / 로그아웃
회원 탈퇴

2️⃣ 가게 탐색

카테고리별 가게 조회
가게 상세 정보 및 메뉴 확인

3️⃣ 주문 및 결제

메뉴 선택 및 주문 생성
결제 진행
주문 내역 및 상태 조회

4️⃣ 리뷰 작성

별점 및 텍스트 리뷰 작성

🧑‍🍳 사장님(가게 관리자)

1️⃣ 계정 관리

회원가입 / 로그인

2️⃣ 가게 및 메뉴 관리

가게 등록 / 수정 / 삭제
메뉴 정보 관리
메뉴 이미지 생성

3️⃣ 주문 관리

주문 확인 및 수락
주문 거절 처리

4️⃣ 리뷰 관리

리뷰 조회
리뷰 답글 작성

⚙️ 시스템(공통 관리 영역)

사용자 권한 분리
결제 시스템 연동
주문 데이터 보존 정책
이미지 업로드 및 삭제 관리

ERD 작성 (초안)

기능리스트를 작성하다가 더 이상 떠오르지 않아서 ERD를 한 번 적어보면
더 구체화할 수 있을 것이라 생각되었다.

각 테이블과의 연관관계를 생각하는 것이 쉽지 않았다.
다른 칼럼으로 충분히 표현이 가능한데 이 칼럼이 필요한가? 하는 것도 있었고,
기능과 도메인 규칙 상, 그리고 기능 확장을 위해 어떤 테이블과 어떤 정보가 필요한지 한 번에 정리하기 쉽지 않았다.
이에 더해 성능까지 생각해보니 여러모로 DB 쿼리와 JPA 개념 이해가 필요했다.

그리고 무엇보다 내 생각을 조리있게 말하는게 어려웠다😂
말하다보면서 앗... 잘못 생각했구나..! 하면서 괜히 시간만 뺏는 경우가 종종 생겼다.😰

팀원들과 고민해 만들었지만, 비식별 방식으로 테이블 연관관계를 설정하는것이 맞아 새로 다시 작성하기로 했다.

또, 지금 다시 확인해 보니 비정규화된 테이블이 있어 수정이 필요했다.

비정규화 문제 :
order_item → order → store
로 이미 가게를 알 수 있는데
order_item에 store_id를 또 넣어둔 상태

자식 테이블은 "직접적으로 필요한 부모만" 참조한다.
부모를 통해 알 수 있는 정보는 중복 FK로 두지 않는다.

PK / FK에는 인덱스가 있음
2~3번 조인은 거의 비용이 미미
RDBMS는 조인 최적화를 매우 잘함
복잡한 다대다 조인 인덱스 없는 컬럼 조인 정도에서만 비정규화를 사용한다.

회고

JPA와 DB의 개념이 머릿속에 확실하게 정리되어있지 않아서 의견을 제시할 때 소극적이게 될 수밖에 없었다. 또, 스치는 아이디어나 속에 걸리는 무언가를 말하려고 할 때 이를 표현할 정확한 용어가 잘 생각이 안나서 답답했다.

앞으로의 협업에는 더 자신있게 말하고, 더 나은 비유와 설명을 할 수 있길 바란다.

dev_joo

풀스택 연습생. 끈기있는 삽질로 무대에서 화려하게 데뷔할 예정 ❤️🔥

이전 포스트

2/23(월) Layered Architecture 개론 특강, MSA - 서비스 디스커버리, 로드밸런스

다음 포스트

2/24(화) SA문서 작성하기

스파르타 Java 단기심화 6기 TIL

AI 검증 비즈니스 프로젝트

컨벤션

Code Convention

응답 타입

DTO

Git 컨벤션

커밋

SA 문서 작성

일반적인 SA 문서 내용:

1️⃣ 시스템 전체 구조

2️⃣ 기술 스택

3️⃣ 서버 구성도

4️⃣ 데이터 흐름

5️⃣ 외부 연동 시스템

작성한 SA 문서 (초안)

시스템 전체 구조

데이터 흐름

기술 스택

설계 원칙

외부 연동 시스템 (core구현 후 추가 구현)

기능 리스트

👤 고객(일반 사용자)

1️⃣ 계정 관리

2️⃣ 가게 탐색

3️⃣ 주문 및 결제

4️⃣ 리뷰 작성

🧑‍🍳 사장님(가게 관리자)

1️⃣ 계정 관리

2️⃣ 가게 및 메뉴 관리

3️⃣ 주문 관리

4️⃣ 리뷰 관리

⚙️ 시스템(공통 관리 영역)

ERD 작성 (초안)

회고

2/23(월) Layered Architecture 개론 특강, MSA - 서비스 디스커버리, 로드밸런스

2/25(수) 코드 카타

0개의 댓글