king
550867ba0c
[admin]
- POST /api/users 사용자 직접 등록 (이메일만으로). UserStore.create_user 추가
- admin.html: 등록 폼 + 삭제 버튼 + 한글 라벨 + 신규 권한 표시
- 신규 권한 키: expense_approver, vacation_approver (APPROVER_KEYS)
- is_approver(user_rec, kind) 헬퍼
[expense 워크플로]
- 상태 전이: 작성중 → 제출 → 승인/반려 → 정산완료
- API: /api/items/{id}/{submit,revert,approve,reject,settle}
- 권한: submit/revert=owner, approve/reject/settle=expense_approver 또는 admin
- expense_items 컬럼: approver_email, decided_at, reject_reason
- 작성중/반려 상태에서만 수정/삭제/첨부 가능
[expense 첨부]
- 영수증/기타 (kind: receipt|other). 최대 20MB, 확장자 화이트리스트
- 저장: DATA_DIR/uploads/expense/{item_id}/{att_id}_{filename}
- expense_attachments 테이블 (CASCADE on item delete)
- API: 업로드/목록/다운로드/삭제
[expense 집계]
- /expense/reports: 연도별 월×카테고리 피벗 표
[expense 엑셀]
- GET /expense/api/export.xlsx?from&to&scope=mine|all
- scope=all 은 승인자/관리자만
[DDL]
- expense_db_init.sql: 신규 컬럼/테이블 포함 (멱등)
- expense_db_002_workflow_attachments.sql: 운영 DB 마이그레이션용
[deps]
- openpyxl>=3.1, python-multipart>=0.0.20
[docs]
- DATABASES.md: 워크플로 다이어그램, attachments 테이블, 마이그레이션
- PROJECT_OVERVIEW.md: 권한 키 표
- DEPLOYMENT.md: DATA_DIR/uploads 안내
129 lines
4.2 KiB
Markdown
129 lines
4.2 KiB
Markdown
# Project Overview
|
|
|
|
## 한 줄 정의
|
|
|
|
`main-app`은 DBX ERP 시스템의 **메인 프로젝트(허브)** 이다.
|
|
주문 수집부터 상품코드 매칭, 재고, CS, 반품, 외부 쇼핑몰 API 연동까지 ERP 운영 전체를 담당한다.
|
|
|
|
---
|
|
|
|
## 기능 범위
|
|
|
|
| 모듈 | 설명 |
|
|
| --- | --- |
|
|
| 주문관리 | 다채널 주문 수집·통합, 상태 추적, 분석 |
|
|
| 상품코드 매칭 | 채널별 상품코드 ↔ 사내 표준 상품코드 매핑, 단품/세트 구성 |
|
|
| 재고관리 | 입고/출고/재고 조정, 채널별 재고 동기화 |
|
|
| CS관리 | 문의/응대 이력, 발주 업무 트리거 |
|
|
| 반품관리 | 반품/교환 접수, 처리, 환불 연계 |
|
|
| 외부 연동 | 쇼핑몰·통합관리·택배사·문자 API 연동 |
|
|
| 개인경비 | 법인카드/개인지출 등록·증빙·정산 신청 (`app/modules/expense/`) — 결재 워크플로 / 첨부(영수증·기타) / 월별 집계 / 엑셀 내보내기 |
|
|
| 휴가 (준비중) | 연차/반차/특별휴가 신청·잔여일수 관리 |
|
|
|
|
### 권한 키 (`MODULE_KEYS`)
|
|
|
|
| 키 | 종류 | 설명 |
|
|
| --- | --- | --- |
|
|
| `corm` / `order` | 접근 | 외부 모듈 진입 |
|
|
| `expense` / `vacation` | 접근 | 내부 모듈 진입 |
|
|
| `expense_approver` | 결재 | 개인경비 승인/반려/정산 |
|
|
| `vacation_approver` | 결재 | 휴가 승인/반려 (모듈 미개발) |
|
|
|
|
`admin` 역할은 모든 권한 자동 부여. 신규 사용자는 관리자 페이지(`/admin`)에서 이메일만으로 등록 가능.
|
|
|
|
---
|
|
|
|
## 모듈 디렉토리 규약
|
|
|
|
신규 업무 모듈은 **별도 디렉토리 한 곳**에 라우터·저장소·템플릿을 모은다.
|
|
|
|
```
|
|
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` 의:
|
|
|
|
1. `_MODULE_TEMPLATE_DIRS` 에 템플릿 경로 추가
|
|
2. `app.include_router(<name>_router)` 추가
|
|
3. `app.state.<name>_store = ...` 등 상태 등록
|
|
4. `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 폴백) |
|
|
|
|
### DB 후보
|
|
|
|
| 모듈 | 현재 저장소 | 비고 |
|
|
| --- | --- | --- |
|
|
| 휴가 | (미개발) | `vacation_db` (승인 후 생성) |
|
|
|
|
> 신규 DB가 필요하면 **승인 요청 후** 생성하며, 이름은 `_db`로 끝낸다. 상세는 `DATABASES.md`.
|
|
|
|
---
|
|
|
|
## 접속/도메인
|
|
|
|
| 환경 | 주소 |
|
|
| --- | --- |
|
|
| 운영 | `https://dbx.no1king.freeddns.org` |
|
|
| 로컬 | `http://localhost:8080` |
|
|
| Git 저장소 | `https://gitea.no1king.freeddns.org/king/dbx-main.git` |
|
|
|
|
---
|
|
|
|
## 허용 사용자 (서버 측 화이트리스트)
|
|
|
|
`app/main.py`의 `ALLOWED_EMAILS`에서 검사한다.
|
|
|
|
- king@dbxcorp.co.kr
|
|
- julie@dbxcorp.co.kr
|
|
- ellen@dbxcorp.co.kr
|
|
- bj@dbxcorp.co.kr
|
|
|
|
Google `hd=dbxcorp.co.kr` 힌트는 클라이언트 편의용이며, **실제 권한 검사는 항상 서버 측**에서 수행한다.
|
|
|
|
---
|
|
|
|
## 작업 우선순위 / 원칙
|
|
|
|
1. 운영 데이터 안전이 최우선. 위험 명령은 사용자 승인 후 실행.
|
|
2. 신규 기능보다 기존 데이터 일관성 유지 우선.
|
|
3. 외부 API 연동은 실패 재시도와 로깅을 기본으로 한다.
|
|
4. 비밀값은 `.env`로만 관리하고 Git에 절대 올리지 않는다.
|