Files
dbx-main/CLAUDE.md
T

15 KiB
Raw Blame History

main-app ERP 프로젝트 작업 기준

이 문서는 Claude Code가 이 저장소에서 작업할 때 가장 먼저 확인하는 기준 문서입니다. 작업 시작 전, 아래 "반드시 먼저 읽을 문서"를 모두 확인한 뒤 작업을 시작합니다.


반드시 먼저 읽을 문서

Claude Code는 이 저장소에서 작업을 시작하기 전에 반드시 아래 문서를 순서대로 읽고 맥락을 확보한 뒤 작업한다.

  1. docs/PROJECT_OVERVIEW.md — 프로젝트 정의, 기능 범위, 연동 대상
  2. docs/SERVER_ARCHITECTURE.md — 서버 구성도와 네트워크 흐름
  3. docs/DATABASES.md — PostgreSQL DB 구성과 명명 규칙
  4. docs/DEPLOYMENT.md — 배포 경로, 서비스 실행 방식, 복구 절차

문서 간 내용이 충돌하면 위의 우선순위(1 → 4)를 따른다.


프로젝트 한 줄 정의

main-app은 DBX ERP 시스템의 메인 프로젝트(허브) 이다.

담당 영역:

  • 주문관리

  • 상품코드 매칭

  • 재고관리

  • CS관리

  • 반품관리

  • 외부 쇼핑몰 API 연동 (카페24, 네이버 스마트스토어, 사방넷 등)

  • 개인경비 (app/modules/expense/, expense_db)

  • 쿠팡 밀크런 (app/modules/cupang/, cupang_db) — 출고 달력/상자 계산, 상품은 itemcode_db 읽기 전용. 출고 묶음은 상자 계산 화면의 [분배 확정] 으로만 만든다(신규 등록 폼 없음, /cupang/new 는 상자 계산으로 리다이렉트). 확정 조건: 미배분 상자 0 + 담긴 센터마다 출고방식(택배/파렛트) 선택. 확정 시 센터마다 출고 묶음 1건(status=출고준비, 센터입고일=출고일+1일, 상자 구성은 cupang_shipments.box_plan JSONB 에 스냅샷 — 혼합 상자 내용물·상자 종류 표시용) + 출고리스트 엑셀 자동 다운로드(GET /cupang/export.xlsx?date=, 시트명 YYYYMMDD). 양식 생성은 app/modules/cupang/export.py 한 곳에서 만들어 xlsx·구글시트가 공유. CUPANG_SHEET_ID + 인증(사용자 OAuth GOOGLE_SHEETS_OAUTH_REFRESH_TOKEN 또는 서비스 계정 GOOGLE_SHEETS_CREDENTIALS[_JSON]) 설정 시 확정과 동시에 Google 스프레드시트에 출고일 시트를 생성/덮어쓰기(app/integrations/google_sheets.py, 미설정이면 조용히 skip). 출고 삭제(건별/날짜 전체) 시에도 같은 날짜 시트를 동기화 — 남은 출고가 있으면 다시 쓰고, 없으면 시트 삭제(문서에 시트가 하나뿐이면 내용만 비움). 작업 중 상태는 cupang_box_calc_drafts 에 이름 붙여 임시 저장/불러오기. 쿠팡 로켓 매출(/cupang/sales, cupang_sales·cupang_sales_weekly) — 발주 라인별 공급가·원가·물류비·마진 표. 기간/센터/유형/검색 조회, 행 CRUD, 구글 시트 양식 xlsx·csv 업로드(같은 발주번호+SKU+출고일+센터+수량은 덮어씀), 엑셀 다운로드. 광고비·할인 프로모션·장려금은 주차 단위(cupang_sales_weekly)로 보관하고 순마진은 화면에서 계산. 초기 데이터는 scripts/sql/cupang_sales_seed.sql. 쿠팡 발주 엑셀(xlsx) 다중 업로드 지원(POST /cupang/api/box-calc/upload, openpyxl) — F13 입고예정일의 하루 전 = 출고일, 22행부터 B=쿠팡상품코드·F=센터명·G=수량을 읽어 cupang_products.coupang_item_code 로 제품 매칭 후 센터별 합산 → 센터 단위로 상자 계산·자동 배분

  • 휴가 관리 (app/modules/vacation/, vacation_db) — 월간 달력(구글식 bar)/연차·반차 신청/승인 워크플로/공휴일·연차 설정. 권한키 vacation·vacation_approver

  • 말레이시아 창고 재고관리 (app/modules/malaysia/, malaysia_stock_db) — 낱개(MT/MX/MZ) 입출고·조정, 세트(MY) BOM, 일일 재고조사(세트→낱개 자동 분해), 현재고 현황. 뚜껑(MD-)은 재고 집계 제외 — 단, 창고 랙에는 위치 확인용으로 배치 가능(store.LID_ITEMS). 상품은 itemcode_db 읽기 전용. 권한키 malaysia

  • 말레이시아 배송 (app/modules/dispatch/, dispatch_db) — TikTok·Shopee 출고관리. 플랫폼별 데이터 엑셀 업로드(TikTok=03_TikTok_Order_Export.xlsx, Shopee=Packing List.Doorstep Delivery.xlsx) → 1상자=1카드 출고 작업 리스트·SKU 피킹 요약·Kagayaku 전달표 자동 생성. 1상자 묶음 기준 Package ID > Tracking ID > Order ID, 같은 상자 같은 SKU 합산. 작업 상태 토글(dispatch_logs 기록). 받는 사람 이름/전화/주소는 상자 단위로 저장(작업 카드 표시 + 출고 엑셀 생성용 — 개인정보). 배치 다운로드 zip 에 업로드 원본 + 취합 출고 엑셀(YYYY.MM.DD(Ddd)_tictoc|shopee.xlsx) 포함. 엑셀은 openpyxl 파싱/생성. 권한키 dispatch. 상세는 docs/DISPATCH_MODULE.md

  • 카페24 상품관리 (app/modules/cafe24/, cafe24_db) — 카페24 관리자에 들어가지 않고 상품 상세페이지(description HTML) 조회·편집·즉시적용·예약적용·버전 이력. 3분할 화면(목록 | HTML 편집기 | 상품 정보 패널). 정보 패널(routes_product_info.py, _side.html)에서 상품명·판매가·공급가·소비자가, 대표이미지(POST /admin/products/{no}/images 에 base64 data URI + image_upload_type=A — NNEditor 업로드 경로를 PUT detail_image 에 넣는 방식은 적용 안 됨), 옵션(생성/이름·썸네일·표시방식 수정/삭제)·품목(자체코드·추가금액·진열·판매)을 수정. 카페24 OAuth/API 클라이언트는 향후 주문관리와 공유하기 위해 공통 계층 app/integrations/cafe24/ 에 둔다 — 라우터에서 httpx/requests 직접 호출 금지. 토큰은 Fernet 암호화 저장(CAFE24_TOKEN_SECRET), 로그/화면에 토큰·시크릿 절대 미출력. 쓰기 직전 항상 카페24 현재 HTML 을 다시 읽어 BACKUP revision 생성(로컬 값을 현재값으로 가정 금지). 카페24 관리자 API 는 PUT 뒤 한동안 GET 에서 예전 값을 돌려준다(읽기 지연) — 우리 캐시 문제가 아니다. 그래서 "마지막 쓰기가 권위": 상세설명은 카페24 값이 최근 revision 중 하나와 같으면 지연으로 보고 마지막 MANUAL/SCHEDULED 를 표시·지문 기준으로 쓰고(store.resolve_description), 스칼라(상품명·가격·이미지·진열/판매)는 PUT 응답 스냅샷(cafe24_products.last_write_snapshot, 마이그레이션 004)과 GET 의 updated_date 를 비교해 덮어씌운다(store.overlay_recent_write). 유예시간 CAFE24_READ_LAG_GRACE_MIN(기본 360분). 쓰기 후 화면은 PUT 응답으로 그리고 다시 GET 하지 않는다. 예약은 DB 저장 + 별도 worker(app/modules/cafe24/worker.py, compose 서비스 dbx-cafe24-worker)가 처리 — 웹 프로세스에서 대기하지 않는다. 권한키 cafe24(연결/해제는 admin 전용). 상세는 docs/CAFE24_MODULE.md

  • 프로젝트 관리 (app/modules/project/, project_db) — 아사나식. 프로젝트/서브프로젝트(self-FK parent_id, CASCADE)·프로젝트 색상(32색 — 아사나 16색 + 진한 16색)·아이콘(projects.icon, Material Symbols 42종, 마이그레이션 011)·작업(tasks: 담당자·우선순위·시작/마감)·진행단계(project_stages 칸반, 생성시 기본 4단계 seed, 섹션 기본 담당자 default_assignee_email — 담당자 빈 작업을 그 섹션에 만들거나 옮기면 자동 배정, 마이그레이션 009)·멤버 배정(project_members)·활동이력(project_activity). 첫 화면(/project/)은 내 작업 목록(프로젝트 홈 카드 화면은 폐지). 프로젝트 화면은 캘린더(FullCalendar)/타임라인(vis-timeline)/보드/목록/대시보드 뷰 토글. 좌측 사이드바는 수신함·내 작업·휴지통·프로젝트 화면 공용(templates/project/_side.html + 프로젝트 목록 동작 initSideTree, 새 프로젝트/수정 모달 _side_modals.html) — 프로젝트 목록(순서 변경·✎·×)은 어느 화면에서나 같다. 보드는 아사나처럼 섹션이 가로로 계속 늘어나고(넘치면 가로 스크롤) 카드의 담당자·마감일을 클릭해 그 자리에서 바꾼다. 좌측 사이드바에 수신함·내 작업(접이식) 메뉴. 설명란은 주소 붙여넣기 시 자동 링크, 설명란·댓글에서 @로 멤버를 태그하면 (task_mentions, 마이그레이션 006) 수신함에 그 작업이 쌓인다. 진입 권한키 project(관리자 페이지 토글로 직원별 부여, admin 자동). 프로젝트 생성은 project 권한자 누구나(만든 사람이 owner), 삭제는 만든 사람만(슈퍼관리자 예외), 사용자 배정은 is_admin 만. 배정 멤버(또는 owner/admin)만 그 프로젝트를 조회(화면·API 모두, 비멤버 403)하고 서브프로젝트/작업/단계 CRUD — URL 의 섹션·부모 작업이 그 프로젝트 것인지 서버가 검증. 실시간 반영은 project_live_version 카운터(마이그레이션 007, 미적용 시 MAX 폴백). 사이드바 전체 검색(/api/search, 제목·설명·댓글, pg_trgm) + 프로젝트/내 작업 필터 바(찾기·상태·담당자·마감·우선순위·정렬, 클라이언트 필터). 협업자(task_followers, 자동 팔로우: 만든 사람·담당자·댓글·@태그) — 완료·댓글 알림은 담당자+협업자에게만. 작업 삭제는 휴지통(project_trash, 마이그레이션 010) — 삭제 직전 스냅샷 3개월 보관, 관리자만 보기·복구(/project/trash). 연간 목표(마이그레이션 013, goal_* 테이블) — 사이드바 "목표" → 연도 펼침 → /project/goals/{연도} 에 매출(목표·실적·달성)·로아스 월별 숫자 + 업무 영역(상품·마케팅·컨텐츠·유통 등)별 연간·월별 글, 조회는 전원·입력은 is_admin 만. 마감 알림(reminders.py 데몬 스레드, 영업일 09시, D-1/당일/지연, task_reminders 로 중복 방지, PROJECT_REMINDER_* env) — 마이그레이션 008. 라우터 핸들러는 동기 DB 라 def 로 둔다(async def 금지). 말풍선은 전부 아사나식 공용 말풍선(.pj-hovertip) — 새 기능도 title=/data-tip= 만 달고 별도 툴팁 구현 금지. 멤버 배정 후보는 project 권한 보유 등록 사용자에서 자동 목록(GET /project/api/assignable-users). 작업 배정·완료 시 관리자에게 메일(app/mail.py stdlib smtplib, SMTP_*+PROJECT_NOTIFY_EMAIL env, 미설정 시 조용히 skip, BackgroundTasks 비동기). 작업 창은 저장 버튼 없이 실시간 저장(칸별 PUT, saveField/saveChain, 새 작업은 제목이 생기는 순간 생성). 댓글 답글·이모티콘 반응(마이그레이션 012 task_comments.parent_id·task_comment_reactions, 미적용 시 버튼 숨김·API 503), 완료 이력 줄은 project_activity completed 를 댓글 사이에 표시(댓글 수 제외), 댓글 @아이디 는 아이콘+이름 칩. 수신함 "확인"은 페이지 이동 없이 오른쪽 iframe 패널(/project/p/{pid}?task=&embed=1, html.pj-embed). 상단 바 화면 배율 토글(html.pj-ui-scale → .erp-app zoom .75, 2880×1620·200%용) — 팝업은 반드시 document.body 에 붙인다(배율 안의 fixed 좌표는 어긋남). 상세는 docs/PROJECT_MODULE.md

  • 실적 (app/modules/performance/, performance_db) — 쇼핑몰 통합 매출. 네 영역 분리: ① 수집 adapters/(쇼핑몰 하나 = 어댑터 파일 하나 + registry.py 한 줄 + SQL seed 한 줄) + sync.py(공통 동기화, 같은 쇼핑몰 동시 실행 차단, 쇼핑몰별 실패 격리) ② 보안 security/(AES-256-GCM, 키 버전, 비밀값 가리기) + credentials.py ③ 계산 calc.py(주=월~일, 수수료 반올림은 commission() 한 곳, 요율 이력) + db.py ④ 화면 dashboard.py/router.py/템플릿. 쇼핑몰 API 인증정보는 .env 가 아니라 설정 화면에서 입력 → 마스터 키 APP_ENCRYPTION_KEY 로 암호화해 DB 저장, secret 원문은 화면으로 다시 보내지 않는다. 쇼핑몰 API 는 백엔드에서만 호출, 오류·로그·raw 는 redact 후 저장. 매출 기준일: 결제=결제일, 취소·반품=발생일(sync.sales_date_for). 금액은 원 단위 정수. 권한키 performance, 설정 화면·API 는 is_admin. 카페24 어댑터는 기존 app/integrations/cafe24 토큰 재사용. 1단계는 모의 데이터(is_sample)·구조까지, 실제 수집은 쇼핑몰별로 공식 문서 확인 후 순차 구현. 상세는 docs/PERFORMANCE_MODULE.md

