Files
dbx-main/CLAUDE.md
T
king cf0e3f2139 feat(라이브): 달력 보기 오른쪽에 공용 달력과 말레이시아 공휴일
표 오른쪽에 erp-datepop 붙박이 달력을 두고, 날짜를 누르면 그 날이 표 맨 왼쪽에 오게 한다.
다른 달을 누르면 그 달 화면으로 이동해 같은 위치로 맞춘다. 마지막 날도 맨 왼쪽에 오도록 표 끝에 여백을 둔다.
말레이시아 공휴일·대체휴일 표(holidays.py, 쿠알라룸푸르 기준 2026·2027)를 표시한다.
공용 달력에 선택 옵션 locale 을 추가해 영문 화면도 영어로 그린다. 기존 화면 동작은 그대로.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 18:50:29 +09:00

152 lines
9.2 KiB
Markdown

# 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 ← 이 문서
```