diff --git a/CLAUDE.md b/CLAUDE.md index 6f31a89..5a352ee 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,7 +36,7 @@ Claude Code는 이 저장소에서 작업을 시작하기 전에 **반드시 아 - 말레이시아 창고 재고관리 (`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 업로드 경로를 PUT `detail_image` 에 넣는 방식은 적용 안 됨), 옵션(생성/이름·썸네일·표시방식 수정/삭제)·품목(자체코드·추가금액·진열·판매)을 수정. 카페24 OAuth/API 클라이언트는 향후 주문관리와 공유하기 위해 **공통 계층 `app/integrations/cafe24/`** 에 둔다 — 라우터에서 `httpx`/`requests` 직접 호출 금지. 토큰은 Fernet 암호화 저장(`CAFE24_TOKEN_SECRET`), 로그/화면에 토큰·시크릿 절대 미출력. 쓰기 직전 항상 카페24 현재 HTML 을 다시 읽어 `BACKUP` revision 생성(로컬 값을 현재값으로 가정 금지). **카페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-FK `parent_id`, CASCADE)·프로젝트 색상(32색 — 아사나 16색 + 진한 16색)·아이콘(`projects.icon`, Material Symbols 42종, 마이그레이션 011)·작업(`tasks`: 담당자·우선순위·시작/마감)·진행단계(`project_stages` 칸반, 생성시 기본 4단계 seed, 섹션 머리는 모두 `#f3f3f3` — 섹션별 색 지정 없음, 섹션 기본 담당자 `default_assignee_email` — 담당자 빈 작업을 그 섹션에 만들거나 옮기면 자동 배정, 마이그레이션 009)·멤버 배정(`project_members`)·활동이력(`project_activity`). 첫 화면(`/project/`)은 **내 작업 목록**(프로젝트 홈 카드 화면은 폐지). 프로젝트 화면은 캘린더(FullCalendar)/타임라인(vis-timeline)/보드/목록/대시보드 뷰 토글. 좌측 사이드바는 수신함·내 작업·휴지통·프로젝트 화면 공용(`templates/project/_side.html` + 프로젝트 목록 동작 `initSideTree`, 새 프로젝트/수정 모달 `_side_modals.html`) — 프로젝트 목록(순서 변경·✎·×)은 어느 화면에서나 같다. 보드는 아사나처럼 섹션이 가로로 계속 늘어나고(넘치면 가로 스크롤) 카드의 담당자·마감일을 클릭해 그 자리에서 바꾼다. 좌측 사이드바에 수신함·내 작업(접이식) 메뉴. 설명란은 주소 붙여넣기 시 자동 링크, 설명란·댓글에서 @로 멤버를 태그하면 (`task_mentions`, 마이그레이션 006) 수신함에 그 작업이 쌓인다. 진입 권한키 `project`(관리자 페이지 토글로 직원별 부여, admin 자동). 프로젝트 생성은 `project` 권한자 누구나(만든 사람이 owner), 삭제는 만든 사람만(슈퍼관리자 예외), 사용자 배정은 `is_admin` 만. 배정 멤버(또는 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개월 보관, 관리자만 보기·복구(`/project/trash`). 권한은 **지금 기준 공통 모듈 `access.py`**(목록·배지·알림·멘션·메일 수신자·삭제·댓글 수정까지 — 멤버에서 빠지면 기록이 있어도 안 보이고 알림도 없음), 소유자 변경은 관리자만, 연결(멀티호밍)된 작업은 연결된 프로젝트 멤버에게 읽기 전용(docs/PROJECT_MODULE.md 6-10). 연간 목표(마이그레이션 013, `goal_*` 테이블) — 사이드바 "목표" → 연도 펼침 → `/project/goals/{연도}` 에 매출(목표·실적·달성)·로아스 월별 숫자 + 업무 영역(상품·마케팅·컨텐츠·유통 등)별 연간·월별 글, 조회는 전원·입력은 `is_admin` 만. 3·6·9·12월 오른쪽 1~4분기 칸(글 칸 13=1분기·15=2분기·14=3분기·16=4분기 — 예전 반기 칸 번호 재사용, 15·16 은 마이그레이션 017) + 분기 월 칸 접기 애니메이션(localStorage `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/{월}`, 프로젝트 권한자 **누구나 수정** — 관리자 [회의 완료](`completed_at`, 마이그레이션 022)면 잠금(지난주 결과는 다음 주 회의록이 열려 있는 동안 허용), 삭제·완료·완료 해제는 관리자, 주차 탭 — **주차는 그 달 안**(`store.month_weeks`: 1일이 월~금이면 1일~일요일이 1주차, 토·일이면 1일~다음 주 일요일, 그 뒤 월~일, 말일이 월·화면 앞 주차에 붙음, 회의록 `week_start` = 주차 시작일, 마이그레이션 020), `goal_meetings`·`goal_meeting_items` 마이그레이션 015 — 지난주 = **바로 앞 주차**(`store.prev_week_period`) 회의록의 같은 연결키 줄(`line_key`, 마이그레이션 018 — 생성 순서·이름 변경과 무관, 이름 추정 연결 금지)로 리뷰(열: 주요 업무·정량 목표 ‖ 전주 업무·결과(글, `result_note` 020)·전주 목표·결과 — 정량 목표·결과는 숫자면 원 정수 칸, 아니면 글 칸 `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_targets` 1주차~이 주차 합 — 목표 표 매출 목표 월 칸을 누르면 주차 입력 창, 합계 = 월 목표)·월 누적 실적(1일~오늘)·누적 목표 대비 차액·%) | ② 결정 사항·메모 | ③ 작업 등록 표(제목·담당자·프로젝트·섹션 → [적용] = 그 프로젝트에 작업 생성, `initMeetQuickTasks`), 실적 모듈 `performance_store` 매출은 머리 카드에만 읽기 전용 — 줄(쇼핑몰)별 자동 결과·이번주 실적·연결 배지·쇼핑몰 연결 메뉴는 폐지, 지난주 결과는 늘 직접 입력). 모든 열 너비 끌어서 조절(localStorage `pj_goal_col_w`), 세로 스크롤 틀 고정은 머리 줄+매출·로아스 줄까지, 항목 칸 +·우클릭으로 줄 위/아래 추가·삭제. 마감 알림(`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.py` stdlib smtplib, `SMTP_*`+`PROJECT_NOTIFY_EMAIL` env, 미설정 시 조용히 skip, `BackgroundTasks` 비동기). 목표 표·회의록 칸 저장은 공용 `createFieldSaver`(같은 칸 요청 직렬화·보낸 값만 저장됨·실패 시 초안 유지·localStorage 초안 백업, 저장 실패면 구조 변경 중단 — docs/PROJECT_MODULE.md 6-9-3), 구역·항목 메뉴는 우클릭 + ⋮ 버튼(키보드·터치). ERP 메뉴 이름은 "Project"(`app/main.py` 모듈 목록 title). 댓글·답글 입력칸은 Enter 등록·Shift+Enter 줄바꿈(textarea), 설명란 이미지 더블클릭 = 별도 창 이미지 보기(확대·축소·끌어 이동). 작업 창은 **저장 버튼 없이 실시간 저장**(칸별 PUT, `saveField`/`saveChain`, 새 작업은 제목이 생기는 순간 생성). 댓글 답글·이모티콘 반응(마이그레이션 012 `task_comments.parent_id`·`task_comment_reactions`, 미적용 시 버튼 숨김·API 503), 완료 이력 줄은 `project_activity` completed 를 댓글 사이에 표시(댓글 수 제외), 댓글 `@아이디` 는 아이콘+이름 칩. 수신함 "확인"은 페이지 이동 없이 오른쪽 iframe 패널(`/project/p/{pid}?task=&embed=1`, `html.pj-embed`). 상단 바 화면 배율 토글(`html.pj-ui-scale` → `.erp-app` zoom .75, 2880×1620·200%용) — **팝업은 반드시 `document.body` 에 붙인다**(배율 안의 fixed 좌표는 어긋남). 상세는 `docs/PROJECT_MODULE.md` +- 프로젝트 관리 (`app/modules/project/`, `project_db`) — 아사나식. 프로젝트/서브프로젝트(self-FK `parent_id`, CASCADE)·프로젝트 색상(32색 — 아사나 16색 + 진한 16색)·아이콘(`projects.icon`, Material Symbols 42종, 마이그레이션 011)·작업(`tasks`: 담당자·우선순위·시작/마감)·진행단계(`project_stages` 칸반, 생성시 기본 4단계 seed, 섹션 머리는 모두 `#f3f3f3` — 섹션별 색 지정 없음, 섹션 기본 담당자 `default_assignee_email` — 담당자 빈 작업을 그 섹션에 만들거나 옮기면 자동 배정, 마이그레이션 009)·멤버 배정(`project_members`)·활동이력(`project_activity`). 첫 화면(`/project/`)은 **내 작업 목록**(프로젝트 홈 카드 화면은 폐지). 프로젝트 화면은 캘린더(FullCalendar)/타임라인(vis-timeline)/보드/목록/대시보드 뷰 토글. 좌측 사이드바는 수신함·내 작업·휴지통·프로젝트 화면 공용(`templates/project/_side.html` + 프로젝트 목록 동작 `initSideTree`, 새 프로젝트/수정 모달 `_side_modals.html`) — 프로젝트 목록(순서 변경·✎·×)은 어느 화면에서나 같다. 보드는 아사나처럼 섹션이 가로로 계속 늘어나고(넘치면 가로 스크롤) 카드의 담당자·마감일을 클릭해 그 자리에서 바꾼다. 좌측 사이드바에 수신함·내 작업(접이식) 메뉴. 설명란은 주소 붙여넣기 시 자동 링크, 설명란·댓글에서 @로 멤버를 태그하면 (`task_mentions`, 마이그레이션 006) 수신함에 그 작업이 쌓인다. 진입 권한키 `project`(관리자 페이지 토글로 직원별 부여, admin 자동). 프로젝트 생성은 `project` 권한자 누구나(만든 사람이 owner), 삭제는 만든 사람만(슈퍼관리자 예외), 사용자 배정은 `is_admin` 만. 배정 멤버(또는 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개월 보관, 관리자만 보기·복구(`/project/trash`). 권한은 **지금 기준 공통 모듈 `access.py`**(목록·배지·알림·멘션·메일 수신자·삭제·댓글 수정까지 — 멤버에서 빠지면 기록이 있어도 안 보이고 알림도 없음), 소유자 변경은 관리자만, 연결(멀티호밍)된 작업은 연결된 프로젝트 멤버에게 읽기 전용(docs/PROJECT_MODULE.md 6-10). 연간 목표(마이그레이션 013, `goal_*` 테이블) — 사이드바 "목표" → 연도 펼침 → `/project/goals/{연도}` 에 매출(목표·실적·달성)·로아스 월별 숫자 + 업무 영역(상품·마케팅·컨텐츠·유통 등)별 연간·월별 글, 조회는 전원·입력은 `is_admin` 만. 3·6·9·12월 오른쪽 1~4분기 칸(글 칸 13=1분기·15=2분기·14=3분기·16=4분기 — 예전 반기 칸 번호 재사용, 15·16 은 마이그레이션 017) + 분기 월 칸 접기 애니메이션(localStorage `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/{월}`, 프로젝트 권한자 **누구나 수정** — 관리자 [회의 완료](`completed_at`, 마이그레이션 022)면 잠금(지난주 결과는 다음 주 회의록이 열려 있는 동안 허용), 삭제·완료·완료 해제는 관리자, 주차 탭 — **주차는 그 달 안**(`store.month_weeks`: 1일이 월~금이면 1일~일요일이 1주차, 토·일이면 1일~다음 주 일요일, 그 뒤 월~일, 말일이 월·화면 앞 주차에 붙음, 회의록 `week_start` = 주차 시작일, 마이그레이션 020), `goal_meetings`·`goal_meeting_items` 마이그레이션 015 — 지난주 = **바로 앞 주차**(`store.prev_week_period`) 회의록의 같은 연결키 줄(`line_key`, 마이그레이션 018 — 생성 순서·이름 변경과 무관, 이름 추정 연결 금지)로 리뷰(열: 주요 업무·정량 목표 ‖ 전주 업무·결과(글, `result_note` 020)·전주 목표·결과 — 정량 목표·결과는 숫자면 원 정수 칸, 아니면 글 칸 `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_targets` 1주차~이 주차 합 — 목표 표 매출 목표 월 칸을 누르면 입력 창 — 월 전체 목표는 직접 입력(주차 합계와 별개), 맨 아래 차이 = 월 목표 − 주차 합계)·월 누적 실적(1일~오늘)·누적 목표 대비 차액·%) | ② 결정 사항·메모 | ③ 작업 등록 표(제목·담당자·프로젝트·섹션 → [적용] = 그 프로젝트에 작업 생성, `initMeetQuickTasks`), 실적 모듈 `performance_store` 매출은 머리 카드에만 읽기 전용 — 줄(쇼핑몰)별 자동 결과·이번주 실적·연결 배지·쇼핑몰 연결 메뉴는 폐지, 지난주 결과는 늘 직접 입력). 모든 열 너비 끌어서 조절(localStorage `pj_goal_col_w`), 세로 스크롤 틀 고정은 머리 줄+매출·로아스 줄까지, 항목 칸 +·우클릭으로 줄 위/아래 추가·삭제. 마감 알림(`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.py` stdlib smtplib, `SMTP_*`+`PROJECT_NOTIFY_EMAIL` env, 미설정 시 조용히 skip, `BackgroundTasks` 비동기). 목표 표·회의록 칸 저장은 공용 `createFieldSaver`(같은 칸 요청 직렬화·보낸 값만 저장됨·실패 시 초안 유지·localStorage 초안 백업, 저장 실패면 구조 변경 중단 — docs/PROJECT_MODULE.md 6-9-3), 구역·항목 메뉴는 우클릭 + ⋮ 버튼(키보드·터치). ERP 메뉴 이름은 "Project"(`app/main.py` 모듈 목록 title). 댓글·답글 입력칸은 Enter 등록·Shift+Enter 줄바꿈(textarea), 설명란 이미지 더블클릭 = 별도 창 이미지 보기(확대·축소·끌어 이동). 작업 창은 **저장 버튼 없이 실시간 저장**(칸별 PUT, `saveField`/`saveChain`, 새 작업은 제목이 생기는 순간 생성). 댓글 답글·이모티콘 반응(마이그레이션 012 `task_comments.parent_id`·`task_comment_reactions`, 미적용 시 버튼 숨김·API 503), 완료 이력 줄은 `project_activity` completed 를 댓글 사이에 표시(댓글 수 제외), 댓글 `@아이디` 는 아이콘+이름 칩. 수신함 "확인"은 페이지 이동 없이 오른쪽 iframe 패널(`/project/p/{pid}?task=&embed=1`, `html.pj-embed`). 상단 바 화면 배율 토글(`html.pj-ui-scale` → `.erp-app` zoom .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`(주=월~일, 수수료 반올림은 `commission()` 한 곳, 요율 이력) + `db.py` ④ 화면 `dashboard.py`/`router.py`/템플릿. 쇼핑몰 API 인증정보는 `.env` 가 아니라 **설정 화면에서 입력 → 마스터 키 `APP_ENCRYPTION_KEY` 로 암호화해 DB 저장**, secret 원문은 화면으로 다시 보내지 않는다. 쇼핑몰 API 는 백엔드에서만 호출, 오류·로그·raw 는 `redact` 후 저장. 매출 기준일: 결제=결제일, 취소·반품=발생일(`sync.sales_date_for`). 금액은 원 단위 정수. 권한키 `performance`, 설정 화면은 모듈 권한자 누구나(일반 사용자는 수수료율만), 수수료 외 설정 API 는 `is_admin`. 매출 업데이트 진행 창에서 쇼핑몰별 [중지](그 쇼핑몰만 멈추고 다음 쇼핑몰로). 카페24 어댑터는 기존 `app/integrations/cafe24` 토큰 재사용. 1단계는 모의 데이터(`is_sample`)·구조까지, 실제 수집은 쇼핑몰별로 공식 문서 확인 후 순차 구현. 상세는 `docs/PERFORMANCE_MODULE.md` diff --git a/app/modules/project/db.py b/app/modules/project/db.py index e470f23..19defac 100644 --- a/app/modules/project/db.py +++ b/app/modules/project/db.py @@ -3090,7 +3090,7 @@ class ProjectStore: return {"sales_unit": head["sales_unit"] if head else "", "sales_target": vals.get(("sales", "target")), "sales_actual": vals.get(("sales", "actual")), "roas_target": vals.get(("roas", "target"))} - # ── 주차별 매출 목표(020) — 목표 표 매출 단위 그대로, 월 목표 = 그 달 주차 합계 ── + # ── 주차별 매출 목표(020) — 목표 표 매출 단위 그대로, 월 목표는 따로 직접 입력(주차 합계와 다를 수 있음) ── def week_targets_enabled(self) -> bool: with self._pool.connection() as conn: return self._table_exists(conn, "goal_week_targets") @@ -3107,10 +3107,13 @@ class ProjectStore: return {r["week_start"].isoformat(): float(r["value"]) for r in rows} def set_goal_week_targets( - self, *, year: int, month: int, values: dict[date, float | None], updated_by: str = "" + self, *, year: int, month: int, values: dict[date, float | None], month_value: float | None, + updated_by: str = "" ) -> float | None: - """그 달 주차별 목표 저장(None = 지움) → 그 달 주차 합계를 매출 목표(goal_metrics sales/target)로. - 주차가 모두 비면 월 목표도 지운다(월 목표 = 주차 합계). 합계를 돌려준다(없으면 None).""" + """그 달 주차별 목표 저장(None = 지움) + 월 매출 목표(goal_metrics sales/target)는 month_value 그대로 + (None = 지움). 월 목표는 주차 합계와 따로 — 차이는 화면이 계산한다. 그 달 주차 합계를 돌려준다(없으면 None).""" + if month_value is not None and month_value < 0: + raise ValueError("월 목표는 0 이상이어야 합니다.") m = store.validate_goal_month(month) periods = {a for a, _ in store.month_weeks(year, m)} if any(d not in periods for d in values): @@ -3139,7 +3142,7 @@ class ProjectStore: (year, m), ).fetchone() total = float(row["total"]) if row["n"] else None - if total is None: + if month_value is None: conn.execute("DELETE FROM goal_metrics WHERE year=%s AND metric='sales' AND kind='target' AND month=%s", (year, m)) else: @@ -3147,7 +3150,7 @@ class ProjectStore: "INSERT INTO goal_metrics (year, metric, kind, month, value, updated_by) " "VALUES (%s,'sales','target',%s,%s,%s) ON CONFLICT (year, metric, kind, month) DO UPDATE " "SET value = EXCLUDED.value, updated_by = EXCLUDED.updated_by, updated_at = now()", - (year, m, total, who), + (year, m, month_value, who), ) return total diff --git a/app/modules/project/router.py b/app/modules/project/router.py index 62e345a..ea078ae 100644 --- a/app/modules/project/router.py +++ b/app/modules/project/router.py @@ -2697,7 +2697,7 @@ def goals_page(request: Request, year: int) -> HTMLResponse: for area in board["areas"]: _goal_area_layout(area["rows"], this_month) _goal_label_spans(area["rows"]) - # 주차별 매출 목표(020) — 월 매출 목표 칸을 누르면 그 달 주차별 입력 창(합계 = 월 목표) + # 주차별 매출 목표(020) — 월 매출 목표 칸을 누르면 그 달 월 목표·주차별 입력 창(월 목표는 직접 입력) week_targets = None if board and st.week_targets_enabled(): saved = st.goal_week_targets(start=date(year, 1, 1), end=date(year, 12, 31)) @@ -2739,15 +2739,23 @@ def goals_page(request: Request, year: int) -> HTMLResponse: @router.put("/api/goals/{year}/week-targets/{month}") def api_set_goal_week_targets(request: Request, year: int, month: int, payload: dict[str, Any] = Body(...)) -> JSONResponse: - """그 달 주차별 매출 목표 {weeks: {주차 시작일: 값|""}} — 합계가 그 달 매출 목표가 된다(관리자).""" + """그 달 주차별 매출 목표 {month: 월 목표|"", weeks: {주차 시작일: 값|""}} — 월 목표는 직접 입력(관리자). + month 가 없으면(예전 화면) 주차 합계를 월 목표로.""" user = _require_admin(request) st = _db_or_503(request) raw = payload.get("weeks") if not isinstance(raw, dict) or len(raw) > 6: raise HTTPException(status_code=400, detail="weeks 가 올바르지 않습니다.") values = {_goal_call(store.validate_period_start, k): _goal_call(store.validate_goal_value, v) for k, v in raw.items()} - total = _goal_call(st.set_goal_week_targets, year=year, month=month, values=values, updated_by=user["email"]) - return JSONResponse({"ok": True, "value": total, "label": _goal_label("sales", total), + if "month" in payload: + month_value = _goal_call(store.validate_goal_value, payload.get("month")) + else: + filled = [v for v in values.values() if v is not None] + month_value = sum(filled) if filled else None + week_total = _goal_call(st.set_goal_week_targets, year=year, month=month, values=values, + month_value=month_value, updated_by=user["email"]) + return JSONResponse({"ok": True, "value": month_value, "label": _goal_label("sales", month_value), + "week_total": week_total, "weeks": {k.isoformat(): _goal_label("sales", v) for k, v in values.items()}}) diff --git a/app/modules/project/templates/project/goals.html b/app/modules/project/templates/project/goals.html index 8303898..48a64a4 100644 --- a/app/modules/project/templates/project/goals.html +++ b/app/modules/project/templates/project/goals.html @@ -56,14 +56,14 @@ {% set rm = board.metrics.roas %} {# 월 칸은 pj-goal-m + data-h(분기 1~4) — 분기 접기(initGoals)가 이걸로 숨긴다. 분기 칸 클래스는 예전 이름 pj-goal-half-col 그대로(연간 칸처럼 굵게·회색 합계) #} - {# 매출 목표 칸(020) — 누르면 그 달 주차별 목표 입력 창(project.js initGoalWeekTargets), 합계 = 월 목표 #} + {# 매출 목표 칸(020) — 누르면 그 달 월 목표(직접 입력)·주차별 목표 입력 창, 맨 아래 차이(월 목표 − 주차 합계) #} {% macro num_cell(metric, kind, labels, mo) -%} {%- set weekly = week_targets and metric == 'sales' and kind == 'target' -%} {%- if is_admin -%} {%- else -%} 매출·로아스 입력과 달성률 계산 - + diff --git a/app/static/project.css b/app/static/project.css index d1c5ec0..ace8a1d 100644 --- a/app/static/project.css +++ b/app/static/project.css @@ -2853,6 +2853,14 @@ input.pj-meet-amount::placeholder { color: rgba(0, 0, 0, .28); } .pj-goal-wkpop-row input[readonly] { background: #f7f8f9; } .pj-goal-wkpop-sum { display: flex; justify-content: space-between; margin-top: 8px; padding-top: 8px; border-top: 1px solid var(--pj-border); } .pj-goal-wkpop-sum b { font-variant-numeric: tabular-nums; } +/* 월 전체 목표(직접 입력) — 주차 줄과 구분선 */ +.pj-goal-wkpop-month { padding-bottom: 8px; margin-bottom: 8px; border-bottom: 1px solid var(--pj-border); font-weight: 700; } +/* 차이 = 월 목표 − 주차 합계 — 남음(+) 주황, 넘음(−) 빨강, 딱 맞음 초록 */ +.pj-goal-wkpop-diff { margin-top: 4px; padding-top: 0; border-top: 0; } +.pj-goal-wkpop-diff small { font-size: 11px; color: var(--pj-ink-soft); } +.pj-goal-wkpop-diff b.is-left { color: #c2410c; } +.pj-goal-wkpop-diff b.is-over { color: #dc2626; } +.pj-goal-wkpop-diff b.is-even { color: #16a34a; } .pj-goal-wkpop-acts { display: flex; justify-content: flex-end; gap: 6px; margin-top: 10px; } /* 나를 태그·작업 배정 알림 — 화면 가운데 아래 큰 팝업(body 에 붙음), 닫기 전까지 깜박인다(2026-10-07) */ diff --git a/app/static/project.js b/app/static/project.js index d37dbba..0f6f21f 100644 --- a/app/static/project.js +++ b/app/static/project.js @@ -9231,8 +9231,9 @@ node.classList.add("is-saved"); } - // ── 주차별 매출 목표(020) — 매출 목표 칸을 누르면 그 달 주차 입력 창(body 에 붙음). 저장하면 주차 합계가 월 목표. - // 관리자는 입력·저장, 보기만 하는 사람은 주차별 값 보기. 주차는 서버(store.month_weeks)가 정한다. + // ── 주차별 매출 목표(020) — 매출 목표 칸을 누르면 그 달 입력 창(body 에 붙음). 월 목표는 맨 위에 직접 입력, + // 아래에 주차별 목표, 맨 아래 주차 합계와 차이(월 목표 − 주차 합계). 주차 합계가 월 목표가 되지 않는다. + // 관리자는 입력·저장, 보기만 하는 사람은 값 보기. 주차는 서버(store.month_weeks)가 정한다. const WEEKS = window.PJ_GOAL_WEEKS || null; let weekPop = null; function closeWeekPop() { @@ -9253,34 +9254,48 @@ weekPop.className = "pj-goal-wkpop"; weekPop.innerHTML = '
' + mo + "월 주차별 매출 목표" + (unit ? " (" + escapeHtml(unit) + ")" : "") + "
" + + '" + list.map(function (w) { return '"; }).join("") + - '
합계 = 월 목표
' + + '
주차 합계
' + + '
차이 (월 목표 − 주차 합계)
' + (edit ? '
' + '
' : ""); document.body.appendChild(weekPop); const r = cell.getBoundingClientRect(), vw = document.documentElement.clientWidth, vh = document.documentElement.clientHeight; weekPop.style.left = Math.max(8, Math.min(r.left, vw - weekPop.offsetWidth - 8)) + "px"; weekPop.style.top = (r.bottom + 6 + weekPop.offsetHeight > vh ? Math.max(8, r.top - weekPop.offsetHeight - 6) : r.bottom + 6) + "px"; - const inputs = Array.from(weekPop.querySelectorAll("input")); - const sumEl = weekPop.querySelector(".pj-goal-wkpop-sum b"); + const monthInput = weekPop.querySelector("input[data-month-total]"); + const inputs = Array.from(weekPop.querySelectorAll("input[data-start]")); + const sumEl = weekPop.querySelector('[data-sum="weeks"]'), diffEl = weekPop.querySelector('[data-sum="diff"]'); function paintSum() { let t = null; inputs.forEach(function (i) { const n = numOf(i); if (n != null) t = (t || 0) + n; }); sumEl.textContent = t == null ? "—" : fmtNum(t); + const total = numOf(monthInput); + const d = total == null ? null : total - (t || 0); + // 차이 + = 주차에 아직 못 나눈 금액, − = 주차 합계가 월 목표를 넘음, 0 = 딱 맞음 + diffEl.textContent = d == null ? "—" : (d > 0 ? "+" : "") + fmtNum(d); + diffEl.classList.toggle("is-over", d != null && d < 0); + diffEl.classList.toggle("is-left", d != null && d > 0); + diffEl.classList.toggle("is-even", d != null && Math.abs(d) < 0.005); } - inputs.forEach(function (i) { i.addEventListener("input", paintSum); }); + [monthInput].concat(inputs).forEach(function (i) { i.addEventListener("input", paintSum); }); paintSum(); async function save(btn) { const weeks = {}; inputs.forEach(function (i) { weeks[i.dataset.start] = i.value; }); btn.disabled = true; try { - const res = await api("PUT", "/project/api/goals/" + year + "/week-targets/" + mo, { weeks: weeks }); + const res = await api("PUT", "/project/api/goals/" + year + "/week-targets/" + mo, + { month: monthInput.value, weeks: weeks }); list.forEach(function (w) { if (res.weeks && w.start in res.weeks) w.value = res.weeks[w.start]; }); cell.value = res.label || ""; recompute(); @@ -9306,7 +9321,7 @@ document.addEventListener("mousedown", onWeekDoc, true); document.addEventListener("keydown", onWeekKey, true); }, 0); - if (edit && inputs.length) { inputs[0].focus(); inputs[0].select(); } + if (edit) { monthInput.focus(); monthInput.select(); } } if (WEEKS) { table.addEventListener("click", function (e) { diff --git a/docs/PROJECT_MODULE.md b/docs/PROJECT_MODULE.md index bb3fe43..e7559f1 100644 --- a/docs/PROJECT_MODULE.md +++ b/docs/PROJECT_MODULE.md @@ -883,9 +883,11 @@ description 을 항상 HTML로 취급하기 때문). 두 번 실행하면 이중 `result_note` — 020, `.pj-meet-rnote` textarea, 0.8초 멈춤·칸 떠남 저장, 초안 `pj_draft:meet:item:{지난 줄}:result_note`) | **전주 목표**(지난 주차 `target_amount`) | **결과**(금액, 지난 주차 `result_amount`). 020 미적용이면 결과 글 칸은 보기만, API 503. - **주차별 매출 목표**(`goal_week_targets(week_start PK, year FK goal_years CASCADE, month, value NUMERIC)` — 목표 표 매출 단위 그대로): - 연간 목표 표 매출 **목표** 월 칸(`data-weekly`, readonly)을 누르면 그 달 주차 입력 창(`.pj-goal-wkpop`, body 에 붙음, 보기만 하는 사람은 값만). - `PUT /project/api/goals/{연도}/week-targets/{월} {weeks: {주차 시작일: 값|""}}`(관리자) → 저장 후 그 달 주차 합계를 - `goal_metrics(sales, target)` 에 쓴다(모두 비면 월 목표도 지움). 020 미적용이면 예전처럼 월 칸 직접 입력. + 연간 목표 표 매출 **목표** 월 칸(`data-weekly`, readonly)을 누르면 그 달 입력 창(`.pj-goal-wkpop`, body 에 붙음, 보기만 하는 사람은 값만). + 맨 위 **월 전체 목표**(직접 입력) → 주차별 목표 → 맨 아래 **주차 합계**·**차이(월 목표 − 주차 합계**, + 주황 = 덜 나눔, + − 빨강 = 넘침, 0 초록). `PUT /project/api/goals/{연도}/week-targets/{월} {month: 월 목표|"", weeks: {주차 시작일: 값|""}}` + (관리자) → 주차 저장 + `goal_metrics(sales, target)` 에 `month` 그대로(빈값 = 지움, 주차 합계와 무관). `month` 가 없는 요청(예전 + 화면 캐시)만 주차 합계를 월 목표로. 020 미적용이면 예전처럼 월 칸 직접 입력. - **020 마이그레이션**(`scripts/sql/project_db_020_meeting_periods.sql`, 멱등): ① `goal_meeting_items.result_note` ② `goal_meetings` 월요일 CHECK 제거 ③ `goal_week_targets` ④ 새 주차에 흡수된 월요일 회의록(1일이 토·일인 달의 2·3일 월요일 → 1일, 말일이 월·화인 달의 마지막 월요일 → 7일 전 월요일)을 옮김 — 옮길 자리에 회의록이 있으면 옮기지 않고 NOTICE. 이미 쓰던 9/28(월) 회의록은 9월 마지막 주차
칸입력·계산 방법
매출 목표월 칸을 누르면 그 달 주차별 목표 입력 창이 열립니다. 주차마다 금액(매출 단위)을 넣고 저장하면 주차 합계가 그 달 매출 목표가 됩니다. 주차는 주간 회의록 주차와 같습니다. 주차를 모두 비우고 저장하면 월 목표도 지워집니다.
매출 목표월 칸을 누르면 그 달 입력 창이 열립니다. 맨 위 월 전체 목표를 직접 넣고, 아래에 주차별 목표(매출 단위)를 넣은 뒤 저장합니다. 월 목표는 주차 합계와 따로 저장되고, 맨 아래에 주차 합계와 차이(월 목표 − 주차 합계)가 나옵니다 — +면 아직 주차에 못 나눈 금액, −면 주차 합계가 월 목표를 넘은 것입니다. 주차는 주간 회의록 주차와 같습니다.
매출 실적관리자가 월별 숫자를 직접 입력합니다. 목표 표의 실적은 회의록의 자동 매출과 별도로 관리하므로 실적 모듈에서 자동으로 채워지지 않습니다.
매출 단위예를 들어 단위가 백만원이면 30은 30,000,000원입니다. 단위를 바꿔도 이미 적은 숫자는 자동 환산되지 않으므로 숫자와 단위를 함께 확인하세요.
연간·분기 매출해당 기간에 입력한 월 숫자의 합계입니다. 합계 칸에 따로 입력하지 않습니다.