상세는 docs/PROJECT_OVERVIEW.md.


개발 원칙

  • 기존 코드를 수정하기 전 관련 파일을 먼저 읽고 구조를 파악한다.
  • 위험 명령은 반드시 사용자 확인 후 실행한다 (아래 "위험 명령" 절 참고).
  • .env, API 키, DB 비밀번호, OAuth Secret, 토큰은 절대 Git에 올리지 않는다.
  • 신규 DB가 필요하면 승인 요청 후 생성하며, DB명은 반드시 _db로 끝낸다 (예: inventory_db).
  • 예전 문서/코드의 orderlist_app은 현재 기준 orderlist_db이다. 발견 시 수정 대상.

위험 명령 (사용자 확인 없이 실행 금지)

아래 명령은 반드시 사용자에게 의도를 설명하고 명시적 승인을 받은 뒤 실행한다.

분류 명령 예시
파일 삭제 rm -rf, Remove-Item -Recurse -Force
DB 파괴 DROP DATABASE, DROP TABLE, DROP SCHEMA
데이터 삭제 TRUNCATE, 조건 없는 대량 DELETE, UPDATE
Docker 파괴 docker volume rm, docker volume prune, docker system prune -a --volumes
Git 파괴 git reset --hard, git push --force, git clean -fd, git branch -D
운영 초기화 운영 DB 덤프 덮어쓰기, 마이그레이션 롤백

