ecommerce-workspace

이 저장소는 단순한 데이터 대시보드가 아니라 실제 운영을 위한 전자상거래 업무 플랫폼이다. 시스템은 내수, 무역, 공급망, 재고, 물류, 재무 및 월결산을 동시에 담당하며, 통합된 업무 데이터와 재무 항목 기반으로 각 모듈을 연결한다. 주요 업무 진입점은 세 부분으로 나뉜다. 내수 워크벤치(경영 개요, 판매 센터, 기초 상품, 재고 센터, 공급망 센터, 택배 물류, 재무 센터), 무역 워크벤치(무역 개요, 무역 주문, B2B 고객 및 유통업체, 채널 관리, 해외 SKU 매핑, 국제 출하 Shipment, 무역 재무, Alsvid 업무), 그리고 독립된 재무 센터이다. 재무 센터는 회사 주체를 첫 번째 차원, 업무 범위를 두 번째 차원으로 하며, 기본 주체는 저장성 회사이고 오스트리아, 독일, 홍콩 등 주체 확장을 미리 대비하여 재무 시스템을 다시 만들 필요가 없다. 핵심 모델은 FinanceEntry로, 회사 주체, 업무 범위, 출처 모듈과 전표 번호, 재무 분류, 수입·지출, 통화, 금액과 세액, 예상과 실제, 결제 상태, 인보이스 상태, 회계 기간, 그리고 현금과 이익에 영향을 미치는지 여부 등의 차원을 포함한다. 현금과 이익은 분리 처리한다. 예를 들어 공제 가능한 수입 VAT는 현금에 영향을 주지만 이익에 직접 영향을 주지 않으며, Shipment 상품 원가는 이익에 영향을 주지만 매입 지급 현금을 중복 계산하지 않는다. 업무 흐름 측면에서 내수는 판매 주문, 판매 후 환불, 판매 원가, 매입 입고 미지급, 택배 물류 예상과 실제 청구서 정산을 통합하여 FinanceEntry로 집계한다. 무역은 무역 주문, Shipment 출하 전표, 중국 수출, 국제 운송, EU 수입 통관, 해외 최종 배송, 재무 항목과 월결산 순서로 흐른다. Shipment는 수출 및 수입 회사 주체, 수입 책임 주체, 선하증권 컨테이너 번호 Tracking, 수출 및 수입 통관, 일반 관세, 반덤핑세, 상계관세, 수입 VAT, 통관 항만 부대비용과 최종 배송, 수출 환급 및 예상과 실제 원가를 기록할 수 있다. 수입 세금은 당사 주체가 수입 책임을 부담할 때만 해당 주체 재무에 반영된다. 월결산 센터는 회사 주체별로 전환하며 업무 데이터베이스를 직접 읽어, 업무 데이터 완전성 검사, 판매 금액과 원가 검사, 은행 거래 명세와 영수증, 무표 매출, 무역 재무 요약, 월간 ZIP 패키징, 재무 이메일 발송 및 이전 버전 아카이빙을 제공한다. 판매 SKU에 매입 입고 원가가 없으면 시스템은 누락된 SKU를 명확히 알려주며, 허구의 원가로 잘못된 이익을 생성하지 않는다. 외부 데이터 소스는 현재 지커윈, 1688, 저장농신 파일 가져오기, 세무 인보이스 목록, SMTP 재무 이메일을 지원하거나 예비하며, 무역 채널과 Shopify는 추후 연동한다. 설정되지 않은 외부 시스템은 설정되지 않음으로 사실대로 표시하며, 모의 데이터로 실제 연결을 위장하지 않는다. 기술 스택은 백엔드가 Python 3.12, FastAPI, SQLAlchemy 2, Alembic, Pydantic, PostgreSQL, Celery와 Redis이고, 프론트엔드는 Next.js 16, React 19, Tailwind CSS 4이며 정적 내보내기 후 FastAPI가 동일 포트에서 호스팅한다. 기본 서비스 포트는 127.0.0.1:8000이고 PostgreSQL과 Redis는 공용 인터넷에 개방하지 않는다. 현재 주요 개발 및 검수 환경은 Mac 로컬 네이티브 실행이며, NAS와 지공간 배포는 보류하고 컨테이너화와 릴리스 설정은 유지한다. 개발 프로세스는 직접 푸시 모드를 사용하여 일상 변경을 develop에 직접 커밋·푸시하고, CI는 push로 트리거되며 main은 정식 릴리스 메인라인이다. 저장소는 상태 확인, 재시작, 프론트엔드 재빌드, Alembic 마이그레이션, 백엔드 테스트, 프론트엔드 타입 검사, 로컬 전체 검수와 백업을 위한 make 명령을 제공한다. 영속성 원칙은 코드, 데이터베이스, 업무 파일, 백업과 로그를 분리하는 것을 강조하며, PERSIST_ROOT, DATA_DIR, BACKUP_DIR, LOG_DIR 설정을 통해 Git 업데이트나 브랜치 전환이 업무 데이터를 덮어쓰지 않도록 한다. 보안 원칙은 .env를 Git에 커밋하지 않기, 데이터베이스와 캐시를 공용 인터넷에 개방하지 않기, 개발 단계에서 8000 포트를 공용 인터넷에 노출하지 않기, 1688은 이미 발생한 매입만 동기화하고 자동 주문·결제는 하지 않기, 원본 재무 자료의 버전 보존, 데이터베이스 구조 변경은 반드시 Alembic을 거치기, 그리고 큰 구조 조정 전에 먼저 백업하기를 포함한다. 시스템 업데이트는 네이티브 모드와 컨테이너 릴리스 신원 식별을 지원하며, Git 브랜치와 원격, 작업 영역 상태, Python과 Node 환경, Alembic, 백업 능력, 프론트엔드 산출물, 헬스 체크와 디스크 공간을 점검한다.