# 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.*` | | `[안내문 발송]` | `outreach/` | `outreach_db` | `outreach` | (모듈 CLAUDE.md) | `outreach.*` | | `[라이브커머스]` `[라이브]` | `live/` | `live_db` | `live`, `live_host` | (모듈 CLAUDE.md) | `live.*` | | `[공통]` `[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 토큰). - 입출고 Gmail 연결(`inout_gmail_tokens`·`/inout/gmail/callback`, `_GMAIL_ORIGINS`): 입출고 발주 메일 + 휴가 메일(`vacation/notify.py`) + 안내문 발송(`outreach/send.py`) — 모두 보내는 사람 본인 Gmail. - `app/integrations/google_sheets.py`(쿠팡) · `google_slides.py`(프로젝트 회의록 보드). - `asset/media.py prepare_photo`(이미지 확인·메타데이터 제거): 자산 + 라이브 커머스. - `app/mail.py`: 프로젝트 알림 메일. - ERP 모든 화면 스크립트: `erp-notice.js`(공지) · `erp-overdue.js`(프로젝트 마감 알림). - 아사나식 날짜 팝업: 프로젝트(`project.js` 안) + 공용 복사본 `erp-datepop.js/css`(휴가 신청·입출고 날짜 칸·라이브 오른쪽 달력) — 바꾸면 둘 다. - 국경일·대체공휴일 표 `project/store.py KR_HOLIDAYS`: 프로젝트 캘린더·날짜 팝업 + 휴가(달력·일수 계산 `vacation/db.holiday_map`) + 입출고(오른쪽 달력·날짜 칸). --- ## 프로젝트 한 줄 정의 `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 ← 이 문서 ```