king
8ed1263bef
- project 를 MODULE_KEYS 에 추가 → 관리자 페이지에 '프로젝트 관리' 토글
자동 생성. 직원별 접근 권한 부여(admin 자동, 일반은 기본 OFF).
- 모듈 진입을 has_module('project') 로 게이트(기존 전원허용 철회).
- 멤버 배정 모달: GET /project/api/assignable-users 로 project 권한 보유
등록 사용자를 드롭다운 자동 목록화(타이핑 제거). 이미 배정된 사람 제외.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
110 lines
6.6 KiB
Markdown
110 lines
6.6 KiB
Markdown
# 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` 읽기 전용
|
|
- 휴가 관리 (`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`
|
|
- 프로젝트 관리 (`app/modules/project/`, `project_db`) — 아사나식. 프로젝트/서브프로젝트(self-FK `parent_id`, CASCADE)·업무(`tasks`: 담당자·우선순위·시작/마감)·진행단계(`project_stages` 칸반, 생성시 기본 4단계 seed)·멤버 배정(`project_members`)·활동이력(`project_activity`). 메인 뷰 달력(FullCalendar)/타임라인(vis-timeline) 버튼 토글 + 보드(드래그로 단계 이동)/리스트. 진입 권한키 `project`(관리자 페이지 토글로 직원별 부여, admin 자동). 프로젝트 생성/삭제·사용자 배정은 `is_admin` 만, 배정 멤버(또는 owner)는 서브프로젝트/업무/단계 CRUD. 멤버 배정 후보는 `project` 권한 보유 등록 사용자에서 자동 목록(`GET /project/api/assignable-users`). 업무 배정·완료 시 관리자에게 메일(`app/mail.py` stdlib smtplib, `SMTP_*`+`PROJECT_NOTIFY_EMAIL` env, 미설정 시 조용히 skip, `BackgroundTasks` 비동기). 상세는 `docs/PROJECT_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 ← 이 문서
|
|
```
|