o2o-negosium-original/negodata/front/README.md

negodata 프론트엔드

negosium/negodata 협상 플랫폼의 웹 프론트엔드.

스택

• 빌드 / 런타임: Vite 6 + React 19 + TypeScript
• 라우팅: react-router v7 (createBrowserRouter)
• 서버 상태: TanStack Query (React Query)
• UI: Tailwind CSS v4 + shadcn/ui, lucide-react, sonner
• 폼 / 검증: react-hook-form + zod
• 전역 상태: zustand
• API 클라이언트: orval (백엔드 OpenAPI → 타입·React Query 훅 자동생성)

실행

이 프론트는 단독으로 띄우지 않는다. 최상위 negosium 폴더(저장소 루트)의 docker compose 로 DB·백엔드와 함께 기동한다.

# 저장소 루트(o2o-negosium)에서 — 전체 스택(DB + 백엔드 2개 + 프론트)
docker compose up -d --build

• 프론트: http://localhost:3001 (compose 가 컨테이너 :3000 → 호스트 :3001 로 매핑)
• 소스를 바인드마운트하므로 코드 수정은 HMR 로 자동 반영된다.

프론트만 단독 개발 (선택)

도커 없이 이 폴더만 띄울 때:

npm install
cp .env.example .env   # 환경변수 (아래 표)
npm run dev            # http://localhost:3000

환경변수 (.env)

.env.example 을 복사해서 만든다. 실제 .env 는 git 에 안 올라간다(.gitignore).

변수	기본값	설명
VITE_API_BASE_URL	http://localhost:9400	백엔드 API 주소. 빌드 시 정적으로 구워진다(운영 빌드는 build arg 로도 전달).

ORVAL_INPUT 은 .env 가 아니라 orval 실행 시 쓰는 셸 환경변수다 (아래 참고).

스크립트

명령	설명
npm run dev	개발 서버 (vite, :3000)
npm run build	프로덕션 빌드
npm run preview	빌드 결과 미리보기
npm run lint	타입 체크 (tsc --noEmit)
npm run orval	백엔드 OpenAPI 로 API 클라이언트 재생성 (아래)

API 클라이언트 생성 (orval)

백엔드 FastAPI 의 OpenAPI 스펙을 읽어 src/api/generated 에 React Query 훅 + 타입을 생성한다. 설정은 orval.config.ts.

# 기본: 백엔드를 :9400 으로 띄운 뒤 라이브 스펙에서 생성
npm run orval

# 백엔드 없이: 저장된 openapi.json 파일을 가리켜 생성
ORVAL_INPUT=../backend/openapi.json npm run orval

• 입력: http://localhost:9400/openapi.json (또는 ORVAL_INPUT 으로 지정한 파일)
• 출력: src/api/generated/** (tags-split, 모델은 generated/model)
• 산출물은 자동생성물 — 직접 수정 금지. 백엔드 API 가 바뀌면 다시 실행한다.
• 모든 생성 호출은 공통 mutator src/api/mutator/custom-fetch.ts 를 통과한다 (baseURL·토큰·에러 처리). baseURL 은 VITE_API_BASE_URL 을 쓴다.
• FastAPI operationId(list_items_v1_item_list_get)는 _v1_ 앞부분만 취해 camelCase 로 정리 → listItems / useListItems 형태가 된다.

디렉토리 구조

src/
  app/           # 엔트리(main), router, provider
  api/
    generated/   # orval 자동생성 (직접 수정 금지)
    mutator/     # custom-fetch (요청 공통 로직: baseURL·토큰·에러)
  features/      # 도메인별: auth, products(상품), partners(협력사), quotations(견적), cards
  components/    # ui(shadcn), layout
  pages/         # 화면
  stores/        # zustand 스토어
  lib/           # 공용 유틸

코딩 컨벤션

에러 처리 규칙

에러는 던지는 곳(service/hook) 과 잡는 곳(UI) 을 분리한다.

• service / hook 계층 — 에러를 처리하지 않는다. 실패하면 throw 로 위로 전파만 한다. 화면을 모르므로 "에러를 어떻게 보여줄지" 를 결정하지 않는다.
  • 단, 사람이 읽을 수 있는 메시지로 가공한 뒤 다시 throw 하는 건 허용 (예: features/auth/service.ts 의 callAuth — ApiError → Error(error_message)).
• UI 계층(페이지/컴포넌트) — try/catch 로 잡아서 화면에 반영한다 (예: pages/login.tsx 의 handleSubmit → setError(...)).

예외: 에러를 무시해도 되는 동작은 그 자리에서 삼킨다. 예) service.ts 의 logout — 서버 호출이 실패해도 로컬 토큰만 정리하면 되므로 UI까지 올리지 않는다.

계층	에러 태도
orval / API 호출	실패 발생 (raw)
callAuth 같은 래퍼	잡아서 다듬고 다시 throw
service / hook	그냥 통과 (안 잡음)
UI (페이지)	catch → 화면 표시