- 세부 업무를 만들 때 협업자도 같이(업무 창 추가 칸·보드 카드 새 줄) — POST tasks 의 followers, 비멤버면 400 - 보드 카드 세부 업무 줄에도 협업자 아이콘, 업무 창 줄의 빈 협업자 아이콘은 늘 보이게 - 협업자 메뉴는 고를 때마다 다시 열려 여러 명을 이어서 지정(openFollowerMenu 공용) - 대시보드 "업무 합계(프로젝트별)" 카드 — 완료 상태별 카드 왼쪽, 프로젝트별 완료/전체·완료율 - 마감 지난 내 업무 위쪽 알림(ERP 모든 화면, erp-overdue.js, GET /project/api/my-overdue) — 닫으면 1시간 뒤 다시, 새로 지난 업무는 바로 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
26 KiB
main-app ERP 프로젝트 작업 기준
이 문서는 Claude Code가 이 저장소에서 작업할 때 가장 먼저 확인하는 기준 문서입니다. 작업 시작 전, 아래 "반드시 먼저 읽을 문서"를 모두 확인한 뒤 작업을 시작합니다.
반드시 먼저 읽을 문서
Claude Code는 이 저장소에서 작업을 시작하기 전에 반드시 아래 문서를 순서대로 읽고 맥락을 확보한 뒤 작업한다.
docs/PROJECT_OVERVIEW.md— 프로젝트 정의, 기능 범위, 연동 대상docs/SERVER_ARCHITECTURE.md— 서버 구성도와 네트워크 흐름docs/DATABASES.md— PostgreSQL DB 구성과 명명 규칙docs/DEPLOYMENT.md— 배포 경로, 서비스 실행 방식, 복구 절차
문서 간 내용이 충돌하면 위의 우선순위(1 → 4)를 따른다.
프로젝트 한 줄 정의
main-app은 DBX ERP 시스템의 메인 프로젝트(허브) 이다.
담당 영역:
-
주문관리
-
상품코드 매칭
-
재고관리
-
CS관리
-
반품관리
-
외부 쇼핑몰 API 연동 (카페24, 네이버 스마트스토어, 사방넷 등)
-
개인경비 (
app/modules/expense/,expense_db) -
쿠팡 밀크런 (
app/modules/cupang/,cupang_db) — 출고 달력/상자 계산, 상품은itemcode_db읽기 전용. 설정(제품명)에서 제품별 포장무게(g,cupang_products.weight_g, 마이그레이션 007 + 시드) 입력·표시·정렬. 출고 상세 상자 목록에 상자별 무게 합계(수량 × 지금 포장무게,router._attach_box_weights, 무게 없는 제품은 "일부 미입력", 화면은 kg 소수 첫째 자리 사사오입router._g_to_kg+ 맨 아래 수량·무게 합계 행(앞 3열 병합), 표 칸 모두 가운데 정렬, 요약 카드와 20px 간격) — 상자 목록 엑셀에도 무게(g) 열. 출고 묶음은 상자 계산 화면의 [분배 확정] 으로만 만든다(신규 등록 폼 없음,/cupang/new는 상자 계산으로 리다이렉트). 확정 조건: 미배분 상자 0 + 담긴 센터마다 출고방식(택배/파렛트) 선택. 확정 시 센터마다 출고 묶음 1건(status=출고준비, 센터입고일=출고일+1일, 상자 구성은cupang_shipments.box_planJSONB 에 스냅샷 — 혼합 상자 내용물·상자 종류 표시용) + 출고리스트 엑셀 자동 다운로드(GET /cupang/export.xlsx?date=, 시트명 YYYYMMDD). 양식 생성은app/modules/cupang/export.py한 곳에서 만들어 xlsx·구글시트가 공유.CUPANG_SHEET_ID+ 인증(사용자 OAuthGOOGLE_SHEETS_OAUTH_REFRESH_TOKEN또는 서비스 계정GOOGLE_SHEETS_CREDENTIALS[_JSON]) 설정 시 확정과 동시에 Google 스프레드시트에 출고일 시트를 생성/덮어쓰기(app/integrations/google_sheets.py, 미설정이면 조용히 skip). 출고 삭제(건별/날짜 전체) 시에도 같은 날짜 시트를 동기화 — 남은 출고가 있으면 다시 쓰고, 없으면 시트 삭제(문서에 시트가 하나뿐이면 내용만 비움). 작업 중 상태는cupang_box_calc_drafts에 이름 붙여 임시 저장/불러오기. 쿠팡 로켓 매출(/cupang/sales,cupang_sales·cupang_sales_weekly) — 발주 라인별 공급가·원가·물류비·마진 표. 기간/센터/유형/검색 조회, 행 CRUD, 구글 시트 양식 xlsx·csv 업로드(같은 발주번호+SKU+출고일+센터+수량은 덮어씀), 엑셀 다운로드. 광고비·할인 프로모션·장려금은 주차 단위(cupang_sales_weekly)로 보관하고 순마진은 화면에서 계산. 초기 데이터는scripts/sql/cupang_sales_seed.sql. 쿠팡 발주 엑셀(xlsx) 다중 업로드 지원(POST /cupang/api/box-calc/upload, openpyxl) — F13 입고예정일의 하루 전 = 출고일, 22행부터 B=쿠팡상품코드·F=센터명·G=수량을 읽어cupang_products.coupang_item_code로 제품 매칭 후 센터별 합산 → 센터 단위로 상자 계산·자동 배분 -
휴가 관리 (
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 -
카페24 상품관리 (
app/modules/cafe24/,cafe24_db) — 카페24 관리자에 들어가지 않고 상품 상세페이지(description HTML) 조회·편집·즉시적용·예약적용·버전 이력. 3분할 화면(목록 | HTML 편집기 | 상품 정보 패널). 정보 패널(routes_product_info.py,_side.html)에서 상품명·판매가·공급가·소비자가, 대표이미지(POST /admin/products/{no}/images에 base64 data URI +image_upload_type=A— NNEditor 업로드 경로를 PUTdetail_image에 넣는 방식은 적용 안 됨), 옵션(생성/이름·썸네일·표시방식 수정/삭제)·품목(자체코드·추가금액·진열·판매)을 수정. 카페24 OAuth/API 클라이언트는 향후 주문관리와 공유하기 위해 공통 계층app/integrations/cafe24/에 둔다 — 라우터에서httpx/requests직접 호출 금지. 토큰은 Fernet 암호화 저장(CAFE24_TOKEN_SECRET), 로그/화면에 토큰·시크릿 절대 미출력. 쓰기 직전 항상 카페24 현재 HTML 을 다시 읽어BACKUPrevision 생성(로컬 값을 현재값으로 가정 금지). 카페24 관리자 API 는 PUT 뒤 한동안 GET 에서 예전 값을 돌려준다(읽기 지연) — 우리 캐시 문제가 아니다. 그래서 "마지막 쓰기가 권위": 상세설명은 카페24 값이 최근 revision 중 하나와 같으면 지연으로 보고 마지막 MANUAL/SCHEDULED 를 표시·지문 기준으로 쓰고(store.resolve_description), 스칼라(상품명·가격·이미지·진열/판매)는 PUT 응답 스냅샷(cafe24_products.last_write_snapshot, 마이그레이션 004)과 GET 의updated_date를 비교해 덮어씌운다(store.overlay_recent_write). 유예시간CAFE24_READ_LAG_GRACE_MIN(기본 360분). 쓰기 후 화면은 PUT 응답으로 그리고 다시 GET 하지 않는다. 예약은 DB 저장 + 별도 worker(app/modules/cafe24/worker.py, compose 서비스dbx-cafe24-worker)가 처리 — 웹 프로세스에서 대기하지 않는다. 권한키cafe24(연결/해제는 admin 전용). 상세는docs/CAFE24_MODULE.md -
프로젝트 관리 (
app/modules/project/,project_db) — 아사나식. 프로젝트/서브프로젝트(self-FKparent_id, CASCADE)·프로젝트 색상(32색 — 아사나 16색 + 진한 16색, 수정 창 12열)·아이콘(projects.icon, Material Symbols 42종, 마이그레이션 011 + [아사나 아이콘] 탭 33종"asana:"+이름, 채워진 모양 전용 부분 글꼴material-symbols-asana.woff2)·작업(tasks: 담당자·우선순위·시작/마감)·진행단계(project_stages칸반, 새 프로젝트는 섹션 없이 시작 —create_project(seed_stages=True)일 때만 기본 4단계, 섹션 머리는 모두#f3f3f3— 섹션별 색 지정 없음, 섹션 이름 굵게, 섹션 기본 담당자default_assignee_email— 담당자 빈 작업을 그 섹션에 만들거나 옮기면 자동 배정, 마이그레이션 009)·멤버 배정(project_members)·활동이력(project_activity). 첫 화면(/project/)은 내 작업 목록(프로젝트 홈 카드 화면은 폐지). 프로젝트 화면은 캘린더(FullCalendar)/타임라인(vis-timeline)/보드/목록/대시보드 뷰 토글. 좌측 사이드바는 수신함·내 작업·휴지통·프로젝트 화면 공용(templates/project/_side.html+ 프로젝트 목록 동작initSideTree, 새 프로젝트/수정 모달_side_modals.html) — 프로젝트 목록(순서 변경·✎·×)은 어느 화면에서나 같다. 보드는 아사나처럼 섹션이 가로로 계속 늘어나고(넘치면 가로 스크롤) 카드의 담당자·마감일을 클릭해 그 자리에서 바꾼다. 좌측 사이드바에 수신함·전체 보기(Pro user 이상 — 예전 오른쪽 위 "전체 프로젝트" 토글,?scope=all)·내 작업(접이식) 메뉴. 설명란 서식 도구에 글자 색·크기(서버는 span style 의 color·font-size 만 허용,desc_inline_style). 설명란은 주소 붙여넣기 시 자동 링크, 설명란·댓글에서 @로 멤버를 태그하면 (task_mentions, 마이그레이션 006) 수신함에 그 작업이 쌓인다. 진입 권한키project(관리자 페이지 토글로 직원별 부여, admin 자동). 관리자 등급 4단계(2026-10-12) — 수퍼관리자(SUPER_ADMIN_EMAIL한 명 고정, 추가 불가) > Admin(role=admin) > Pro user(role=pro) > User — 판단은access.is_pro(Pro user 이상)·access.is_project_admin(Admin 이상), 라우터_require_pro, 화면pj_pro·pj_admin(_role_ctx,is_admin은 ERP 상단 관리자 메뉴용 그대로). pro 는 프로젝트 모듈 밖에서는 user 와 같다. 새 프로젝트·프로젝트 이름/색/아이콘/소유자 수정·멤버 배정(자기가 멤버인 프로젝트)·사이드바 순서·남의 댓글 수정/삭제·휴지통·전체 보기·담당자별 합계·전체 멤버 = Pro user 이상, 프로젝트·섹션 삭제 = Admin 이상 또는 만든 사람, 작업 삭제·서브프로젝트 = 멤버 누구나(표는 docs/PROJECT_MODULE.md 6-14). 배정 멤버(또는 owner)만 그 프로젝트를 조회 — 관리자도 멤버가 아니면 안 보임, 예외는 슈퍼관리자뿐(2026-10-07,access.sees_all_projects; 사이드바 목록·검색·휴지통·알림도 같은 기준, 화면·API 모두 비멤버 403)하고 서브프로젝트/작업/단계 CRUD — URL 의 섹션·부모 작업이 그 프로젝트 것인지 서버가 검증. 실시간 반영은project_live_version카운터(마이그레이션 007, 미적용 시 MAX 폴백). 사이드바 전체 검색(/api/search, 제목·설명·댓글, pg_trgm) + 프로젝트/내 작업 필터 바(찾기·상태·담당자·마감·우선순위·정렬, 클라이언트 필터). 협업자(task_followers, 자동 팔로우: 만든 사람·담당자·댓글·@태그) — 완료·댓글 알림은 담당자+협업자에게만. 나를 태그하거나 작업이 배정되면 프로젝트 화면 가운데 아래에 깜박이는 큰 팝업(닫기 전까지,initTaskAlerts+GET /api/notifications/alerts). 작업 삭제는 휴지통(project_trash, 마이그레이션 010) — 삭제 직전 스냅샷 3개월 보관, Pro user 이상만 보기·복구(/project/trash). 권한은 지금 기준 공통 모듈access.py(목록·배지·알림·멘션·메일 수신자·삭제·댓글 수정까지 — 멤버에서 빠지면 기록이 있어도 안 보이고 알림도 없음), 소유자 변경은 Pro user 이상, 연결(멀티호밍)된 작업은 연결된 프로젝트 멤버에게 읽기 전용(docs/PROJECT_MODULE.md 6-10). 연간 목표(마이그레이션 013,goal_*테이블) — 사이드바 "목표" → 연도 펼침 →/project/goals/{연도}에 매출(목표·실적·달성)·로아스 월별 숫자 + 업무 영역(상품·마케팅·컨텐츠·유통 등)별 연간·월별 글, 조회는 전원·입력(주차별 목표·연도 추가/삭제 포함)은 Pro user 이상. 3·6·9·12월 오른쪽 14분기 칸(글 칸 13=1분기·15=2분기·14=3분기·16=4분기 — 예전 반기 칸 번호 재사용, 15·16 은 마이그레이션 017) + 분기 월 칸 접기 애니메이션(localStorage금이면 1일pj_goal_fold_q, 표는width:1px+table-layout:fixed), 영역·줄 이름 클릭 바로 수정, 엑셀식 칸 병합(마우스로 끌어 사각형 선택 → 우클릭 셀 병합/병합 해제, 같은 영역 안 세로row_span+ 같은 분기 월 칸 가로, 글은 왼쪽 위 칸 —goal_cell_merges, 마이그레이션 014·015·017), 3열 줄 추가는 같은 항목 칸(2열) 안에(goal_rows.label_cont, 마이그레이션 016), 구조 변경은 새로고침 없이 제자리 다시 그리기(refreshTable)+애니메이션, 로아스는 % 표기. 월 머리 → 주간 회의록(/project/goals/{연도}/meetings/{월}, 프로젝트 권한자 누구나 수정 — Pro user 이상 [회의 완료](completed_at, 마이그레이션 022)면 잠금(지난주 결과는 다음 주 회의록이 열려 있는 동안 허용), 삭제·완료·완료 해제는 Pro user 이상, 표 첫 열 머리 글자 "구분", 주차 탭 — 주차는 그 달 안(store.month_weeks: 1일이 월일요일이 1주차, 토·일이면 1일다음 주 일요일, 그 뒤 월일, 말일이 월·화면 앞 주차에 붙음, 회의록이 주차 합 — 목표 표 매출 목표 월 칸을 누르면 입력 창 — 월 전체 목표는 직접 입력(주차 합계와 별개), 맨 아래 차이 = 월 목표 − 주차 합계)·월 누적 실적(1일~오늘)·누적 목표 대비 차액·%) | ② 결정 사항·메모 | ③ "N주차 작업 등록" 표(제목·담당자·프로젝트·섹션 → [적용] = 서버가 그 프로젝트에 작업 생성,week_start= 주차 시작일, 마이그레이션 020),goal_meetings·goal_meeting_items마이그레이션 015 — 지난주 = 바로 앞 주차(store.prev_week_period) 회의록의 같은 연결키 줄(line_key, 마이그레이션 018 — 생성 순서·이름 변경과 무관, 이름 추정 연결 금지)로 리뷰(열: 주요 업무·정량 목표 ‖ 전주 업무·결과(글,result_note020)·전주 목표·결과 — 정량 목표·결과는 숫자면 원 정수 칸, 아니면 글 칸target_text·result_text(예: 20개, 021)), 실적 조회 장애는 0원이 아니라 "미확인", 위에 목표 표 그 달 열 글을 영역별 "N월 계획" 카드로, 참석자 옆 [회의록 보드] = 그 주차의 빈 Google 슬라이드를 독립 창으로(오른쪽 🔗 아이콘 = 그 보드 링크 복사)(공유 드라이브MEETING_BOARD_FOLDER_ID, 없으면 만듦,app/integrations/google_slides.py, Drive appProperties 로 주차 연결 — Drive·Slides 권한 토큰 필요), 표를 스크롤해도 보이는 머리 영역 3칸 = ① 월 계획 + 머리 줄에 숫자 4개 작게 1행(월 목표 매출·월 누적 목표 매출(목표 표 주차별 매출 목표goal_week_targets1주차initMeetQuickTasks— 주차별 서버 표goal_meeting_tasks(마이그레이션 025)라 모두가 같이 보고, 남의 프로젝트 이름은 가림, 완료 프로젝트·섹션은 목록에서 뺌, 작업 칸(마이그레이션 026parent_task_id) = 이미 있는 작업을 고르면 그 작업의 세부 작업으로 등록, 등록된 줄 제목 = 오른쪽 작업 창(편집, 저장 대기), [크게 열기] = 같은 표를 넓은 창으로), 실적 모듈performance_store매출은 머리 카드에만 읽기 전용 — 줄(쇼핑몰)별 자동 결과·이번주 실적·연결 배지·쇼핑몰 연결 메뉴는 폐지, 지난주 결과는 늘 직접 입력). 모든 열 너비 끌어서 조절(localStoragepj_goal_col_w), 세로 스크롤 틀 고정은 머리 줄+매출·로아스 줄까지, 항목 칸 +·우클릭으로 줄 위/아래 추가·삭제, 회의록 "주요 업무" 칸 우클릭 위/아래 줄 추가 = 항목 칸은 그대로 그 항목 안에(마이그레이션 027label_cont, 항목 칸 나누기), 회의록 줄 작업은 새로고침 없이 제자리 다시 그리기(refreshMeeting)+애니메이션, 구분(구역) 칸 우클릭·⋯ = 구역 통째로 위/아래(move-section). 마감 알림(reminders.py데몬 스레드, 영업일 09시, D-1/당일/지연,task_reminders로 중복 방지,PROJECT_REMINDER_*env) — 마이그레이션 008. 라우터 핸들러는 동기 DB 라def로 둔다(async def금지). 말풍선은 전부 아사나식 공용 말풍선(.pj-hovertip) — 새 기능도title=/data-tip=만 달고 별도 툴팁 구현 금지. 멤버 배정 후보는project권한 보유 등록 사용자에서 자동 목록(GET /project/api/assignable-users). 작업 배정·완료 시 관리자에게 메일(app/mail.pystdlib smtplib,SMTP_*+PROJECT_NOTIFY_EMAILenv, 미설정 시 조용히 skip,BackgroundTasks비동기). 목표 표·회의록 칸 저장은 공용createFieldSaver(같은 칸 요청 직렬화·보낸 값만 저장됨·실패 시 초안 유지·localStorage 초안 백업, 저장 실패면 구조 변경 중단 — docs/PROJECT_MODULE.md 6-9-3), 구역·항목 메뉴는 우클릭 + ⋮ 버튼(키보드·터치). ERP 메뉴 이름은 "Project"(app/main.py모듈 목록 title). PC 알림 프로그램(desktop/notifier/, C# .NET Framework 4.8 WinForms exe 하나·트레이 상주, 마이그레이션 023notifier_links·notifier_tokens) — 브라우저가 뒤에 있어도 태그·배정 알림을 웹 팝업과 같은 모양으로 화면 위에. 브라우저/project/notifier?code=승인으로 PC별 토큰(서버는 SHA-256 만, PC 는 DPAPI),GET /project/api/notifier/alerts(Bearer)는 웹 알림과 같은_alerts_payload, 토큰마다 지금 사용자·권한 재확인. 프로그램이 돌고 있으면(최근 3분 확인,notifier_active) 웹 큰 팝업은 쉰다(desktop: true). 압축·난독화 금지(백신 오탐), 빌드desktop/notifier/build.ps1, 상세 docs/PROJECT_MODULE.md 6-11. 댓글·답글 입력칸은 Enter 등록·Shift+Enter 줄바꿈(textarea), 설명란 이미지 더블클릭 = 별도 창 이미지 보기(확대·축소·끌어 이동). 작업 창은 저장 버튼 없이 실시간 저장(칸별 PUT,saveField/saveChain, 새 작업은 제목이 생기는 순간 생성). 댓글 답글·이모티콘 반응(마이그레이션 012task_comments.parent_id·task_comment_reactions, 미적용 시 버튼 숨김·API 503), 완료 이력 줄은project_activitycompleted 를 댓글 사이에 표시(댓글 수 제외), 댓글@아이디는 아이콘+이름 칩. 수신함은 확인 안 한 태그·읽지 않은 알림만(2026-10-08) — [확인] 버튼 없이 줄을 누르면 읽음·확인 처리(같은 작업 줄 함께) + 페이지 이동 없이 오른쪽 iframe 패널, 다른 줄을 고르거나 패널을 닫으면 그 줄은 목록에서 빠짐. 용어는 "업무"(2026-10-13 "작업"에서 다시 통일 — 화면·메시지·알림 제목, 코드·DB 는 그대로)·"세부 업무"·"메인 업무 추가". 섹션 제목 오른쪽 담당자 아이콘 = 그 자리에서 기본 담당자 지정, 업무 창 세부 업무 줄 담당자 오른쪽 = 협업자 지정, 댓글 이모티콘 반응 = 댓글 쓴 사람에게 알림(type=reaction), 왼쪽 전체 보기 = 기본 대시보드, 대시보드 업무 목록 패널에서 연 업무 창은 패널 왼쪽에(docs/PROJECT_MODULE.md 6-16). 세부 업무를 만들 때(업무 창 추가 칸·보드 카드 새 줄) 협업자도 같이(POST …/tasks의followers, 비멤버 400), 보드 카드 세부 업무 줄에도 협업자 아이콘, 대시보드 "업무 합계(프로젝트별)" 카드, 마감 지난 내 업무 위쪽 알림(static/erp-overdue.js, ERP 모든 화면,GET /project/api/my-overdue, 닫으면 1시간 뒤 다시 — 새로 지난 업무는 바로)(6-17). 패널(/project/p/{pid}?task=&embed=1,html.pj-embed). 상단 바 화면 배율 토글(html.pj-ui-scale→.erp-appzoom .75, 2880×1620·200%용) — 팝업은 반드시document.body에 붙인다(배율 안의 fixed 좌표는 어긋남). 상세는docs/PROJECT_MODULE.md -
실적 (
app/modules/performance/,performance_db) — 쇼핑몰 통합 매출. 네 영역 분리: ① 수집adapters/(쇼핑몰 하나 = 어댑터 파일 하나 +registry.py한 줄 + SQL seed 한 줄) +sync.py(공통 동기화, 같은 쇼핑몰 동시 실행 차단, 쇼핑몰별 실패 격리) ② 보안security/(AES-256-GCM, 키 버전, 비밀값 가리기) +credentials.py③ 계산calc.py(주=월일, 수수료 반올림은19시 정각·30분마다 오늘 포함 최근 10일, 진행 창 작업으로 돌고 다른 업데이트 중이면 그 회차 건너뜀, envcommission()한 곳, 요율 이력) +db.py④ 화면dashboard.py/router.py/템플릿. 쇼핑몰 API 인증정보는.env가 아니라 설정 화면에서 입력 → 마스터 키APP_ENCRYPTION_KEY로 암호화해 DB 저장, secret 원문은 화면으로 다시 보내지 않는다. 쇼핑몰 API 는 백엔드에서만 호출, 오류·로그·raw 는redact후 저장. 매출 기준일: 결제=결제일, 취소·반품=발생일(sync.sales_date_for). 금액은 원 단위 정수. 권한키performance, 설정 화면은 모듈 권한자 누구나(일반 사용자는 수수료율만), 수수료 외 설정 API 는is_admin. 매출 업데이트 진행 창에서 쇼핑몰별 [중지](그 쇼핑몰만 멈추고 다음 쇼핑몰로). 자동 업데이트(auto_sync.py, 웹 프로세스 데몬 스레드) — 매일 09PERFORMANCE_AUTO_SYNC·_DAYS·_HOURS. 카페24 어댑터는 기존app/integrations/cafe24토큰 재사용. 1단계는 모의 데이터(is_sample)·구조까지, 실제 수집은 쇼핑몰별로 공식 문서 확인 후 순차 구현. 쿠팡은 판매자배송 발주서 + 로켓그로스 주문을 결제일로 합산(WING 판매분석 대조는 원본 데이터 확인으로). 설정의 쇼핑몰별 수동 입력 토글(마이그레이션 002manual_input·perf_manual_sales) — 켜면 일자별 표 날짜 칸에 총매출 직접 입력, 넣은 날은 API 값 대신(daily_amounts한 곳). 일자별 표 [엑셀 업로드] 팝업(manual_upload.py,POST /performance/api/manual-sales/upload) — 1열 날짜·2열부터 쇼핑몰 이름 머리글, 수동 입력 켜진 쇼핑몰 열의 값 있는 칸만 반영(덮어씀, 빈 칸 그대로), 잘못된 칸이 하나라도 있으면 전부 저장 안 함, 샘플 = 모듈 폴더upload_sample.xlsx. 열 순서 카페24·네이버·쿠팡(윙)·쿠팡(로켓)·오늘의집·G마켓·카카오·GS샵·11번가·롯데ON·토스·애터미아자몰(마이그레이션 003). 쿠팡(로켓)·애터미아자몰은 수동 입력 전용(adapters/manual.py,manual_only— 매출 업데이트에서 빠지고 인증 설정·연결 테스트 없음, 수동 입력 늘 켜짐). 상세는docs/PERFORMANCE_MODULE.md -
긴급 공지 (
app/modules/notice/,project_db마이그레이션 024urgent_notice*) — 수퍼관리자만 작성(/notice/, ERP 왼쪽 아래·Project ⚙ 옵션). 제목·내용(이미지 bytea)·띄울 시각·전체/고른 사람 → ERP 모든 화면(erp_base.html·main.html·admin.html의static/erp-notice.js) 가로·세로 정가운데에 [확인] 누를 때까지(Esc·바깥 클릭 무시), 확인 기록. 연결 풀은ProjectStore.pool공유, 새 환경변수 없음. PC 알림 프로그램은 아직 미지원. 상세는docs/NOTICE_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 덤프 덮어쓰기, 마이그레이션 롤백 |
원칙:
- 실행 전 현재 상태 확인 명령을 먼저 보여준다 (예:
docker ps,\l,git status). - 백업 존재 여부와 위치를 명시한다.
- 실행 후 결과 확인 절차를 같이 제시한다.
서버 작업 원칙
- 배포, 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.
- 개발 PC:
환경 변수 / 비밀값
.env,.env.local,.env.production은 Git에 절대 커밋하지 않는다.- 예시 파일(
*.example)만 커밋한다. - 비밀값 유출이 의심되면 즉시 회전(rotate)을 권고한다.
- 신규 환경변수 추가 시
*.example파일과 본 문서(또는docs/DEPLOYMENT.md)에 변수 설명을 함께 갱신한다.
디렉터리 구조 (요약)
Main-app/
├─ app/ FastAPI 앱 소스
├─ desktop/notifier/ PC 알림 트레이 프로그램(C#, Windows exe)
├─ docs/ 운영/설계 문서 (작업 전 필독)
├─ scripts/ 배포·유지보수 스크립트
├─ skills/ Claude Code 규칙/스킬
├─ docker-compose.yml 운영 컴포즈
├─ docker-compose.local.yml 로컬 컴포즈
├─ Dockerfile
├─ requirements.txt
└─ CLAUDE.md ← 이 문서