09f6a2ee6f
- /vacation/options(달력 [옵션], 수정 = ERP 관리자): 휴가 승인자(여러 명)·휴가 승인 통보자 — vacation_options(마이그레이션 001) - 승인·반려 = 관리자 + 옵션 승인자(지정 시 그 사람만), 비우면 예전처럼 vacation_approver 권한자 - 메일(notify.py, 응답 뒤 백그라운드): 제출 = 승인자+통보자, 승인·반려 = 승인자+통보자+신청자 보내는 사람 = 그 일을 한 사람 본인 Gmail(입출고와 같은 연결·같은 구글 콜백, _gmail_callback_vacation), 없거나 실패하면 회사 SMTP(이름·Reply-To = 그 사람, app/mail.py reply_to 추가) - vacation_mail_log → 상세 화면 "메일" 줄, 휴가 화면 셸 오른쪽 넘침(border-box) 수정 - 테스트: test_vacation_options_mail.py(규칙·내용·Gmail→SMTP·실제 앱 권한·콜백), test_vacation_db.py(실제 PG) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
8.4 KiB
8.4 KiB
main-app ERP 프로젝트 작업 기준
이 문서는 Claude Code가 이 저장소에서 작업할 때 매 대화 자동으로 읽는 기준 문서다. 토큰 절약을 위해 짧게 유지한다. 모듈별 상세 규칙은 각 모듈 폴더의
CLAUDE.md와docs/*_MODULE.md에 둔다. 이 파일에 모듈 상세 설명을 다시 쌓지 말 것 — 새 기능 설명은 그 모듈의CLAUDE.md(요약)·docs/*_MODULE.md(상세)에 쓴다.
작업 시작 규칙 — 필요한 것만 읽는다
사용자는 요청 앞에 [모듈명] 을 붙인다(예: [휴가] 반차 버튼 색 변경).
[모듈명]으로 아래 표에서 모듈을 찾는다.- 그 모듈의
app/modules/<폴더>/CLAUDE.md를 먼저 읽는다(요약·핵심 규칙). - 코드는 그 모듈 폴더 + 표의 정적 파일만 본다. 다른 모듈 폴더는 연결이 확인될 때만 연다.
- 상세 문서(
docs/*_MODULE.md)는 요약으로 부족할 때만 — 큰 문서는grep -n '^#' <문서>로 목차를 보고 필요한 절만 offset/limit 으로 읽는다. - 큰 코드 파일도 통째로 읽지 말고 Grep 으로 위치를 찾은 뒤 그 부분만 읽는다.
[모듈명]이 없거나 표에 없으면 어느 모듈인지 짧게 묻는다(뻔하면 추정하고 진행).
공통 문서는 작업 종류에 해당할 때만 읽는다(예전 "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 토큰).- 입출고 Gmail 연결(
inout_gmail_tokens·/inout/gmail/callback): 입출고 발주 메일 + 휴가 메일(vacation/notify.py, 처리한 사람 본인 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 덤프 덮어쓰기, 마이그레이션 롤백 |
원칙:
- 실행 전 현재 상태 확인 명령을 먼저 보여준다 (예:
docker ps,\l,git status). - 백업 존재 여부와 위치를 명시한다.
- 실행 후 결과 확인 절차를 같이 제시한다.
서버 작업 원칙
- 배포, 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.
- 개발 PC:
환경 변수 / 비밀값
.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 ← 이 문서