- app.store: role "pro" (ROLES, ROLE_LABELS); admin page grade select Admin / Pro user / User, super admin fixed to one account. - project.access: role_of, is_pro, is_project_admin. - router: _require_admin -> _require_pro (goals, meetings complete/delete, members, reorder, trash restore, assignable users); new project and project edit/owner change need Pro user+; task delete open to any member; project/section delete = Admin+ or creator; comment edit/delete of others and workload summary = Pro user+. Templates get pj_pro / pj_admin. - Weekly meeting table first header "구역" -> "구분". - Docs (CLAUDE.md, PROJECT_MODULE 6-14, overview, help page) and tests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.7 KiB
Project Overview
한 줄 정의
main-app은 DBX ERP 시스템의 메인 프로젝트(허브) 이다.
주문 수집부터 상품코드 매칭, 재고, CS, 반품, 외부 쇼핑몰 API 연동까지 ERP 운영 전체를 담당한다.
기능 범위
| 모듈 | 설명 |
|---|---|
| 주문관리 | 다채널 주문 수집·통합, 상태 추적, 분석 |
| 상품코드 매칭 | 채널별 상품코드 ↔ 사내 표준 상품코드 매핑, 단품/세트 구성 |
| 재고관리 | 입고/출고/재고 조정, 채널별 재고 동기화 |
| CS관리 | 문의/응대 이력, 발주 업무 트리거 |
| 반품관리 | 반품/교환 접수, 처리, 환불 연계 |
| 외부 연동 | 쇼핑몰·통합관리·택배사·문자 API 연동 |
| 개인경비 | 법인카드/개인지출 등록·증빙·정산 신청 (app/modules/expense/) — 결재 워크플로 / 첨부(영수증·기타) / 월별 집계 / 엑셀 내보내기 |
| 쿠팡 밀크런 | 쿠팡 출고 일정 관리 (app/modules/cupang/) — 월간 달력 / 출고 묶음(헤더+라인) / 상자 입수량 자동계산 / 로켓 매출 관리 / 엑셀 내보내기. 상품은 itemcode_db 읽기 전용 참조 |
| 휴가 (준비중) | 연차/반차/특별휴가 신청·잔여일수 관리 |
| 말레이시아 재고 | 말레이시아 창고 재고관리 (app/modules/malaysia/) — 낱개 입출고/조정, 세트 BOM, 일일 재고조사(세트 분해 자동 반영), 현재고 현황. 상품명은 itemcode_db 읽기 전용 참조 |
| 실적 | 쇼핑몰 통합 매출 (app/modules/performance/) — 쇼핑몰별 어댑터로 수집 → performance_db 저장 → 일자×쇼핑몰 표·KPI·월/연 누적·그래프. 수수료율 이력, API 인증정보는 설정 화면 입력 + AES-256-GCM 암호화 저장. 1단계는 모의 데이터·구조까지(실제 API 는 쇼핑몰별로 순차 연동). docs/PERFORMANCE_MODULE.md |
권한 키 (MODULE_KEYS)
자산관리: app/modules/asset/, /asset/, asset_db — 사무집기·전산장비 개별 등록,
배정/반납/상태·구매/보증·활동 이력, HWiNFO XML 사양/보고서 보존. 상세 docs/ASSET_MODULE.md.
사진 갤러리, 보고서 모니터 자산 개요·등록·연결, 수퍼 관리자 삭제(이력/원본 보존)를 제공한다.
| 키 | 종류 | 설명 |
|---|---|---|
corm / order |
접근 | 외부 모듈 진입 |
expense / vacation / cupang / malaysia / performance |
접근 | 내부 모듈 진입 (performance 설정 화면·API 는 추가로 admin 필요) |
expense_approver |
결재 | 개인경비 승인/반려/정산 |
asset |
접근 | 자산관리 조회·등록·수정·배정·반납·보고서 |
vacation_approver |
결재 | 휴가 승인/반려 (모듈 미개발) |
admin 역할은 모든 권한 자동 부여. 신규 사용자는 관리자 페이지(/admin)에서 이메일만으로 등록 가능.
관리자 등급(2026-10-12): 수퍼관리자(SUPER_ADMIN_EMAIL 한 명 고정 — 변경·삭제·추가 불가) > Admin(role=admin) >
Pro user(role=pro) > User(role=user). Pro user 는 Project 모듈(프로젝트·목표·주간 회의록)에서만 권한이 늘고
(app/modules/project/access.py, 표는 docs/PROJECT_MODULE.md 6-14), 다른 모듈·관리자 페이지에서는 User 와 같다.
모듈 디렉토리 규약
신규 업무 모듈은 별도 디렉토리 한 곳에 라우터·저장소·템플릿을 모은다.
app/modules/<name>/
├─ __init__.py # router export
├─ router.py # FastAPI APIRouter (prefix=/<name>)
├─ store.py # 데이터 저장소 (JSON → 향후 <name>_db)
└─ templates/<name>/ # Jinja 템플릿 (ChoiceLoader 로 검색)
신규 모듈 등록 시 app/main.py 의:
_MODULE_TEMPLATE_DIRS에 템플릿 경로 추가app.include_router(<name>_router)추가app.state.<name>_store = ...등 상태 등록MODULE_KEYS(app/store.py) 와_menu_items_for()메뉴 항목 동기화
외부 연동 대상
- 쇼핑몰: 카페24, 네이버 스마트스토어
- 통합 관리: 사방넷
- 물류: CJ대한통운(CJ Logistics) 외 택배사 API
- 알림: 문자 발송 API
- 인증: Google OAuth (Google Workspace 계정 기반)
기술 스택
| 영역 | 사용 기술 |
|---|---|
| Backend | Python, FastAPI |
| DB | PostgreSQL (Docker 컨테이너) |
| 컨테이너 | Docker, Docker Compose |
| Reverse Proxy | Nginx Proxy Manager (NPM) |
| OS | Ubuntu Server (Proxmox VM) |
| 인증 | Google OAuth + 화이트리스트 |
| 저장소 | Gitea (self-hosted) |
관련 DB
| DB명 | 용도 |
|---|---|
itemcode_db |
상품코드, 단품/세트 구성, 매칭 정보 |
orderlist_db |
주문 수집·분석·관리 (구 orderlist_app) |
return_db |
반품·교환·CS 데이터 |
expense_db |
개인경비 / 법인카드 / 정산 (EXPENSE_DB_URL 미설정 시 JSON 폴백) |
cupang_db |
쿠팡 밀크런 출고/입고센터/박스규칙 (CUPANG_DB_URL 필수, JSON 폴백 없음) |
vacation_db |
휴가 신청/공휴일/연차잔여 (VACATION_DB_URL 필수, JSON 폴백 없음) |
malaysia_stock_db |
말레이시아 창고 재고/세트BOM/재고조사 (MALAYSIA_STOCK_DB_URL 필수, JSON 폴백 없음) |
performance_db |
실적 — 쇼핑몰 설정/수수료 이력/인증정보(암호문)/매출 사건 (PERFORMANCE_DB_URL 필수, JSON 폴백 없음) |
신규 DB 생성은 서버 실행 명령을 제공하고 사용자가 직접 진행한다 (사용자 지시: 2026-10-06). 대상·상태·백업 확인 명령을 제공하고 이름은
_db로 끝낸다. 기존 DB 삭제·덮어쓰기는 별도 승인 대상이다. 상세는DATABASES.md.
자산관리는 전용 asset_db를 사용한다. ASSET_DB_URL 미설정 시 저장 비활성, XML 분석 미리보기 가능.
접속/도메인
| 환경 | 주소 |
|---|---|
| 운영 | https://dbx.no1king.freeddns.org |
| 로컬 | http://localhost:8080 |
| Git 저장소 | https://gitea.no1king.freeddns.org/king/dbx-main.git |
허용 사용자 (서버 측 화이트리스트)
app/main.py의 ALLOWED_EMAILS에서 검사한다.
Google hd=dbxcorp.co.kr 힌트는 클라이언트 편의용이며, 실제 권한 검사는 항상 서버 측에서 수행한다.
작업 우선순위 / 원칙
- 운영 데이터 안전이 최우선. 위험 명령은 사용자 승인 후 실행.
- 신규 기능보다 기존 데이터 일관성 유지 우선.
- 외부 API 연동은 실패 재시도와 로깅을 기본으로 한다.
- 비밀값은
.env로만 관리하고 Git에 절대 올리지 않는다.