2) SeMo(Settlement + Moa = 정산 모아) : 설계하기~:)

태하팍 입니다.
❒ 오늘은 세모 프로젝트를 통해 Claude Code를 좀 더 알아가보고 효율적으로 사용해 볼 생각 입니다.

준비

2026.02.17 - [역량 UP!/Business] - 1) SeMo(Settlement + Moa = 정산 모아)

백엔드는 Kotlin을 사용, 프론트엔드는? 기존에는 react-admin(=nonos project)을 사용하였다.
react-admin 선택은 내가 사용해보았던 프레임워크여서 빠르게 서빙하기 위해 선택을 하였다.
그리고 nonos는 처음부터 Claude Code를 사용해서 개발한 것이 아니라 직접 개발을 하는 중간에 Claude Code를 사용한 Case이다.

1. 프론트엔드 선택

  Refine이 뭔가?
  Refine은 React 기반 프레임워크입니다. 

즉:
  React (라이브러리)
    └── Refine (React 위에 만들어진 어드민/CRUD 프레임워크)
                      └── UI 라이브러리 선택 가능 (Ant Design, MUI, shadcn/ui 등)
  react-admin도 마찬가지 구조입니다:
  React (라이브러리)
      └── react-admin (React 위에 만들어진 어드민 프레임워크)
                            └── MUI에 강하게 종속
  둘 다 React입니다.
  Refine은 react-admin의 "더 유연한 버전"이라고 보면 됩니다.

1) Refine이 좋은 경우
  - CRUD + 커스텀 화면 반반 → SEMO가 여기에 해당
  - react-admin 개념(DataProvider, Resource)을 알고 있어서 전환 비용이 낮음
  - 정산 대시보드, PDF 미리보기 같은 자유로운 화면이 필요

2) 순수 React (Next.js + shadcn/ui)가 더 나은 경우
  - 커스텀 화면 비중이 80% 이상일 때
  - 어드민 프레임워크의 규칙이 오히려 걸림돌일 때

3) react-admin 유지가 나은 경우
  - 빠르게 만들고 싶고, 화면이 대부분 CRUD 테이블일 때

SEMO는 CRUD(업체 관리, 발주 목록)도 있고, 커스텀 화면(정산 요약 대시보드, PDF 정산서, 엑셀 업로드)도 있는
혼합형이라 Refine이 가장 균형 잡힌 선택입니다.
  - react-admin 경험이 거의 그대로 통함 (개념이 동일)
  - MUI를 계속 쓸 수도 있고, Ant Design이나 shadcn/ui로 바꿀 수도 있음
  - NONOS처럼 Vite + TypeScript 그대로 사용

 SEMO Frontend
  ├── Vite + TypeScript (NONOS와 동일)
  ├── Refine (어드민 프레임워크)
  ├── Ant Design (UI 라이브러리)
  └── Recharts 또는 Ant Design Charts (정산 차트)

2. 프로젝트 구조

Spring Boot + Kotlin, 베스트인가?
결론 : 베스트 인정!  
  1. 바꿀 이유가 없다!!

  2. SEMO에 Spring Boot + Kotlin이 맞는 구체적 이유
  - 정산 = 돈 계산 → Kotlin의 타입 안전성 + BigDecimal 처리가 중요
  - 엑셀 처리 → Apache POI (이미 NONOS에서 사용 중)
  - PDF 생성 → Spring 생태계에 라이브러리 풍부
  - 향후 Kafka 연동 → Spring Kafka가 가장 성숙한 라이브러리
  - NONOS API 연동 → 같은 언어라 DTO 구조 참고/공유 가능

  3. 개선할 점만 챙기면 됨
     몇 가지 업그레이드 포인트가 있습니다.

SEMO 프로젝트 구조 정리
참고 : 2025.06.20 - [Language/Kotlin] - 프론트엔드(React)와 백엔드(Kotlin)를 함께 배포하는 Monolith 구조 도전기_01

  semo/
  ├── build.gradle.kts          # 루트 빌드 (NONOS와 동일한 패턴)
  ├── settings.gradle.kts
  ├── backend/
  │   └── src/
  │       ├── main/kotlin/kr/semo/www/
  │       │   ├── SemoApplication.kt
  │       │   ├── settlement/     # 정산 도메인
  │       │   ├── order/          # 발주 도메인
  │       │   ├── invoice/        # 송장 도메인
  │       │   ├── company/        # 업체 관리
  │       │   ├── upload/         # 엑셀 업로드
  │       │   └── common/         # 공통 (인증, 예외처리 등)
  │       └── main/resources/
  │           ├── application.yml
  │           └── static/         # 프론트 빌드 결과물
  ├── frontend/
  │   ├── package.json            # Refine + Ant Design
  │   ├── vite.config.ts
  │   └── src/
  └── Dockerfile

3.  요구사항 체크 (=설계)

