Files
dbx-main/CLAUDE.md
T
king 619f95b7f4 docs: split CLAUDE.md into per-module CLAUDE.md to cut token use
Root CLAUDE.md (loaded every conversation) shrank from 34KB to ~8KB.
Module details moved verbatim-in-substance to app/modules/<mod>/CLAUDE.md,
which Claude Code loads only when working in that folder.

- [모듈명] prefix → module table (folder, DB, perm key, docs, static files)
- shared docs read only per task type (old "read 4 docs first" rule dropped)
- large docs: read TOC via grep, then only the needed section
- cross-module dependency list kept in root

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18 02:41:26 +09:00

8.3 KiB

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

이 문서는 Claude Code가 이 저장소에서 작업할 때 매 대화 자동으로 읽는 기준 문서다. 토큰 절약을 위해 짧게 유지한다. 모듈별 상세 규칙은 각 모듈 폴더의 CLAUDE.md 와 docs/*_MODULE.md 에 둔다. 이 파일에 모듈 상세 설명을 다시 쌓지 말 것 — 새 기능 설명은 그 모듈의 CLAUDE.md(요약)·docs/*_MODULE.md(상세)에 쓴다.


작업 시작 규칙 — 필요한 것만 읽는다

사용자는 요청 앞에 [모듈명] 을 붙인다(예: [휴가] 반차 버튼 색 변경).

  1. [모듈명] 으로 아래 표에서 모듈을 찾는다.
  2. 그 모듈의 app/modules/<폴더>/CLAUDE.md 를 먼저 읽는다(요약·핵심 규칙).
  3. 코드는 그 모듈 폴더 + 표의 정적 파일만 본다. 다른 모듈 폴더는 연결이 확인될 때만 연다.
  4. 상세 문서(docs/*_MODULE.md)는 요약으로 부족할 때만 — 큰 문서는 grep -n '^#' <문서> 로 목차를 보고 필요한 절만 offset/limit 으로 읽는다.
  5. 큰 코드 파일도 통째로 읽지 말고 Grep 으로 위치를 찾은 뒤 그 부분만 읽는다.
  6. [모듈명] 이 없거나 표에 없으면 어느 모듈인지 짧게 묻는다(뻔하면 추정하고 진행).

공통 문서는 작업 종류에 해당할 때만 읽는다(예전 "4개 필독" 규칙 폐지):

작업 종류 추가로 읽을 문서
DB 테이블·마이그레이션·새 DB docs/DATABASES.md (해당 DB 절만)
배포·서버·Docker·복구 docs/DEPLOYMENT.md, docs/SERVER_ARCHITECTURE.md
여러 모듈에 걸친 작업·새 모듈 추가·전체 구조 질문 docs/PROJECT_OVERVIEW.md
화면 디자인 공통(ERP 셸·공용 CSS) docs/DESIGN.md
테스트 방법 docs/TESTING.md

문서끼리 충돌하면 PROJECT_OVERVIEW → SERVER_ARCHITECTURE → DATABASES → DEPLOYMENT 순으로 우선한다.


모듈 표

[모듈명] 폴더 (app/modules/) DB 권한키 상세 문서 정적 파일 (app/static/)
[프로젝트] [Project] project/ project_db project docs/PROJECT_MODULE.md (178KB, 절만) project*.js/css, erp-overdue.*
[실적] performance/ performance_db performance docs/PERFORMANCE_MODULE.md (절만) performance.*
[카페24] cafe24/ cafe24_db cafe24 docs/CAFE24_MODULE.md (절만) cafe24.css, cafe24-options.js
[쿠팡] cupang/ cupang_db cupang (모듈 CLAUDE.md 가 기준) cupang.*
[입출고] inout/ inout_db inout docs/INOUT_MODULE.md inout.*
[배송] [말레이시아배송] dispatch/ dispatch_db dispatch docs/DISPATCH_MODULE.md dispatch/
[말레이시아재고] [말레이시아] malaysia/ malaysia_stock_db malaysia app/modules/malaysia/README.md malaysia*.js
[휴가] vacation/ vacation_db vacation, vacation_approver (모듈 CLAUDE.md) vacation.*
[경비] [개인경비] expense/ expense_db expense (모듈 CLAUDE.md) —
[공지] [긴급공지] notice/ project_db(024) 수퍼관리자 docs/NOTICE_MODULE.md erp-notice*
[자산] asset/ asset_db asset docs/ASSET_MODULE.md asset.*
[공통] [ERP] app/main.py, app/templates/(셸·로그인·관리자), 인증·권한 — — docs/PROJECT_OVERVIEW.md, docs/DESIGN.md erp*.js/css, styles.css
[배포] [서버] docker-compose*.yml, Dockerfile, scripts/ — — docs/DEPLOYMENT.md —
[DB] scripts/sql/ — — docs/DATABASES.md —

외부 쇼핑몰 연동(사방넷·네이버 등)·주문관리·상품코드 매칭·재고·CS·반품은 허브 담당 영역 — docs/PROJECT_OVERVIEW.md 참고.

모듈 사이 연결 (이것을 바꾸면 상대 모듈도 확인)

  • itemcode_db 읽기 전용 상품: 쿠팡·말레이시아재고·입출고 (itemcode_ro 권한).
  • app/integrations/cafe24/ 토큰: 카페24 + 실적(카페24 어댑터).
  • performance_store 매출: 실적 → 프로젝트 주간 회의록 머리 카드(읽기 전용).
  • ProjectStore.pool(project_db): 프로젝트 + 긴급 공지.
  • APP_ENCRYPTION_KEY: 실적(쇼핑몰·광고 인증) + 입출고(Gmail 토큰).
  • app/integrations/google_sheets.py(쿠팡) · google_slides.py(프로젝트 회의록 보드).
  • app/mail.py: 프로젝트 알림 메일.
  • ERP 모든 화면 스크립트: erp-notice.js(공지) · erp-overdue.js(프로젝트 마감 알림).

프로젝트 한 줄 정의

main-app은 DBX ERP 시스템의 메인 프로젝트(허브) 이다. 상세는 docs/PROJECT_OVERVIEW.md.


개발 원칙

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

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

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

분류 명령 예시
파일 삭제 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(또는 그 모듈 CLAUDE.md)에 변수 설명을 함께 갱신한다.

디렉터리 구조 (요약)

Main-app/
├─ app/                  FastAPI 앱 소스
│  ├─ modules/<모듈>/    모듈별 코드 + templates/ + CLAUDE.md(모듈 요약)
│  ├─ integrations/      외부 API 공통 계층(cafe24, google_sheets, google_slides)
│  ├─ static/            정적 파일(모듈별 js/css)
│  └─ templates/         ERP 공통 셸·로그인·관리자
├─ desktop/notifier/     PC 알림 트레이 프로그램(C#, Windows exe)
├─ docs/                 운영/설계 문서 (필요한 것만 읽기)
├─ scripts/              배포·유지보수 스크립트, sql/ 마이그레이션
├─ skills/               Claude Code 규칙/스킬
├─ docker-compose.yml    운영 컴포즈
├─ docker-compose.local.yml  로컬 컴포즈
├─ Dockerfile
├─ requirements.txt
└─ CLAUDE.md             ← 이 문서