원칙:

  1. 실행 전 현재 상태 확인 명령을 먼저 보여준다 (예: docker ps, \l, git status).
  2. 백업 존재 여부와 위치를 명시한다.
  3. 실행 후 결과 확인 절차를 같이 제시한다.

서버 작업 원칙

  • 배포, DB 복구, Docker 작업 전에는 현재 상태 확인 명령을 먼저 제안한다.
  • PostgreSQL 작업 전에는 DB명, 컨테이너명, 포트, 백업 위치를 확인한다.
  • 운영 서버 경로와 개발 PC 경로를 혼동하지 않는다.
    • 개발 PC: G:\내 드라이브\프로젝트\Main-app
    • 운영 서버 (main-app): /opt/www/main ← 본 프로젝트 경로
    • 참고용 (같은 호스트 내 다른 서비스 경로): /opt/dbx-corm, /opt/dbx-orderlist
    • 명령 예시·문서 작성 시 main-app 경로는 반드시 /opt/www/main 사용. 상세는 docs/DEPLOYMENT.md.

환경 변수 / 비밀값

  • .env, .env.local, .env.production 은 Git에 절대 커밋하지 않는다.
  • 예시 파일(*.example)만 커밋한다.
  • 비밀값 유출이 의심되면 즉시 회전(rotate)을 권고한다.
  • 신규 환경변수 추가 시 *.example 파일과 본 문서(또는 docs/DEPLOYMENT.md)에 변수 설명을 함께 갱신한다.

디렉터리 구조 (요약)

Main-app/
├─ app/                  FastAPI 앱 소스
├─ docs/                 운영/설계 문서 (작업 전 필독)
├─ scripts/              배포·유지보수 스크립트
├─ skills/               Claude Code 규칙/스킬
├─ docker-compose.yml    운영 컴포즈
├─ docker-compose.local.yml  로컬 컴포즈
├─ Dockerfile
├─ requirements.txt
└─ CLAUDE.md             ← 이 문서