어떤점이 불편한지 체크를 하고 관련해서 어떤식으로 만들어야 유저입장에서 불편함없이 사용할지 고민해야할 단계
특히나 공급자와 셀러의 관계 및 하나의 계정에 여러 역할을 가질수 있다고 판단하였으며
이럴경우 유저입장에서 헷깔리지 않게 역할수행을 할수 있을지 고민 함.
로그인도 회원가입이냐 소셜인증이냐 등등

 1단계 MVP(=Minimum Viable Product (최소 기능 제품))
  ├── 인증 (네이버 로그인, 초대)
  ├── 회사/거래 관리
  ├── 상품 관리
  ├── 발주 관리 (엑셀 업로드)
  ├── 송장 관리 (엑셀 업로드)
  ├── CS 차감 (반품/취소)
  ├── 대조/매칭
  ├── 정산서 생성 (PDF)
  ├── NONOS 연동              ← 2단계
  ├── Kafka                         ← 2단계(필요 시)
  ├── 쇼핑몰 연동 (쿠팡 등)  ← 3단계

특히 CS 처리 요구사항이 중요 함.
CS의 본질부터 생각해보면 SEMO는 정산 도구이지, CS 관리 도구가 아님.
현실에서 CS가 어떻게 처리되는지 보면:
  현실:
    고객 불만 → 셀러가 카톡/전화로 공급사에 연락
    → 둘이 통화하면서 "반품할게요" "네 보내세요" 결정
    → 결정된 내용을 월말에 엑셀로 정리 ← 이게 고통
결론적으로 SEMO가 해야 할 것:
  - 카톡/전화를 대체하는 게 아님 (그건 이미 잘 되고 있음)
  - 결정된 내용을 기록하고, 정산에 자동 반영하는 것! 요게 포인트!

CS가 발생하는 상황:
  1. 반품 - 고객 변심     → 배송비 보통 셀러 부담
  2. 반품 - 상품 불량     → 배송비 공급사 부담
  3. 반품 - 오배송        → 배송비 공급사 부담
  4. 교환                → 추가 배송비 발생
  5. 취소 (출고 후)       → 회수 필요
  6. 파손                → 배송 중 파손, 택배사/공급사 책임

정산에 필요한 건 결국:
    → 얼마를 차감할 것인가?
    → 배송비는 누가 낼 것인가?

설계 시에는 토큰이 조금 더 들어가는 think or think hard로 프롬프트를 작성하였습니다.
프롬프트 작성 후 뒤에 think keyword 작성!

4.  DB 스키마 설계

claude는 설계한 내용을 메모리 업데이트를 하는데 이것은 아래와 같습니다.
메모리 업데이트란?
대화 내용을 파일로 저장해두는 겁니다.
위치는:
  .claude/projects/.../memory/
  ├── MEMORY.md          ← 프로젝트 전체 요약
  ├── architecture.md    ← 아키텍처 결정사항
  ├── requirements.md    ← 요구사항 (방금 CS 내용 반영함)
  └── db-schema.md       ← DB 스키마 (방금 새로 저장)

왜 필요하냐면 — 다음에 새 대화를 시작해도 이전에 논의한 내용을 기억합니다. 
이 파일들을 읽어서
  "아, SEMO는 Refine + Ant Design 쓰기로 했고, CS는 셀러가 등록하고 공급사가 결정하는 구조였지"를 바로 알 수 있음!

5.  프로젝트 셋팅

물어보고 sonnet으로 모델 변경!

프로젝트 세팅 완료!
완성된 구조
  semo/
  ├── build.gradle.kts          ← Kotlin 2.1 + Spring Boot 3.4
  ├── settings.gradle.kts
  ├── .java-version             ← Java 21 (jenv)
  ├── .gitignore
  ├── Dockerfile
  ├── gradlew
  ├── backend/
  │   └── src/main/kotlin/kr/semo/www/
  │       └── SemoApplication.kt
  │   └── src/main/resources/
  │       ├── application.yml       ← 공통 설정
  │       └── application-dev.yml   ← 개발용 H2
  └── frontend/
      ├── package.json          ← Refine + Ant Design
      ├── vite.config.ts        ← /v1 → 8080 프록시
      ├── tsconfig.json
      ├── index.html
      └── src/
          ├── index.tsx
          ├── App.tsx           ← Refine 기본 세팅
          └── dataProvider.ts   ← API 연동

  NONOS와 다른 점:
  - Kotlin 2.1.20 (NONOS는 1.9.25)
  - Lombok 없음
  - MariaDB 드라이버 (MySQL 대신)
  - 프론트: Refine + Ant Design (react-admin + MUI 대신)

6. DB셋팅

Charset:   utf8mb4
   - utf8mb4 — 한글 + 이모지까지 완벽 지원 (latin1은 한글 깨짐) 
Collation: utf8mb4_unicode_ci
  - utf8mb4_unicode_ci — 대소문자 구분 없는 정렬, 한글 정렬도 정확!

7. 프로젝트 간단히 띄워보기

이제 준비는 끝났습니다.
기능을 추가하면 되겠습니다!!

그럼 다음 기능추가에서 뵙겠습니다.