diff --git a/CLAUDE.md b/CLAUDE.md index 2554314..d3b4a6a 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, 섹션 기본 담당자 `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/admin)만 그 프로젝트를 조회(화면·API 모두, 비멤버 403)하고 서브프로젝트/작업/단계 CRUD — URL 의 섹션·부모 작업이 그 프로젝트 것인지 서버가 검증. 실시간 반영은 `project_live_version` 카운터(마이그레이션 007, 미적용 시 MAX 폴백). 사이드바 전체 검색(`/api/search`, 제목·설명·댓글, pg_trgm) + 프로젝트/내 작업 필터 바(찾기·상태·담당자·마감·우선순위·정렬, 클라이언트 필터). 협업자(`task_followers`, 자동 팔로우: 만든 사람·담당자·댓글·@태그) — 완료·댓글 알림은 담당자+협업자에게만. 작업 삭제는 휴지통(`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/{월}`, 주차 탭 — **주차는 그 달 안**(`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 권한 토큰 필요), 스크롤해도 고정되는 위쪽 영역 = 왼쪽 숫자 4칸(월 목표 매출·월 누적 목표 매출(목표 표 **주차별 매출 목표** `goal_week_targets` 1주차~이 주차 합 — 목표 표 매출 목표 월 칸을 누르면 주차 입력 창, 합계 = 월 목표)·월 누적 실적(1일~오늘)·누적 목표 대비 차액·%) | 오른쪽 결정 사항·메모, 실적 모듈 `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, 섹션 기본 담당자 `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`, 자동 팔로우: 만든 사람·담당자·댓글·@태그) — 완료·댓글 알림은 담당자+협업자에게만. 작업 삭제는 휴지통(`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/{월}`, 주차 탭 — **주차는 그 달 안**(`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 권한 토큰 필요), 스크롤해도 고정되는 위쪽 영역 = 왼쪽 숫자 4칸(월 목표 매출·월 누적 목표 매출(목표 표 **주차별 매출 목표** `goal_week_targets` 1주차~이 주차 합 — 목표 표 매출 목표 월 칸을 누르면 주차 입력 창, 합계 = 월 목표)·월 누적 실적(1일~오늘)·누적 목표 대비 차액·%) | 오른쪽 결정 사항·메모, 실적 모듈 `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/access.py b/app/modules/project/access.py index 1ac297b..6536e65 100644 --- a/app/modules/project/access.py +++ b/app/modules/project/access.py @@ -5,7 +5,9 @@ 바꾸지도 알림을 받지도 않는다(기록 자체는 업무 이력으로 남긴다). 프로젝트 - 관리(=보기·작업 CRUD) : 관리자(is_admin) · 프로젝트 owner · 배정 멤버. 모두 `project` 모듈 권한이 있어야 한다. + 관리(=보기·작업 CRUD) : 프로젝트 owner · 배정 멤버 · 슈퍼관리자. 모두 `project` 모듈 권한이 있어야 한다. + (2026-10-07 — 관리자(is_admin)도 멤버가 아닌 프로젝트는 보이지 않는다. 예외는 슈퍼관리자 한 명뿐. + 멤버 배정 자체는 여전히 관리자만 — 라우터의 _require_admin.) 작업 FULL : 원 소속 프로젝트를 관리할 수 있음 → 보기·수정·댓글·첨부·삭제(삭제는 추가로 생성자 규칙) @@ -34,10 +36,16 @@ def default_user_lookup(email: str) -> dict[str, Any] | None: return user_store.get(store.norm_str(email, lower=True)) -def _is_admin(user: dict[str, Any] | None) -> bool: - from app.store import is_admin # noqa: WPS433 +def _is_super(user: dict[str, Any] | None) -> bool: + """슈퍼관리자(app.store.SUPER_ADMIN_EMAIL) — 모든 프로젝트를 보는 유일한 예외.""" + from app.store import SUPER_ADMIN_EMAIL # noqa: WPS433 - return is_admin(user) + return bool(user) and email_of(user) == SUPER_ADMIN_EMAIL + + +def sees_all_projects(user: dict[str, Any] | None) -> bool: + """멤버가 아니어도 모든 프로젝트를 보는가 — 슈퍼관리자만(모듈 권한도 있어야).""" + return can_use_module(user) and _is_super(user) def can_use_module(user: dict[str, Any] | None) -> bool: @@ -51,10 +59,10 @@ def email_of(user: dict[str, Any] | None) -> str: def can_manage_project(st: Any, user: dict[str, Any] | None, project_id: Any) -> bool: - """프로젝트 관리(=보기·작업 CRUD) — 관리자 또는 owner/멤버. 모듈 권한이 없으면 False.""" + """프로젝트 관리(=보기·작업 CRUD) — owner/멤버(관리자도 마찬가지), 슈퍼관리자는 전부. 모듈 권한이 없으면 False.""" if not can_use_module(user): return False - if _is_admin(user): + if _is_super(user): return True try: pid = int(project_id) @@ -64,11 +72,11 @@ def can_manage_project(st: Any, user: dict[str, Any] | None, project_id: Any) -> def visible_project_ids(st: Any, user: dict[str, Any]) -> set[int] | None: - """관리할 수 있는 프로젝트 id 집합. 관리자는 None(=전체).""" - if _is_admin(user): - return None + """관리할 수 있는 프로젝트 id 집합. 슈퍼관리자는 None(=전체), 그 밖(관리자 포함)은 owner·멤버인 프로젝트만.""" if not can_use_module(user): return set() + if _is_super(user): + return None return { int(p["id"]) for p in st.list_projects(include_archived=True, member_email=email_of(user)) } diff --git a/app/modules/project/router.py b/app/modules/project/router.py index 02a83f8..e485f65 100644 --- a/app/modules/project/router.py +++ b/app/modules/project/router.py @@ -94,7 +94,7 @@ def _require_admin(request: Request) -> dict[str, Any]: def _can_manage(request: Request, st: Any, user: dict[str, Any], project_id: int) -> bool: - """프로젝트 단위 관리 권한: 관리자이거나 멤버/owner (access.can_manage_project — 지금 기준).""" + """프로젝트 단위 관리 권한: 멤버/owner(관리자도 마찬가지), 슈퍼관리자는 전부 (access.can_manage_project — 지금 기준).""" return access.can_manage_project(st, user, project_id) @@ -439,10 +439,11 @@ def _nav_projects(st: Any, user: dict[str, Any], admin: bool) -> list[dict[str, """좌측 사이드바(project/_side.html)의 프로젝트 트리 데이터. 내 업무 · 수신함 · 프로젝트 화면이 같은 사이드바를 쓰므로 한 곳에서 만든다. + 내가 owner·멤버인 프로젝트만(관리자도 마찬가지, 슈퍼관리자만 전체 — access.sees_all_projects). """ projects = st.list_projects( include_archived=False, - member_email=None if admin else user["email"], + member_email=None if access.sees_all_projects(user) else user["email"], ) return [ { @@ -775,7 +776,7 @@ def project_page(request: Request, project_id: int) -> HTMLResponse: ) all_projects = st.list_projects( include_archived=False, - member_email=None if admin else user["email"], + member_email=None if access.sees_all_projects(user) else user["email"], ) members = st.list_members(project_id=project_id) top_projects = [p for p in all_projects if not p.get("parent_id")] # 과거 서브프로젝트 제외 @@ -919,14 +920,11 @@ def _db_or_503(request: Request) -> Any: @router.get("/api/projects") def api_list_projects(request: Request) -> JSONResponse: - from app.store import is_admin # noqa: WPS433 - user = _require_user(request) st = _db_or_503(request) - admin = is_admin(user) projects = st.list_projects( include_archived=False, - member_email=None if admin else user["email"], + member_email=None if access.sees_all_projects(user) else user["email"], ) return JSONResponse({"projects": projects, "tree": _build_tree(projects)}) @@ -2426,11 +2424,18 @@ def trash_page(request: Request) -> HTMLResponse: "color_palette": list(store.COLOR_PALETTE), "project_icons": list(store.PROJECT_ICONS), "trash_enabled": enabled, - "items": _trash_view_items(st.list_trash()) if enabled else [], + # 휴지통도 내가 볼 수 있는 프로젝트(owner·멤버, 슈퍼관리자는 전체)의 것만 + "items": _trash_view_items(_visible_trash(st, user)) if enabled else [], }, ) +def _visible_trash(st: Any, user: dict[str, Any]) -> list[dict[str, Any]]: + allowed = _accessible_project_ids(st, user) + items = st.list_trash() + return items if allowed is None else [it for it in items if it.get("project_id") in allowed] + + def _trash_view_items(items: list[dict[str, Any]]) -> list[dict[str, Any]]: """휴지통 화면용 — 삭제 시각(KST 문자열)·남은 보관 일수.""" from datetime import datetime # noqa: WPS433 @@ -2457,6 +2462,8 @@ def api_restore_trash(request: Request, trash_id: int) -> JSONResponse: """휴지통 항목 복구 — 관리자 전용. 업무·하위 업무·댓글 등 원래 id 그대로.""" user = _require_admin(request) st = _db_or_503(request) + if not any(int(it["id"]) == trash_id for it in _visible_trash(st, user)): + raise HTTPException(status_code=404, detail="휴지통 항목을 찾을 수 없습니다.") # 멤버가 아닌 프로젝트 것은 없는 것처럼 try: result = st.restore_trash(trash_id=trash_id, restored_by=user["email"]) except KeyError: diff --git a/app/modules/project/templates/project/help.html b/app/modules/project/templates/project/help.html index b7d3272..4cbf8d6 100644 --- a/app/modules/project/templates/project/help.html +++ b/app/modules/project/templates/project/help.html @@ -131,12 +131,12 @@

프로젝트 관리 메뉴는 관리자 페이지에서 “프로젝트 관리” 권한을 받은 직원에게 보입니다.

- - + + - + @@ -485,7 +485,7 @@ @@ -494,7 +494,7 @@

19휴지통 (관리자)

diff --git a/docs/PROJECT_MODULE.md b/docs/PROJECT_MODULE.md index 86fc931..508e36c 100644 --- a/docs/PROJECT_MODULE.md +++ b/docs/PROJECT_MODULE.md @@ -48,8 +48,8 @@ | 멤버 배정 후보 | `project` 권한 보유 등록 사용자 자동 목록 (`GET /project/api/assignable-users`) | | 생성 권한 | **프로젝트·섹션·작업(하위 작업 포함) 생성은 로그인해 이 모듈에 접근할 수 있는 사용자 누구나.** 프로젝트를 만든 사람은 자동으로 owner 가 되어 그 프로젝트를 관리(`_can_manage`)할 수 있다. 다른 사람을 owner 로 지정해 만드는 건 관리자만(비관리자가 `owner_email` 을 남으로 보내면 403) | | 소유자 변경 | **관리자만**(2026-09-30). owner 는 멤버에서 빠져도 관리 권한이 남으므로, 일반 멤버가 스스로를 owner 로 바꿔 권한 회수를 피할 수 없게 `PUT /api/projects/{id}` 의 `owner_email` 변경은 비관리자 403(같은 값은 무시). 새 owner 는 `project` 권한이 있는 등록 사용자여야 한다(아니면 400) | -| 수정/이동 권한 | 서브프로젝트·작업·섹션 CRUD(이름변경·완료토글·순서변경 등) = 그 프로젝트의 배정 멤버 또는 owner 또는 admin(`_require_manage`). 작업 API 는 `_require_task(write=True)` = 원 소속 프로젝트 권한(FULL) | -| 조회 권한 | 프로젝트 화면(`/p/{id}`)·멤버/섹션/작업/활동/스냅샷 API 도 멤버·owner·admin 만(`_require_manage`). 비멤버는 403. `GET /api/users/tasks` 를 프로젝트 없이 부르면 내가 볼 수 있는 프로젝트의 작업만 돌려준다. 연결된(멀티호밍) 작업은 연결된 프로젝트 멤버에게 **읽기 전용**(6-10) | +| 수정/이동 권한 | 서브프로젝트·작업·섹션 CRUD(이름변경·완료토글·순서변경 등) = 그 프로젝트의 배정 멤버 또는 owner 또는 슈퍼관리자(`_require_manage`). 작업 API 는 `_require_task(write=True)` = 원 소속 프로젝트 권한(FULL) | +| 조회 권한 | 프로젝트 화면(`/p/{id}`)·멤버/섹션/작업/활동/스냅샷 API 도 멤버·owner 만(`_require_manage`). 비멤버는 403. **관리자(is_admin)도 멤버가 아니면 못 본다 — 예외는 슈퍼관리자(`app.store.SUPER_ADMIN_EMAIL`) 한 명**(2026-10-07, `access.sees_all_projects`·`visible_project_ids`). 왼쪽 사이드바 프로젝트 목록·`GET /api/projects`·검색·수신함·알림·마감 알림·휴지통(목록·복구)도 같은 기준. 멤버 배정은 여전히 관리자만이라, 관리자는 자기가 멤버인 프로젝트에서만 배정할 수 있다(직원이 만든 프로젝트는 슈퍼관리자가 배정). `GET /api/users/tasks` 를 프로젝트 없이 부르면 내가 볼 수 있는 프로젝트의 작업만 돌려준다. 연결된(멀티호밍) 작업은 연결된 프로젝트 멤버에게 **읽기 전용**(6-10) | | 지금 권한 기준 | 모든 판단은 **지금** 권한(`app/modules/project/access.py`) — 멤버에서 빠진 사람은 예전 담당자·멘션·협업자 기록이 있어도 내 작업·수신함·알림·검색·상세·공유 링크·댓글·첨부에서 그 작업이 보이지 않고, 새 알림·메일도 받지 않는다(기록은 이력으로 남김) | | 입력 검증 | URL 의 섹션이 URL 의 프로젝트 것인지(`_stage_of_project`), 작업 생성/수정·연결 시 섹션이 그 프로젝트 것인지(`stage_in_project`), 하위 작업의 부모가 같은 프로젝트인지 확인 — 권한은 URL 의 project_id 로 보므로 이걸 안 보면 남의 프로젝트를 건드릴 수 있다. 새 담당자는 그 프로젝트를 볼 수 있는 사람만(400). 날짜 범위(시작 ≤ 마감, 같은 날이면 시작 시각 ≤ 마감 시각)는 부분 수정도 기존 값과 합친 최종 상태로 검사(400) | | 삭제 권한 | **프로젝트·섹션·작업 모두 "만든 사람만"**(슈퍼관리자 예외, 생성자 정보 없는 과거 데이터는 admin 허용) — `_can_delete` 하나로 통일. **그리고 지금 그 프로젝트 권한이 있어야 한다**(멤버에서 빠진 생성자는 403, DB·휴지통 변화 없음) | diff --git a/tests/test_project_access_members_only.py b/tests/test_project_access_members_only.py new file mode 100644 index 0000000..fad20a6 --- /dev/null +++ b/tests/test_project_access_members_only.py @@ -0,0 +1,80 @@ +"""프로젝트는 멤버(owner 포함)만 — 관리자도 멤버가 아니면 안 보인다, 예외는 슈퍼관리자(2026-10-07). DB 없이.""" +import importlib +import sys +import unittest +from types import SimpleNamespace +from unittest.mock import Mock, patch + +from fastapi import FastAPI +from fastapi.testclient import TestClient + +from app.modules.project import access +from app.store import SUPER_ADMIN_EMAIL + +api = importlib.import_module("app.modules.project.router") + +ADMIN = {"email": "admin@test.local", "role": "admin"} +SUPER = {"email": SUPER_ADMIN_EMAIL, "role": "admin"} +MEMBER = {"email": "bob@test.local", "role": "user"} + + +class FakeStore: + """프로젝트 1 = bob 멤버, 2 = admin 멤버. list_projects(member_email) 는 그 사람이 owner·멤버인 것만.""" + members = {1: {"bob@test.local"}, 2: {"admin@test.local"}} + + def __init__(self): + self.member_email_asked = "unset" + + def is_member(self, project_id, user_email): + return user_email in self.members.get(project_id, set()) + + def list_projects(self, include_archived=False, member_email=None): + self.member_email_asked = member_email + return [{"id": pid, "parent_id": None, "name": f"P{pid}"} for pid, ms in self.members.items() + if member_email is None or member_email in ms] + + +class MembersOnlyTests(unittest.TestCase): + def setUp(self): + self.st = FakeStore() + p = patch.object(access, "can_use_module", side_effect=lambda u: bool(u)) + p.start() + self.addCleanup(p.stop) + + def test_admin_sees_only_member_projects(self): + self.assertFalse(access.can_manage_project(self.st, ADMIN, 1)) + self.assertTrue(access.can_manage_project(self.st, ADMIN, 2)) + self.assertEqual(access.visible_project_ids(self.st, ADMIN), {2}) + self.assertFalse(access.sees_all_projects(ADMIN)) + + def test_member_and_super_admin(self): + self.assertTrue(access.can_manage_project(self.st, MEMBER, 1)) + self.assertFalse(access.can_manage_project(self.st, MEMBER, 2)) + self.assertTrue(access.can_manage_project(self.st, SUPER, 1)) + self.assertIsNone(access.visible_project_ids(self.st, SUPER)) # 전체 + self.assertTrue(access.sees_all_projects(SUPER)) + + def test_sidebar_list_is_member_only_for_admin(self): + self.assertEqual([p["id"] for p in api._nav_projects(self.st, ADMIN, True)], [2]) + self.assertEqual(self.st.member_email_asked, "admin@test.local") + self.assertEqual(sorted(p["id"] for p in api._nav_projects(self.st, SUPER, True)), [1, 2]) + self.assertIsNone(self.st.member_email_asked) + + def test_project_list_api_is_member_only_for_admin(self): + app = FastAPI() + app.include_router(api.router) + client = TestClient(app) + with patch.object(api, "_require_user", return_value=ADMIN), patch.object(api, "_db_or_503", return_value=self.st): + r = client.get("/project/api/projects") + self.assertEqual(r.status_code, 200, r.text) + self.assertEqual([p["id"] for p in r.json()["projects"]], [2]) + + def test_trash_is_filtered_to_member_projects(self): + st = SimpleNamespace(list_trash=lambda: [{"id": 7, "project_id": 1}, {"id": 8, "project_id": 2}], + **{k: getattr(self.st, k) for k in ("is_member", "list_projects")}) + self.assertEqual([t["id"] for t in api._visible_trash(st, ADMIN)], [8]) + self.assertEqual([t["id"] for t in api._visible_trash(st, SUPER)], [7, 8]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_project_module.py b/tests/test_project_module.py index afd401a..a14fe34 100644 --- a/tests/test_project_module.py +++ b/tests/test_project_module.py @@ -121,7 +121,8 @@ def _count(sql: str, *args) -> int: # [07] 소유자 변경은 관리자만 # ════════════════════════════════════════════════════════════ def test_owner_change_admin_only(): - p = _project("P-owner", ADMIN, (BOB,)) + # 관리자도 멤버가 아닌 프로젝트는 못 다룬다(2026-10-07) — 소유자를 남에게 넘긴 뒤에도 바꿀 수 있게 멤버로 둔다 + p = _project("P-owner", ADMIN, (BOB, ADMIN)) r = req("PUT", f"/project/api/projects/{p['id']}", BOB, json={"owner_email": BOB}) assert r.status_code == 403, r.text assert ST.get_project(project_id=p["id"])["owner_email"] == ADMIN
할 수 있는 일누가
프로젝트 보기그 프로젝트의 멤버·소유자(또는 관리자). 멤버가 아니면 주소를 알아도 열리지 않습니다.
작업·하위 작업·댓글그 프로젝트의 멤버·소유자·관리자가 만들고 고칠 수 있습니다.
프로젝트 보기그 프로젝트의 멤버·소유자만. 관리자도 멤버가 아니면 왼쪽 프로젝트 목록·검색·휴지통에 보이지 않고, 주소를 알아도 열리지 않습니다(최고 관리자만 예외).
작업·하위 작업·댓글그 프로젝트의 멤버·소유자가 만들고 고칠 수 있습니다.
작업·섹션·프로젝트 삭제만든 사람만 지울 수 있습니다(최고 관리자는 예외).
댓글 고치기·지우기댓글을 쓴 사람(또는 관리자)만.
새 프로젝트, 사이드바의 프로젝트 수정·순서 바꾸기관리자 (+ · ✎ · ⣿ 버튼이 관리자에게만 보입니다)
멤버 배정·제외, 프로젝트 소유자 바꾸기관리자
멤버 배정·제외, 프로젝트 소유자 바꾸기관리자(자기가 멤버인 프로젝트에서)
다른 프로젝트에서 연결돼 온 작업원래 프로젝트 멤버가 아니면 읽기만 — 내용·댓글·첨부는 보이지만 고치거나 댓글을 달 수 없습니다(연결된 보드 안에서 섹션 옮기기는 됩니다).
멤버에서 빠졌을 때그 프로젝트의 작업은 내 작업·수신함·알림·검색에서 사라지고, 예전 링크로도 열리지 않습니다. 새 알림도 오지 않습니다.
휴지통 보기·복구, 전체 멤버, 대시보드의 담당자별 차트관리자