chore(cupang): 되돌린 뒤 CSS 캐시버전 갱신

47e09b9 되돌리기로 cupang.css 내용이 20260829e 시점으로 돌아갔지만,
브라우저에 20260829f(핸들 스타일 포함)가 캐시돼 있을 수 있어 새 버전으로
올린다.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.env.example

@@ -32,6 +32,66 @@ CUSTOMER_ORDER_LIST_URL=/orderlist/
 # 권한키: vacation(접근) / vacation_approver(승인·반려). admin 은 항상 통과.
 # VACATION_DB_URL=postgresql://vacation_app:replace-me@postgres-db:5432/vacation_db
 
+# ─── 말레이시아 창고 재고관리 모듈 (malaysia_stock_db) ───
+# 설정해야 모듈이 동작한다(미설정 시 "설정 필요" 안내, JSON 폴백 없음).
+# DB/역할/스키마/창고·아이템 seed 생성: scripts/sql/malaysia_stock_db_init.sql 참고.
+# 권한키: malaysia(접근). admin 은 항상 통과. 상품명은 아래 ITEMCODE_DB_URL 재사용.
+# MALAYSIA_STOCK_DB_URL=postgresql://malaysia_app:replace-me@postgres-db:5432/malaysia_stock_db
+
+# ─── 말레이시아 배송 모듈 (dispatch_db) — TikTok 출고관리 ───
+# 설정해야 모듈이 동작한다(미설정 시 "설정 필요" 안내, JSON 폴백 없음).
+# DB/역할/스키마 생성: scripts/sql/dispatch_db_init.sql 참고.
+# 권한키: dispatch(접근). admin 은 항상 통과.
+# 업로드 원본 파일은 DATA_DIR/dispatch/<날짜>/<배치>/ 아래에 저장된다.
+# 개인정보(고객 이름/주소/전화)는 저장하지 않는다.
+# DISPATCH_DB_URL=postgresql://dispatch_app:replace-me@postgres-db:5432/dispatch_db
+
+# ─── 프로젝트 관리 모듈 (project_db) — 아사나식 ───
+# 설정해야 모듈이 동작한다(미설정 시 "설정 필요" 안내, JSON 폴백 없음).
+# DB/역할/스키마 생성: scripts/sql/project_db_init.sql 참고.
+# 진입 권한: 로그인한 회사 직원 전원(별도 권한키 없음). 프로젝트 생성/배정은 관리자만.
+# PROJECT_DB_URL=postgresql://project_app:replace-me@postgres-db:5432/project_db
+
+# ─── 메일 알림 (SMTP) — 프로젝트 업무 배정/완료 시 관리자 알림 ───
+# SMTP_HOST 가 있어야 발송. 미설정 시 조용히 skip(앱은 정상 동작).
+# SMTP_TLS: true(STARTTLS,587 기본) | ssl(SMTPS,465) | false(평문)
+# SMTP_HOST=smtp.gmail.com
+# SMTP_PORT=587
+# SMTP_USER=alarm@dbxcorp.co.kr
+# SMTP_PASSWORD=app-password-here
+# SMTP_FROM=alarm@dbxcorp.co.kr
+# SMTP_TLS=true
+# 알림 수신자(쉼표구분). 비워두면 ERP 관리자(admin) 전원에게 발송.
+# PROJECT_NOTIFY_EMAIL=king@dbxcorp.co.kr
+
+# ─── 카페24 상품 상세페이지 관리 모듈 (cafe24_db) ───
+# 설정해야 모듈이 동작한다(미설정 시 "설정 필요" 안내, JSON 폴백 없음).
+# DB/역할/스키마 생성: scripts/sql/cafe24_db_init.sql 참고.
+# 권한키: cafe24(접근). admin 은 항상 통과. 카페24 연결(OAuth)은 admin 전용.
+# CAFE24_DB_URL=postgresql://cafe24_app:replace-me@postgres-db:5432/cafe24_db
+#
+# 카페24 개발자센터(https://developers.cafe24.com)에서 앱을 만들고 발급받은 값.
+#   - Redirect URI 는 아래 CAFE24_REDIRECT_URI 와 반드시 동일하게 앱에 등록.
+#   - Scope 는 상품관리에 mall.read_product, mall.write_product 가 필요하다.
+#     (향후 주문관리 추가 시 mall.read_order, mall.write_order 를 앱에 추가하고
+#      재인증하면 된다 — 코드는 app/integrations/cafe24/config.py 의 SCOPES)
+# CAFE24_MALL_ID=miraskitchen
+# CAFE24_CLIENT_ID=
+# CAFE24_CLIENT_SECRET=
+# CAFE24_REDIRECT_URI=https://dbx.no1king.freeddns.org/cafe24/oauth/callback
+# CAFE24_API_VERSION=2026-03-01
+#
+# 고객이 보는 쇼핑몰 주소. 상품관리 화면에서 상세페이지 다이렉트 주소를 만들 때 쓴다
+#   (예: https://miras.co.kr/product/detail.html?product_no=119).
+# 커스텀 도메인은 mall_id 로 알 수 없어 직접 지정해야 한다.
+# 미설정 시 카페24 기본 도메인(https://<mall_id>.cafe24.com)으로 대체된다.
+# CAFE24_SHOP_URL=https://miras.co.kr
+#
+# access/refresh token 을 DB 에 Fernet 암호화해서 저장할 때 쓰는 키.
+# openssl rand -hex 32 로 생성. ⚠️ 값을 바꾸면 기존 토큰을 복호화할 수 없어
+# 카페24 재연결(재인증)이 필요하다.
+# CAFE24_TOKEN_SECRET=
+
 # ─── 상품 검색 (itemcode_db 읽기 전용) ───
 # cupang 설정 화면에서 제품명을 itemcode_db 에서 검색해 등록한다(읽기만).
 # 미설정 시 검색 비활성 → 수동 등록만 가능.

.gitignore

@@ -20,3 +20,7 @@ __pycache__/
 .idea/
 .claude/
 
+
+# dispatch 라벨 PDF 샘플(실제 고객 PII — 커밋 금지)
+docs/samples/
+tests/js/.out/

CLAUDE.md

@@ -33,6 +33,10 @@ Claude Code는 이 저장소에서 작업을 시작하기 전에 **반드시 아
 - 개인경비 (`app/modules/expense/`, `expense_db`)
 - 쿠팡 밀크런 (`app/modules/cupang/`, `cupang_db`) — 출고 달력/박스 입수량 계산/입고센터 관리, 상품은 `itemcode_db` 읽기 전용
 - 휴가 관리 (`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) 조회·편집·즉시적용·예약적용·자동복원·버전 롤백·일괄수정. 카페24 OAuth/API 클라이언트는 향후 주문관리와 공유하기 위해 **공통 계층 `app/integrations/cafe24/`** 에 둔다 — 라우터에서 `httpx`/`requests` 직접 호출 금지. 토큰은 Fernet 암호화 저장(`CAFE24_TOKEN_SECRET`), 로그/화면에 토큰·시크릿 절대 미출력. 쓰기 직전 항상 카페24 현재 HTML 을 다시 읽어 `BACKUP` revision 생성(로컬 값을 현재값으로 가정 금지). 예약은 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)·업무(`tasks`: 담당자·우선순위·시작/마감)·진행단계(`project_stages` 칸반, 생성시 기본 4단계 seed)·멤버 배정(`project_members`)·활동이력(`project_activity`). 메인 뷰 달력(FullCalendar)/타임라인(vis-timeline) 버튼 토글 + 보드(드래그로 단계 이동)/리스트. 진입 권한키 `project`(관리자 페이지 토글로 직원별 부여, admin 자동). 프로젝트 생성/삭제·사용자 배정은 `is_admin` 만, 배정 멤버(또는 owner)는 서브프로젝트/업무/단계 CRUD. 멤버 배정 후보는 `project` 권한 보유 등록 사용자에서 자동 목록(`GET /project/api/assignable-users`). 업무 배정·완료 시 관리자에게 메일(`app/mail.py` stdlib smtplib, `SMTP_*`+`PROJECT_NOTIFY_EMAIL` env, 미설정 시 조용히 skip, `BackgroundTasks` 비동기). 상세는 `docs/PROJECT_MODULE.md`
 
 상세는 `docs/PROJECT_OVERVIEW.md`.
 

app/integrations/__init__.py

@@ -0,0 +1,5 @@
+"""외부 서비스 연동 공통 계층.
+
+모듈(app/modules/*)에 종속되지 않는 재사용 가능한 API 클라이언트를 둔다.
+현재: cafe24 (상품관리 + 향후 주문관리가 공유).
+"""

app/integrations/cafe24/__init__.py

@@ -0,0 +1,95 @@
+"""카페24 연동 공통 계층 (상품관리 + 향후 주문관리 공유).
+
+구성
+    config.py    환경변수 → Cafe24Config (하드코딩 금지)
+    crypto.py    토큰 Fernet 암복호화
+    oauth.py     인증 URL / code→token / refresh
+    tokens.py    TokenService — 저장·만료판정·자동갱신(행 잠금)
+    client.py    Cafe24Client — 전송·재시도·429/5xx·API 로그
+    products.py  상품 엔드포인트 래퍼
+    errors.py    공통 예외
+
+사용 예 (모듈 라우터에서):
+
+    from app.integrations.cafe24 import build_cafe24_api
+
+    api = build_cafe24_api(store)          # store = Cafe24Store
+    html = products.get_description(api.client, 123)
+
+CAFE24_* 환경변수가 없어도 import 는 성공한다. 실제 호출 시점에
+Cafe24ConfigError 가 나며, 라우터가 "설정 필요" 안내를 보여준다.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from . import products
+from .client import Cafe24Client
+from .config import (
+    DEFAULT_SCOPES,
+    DESIGN_SCOPES,
+    ORDER_SCOPES,
+    PRODUCT_SCOPES,
+    Cafe24Config,
+    load_config,
+)
+from .errors import (
+    Cafe24ApiError,
+    Cafe24AuthError,
+    Cafe24ConfigError,
+    Cafe24Error,
+    Cafe24RateLimitError,
+)
+from .oauth import TokenBundle, build_authorize_url, exchange_code, new_state, refresh_tokens
+from .tokens import TokenService
+
+__all__ = [
+    "Cafe24Api",
+    "build_cafe24_api",
+    "Cafe24Client",
+    "Cafe24Config",
+    "TokenService",
+    "TokenBundle",
+    "load_config",
+    "build_authorize_url",
+    "exchange_code",
+    "refresh_tokens",
+    "new_state",
+    "products",
+    "PRODUCT_SCOPES",
+    "ORDER_SCOPES",
+    "DESIGN_SCOPES",
+    "DEFAULT_SCOPES",
+    "Cafe24Error",
+    "Cafe24ConfigError",
+    "Cafe24AuthError",
+    "Cafe24RateLimitError",
+    "Cafe24ApiError",
+]
+
+
+@dataclass(frozen=True)
+class Cafe24Api:
+    """설정 + 토큰서비스 + 클라이언트 묶음. 라우터/worker 가 이것만 들고 다닌다."""
+
+    config: Cafe24Config
+    tokens: TokenService
+    client: Cafe24Client
+
+
+def build_cafe24_api(store: Any, *, scopes: tuple[str, ...] = DEFAULT_SCOPES) -> Cafe24Api:
+    """Cafe24Store 를 저장소로 쓰는 API 묶음 생성.
+
+    store 는 토큰 3개 메서드(get_token_row/save_token_row/token_lock)와
+    API 로그 기록용 log_api_call 을 제공해야 한다.
+    """
+    config = load_config(scopes=scopes)
+    token_service = TokenService(store, config)
+    client = Cafe24Client(
+        config,
+        token_service,
+        api_logger=getattr(store, "log_api_call", None),
+    )
+    return Cafe24Api(config=config, tokens=token_service, client=client)

app/integrations/cafe24/client.py

@@ -0,0 +1,258 @@
+"""카페24 Admin API 전송 계층.
+
+라우터/서비스는 httpx 를 직접 쓰지 않고 이 클라이언트만 쓴다.
+여기서 처리하는 것:
+  - Authorization 헤더 부착 (TokenService 가 만료 시 자동 갱신)
+  - X-Cafe24-Api-Version 헤더
+  - timeout
+  - 401 → 토큰 1회 강제 갱신 후 재시도
+  - 429 → Retry-After 존중, 제한 횟수만큼 대기 후 재시도
+  - 5xx / 네트워크 오류 → 지수 백오프 재시도
+  - 호출당 최소 간격 유지(대량 작업이 한 번에 몰리지 않게)
+  - API 로그 기록 (토큰/시크릿은 절대 기록하지 않음)
+
+동기(sync) 클라이언트다. 예약 worker 가 평범한 스크립트이고, 라우터에서는
+`async def` 대신 `def` 핸들러로 선언해 FastAPI 의 스레드풀에서 실행하면
+이벤트 루프를 막지 않는다.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Any, Callable
+
+import httpx
+
+from .config import Cafe24Config
+from .errors import (
+    Cafe24ApiError,
+    Cafe24AuthError,
+    Cafe24ConfigError,
+    Cafe24RateLimitError,
+)
+from .tokens import TokenService
+
+logger = logging.getLogger("cafe24.client")
+
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+# 카페24 호출 사이 최소 간격(초). 대량 수정 시 429 를 미리 피한다.
+DEFAULT_MIN_INTERVAL = 0.35
+
+# api_logger(endpoint, method, product_no, http_status, result, error_message, duration_ms)
+ApiLogger = Callable[..., None]
+
+
+class Cafe24Client:
+    def __init__(
+        self,
+        config: Cafe24Config,
+        token_service: TokenService,
+        *,
+        api_logger: ApiLogger | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        min_interval: float = DEFAULT_MIN_INTERVAL,
+    ):
+        self._config = config
+        self._tokens = token_service
+        self._api_logger = api_logger
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._min_interval = min_interval
+        self._pace_lock = threading.Lock()
+        self._last_call = 0.0
+
+    # ────────────────────────────────────────────────────────────
+    # 내부 헬퍼
+    # ────────────────────────────────────────────────────────────
+    def _pace(self) -> None:
+        """호출 간 최소 간격 확보 (스레드 안전)."""
+        with self._pace_lock:
+            gap = time.monotonic() - self._last_call
+            if gap < self._min_interval:
+                time.sleep(self._min_interval - gap)
+            self._last_call = time.monotonic()
+
+    def _headers(self, access_token: str) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {access_token}",
+            "Content-Type": "application/json",
+            "X-Cafe24-Api-Version": self._config.api_version,
+        }
+
+    def _log(
+        self,
+        *,
+        endpoint: str,
+        method: str,
+        product_no: int | None,
+        http_status: int | None,
+        result: str,
+        error_message: str,
+        duration_ms: int,
+    ) -> None:
+        if self._api_logger is None:
+            return
+        try:
+            self._api_logger(
+                endpoint=endpoint,
+                method=method,
+                product_no=product_no,
+                http_status=http_status,
+                result=result,
+                error_message=error_message[:500],
+                duration_ms=duration_ms,
+            )
+        except Exception:  # noqa: BLE001 — 로그 실패가 본 작업을 막으면 안 된다.
+            logger.exception("카페24 API 로그 기록 실패")
+
+    @staticmethod
+    def _error_message(response: httpx.Response) -> str:
+        """카페24 오류 응답에서 사람이 읽을 메시지만 뽑는다."""
+        try:
+            payload = response.json()
+        except ValueError:
+            return response.text[:500]
+        error = payload.get("error")
+        if isinstance(error, dict):
+            parts = [str(error.get("message") or "")]
+            detail = error.get("details")
+            if isinstance(detail, list) and detail:
+                parts.append("; ".join(str(d.get("message", d)) for d in detail[:3]))
+            message = " / ".join(p for p in parts if p)
+            if message:
+                return message[:500]
+        return str(payload)[:500]
+
+    @staticmethod
+    def _retry_after(response: httpx.Response, *, attempt: int) -> float:
+        raw = (response.headers.get("Retry-After") or "").strip()
+        if raw:
+            try:
+                return max(0.5, float(raw))
+            except ValueError:
+                pass
+        return min(8.0, 0.5 * (2**attempt))
+
+    # ────────────────────────────────────────────────────────────
+    # 공개 API
+    # ────────────────────────────────────────────────────────────
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        product_no: int | None = None,
+    ) -> dict[str, Any]:
+        """카페24 Admin API 호출. 성공 시 응답 JSON(dict) 반환."""
+        if not self._config.configured:
+            raise Cafe24ConfigError(
+                "카페24 설정이 없습니다. 미설정 항목: " + ", ".join(self._config.missing)
+            )
+
+        endpoint = path if path.startswith("/") else f"/{path}"
+        url = f"{self._config.api_base}{endpoint}"
+        method = method.upper()
+        forced_refresh = False
+        last_error: Exception | None = None
+
+        for attempt in range(self._max_retries + 1):
+            self._pace()
+            started = time.monotonic()
+            status: int | None = None
+            try:
+                access_token = self._tokens.get_access_token()
+                with httpx.Client(timeout=self._timeout) as client:
+                    response = client.request(
+                        method,
+                        url,
+                        headers=self._headers(access_token),
+                        params=params,
+                        json=json,
+                    )
+                status = response.status_code
+                elapsed = int((time.monotonic() - started) * 1000)
+
+                if 200 <= status < 300:
+                    self._log(
+                        endpoint=endpoint, method=method, product_no=product_no,
+                        http_status=status, result="SUCCESS", error_message="",
+                        duration_ms=elapsed,
+                    )
+                    try:
+                        return response.json()
+                    except ValueError:
+                        return {}
+
+                message = self._error_message(response)
+                self._log(
+                    endpoint=endpoint, method=method, product_no=product_no,
+                    http_status=status, result="FAIL", error_message=message,
+                    duration_ms=elapsed,
+                )
+
+                if status == 401 and not forced_refresh:
+                    # 서버가 토큰을 먼저 무효화한 경우 — 1회만 강제 갱신 후 재시도.
+                    forced_refresh = True
+                    self._tokens.force_expire()
+                    last_error = Cafe24AuthError("카페24 인증이 만료되어 갱신 후 재시도합니다.")
+                    continue
+
+                if status == 401:
+                    raise Cafe24AuthError(
+                        "카페24 인증에 실패했습니다. 시스템 → 카페24 연결에서 재인증하세요.",
+                        needs_reauth=True,
+                    )
+
+                if status == 429:
+                    wait = self._retry_after(response, attempt=attempt)
+                    last_error = Cafe24RateLimitError(
+                        f"카페24 API 호출 제한(429). {wait:.1f}초 후 재시도합니다.",
+                        retry_after=wait,
+                    )
+                    if attempt >= self._max_retries:
+                        raise last_error
+                    time.sleep(wait)
+                    continue
+
+                error = Cafe24ApiError(message, status=status, endpoint=endpoint)
+                if error.retryable and attempt < self._max_retries:
+                    last_error = error
+                    time.sleep(min(8.0, 0.5 * (2**attempt)))
+                    continue
+                raise error
+
+            except (Cafe24AuthError, Cafe24RateLimitError, Cafe24ApiError, Cafe24ConfigError):
+                raise
+            except httpx.HTTPError as exc:
+                elapsed = int((time.monotonic() - started) * 1000)
+                message = f"네트워크 오류 ({type(exc).__name__})"
+                self._log(
+                    endpoint=endpoint, method=method, product_no=product_no,
+                    http_status=status, result="ERROR", error_message=message,
+                    duration_ms=elapsed,
+                )
+                last_error = Cafe24ApiError(message, status=0, endpoint=endpoint)
+                if attempt < self._max_retries:
+                    time.sleep(min(8.0, 0.5 * (2**attempt)))
+                    continue
+                raise last_error from None
+
+        # 재시도를 모두 소진 (401 강제갱신 루프 포함)
+        if last_error:
+            raise last_error
+        raise Cafe24ApiError("카페24 API 호출에 실패했습니다.", endpoint=endpoint)
+
+    def get(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        return self.request("GET", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        return self.request("PUT", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        return self.request("POST", path, **kwargs)

app/integrations/cafe24/config.py

@@ -0,0 +1,117 @@
+"""카페24 연동 설정 — 환경변수만 읽는다(하드코딩 금지).
+
+app/main.py 의 env() 헬퍼와 동일하게 os.getenv + strip 규칙을 쓴다.
+integrations 계층은 app.main 을 import 하지 않는다(순환 import 방지).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+# 상품관리에 필요한 최소 scope. 향후 주문관리는 ORDER_SCOPES 를 더한다.
+PRODUCT_SCOPES: tuple[str, ...] = ("mall.read_product", "mall.write_product")
+ORDER_SCOPES: tuple[str, ...] = ("mall.read_order", "mall.write_order")
+
+# 디자인(테마) — **요청하지 않는다.** 아래 확인 결과 때문이다.
+#
+# 운영몰에서 직접 호출해 확인한 사실(2026-08-14):
+#   GET /admin/themes        → 조회는 가능(디자인 권한 필요)하지만 테마 "목록"뿐이며
+#                              스킨 파일 내용은 응답에 없다.
+#   GET /admin/themes/pages  → No API found. (버전 2026-03-01 에 존재하지 않음)
+#   스킨 HTML 파일(product/detail.html 등)을 읽거나 쓰는 엔드포인트는 없다.
+#
+# 즉 스킨에 박힌 값(예: 상단 공통 홍보를 제외할 상품번호 목록)을 API 로 고치는
+# 방법은 없다. 스킨은 카페24 관리자에서 직접 관리해야 한다.
+#
+# 페이지에 코드를 주입하는 유일한 수단은 스크립트 태그(/admin/scripttags)이며,
+# 디자인이 아니라 **mall.write_store(상점)** 권한이 필요하고 인라인 코드가 아닌
+# 외부 HTTPS URL 만 받는다. 쓰려면 우리 서버에 공개 JS 엔드포인트가 필요하다.
+DESIGN_SCOPES: tuple[str, ...] = ("mall.read_design", "mall.write_design")
+STORE_SCOPES: tuple[str, ...] = ("mall.read_store", "mall.write_store")
+
+# 실제로 요청하는 scope 묶음. 개발자센터 앱에 등록된 권한과 어긋나면 인증이
+# 거부되므로, 여기에 추가할 때는 앱 권한도 함께 확인해야 한다.
+# 쓰지 않는 권한은 요청하지 않는다 — 토큰이 유출돼도 피해 범위를 좁히기 위함.
+DEFAULT_SCOPES: tuple[str, ...] = PRODUCT_SCOPES
+
+DEFAULT_API_VERSION = "2026-03-01"
+
+
+def _env(name: str, default: str = "") -> str:
+    value = os.getenv(name, "").strip()
+    return value if value else default
+
+
+@dataclass(frozen=True)
+class Cafe24Config:
+    mall_id: str
+    client_id: str
+    client_secret: str
+    redirect_uri: str
+    api_version: str
+    token_secret: str
+    scopes: tuple[str, ...]
+    # 쇼핑몰 표시 주소(고객이 보는 도메인). 커스텀 도메인은 mall_id 로 알 수 없어
+    # 환경변수로 받는다. 미설정 시 카페24 기본 도메인으로 대체한다.
+    shop_url: str = ""
+
+    @property
+    def configured(self) -> bool:
+        """OAuth 를 시작할 수 있는 최소 조건."""
+        return bool(self.mall_id and self.client_id and self.client_secret and self.redirect_uri)
+
+    @property
+    def missing(self) -> list[str]:
+        """설정 안내 화면에 표시할 미설정 환경변수 이름들."""
+        pairs = (
+            ("CAFE24_MALL_ID", self.mall_id),
+            ("CAFE24_CLIENT_ID", self.client_id),
+            ("CAFE24_CLIENT_SECRET", self.client_secret),
+            ("CAFE24_REDIRECT_URI", self.redirect_uri),
+            ("CAFE24_TOKEN_SECRET", self.token_secret),
+        )
+        return [name for name, value in pairs if not value]
+
+    @property
+    def api_base(self) -> str:
+        return f"https://{self.mall_id}.cafe24api.com/api/v2"
+
+    @property
+    def scope_param(self) -> str:
+        return ",".join(self.scopes)
+
+    @property
+    def shop_base(self) -> str:
+        """고객이 보는 쇼핑몰 주소(끝 슬래시 없음).
+
+        `CAFE24_SHOP_URL` 이 없으면 카페24 기본 도메인을 쓴다 — 커스텀 도메인을
+        모르더라도 항상 유효한 주소가 나온다.
+        """
+        url = (self.shop_url or "").strip().rstrip("/")
+        if url:
+            return url if "://" in url else f"https://{url}"
+        return f"https://{self.mall_id}.cafe24.com" if self.mall_id else ""
+
+    def product_url(self, product_no: int | str) -> str:
+        """상품 상세페이지 다이렉트 주소."""
+        base = self.shop_base
+        return f"{base}/product/detail.html?product_no={product_no}" if base else ""
+
+
+def load_config(*, scopes: tuple[str, ...] = DEFAULT_SCOPES) -> Cafe24Config:
+    """환경변수에서 설정을 읽는다. 값이 없어도 예외를 던지지 않는다.
+
+    미설정 판단은 호출부가 `configured` / `missing` 으로 한다
+    (앱 기동을 막지 않기 위해 — 다른 모듈과 동일한 정책).
+    """
+    return Cafe24Config(
+        mall_id=_env("CAFE24_MALL_ID"),
+        client_id=_env("CAFE24_CLIENT_ID"),
+        client_secret=_env("CAFE24_CLIENT_SECRET"),
+        redirect_uri=_env("CAFE24_REDIRECT_URI"),
+        api_version=_env("CAFE24_API_VERSION", DEFAULT_API_VERSION),
+        token_secret=_env("CAFE24_TOKEN_SECRET"),
+        scopes=scopes,
+        shop_url=_env("CAFE24_SHOP_URL"),
+    )

app/integrations/cafe24/crypto.py

@@ -0,0 +1,51 @@
+"""토큰 암호화 — Fernet(AES-128-CBC + HMAC).
+
+DB 덤프가 유출돼도 access/refresh token 이 평문으로 남지 않게 한다.
+키는 .env 의 CAFE24_TOKEN_SECRET 하나이며, 임의 길이 문자열을 받아
+SHA-256 으로 32바이트를 만든 뒤 Fernet 키 형식으로 변환한다
+(운영자가 `openssl rand -hex 32` 같은 익숙한 방식을 그대로 쓰게 하려는 것).
+
+⚠️ CAFE24_TOKEN_SECRET 을 바꾸면 기존 저장 토큰은 복호화할 수 없다.
+   그 경우 관리자 화면에서 카페24 재연결(재인증)을 하면 된다.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+
+from .errors import Cafe24ConfigError
+
+
+def _fernet(secret: str):
+    from cryptography.fernet import Fernet  # 지연 import
+
+    if not (secret or "").strip():
+        raise Cafe24ConfigError(
+            "CAFE24_TOKEN_SECRET 환경변수가 설정되지 않았습니다. "
+            "openssl rand -hex 32 로 값을 만들어 .env 에 넣고 컨테이너를 재기동하세요."
+        )
+    digest = hashlib.sha256(secret.strip().encode("utf-8")).digest()
+    return Fernet(base64.urlsafe_b64encode(digest))
+
+
+def encrypt(value: str, *, secret: str) -> str:
+    """평문 → 암호문. 빈 문자열은 그대로 둔다(미연결 상태 표현)."""
+    if not value:
+        return ""
+    return _fernet(secret).encrypt(value.encode("utf-8")).decode("ascii")
+
+
+def decrypt(value: str, *, secret: str) -> str:
+    """암호문 → 평문. 키가 바뀌었거나 손상되면 Cafe24ConfigError."""
+    if not value:
+        return ""
+    from cryptography.fernet import InvalidToken  # 지연 import
+
+    try:
+        return _fernet(secret).decrypt(value.encode("ascii")).decode("utf-8")
+    except InvalidToken:
+        raise Cafe24ConfigError(
+            "저장된 카페24 토큰을 복호화하지 못했습니다. "
+            "CAFE24_TOKEN_SECRET 이 변경되었을 수 있습니다. 카페24 재연결이 필요합니다."
+        ) from None

app/integrations/cafe24/errors.py

@@ -0,0 +1,45 @@
+"""카페24 연동 공통 예외.
+
+라우터/서비스는 httpx 예외를 직접 다루지 않고 여기 정의된 타입만 잡는다.
+모든 메시지는 사용자에게 그대로 노출될 수 있으므로 토큰/시크릿을 담지 않는다.
+"""
+
+from __future__ import annotations
+
+
+class Cafe24Error(Exception):
+    """카페24 연동 최상위 예외."""
+
+
+class Cafe24ConfigError(Cafe24Error):
+    """CAFE24_* 환경변수 미설정 등 설정 문제."""
+
+
+class Cafe24AuthError(Cafe24Error):
+    """인증 실패 — 토큰 없음/만료/refresh 불가. 재인증이 필요하다."""
+
+    def __init__(self, message: str, *, needs_reauth: bool = False):
+        super().__init__(message)
+        self.needs_reauth = needs_reauth
+
+
+class Cafe24RateLimitError(Cafe24Error):
+    """429 Too Many Requests. retry_after 초 뒤 재시도 가능."""
+
+    def __init__(self, message: str, *, retry_after: float = 1.0):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class Cafe24ApiError(Cafe24Error):
+    """그 외 API 오류(4xx/5xx). status 로 재시도 가능 여부를 판단한다."""
+
+    def __init__(self, message: str, *, status: int = 0, endpoint: str = ""):
+        super().__init__(message)
+        self.status = status
+        self.endpoint = endpoint
+
+    @property
+    def retryable(self) -> bool:
+        """5xx 와 타임아웃(status=0)만 재시도 대상. 4xx 는 고쳐야 할 요청."""
+        return self.status == 0 or self.status >= 500

app/integrations/cafe24/oauth.py

@@ -0,0 +1,145 @@
+"""카페24 OAuth 2.0 (Authorization Code) — URL 생성 / 토큰 발급 / 갱신.
+
+토큰 저장은 여기서 하지 않는다(tokens.TokenService 담당). 이 모듈은 순수하게
+카페24 인증 엔드포인트와만 대화한다.
+
+카페24 토큰 응답의 만료시각(`expires_at`, `refresh_token_expires_at`)은
+타임존 표기가 없는 KST 문자열이므로 KST 를 붙여 aware datetime 으로 만든다.
+"""
+
+from __future__ import annotations
+
+import base64
+import secrets
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from urllib.parse import urlencode
+
+import httpx
+
+from app.timezone import KST, now_kst
+
+from .config import Cafe24Config
+from .errors import Cafe24AuthError, Cafe24ConfigError
+
+TOKEN_TIMEOUT = 20.0
+
+
+@dataclass(frozen=True)
+class TokenBundle:
+    """카페24가 돌려준 토큰 한 벌 (평문 — 저장 직전에 암호화된다)."""
+
+    access_token: str
+    refresh_token: str
+    access_token_expires_at: datetime
+    refresh_token_expires_at: datetime | None
+    scopes: str
+
+
+def new_state() -> str:
+    """CSRF 방어용 state. 세션에 넣어두고 콜백에서 대조한다."""
+    return secrets.token_urlsafe(24)
+
+
+def build_authorize_url(config: Cafe24Config, *, state: str) -> str:
+    if not config.configured:
+        raise Cafe24ConfigError(
+            "카페24 설정이 없습니다. 미설정 항목: " + ", ".join(config.missing)
+        )
+    query = urlencode(
+        {
+            "response_type": "code",
+            "client_id": config.client_id,
+            "redirect_uri": config.redirect_uri,
+            "scope": config.scope_param,
+            "state": state,
+        }
+    )
+    return f"{config.api_base}/oauth/authorize?{query}"
+
+
+def _basic_auth_header(config: Cafe24Config) -> str:
+    raw = f"{config.client_id}:{config.client_secret}".encode("utf-8")
+    return "Basic " + base64.b64encode(raw).decode("ascii")
+
+
+def _parse_expiry(value: str | None, *, fallback_seconds: int) -> datetime:
+    """'2026-08-20T14:00:00.000' → KST aware datetime. 실패 시 fallback."""
+    text = (value or "").strip()
+    if text:
+        try:
+            parsed = datetime.fromisoformat(text)
+            return parsed if parsed.tzinfo else parsed.replace(tzinfo=KST)
+        except ValueError:
+            pass
+    return now_kst() + timedelta(seconds=fallback_seconds)
+
+
+def _to_bundle(payload: dict) -> TokenBundle:
+    access = (payload.get("access_token") or "").strip()
+    refresh = (payload.get("refresh_token") or "").strip()
+    if not access:
+        raise Cafe24AuthError("카페24 응답에 access_token 이 없습니다.", needs_reauth=True)
+
+    scopes = payload.get("scopes")
+    if isinstance(scopes, list):
+        scope_text = ",".join(str(s) for s in scopes)
+    else:
+        scope_text = str(scopes or "")
+
+    return TokenBundle(
+        access_token=access,
+        refresh_token=refresh,
+        # access token 은 통상 2시간, refresh token 은 2주.
+        access_token_expires_at=_parse_expiry(payload.get("expires_at"), fallback_seconds=7200),
+        refresh_token_expires_at=(
+            _parse_expiry(payload.get("refresh_token_expires_at"), fallback_seconds=1209600)
+            if refresh
+            else None
+        ),
+        scopes=scope_text,
+    )
+
+
+def _post_token(config: Cafe24Config, data: dict[str, str]) -> TokenBundle:
+    url = f"{config.api_base}/oauth/token"
+    headers = {
+        "Authorization": _basic_auth_header(config),
+        "Content-Type": "application/x-www-form-urlencoded",
+    }
+    try:
+        with httpx.Client(timeout=TOKEN_TIMEOUT) as client:
+            response = client.post(url, headers=headers, data=data)
+    except httpx.HTTPError as exc:
+        # 예외 문자열에 Authorization 헤더가 들어가지 않도록 타입명만 남긴다.
+        raise Cafe24AuthError(f"카페24 인증 서버에 연결하지 못했습니다. ({type(exc).__name__})") from None
+
+    if response.status_code != 200:
+        # 400/401 = 코드/리프레시토큰 무효 → 재인증 필요.
+        raise Cafe24AuthError(
+            f"카페24 토큰 요청이 거부되었습니다. (HTTP {response.status_code})",
+            needs_reauth=response.status_code in (400, 401),
+        )
+    return _to_bundle(response.json())
+
+
+def exchange_code(config: Cafe24Config, *, code: str) -> TokenBundle:
+    """authorization code → 최초 토큰."""
+    return _post_token(
+        config,
+        {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": config.redirect_uri,
+        },
+    )
+
+
+def refresh_tokens(config: Cafe24Config, *, refresh_token: str) -> TokenBundle:
+    """refresh token → 새 토큰 한 벌 (refresh token 도 함께 회전된다)."""
+    if not (refresh_token or "").strip():
+        raise Cafe24AuthError("저장된 refresh token 이 없습니다.", needs_reauth=True)
+    return _post_token(
+        config,
+        {"grant_type": "refresh_token", "refresh_token": refresh_token},
+    )

app/integrations/cafe24/products.py

@@ -0,0 +1,254 @@
+"""카페24 상품 엔드포인트 래퍼.
+
+전송/재시도/인증은 Cafe24Client 가 담당하고, 여기서는 경로와 payload 모양만
+안다. 향후 주문관리는 같은 클라이언트로 `orders.py` 를 추가하면 된다.
+
+상세설명은 **별도 리소스가 아니다.** 실제 쇼핑몰(miraskitchen)에 확인한 결과
+`/admin/products/{no}/description` 은 존재하지 않는다(`No API found.`).
+상세설명은 상품 리소스의 필드로 읽고 쓴다.
+
+    GET  /admin/products/{no}   → description · mobile_description ·
+                                  separated_mobile_description
+    PUT  /admin/products/{no}   → {"request": {"description": ...}}
+
+목록 API(`/admin/products`) 응답에는 description 이 **없다**. 그래서 상세설명은
+상품 1건씩 조회해야 한다(목록 화면에서 미리보기를 뿌리지 않는 이유).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .client import Cafe24Client
+
+# 카페24 상품 목록 API 의 1회 최대 조회 수
+PAGE_LIMIT = 100
+
+
+def _flag(value: Any, *, default: bool = True) -> bool:
+    """카페24는 boolean 을 'T'/'F' 문자열로 준다."""
+    if isinstance(value, bool):
+        return value
+    text = str(value or "").strip().upper()
+    if text in ("T", "TRUE", "Y", "1"):
+        return True
+    if text in ("F", "FALSE", "N", "0"):
+        return False
+    return default
+
+
+def count_products(client: Cafe24Client, *, product_name: str = "") -> int:
+    params: dict[str, Any] = {}
+    if product_name:
+        params["product_name"] = product_name
+    payload = client.get("/admin/products/count", params=params)
+    try:
+        return int(payload.get("count") or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def list_products(
+    client: Cafe24Client,
+    *,
+    limit: int = PAGE_LIMIT,
+    offset: int = 0,
+    product_name: str = "",
+    product_no: int | None = None,
+) -> list[dict[str, Any]]:
+    """상품 목록 1페이지. 검색어가 있으면 상품명 부분일치로 조회한다."""
+    params: dict[str, Any] = {
+        "limit": max(1, min(int(limit), PAGE_LIMIT)),
+        "offset": max(0, int(offset)),
+    }
+    if product_name:
+        params["product_name"] = product_name
+    if product_no:
+        params["product_no"] = int(product_no)
+    payload = client.get("/admin/products", params=params)
+    products = payload.get("products")
+    return products if isinstance(products, list) else []
+
+
+def list_all_products(
+    client: Cafe24Client,
+    *,
+    product_name: str = "",
+    max_items: int = 1000,
+) -> tuple[list[dict[str, Any]], bool]:
+    """전체 상품을 페이지를 넘겨가며 모두 가져온다.
+
+    2분할 화면의 왼쪽 목록은 페이지 없이 한 번에 보여주고 필터·정렬을 브라우저에서
+    처리한다. 그래야 "진열중만" 같은 필터가 전체 기준으로 정확해진다
+    (한 페이지만 받아 걸러내면 다음 페이지의 해당 상품이 빠진다).
+
+    반환: (상품 목록, 상한에 걸려 잘렸는지)
+    상품이 max_items 를 넘으면 거기서 멈춘다 — 무한 호출로 API 제한에 걸리는
+    것을 막기 위한 안전장치다(현재 쇼핑몰 87개, 1회 100개 조회).
+    """
+    collected: list[dict[str, Any]] = []
+    while len(collected) < max_items:
+        want = min(PAGE_LIMIT, max_items - len(collected))
+        batch = list_products(
+            client,
+            limit=want,
+            offset=len(collected),
+            product_name=product_name,
+        )
+        collected.extend(batch)
+        if len(batch) < want:
+            return collected, False  # 요청한 만큼 못 받았다 = 마지막 페이지
+        if len(collected) >= max_items:
+            return collected, True  # 상한에서 멈췄다 — 뒤에 더 있을 수 있다
+    return collected, False
+
+
+def get_product(client: Cafe24Client, product_no: int) -> dict[str, Any]:
+    """상품 1건 상세. 이 응답에 상세설명 필드까지 들어 있다."""
+    no = int(product_no)
+    payload = client.get(f"/admin/products/{no}", product_no=no)
+    product = payload.get("product")
+    return product if isinstance(product, dict) else {}
+
+
+@dataclass(frozen=True)
+class Descriptions:
+    """상품 1건의 상세설명 묶음. 카페24가 언제나 source of truth 다."""
+
+    product_no: int
+    product_name: str
+    description: str
+    mobile_description: str
+    # separated_mobile_description = 'T' 면 PC/모바일 상세설명을 따로 쓴다.
+    # 'F' 면 모바일도 PC 값을 쓰므로 수정 시 두 필드를 함께 맞춰야 한다.
+    separated_mobile: bool
+
+    @property
+    def mobile_differs(self) -> bool:
+        return self.mobile_description != self.description
+
+
+def descriptions_from_product(raw: dict[str, Any]) -> Descriptions:
+    """`get_product` 응답 dict → Descriptions."""
+    try:
+        product_no = int(raw.get("product_no") or 0)
+    except (TypeError, ValueError):
+        product_no = 0
+    return Descriptions(
+        product_no=product_no,
+        product_name=str(raw.get("product_name") or ""),
+        description=str(raw.get("description") or ""),
+        mobile_description=str(raw.get("mobile_description") or ""),
+        separated_mobile=_flag(raw.get("separated_mobile_description"), default=False),
+    )
+
+
+def fetch_descriptions(client: Cafe24Client, product_no: int) -> Descriptions:
+    """상품의 현재 상세설명. 로컬 DB 의 마지막 버전을 현재값으로 가정하지 않는다."""
+    return descriptions_from_product(get_product(client, product_no))
+
+
+def _flag_value(flag: bool) -> str:
+    """카페24는 boolean 을 'T'/'F' 문자열로 받는다."""
+    return "T" if flag else "F"
+
+
+def build_update_payload(
+    *,
+    description: str | None = None,
+    mobile_description: str | None = None,
+    product_name: str | None = None,
+    display: bool | None = None,
+    selling: bool | None = None,
+    shop_no: int | None = None,
+) -> dict[str, Any]:
+    """상품 수정 PUT body. 준 필드만 바뀌고 나머지는 유지된다(부분 수정).
+
+    `None` 인 항목은 payload 에 넣지 않는다 = 그 필드를 건드리지 않는다.
+    예약에서 "진열만 켜기"처럼 상세설명 없이 상태만 바꾸는 경우가 있으므로
+    description 도 생략할 수 있다.
+    """
+    request: dict[str, Any] = {}
+    if description is not None:
+        request["description"] = description
+    if product_name is not None:
+        request["product_name"] = product_name
+    if mobile_description is not None:
+        request["mobile_description"] = mobile_description
+    if display is not None:
+        request["display"] = _flag_value(display)
+    if selling is not None:
+        request["selling"] = _flag_value(selling)
+    payload: dict[str, Any] = {"request": request}
+    if shop_no:
+        payload["shop_no"] = int(shop_no)
+    return payload
+
+
+def update_product(
+    client: Cafe24Client,
+    product_no: int,
+    *,
+    description: str | None = None,
+    mobile_description: str | None = None,
+    product_name: str | None = None,
+    display: bool | None = None,
+    selling: bool | None = None,
+    shop_no: int | None = None,
+) -> dict[str, Any]:
+    """상품 부분 수정. 상세설명·상품명·진열·판매를 한 번의 호출로 바꿀 수 있다.
+
+    바꿀 것이 하나도 없으면 호출하지 않고 빈 dict 를 돌려준다.
+
+    ⚠️ 상세설명을 바꿀 때는 쓰기 직전 카페24 현재 HTML 을 다시 읽어 BACKUP
+       revision 을 남길 것(`docs/CAFE24_MODULE.md` 규칙). 이 함수는 백업하지 않는다.
+    """
+    payload = build_update_payload(
+        description=description,
+        mobile_description=mobile_description,
+        product_name=product_name,
+        display=display,
+        selling=selling,
+        shop_no=shop_no,
+    )
+    if not payload["request"]:
+        return {}
+    no = int(product_no)
+    response = client.put(f"/admin/products/{no}", json=payload, product_no=no)
+    product = response.get("product")
+    return product if isinstance(product, dict) else response
+
+
+def update_descriptions(
+    client: Cafe24Client,
+    product_no: int,
+    *,
+    description: str,
+    mobile_description: str | None = None,
+    shop_no: int | None = None,
+) -> dict[str, Any]:
+    """상세설명만 교체하는 지름길. 실제 전송은 `update_product` 가 한다."""
+    return update_product(
+        client,
+        product_no,
+        description=description,
+        mobile_description=mobile_description,
+        shop_no=shop_no,
+    )
+
+
+def normalize_product(raw: dict[str, Any]) -> dict[str, Any]:
+    """카페24 상품 dict → 캐시 테이블(cafe24_products) 컬럼 모양으로 정규화."""
+    try:
+        product_no = int(raw.get("product_no") or 0)
+    except (TypeError, ValueError):
+        product_no = 0
+
+    return {
+        "product_no": product_no,
+        "product_code": str(raw.get("product_code") or ""),
+        "product_name": str(raw.get("product_name") or ""),
+        "display": _flag(raw.get("display")),
+        "selling": _flag(raw.get("selling")),
+    }

app/integrations/cafe24/tokens.py

@@ -0,0 +1,185 @@
+"""토큰 수명 관리 — 저장/복호화/만료판정/자동 갱신.
+
+저장소(repo)는 duck typing 으로 주입한다. 실제 구현은
+`app/modules/cafe24/db.py` 의 Cafe24Store 이며, 아래 3개만 있으면 된다.
+
+    repo.get_token_row(mall_id)  -> dict | None      (암호문 그대로)
+    repo.save_token_row(**fields)-> None             (UPSERT)
+    repo.token_lock(mall_id)     -> contextmanager   (FOR UPDATE, .row / .save())
+
+`token_lock` 은 web 컨테이너와 worker 컨테이너가 동시에 refresh 를 시도해도
+한쪽만 카페24에 요청하도록 행 잠금을 건다(카페24는 refresh token 을 회전시키므로
+동시 refresh 시 한쪽 토큰이 무효화된다).
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import timedelta
+from typing import Any
+
+from app.timezone import KST, now_kst
+
+from .config import Cafe24Config
+from .crypto import decrypt, encrypt
+from .errors import Cafe24AuthError
+from .oauth import TokenBundle, refresh_tokens
+
+logger = logging.getLogger("cafe24.tokens")
+
+# 만료 몇 초 전부터 미리 갱신할지 (네트워크 지연 여유)
+REFRESH_MARGIN = timedelta(seconds=120)
+
+
+class TokenService:
+    def __init__(self, repo: Any, config: Cafe24Config):
+        self._repo = repo
+        self._config = config
+
+    # ────────────────────────────────────────────────────────────
+    # 저장
+    # ────────────────────────────────────────────────────────────
+    def save_bundle(self, bundle: TokenBundle, *, connected_by: str = "") -> None:
+        """최초 인증/재인증 후 토큰 저장. 토큰은 암호화해서 넣는다."""
+        secret = self._config.token_secret
+        self._repo.save_token_row(
+            mall_id=self._config.mall_id,
+            access_token=encrypt(bundle.access_token, secret=secret),
+            refresh_token=encrypt(bundle.refresh_token, secret=secret),
+            access_token_expires_at=bundle.access_token_expires_at,
+            refresh_token_expires_at=bundle.refresh_token_expires_at,
+            scopes=bundle.scopes,
+            last_refreshed_at=now_kst(),
+            last_error="",
+            connected_by=connected_by,
+        )
+
+    # ────────────────────────────────────────────────────────────
+    # 조회
+    # ────────────────────────────────────────────────────────────
+    def _aware(self, value: Any):
+        """DB 에서 온 datetime 을 KST aware 로 정규화.
+
+        컬럼이 timestamptz 라 psycopg 는 UTC 로 돌려준다. 시각 자체는 같지만
+        화면에 `+00:00` 으로 보이므로 KST 로 변환해 다른 모듈과 표기를 맞춘다.
+        """
+        if value is None:
+            return None
+        aware = value if value.tzinfo else value.replace(tzinfo=KST)
+        return aware.astimezone(KST)
+
+    def status(self) -> dict[str, Any]:
+        """관리자 화면용 연결 상태. 토큰 값 자체는 절대 넣지 않는다."""
+        if not self._config.configured:
+            return {
+                "connected": False,
+                "mall_id": self._config.mall_id,
+                "missing": self._config.missing,
+                "needs_reauth": False,
+                "reason": "환경변수 미설정",
+            }
+
+        row = self._repo.get_token_row(self._config.mall_id)
+        if not row or not row.get("access_token"):
+            return {
+                "connected": False,
+                "mall_id": self._config.mall_id,
+                "missing": self._config.missing,
+                "needs_reauth": True,
+                "reason": "아직 카페24 연결(인증)을 하지 않았습니다.",
+            }
+
+        access_exp = self._aware(row.get("access_token_expires_at"))
+        refresh_exp = self._aware(row.get("refresh_token_expires_at"))
+        now = now_kst()
+        refresh_dead = bool(refresh_exp and now >= refresh_exp)
+
+        return {
+            "connected": not refresh_dead,
+            "mall_id": row.get("mall_id") or self._config.mall_id,
+            "missing": self._config.missing,
+            "needs_reauth": refresh_dead,
+            "reason": "refresh token 이 만료되었습니다. 재연결이 필요합니다." if refresh_dead else "",
+            "scopes": row.get("scopes") or "",
+            "access_token_expires_at": access_exp.isoformat(timespec="seconds") if access_exp else "",
+            "refresh_token_expires_at": refresh_exp.isoformat(timespec="seconds") if refresh_exp else "",
+            "access_expired": bool(access_exp and now >= access_exp),
+            "last_refreshed_at": (
+                self._aware(row.get("last_refreshed_at")).isoformat(timespec="seconds")
+                if row.get("last_refreshed_at")
+                else ""
+            ),
+            "last_error": row.get("last_error") or "",
+            "connected_by": row.get("connected_by") or "",
+        }
+
+    # ────────────────────────────────────────────────────────────
+    # 사용 (Cafe24Client 가 호출)
+    # ────────────────────────────────────────────────────────────
+    def get_access_token(self) -> str:
+        """유효한 access token. 만료(임박)면 잠금 걸고 1회 갱신 후 반환."""
+        mall_id = self._config.mall_id
+        row = self._repo.get_token_row(mall_id)
+        if not row or not row.get("access_token"):
+            raise Cafe24AuthError(
+                "카페24에 연결되어 있지 않습니다. 시스템 → 카페24 연결에서 인증하세요.",
+                needs_reauth=True,
+            )
+
+        expires_at = self._aware(row.get("access_token_expires_at"))
+        if expires_at and now_kst() < expires_at - REFRESH_MARGIN:
+            return decrypt(row["access_token"], secret=self._config.token_secret)
+
+        return self._refresh_locked(mall_id)
+
+    def force_expire(self) -> None:
+        """access token 만료시각을 과거로 밀어 다음 호출에서 반드시 갱신하게 한다.
+
+        서버가 만료 전에 토큰을 무효화해 401 이 온 경우(Cafe24Client)에 쓴다.
+        """
+        self._repo.save_token_row(
+            mall_id=self._config.mall_id,
+            access_token_expires_at=now_kst() - timedelta(seconds=1),
+        )
+
+    def _refresh_locked(self, mall_id: str) -> str:
+        """행 잠금 안에서 갱신. 잠금 대기 중 다른 프로세스가 이미 갱신했으면 그 값 사용."""
+        secret = self._config.token_secret
+        with self._repo.token_lock(mall_id) as handle:
+            row = handle.row
+            if not row:
+                raise Cafe24AuthError("카페24 토큰이 없습니다.", needs_reauth=True)
+
+            expires_at = self._aware(row.get("access_token_expires_at"))
+            if expires_at and now_kst() < expires_at - REFRESH_MARGIN:
+                # 잠금 대기 사이에 다른 프로세스가 갱신 완료.
+                return decrypt(row["access_token"], secret=secret)
+
+            refresh_exp = self._aware(row.get("refresh_token_expires_at"))
+            if refresh_exp and now_kst() >= refresh_exp:
+                handle.save(last_error="refresh token 만료 — 재인증 필요")
+                raise Cafe24AuthError(
+                    "카페24 refresh token 이 만료되었습니다. 시스템 → 카페24 연결에서 재인증하세요.",
+                    needs_reauth=True,
+                )
+
+            try:
+                bundle = refresh_tokens(
+                    self._config,
+                    refresh_token=decrypt(row.get("refresh_token") or "", secret=secret),
+                )
+            except Cafe24AuthError as exc:
+                handle.save(last_error=str(exc))
+                raise
+
+            logger.info("카페24 access token 갱신 완료 (mall_id=%s)", mall_id)
+            handle.save(
+                access_token=encrypt(bundle.access_token, secret=secret),
+                refresh_token=encrypt(bundle.refresh_token, secret=secret),
+                access_token_expires_at=bundle.access_token_expires_at,
+                refresh_token_expires_at=bundle.refresh_token_expires_at,
+                scopes=bundle.scopes,
+                last_refreshed_at=now_kst(),
+                last_error="",
+            )
+            return bundle.access_token

app/mail.py

@@ -0,0 +1,97 @@
+"""SMTP 메일 발송 유틸 (표준 라이브러리 smtplib 만 사용 — 추가 의존성 없음).
+
+모든 모듈이 공용으로 쓰는 가벼운 발송기. 현재는 프로젝트 관리 모듈의
+관리자 알림(업무 배정/완료)에 사용한다.
+
+환경변수:
+  SMTP_HOST        SMTP 서버 호스트 (미설정 시 발송 비활성 — 조용히 skip)
+  SMTP_PORT        포트 (기본 587)
+  SMTP_USER        로그인 사용자 (없으면 익명)
+  SMTP_PASSWORD    로그인 비밀번호
+  SMTP_FROM        보내는 사람 (미설정 시 SMTP_USER)
+  SMTP_TLS         "true"(STARTTLS, 기본) | "ssl"(SMTPS/465) | "false"(평문)
+  SMTP_TIMEOUT     연결 타임아웃 초 (기본 10)
+
+설계 원칙:
+  - 미설정/실패해도 앱이 죽지 않는다. 로그만 남기고 False 반환.
+  - 호출부는 FastAPI BackgroundTasks 로 비동기 호출 권장(요청 지연 방지).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import smtplib
+from email.message import EmailMessage
+from email.utils import formataddr
+
+logger = logging.getLogger("app.mail")
+
+
+def _env(name: str, default: str = "") -> str:
+    return (os.getenv(name, "") or "").strip() or default
+
+
+def mail_enabled() -> bool:
+    """SMTP_HOST 가 있으면 발송 가능으로 본다."""
+    return bool(_env("SMTP_HOST"))
+
+
+def send_email(
+    *,
+    to: list[str] | str,
+    subject: str,
+    body: str,
+    html: str | None = None,
+    from_name: str = "DBX ERP",
+) -> bool:
+    """단순 텍스트(+선택 HTML) 메일 1건 발송.
+
+    반환: 성공 True / 비활성·실패 False. 예외를 밖으로 던지지 않는다.
+    """
+    host = _env("SMTP_HOST")
+    if not host:
+        logger.info("SMTP 미설정 — 메일 발송 skip (subject=%s)", subject)
+        return False
+
+    recipients = [to] if isinstance(to, str) else list(to)
+    recipients = [r.strip() for r in recipients if r and r.strip()]
+    if not recipients:
+        logger.info("수신자 없음 — 메일 발송 skip (subject=%s)", subject)
+        return False
+
+    port = int(_env("SMTP_PORT", "587"))
+    user = _env("SMTP_USER")
+    password = _env("SMTP_PASSWORD")
+    sender = _env("SMTP_FROM", user or "no-reply@dbxcorp.co.kr")
+    mode = _env("SMTP_TLS", "true").lower()
+    timeout = int(_env("SMTP_TIMEOUT", "10"))
+
+    msg = EmailMessage()
+    msg["Subject"] = subject
+    msg["From"] = formataddr((from_name, sender))
+    msg["To"] = ", ".join(recipients)
+    msg.set_content(body)
+    if html:
+        msg.add_alternative(html, subtype="html")
+
+    try:
+        if mode == "ssl":
+            with smtplib.SMTP_SSL(host, port, timeout=timeout) as server:
+                if user:
+                    server.login(user, password)
+                server.send_message(msg)
+        else:
+            with smtplib.SMTP(host, port, timeout=timeout) as server:
+                server.ehlo()
+                if mode != "false":
+                    server.starttls()
+                    server.ehlo()
+                if user:
+                    server.login(user, password)
+                server.send_message(msg)
+        logger.info("메일 발송 완료 → %s (subject=%s)", recipients, subject)
+        return True
+    except Exception as exc:  # noqa: BLE001 — 메일 실패가 앱을 막으면 안 됨
+        logger.warning("메일 발송 실패 (subject=%s): %s", subject, exc)
+        return False

app/main.py

@@ -13,10 +13,18 @@ from jinja2 import ChoiceLoader, FileSystemLoader
 from pydantic import BaseModel
 from starlette.middleware.sessions import SessionMiddleware
 
+from .modules.cafe24 import build_cafe24_store
+from .modules.cafe24 import router as cafe24_router
 from .modules.cupang import build_cupang_store, build_itemcode_reader
 from .modules.cupang import router as cupang_router
+from .modules.dispatch import build_dispatch_store
+from .modules.dispatch import router as dispatch_router
 from .modules.expense import CategoryStore, build_expense_store
 from .modules.expense import router as expense_router
+from .modules.malaysia import build_malaysia_itemcode, build_malaysia_store
+from .modules.malaysia import router as malaysia_router
+from .modules.project import build_project_store
+from .modules.project import router as project_router
 from .modules.vacation import build_vacation_store
 from .modules.vacation import router as vacation_router
 from .store import (
@@ -36,6 +44,10 @@ MODULE_LABELS: dict[str, str] = {
     "expense": "개인경비",
     "vacation": "휴가",
     "cupang": "쿠팡 밀크런",
+    "malaysia": "말레이시아 재고관리",
+    "dispatch": "말레이시아 배송",
+    "project": "프로젝트 관리",
+    "cafe24": "카페24 상품관리",
     "expense_approver": "개인경비",
     "vacation_approver": "휴가",
 }
@@ -108,6 +120,10 @@ _MODULE_TEMPLATE_DIRS = [
     BASE_DIR / "modules" / "expense" / "templates",
     BASE_DIR / "modules" / "cupang" / "templates",
     BASE_DIR / "modules" / "vacation" / "templates",
+    BASE_DIR / "modules" / "malaysia" / "templates",
+    BASE_DIR / "modules" / "dispatch" / "templates",
+    BASE_DIR / "modules" / "project" / "templates",
+    BASE_DIR / "modules" / "cafe24" / "templates",
 ]
 templates = Jinja2Templates(directory=str(BASE_DIR / "templates"))
 templates.env.loader = ChoiceLoader(
@@ -117,6 +133,18 @@ templates.env.loader = ChoiceLoader(
     ]
 )
 
+# dispatch 모듈 템플릿 필터: 배송사 로고 URL / 송장 조회 딥링크.
+#   {{ provider | courier_logo }}  ·  {{ tracking | courier_track(provider) }}
+from .modules.dispatch.store import (  # noqa: E402
+    courier_logo_url as _courier_logo_url,
+)
+from .modules.dispatch.store import (  # noqa: E402
+    courier_tracking_url as _courier_tracking_url,
+)
+
+templates.env.filters["courier_logo"] = _courier_logo_url
+templates.env.filters["courier_track"] = _courier_tracking_url
+
 oauth = build_google_oauth()
 user_store = UserStore(DATA_DIR / "users.json")
 
@@ -135,11 +163,29 @@ app.state.cupang_store = build_cupang_store(dsn=env("CUPANG_DB_URL") or None)
 app.state.itemcode_reader = build_itemcode_reader()
 # 휴가 관리: VACATION_DB_URL 없으면 store=None(라우터가 "설정 필요" 안내).
 app.state.vacation_store = build_vacation_store(dsn=env("VACATION_DB_URL") or None)
+# 말레이시아 재고관리: MALAYSIA_STOCK_DB_URL 없으면 store=None(라우터가 "설정 필요" 안내).
+# 상품명은 위 itemcode_reader(읽기 전용) 재사용.
+app.state.malaysia_store = build_malaysia_store(dsn=env("MALAYSIA_STOCK_DB_URL") or None)
+# 세트 BOM 은 itemcode_db(set_components)에서 읽는다(ITEMCODE_DB_URL 재사용).
+app.state.malaysia_itemcode = build_malaysia_itemcode()
+# 말레이시아 배송(TikTok 출고): DISPATCH_DB_URL 없으면 store=None(라우터가 "설정 필요" 안내).
+# 업로드 원본은 DATA_DIR/dispatch/ 아래 저장(개인정보는 저장하지 않음).
+app.state.dispatch_store = build_dispatch_store(dsn=env("DISPATCH_DB_URL") or None)
+# 프로젝트 관리(아사나식): PROJECT_DB_URL 없으면 store=None(라우터가 "설정 필요" 안내).
+# 메일 알림은 SMTP_* 환경변수 기반(app/mail.py). 미설정 시 조용히 skip.
+app.state.project_store = build_project_store(dsn=env("PROJECT_DB_URL") or None)
+# 카페24 상품관리: CAFE24_DB_URL 없으면 store=None(라우터가 "설정 필요" 안내).
+# 카페24 API 호출/토큰은 app/integrations/cafe24 공통 계층(CAFE24_* 환경변수).
+app.state.cafe24_store = build_cafe24_store(dsn=env("CAFE24_DB_URL") or None)
 
 # 모듈 라우터 등록 — 신규 모듈 추가 시 여기 한 줄.
 app.include_router(expense_router)
 app.include_router(cupang_router)
 app.include_router(vacation_router)
+app.include_router(malaysia_router)
+app.include_router(dispatch_router)
+app.include_router(project_router)
+app.include_router(cafe24_router)
 
 
 def public_url_for(request: Request, route_name: str) -> str:
@@ -282,6 +328,46 @@ def _menu_items_for(user_rec: dict[str, Any]) -> list[dict[str, Any]]:
             "status": "ready",
             "category": "관리",
         },
+        {
+            "key": "malaysia",
+            "title": "말레이시아 재고관리",
+            "subtitle": "Malaysia Stock",
+            "description": "말레이시아 창고 입출고·세트 BOM·일일 재고조사를 관리합니다.",
+            "url": "/malaysia/",
+            "health_url": "/malaysia/health",
+            "status": "ready",
+            "category": "운영",
+        },
+        {
+            "key": "dispatch",
+            "title": "말레이시아 배송",
+            "subtitle": "Malaysia Dispatch",
+            "description": "TikTok 출고 파일을 올리면 박스별 작업 리스트·피킹 요약·Kagayaku 전달표를 자동 생성합니다.",
+            "url": "/dispatch/",
+            "health_url": "/dispatch/health",
+            "status": "ready",
+            "category": "운영",
+        },
+        {
+            "key": "project",
+            "title": "프로젝트 관리",
+            "subtitle": "Projects",
+            "description": "프로젝트·서브프로젝트·업무를 달력/타임라인/보드로 관리합니다(아사나식).",
+            "url": "/project/",
+            "health_url": "/project/health",
+            "status": "ready",
+            "category": "관리",
+        },
+        {
+            "key": "cafe24",
+            "title": "카페24 상품관리",
+            "subtitle": "Cafe24 Products",
+            "description": "카페24 관리자에 들어가지 않고 상품 상세페이지를 편집·예약 적용하고 이전 버전으로 되돌립니다.",
+            "url": "/cafe24/",
+            "health_url": "/cafe24/health",
+            "status": "ready",
+            "category": "운영",
+        },
     ]
     allowed = allowed_modules(user_rec)
     for item in items:
@@ -298,6 +384,10 @@ def _icon_svg(name: str) -> str:
         "corm": '<path d="M21 11.5a8.4 8.4 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.4 8.4 0 0 1-3.8-.9L3 21l1.9-5.7a8.4 8.4 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6 8.4 8.4 0 0 1 3.8-.9h.5a8.5 8.5 0 0 1 8 8v.5z"/>',
         "order": '<rect x="3" y="3" width="18" height="18" rx="2"/><line x1="3" y1="9" x2="21" y2="9"/><line x1="9" y1="21" x2="9" y2="9"/>',
         "cupang": '<rect x="3" y="4" width="18" height="18" rx="2"/><line x1="3" y1="10" x2="21" y2="10"/><line x1="8" y1="2" x2="8" y2="6"/><line x1="16" y1="2" x2="16" y2="6"/>',
+        "malaysia": '<path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z"/><polyline points="3.27 6.96 12 12.01 20.73 6.96"/><line x1="12" y1="22.08" x2="12" y2="12"/>',
+        "dispatch": '<rect x="1" y="3" width="15" height="13"/><path d="M16 8h4l3 3v5h-7V8z"/><circle cx="5.5" cy="18.5" r="2.5"/><circle cx="18.5" cy="18.5" r="2.5"/>',
+        "project": '<rect x="3" y="4" width="18" height="16" rx="2"/><line x1="3" y1="9" x2="21" y2="9"/><line x1="8" y1="13" x2="13" y2="13"/><line x1="8" y1="16" x2="11" y2="16"/>',
+        "cafe24": '<rect x="3" y="4" width="18" height="16" rx="2"/><path d="M7 9h10"/><path d="M7 13h7"/><path d="M7 17h4"/>',
         "modules": '<rect x="3" y="3" width="7" height="7"/><rect x="14" y="3" width="7" height="7"/><rect x="3" y="14" width="7" height="7"/><rect x="14" y="14" width="7" height="7"/>',
     }
     body = paths.get(name, paths["modules"])

app/modules/cafe24/__init__.py

@@ -0,0 +1,48 @@
+"""카페24 상품 상세페이지 관리 모듈.
+
+라우터/저장소/순수로직/템플릿을 한 디렉토리에서 관리한다.
+- 라우터: `router.py` (FastAPI APIRouter, prefix=/cafe24) + `routes_*.py`
+- 저장소: `db.py` (cafe24_db / PostgreSQL 전용)
+- 순수 로직: `store.py` (버전/예약 상수, 재시도 규칙, 검증)
+- 템플릿: `templates/cafe24/`
+
+카페24 API 호출은 이 모듈에 두지 않는다. 향후 주문관리 모듈과 공유하기 위해
+`app/integrations/cafe24/` 공통 계층을 쓴다.
+
+데이터 저장은 cafe24_db 전용이다. CAFE24_DB_URL 미설정 시
+build_cafe24_store 는 None 을 반환하고, 라우터가 "설정 필요" 안내 페이지를
+보여준다(앱은 죽지 않음).
+"""
+
+from typing import Any
+
+from . import store
+from .router import router
+from .store import (
+    REVISION_LABELS,
+    REVISION_TYPES,
+    SCHEDULE_STATUS_LABELS,
+    SCHEDULE_STATUSES,
+)
+
+__all__ = [
+    "router",
+    "store",
+    "REVISION_TYPES",
+    "REVISION_LABELS",
+    "SCHEDULE_STATUSES",
+    "SCHEDULE_STATUS_LABELS",
+    "build_cafe24_store",
+]
+
+
+def build_cafe24_store(*, dsn: str | None) -> Any:
+    """CAFE24_DB_URL 이 있으면 Cafe24Store, 없으면 None.
+
+    JSON 폴백을 두지 않는다(운영 데이터 분기 방지). None 이면 라우터가 안내 표시.
+    """
+    if not dsn:
+        return None
+    from .db import Cafe24Store  # 지연 import (개발 환경 deps 없을 수 있음)
+
+    return Cafe24Store(dsn)

app/modules/cafe24/common.py

@@ -0,0 +1,118 @@
+"""카페24 모듈 공용 가드/컨텍스트 헬퍼.
+
+router.py 와 routes_*.py 가 함께 쓴다(순환 import 방지를 위해 분리).
+다른 모듈과 동일한 규칙:
+  - JSON API   → require_user() : 401/403 HTTPException
+  - HTML 페이지 → guard()       : 리다이렉트 / denied.html 응답 반환
+app.main 은 함수 안에서 지연 import 한다(순환 import 방지).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import HTTPException, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+
+MODULE_KEY = "cafe24"
+MODULE_NAME = "카페24 상품관리"
+
+CONFIG_HELP = (
+    "카페24 모듈이 아직 설정되지 않았습니다. "
+    "CAFE24_DB_URL 환경변수를 설정하고 "
+    "scripts/sql/cafe24_db_init.sql 로 cafe24_db 를 초기화한 뒤 "
+    "컨테이너를 재기동하세요."
+)
+
+
+def get_store(request: Request) -> Any:
+    return getattr(request.app.state, "cafe24_store", None)
+
+
+def require_user(request: Request) -> dict[str, Any]:
+    from app.main import get_current_user_record  # noqa: WPS433
+    from app.store import has_module  # noqa: WPS433
+
+    user = get_current_user_record(request)
+    if user is None:
+        raise HTTPException(status_code=401, detail="로그인이 필요합니다.")
+    if not has_module(user, MODULE_KEY):
+        raise HTTPException(status_code=403, detail=f"{MODULE_NAME} 모듈 권한이 없습니다.")
+    return user
+
+
+def require_admin(request: Request) -> dict[str, Any]:
+    """카페24 연결(OAuth)·연결 해제는 관리자만."""
+    from app.store import is_admin  # noqa: WPS433
+
+    user = require_user(request)
+    if not is_admin(user):
+        raise HTTPException(status_code=403, detail="관리자만 카페24 연결을 변경할 수 있습니다.")
+    return user
+
+
+def require_store(request: Request) -> tuple[Any, dict[str, Any]]:
+    """JSON API 용 — store 미설정이면 503."""
+    user = require_user(request)
+    st = get_store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail=CONFIG_HELP)
+    return st, user
+
+
+def render_config_needed(request: Request, user: dict[str, Any]) -> HTMLResponse:
+    from app.main import build_erp_nav, render_template  # noqa: WPS433
+    from app.store import is_admin  # noqa: WPS433
+
+    return render_template(
+        request,
+        "denied.html",
+        {
+            "reason": CONFIG_HELP,
+            "user": user,
+            "is_admin": is_admin(user),
+            "nav_items": build_erp_nav(user, active=MODULE_KEY),
+        },
+        status_code=503,
+    )
+
+
+def guard(request: Request):
+    """로그인+권한+store 점검. 페이지 핸들러 진입부에서 사용.
+
+    반환이 tuple 이면 (store, user), 아니면 그대로 응답으로 돌려준다.
+    """
+    from app.main import get_current_user_record, render_template  # noqa: WPS433
+    from app.store import has_module, is_admin  # noqa: WPS433
+
+    user = get_current_user_record(request)
+    if user is None:
+        return RedirectResponse(url="/login", status_code=303)
+    if not has_module(user, MODULE_KEY):
+        return render_template(
+            request,
+            "denied.html",
+            {
+                "reason": f"{MODULE_NAME} 접근 권한이 없습니다.",
+                "user": user,
+                "is_admin": is_admin(user),
+            },
+            status_code=403,
+        )
+    st = get_store(request)
+    if st is None:
+        return render_config_needed(request, user)
+    return st, user
+
+
+def base_ctx(request: Request, user: dict[str, Any], *, active_tab: str = "") -> dict[str, Any]:
+    from app.main import build_erp_nav  # noqa: WPS433
+    from app.store import is_admin  # noqa: WPS433
+
+    return {
+        "user": user,
+        "is_admin": is_admin(user),
+        "is_super": bool(user.get("is_super_admin")),
+        "nav_items": build_erp_nav(user, active=MODULE_KEY),
+        "active_tab": active_tab,
+    }

app/modules/cafe24/db.py

@@ -0,0 +1,482 @@
+"""cafe24_db PostgreSQL 저장소.
+
+- 드라이버: psycopg 3 (`psycopg[binary,pool]`) — 다른 모듈과 동일 패턴.
+- 연결 정보: 환경변수 `CAFE24_DB_URL`
+  (예: postgresql://cafe24_app:<pwd>@postgres-db:5432/cafe24_db)
+- 스키마는 앱이 만들지 않는다. `scripts/sql/cafe24_db_init.sql` 을 superuser 가
+  사전 적용한다. 앱 계정(cafe24_app)은 CRUD 권한만 받는다.
+- 연결 풀은 lazy open — 부팅 시 DB 가 잠시 끊겨도 컨테이너가 죽지 않게.
+
+토큰 값은 이 계층에 도달하기 전 이미 Fernet 암호문이다(평문 취급 금지).
+API 로그에는 토큰/시크릿을 넣지 않는다.
+"""
+
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from datetime import date, datetime
+from typing import Any, Iterator
+
+from psycopg.rows import dict_row
+from psycopg_pool import ConnectionPool
+
+from app.timezone import KST
+
+from . import store
+
+logger = logging.getLogger("cafe24.db")
+
+# save_token_row / TokenLock.save 에서 부분 갱신을 허용하는 컬럼 화이트리스트.
+# 여기 없는 키는 무시한다(임의 컬럼 주입 방지).
+_TOKEN_FIELDS: tuple[str, ...] = (
+    "access_token",
+    "refresh_token",
+    "access_token_expires_at",
+    "refresh_token_expires_at",
+    "scopes",
+    "last_refreshed_at",
+    "last_error",
+    "connected_by",
+)
+
+
+class TokenLock:
+    """token_lock() 이 넘겨주는 핸들. 잠긴 행 조회 + 같은 트랜잭션 안 저장."""
+
+    def __init__(self, conn: Any, mall_id: str, row: dict[str, Any] | None):
+        self._conn = conn
+        self._mall_id = mall_id
+        self.row = row
+
+    def save(self, **fields: Any) -> None:
+        _update_token_row(self._conn, self._mall_id, fields)
+
+
+def _update_token_row(conn: Any, mall_id: str, fields: dict[str, Any]) -> None:
+    """UPSERT. 주어진 컬럼만 갱신한다(부분 갱신)."""
+    allowed = {k: v for k, v in fields.items() if k in _TOKEN_FIELDS}
+    if not allowed:
+        return
+    columns = list(allowed.keys())
+    placeholders = ", ".join(["%s"] * len(columns))
+    assignments = ", ".join(f"{col} = EXCLUDED.{col}" for col in columns)
+    conn.execute(
+        f"""
+        INSERT INTO cafe24_oauth_tokens (mall_id, {", ".join(columns)})
+        VALUES (%s, {placeholders})
+        ON CONFLICT (mall_id) DO UPDATE SET {assignments}
+        """,
+        (mall_id, *[allowed[col] for col in columns]),
+    )
+
+
+class Cafe24Store:
+    def __init__(self, dsn: str, *, min_size: int = 1, max_size: int = 5):
+        self._pool = ConnectionPool(
+            conninfo=dsn,
+            min_size=min_size,
+            max_size=max_size,
+            kwargs={"row_factory": dict_row, "autocommit": True},
+            open=False,
+        )
+        self._pool.open(wait=False)
+
+    def close(self) -> None:
+        self._pool.close()
+
+    # ════════════════════════════════════════════════════════════
+    # OAuth 토큰 — app/integrations/cafe24/tokens.py 가 요구하는 3개 메서드
+    # ════════════════════════════════════════════════════════════
+    def get_token_row(self, mall_id: str) -> dict[str, Any] | None:
+        with self._pool.connection() as conn:
+            return conn.execute(
+                "SELECT * FROM cafe24_oauth_tokens WHERE mall_id = %s",
+                (mall_id,),
+            ).fetchone()
+
+    def save_token_row(self, *, mall_id: str, **fields: Any) -> None:
+        with self._pool.connection() as conn:
+            _update_token_row(conn, mall_id, fields)
+
+    @contextmanager
+    def token_lock(self, mall_id: str) -> Iterator[TokenLock]:
+        """토큰 행을 FOR UPDATE 로 잠근 채 작업.
+
+        web 컨테이너와 worker 컨테이너가 동시에 refresh 하는 것을 막는다
+        (카페24는 refresh token 을 회전시키므로 동시 갱신 시 한쪽이 무효화됨).
+        행이 아직 없으면 row=None 으로 넘어간다.
+        """
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                row = conn.execute(
+                    "SELECT * FROM cafe24_oauth_tokens WHERE mall_id = %s FOR UPDATE",
+                    (mall_id,),
+                ).fetchone()
+                yield TokenLock(conn, mall_id, row)
+
+    def disconnect(self, mall_id: str) -> None:
+        """연결 해제 — 토큰만 지운다(이력/예약은 보존)."""
+        with self._pool.connection() as conn:
+            conn.execute("DELETE FROM cafe24_oauth_tokens WHERE mall_id = %s", (mall_id,))
+
+    # ════════════════════════════════════════════════════════════
+    # API 호출 로그 (Cafe24Client 가 주입받아 호출)
+    # ⚠️ Authorization/토큰/시크릿은 절대 기록하지 않는다.
+    # ════════════════════════════════════════════════════════════
+    def log_api_call(
+        self,
+        *,
+        endpoint: str,
+        method: str,
+        product_no: int | None,
+        http_status: int | None,
+        result: str,
+        error_message: str,
+        duration_ms: int,
+    ) -> None:
+        with self._pool.connection() as conn:
+            conn.execute(
+                """
+                INSERT INTO cafe24_api_logs
+                    (endpoint, method, product_no, http_status, result, error_message, duration_ms)
+                VALUES (%s,%s,%s,%s,%s,%s,%s)
+                """,
+                (endpoint, method, product_no, http_status, result, error_message, duration_ms),
+            )
+
+    def list_api_logs(self, *, limit: int = 100) -> list[dict[str, Any]]:
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                """
+                SELECT * FROM cafe24_api_logs
+                ORDER BY created_at DESC, id DESC
+                LIMIT %s
+                """,
+                (max(1, min(int(limit), 500)),),
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    # ════════════════════════════════════════════════════════════
+    # 작업 감사 로그
+    # ════════════════════════════════════════════════════════════
+    def log_audit(
+        self,
+        *,
+        actor: str,
+        action: str,
+        product_no: int | None = None,
+        revision_id: int | None = None,
+        schedule_id: int | None = None,
+        result: str = "",
+        detail: str = "",
+    ) -> None:
+        with self._pool.connection() as conn:
+            self._insert_audit(
+                conn,
+                actor=actor,
+                action=action,
+                product_no=product_no,
+                revision_id=revision_id,
+                schedule_id=schedule_id,
+                result=result,
+                detail=detail,
+            )
+
+    @staticmethod
+    def _insert_audit(
+        conn: Any,
+        *,
+        actor: str,
+        action: str,
+        product_no: int | None = None,
+        revision_id: int | None = None,
+        schedule_id: int | None = None,
+        result: str = "",
+        detail: str = "",
+    ) -> None:
+        """호출자의 트랜잭션에 합류시키기 위해 conn 을 받는 정적 헬퍼."""
+        conn.execute(
+            """
+            INSERT INTO cafe24_audit_logs
+                (actor, action, product_no, revision_id, schedule_id, result, detail)
+            VALUES (%s,%s,%s,%s,%s,%s,%s)
+            """,
+            (actor, action, product_no, revision_id, schedule_id, result, detail[:1000]),
+        )
+
+    def list_audit_logs(self, *, limit: int = 100) -> list[dict[str, Any]]:
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                """
+                SELECT * FROM cafe24_audit_logs
+                ORDER BY created_at DESC, id DESC
+                LIMIT %s
+                """,
+                (max(1, min(int(limit), 500)),),
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    # ════════════════════════════════════════════════════════════
+    # 상품 캐시
+    # source of truth 는 언제나 카페24다. 이 표는 목록 조회 결과를 담아두는
+    # 곳이며, 예약·로그 화면에서 API 호출 없이 상품명을 보여줄 때 쓴다.
+    # 상세설명(HTML)은 여기 넣지 않는다(cafe24_product_revisions 담당).
+    # ════════════════════════════════════════════════════════════
+    def upsert_products(self, rows: list[dict[str, Any]]) -> int:
+        """정규화된 상품 dict 목록(products.normalize_product 결과)을 UPSERT."""
+        valid = [r for r in rows if int(r.get("product_no") or 0) > 0]
+        if not valid:
+            return 0
+        with self._pool.connection() as conn:
+            with conn.cursor() as cur:
+                cur.executemany(
+                    """
+                    INSERT INTO cafe24_products
+                        (product_no, product_code, product_name, display, selling, last_synced_at)
+                    VALUES (%s,%s,%s,%s,%s, now())
+                    ON CONFLICT (product_no) DO UPDATE SET
+                        product_code   = EXCLUDED.product_code,
+                        product_name   = EXCLUDED.product_name,
+                        display        = EXCLUDED.display,
+                        selling        = EXCLUDED.selling,
+                        last_synced_at = now()
+                    """,
+                    [
+                        (
+                            int(r["product_no"]),
+                            str(r.get("product_code") or ""),
+                            str(r.get("product_name") or ""),
+                            bool(r.get("display", True)),
+                            bool(r.get("selling", True)),
+                        )
+                        for r in valid
+                    ],
+                )
+        return len(valid)
+
+    def get_cached_product(self, product_no: int) -> dict[str, Any]:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT * FROM cafe24_products WHERE product_no = %s",
+                (int(product_no),),
+            ).fetchone()
+        return self._serialize(row)
+
+    # ════════════════════════════════════════════════════════════
+    # 상세페이지 HTML 버전 (append-only — UPDATE/DELETE 하지 않는다)
+    # 쓰기 직전 BACKUP 을 남기는 것이 유일한 복구 수단이다.
+    # ════════════════════════════════════════════════════════════
+    def add_revision(
+        self,
+        *,
+        product_no: int,
+        html_content: str,
+        revision_type: str,
+        memo: str = "",
+        created_by: str = "",
+    ) -> int:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                """
+                INSERT INTO cafe24_product_revisions
+                    (product_no, html_content, revision_type, memo, created_by)
+                VALUES (%s,%s,%s,%s,%s)
+                RETURNING id
+                """,
+                (
+                    int(product_no),
+                    html_content or "",
+                    store.normalize_revision_type(revision_type),
+                    (memo or "")[:500],
+                    created_by or "",
+                ),
+            ).fetchone()
+        return int(row["id"]) if row else 0
+
+    def list_revisions(self, product_no: int, *, limit: int = 20) -> list[dict[str, Any]]:
+        """버전 목록. html_content 는 수 MB 일 수 있어 길이만 계산해서 준다."""
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                """
+                SELECT id, product_no, revision_type, memo, created_by, created_at,
+                       length(html_content) AS html_length
+                FROM cafe24_product_revisions
+                WHERE product_no = %s
+                ORDER BY created_at DESC, id DESC
+                LIMIT %s
+                """,
+                (int(product_no), max(1, min(int(limit), 200))),
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def get_revision(self, revision_id: int) -> dict[str, Any]:
+        """버전 1건 전체(HTML 포함). 복원/비교용."""
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT * FROM cafe24_product_revisions WHERE id = %s",
+                (int(revision_id),),
+            ).fetchone()
+        return self._serialize(row)
+
+    # ════════════════════════════════════════════════════════════
+    # 예약 (지정 시각에 상세페이지·진열/판매 적용)
+    # 되돌리기는 쓰지 않으므로 end_* 컬럼은 건드리지 않는다.
+    # ════════════════════════════════════════════════════════════
+    def create_schedule(
+        self,
+        *,
+        product_no: int,
+        scheduled_at: datetime,
+        revision_id: int | None,
+        set_display: bool | None,
+        set_selling: bool | None,
+        memo: str = "",
+        created_by: str = "",
+    ) -> int:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                """
+                INSERT INTO cafe24_product_schedules
+                    (product_no, scheduled_at, revision_id, set_display, set_selling,
+                     memo, created_by)
+                VALUES (%s,%s,%s,%s,%s,%s,%s)
+                RETURNING id
+                """,
+                (
+                    int(product_no),
+                    scheduled_at,
+                    revision_id,
+                    set_display,
+                    set_selling,
+                    (memo or "")[:500],
+                    created_by or "",
+                ),
+            ).fetchone()
+        return int(row["id"]) if row else 0
+
+    def list_schedules(self, *, limit: int = 200) -> list[dict[str, Any]]:
+        """예약 목록. 대기 중인 것을 먼저, 그다음 최근 처리 순."""
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                """
+                SELECT s.*, p.product_name,
+                       (s.revision_id IS NOT NULL) AS has_html
+                FROM cafe24_product_schedules s
+                LEFT JOIN cafe24_products p ON p.product_no = s.product_no
+                ORDER BY (s.status = 'PENDING') DESC,
+                         CASE WHEN s.status = 'PENDING' THEN s.scheduled_at END ASC,
+                         s.scheduled_at DESC, s.id DESC
+                LIMIT %s
+                """,
+                (max(1, min(int(limit), 500)),),
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def cancel_schedule(self, schedule_id: int, *, actor: str = "") -> bool:
+        """대기 중인 예약만 취소한다. 실행 중/완료된 것은 건드리지 않는다."""
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                row = conn.execute(
+                    """
+                    UPDATE cafe24_product_schedules
+                    SET status = 'CANCELLED', completed_at = now()
+                    WHERE id = %s AND status = 'PENDING'
+                    RETURNING id, product_no
+                    """,
+                    (int(schedule_id),),
+                ).fetchone()
+                if row is None:
+                    return False
+                self._insert_audit(
+                    conn,
+                    actor=actor,
+                    action="schedule_cancel",
+                    product_no=row["product_no"],
+                    schedule_id=row["id"],
+                    result="SUCCESS",
+                )
+        return True
+
+    @contextmanager
+    def claim_due_schedule(self, *, now: datetime) -> Iterator[dict[str, Any] | None]:
+        """실행할 예약 1건을 잡아 PROCESSING 으로 바꾼다(worker 전용).
+
+        `FOR UPDATE SKIP LOCKED` 로 잠그므로 worker 가 여러 개 떠 있어도 같은 예약을
+        두 번 실행하지 않는다. 재시도 대기(next_retry_at)가 남아 있으면 건너뛴다.
+        """
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                row = conn.execute(
+                    """
+                    SELECT * FROM cafe24_product_schedules
+                    WHERE status = 'PENDING'
+                      AND scheduled_at <= %s
+                      AND (next_retry_at IS NULL OR next_retry_at <= %s)
+                    ORDER BY scheduled_at ASC, id ASC
+                    LIMIT 1
+                    FOR UPDATE SKIP LOCKED
+                    """,
+                    (now, now),
+                ).fetchone()
+                if row is not None:
+                    conn.execute(
+                        """
+                        UPDATE cafe24_product_schedules
+                        SET status = 'PROCESSING', started_at = now(), last_error = ''
+                        WHERE id = %s
+                        """,
+                        (row["id"],),
+                    )
+            yield dict(row) if row is not None else None
+
+    def finish_schedule(
+        self,
+        schedule_id: int,
+        *,
+        status: str,
+        error: str = "",
+        next_retry_at: datetime | None = None,
+        retry_count: int | None = None,
+    ) -> None:
+        """예약 종료 처리. 재시도로 되돌릴 때는 status='PENDING' + next_retry_at."""
+        with self._pool.connection() as conn:
+            conn.execute(
+                """
+                UPDATE cafe24_product_schedules
+                SET status = %s,
+                    last_error = %s,
+                    next_retry_at = %s,
+                    retry_count = COALESCE(%s, retry_count),
+                    completed_at = CASE WHEN %s IN ('SUCCESS','FAILED','CANCELLED')
+                                        THEN now() ELSE completed_at END
+                WHERE id = %s
+                """,
+                (
+                    store.normalize_schedule_status(status),
+                    (error or "")[:1000],
+                    next_retry_at,
+                    retry_count,
+                    store.normalize_schedule_status(status),
+                    int(schedule_id),
+                ),
+            )
+
+    # ════════════════════════════════════════════════════════════
+    # 직렬화 — datetime → KST ISO, date → ISO (다른 모듈과 동일)
+    # ════════════════════════════════════════════════════════════
+    @staticmethod
+    def _serialize(row: dict[str, Any] | None) -> dict[str, Any]:
+        if not row:
+            return {}
+        out = dict(row)
+        for key, value in list(out.items()):
+            if isinstance(value, datetime):
+                aware = value if value.tzinfo else value.replace(tzinfo=KST)
+                out[key] = aware.astimezone(KST).isoformat(timespec="seconds")
+            elif isinstance(value, date):
+                out[key] = value.isoformat()
+        return out
+
+
+__all__ = ["Cafe24Store", "TokenLock", "store"]

app/modules/cafe24/router.py

@@ -0,0 +1,39 @@
+"""카페24 상품 상세페이지 관리 모듈 라우터.
+
+- 경로: /cafe24
+- 권한: 로그인 + `cafe24` 모듈 권한 (관리자는 항상 통과). 서버 측 검사.
+  카페24 연결(OAuth) 변경은 `is_admin` 만.
+- 데이터: Cafe24Store (cafe24_db / PostgreSQL) 전용.
+  CAFE24_DB_URL 미설정 시 store 가 None 이며, 각 페이지는 "설정 필요" 안내.
+- 카페24 API 호출은 app/integrations/cafe24 공통 계층을 통해서만 한다.
+
+라우트가 많아 기능별 파일로 나눈다(다른 모듈의 단일 router.py 패턴을 규모 때문에
+확장한 것). 여기서는 루트 라우터를 만들고 서브 라우터를 결합한다.
+    routes_products  상품 목록/검색 · 상세설명 조회·편집·적용
+    routes_schedules 예약 등록·목록·취소 (실행은 worker.py)
+    routes_system    연결(OAuth)·상태·API 로그·작업 로그
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter
+
+from .routes_products import products_router
+from .routes_schedules import schedules_router
+from .routes_system import system_router
+
+logger = logging.getLogger("cafe24.router")
+
+router = APIRouter(prefix="/cafe24", tags=["cafe24"])
+
+router.include_router(products_router)
+router.include_router(schedules_router)
+router.include_router(system_router)
+
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    """포털 카드의 상태 점(dot) 용. 인증 불필요 — 상태 문자열만 반환."""
+    return {"status": "ok"}

app/modules/cafe24/routes_products.py

@@ -0,0 +1,488 @@
+"""카페24 상품 화면 — 좌우 2분할(목록 | 상세페이지 편집).
+
+화면 구성
+    왼쪽  전체 상품 목록. 좁게. 진열/판매 필터(중복 선택) + 제목행 클릭 정렬.
+    오른쪽 선택한 상품의 상세설명 HTML 편집기 + 버전 이력. 넓게.
+
+목록은 페이지를 넘겨가며 **전체**를 한 번에 받는다(`list_all_products`). 필터·정렬을
+브라우저에서 처리하려면 전체가 있어야 정확하다 — 한 페이지만 받아 걸러내면 다음
+페이지에 있는 해당 상품이 빠진다.
+
+상품을 클릭하면 오른쪽만 교체한다(`GET /products/{no}/pane` 이 편집기 조각을
+돌려주고 JS 가 끼워 넣는다). 목록을 다시 불러오지 않으므로 카페24 호출이 1회로
+끝난다. JS 가 없거나 실패하면 각 행은 그냥 링크(`/cafe24/?selected=`)로 동작한다.
+
+쓰기(`POST /products/{no}/apply`)는 반드시 이 순서를 지킨다.
+    카페24 현재값 재조회 → BACKUP 버전 저장 → 지문 대조(충돌 거부) → PUT →
+    MANUAL 버전 + 감사로그
+로컬 DB 의 마지막 버전을 "지금 카페24에 올라간 값"으로 가정하지 않는다.
+
+PC/모바일은 구분하지 않는다 — 적용 시 `description` 과 `mobile_description` 에
+같은 HTML 을 쓴다(운영 방침). 분리 사용 상품이어도 한쪽만 바뀌는 일이 없다.
+
+이미지 경로의 한글은 카페24에 퍼센트 인코딩으로 저장돼 있다. 편집기에는
+`store.decode_html_urls` 로 풀어서 보여주고, 저장할 때 `encode_html_urls` 로
+되돌린다(왕복 보존 — store.py 주석 참고).
+
+핸들러는 `async def` 가 아니라 `def`(동기)로 선언한다. 카페24 API·DB 호출이
+블로킹이므로 FastAPI 스레드풀에서 돌게 두는 편이 이벤트 루프를 막지 않는다.
+"""
+
+from __future__ import annotations
+
+import logging
+from decimal import Decimal
+from typing import Any
+from urllib.parse import urlencode
+
+from fastapi import APIRouter, Body, Form, HTTPException, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+
+from app.integrations.cafe24 import Cafe24Error, build_cafe24_api, products
+
+from . import store
+from .common import base_ctx, guard, require_store
+
+logger = logging.getLogger("cafe24.products")
+
+products_router = APIRouter()
+
+
+def _checked(request: Request, name: str) -> bool:
+    """체크박스 → bool. 값이 무엇이든 파라미터가 있으면 체크된 것으로 본다."""
+    return request.query_params.get(name) is not None
+
+
+def _no_store(response: Any) -> Any:
+    """브라우저가 이 응답을 재사용하지 못하게 한다.
+
+    편집기는 카페24의 **현재** HTML 을 보여줘야 한다. 캐시된 화면이 다시 그려지면
+    카페24 관리자에서 값을 바꾼 뒤에도 예전 소스가 보이고, 그것을 그대로 편집하면
+    남의 수정을 덮어쓴다. 조각을 가져가는 fetch 에도 `cache: "no-store"` 를 건다.
+    """
+    response.headers["Cache-Control"] = "no-store, must-revalidate"
+    response.headers["Pragma"] = "no-cache"
+    return response
+
+
+def _price(value: Any) -> str:
+    """카페24 가격('6900.00') → 화면 표기('6,900원').
+
+    소수점 아래는 버린다 — 이 쇼핑몰은 원 단위라 언제나 .00 이고, 화면에 보일
+    이유가 없다. 숫자로 못 읽으면 받은 값을 그대로 보여준다.
+    """
+    text = str(value or "").strip()
+    if not text:
+        return ""
+    try:
+        won = int(Decimal(text))
+    except (ArithmeticError, ValueError):
+        return text
+    return f"{won:,}원"
+
+
+def _short_dt(value: Any) -> str:
+    """'2026-08-14T11:38:18+09:00' → '2026-08-14 11:38'."""
+    text = str(value or "").strip()
+    if not text:
+        return ""
+    return text.replace("T", " ")[:16]
+
+
+def _row_for_list(raw: dict[str, Any]) -> dict[str, Any]:
+    """왼쪽 목록에 쓸 필드만 — 상품번호·상품명·진열·판매·최근수정."""
+    normalized = products.normalize_product(raw)
+    return {
+        "product_no": normalized["product_no"],
+        "product_name": normalized["product_name"],
+        "display": normalized["display"],
+        "selling": normalized["selling"],
+        "updated_date": _short_dt(raw.get("updated_date")),
+    }
+
+
+# 필터 폼이 제출됐음을 알리는 표식.
+# 체크박스는 해제 상태면 아무 값도 보내지 않으므로, 이것 없이는 "첫 방문"과
+# "사용자가 일부러 해제함"을 구분할 수 없다(기본값이 체크라서 해제가 무시된다).
+_FILTER_MARK = "f"
+
+
+def _filter_flags(request: Request) -> tuple[bool, bool]:
+    """(진열중만, 판매중만). 첫 방문이면 둘 다 기본 체크로 본다."""
+    if request.query_params.get(_FILTER_MARK) is None:
+        return True, True
+    return _checked(request, "display"), _checked(request, "selling")
+
+
+def _list_query(request: Request, *, selected: int | None = None) -> str:
+    """현재 검색·필터를 유지한 목록 URL 쿼리스트링."""
+    params: list[tuple[str, str]] = []
+    keyword = (request.query_params.get("q") or "").strip()
+    if keyword:
+        params.append(("q", keyword))
+    if request.query_params.get(_FILTER_MARK) is not None:
+        # 해제 상태까지 그대로 이어지도록 표식을 함께 남긴다.
+        params.append((_FILTER_MARK, "1"))
+        for flag in ("display", "selling"):
+            if _checked(request, flag):
+                params.append((flag, "1"))
+    if selected:
+        params.append(("selected", str(selected)))
+    return urlencode(params)
+
+
+def _editor_ctx(st: Any, product_no: int) -> dict[str, Any]:
+    """오른쪽 편집기 조각에 필요한 컨텍스트. 전체 페이지와 조각이 함께 쓴다."""
+    api = build_cafe24_api(st)
+    product: dict[str, Any] = {}
+    desc = None
+    error = ""
+    try:
+        product = products.get_product(api.client, product_no)
+        desc = products.descriptions_from_product(product)
+        st.upsert_products([products.normalize_product(product)])
+    except Cafe24Error as exc:
+        error = str(exc)
+        logger.warning("카페24 상품 %s 조회 실패: %s", product_no, exc)
+
+    info = products.normalize_product(product) if product else {}
+    return {
+        "product_no": product_no,
+        # 고객이 보는 상세페이지 주소 (CAFE24_SHOP_URL, 없으면 카페24 기본 도메인)
+        "product_url": api.config.product_url(product_no),
+        "info": {
+            **info,
+            "price": _price(product.get("price")),
+            "updated_date": _short_dt(product.get("updated_date")),
+            "summary_description": product.get("summary_description") or "",
+        },
+        "desc": desc,
+        # 편집기에는 (1) 이미지 경로의 %EC%9A%A9… 을 한글로 풀고
+        #            (2) 태그마다 줄을 나눠 정리해서 보여준다.
+        # 저장할 때 같은 정리를 거친 값을 카페24에 쓴다(화면과 저장값이 같다).
+        "html_pc": store.format_html(store.decode_html_urls(desc.description)) if desc else "",
+        # 지문은 **인코딩된 원본**으로 만든다(적용 직전 카페24 값과 비교하므로).
+        "fingerprint": store.fingerprint(desc.description) if desc else "",
+        "revisions": st.list_revisions(product_no, limit=20),
+        "editor_error": error,
+    }
+
+
+@products_router.get("/", response_class=HTMLResponse)
+def product_list(request: Request) -> HTMLResponse:
+    """2분할 화면. `selected` 가 있으면 오른쪽 편집기까지 서버에서 그린다."""
+    from app.main import render_template  # noqa: WPS433
+
+    checked = guard(request)
+    if not isinstance(checked, tuple):
+        return checked
+    st, user = checked
+
+    keyword = (request.query_params.get("q") or "").strip()
+    only_display, only_selling = _filter_flags(request)
+
+    api = build_cafe24_api(st)
+    rows: list[dict[str, Any]] = []
+    total = 0
+    truncated = False
+    error = ""
+    try:
+        raw_rows, truncated = products.list_all_products(api.client, product_name=keyword)
+        st.upsert_products([products.normalize_product(r) for r in raw_rows])
+        total = len(raw_rows)
+        rows = [_row_for_list(r) for r in raw_rows]
+        # 필터는 전체를 받아온 뒤 적용한다(문서에 없는 API 파라미터에 기대지 않는다).
+        if only_display:
+            rows = [r for r in rows if r["display"]]
+        if only_selling:
+            rows = [r for r in rows if r["selling"]]
+    except Cafe24Error as exc:
+        # 미연결/토큰만료/호출제한 모두 여기로 온다. 화면은 살려두고 사유만 알린다.
+        error = str(exc)
+        logger.warning("카페24 상품 목록 조회 실패: %s", exc)
+
+    try:
+        selected = int(request.query_params.get("selected") or 0)
+    except ValueError:
+        selected = 0
+
+    ctx = base_ctx(request, user, active_tab="products")
+    ctx.update(
+        {
+            "page_title": "카페24 상품관리",
+            "page_subtitle": "상품 상세페이지 조회·편집·예약",
+            "rows": rows,
+            "total": total,
+            "shown": len(rows),
+            "truncated": truncated,
+            "keyword": keyword,
+            "only_display": only_display,
+            "only_selling": only_selling,
+            "selected": selected,
+            "list_query": _list_query(request),
+            "error": error,
+            "flash": request.query_params.get("msg", ""),
+            "flash_error": request.query_params.get("err", ""),
+        }
+    )
+    if selected:
+        ctx.update(_editor_ctx(st, selected))
+    return _no_store(render_template(request, "cafe24/products.html", ctx))
+
+
+@products_router.get("/products/{product_no}/pane", response_class=HTMLResponse)
+def product_pane(request: Request, product_no: int) -> HTMLResponse:
+    """오른쪽 편집기 조각만 — 목록을 다시 그리지 않기 위해 JS 가 가져간다."""
+    from app.main import render_template  # noqa: WPS433
+
+    checked = guard(request)
+    if not isinstance(checked, tuple):
+        return checked
+    st, user = checked
+
+    ctx = base_ctx(request, user, active_tab="products")
+    ctx.update(_editor_ctx(st, product_no))
+    ctx["list_query"] = _list_query(request)
+    return _no_store(render_template(request, "cafe24/_editor.html", ctx))
+
+
+# 카페24 상품명 최대 길이(API 문서 기준). 넘기면 카페24가 거절하므로 미리 막는다.
+NAME_MAX = 250
+
+
+@products_router.post("/products/{product_no}/name")
+def product_rename(
+    request: Request,
+    product_no: int,
+    payload: dict[str, Any] = Body(default_factory=dict),
+) -> dict[str, Any]:
+    """상품명만 바꾼다 — 편집기 제목 옆 연필 버튼용(JSON API).
+
+    상세설명과 마찬가지로 **쓰기 전에 카페24의 현재값을 읽는다.** 여기서는 되돌릴
+    HTML 이 없으므로 revision 은 만들지 않고, 대신 이전 이름을 감사로그에 남긴다
+    (되돌리려면 로그를 보고 다시 바꾼다).
+    """
+    st, user = require_store(request)
+    actor = str(user.get("email") or "")
+
+    name = str(payload.get("name") or "").strip()
+    if not name:
+        raise HTTPException(status_code=400, detail="상품명을 입력하세요.")
+    if len(name) > NAME_MAX:
+        raise HTTPException(status_code=400, detail=f"상품명은 {NAME_MAX}자를 넘을 수 없습니다.")
+
+    api = build_cafe24_api(st)
+    try:
+        current = products.get_product(api.client, product_no)
+    except Cafe24Error as exc:
+        st.log_audit(
+            actor=actor, action="rename_product", product_no=product_no,
+            result="FAIL", detail=f"현재값 조회 실패: {exc}",
+        )
+        raise HTTPException(status_code=502, detail=f"카페24 현재값을 읽지 못했습니다: {exc}") from exc
+
+    before = str(current.get("product_name") or "")
+    if before == name:
+        return {"ok": True, "product_name": before, "changed": False}
+
+    try:
+        updated = products.update_product(api.client, product_no, product_name=name)
+    except Cafe24Error as exc:
+        st.log_audit(
+            actor=actor, action="rename_product", product_no=product_no,
+            result="FAIL", detail=f"'{before}' → '{name}' 실패: {exc}",
+        )
+        logger.warning("카페24 상품 %s 이름 변경 실패: %s", product_no, exc)
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+
+    info = products.normalize_product(updated) if updated else {}
+    if info.get("product_no"):
+        st.upsert_products([info])
+    after = str(info.get("product_name") or name)
+    st.log_audit(
+        actor=actor, action="rename_product", product_no=product_no,
+        result="SUCCESS", detail=f"'{before}' → '{after}'",
+    )
+    logger.info("카페24 상품 %s 이름 변경 (%s)", product_no, actor)
+    return {"ok": True, "product_name": after, "changed": True}
+
+
+@products_router.post("/products/{product_no}/status")
+def product_status(
+    request: Request,
+    product_no: int,
+    payload: dict[str, Any] = Body(default_factory=dict),
+) -> dict[str, Any]:
+    """진열/판매 상태만 바꾼다 — 편집기 오른쪽 위 배지 클릭용(JSON API).
+
+    상세설명은 건드리지 않는다(`build_update_payload` 는 준 필드만 보낸다). 그래서
+    BACKUP revision 도 만들지 않는다 — 되돌릴 HTML 이 없고, 상태는 다시 눌러
+    되돌릴 수 있다.
+
+    `value` 는 클라이언트가 **원하는 결과값**이다(현재값을 뒤집지 않는다). 화면의
+    배지가 카페24와 어긋나 있어도 사용자가 누른 대로 되는 편이 예측 가능하다.
+    응답에는 쓰기 후 카페24가 돌려준 실제 상태를 담아 화면을 그것에 맞춘다.
+    """
+    st, user = require_store(request)
+    actor = str(user.get("email") or "")
+
+    field = str(payload.get("field") or "").strip()
+    if field not in ("display", "selling"):
+        raise HTTPException(status_code=400, detail="field 는 display 또는 selling 이어야 합니다.")
+    want = bool(payload.get("value"))
+
+    api = build_cafe24_api(st)
+    try:
+        updated = products.update_product(api.client, product_no, **{field: want})
+    except Cafe24Error as exc:
+        st.log_audit(
+            actor=actor, action=f"set_{field}", product_no=product_no,
+            result="FAIL", detail=f"{want} 설정 실패: {exc}",
+        )
+        logger.warning("카페24 상품 %s %s 변경 실패: %s", product_no, field, exc)
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+
+    # 응답이 상품 dict 면 그것이 곧 현재 상태다. 모양이 다르면(방어) 다시 조회한다.
+    if "display" not in updated or "selling" not in updated:
+        try:
+            updated = products.get_product(api.client, product_no)
+        except Cafe24Error as exc:  # 쓰기는 됐다 — 화면만 요청값으로 맞춘다.
+            logger.warning("카페24 상품 %s 상태 재조회 실패: %s", product_no, exc)
+            updated = {}
+
+    info = products.normalize_product(updated) if updated else {}
+    if info.get("product_no"):
+        st.upsert_products([info])
+    state = {
+        "display": bool(info.get("display", want if field == "display" else True)),
+        "selling": bool(info.get("selling", want if field == "selling" else True)),
+    }
+    st.log_audit(
+        actor=actor, action=f"set_{field}", product_no=product_no,
+        result="SUCCESS", detail=f"{field}={'T' if want else 'F'}",
+    )
+    logger.info("카페24 상품 %s %s=%s (%s)", product_no, field, want, actor)
+    return {"ok": True, **state}
+
+
+@products_router.get("/products/{product_no}")
+def product_redirect(request: Request, product_no: int):
+    """옛 단독 화면 주소 → 2분할 화면에서 해당 상품을 선택한 상태로 보낸다."""
+    return RedirectResponse(url=f"/cafe24/?selected={product_no}", status_code=303)
+
+
+@products_router.post("/products/{product_no}/apply")
+def product_apply(
+    request: Request,
+    product_no: int,
+    html: str = Form(""),
+    base_fingerprint: str = Form(""),
+    memo: str = Form(""),
+    list_query: str = Form(""),
+):
+    """편집한 HTML 을 카페24에 즉시 적용한다.
+
+    순서를 지키는 것이 이 함수의 핵심이다.
+      1) 카페24에서 **현재** HTML 을 다시 읽는다(로컬 값을 현재값으로 믿지 않는다)
+      2) 그 값으로 BACKUP 버전을 남긴다 ← 유일한 복구 수단
+      3) 편집 시작 시점의 지문과 비교해 충돌이면 거부한다
+      4) 쓰고, MANUAL 버전과 감사로그를 남긴다
+
+    PC/모바일을 구분하지 않는다 — 두 필드에 같은 HTML 을 쓴다. 분리 사용 상품의
+    모바일 내용이 PC 와 달랐다면 덮어쓰기 전에 그 내용도 BACKUP 으로 남긴다.
+    """
+    checked = guard(request)
+    if not isinstance(checked, tuple):
+        return checked
+    st, user = checked
+
+    actor = str(user.get("email") or "")
+    # 적용 후에는 검색·필터를 유지한 채 같은 상품이 선택된 화면으로 돌아온다.
+    base = f"/cafe24/?{list_query}" if list_query else f"/cafe24/?selected={product_no}"
+    back = base if f"selected={product_no}" in base else f"{base}&selected={product_no}"
+
+    # 화면에서 보던 그대로(정리된 소스)를 카페24에 반영한다. 한글 이미지 경로는
+    # 원래의 퍼센트 인코딩으로 되돌린다.
+    submitted = store.format_html(store.encode_html_urls(html or ""))
+    if not submitted.strip():
+        return RedirectResponse(
+            url=f"{back}&err=내용이 비어 있습니다. 상세페이지를 비우려면 카페24 관리자에서 하세요.",
+            status_code=303,
+        )
+
+    api = build_cafe24_api(st)
+    try:
+        current = products.fetch_descriptions(api.client, product_no)
+    except Cafe24Error as exc:
+        st.log_audit(
+            actor=actor, action="apply_description", product_no=product_no,
+            result="FAIL", detail=f"현재값 조회 실패: {exc}",
+        )
+        return RedirectResponse(url=f"{back}&err=카페24 현재값을 읽지 못해 중단했습니다: {exc}", status_code=303)
+
+    backup_id = st.add_revision(
+        product_no=product_no,
+        html_content=current.description,
+        revision_type=store.REVISION_BACKUP,
+        memo="적용 직전 자동 백업",
+        created_by=actor,
+    )
+    # 모바일 내용이 PC 와 달랐다면 그것도 따로 남긴다. 아래에서 모바일을 PC 와 같게
+    # 덮어쓰므로, 백업하지 않으면 그 내용을 되찾을 방법이 없다.
+    if current.mobile_description and current.mobile_description != current.description:
+        st.add_revision(
+            product_no=product_no,
+            html_content=current.mobile_description,
+            revision_type=store.REVISION_BACKUP,
+            memo="적용 직전 자동 백업 (모바일 — PC와 달랐던 내용)",
+            created_by=actor,
+        )
+
+    if base_fingerprint and base_fingerprint != store.fingerprint(current.description):
+        st.log_audit(
+            actor=actor, action="apply_description", product_no=product_no,
+            revision_id=backup_id, result="FAIL", detail="충돌 — 편집 중 카페24 값이 변경됨",
+        )
+        return RedirectResponse(
+            url=f"{back}&err=편집하는 동안 카페24 값이 변경되었습니다. 새로고침해 현재 내용을 확인한 뒤 다시 적용하세요.",
+            status_code=303,
+        )
+
+    # PC/모바일을 구분하지 않는다 — 항상 같은 내용으로 함께 쓴다(운영 방침).
+    # 분리 사용 상품이어도 모바일에 같은 HTML 을 넣으므로 한쪽만 바뀌는 일이 없다.
+    mobile_html = submitted
+
+    if submitted == current.description and mobile_html == current.mobile_description:
+        return RedirectResponse(url=f"{back}&msg=변경된 내용이 없어 적용하지 않았습니다.", status_code=303)
+    try:
+        products.update_descriptions(
+            api.client, product_no, description=submitted, mobile_description=mobile_html
+        )
+    except Cafe24Error as exc:
+        st.log_audit(
+            actor=actor, action="apply_description", product_no=product_no,
+            revision_id=backup_id, result="FAIL", detail=str(exc),
+        )
+        logger.warning("카페24 상품 %s 적용 실패: %s", product_no, exc)
+        return RedirectResponse(
+            url=f"{back}&err=적용에 실패했습니다: {exc} (직전 내용은 버전 {backup_id} 로 보관됨)",
+            status_code=303,
+        )
+
+    revision_id = st.add_revision(
+        product_no=product_no,
+        html_content=submitted,
+        revision_type=store.REVISION_MANUAL,
+        memo=memo,
+        created_by=actor,
+    )
+    st.log_audit(
+        actor=actor, action="apply_description", product_no=product_no,
+        revision_id=revision_id, result="SUCCESS",
+        detail=f"{len(submitted)}자 적용 (백업 {backup_id}, PC·모바일 동시 반영)",
+    )
+    logger.info("카페24 상품 %s 상세설명 적용 (%s)", product_no, actor)
+    return RedirectResponse(
+        url=f"{back}&msg=카페24에 적용했습니다. 직전 내용은 버전 {backup_id} 로 보관됩니다.",
+        status_code=303,
+    )

app/modules/cafe24/routes_schedules.py

@@ -0,0 +1,189 @@
+"""카페24 예약관리 — 지정 시각에 상세페이지·진열/판매를 자동 적용.
+
+되돌리기(자동 복원)는 쓰지 않는다. 예약은 "그 시각에 이 내용을 적용" 하나뿐이다.
+한 예약에서 세 가지를 각각 고를 수 있다.
+
+    상세페이지 HTML   편집기에 있는 내용을 그 시각에 적용 (안 고르면 HTML 은 그대로)
+    진열              진열 / 미진열 / 변경 없음
+    판매              판매 / 중지 / 변경 없음
+
+예약을 만들 때 편집기의 HTML 을 **DRAFT revision 으로 먼저 저장**하고 예약이 그
+버전을 가리킨다. 나중에 편집기에서 내용을 더 고쳐도 예약 내용은 등록 시점 그대로다
+(예약해둔 것이 조용히 바뀌면 안 된다).
+
+실제 적용은 웹 프로세스가 아니라 **worker** 가 한다(`app/modules/cafe24/worker.py`,
+compose 서비스 `dbx-cafe24-worker`). 브라우저를 닫아도 실행되어야 하기 때문이다.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Form, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+
+from app.integrations.cafe24 import Cafe24Error, build_cafe24_api, products
+
+from . import store
+from .common import base_ctx, guard
+from .routes_products import _no_store
+
+logger = logging.getLogger("cafe24.schedules")
+
+schedules_router = APIRouter()
+
+
+@schedules_router.get("/schedules", response_class=HTMLResponse)
+def schedules_page(request: Request) -> HTMLResponse:
+    """예약 목록 — 대기 중인 것이 위, 그다음 최근 처리 순."""
+    from app.main import render_template  # noqa: WPS433
+
+    checked = guard(request)
+    if not isinstance(checked, tuple):
+        return checked
+    st, user = checked
+
+    rows = []
+    for row in st.list_schedules(limit=200):
+        rows.append(
+            {
+                **row,
+                "status_label": store.SCHEDULE_STATUS_LABELS.get(row.get("status") or "", ""),
+                "action_label": store.describe_schedule_action(
+                    has_html=bool(row.get("has_html")),
+                    set_display=row.get("set_display"),
+                    set_selling=row.get("set_selling"),
+                ),
+                "editable": store.is_editable(row.get("status") or ""),
+            }
+        )
+
+    ctx = base_ctx(request, user, active_tab="schedules")
+    ctx.update(
+        {
+            "page_title": "카페24 — 예약관리",
+            "page_subtitle": "지정 시각에 상세페이지·진열/판매 자동 적용",
+            "rows": rows,
+            "pending": sum(1 for r in rows if r["status"] == store.STATUS_PENDING),
+            "flash": request.query_params.get("msg", ""),
+            "flash_error": request.query_params.get("err", ""),
+        }
+    )
+    return _no_store(render_template(request, "cafe24/schedules.html", ctx))
+
+
+@schedules_router.post("/schedules")
+def schedule_create(
+    request: Request,
+    product_no: int = Form(...),
+    scheduled_at: str = Form(""),
+    html: str = Form(""),
+    apply_html: str = Form(""),
+    set_display: str = Form(""),
+    set_selling: str = Form(""),
+    memo: str = Form(""),
+    list_query: str = Form(""),
+):
+    """편집기에서 예약을 등록한다.
+
+    HTML 을 적용하는 예약이면 지금 편집기 내용을 DRAFT revision 으로 저장해 고정한다.
+    단건 적용과 같은 다듬기(URL 인코딩 → 소스 정리)를 거치므로, 예약이 실행됐을 때
+    저장되는 값이 화면에서 본 것과 같다.
+    """
+    checked = guard(request)
+    if not isinstance(checked, tuple):
+        return checked
+    st, user = checked
+
+    actor = str(user.get("email") or "")
+    base = f"/cafe24/?{list_query}" if list_query else f"/cafe24/?selected={product_no}"
+    back = base if f"selected={product_no}" in base else f"{base}&selected={product_no}"
+
+    want_html = bool(apply_html)
+    display_flag = store.parse_tristate(set_display)
+    selling_flag = store.parse_tristate(set_selling)
+
+    if not want_html and display_flag is None and selling_flag is None:
+        return RedirectResponse(
+            url=f"{back}&err=예약할 내용을 하나 이상 선택하세요(상세페이지 / 진열 / 판매).",
+            status_code=303,
+        )
+
+    try:
+        run_at = store.parse_schedule_at(scheduled_at)
+    except ValueError as exc:
+        return RedirectResponse(url=f"{back}&err={exc}", status_code=303)
+
+    revision_id: int | None = None
+    if want_html:
+        body = store.format_html(store.encode_html_urls(html or ""))
+        if not body.strip():
+            return RedirectResponse(
+                url=f"{back}&err=상세페이지 내용이 비어 있습니다.", status_code=303
+            )
+        revision_id = st.add_revision(
+            product_no=product_no,
+            html_content=body,
+            revision_type=store.REVISION_DRAFT,
+            memo=f"예약 등록 ({run_at.strftime('%Y-%m-%d %H:%M')} 적용 예정)",
+            created_by=actor,
+        )
+
+    schedule_id = st.create_schedule(
+        product_no=product_no,
+        scheduled_at=run_at,
+        revision_id=revision_id,
+        set_display=display_flag,
+        set_selling=selling_flag,
+        memo=memo,
+        created_by=actor,
+    )
+    detail = store.describe_schedule_action(
+        has_html=want_html, set_display=display_flag, set_selling=selling_flag
+    )
+    st.log_audit(
+        actor=actor, action="schedule_create", product_no=product_no,
+        revision_id=revision_id, schedule_id=schedule_id, result="SUCCESS",
+        detail=f"{run_at.strftime('%Y-%m-%d %H:%M')} — {detail}",
+    )
+    logger.info("카페24 예약 등록 #%s 상품 %s (%s)", schedule_id, product_no, detail)
+    return RedirectResponse(
+        url=f"/cafe24/schedules?msg={run_at.strftime('%Y-%m-%d %H:%M')} 예약을 등록했습니다 — {detail}",
+        status_code=303,
+    )
+
+
+@schedules_router.post("/schedules/{schedule_id}/cancel")
+def schedule_cancel(request: Request, schedule_id: int):
+    """대기 중인 예약 취소. 이미 실행됐거나 실행 중이면 아무것도 하지 않는다."""
+    checked = guard(request)
+    if not isinstance(checked, tuple):
+        return checked
+    st, user = checked
+
+    ok = st.cancel_schedule(schedule_id, actor=str(user.get("email") or ""))
+    if ok:
+        return RedirectResponse(url=f"/cafe24/schedules?msg=예약 #{schedule_id} 을 취소했습니다.", status_code=303)
+    return RedirectResponse(
+        url=f"/cafe24/schedules?err=예약 #{schedule_id} 은 이미 처리되었거나 실행 중이라 취소할 수 없습니다.",
+        status_code=303,
+    )
+
+
+@schedules_router.get("/schedules/preview/{product_no}")
+def schedule_current_flags(request: Request, product_no: int) -> dict:
+    """예약 폼의 기본값을 위해 현재 진열/판매 상태를 알려준다(JSON, 읽기 전용)."""
+    from .common import require_store  # noqa: WPS433
+
+    st, _user = require_store(request)
+    api = build_cafe24_api(st)
+    try:
+        raw = products.get_product(api.client, product_no)
+    except Cafe24Error as exc:
+        return {"product_no": product_no, "error": str(exc)}
+    normalized = products.normalize_product(raw)
+    return {
+        "product_no": product_no,
+        "display": normalized["display"],
+        "selling": normalized["selling"],
+    }

app/modules/cafe24/routes_system.py

@@ -0,0 +1,162 @@
+"""카페24 시스템 화면 — 연결(OAuth) / 연결 상태 / API 로그 / 작업 로그.
+
+OAuth 흐름
+    1) 관리자가 [카페24 연결] → GET /cafe24/system/oauth/start
+       state 를 만들어 세션에 넣고 카페24 인증 페이지로 302.
+    2) 카페24가 GET /cafe24/oauth/callback?code=&state= 로 되돌려보냄.
+       세션 state 와 대조(CSRF 방어) 후 code → 토큰 교환, 암호화 저장.
+
+핸들러는 `def`(동기)로 선언한다. 카페24 API·DB 호출이 블로킹이므로 FastAPI 의
+스레드풀에서 돌게 두는 편이 이벤트 루프를 막지 않는다.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse, RedirectResponse
+
+from app.integrations.cafe24 import (
+    Cafe24AuthError,
+    Cafe24ConfigError,
+    Cafe24Error,
+    build_authorize_url,
+    build_cafe24_api,
+    exchange_code,
+    load_config,
+    new_state,
+)
+
+from .common import base_ctx, guard, render_config_needed, require_admin
+
+logger = logging.getLogger("cafe24.system")
+
+system_router = APIRouter()
+
+# 세션에 state 를 담는 키
+_STATE_KEY = "cafe24_oauth_state"
+
+
+@system_router.get("/system", response_class=HTMLResponse)
+def system_page(request: Request) -> HTMLResponse:
+    from app.main import render_template  # noqa: WPS433
+
+    checked = guard(request)
+    if not isinstance(checked, tuple):
+        return checked
+    st, user = checked
+
+    api = build_cafe24_api(st)
+    try:
+        status = api.tokens.status()
+    except Cafe24Error as exc:
+        status = {
+            "connected": False,
+            "mall_id": api.config.mall_id,
+            "missing": api.config.missing,
+            "needs_reauth": True,
+            "reason": str(exc),
+        }
+
+    ctx = base_ctx(request, user, active_tab="system")
+    ctx.update(
+        {
+            "page_title": "카페24 — 시스템",
+            "page_subtitle": "연결 상태 · API 로그 · 작업 로그",
+            "status": status,
+            "api_version": api.config.api_version,
+            "scopes": api.config.scope_param,
+            "redirect_uri": api.config.redirect_uri,
+            "api_logs": st.list_api_logs(limit=50),
+            "audit_logs": st.list_audit_logs(limit=50),
+            "flash": request.query_params.get("msg", ""),
+            "flash_error": request.query_params.get("err", ""),
+        }
+    )
+    return render_template(request, "cafe24/system.html", ctx)
+
+
+@system_router.get("/system/oauth/start")
+def oauth_start(request: Request):
+    """카페24 인증 시작 (관리자 전용)."""
+    user = require_admin(request)
+    st = getattr(request.app.state, "cafe24_store", None)
+    if st is None:
+        return render_config_needed(request, user)
+
+    config = load_config()
+    try:
+        state = new_state()
+        url = build_authorize_url(config, state=state)
+    except Cafe24ConfigError as exc:
+        return RedirectResponse(url=f"/cafe24/system?err={exc}", status_code=303)
+
+    request.session[_STATE_KEY] = state
+    return RedirectResponse(url=url, status_code=303)
+
+
+@system_router.get("/oauth/callback")
+def oauth_callback(request: Request):
+    """카페24 콜백 — code → 토큰 교환 후 암호화 저장."""
+    user = require_admin(request)
+    st = getattr(request.app.state, "cafe24_store", None)
+    if st is None:
+        return render_config_needed(request, user)
+
+    expected = request.session.pop(_STATE_KEY, "")
+    received = request.query_params.get("state", "")
+    error = request.query_params.get("error", "")
+    code = request.query_params.get("code", "")
+
+    if error:
+        return RedirectResponse(url=f"/cafe24/system?err=카페24 인증이 취소되었습니다. ({error})", status_code=303)
+    if not expected or expected != received:
+        # state 불일치 = 위조된 콜백일 수 있다. 토큰 교환하지 않는다.
+        logger.warning("카페24 OAuth state 불일치 — 콜백 거부")
+        return RedirectResponse(
+            url="/cafe24/system?err=인증 state 가 일치하지 않습니다. 다시 시도하세요.",
+            status_code=303,
+        )
+    if not code:
+        return RedirectResponse(url="/cafe24/system?err=인증 코드가 없습니다.", status_code=303)
+
+    api = build_cafe24_api(st)
+    try:
+        bundle = exchange_code(api.config, code=code)
+        api.tokens.save_bundle(bundle, connected_by=str(user.get("email") or ""))
+    except (Cafe24AuthError, Cafe24ConfigError) as exc:
+        st.log_audit(
+            actor=str(user.get("email") or ""),
+            action="oauth_connect",
+            result="FAIL",
+            detail=str(exc),
+        )
+        return RedirectResponse(url=f"/cafe24/system?err={exc}", status_code=303)
+
+    st.log_audit(
+        actor=str(user.get("email") or ""),
+        action="oauth_connect",
+        result="SUCCESS",
+        detail=f"scopes={bundle.scopes}",
+    )
+    logger.info("카페24 연결 완료 (mall_id=%s)", api.config.mall_id)
+    return RedirectResponse(url="/cafe24/system?msg=카페24에 연결되었습니다.", status_code=303)
+
+
+@system_router.post("/system/oauth/disconnect")
+def oauth_disconnect(request: Request):
+    """저장된 토큰 삭제 (관리자 전용). 이력/예약 데이터는 지우지 않는다."""
+    user = require_admin(request)
+    st = getattr(request.app.state, "cafe24_store", None)
+    if st is None:
+        return render_config_needed(request, user)
+
+    config = load_config()
+    st.disconnect(config.mall_id)
+    st.log_audit(
+        actor=str(user.get("email") or ""),
+        action="oauth_disconnect",
+        result="SUCCESS",
+    )
+    return RedirectResponse(url="/cafe24/system?msg=카페24 연결을 해제했습니다.", status_code=303)

app/modules/cafe24/store.py

@@ -0,0 +1,441 @@
+"""카페24 모듈 순수 로직 — DB/네트워크 I/O 없음(유닛테스트 대상).
+
+상수, 상태 전이 규칙, HTML 치환/검증처럼 부수효과 없는 함수만 둔다.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import datetime, timedelta
+from urllib.parse import quote
+
+from app.timezone import KST
+
+# ── 상세페이지 버전 종류 (cafe24_product_revisions.revision_type) ──
+REVISION_SYNC = "SYNC"          # 카페24 현재값 스냅샷
+REVISION_DRAFT = "DRAFT"        # 저장만 한 초안
+REVISION_BACKUP = "BACKUP"      # 쓰기 직전 자동 백업 ← 복원 기준
+REVISION_MANUAL = "MANUAL"      # 즉시 적용
+REVISION_SCHEDULED = "SCHEDULED"  # 예약 적용
+REVISION_ROLLBACK = "ROLLBACK"  # 과거 버전 되돌림
+
+REVISION_TYPES: tuple[str, ...] = (
+    REVISION_SYNC,
+    REVISION_DRAFT,
+    REVISION_BACKUP,
+    REVISION_MANUAL,
+    REVISION_SCHEDULED,
+    REVISION_ROLLBACK,
+)
+
+REVISION_LABELS: dict[str, str] = {
+    REVISION_SYNC: "현재값 동기화",
+    REVISION_DRAFT: "초안",
+    REVISION_BACKUP: "적용 직전 자동백업",
+    REVISION_MANUAL: "즉시 적용",
+    REVISION_SCHEDULED: "예약 적용",
+    REVISION_ROLLBACK: "복원",
+}
+
+# ── 예약 상태 (cafe24_product_schedules.status) ──
+STATUS_PENDING = "PENDING"
+STATUS_PROCESSING = "PROCESSING"
+STATUS_SUCCESS = "SUCCESS"
+STATUS_FAILED = "FAILED"
+STATUS_CANCELLED = "CANCELLED"
+
+SCHEDULE_STATUSES: tuple[str, ...] = (
+    STATUS_PENDING,
+    STATUS_PROCESSING,
+    STATUS_SUCCESS,
+    STATUS_FAILED,
+    STATUS_CANCELLED,
+)
+
+SCHEDULE_STATUS_LABELS: dict[str, str] = {
+    STATUS_PENDING: "대기",
+    STATUS_PROCESSING: "실행중",
+    STATUS_SUCCESS: "완료",
+    STATUS_FAILED: "실패",
+    STATUS_CANCELLED: "취소",
+}
+
+# 사용자가 손댈 수 있는 상태 — PROCESSING/SUCCESS 는 임의 변경 금지
+EDITABLE_STATUSES: tuple[str, ...] = (STATUS_PENDING,)
+
+# 예약 실패 시 최대 재시도 횟수
+MAX_RETRY = 3
+
+# 종료 후 동작 (cafe24_product_schedules.end_action)
+END_NONE = ""
+END_RESTORE = "restore"    # 적용 직전 BACKUP 으로 복원
+END_REVISION = "revision"  # 지정한 버전 적용
+END_ACTIONS: tuple[str, ...] = (END_NONE, END_RESTORE, END_REVISION)
+
+
+def is_editable(status: str) -> bool:
+    """예약을 수정/취소할 수 있는 상태인지."""
+    return (status or "").strip().upper() in EDITABLE_STATUSES
+
+
+def can_retry(retry_count: int) -> bool:
+    """재시도 여지가 남았는지. 소진되면 FAILED 로 확정한다."""
+    try:
+        return int(retry_count) < MAX_RETRY
+    except (TypeError, ValueError):
+        return False
+
+
+def retry_backoff_seconds(retry_count: int) -> int:
+    """재시도 간격(초). 1분 → 5분 → 15분. 무한 재시도는 하지 않는다."""
+    table = (60, 300, 900)
+    try:
+        index = max(0, int(retry_count))
+    except (TypeError, ValueError):
+        index = 0
+    return table[min(index, len(table) - 1)]
+
+
+def normalize_revision_type(value: str) -> str:
+    text = (value or "").strip().upper()
+    return text if text in REVISION_TYPES else REVISION_DRAFT
+
+
+def normalize_schedule_status(value: str) -> str:
+    """DB CHECK 제약에 걸리지 않게 상태값을 정규화한다."""
+    text = (value or "").strip().upper()
+    return text if text in SCHEDULE_STATUSES else STATUS_PENDING
+
+
+def parse_product_no(value: object) -> int:
+    """상품번호 정규화. 잘못된 값이면 ValueError."""
+    try:
+        number = int(str(value).strip())
+    except (TypeError, ValueError):
+        raise ValueError("상품번호는 숫자여야 합니다.") from None
+    if number <= 0:
+        raise ValueError("상품번호는 1 이상이어야 합니다.")
+    return number
+
+
+# ════════════════════════════════════════════════════════════
+# 이미지 URL 의 한글 파일명 표시 (%EC%9A%A9… ↔ 용기…)
+#
+# 카페24는 상세페이지 HTML 안 이미지 경로를 퍼센트 인코딩해서 저장한다.
+#     src="/web/product/big/%EC%9A%A9%EA%B8%B0…(%ED%99%A9%ED%86%A0)_12.gif"
+# 사람이 읽을 수 없으니 화면에서는 한글로 풀어 보여주고, 카페24에 쓸 때는 다시
+# 원래 형식으로 되돌린다. 두 함수는 서로의 역이며 왕복이 보존돼야 한다
+# (encode(decode(원본)) == 원본).
+#
+# 안전 규칙 두 가지:
+#   1) 디코딩은 **non-ASCII 바이트(%80~%FF)** 만 한다. %20·%3C·%26 같은 ASCII
+#      이스케이프를 풀면 HTML 구조나 쿼리스트링이 깨진다.
+#   2) 인코딩은 **URL 속성값 안의 non-ASCII** 만 한다. 본문 한글 텍스트를
+#      건드리면 페이지가 깨지므로 대상 범위를 정규식으로 좁힌다.
+# ════════════════════════════════════════════════════════════
+# src="..." / href='...' 같은 URL 속성값
+_URL_ATTR_RE = re.compile(
+    r"""(?P<head>\b(?:src|href|poster|data-src|data-original)\s*=\s*(?P<q>["']))(?P<url>[^"']*)(?P=q)""",
+    re.IGNORECASE,
+)
+# CSS 의 url(...) — 인라인 <style> 안 배경 이미지
+_CSS_URL_RE = re.compile(
+    r"""(?P<head>url\(\s*(?P<q>["']?))(?P<url>[^"')]*)(?P<tail>(?P=q)\s*\))""",
+    re.IGNORECASE,
+)
+# 연속된 %XX 중 첫 바이트가 0x80 이상인 구간(= UTF-8 멀티바이트 문자)
+_NON_ASCII_PCT_RUN = re.compile(r"(?:%[89A-Fa-f][0-9A-Fa-f])+")
+# 인코딩 대상에서 제외할 문자 = 모든 ASCII 출력문자.
+# 결과적으로 non-ASCII 와 공백만 %XX 로 바뀐다. 괄호·밑줄·마침표는 카페24
+# 원본에서도 인코딩되지 않은 채 쓰이므로 반드시 그대로 남겨야 한다.
+_ASCII_SAFE = "".join(chr(code) for code in range(0x21, 0x7F))
+
+
+def _decode_pct_run(match: re.Match[str]) -> str:
+    text = match.group(0)
+    try:
+        raw = bytes(int(text[i + 1 : i + 3], 16) for i in range(0, len(text), 3))
+        return raw.decode("utf-8")
+    except (ValueError, UnicodeDecodeError):
+        # UTF-8 이 아니면(EUC-KR 등) 건드리지 않는다 — 깨뜨리는 것보다 낫다.
+        return text
+
+
+def decode_url_value(value: str) -> str:
+    return _NON_ASCII_PCT_RUN.sub(_decode_pct_run, value or "")
+
+
+def encode_url_value(value: str) -> str:
+    return quote(value or "", safe=_ASCII_SAFE, encoding="utf-8")
+
+
+def _map_urls(html: str, transform) -> str:
+    def attr(match: re.Match[str]) -> str:
+        return f"{match.group('head')}{transform(match.group('url'))}{match.group('q')}"
+
+    def css(match: re.Match[str]) -> str:
+        return f"{match.group('head')}{transform(match.group('url'))}{match.group('tail')}"
+
+    return _CSS_URL_RE.sub(css, _URL_ATTR_RE.sub(attr, html or ""))
+
+
+def decode_html_urls(html: str) -> str:
+    """화면 표시용 — URL 안 %XX(한글 등)를 원래 문자로 되돌린다."""
+    return _map_urls(html, decode_url_value)
+
+
+def encode_html_urls(html: str) -> str:
+    """카페24 저장용 — URL 안 non-ASCII 를 퍼센트 인코딩으로 되돌린다."""
+    return _map_urls(html, encode_url_value)
+
+
+# ════════════════════════════════════════════════════════════
+# 소스 정리(포맷) — 태그마다 줄을 나누고 들여쓴다.
+#
+# ⚠️ 렌더링을 바꾸지 않는 것이 최우선이다. HTML 에서 공백은 의미가 있어서,
+#    인라인 요소 사이에 줄바꿈을 넣으면 화면에 공백이 생긴다(이미지 사이가
+#    벌어지는 고전적인 사고). 그래서 **블록 요소 경계에서만** 줄을 나눈다.
+#    img·br·span·a 같은 인라인 요소와 텍스트는 원래 줄에 그대로 둔다.
+#    <style>·<script>·<pre>·<textarea> 안은 한 글자도 건드리지 않는다.
+# ════════════════════════════════════════════════════════════
+
+# 앞뒤 공백이 렌더링에 영향을 주지 않는 구조 태그만 넣는다.
+_BLOCK_TAGS = frozenset(
+    """html head body div p table thead tbody tfoot tr td th caption colgroup col
+    ul ol li dl dt dd section article header footer nav aside main
+    figure figcaption form fieldset legend h1 h2 h3 h4 h5 h6 hr center blockquote
+    style script iframe noscript""".split()
+)
+# 안쪽을 원문 그대로 보존할 태그
+_RAW_TAGS = frozenset({"style", "script", "pre", "textarea"})
+# 닫는 태그가 없는 태그
+_VOID_TAGS = frozenset(
+    "area base br col embed hr img input link meta param source track wbr".split()
+)
+# 들여쓰기가 무한히 깊어지지 않게 (닫는 태그를 생략한 HTML 이 흔하다)
+_MAX_INDENT = 12
+
+_TOKEN_RE = re.compile(
+    r"(?P<comment><!--.*?-->)"
+    r"|(?P<cdata><!\[CDATA\[.*?\]\]>)"
+    r"|(?P<decl><![^>]*>)"
+    r"|(?P<tag><(?P<slash>/?)\s*(?P<name>[a-zA-Z][\w:.-]*)"
+    r"(?P<attrs>(?:\"[^\"]*\"|'[^']*'|[^>\"'])*)>)",
+    re.DOTALL,
+)
+
+
+def format_html(html: str, *, indent: str = "  ") -> str:
+    """상세페이지 HTML 을 사람이 읽기 좋게 정리한다.
+
+    실패하면 원본을 그대로 돌려준다 — 정리보다 안 깨지는 게 중요하다.
+    같은 값을 두 번 넣어도 결과가 같다(멱등).
+    """
+    source = html or ""
+    if not source.strip():
+        return source
+    try:
+        return _format_html(source, indent)
+    except Exception:  # noqa: BLE001 — 어떤 이유로든 원본을 지키는 쪽을 택한다.
+        return source
+
+
+def _format_html(source: str, indent: str) -> str:
+    lines: list[str] = []
+    buffer = ""
+    depth = 0
+
+    def pad(level: int) -> str:
+        return indent * min(max(level, 0), _MAX_INDENT)
+
+    def flush() -> None:
+        """모아둔 인라인/텍스트를 내보낸다.
+
+        원문에 이미 있던 줄바꿈은 **그대로 살린다.** 이미지가 한 줄에 하나씩 적혀
+        있으면 그 모양이 저자의 의도이고, 한 줄로 합치면 오히려 읽기 어려워진다.
+        각 줄마다 현재 깊이로 들여쓴다(줄 앞 공백은 렌더링에 영향이 없다).
+        빈 줄은 연속 한 개까지만 남겨 구획을 유지한다.
+        """
+        nonlocal buffer
+        # 양 끝 공백을 함께 제거한다. `"\n"` 만 벗기면 끝에 남은 `"\n  "` 조각이
+        # 빈 줄로 바뀌어 실행마다 빈 줄이 하나씩 늘어난다(멱등 깨짐).
+        # 블록 태그 경계의 공백은 렌더링에 영향이 없으므로 제거해도 안전하다.
+        text = buffer.strip()
+        buffer = ""
+        if not text:
+            return
+        for raw_line in text.split("\n"):
+            line = raw_line.strip()
+            if not line:
+                # 문서 맨 앞이나 빈 줄 뒤에는 빈 줄을 더하지 않는다.
+                if lines and lines[-1] != "":
+                    lines.append("")
+                continue
+            lines.append(pad(depth) + line)
+
+    position = 0
+    while True:
+        match = _TOKEN_RE.search(source, position)
+        if match is None:
+            buffer += source[position:]
+            break
+
+        buffer += source[position : match.start()]
+        position = match.end()
+        raw = match.group(0)
+
+        # 주석·DOCTYPE 등은 흐름에 그대로 둔다.
+        # 상세페이지에는 `<!-- 대파_타임랩스 --><img ...>` 처럼 바로 뒤 요소를
+        # 설명하는 주석이 많다. 줄을 강제로 나누면 라벨과 대상이 떨어져 오히려
+        # 읽기 나빠진다. 원문에서 줄이 나뉘어 있었다면 flush 가 그 줄바꿈을 살린다.
+        if match.group("comment") or match.group("cdata") or match.group("decl"):
+            buffer += raw
+            continue
+
+        name = (match.group("name") or "").lower()
+        closing = bool(match.group("slash"))
+        self_closed = (match.group("attrs") or "").rstrip().endswith("/")
+
+        # <style>/<script>/<pre>/<textarea> 안은 원문 유지
+        if name in _RAW_TAGS and not closing:
+            end = re.compile(r"</\s*%s\s*>" % re.escape(name), re.IGNORECASE).search(
+                source, position
+            )
+            inner = source[position : end.start()] if end else source[position:]
+            flush()
+            lines.append(pad(depth) + raw)
+            # 앞뒤 빈 줄은 버린다 — 남기면 매번 실행할 때마다 한 줄씩 늘어난다(멱등 깨짐).
+            body = inner.strip("\n")
+            if body:
+                for line in body.split("\n"):
+                    lines.append(line.rstrip())
+            if end:
+                lines.append(pad(depth) + end.group(0))
+                position = end.end()
+            else:
+                position = len(source)
+            continue
+
+        # 인라인 태그와 텍스트는 줄을 나누지 않는다 (공백이 생기면 렌더링이 바뀐다)
+        if name not in _BLOCK_TAGS:
+            buffer += raw
+            continue
+
+        if closing:
+            flush()
+            depth -= 1
+            lines.append(pad(depth) + raw)
+        else:
+            flush()
+            lines.append(pad(depth) + raw)
+            if name not in _VOID_TAGS and not self_closed:
+                depth += 1
+
+    flush()
+    return "\n".join(_collapse_short_blocks(lines))
+
+
+# 짧은 블록을 한 줄로 되돌릴 때 쓰는 패턴
+_OPEN_TAG_LINE = re.compile(
+    r"^(?P<pad>\s*)<(?P<name>[a-zA-Z][\w:.-]*)(?:\"[^\"]*\"|'[^']*'|[^>\"'])*>$"
+)
+_BLOCK_TAG_IN_TEXT = re.compile(
+    r"</?(?:%s)\b" % "|".join(sorted(_BLOCK_TAGS)), re.IGNORECASE
+)
+# 한 줄로 합칠 최대 길이
+_COLLAPSE_WIDTH = 120
+
+
+def _collapse_short_blocks(lines: list[str]) -> list[str]:
+    """`<td>\n  1\n</td>` 처럼 내용이 한 줄뿐인 짧은 블록은 한 줄로 되돌린다.
+
+    보기 좋게 하려는 것이며, 합치는 규칙이 결정적이라 멱등성은 유지된다.
+    """
+    out: list[str] = []
+    index = 0
+    while index < len(lines):
+        opening = _OPEN_TAG_LINE.match(lines[index])
+        if opening and index + 2 < len(lines):
+            name = opening.group("name").lower()
+            middle = lines[index + 1].strip()
+            closing = lines[index + 2].strip()
+            merged = lines[index] + middle + closing
+            if (
+                name not in _VOID_TAGS
+                and name not in _RAW_TAGS
+                and closing.lower() == f"</{name}>"
+                and middle
+                and not _BLOCK_TAG_IN_TEXT.search(middle)
+                and len(merged) <= _COLLAPSE_WIDTH
+            ):
+                out.append(merged)
+                index += 3
+                continue
+        out.append(lines[index])
+        index += 1
+    return out
+
+
+# ════════════════════════════════════════════════════════════
+# 예약 입력 검증
+#
+# 되돌리기(자동 복원)는 쓰지 않는다. 예약은 "지정 시각에 이 내용을 적용" 뿐이다.
+# 세 가지를 각각 선택할 수 있다 — 상세페이지 HTML / 진열 / 판매.
+# ════════════════════════════════════════════════════════════
+# 화면의 select 값 → 3-상태. 빈 값·미지정이면 "변경하지 않음"(None).
+_TRISTATE: dict[str, bool] = {
+    "on": True, "off": False,
+    "t": True, "f": False,
+    "true": True, "false": False,
+    "1": True, "0": False,
+}
+
+
+def parse_tristate(value: object) -> bool | None:
+    """'on'/'off'/'' → True/False/None. 알 수 없는 값은 "변경하지 않음"으로 본다."""
+    return _TRISTATE.get(str(value or "").strip().lower())
+
+
+def parse_schedule_at(value: object, *, now: datetime | None = None) -> datetime:
+    """`datetime-local` 입력('2026-08-20T14:00') → KST aware datetime.
+
+    타임존 표기가 없으므로 KST 로 해석한다(운영 기준 시간대).
+    과거 시각은 거부한다 — worker 가 즉시 실행해버려 "예약"의 의미가 없어진다.
+    """
+    text = str(value or "").strip().replace(" ", "T")
+    if not text:
+        raise ValueError("예약 시각을 입력하세요.")
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        raise ValueError("예약 시각 형식이 올바르지 않습니다.") from None
+    aware = parsed if parsed.tzinfo else parsed.replace(tzinfo=KST)
+    current = now or datetime.now(KST)
+    # 1분 여유 — 폼을 채우는 동안 시간이 흐른 경우를 걸러내지 않기 위해.
+    if aware < current - timedelta(minutes=1):
+        raise ValueError("예약 시각이 이미 지났습니다. 앞으로의 시각을 지정하세요.")
+    return aware
+
+
+def describe_schedule_action(
+    *, has_html: bool, set_display: bool | None, set_selling: bool | None
+) -> str:
+    """예약 내용을 한 줄로 요약(목록·로그 표시용)."""
+    parts: list[str] = []
+    if has_html:
+        parts.append("상세페이지")
+    if set_display is not None:
+        parts.append("진열" if set_display else "미진열")
+    if set_selling is not None:
+        parts.append("판매" if set_selling else "판매중지")
+    return " · ".join(parts) if parts else "없음"
+
+
+def fingerprint(html: str) -> str:
+    """편집 시작 시점의 카페24 값 지문. 적용 직전 값과 비교해 충돌을 잡는다.
+
+    편집 중에 다른 사람이 카페24 관리자에서 같은 상품을 바꿨다면, 우리가 쓰는
+    순간 그 변경이 조용히 사라진다. 그것을 막기 위한 낙관적 잠금이다.
+    """
+    return hashlib.sha256((html or "").encode("utf-8")).hexdigest()[:32]

app/modules/cafe24/templates/cafe24/_editor.html

@@ -0,0 +1,211 @@
+{# 오른쪽 편집기 조각.
+   전체 페이지(products.html)가 include 하고, JS 가 /products/{no}/pane 으로
+   같은 조각만 다시 받아 끼워 넣는다. 그래서 여기에는 <script> 를 두지 않는다
+   (innerHTML 로 삽입된 script 는 실행되지 않는다 — JS 는 products.html 에 있고
+   삽입 후 cf24BindEditor() 로 다시 연결한다). #}
+
+{% if editor_error %}
+<div class="cf24-flash cf24-flash-err">
+  카페24 조회에 실패했습니다: {{ editor_error }}<br />
+  <a href="/cafe24/system">시스템 화면에서 연결 상태를 확인하세요.</a>
+</div>
+{% endif %}
+
+<div class="cf24-editor-head">
+  {# 제목 = 상품명. 연필 버튼을 누르면 입력칸으로 바뀐다(평소에는 읽기 전용 —
+     클릭만으로 실수로 고쳐지지 않게). 저장은 JS 가 POST /products/{no}/name.
+     카페24 조회에 실패했을 때(desc 없음)는 현재 이름을 믿을 수 없어 버튼을 뺀다. #}
+  <div class="cf24-name-box" id="cf24-name" data-product-no="{{ product_no }}">
+    <h3 class="cf24-editor-title" id="cf24-name-view">
+      <span id="cf24-name-text">{{ info.product_name or '상품' }}</span>
+      {% if desc %}
+      <button type="button" class="cf24-name-edit" id="cf24-name-edit"
+              title="상품명 수정 (카페24에 즉시 반영)" aria-label="상품명 수정">✎</button>
+      {% endif %}
+    </h3>
+    {% if desc %}
+    <div class="cf24-name-form is-hidden" id="cf24-name-form">
+      <input class="cf24-name-input" id="cf24-name-input" type="text" maxlength="250"
+             value="{{ info.product_name }}" aria-label="상품명" />
+      <button class="erp-btn erp-btn-primary" type="button" id="cf24-name-save">저장</button>
+      <button class="erp-btn erp-btn-outline" type="button" id="cf24-name-cancel">취소</button>
+    </div>
+    {% endif %}
+    <p class="cf24-editor-sub">
+      상품번호 {{ product_no }}
+      {% if info.product_code %}· <code>{{ info.product_code }}</code>{% endif %}
+      {% if info.price %}· {{ info.price }}{% endif %}
+      {% if info.updated_date %}· 최근 수정 {{ info.updated_date }}{% endif %}
+    </p>
+  </div>
+  {# 배지 클릭 = 진열/판매 토글. 카페24 조회에 실패했을 때(desc 없음)는 현재 상태를
+     믿을 수 없으므로 누를 수 없는 표시로만 둔다. 실제 전환은 products.html 의
+     JS 가 POST /products/{no}/status 로 처리하고 응답값으로 다시 그린다. #}
+  <div class="cf24-editor-badges" id="cf24-status" data-product-no="{{ product_no }}">
+    {% if desc %}
+    <button type="button" class="erp-badge cf24-badge-btn {{ 'cf24-badge-ok' if info.display else 'cf24-badge-off' }}"
+            data-status-field="display" data-status-on="{{ 1 if info.display else 0 }}"
+            title="클릭하면 진열 상태를 바꿉니다 (카페24에 즉시 반영)">{{ '진열' if info.display else '미진열' }}</button>
+    <button type="button" class="erp-badge cf24-badge-btn {{ 'cf24-badge-ok' if info.selling else 'cf24-badge-off' }}"
+            data-status-field="selling" data-status-on="{{ 1 if info.selling else 0 }}"
+            title="클릭하면 판매 상태를 바꿉니다 (카페24에 즉시 반영)">{{ '판매' if info.selling else '중지' }}</button>
+    {% else %}
+    {% if info.display %}<span class="erp-badge cf24-badge-ok">진열</span>
+    {% else %}<span class="erp-badge cf24-badge-off">미진열</span>{% endif %}
+    {% if info.selling %}<span class="erp-badge cf24-badge-ok">판매</span>
+    {% else %}<span class="erp-badge cf24-badge-off">중지</span>{% endif %}
+    {% endif %}
+  </div>
+</div>
+
+{# 고객이 보는 상세페이지 주소. readonly input 이라 기존 복사 버튼(data-copy)이
+   그대로 동작한다(값을 box.value 로 읽는다). #}
+{% if product_url %}
+<div class="cf24-url-row">
+  <input class="cf24-url" id="cf24-url" type="text" readonly value="{{ product_url }}"
+         onclick="this.select();" aria-label="상품 상세페이지 주소" />
+  <button class="erp-btn erp-btn-outline" type="button" data-copy="cf24-url">주소 복사</button>
+  <a class="erp-btn erp-btn-outline" href="{{ product_url }}"
+     target="_blank" rel="noopener noreferrer">쇼핑몰에서 열기</a>
+</div>
+{% endif %}
+
+{% if desc %}
+<form class="cf24-editor-form" method="post"
+      action="/cafe24/products/{{ product_no }}/apply"
+      data-confirm="카페24 쇼핑몰에 바로 반영됩니다. 적용할까요?&#10;&#10;직전 내용은 자동으로 백업되어 되돌릴 수 있습니다.">
+  <input type="hidden" name="base_fingerprint" value="{{ fingerprint }}" />
+  <input type="hidden" name="list_query" value="{{ list_query }}" />
+
+  <div class="cf24-editor-bar">
+    <span class="cf24-shortcuts">단축키: 주석토글[Ctrl+/] · 줄 복사[Alt+Shift+↑↓] · 줄 이동[Alt+↑↓] · 줄 삭제[Shift+Del]</span>
+    <span class="cf24-editor-bar-right">
+      <input class="cf24-memo" type="text" name="memo" maxlength="200"
+             placeholder="변경 메모 (버전 이력에 남습니다)" />
+      <button class="erp-btn erp-btn-outline" type="button" data-copy="cf24-html-pc">복사</button>
+      <button class="erp-btn erp-btn-outline" type="button"
+              data-reload="{{ product_no }}"
+              title="카페24에서 현재 소스를 다시 읽어옵니다. 카페24 관리자에서 방금 고쳤다면 이걸 누르세요.">다시 읽기</button>
+      <button class="erp-btn erp-btn-primary" type="submit">카페24에 적용</button>
+    </span>
+  </div>
+
+  {# 색칠된 <pre> 위에 투명한 <textarea> 를 겹쳐 문법 강조를 만든다.
+     <pre> 가 크기를 정하고 <textarea> 는 inset:0 으로 그 위를 정확히 덮는다.
+     줄바꿈을 하지 않고(wrap=off) 가로로 스크롤하므로 줄 번호가 항상 맞는다.
+     두 요소의 폰트·여백이 다르면 글자가 어긋난다 — CSS 에서 함께 관리한다. #}
+  <div class="cf24-code" id="cf24-code-pc">
+    <div class="cf24-gutter" aria-hidden="true"><div class="cf24-gutter-inner" id="cf24-gutter-pc"></div></div>
+    <div class="cf24-code-body">
+      <pre class="cf24-code-hl" id="cf24-hl-pc" aria-hidden="true"></pre>
+      {# title 툴팁은 달지 않는다 — 편집 중 마우스 옆에 뜨면 소스를 가린다.
+         단축키 안내는 위 바(cf24-shortcuts)에 항상 보인다. #}
+      <textarea id="cf24-html-pc" class="cf24-code-input" name="html" wrap="off"
+                spellcheck="false" autocapitalize="off" autocorrect="off">{{ html_pc }}</textarea>
+    </div>
+  </div>
+</form>
+
+{# 예약 — 적용 폼과 형제로 둔다(폼 중첩은 불가). 위 편집기 내용을 JS 가 hidden 에
+   복사해 함께 보낸다. 등록 시점 내용이 DRAFT 버전으로 고정되므로, 이후 편집기를
+   더 고쳐도 예약된 내용은 바뀌지 않는다. #}
+<details class="cf24-details">
+  <summary>예약 적용 — 지정한 시각에 자동 반영</summary>
+  <form class="cf24-schedule-form" id="cf24-schedule-form" method="post"
+        action="/cafe24/schedules"
+        data-confirm="지정한 시각에 자동으로 반영됩니다. 예약을 등록할까요?">
+    <input type="hidden" name="product_no" value="{{ product_no }}" />
+    <input type="hidden" name="list_query" value="{{ list_query }}" />
+    <input type="hidden" name="html" id="cf24-schedule-html" />
+
+    {# datetime-local 은 로캘·브라우저마다 표시 폭이 달라 잘리는 사고가 있었다(실제
+       발생). 날짜/시간을 별도 input 으로 나누면 각각 폭이 고정이라 잘릴 일이 없다.
+       제출 직전 JS 가 두 값을 합쳐 hidden scheduled_at 에 넣는다 — 서버(store.
+       parse_schedule_at)는 예전과 같은 'YYYY-MM-DDTHH:MM' 형식을 그대로 받으므로
+       백엔드는 변경하지 않았다. #}
+    <input type="hidden" name="scheduled_at" id="cf24-schedule-at" />
+    <div class="cf24-schedule-grid">
+      <label class="cf24-schedule-datetime">
+        <span>예약 시각</span>
+        {# 네이티브 date/time input 은 브라우저가 표시 형식을 강제한다(CSS로 못 바꿈).
+           그래서 코드 편집기와 같은 방식을 쓴다 — 투명한 네이티브 input 을 우리가
+           그린 형식화된 텍스트 위에 겹친다. 클릭·키보드·달력 팝업은 네이티브 그대로
+           동작하고, 보이는 글자만 "2026년 08월 20일"/"오후 07시 30분" 형식이다.
+           value 는 그대로 YYYY-MM-DD / HH:MM 이라 제출 시 합치는 로직은 그대로다. #}
+        <span class="cf24-schedule-datetime-row">
+          <span class="cf24-dt-field cf24-dt-field-date">
+            <span class="cf24-dt-display" id="cf24-schedule-date-display" aria-hidden="true">연도.월.일</span>
+            <input class="cf24-dt-native" type="date" id="cf24-schedule-date"
+                   aria-label="예약 날짜" required />
+          </span>
+          <span class="cf24-dt-field cf24-dt-field-time">
+            <span class="cf24-dt-display" id="cf24-schedule-time-display" aria-hidden="true">시:분</span>
+            <input class="cf24-dt-native" type="time" id="cf24-schedule-time"
+                   aria-label="예약 시간" required />
+          </span>
+        </span>
+      </label>
+      <label>
+        <span>진열</span>
+        <select class="cf24-schedule-input" name="set_display">
+          <option value="">변경 없음</option>
+          <option value="on">진열</option>
+          <option value="off">미진열</option>
+        </select>
+      </label>
+      <label>
+        <span>판매</span>
+        <select class="cf24-schedule-input" name="set_selling">
+          <option value="">변경 없음</option>
+          <option value="on">판매</option>
+          <option value="off">중지</option>
+        </select>
+      </label>
+      <label class="cf24-schedule-wide">
+        <span>메모</span>
+        <input class="cf24-schedule-input" type="text" name="memo" maxlength="200"
+               placeholder="예: 8월 프로모션 시작" />
+      </label>
+    </div>
+
+    <div class="cf24-toolbar" style="margin-top:8px;">
+      <label class="cf24-check-inline" style="margin-left:0;">
+        <input type="checkbox" name="apply_html" value="1" checked />
+        위 편집기 내용을 그 시각에 적용
+      </label>
+      <button class="erp-btn erp-btn-primary" type="submit">예약 등록</button>
+      <a class="erp-btn erp-btn-outline" href="/cafe24/schedules">예약 목록</a>
+    </div>
+    <p class="cf24-muted" style="margin:8px 0 0;">
+      진열·판매만 바꾸려면 위 체크를 해제하세요. 셋 중 하나 이상은 선택해야 합니다.
+    </p>
+  </form>
+</details>
+
+<details class="cf24-details">
+  <summary>버전 이력 {% if revisions %}({{ revisions | length }}건){% endif %}</summary>
+  {% if revisions %}
+  <div class="cf24-scroll">
+    <table class="erp-table cf24-compact">
+      <thead>
+        <tr><th>시각</th><th>유형</th><th>길이</th><th>작업자</th><th>메모</th></tr>
+      </thead>
+      <tbody>
+        {% for rev in revisions %}
+        <tr>
+          <td class="cf24-nowrap">{{ rev.created_at }}</td>
+          <td class="cf24-nowrap"><code>{{ rev.revision_type }}</code></td>
+          <td class="cf24-nowrap">{{ rev.html_length }}자</td>
+          <td class="cf24-nowrap">{{ rev.created_by or '—' }}</td>
+          <td>{{ rev.memo or '' }}</td>
+        </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+  </div>
+  <p class="cf24-muted">버전 선택 복원은 Phase 6 에서 붙습니다. 내용은 모두 보관됩니다.</p>
+  {% else %}
+  <p class="cf24-muted">아직 이 상품의 변경 이력이 없습니다.</p>
+  {% endif %}
+</details>
+{% endif %}

app/modules/cafe24/templates/cafe24/_nav.html

@@ -0,0 +1,9 @@
+{# 카페24 모듈 공용 상단 탭. active_tab: products | schedules | system #}
+<div class="erp-page-actions" style="display:flex;gap:8px;flex-wrap:wrap;align-items:center;">
+  <a class="erp-btn {% if active_tab=='products' %}erp-btn-primary{% else %}erp-btn-outline{% endif %}"
+     href="/cafe24/">상품관리</a>
+  <a class="erp-btn {% if active_tab=='schedules' %}erp-btn-primary{% else %}erp-btn-outline{% endif %}"
+     href="/cafe24/schedules">예약관리</a>
+  <a class="erp-btn {% if active_tab=='system' %}erp-btn-primary{% else %}erp-btn-outline{% endif %}"
+     href="/cafe24/system">시스템</a>
+</div>

app/modules/cafe24/templates/cafe24/products.html

@@ -0,0 +1,751 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<link rel="stylesheet" href="/static/cafe24.css?v=20260819c" />
+{% endblock %}
+
+{% block content %}
+{% include "cafe24/_nav.html" %}
+{% set qs = (list_query ~ '&') if list_query else '' %}
+
+{% if flash %}<div class="cf24-flash cf24-flash-ok">{{ flash }}</div>{% endif %}
+{% if flash_error %}<div class="cf24-flash cf24-flash-err">{{ flash_error }}</div>{% endif %}
+
+{% if error %}
+<div class="cf24-flash cf24-flash-err">
+  카페24 조회에 실패했습니다: {{ error }}<br />
+  <a href="/cafe24/system">시스템 화면에서 연결 상태를 확인하세요.</a>
+</div>
+{% endif %}
+
+<div class="cf24-split">
+
+  {# ── 왼쪽: 상품 목록 ──────────────────────────────────────── #}
+  <aside class="erp-card cf24-pane cf24-pane-list">
+    <form class="cf24-filters" method="get" action="/cafe24/" id="cf24-filter-form">
+      {# 폼이 제출됐음을 알리는 표식. 없으면 체크 해제를 "첫 방문"과 구분할 수 없다. #}
+      <input type="hidden" name="f" value="1" />
+      {% if selected %}<input type="hidden" name="selected" value="{{ selected }}" />{% endif %}
+      <input class="cf24-search" type="search" name="q" value="{{ keyword }}"
+             placeholder="상품명 검색" />
+      <div class="cf24-checks">
+        <label><input type="checkbox" name="display" value="1"
+                      {% if only_display %}checked{% endif %} /> 진열중</label>
+        <label><input type="checkbox" name="selling" value="1"
+                      {% if only_selling %}checked{% endif %} /> 판매중</label>
+      </div>
+      <div class="cf24-list-count">
+        {{ shown }}건{% if shown != total %} / 전체 {{ total }}건{% endif %}
+        {% if truncated %}<span class="cf24-warn">(상한 도달)</span>{% endif %}
+      </div>
+    </form>
+
+    <div class="cf24-list-scroll">
+      <table class="erp-table cf24-list-table" id="cf24-list">
+        <thead>
+          <tr>
+            <th class="cf24-col-no"   data-sort-key="no"      data-sort-type="num">번호</th>
+            <th class="cf24-col-name" data-sort-key="name"    data-sort-type="text">상품명</th>
+            <th class="cf24-col-flag" data-sort-key="display" data-sort-type="num">진열</th>
+            <th class="cf24-col-flag" data-sort-key="selling" data-sort-type="num">판매</th>
+            <th class="cf24-col-date" data-sort-key="updated" data-sort-type="text">수정</th>
+          </tr>
+        </thead>
+        <tbody>
+          {% for r in rows %}
+          <tr class="cf24-row {% if selected == r.product_no %}is-active{% endif %}"
+              data-no="{{ r.product_no }}"
+              data-name="{{ r.product_name }}"
+              data-display="{{ 1 if r.display else 0 }}"
+              data-selling="{{ 1 if r.selling else 0 }}"
+              data-updated="{{ r.updated_date }}">
+            <td class="cf24-col-no">{{ r.product_no }}</td>
+            <td class="cf24-col-name" title="{{ r.product_name }}">
+              <a href="/cafe24/?{{ qs }}selected={{ r.product_no }}">{{ r.product_name }}</a>
+            </td>
+            <td class="cf24-col-flag">
+              {% if r.display %}<span class="cf24-dot cf24-dot-on" title="진열중"></span>
+              {% else %}<span class="cf24-dot" title="미진열"></span>{% endif %}
+            </td>
+            <td class="cf24-col-flag">
+              {% if r.selling %}<span class="cf24-dot cf24-dot-on" title="판매중"></span>
+              {% else %}<span class="cf24-dot" title="판매중지"></span>{% endif %}
+            </td>
+            {# 연도는 생략(월-일 시:분). 전체 값은 title 로 확인 #}
+            <td class="cf24-col-date" title="{{ r.updated_date }}">{{ r.updated_date[5:16] }}</td>
+          </tr>
+          {% endfor %}
+        </tbody>
+      </table>
+      {% if not rows and not error %}
+      <p class="cf24-muted" style="padding:12px;">조건에 맞는 상품이 없습니다.</p>
+      {% endif %}
+    </div>
+  </aside>
+
+  {# ── 오른쪽: 상세페이지 편집 ──────────────────────────────── #}
+  <section class="erp-card cf24-pane cf24-pane-editor" id="cf24-editor-pane">
+    {% if selected %}
+      {% include "cafe24/_editor.html" %}
+    {% else %}
+    <div class="cf24-empty-pane">
+      <h3>왼쪽에서 상품을 선택하세요.</h3>
+      <p class="cf24-muted">
+        선택한 상품의 상세페이지 HTML 을 여기서 바로 편집하고 카페24에 적용할 수 있습니다.<br />
+        적용 직전 내용은 자동으로 백업되어 되돌릴 수 있습니다.
+      </p>
+    </div>
+    {% endif %}
+  </section>
+</div>
+{% endblock %}
+
+{% block scripts %}
+<script>
+(function () {
+  var pane = document.getElementById("cf24-editor-pane");
+  var listQuery = {{ list_query | tojson }};
+  var dirty = false;
+
+  /* ── 문법 강조 ──────────────────────────────────────────────
+     색칠된 <pre> 를 투명한 <textarea> 뒤에 겹쳐 놓는 방식. 외부 라이브러리를
+     쓰지 않는다(자체 호스팅 원칙). 태그·속성이름·속성값·주석·기호를 구분한다. */
+  var TOKEN_RE = /(<!--[\s\S]*?-->)|(<![^>]*>)|(<\/?)([a-zA-Z][\w:.-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)(>)/g;
+  var ATTR_RE = /([\w:.-]+)(?:(\s*=\s*)("[^"]*"|'[^']*'|[^\s"'>]+))?/g;
+  // 이 길이를 넘으면 강조를 끈다 — 타이핑마다 다시 칠하면 느려진다.
+  var HL_LIMIT = 200000;
+
+  function esc(text) {
+    return text.replace(/[&<>]/g, function (c) {
+      return c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;";
+    });
+  }
+
+  function paintAttrs(text) {
+    return text.replace(ATTR_RE, function (whole, name, eq, val) {
+      if (!name) return esc(whole);
+      var out = '<span class="cf24-t-attr">' + esc(name) + "</span>";
+      if (eq) out += '<span class="cf24-t-pun">' + esc(eq) + "</span>";
+      if (val) out += '<span class="cf24-t-val">' + esc(val) + "</span>";
+      return out;
+    });
+  }
+
+  function paintHtml(src) {
+    var out = "", last = 0, m;
+    TOKEN_RE.lastIndex = 0;
+    while ((m = TOKEN_RE.exec(src)) !== null) {
+      out += esc(src.slice(last, m.index));
+      last = TOKEN_RE.lastIndex;
+      if (m[1]) { out += '<span class="cf24-t-com">' + esc(m[1]) + "</span>"; continue; }
+      if (m[2]) { out += '<span class="cf24-t-doc">' + esc(m[2]) + "</span>"; continue; }
+      out += '<span class="cf24-t-pun">' + esc(m[3]) + "</span>" +
+             '<span class="cf24-t-tag">' + esc(m[4]) + "</span>" +
+             paintAttrs(m[5]) +
+             '<span class="cf24-t-pun">' + esc(m[6]) + "</span>";
+    }
+    return out + esc(src.slice(last));
+  }
+
+  function setupCodeEditor() {
+    var ta = document.getElementById("cf24-html-pc");
+    var hl = document.getElementById("cf24-hl-pc");
+    var gutter = document.getElementById("cf24-gutter-pc");
+    if (!ta || !hl) return;
+
+    var timer = null;
+
+    function renderGutter(count) {
+      if (!gutter || gutter.dataset.lines === String(count)) return;
+      var out = "";
+      for (var i = 1; i <= count; i++) out += i + "\n";
+      gutter.textContent = out;
+      gutter.dataset.lines = String(count);
+    }
+
+    // 스크롤 주체는 textarea 다. 색칠 층과 줄 번호를 같은 양만큼 이동시켜
+    // 글자 위치를 맞춘다(크기를 계산해 맞추는 방식은 긴 줄에서 어긋났다).
+    function sync() {
+      var x = ta.scrollLeft, y = ta.scrollTop;
+      hl.style.transform = "translate(" + -x + "px," + -y + "px)";
+      if (gutter) gutter.style.transform = "translateY(" + -y + "px)";
+    }
+
+    function repaint() {
+      // 마지막 줄이 잘리지 않게 개행을 하나 덧붙인다(<pre> 특성).
+      if (ta.value.length > HL_LIMIT) hl.textContent = ta.value + "\n";
+      else hl.innerHTML = paintHtml(ta.value) + "\n";
+      renderGutter(ta.value.split("\n").length);
+      sync();
+    }
+
+    function refresh() {
+      // 짧은 소스는 바로 칠해야 줄 번호가 즉시 따라온다.
+      if (ta.value.length < 50000) { repaint(); return; }
+      clearTimeout(timer);
+      timer = setTimeout(repaint, 80);
+    }
+
+    /* ── 편집 단축키 공용 헬퍼 ──
+       lineRange() : 지금 선택(없으면 커서)이 걸친 **줄 전체** 범위.
+       applyEdit() : 그 범위를 새 문자열로 바꾸고 선택을 다시 잡는다. */
+
+    function lineRange() {
+      var value = ta.value;
+      var start = ta.selectionStart, end = ta.selectionEnd;
+      // 선택이 개행에서 끝나면 그 다음 줄은 대상이 아니다(드래그로 줄 끝까지
+      // 끌었을 때 아래 줄까지 딸려오는 것을 막는다).
+      if (end > start && value.charAt(end - 1) === "\n") end -= 1;
+      var from = value.lastIndexOf("\n", start - 1) + 1;
+      var to = value.indexOf("\n", end);
+      if (to === -1) to = value.length;
+      return { value: value, start: start, end: end, from: from, to: to };
+    }
+
+    function applyEdit(from, to, text, selStart, selEnd) {
+      // execCommand 로 넣어야 브라우저의 실행취소(Ctrl+Z) 이력에 남는다.
+      // 지원하지 않으면 value 를 직접 바꾼다(되돌리기만 안 될 뿐 동작은 같다).
+      var value = ta.value;
+      ta.selectionStart = from;
+      ta.selectionEnd = to;
+      var inserted = false;
+      try {
+        // 빈 문자열은 insertText 가 브라우저에 따라 무시된다 — 삭제는 delete 로.
+        inserted = text === ""
+          ? document.execCommand("delete")
+          : document.execCommand("insertText", false, text);
+      } catch (err) { inserted = false; }
+      if (!inserted) ta.value = value.slice(0, from) + text + value.slice(to);
+      ta.selectionStart = selStart;
+      ta.selectionEnd = selEnd;
+      dirty = true;
+      refresh();
+    }
+
+    /* Ctrl+/ (Mac ⌘+/) 로 HTML 주석 토글.
+       - 선택이 있으면 그 선택이 걸친 **줄 전체**가 대상이다(반쯤 걸친 줄이
+         잘려 태그가 깨지지 않게).
+       - 선택이 없으면 커서가 있는 줄 하나.
+       - 대상 안에 주석 기호가 하나라도 있으면 **제거**, 없으면 블록 전체를
+         <!-- --> 로 감싼다. HTML 주석은 중첩이 안 되므로 "이미 주석인 부분을
+         또 감싸기"를 피하는 것이 이 규칙의 이유다. */
+    var COMMENT_MARK = /<!--[ \t]?|[ \t]?-->/g;
+
+    function toggleComment() {
+      var r = lineRange();
+      var block = r.value.slice(r.from, r.to);
+      if (!block.trim()) return;   // 빈 줄에서는 아무 것도 하지 않는다
+
+      var caretIn = r.start - r.from;   // 블록 안에서의 커서 위치
+      var shift = 0, out;
+
+      COMMENT_MARK.lastIndex = 0;
+      if (COMMENT_MARK.test(block)) {
+        COMMENT_MARK.lastIndex = 0;
+        out = block.replace(COMMENT_MARK, function (mark, offset) {
+          if (offset < caretIn) shift -= mark.length;   // 커서 앞이 줄어든 만큼
+          return "";
+        });
+      } else {
+        var indent = block.match(/^[ \t]*/)[0];
+        out = indent + "<!-- " + block.slice(indent.length) + " -->";
+        shift = caretIn >= indent.length ? 5 : 0;       // "<!-- " 길이
+      }
+
+      if (r.start === r.end) {
+        var pos = r.from + Math.min(out.length, Math.max(0, caretIn + shift));
+        applyEdit(r.from, r.to, out, pos, pos);
+      } else {
+        // 바꾼 범위를 계속 선택해 둔다(연달아 다시 누르면 그대로 되돌아온다).
+        applyEdit(r.from, r.to, out, r.from, r.from + out.length);
+      }
+    }
+
+    /* Alt+↑/↓ — 커서가 있는 줄(선택이 있으면 그 줄들)을 위/아래로 옮긴다.
+       윗줄/아랫줄과 통째로 자리를 바꾸는 방식이라 줄 수는 그대로다. */
+    function moveLines(down) {
+      var r = lineRange();
+      var block = r.value.slice(r.from, r.to);
+      if (!down) {
+        if (r.from === 0) return;                       // 첫 줄 위로는 못 간다
+        var prevFrom = r.value.lastIndexOf("\n", r.from - 2) + 1;
+        var prev = r.value.slice(prevFrom, r.from - 1);
+        var up = -(prev.length + 1);
+        applyEdit(prevFrom, r.to, block + "\n" + prev, r.start + up, r.end + up);
+      } else {
+        if (r.to >= r.value.length) return;             // 마지막 줄 아래로는 못 간다
+        var nextTo = r.value.indexOf("\n", r.to + 1);
+        if (nextTo === -1) nextTo = r.value.length;
+        var next = r.value.slice(r.to + 1, nextTo);
+        var dn = next.length + 1;
+        applyEdit(r.from, nextTo, next + "\n" + block, r.start + dn, r.end + dn);
+      }
+    }
+
+    /* Alt+Shift+↑/↓ — 같은 줄을 하나 더 만든다.
+       위로 복사하면 커서는 원래 자리(위쪽 사본)에, 아래로 복사하면 새로 생긴
+       아래쪽 사본으로 옮긴다(VS Code 와 같은 느낌). */
+    function duplicateLines(down) {
+      var r = lineRange();
+      var block = r.value.slice(r.from, r.to);
+      var text = block + "\n" + block;
+      var shift = down ? block.length + 1 : 0;
+      applyEdit(r.from, r.to, text, r.start + shift, r.end + shift);
+    }
+
+    /* Shift+Delete — 커서가 있는 줄(선택이 있으면 그 줄들)을 통째로 지운다.
+       줄바꿈까지 같이 지워야 빈 줄이 남지 않는다. 마지막 줄이면 대신 앞의
+       줄바꿈을 지운다(문서 끝에 빈 줄이 생기지 않게). */
+    function deleteLines() {
+      var r = lineRange();
+      var from = r.from, to = r.to;
+      if (to < r.value.length) to += 1;
+      else if (from > 0) from -= 1;
+      if (from === to) return;                 // 빈 문서 — 지울 것이 없다
+
+      var rest = r.value.slice(0, from) + r.value.slice(to);
+      // 커서는 지운 자리로 올라온 줄의 같은 칸에 둔다(칸이 모자라면 줄 끝).
+      var lineFrom = rest.lastIndexOf("\n", from - 1) + 1;
+      var lineTo = rest.indexOf("\n", lineFrom);
+      if (lineTo === -1) lineTo = rest.length;
+      var col = Math.min(Math.max(0, r.start - r.from), lineTo - lineFrom);
+      applyEdit(from, to, "", lineFrom + col, lineFrom + col);
+    }
+
+    ta.addEventListener("scroll", sync);
+    ta.addEventListener("input", function () { dirty = true; refresh(); });
+    ta.addEventListener("keydown", function (e) {
+      // Ctrl+/ · ⌘+/ — 자판에 따라 key 가 "/" 가 아닐 수 있어 code 도 함께 본다.
+      if ((e.ctrlKey || e.metaKey) && !e.altKey &&
+          (e.key === "/" || e.code === "Slash" || e.code === "NumpadDivide")) {
+        e.preventDefault();
+        toggleComment();
+        return;
+      }
+      // Alt+↑/↓ 줄 이동, Alt+Shift+↑/↓ 줄 복사.
+      var isUp = e.key === "ArrowUp" || e.code === "ArrowUp";
+      var isDown = e.key === "ArrowDown" || e.code === "ArrowDown";
+      if (e.altKey && !e.ctrlKey && !e.metaKey && (isUp || isDown)) {
+        e.preventDefault();
+        if (e.shiftKey) duplicateLines(isDown);
+        else moveLines(isDown);
+        return;
+      }
+      // Shift+Delete — 줄 삭제. (윈도우 기본 동작인 "잘라내기"를 대신한다)
+      if (e.shiftKey && !e.ctrlKey && !e.altKey && !e.metaKey &&
+          (e.key === "Delete" || e.code === "Delete")) {
+        e.preventDefault();
+        deleteLines();
+        return;
+      }
+      // Tab 은 포커스 이동이 아니라 들여쓰기로 쓴다.
+      if (e.key !== "Tab") return;
+      e.preventDefault();
+      var start = ta.selectionStart, end = ta.selectionEnd;
+      ta.value = ta.value.slice(0, start) + "  " + ta.value.slice(end);
+      ta.selectionStart = ta.selectionEnd = start + 2;
+      dirty = true;
+      refresh();
+    });
+
+    repaint();
+  }
+
+  // ── 편집기 조각을 새로 끼워 넣은 뒤 다시 연결 ──
+  window.cf24BindEditor = function () {
+    dirty = false;
+    setupCodeEditor();
+
+    pane.querySelectorAll("[data-copy]").forEach(function (btn) {
+      btn.addEventListener("click", function () {
+        var box = document.getElementById(btn.dataset.copy);
+        if (!box) return;
+        var done = function () {
+          var old = btn.textContent;
+          btn.textContent = "복사됨";
+          setTimeout(function () { btn.textContent = old; }, 1500);
+        };
+        if (navigator.clipboard && window.isSecureContext) {
+          navigator.clipboard.writeText(box.value).then(done, function () { box.select(); });
+        } else {
+          box.select();
+          try { document.execCommand("copy"); done(); } catch (e) { /* 직접 복사 */ }
+        }
+      });
+    });
+
+    // 「다시 읽기」 — 카페24 관리자에서 방금 고친 경우 현재 소스를 강제로 다시 받는다.
+    var reloadBtn = pane.querySelector("[data-reload]");
+    if (reloadBtn) {
+      reloadBtn.addEventListener("click", function () {
+        confirmLeave().then(function (ok) {
+          if (ok) select(reloadBtn.dataset.reload, false);
+        });
+      });
+    }
+
+    // 예약 시각 — 네이티브 date/time input 은 투명하게 두고(opacity:0), 보이는
+    // 글자는 우리가 원하는 형식으로 직접 그린다("2026년 08월 20일" / "오후 07시 30분").
+    // input 의 value 자체는 그대로 YYYY-MM-DD / HH:MM 이라 제출 로직은 안 바뀐다.
+    (function setupScheduleDateTime() {
+      var dateEl = document.getElementById("cf24-schedule-date");
+      var timeEl = document.getElementById("cf24-schedule-time");
+      var dateOut = document.getElementById("cf24-schedule-date-display");
+      var timeOut = document.getElementById("cf24-schedule-time-display");
+      if (!dateEl || !timeEl) return;
+
+      var WEEKDAY = ["일", "월", "화", "수", "목", "금", "토"];
+
+      function pad2(n) { return (n < 10 ? "0" : "") + n; }
+
+      function paintDate() {
+        var v = dateEl.value; // "YYYY-MM-DD"
+        if (!v) { dateOut.textContent = "연도.월.일"; return; }
+        var p = v.split("-");
+        var y = parseInt(p[0], 10), mo = parseInt(p[1], 10), d = parseInt(p[2], 10);
+        // new Date(y, mo-1, d) 는 로컬 시간대로 만들어져 날짜가 밀리지 않는다
+        // (문자열을 그대로 new Date("YYYY-MM-DD") 로 파싱하면 UTC 로 해석돼 하루
+        // 어긋날 수 있다).
+        var weekday = WEEKDAY[new Date(y, mo - 1, d).getDay()];
+        dateOut.textContent = p[0] + "년 " + p[1] + "월 " + p[2] + "일 (" + weekday + ")";
+      }
+
+      function paintTime() {
+        var v = timeEl.value; // "HH:MM" (24시간제 고정 — 로캘과 무관)
+        if (!v) { timeOut.textContent = "시:분"; return; }
+        var parts = v.split(":");
+        var h = parseInt(parts[0], 10);
+        var period = h < 12 ? "오전" : "오후";
+        var h12 = h % 12;
+        if (h12 === 0) h12 = 12;
+        timeOut.textContent = period + " " + pad2(h12) + "시 " + parts[1] + "분";
+      }
+
+      // 네이티브 달력/시간 팝업은 브라우저가 자체 아이콘(우측 끝) 클릭에만 반응하고
+      // 칸 전체 클릭에는 반응하지 않는다. showPicker() 를 직접 호출해 칸 어디를
+      // 클릭해도 팝업이 뜨게 한다. 지원하지 않는 브라우저에서는 조용히 무시되고
+      // 포커스만 이동한다(기존 동작 그대로 유지되므로 안전).
+      function openPicker(el) {
+        if (typeof el.showPicker === "function") {
+          try { el.showPicker(); } catch (err) { /* 사용자 제스처 밖 호출 등 — 무시 */ }
+        }
+      }
+      dateEl.addEventListener("click", function () { openPicker(dateEl); });
+      timeEl.addEventListener("click", function () { openPicker(timeEl); });
+
+      dateEl.addEventListener("input", paintDate);
+      dateEl.addEventListener("change", paintDate);
+      timeEl.addEventListener("input", paintTime);
+      timeEl.addEventListener("change", paintTime);
+      paintDate();
+      paintTime();
+    })();
+
+    // 예약 폼 — 편집기 내용을 hidden 에 복사해 함께 보낸다(폼이 서로 형제라서).
+    // 날짜·시간도 두 개의 별도 input 값을 합쳐 서버가 기대하는 형식으로 만든다.
+    var schedForm = pane.querySelector("#cf24-schedule-form");
+    if (schedForm) {
+      schedForm.addEventListener("submit", function (e) {
+        var box = document.getElementById("cf24-html-pc");
+        var holder = document.getElementById("cf24-schedule-html");
+        var wantHtml = schedForm.querySelector('[name="apply_html"]').checked;
+        if (holder && box) holder.value = wantHtml ? box.value : "";
+
+        var dateEl = document.getElementById("cf24-schedule-date");
+        var timeEl = document.getElementById("cf24-schedule-time");
+        var atHolder = document.getElementById("cf24-schedule-at");
+        // date/time 이 필수(required)라 브라우저가 빈 값이면 여기까지 오지 않는다.
+        if (atHolder && dateEl && timeEl) atHolder.value = dateEl.value + "T" + timeEl.value;
+
+        // 확인창이 비동기라 일단 제출을 멈추고, 확인을 받으면 다시 보낸다.
+        // (required 검사는 이미 통과한 뒤라 form.submit() 으로 보내도 안전하다)
+        e.preventDefault();
+        window.erpConfirm(schedForm.dataset.confirm).then(function (ok) {
+          if (!ok) return;
+          dirty = false;   // 예약 등록으로 화면을 떠나므로 편집 중 경고를 끈다.
+          schedForm.submit();
+        });
+      });
+    }
+
+    // ── 상품명 수정 ──
+    // 연필 → 입력칸, 저장 시 POST /products/{no}/name. 서버가 쓰기 전에 카페24
+    // 현재값을 읽어 이전 이름을 감사로그에 남긴다.
+    (function setupRename() {
+      var box = pane.querySelector("#cf24-name");
+      var form = box && box.querySelector("#cf24-name-form");
+      if (!box || !form) return;   // 조회 실패 시엔 수정 버튼 자체가 없다
+      var no = box.dataset.productNo;
+      var view = box.querySelector("#cf24-name-view");
+      var text = box.querySelector("#cf24-name-text");
+      var input = box.querySelector("#cf24-name-input");
+      var saveBtn = box.querySelector("#cf24-name-save");
+      var cancelBtn = box.querySelector("#cf24-name-cancel");
+
+      function open(on) {
+        view.classList.toggle("is-hidden", on);
+        form.classList.toggle("is-hidden", !on);
+        if (on) { input.value = text.textContent; input.focus(); input.select(); }
+      }
+
+      // 왼쪽 목록도 다시 받지 않으므로 같은 상품 행의 이름·정렬키를 직접 맞춘다.
+      function paintRow(name) {
+        var tr = document.querySelector('#cf24-list tr.cf24-row[data-no="' + no + '"]');
+        if (!tr) return;
+        tr.dataset.name = name;
+        var cell = tr.querySelector(".cf24-col-name");
+        if (!cell) return;
+        cell.title = name;
+        var link = cell.querySelector("a");
+        (link || cell).textContent = name;
+      }
+
+      function busy(state) {
+        saveBtn.disabled = state;
+        cancelBtn.disabled = state;
+        input.disabled = state;
+      }
+
+      function save() {
+        var name = input.value.trim();
+        if (!name) {
+          window.erpAlert("상품명을 입력하세요.").then(function () { input.focus(); });
+          return;
+        }
+        if (name === text.textContent) { open(false); return; }
+        window.erpConfirm("상품명을 「" + name + "」(으)로 바꿉니다.\n카페24 쇼핑몰에 바로 반영됩니다. 계속할까요?")
+          .then(function (ok) { if (ok) send(name); });
+      }
+
+      function send(name) {
+        busy(true);
+        fetch("/cafe24/products/" + no + "/name", {
+          method: "POST",
+          credentials: "same-origin",
+          cache: "no-store",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ name: name })
+        })
+          .then(function (res) {
+            return res.json().catch(function () { return {}; }).then(function (data) {
+              if (!res.ok) throw new Error(data.detail || "HTTP " + res.status);
+              return data;
+            });
+          })
+          .then(function (data) {
+            // 화면은 요청값이 아니라 카페24가 확인해 준 이름으로 그린다.
+            var applied = data.product_name || name;
+            text.textContent = applied;
+            input.value = applied;
+            paintRow(applied);
+            open(false);
+          })
+          .catch(function (err) {
+            window.erpAlert("상품명 변경에 실패했습니다: " + err.message);
+          })
+          .then(function () { busy(false); });
+      }
+
+      box.querySelector("#cf24-name-edit").addEventListener("click", function () { open(true); });
+      cancelBtn.addEventListener("click", function () { open(false); });
+      saveBtn.addEventListener("click", save);
+      input.addEventListener("keydown", function (e) {
+        if (e.key === "Enter") { e.preventDefault(); save(); }
+        else if (e.key === "Escape") { e.preventDefault(); open(false); }
+      });
+    })();
+
+    // ── 진열/판매 배지 클릭 = 상태 토글 ──
+    // 쓰기는 서버가 한다(POST /products/{no}/status). 화면은 **응답에 담긴 실제
+    // 상태**로 다시 그린다 — 요청값을 낙관적으로 반영하면 실패했을 때 화면과
+    // 카페24가 어긋난다.
+    (function setupStatusToggle() {
+      var box = pane.querySelector("#cf24-status");
+      if (!box) return;
+      var no = box.dataset.productNo;
+      var LABEL = {
+        display: { word: "진열", on: "진열", off: "미진열", dotOn: "진열중", dotOff: "미진열" },
+        selling: { word: "판매", on: "판매", off: "중지", dotOn: "판매중", dotOff: "판매중지" }
+      };
+      var buttons = box.querySelectorAll("[data-status-field]");
+
+      function paint(btn, on) {
+        var label = LABEL[btn.dataset.statusField];
+        btn.dataset.statusOn = on ? "1" : "0";
+        btn.textContent = on ? label.on : label.off;
+        btn.classList.toggle("cf24-badge-ok", on);
+        btn.classList.toggle("cf24-badge-off", !on);
+      }
+
+      // 왼쪽 목록은 다시 불러오지 않으므로 같은 상품 행의 점도 직접 맞춘다.
+      // data-display/data-selling 은 정렬 기준이라 함께 갱신한다.
+      function paintRow(state) {
+        var tr = document.querySelector('#cf24-list tr.cf24-row[data-no="' + no + '"]');
+        if (!tr) return;
+        ["display", "selling"].forEach(function (field, i) {
+          var on = !!state[field];
+          var label = LABEL[field];
+          tr.dataset[field] = on ? "1" : "0";
+          var dot = tr.querySelectorAll(".cf24-dot")[i];
+          if (!dot) return;
+          dot.classList.toggle("cf24-dot-on", on);
+          dot.title = on ? label.dotOn : label.dotOff;
+        });
+      }
+
+      function busy(state) {
+        buttons.forEach(function (b) { b.disabled = state; });
+      }
+
+      buttons.forEach(function (btn) {
+        btn.addEventListener("click", function () {
+          var field = btn.dataset.statusField;
+          var label = LABEL[field];
+          var want = btn.dataset.statusOn !== "1";
+          var msg = label.word + " 상태를 「" + (want ? label.on : label.off) + "」(으)로 바꿉니다.\n" +
+                    "카페24 쇼핑몰에 바로 반영됩니다. 계속할까요?";
+          window.erpConfirm(msg).then(function (ok) { if (ok) send(field, want); });
+        });
+      });
+
+      function send(field, want) {
+        busy(true);
+        fetch("/cafe24/products/" + no + "/status", {
+          method: "POST",
+          credentials: "same-origin",
+          cache: "no-store",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ field: field, value: want })
+        })
+          .then(function (res) {
+            return res.json().catch(function () { return {}; }).then(function (data) {
+              if (!res.ok) throw new Error(data.detail || "HTTP " + res.status);
+              return data;
+            });
+          })
+          .then(function (data) {
+            buttons.forEach(function (b) { paint(b, !!data[b.dataset.statusField]); });
+            paintRow(data);
+          })
+          .catch(function (err) {
+            window.erpAlert("상태 변경에 실패했습니다: " + err.message);
+          })
+          .then(function () { busy(false); });
+      }
+    })();
+
+    var form = pane.querySelector(".cf24-editor-form");
+    if (form) {
+      form.addEventListener("submit", function (e) {
+        e.preventDefault();
+        window.erpConfirm(form.dataset.confirm).then(function (ok) {
+          if (!ok) return;
+          dirty = false;
+          form.submit();
+        });
+      });
+    }
+  };
+
+  // 공용 확인창(erp-dialog.js)은 비동기다 — 기본 confirm() 과 달리 Promise 를
+  // 돌려주므로 호출부는 모두 then() 안에서 이어간다.
+  function confirmLeave() {
+    if (!dirty) return Promise.resolve(true);
+    return window.erpConfirm("편집한 내용이 저장되지 않았습니다. 이동할까요?");
+  }
+
+  // ── 목록 클릭 → 오른쪽만 교체 ──
+  function select(no, push) {
+    pane.innerHTML = '<p class="cf24-muted" style="padding:16px;">불러오는 중…</p>';
+    var url = "/cafe24/products/" + no + "/pane" + (listQuery ? "?" + listQuery : "");
+    // no-store: 캐시된 조각이 뜨면 카페24의 현재 소스가 아닌 예전 것을 편집하게 된다.
+    fetch(url, { credentials: "same-origin", cache: "no-store" })
+      .then(function (res) {
+        if (res.redirected) { window.location.href = res.url; return null; }
+        if (!res.ok) throw new Error("HTTP " + res.status);
+        return res.text();
+      })
+      .then(function (htmlText) {
+        if (htmlText === null) return;
+        pane.innerHTML = htmlText;
+        window.cf24BindEditor();
+        pane.scrollTop = 0;
+        if (push) {
+          var target = "/cafe24/?" + (listQuery ? listQuery + "&" : "") + "selected=" + no;
+          history.pushState({ no: no }, "", target);
+        }
+      })
+      .catch(function () {
+        // 조각 로드가 실패하면 평범한 페이지 이동으로 대체한다.
+        window.location.href = "/cafe24/?" + (listQuery ? listQuery + "&" : "") + "selected=" + no;
+      });
+  }
+
+  document.querySelectorAll("#cf24-list tbody tr.cf24-row").forEach(function (tr) {
+    tr.addEventListener("click", function (e) {
+      if (e.target.tagName === "A") e.preventDefault();
+      confirmLeave().then(function (ok) {
+        if (!ok) return;
+        document.querySelectorAll("#cf24-list tr.is-active").forEach(function (el) {
+          el.classList.remove("is-active");
+        });
+        tr.classList.add("is-active");
+        select(tr.dataset.no, true);
+      });
+    });
+  });
+
+  window.addEventListener("popstate", function () {
+    window.location.reload();
+  });
+
+  // ── 필터 체크박스는 즉시 적용 ──
+  var filterForm = document.getElementById("cf24-filter-form");
+  filterForm.querySelectorAll('input[type="checkbox"]').forEach(function (cb) {
+    cb.addEventListener("change", function () {
+      confirmLeave().then(function (ok) {
+        // 확인창이 비동기라 체크는 이미 바뀌어 있다 — 취소하면 되돌린다.
+        if (ok) filterForm.submit();
+        else cb.checked = !cb.checked;
+      });
+    });
+  });
+
+  // ── 제목행 클릭 정렬(오름/내림 토글) ──
+  var table = document.getElementById("cf24-list");
+  var tbody = table.querySelector("tbody");
+  var sortKey = null, sortAsc = true;
+
+  table.querySelectorAll("th[data-sort-key]").forEach(function (th) {
+    th.classList.add("cf24-sortable");
+    th.addEventListener("click", function () {
+      var key = th.dataset.sortKey;
+      sortAsc = key === sortKey ? !sortAsc : true;
+      sortKey = key;
+
+      table.querySelectorAll("th[data-sort-key]").forEach(function (other) {
+        other.classList.remove("is-asc", "is-desc");
+      });
+      th.classList.add(sortAsc ? "is-asc" : "is-desc");
+
+      var numeric = th.dataset.sortType === "num";
+      var rows = Array.prototype.slice.call(tbody.querySelectorAll("tr.cf24-row"));
+      rows.sort(function (a, b) {
+        var x = a.dataset[key] || "", y = b.dataset[key] || "";
+        var cmp = numeric
+          ? (parseFloat(x) || 0) - (parseFloat(y) || 0)
+          : x.localeCompare(y, "ko");
+        return sortAsc ? cmp : -cmp;
+      });
+      rows.forEach(function (tr) { tbody.appendChild(tr); });
+    });
+  });
+
+  window.addEventListener("beforeunload", function (e) {
+    if (dirty) { e.preventDefault(); e.returnValue = ""; }
+  });
+
+  if (pane.querySelector(".cf24-editor-form")) window.cf24BindEditor();
+})();
+</script>
+{% endblock %}

app/modules/cafe24/templates/cafe24/schedules.html

@@ -0,0 +1,81 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<link rel="stylesheet" href="/static/cafe24.css?v=20260819c" />
+{% endblock %}
+
+{% block content %}
+{% include "cafe24/_nav.html" %}
+
+{% if flash %}<div class="cf24-flash cf24-flash-ok">{{ flash }}</div>{% endif %}
+{% if flash_error %}<div class="cf24-flash cf24-flash-err">{{ flash_error }}</div>{% endif %}
+
+<div class="erp-card cf24-card">
+  <div class="cf24-card-head">
+    <h3>예약 목록</h3>
+    <span class="cf24-muted">대기 {{ pending }}건 · 최근 200건</span>
+  </div>
+
+  <p class="cf24-note">
+    예약은 <strong>상품관리 화면의 편집기 아래 「예약 적용」</strong> 에서 등록합니다.
+    지정한 시각에 <code>dbx-cafe24-worker</code> 가 적용하므로 브라우저를 닫아도 실행됩니다.
+    적용 직전 내용은 상품별 <code>BACKUP</code> 버전으로 보관됩니다.
+    <strong>대기</strong> 상태인 예약만 취소할 수 있습니다.
+  </p>
+
+  {% if rows %}
+  <div class="cf24-scroll">
+    <table class="erp-table cf24-compact">
+      <thead>
+        <tr>
+          <th style="width:56px;">번호</th>
+          <th style="width:130px;">예정 시각</th>
+          <th style="width:66px;">상품</th>
+          <th>상품명</th>
+          <th style="width:150px;">적용 내용</th>
+          <th style="width:96px;">상태</th>
+          <th>메모 / 오류</th>
+          <th style="width:130px;">등록자</th>
+          <th style="width:60px;"></th>
+        </tr>
+      </thead>
+      <tbody>
+        {% for r in rows %}
+        <tr>
+          <td class="cf24-nowrap">#{{ r.id }}</td>
+          <td class="cf24-nowrap">{{ (r.scheduled_at or '')[:16] | replace("T", " ") }}</td>
+          <td class="cf24-nowrap">
+            <a href="/cafe24/?selected={{ r.product_no }}">{{ r.product_no }}</a>
+          </td>
+          <td>{{ r.product_name or '—' }}</td>
+          <td class="cf24-nowrap">{{ r.action_label }}</td>
+          <td class="cf24-nowrap">
+            {% if r.status == 'SUCCESS' %}<span class="erp-badge cf24-badge-ok">{{ r.status_label }}</span>
+            {% elif r.status == 'FAILED' %}<span class="cf24-err">{{ r.status_label }}</span>
+            {% elif r.status == 'PENDING' %}<span class="cf24-warn">{{ r.status_label }}</span>
+            {% else %}<span class="cf24-muted">{{ r.status_label }}</span>{% endif %}
+            {% if r.retry_count %}<span class="cf24-muted">({{ r.retry_count }}회)</span>{% endif %}
+          </td>
+          <td>
+            {{ r.memo or '' }}
+            {% if r.last_error %}<div class="cf24-err">{{ r.last_error }}</div>{% endif %}
+          </td>
+          <td class="cf24-nowrap">{{ r.created_by or '—' }}</td>
+          <td class="cf24-nowrap">
+            {% if r.editable %}
+            <form method="post" action="/cafe24/schedules/{{ r.id }}/cancel" style="display:inline;"
+                  data-erp-confirm="예약 #{{ r.id }} 을 취소할까요?">
+              <button type="submit" class="erp-btn erp-btn-outline">취소</button>
+            </form>
+            {% endif %}
+          </td>
+        </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+  </div>
+  {% else %}
+  <p class="cf24-muted">등록된 예약이 없습니다. 상품관리 화면에서 상품을 고른 뒤 편집기 아래에서 예약할 수 있습니다.</p>
+  {% endif %}
+</div>
+{% endblock %}

app/modules/cafe24/templates/cafe24/system.html

@@ -0,0 +1,137 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<link rel="stylesheet" href="/static/cafe24.css?v=20260819c" />
+{% endblock %}
+
+{% block content %}
+{% include "cafe24/_nav.html" %}
+
+{% if flash %}<div class="cf24-flash cf24-flash-ok">{{ flash }}</div>{% endif %}
+{% if flash_error %}<div class="cf24-flash cf24-flash-err">{{ flash_error }}</div>{% endif %}
+
+{# ── 연결 상태 ───────────────────────────────────────────── #}
+<div class="erp-card cf24-card">
+  <div class="cf24-card-head">
+    <h3>카페24 연결</h3>
+    {% if status.connected %}
+      <span class="erp-badge cf24-badge-ok">연결됨</span>
+    {% else %}
+      <span class="erp-badge cf24-badge-off">연결 안 됨</span>
+    {% endif %}
+  </div>
+
+  {% if status.missing %}
+  <div class="cf24-flash cf24-flash-err">
+    다음 환경변수가 설정되지 않았습니다:
+    <code>{{ status.missing | join(', ') }}</code><br />
+    <code>.env</code> 에 추가한 뒤 컨테이너를 재기동하세요.
+  </div>
+  {% endif %}
+
+  {% if status.reason %}<p class="cf24-muted">{{ status.reason }}</p>{% endif %}
+
+  <table class="erp-table cf24-kv">
+    <tbody>
+      <tr><th>쇼핑몰 ID</th><td>{{ status.mall_id or '—' }}</td></tr>
+      <tr><th>API 버전</th><td>{{ api_version }}</td></tr>
+      <tr><th>요청 권한(scope)</th><td><code>{{ scopes }}</code></td></tr>
+      <tr><th>Redirect URI</th><td><code>{{ redirect_uri or '—' }}</code></td></tr>
+      <tr>
+        <th>승인된 권한</th>
+        <td>{% if status.scopes %}<code>{{ status.scopes }}</code>{% else %}—{% endif %}</td>
+      </tr>
+      <tr>
+        <th>Access Token 만료</th>
+        <td>
+          {{ status.access_token_expires_at or '—' }}
+          {% if status.access_expired %}<span class="cf24-muted">(만료 — 다음 호출 시 자동 갱신)</span>{% endif %}
+        </td>
+      </tr>
+      <tr><th>Refresh Token 만료</th><td>{{ status.refresh_token_expires_at or '—' }}</td></tr>
+      <tr><th>마지막 갱신</th><td>{{ status.last_refreshed_at or '—' }}</td></tr>
+      <tr><th>연결한 사람</th><td>{{ status.connected_by or '—' }}</td></tr>
+      {% if status.last_error %}
+      <tr><th>마지막 오류</th><td class="cf24-err">{{ status.last_error }}</td></tr>
+      {% endif %}
+    </tbody>
+  </table>
+
+  {% if is_admin %}
+  <div class="cf24-actions">
+    <a class="erp-btn erp-btn-primary" href="/cafe24/system/oauth/start">
+      {% if status.connected %}카페24 재연결{% else %}카페24 연결{% endif %}
+    </a>
+    {% if status.connected or status.needs_reauth %}
+    <form method="post" action="/cafe24/system/oauth/disconnect" style="display:inline;"
+          data-erp-confirm="저장된 카페24 토큰을 삭제합니다. 계속할까요?&#10;(변경 이력·예약 데이터는 지워지지 않습니다)">
+      <button type="submit" class="erp-btn erp-btn-outline">연결 해제</button>
+    </form>
+    {% endif %}
+  </div>
+  {% else %}
+  <p class="cf24-muted">카페24 연결 변경은 관리자만 할 수 있습니다.</p>
+  {% endif %}
+</div>
+
+{# ── 작업 로그 ───────────────────────────────────────────── #}
+<div class="erp-card cf24-card">
+  <div class="cf24-card-head"><h3>작업 로그</h3><span class="cf24-muted">최근 50건</span></div>
+  {% if audit_logs %}
+  <div class="cf24-scroll">
+    <table class="erp-table">
+      <thead>
+        <tr><th>시각</th><th>작업자</th><th>작업</th><th>상품</th><th>결과</th><th>내용</th></tr>
+      </thead>
+      <tbody>
+        {% for log in audit_logs %}
+        <tr>
+          <td class="cf24-nowrap">{{ log.created_at }}</td>
+          <td>{{ log.actor or '—' }}</td>
+          <td>{{ log.action }}</td>
+          <td>{{ log.product_no or '—' }}</td>
+          <td class="{% if log.result == 'FAIL' %}cf24-err{% endif %}">{{ log.result or '—' }}</td>
+          <td>{{ log.detail or '' }}</td>
+        </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+  </div>
+  {% else %}
+  <p class="cf24-muted">아직 기록된 작업이 없습니다.</p>
+  {% endif %}
+</div>
+
+{# ── API 로그 ────────────────────────────────────────────── #}
+<div class="erp-card cf24-card">
+  <div class="cf24-card-head">
+    <h3>카페24 API 로그</h3>
+    <span class="cf24-muted">최근 50건 · 토큰/시크릿은 기록하지 않습니다</span>
+  </div>
+  {% if api_logs %}
+  <div class="cf24-scroll">
+    <table class="erp-table">
+      <thead>
+        <tr><th>시각</th><th>메서드</th><th>엔드포인트</th><th>상품</th><th>상태</th><th>결과</th><th>소요</th><th>오류</th></tr>
+      </thead>
+      <tbody>
+        {% for log in api_logs %}
+        <tr>
+          <td class="cf24-nowrap">{{ log.created_at }}</td>
+          <td>{{ log.method }}</td>
+          <td><code>{{ log.endpoint }}</code></td>
+          <td>{{ log.product_no or '—' }}</td>
+          <td>{{ log.http_status or '—' }}</td>
+          <td class="{% if log.result != 'SUCCESS' %}cf24-err{% endif %}">{{ log.result }}</td>
+          <td class="cf24-nowrap">{{ log.duration_ms }}ms</td>
+          <td>{{ log.error_message or '' }}</td>
+        </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+  </div>
+  {% else %}
+  <p class="cf24-muted">아직 API 호출 기록이 없습니다.</p>
+  {% endif %}
+</div>
+{% endblock %}

app/modules/cafe24/tests/test_cafe24.py

@@ -0,0 +1,790 @@
+"""카페24 모듈 순수 로직 + 토큰/암호화 테스트.
+
+DB/네트워크 없이 검증한다(가짜 저장소 + refresh 함수 주입).
+    python -m app.modules.cafe24.tests.test_cafe24
+또는 pytest 로 실행 가능.
+"""
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from datetime import timedelta
+
+from app.integrations.cafe24 import config as cfgmod
+from app.integrations.cafe24 import crypto, oauth, products, tokens
+from app.integrations.cafe24.errors import Cafe24ApiError, Cafe24AuthError, Cafe24ConfigError
+from app.modules.cafe24 import store, worker
+from app.timezone import now_kst
+
+SECRET = "unit-test-secret"
+
+_TEST_ENV = {
+    "CAFE24_MALL_ID": "testmall",
+    "CAFE24_CLIENT_ID": "cid",
+    "CAFE24_CLIENT_SECRET": "csecret",
+    "CAFE24_REDIRECT_URI": "http://localhost:8080/cafe24/oauth/callback",
+    "CAFE24_TOKEN_SECRET": SECRET,
+}
+
+
+def _config():
+    """환경변수에 의존하지 않도록 테스트용 값을 주입해 설정을 만든다."""
+    saved = {k: os.environ.get(k) for k in _TEST_ENV}
+    os.environ.update(_TEST_ENV)
+    try:
+        return cfgmod.load_config()
+    finally:
+        for key, value in saved.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+
+
+class _FakeRepo:
+    """Cafe24Store 의 토큰 3개 메서드만 흉내낸다."""
+
+    def __init__(self, row=None):
+        self.row = row
+        self.saves: list[dict] = []
+
+    def get_token_row(self, mall_id):
+        return self.row
+
+    def save_token_row(self, *, mall_id, **fields):
+        self.saves.append(fields)
+        if self.row is None:
+            self.row = {"mall_id": mall_id}
+        self.row.update(fields)
+
+    @contextmanager
+    def token_lock(self, mall_id):
+        outer = self
+
+        class Handle:
+            row = outer.row
+
+            def save(self, **fields):
+                outer.save_token_row(mall_id=mall_id, **fields)
+
+        yield Handle()
+
+
+def _row(**overrides):
+    row = {
+        "mall_id": "testmall",
+        "access_token": crypto.encrypt("AT", secret=SECRET),
+        "refresh_token": crypto.encrypt("RT", secret=SECRET),
+        "access_token_expires_at": now_kst() + timedelta(hours=1),
+        "refresh_token_expires_at": now_kst() + timedelta(days=13),
+        "scopes": "mall.read_product,mall.write_product",
+        "last_refreshed_at": now_kst(),
+        "last_error": "",
+        "connected_by": "king@dbxcorp.co.kr",
+    }
+    row.update(overrides)
+    return row
+
+
+# ════════════════════════════════════════════════════════════
+# 암호화
+# ════════════════════════════════════════════════════════════
+def test_crypto_roundtrip():
+    token = "ACCESS-TOKEN-한글-123"
+    encrypted = crypto.encrypt(token, secret=SECRET)
+    assert encrypted != token and token not in encrypted
+    assert crypto.decrypt(encrypted, secret=SECRET) == token
+
+
+def test_crypto_empty_passthrough():
+    assert crypto.encrypt("", secret=SECRET) == ""
+    assert crypto.decrypt("", secret=SECRET) == ""
+
+
+def test_crypto_wrong_secret_raises():
+    encrypted = crypto.encrypt("AT", secret=SECRET)
+    try:
+        crypto.decrypt(encrypted, secret="다른키")
+    except Cafe24ConfigError:
+        return
+    raise AssertionError("키가 바뀌면 Cafe24ConfigError 가 나야 한다")
+
+
+def test_crypto_requires_secret():
+    try:
+        crypto.encrypt("x", secret="")
+    except Cafe24ConfigError:
+        return
+    raise AssertionError("CAFE24_TOKEN_SECRET 없으면 예외여야 한다")
+
+
+# ════════════════════════════════════════════════════════════
+# 설정 / 인증 URL
+# ════════════════════════════════════════════════════════════
+def test_config_basics():
+    config = _config()
+    assert config.configured
+    assert config.missing == []
+    assert config.api_base == "https://testmall.cafe24api.com/api/v2"
+    # 요청 scope 는 DEFAULT_SCOPES 한 곳에서 나온다(authorize 와 클라이언트가
+    # 어긋나지 않게). 늘어날 때 이 테스트도 함께 갱신할 것.
+    assert config.scope_param == ",".join(cfgmod.DEFAULT_SCOPES)
+    assert "mall.read_product" in config.scope_param
+    assert "mall.write_product" in config.scope_param
+
+
+def test_product_url_uses_shop_url_env():
+    """다이렉트 주소는 CAFE24_SHOP_URL 기준. 스킴·끝 슬래시가 없어도 맞춘다."""
+    saved = os.environ.get("CAFE24_SHOP_URL")
+    try:
+        for value in ("https://miras.co.kr", "miras.co.kr", "https://miras.co.kr/"):
+            os.environ["CAFE24_SHOP_URL"] = value
+            config = _config()
+            assert (
+                config.product_url(119)
+                == "https://miras.co.kr/product/detail.html?product_no=119"
+            ), value
+    finally:
+        if saved is None:
+            os.environ.pop("CAFE24_SHOP_URL", None)
+        else:
+            os.environ["CAFE24_SHOP_URL"] = saved
+
+
+def test_product_url_falls_back_to_cafe24_domain():
+    """CAFE24_SHOP_URL 이 없어도 항상 유효한 주소가 나와야 한다."""
+    saved = os.environ.pop("CAFE24_SHOP_URL", None)
+    try:
+        assert _config().product_url(119) == (
+            "https://testmall.cafe24.com/product/detail.html?product_no=119"
+        )
+    finally:
+        if saved is not None:
+            os.environ["CAFE24_SHOP_URL"] = saved
+
+
+def test_authorize_url_has_state_and_no_secret():
+    url = oauth.build_authorize_url(_config(), state="STATE123")
+    assert url.startswith("https://testmall.cafe24api.com/api/v2/oauth/authorize?")
+    assert "state=STATE123" in url
+    # client_secret 은 authorize 단계에 절대 실리면 안 된다.
+    assert "csecret" not in url
+
+
+# ════════════════════════════════════════════════════════════
+# 토큰 상태 / 자동 갱신
+# ════════════════════════════════════════════════════════════
+def test_status_without_token():
+    status = tokens.TokenService(_FakeRepo(None), _config()).status()
+    assert status["connected"] is False
+    assert status["needs_reauth"] is True
+
+
+def test_status_never_leaks_token_values():
+    service = tokens.TokenService(_FakeRepo(_row()), _config())
+    status = service.status()
+    assert status["connected"] is True
+    assert "AT" not in str(status) and "RT" not in str(status)
+
+
+def test_valid_token_returned_without_refresh():
+    service = tokens.TokenService(_FakeRepo(_row()), _config())
+    assert service.get_access_token() == "AT"
+
+
+def test_expired_refresh_token_needs_reauth():
+    row = _row(refresh_token_expires_at=now_kst() - timedelta(days=1))
+    assert tokens.TokenService(_FakeRepo(row), _config()).status()["needs_reauth"] is True
+
+
+def test_expired_access_token_triggers_refresh():
+    """만료된 access token 은 refresh 후 새 값을 돌려주고, 저장은 암호문으로 한다."""
+    repo = _FakeRepo(_row(access_token_expires_at=now_kst() - timedelta(minutes=5)))
+    service = tokens.TokenService(repo, _config())
+    seen: list[str] = []
+
+    def fake_refresh(config, *, refresh_token):
+        seen.append(refresh_token)
+        return oauth.TokenBundle(
+            access_token="NEW-AT",
+            refresh_token="NEW-RT",
+            access_token_expires_at=now_kst() + timedelta(hours=2),
+            refresh_token_expires_at=now_kst() + timedelta(days=14),
+            scopes="mall.read_product,mall.write_product",
+        )
+
+    original = tokens.refresh_tokens
+    tokens.refresh_tokens = fake_refresh
+    try:
+        assert service.get_access_token() == "NEW-AT"
+    finally:
+        tokens.refresh_tokens = original
+
+    assert seen == ["RT"]  # 복호화된 refresh token 이 전달돼야 한다
+    saved = repo.saves[-1]
+    assert saved["access_token"] != "NEW-AT"  # 평문 저장 금지
+    assert crypto.decrypt(saved["access_token"], secret=SECRET) == "NEW-AT"
+    assert saved["last_error"] == ""
+
+
+def test_dead_refresh_token_raises_auth_error():
+    row = _row(
+        access_token_expires_at=now_kst() - timedelta(minutes=1),
+        refresh_token_expires_at=now_kst() - timedelta(days=1),
+    )
+    service = tokens.TokenService(_FakeRepo(row), _config())
+    try:
+        service.get_access_token()
+    except Cafe24AuthError as exc:
+        assert exc.needs_reauth is True
+        return
+    raise AssertionError("refresh token 만료 시 Cafe24AuthError 여야 한다")
+
+
+# ════════════════════════════════════════════════════════════
+# store.py 순수 로직
+# ════════════════════════════════════════════════════════════
+def test_schedule_editable_only_when_pending():
+    assert store.is_editable("PENDING") is True
+    for locked in ("PROCESSING", "SUCCESS", "FAILED", "CANCELLED"):
+        assert store.is_editable(locked) is False, locked
+
+
+def test_retry_budget_and_backoff():
+    assert all(store.can_retry(i) for i in range(store.MAX_RETRY))
+    assert store.can_retry(store.MAX_RETRY) is False
+    # 무한 재시도 방지 — 간격은 증가하되 상한이 있다.
+    assert store.retry_backoff_seconds(0) < store.retry_backoff_seconds(1)
+    assert store.retry_backoff_seconds(99) == store.retry_backoff_seconds(2)
+
+
+def test_normalize_revision_type():
+    assert store.normalize_revision_type("backup") == store.REVISION_BACKUP
+    assert store.normalize_revision_type("nope") == store.REVISION_DRAFT
+
+
+def test_parse_product_no():
+    assert store.parse_product_no(" 123 ") == 123
+    for bad in ("abc", "0", "-3", None, ""):
+        try:
+            store.parse_product_no(bad)
+        except ValueError:
+            continue
+        raise AssertionError(f"{bad!r} 는 거부해야 한다")
+
+
+# ════════════════════════════════════════════════════════════
+# 상품 엔드포인트 래퍼
+# 실제 쇼핑몰 확인 결과 /admin/products/{no}/description 은 존재하지 않는다
+# (`No API found.`). 상세설명은 상품 리소스의 필드다 — 경로가 되돌아가지 않게
+# 여기서 고정한다.
+# ════════════════════════════════════════════════════════════
+class _FakeClient:
+    """Cafe24Client 의 get/put 만 흉내내고 호출을 기록한다."""
+
+    def __init__(self, payload=None):
+        self.payload = payload or {}
+        self.calls: list[dict] = []
+
+    def get(self, path, *, params=None, json=None, product_no=None):
+        self.calls.append({"method": "GET", "path": path, "params": params})
+        return self.payload
+
+    def put(self, path, *, params=None, json=None, product_no=None):
+        self.calls.append({"method": "PUT", "path": path, "json": json})
+        return self.payload
+
+
+_PRODUCT = {
+    "product_no": 131,
+    "product_code": "P000000B",
+    "product_name": "빠져락 1개(사은품)",
+    "display": "T",
+    "selling": "F",
+    "description": "<p>PC</p>",
+    "mobile_description": "<p>PC</p>",
+    "separated_mobile_description": "F",
+}
+
+
+def test_descriptions_from_product():
+    desc = products.descriptions_from_product(_PRODUCT)
+    assert desc.product_no == 131
+    assert desc.description == "<p>PC</p>"
+    assert desc.separated_mobile is False
+    assert desc.mobile_differs is False
+
+
+def test_descriptions_separated_mobile_and_diff():
+    desc = products.descriptions_from_product(
+        {**_PRODUCT, "separated_mobile_description": "T", "mobile_description": "<p>MO</p>"}
+    )
+    assert desc.separated_mobile is True
+    assert desc.mobile_differs is True
+
+
+def test_fetch_descriptions_uses_product_resource():
+    client = _FakeClient({"product": _PRODUCT})
+    desc = products.fetch_descriptions(client, 131)
+    assert desc.description == "<p>PC</p>"
+    paths = [c["path"] for c in client.calls]
+    assert paths == ["/admin/products/131"], paths
+    assert not any(p.endswith("/description") for p in paths)
+
+
+def test_update_descriptions_payload():
+    client = _FakeClient({"product": _PRODUCT})
+    products.update_descriptions(client, 131, description="<p>NEW</p>")
+    call = client.calls[0]
+    assert call["method"] == "PUT" and call["path"] == "/admin/products/131"
+    # 준 필드만 바뀌어야 한다 — 모바일을 지정하지 않으면 보내지 않는다.
+    assert call["json"] == {"request": {"description": "<p>NEW</p>"}}
+
+
+def test_update_payload_optional_fields():
+    both = products.build_update_payload(
+        description="<p>PC</p>", mobile_description="<p>MO</p>", shop_no=1
+    )
+    assert both == {"shop_no": 1, "request": {"description": "<p>PC</p>", "mobile_description": "<p>MO</p>"}}
+    # 빈 문자열은 "모바일을 비운다"는 뜻이므로 None 과 구분해 전달돼야 한다.
+    assert products.build_update_payload(description="x", mobile_description="")["request"] == {
+        "description": "x",
+        "mobile_description": "",
+    }
+
+
+def test_normalize_product_flags():
+    row = products.normalize_product(_PRODUCT)
+    assert row == {
+        "product_no": 131,
+        "product_code": "P000000B",
+        "product_name": "빠져락 1개(사은품)",
+        "display": True,
+        "selling": False,
+    }
+    # 값이 없으면 기본 True(카페24 응답에 필드가 빠진 경우 진열 중으로 본다).
+    assert products.normalize_product({"product_no": "9"})["display"] is True
+
+
+class _PagingClient:
+    """페이지를 넘겨가며 응답하는 가짜 클라이언트."""
+
+    def __init__(self, count: int):
+        self.count = count
+        self.calls: list[dict] = []
+
+    def get(self, path, *, params=None, json=None, product_no=None):
+        self.calls.append(dict(params or {}))
+        offset = int((params or {}).get("offset", 0))
+        limit = int((params or {}).get("limit", 100))
+        page = [{"product_no": n} for n in range(offset, min(offset + limit, self.count))]
+        return {"products": page}
+
+
+def test_list_all_products_walks_pages():
+    client = _PagingClient(230)
+    rows, truncated = products.list_all_products(client)
+    assert len(rows) == 230 and truncated is False
+    # 100 + 100 + 30 → 3회 호출로 끝나야 한다.
+    assert len(client.calls) == 3
+    assert [c["offset"] for c in client.calls] == [0, 100, 200]
+
+
+def test_list_all_products_stops_at_cap():
+    """상한을 넘으면 잘렸다고 알린다 — 무한 호출로 API 제한에 걸리지 않게."""
+    client = _PagingClient(10_000)
+    rows, truncated = products.list_all_products(client, max_items=150)
+    assert len(rows) == 150 and truncated is True
+
+
+def test_list_all_products_single_page():
+    """현재 쇼핑몰(87개)은 1회 호출로 끝난다."""
+    client = _PagingClient(87)
+    rows, truncated = products.list_all_products(client)
+    assert len(rows) == 87 and truncated is False
+    assert len(client.calls) == 1
+
+
+def test_list_products_clamps_paging():
+    client = _FakeClient({"products": []})
+    products.list_products(client, limit=999, offset=-5, product_name="락")
+    params = client.calls[0]["params"]
+    assert params["limit"] == products.PAGE_LIMIT
+    assert params["offset"] == 0
+    assert params["product_name"] == "락"
+
+
+# ════════════════════════════════════════════════════════════
+# 이미지 URL 한글 파일명 표시 ↔ 저장 (왕복 보존이 핵심)
+# ════════════════════════════════════════════════════════════
+_REAL_IMG = "%EC%9A%A9%EA%B8%B0%EB%83%84%EC%83%88%EC%B0%A8%EB%8B%A8(%ED%99%A9%ED%86%A0)_12.gif"
+_REAL_HTML = f'<img src="/web/product/big/{_REAL_IMG}" alt="용기 냄새차단">'
+
+
+def test_decode_shows_korean_filename():
+    decoded = store.decode_html_urls(_REAL_HTML)
+    assert "용기냄새차단(황토)_12.gif" in decoded
+    assert "%EC%9A%A9" not in decoded
+    # 괄호는 원본에서 인코딩돼 있지 않으므로 그대로 남아야 한다.
+    assert "(황토)" in decoded
+
+
+def test_url_roundtrip_is_byte_identical():
+    """편집하지 않고 적용해도 카페24 저장값이 달라지면 안 된다."""
+    assert store.encode_html_urls(store.decode_html_urls(_REAL_HTML)) == _REAL_HTML
+
+
+def test_ascii_escapes_are_not_decoded():
+    """%20·%3C 를 풀면 URL·HTML 구조가 깨진다 — 건드리지 않는다."""
+    html = '<img src="/web/a%20b.png?x=1%3C2">'
+    assert store.decode_html_urls(html) == html
+    assert store.encode_html_urls(html) == html
+
+
+def test_encode_leaves_body_text_alone():
+    """본문 한글은 인코딩 대상이 아니다(URL 속성값만 바꾼다)."""
+    html = '<p>여름 특가 안내</p><a href="/web/여름.html">보기</a>'
+    encoded = store.encode_html_urls(html)
+    assert "<p>여름 특가 안내</p>" in encoded
+    assert 'href="/web/%EC%97%AC%EB%A6%84.html"' in encoded
+
+
+def test_css_url_is_handled():
+    html = "<style>.a{background:url(/web/upload/%ED%99%A9%ED%86%A0.png)}</style>"
+    assert "황토.png" in store.decode_html_urls(html)
+    assert store.encode_html_urls(store.decode_html_urls(html)) == html
+
+
+def test_invalid_utf8_sequence_left_alone():
+    """EUC-KR 등 UTF-8 이 아닌 이스케이프는 깨뜨리지 않고 그대로 둔다."""
+    html = '<img src="/web/%C7%CF%B3%AA.gif">'
+    assert store.decode_html_urls(html) == html
+
+
+# ════════════════════════════════════════════════════════════
+# 소스 정리(포맷) — 렌더링을 바꾸지 않는 것이 최우선
+# ════════════════════════════════════════════════════════════
+_MESSY = (
+    '<style>\n\t/* 주석 */\n\t.v{max-width:100%}\n</style>'
+    '<div class="wrap"><p>안녕<span>하세요</span> 여름 특가</p>'
+    '<img src="/web/a.gif"><img src="/web/b.gif">'
+    "<table><tr><td>1</td><td>2</td></tr></table></div>"
+)
+
+
+def test_format_breaks_block_tags():
+    out = store.format_html(_MESSY)
+    lines = out.split("\n")
+    assert '<div class="wrap">' in lines
+    assert "</div>" in lines
+    # 블록 안쪽은 들여쓴다.
+    assert any(line.startswith("  <table>") for line in lines)
+    assert any(line.startswith("      <td>") for line in lines)
+
+
+def test_format_keeps_inline_elements_together():
+    """이미지 사이에 줄바꿈이 들어가면 화면에 공백이 생긴다 — 붙여둬야 한다."""
+    out = store.format_html(_MESSY)
+    assert '<img src="/web/a.gif"><img src="/web/b.gif">' in out
+    assert "<p>안녕<span>하세요</span> 여름 특가</p>" in out
+
+
+def test_format_preserves_style_content_verbatim():
+    out = store.format_html(_MESSY)
+    assert "\t/* 주석 */" in out
+    assert "\t.v{max-width:100%}" in out
+
+
+def test_format_is_idempotent():
+    """편집하지 않고 다시 적용해도 저장값이 계속 바뀌면 안 된다."""
+    once = store.format_html(_MESSY)
+    assert store.format_html(once) == once
+    assert store.format_html(store.format_html(once)) == once
+
+
+_REAL_DETAIL = """<div style="width: 1000px; margin: 0 auto;">
+
+<img src="../img/promo/dadamam_detail1.jpg">
+<img src="../img/promo/dadamam_detail2.jpg">
+
+<!-- 대파_타임랩스----------------><img contenteditable="false" src="../img/gif/NEW_1.gif">
+<img contenteditable="false" src="../img/2+1/2+1_02.jpg">
+</div>"""
+
+
+def test_format_indents_every_line_of_a_run():
+    """원문 줄바꿈을 살리고 **모든 줄**을 들여쓴다.
+
+    예전에는 첫 줄만 들여쓰고 나머지가 1열에 붙어 나왔다.
+    """
+    lines = store.format_html(_REAL_DETAIL).split("\n")
+    img_lines = [line for line in lines if "<img" in line]
+    assert len(img_lines) == 4, img_lines
+    assert all(line.startswith("  <") for line in img_lines), img_lines
+
+
+def test_format_keeps_comment_with_its_element():
+    """`<!-- 라벨 --><img>` 는 붙여둔다 — 나누면 라벨과 대상이 떨어진다."""
+    out = store.format_html(_REAL_DETAIL)
+    assert "<!-- 대파_타임랩스----------------><img contenteditable=" in out
+
+
+def test_format_keeps_single_blank_line():
+    """구획용 빈 줄은 한 줄까지 유지한다(여러 줄은 하나로)."""
+    out = store.format_html("<div>\n\n\n<img src=\"a.gif\">\n\n\n<img src=\"b.gif\">\n</div>")
+    assert "\n\n" in out
+    assert "\n\n\n" not in out
+
+
+def test_format_real_detail_is_idempotent():
+    once = store.format_html(_REAL_DETAIL)
+    assert store.format_html(once) == once
+
+
+def test_format_collapses_short_blocks():
+    assert store.format_html("<td>1</td>") == "<td>1</td>"
+    # 길면 나눈다.
+    long_text = "가" * 200
+    assert "\n" in store.format_html("<td>%s</td>" % long_text)
+
+
+def test_format_survives_broken_html():
+    """닫는 태그 누락·꺾쇠 조각이 있어도 예외 없이 뭔가를 돌려준다."""
+    for bad in ("<div><p>열고 안 닫음", "a < b 그리고 c > d", "<<>>", "<div", ""):
+        assert isinstance(store.format_html(bad), str)
+
+
+def test_format_does_not_touch_urls():
+    """포맷은 속성값을 건드리지 않는다(인코딩과 서로 간섭하지 않게)."""
+    html = '<div><img src="/web/%EC%9A%A9%EA%B8%B0(a)_1.gif"></div>'
+    assert "/web/%EC%9A%A9%EA%B8%B0(a)_1.gif" in store.format_html(html)
+
+
+def test_format_then_encode_roundtrip():
+    """화면 표시(디코딩+정리) → 저장(인코딩+정리) 순서에서 URL 이 원형을 지킨다."""
+    raw = store.format_html(_REAL_HTML)
+    shown = store.format_html(store.decode_html_urls(raw))
+    saved = store.format_html(store.encode_html_urls(shown))
+    assert saved == raw
+
+
+# ════════════════════════════════════════════════════════════
+# 예약 — 입력 검증
+# ════════════════════════════════════════════════════════════
+def test_parse_tristate():
+    assert store.parse_tristate("on") is True
+    assert store.parse_tristate("off") is False
+    for keep in ("", None, "keep", "이상한값"):
+        assert store.parse_tristate(keep) is None, keep
+
+
+def test_parse_schedule_at_accepts_future_kst():
+    base = now_kst()
+    target = (base + timedelta(hours=3)).replace(second=0, microsecond=0)
+    parsed = store.parse_schedule_at(target.strftime("%Y-%m-%dT%H:%M"), now=base)
+    assert parsed.utcoffset() == timedelta(hours=9)  # 타임존 표기 없는 입력을 KST 로 해석
+    assert parsed.hour == target.hour and parsed.minute == target.minute
+
+
+def test_parse_schedule_at_rejects_past_and_garbage():
+    base = now_kst()
+    past = (base - timedelta(hours=1)).strftime("%Y-%m-%dT%H:%M")
+    for bad in (past, "", "어제", "2026-13-45T99:99"):
+        try:
+            store.parse_schedule_at(bad, now=base)
+        except ValueError:
+            continue
+        raise AssertionError(f"{bad!r} 는 거부해야 한다")
+
+
+def test_parse_schedule_at_allows_one_minute_grace():
+    """`datetime-local` 은 초를 버린다 — 지금 이 분(分)을 고른 것을 거부하면 안 된다.
+
+    now 의 초를 고정해 실행 시각에 따라 결과가 달라지지 않게 한다(예전에 이 테스트가
+    초에 따라 실패했다).
+    """
+    base = now_kst().replace(second=40, microsecond=0)
+    this_minute = base.strftime("%Y-%m-%dT%H:%M")  # 초가 잘려 base 보다 40초 과거
+    assert store.parse_schedule_at(this_minute, now=base) is not None
+
+
+def test_describe_schedule_action():
+    assert store.describe_schedule_action(
+        has_html=True, set_display=True, set_selling=False
+    ) == "상세페이지 · 진열 · 판매중지"
+    assert store.describe_schedule_action(
+        has_html=False, set_display=None, set_selling=True
+    ) == "판매"
+    assert store.describe_schedule_action(
+        has_html=False, set_display=None, set_selling=None
+    ) == "없음"
+
+
+def test_normalize_schedule_status():
+    assert store.normalize_schedule_status("success") == store.STATUS_SUCCESS
+    assert store.normalize_schedule_status("없는상태") == store.STATUS_PENDING
+
+
+# ════════════════════════════════════════════════════════════
+# 예약 — 상품 수정 payload (진열/판매 포함)
+# ════════════════════════════════════════════════════════════
+def test_update_payload_flags():
+    payload = products.build_update_payload(display=True, selling=False)
+    assert payload == {"request": {"display": "T", "selling": "F"}}
+
+
+def test_update_payload_skips_none():
+    """None 인 항목은 아예 보내지 않는다 = 그 필드를 건드리지 않는다."""
+    payload = products.build_update_payload(description="<p>x</p>")
+    assert payload["request"] == {"description": "<p>x</p>"}
+
+
+def test_update_product_skips_empty_request():
+    """바꿀 것이 없으면 API 를 호출하지 않는다."""
+    client = _FakeClient({"product": _PRODUCT})
+    assert products.update_product(client, 131) == {}
+    assert client.calls == []
+
+
+def test_update_product_sends_flags_and_html():
+    client = _FakeClient({"product": _PRODUCT})
+    products.update_product(client, 131, description="<p>새</p>", display=False)
+    call = client.calls[0]
+    assert call["method"] == "PUT" and call["path"] == "/admin/products/131"
+    assert call["json"] == {"request": {"description": "<p>새</p>", "display": "F"}}
+
+
+# ════════════════════════════════════════════════════════════
+# 예약 worker — 성공/재시도/최종실패
+# ════════════════════════════════════════════════════════════
+class _FakeStore:
+    """worker 가 쓰는 저장소 메서드만 흉내낸다."""
+
+    def __init__(self, rows):
+        self.rows = list(rows)
+        self.revisions = {}
+        self.added = []
+        self.finished = []
+        self.audits = []
+
+    @contextmanager
+    def claim_due_schedule(self, *, now):
+        yield self.rows.pop(0) if self.rows else None
+
+    def get_revision(self, revision_id):
+        return self.revisions.get(int(revision_id), {})
+
+    def add_revision(self, **fields):
+        self.added.append(fields)
+        return 900 + len(self.added)
+
+    def finish_schedule(self, schedule_id, *, status, error="", next_retry_at=None, retry_count=None):
+        self.finished.append(
+            {"id": schedule_id, "status": status, "error": error,
+             "next_retry_at": next_retry_at, "retry_count": retry_count}
+        )
+
+    def log_audit(self, **fields):
+        self.audits.append(fields)
+
+
+class _FakeApi:
+    def __init__(self, client):
+        self.client = client
+
+
+class _WorkerClient(_FakeClient):
+    """PUT 을 실패시킬 수 있는 클라이언트."""
+
+    def __init__(self, payload=None, fail_put=None):
+        super().__init__(payload)
+        self.fail_put = fail_put
+
+    def put(self, path, *, params=None, json=None, product_no=None):
+        if self.fail_put:
+            raise self.fail_put
+        return super().put(path, params=params, json=json, product_no=product_no)
+
+
+def _schedule_row(**overrides):
+    row = {
+        "id": 7, "product_no": 131, "revision_id": 55,
+        "set_display": True, "set_selling": None, "retry_count": 0,
+    }
+    row.update(overrides)
+    return row
+
+
+def test_worker_applies_html_and_flags():
+    st = _FakeStore([_schedule_row()])
+    st.revisions[55] = {"html_content": "<p>예약 내용</p>"}
+    client = _WorkerClient({"product": _PRODUCT})
+    assert worker.process_once(st, _FakeApi(client)) == 1
+
+    # 쓰기 직전 현재값을 읽어 BACKUP 을 남겼는가
+    assert any(r["revision_type"] == store.REVISION_BACKUP for r in st.added)
+    # HTML 과 진열 상태를 한 번의 PUT 으로 보냈는가
+    put = [c for c in client.calls if c["method"] == "PUT"][0]
+    assert put["json"]["request"]["description"] == "<p>예약 내용</p>"
+    assert put["json"]["request"]["mobile_description"] == "<p>예약 내용</p>"
+    assert put["json"]["request"]["display"] == "T"
+    assert "selling" not in put["json"]["request"]  # 변경 없음이면 보내지 않는다
+    assert st.finished == [
+        {"id": 7, "status": store.STATUS_SUCCESS, "error": "",
+         "next_retry_at": None, "retry_count": None}
+    ]
+
+
+def test_worker_flags_only_skips_backup():
+    """HTML 없이 진열/판매만 바꾸는 예약은 상세설명을 읽거나 백업하지 않는다."""
+    st = _FakeStore([_schedule_row(revision_id=None, set_selling=False)])
+    client = _WorkerClient({"product": _PRODUCT})
+    assert worker.process_once(st, _FakeApi(client)) == 1
+    assert st.added == []  # 백업 없음
+    put = [c for c in client.calls if c["method"] == "PUT"][0]
+    assert "description" not in put["json"]["request"]
+    assert put["json"]["request"] == {"display": "T", "selling": "F"}
+
+
+def test_worker_retries_then_fails():
+    """실패는 재시도 예산 안에서 다시 시도하고, 소진되면 FAILED 로 확정한다."""
+    boom = Cafe24ApiError("서버 오류", status=500)
+
+    st = _FakeStore([_schedule_row(retry_count=0)])
+    st.revisions[55] = {"html_content": "<p>x</p>"}
+    worker.process_once(st, _FakeApi(_WorkerClient({"product": _PRODUCT}, fail_put=boom)))
+    first = st.finished[0]
+    assert first["status"] == store.STATUS_PENDING      # 다시 대기로
+    assert first["retry_count"] == 1
+    assert first["next_retry_at"] is not None
+
+    st2 = _FakeStore([_schedule_row(retry_count=store.MAX_RETRY)])
+    st2.revisions[55] = {"html_content": "<p>x</p>"}
+    worker.process_once(st2, _FakeApi(_WorkerClient({"product": _PRODUCT}, fail_put=boom)))
+    assert st2.finished[0]["status"] == store.STATUS_FAILED
+    assert any(a["result"] == "FAIL" for a in st2.audits)
+
+
+def test_worker_missing_revision_is_failure_not_crash():
+    st = _FakeStore([_schedule_row(revision_id=999, retry_count=store.MAX_RETRY)])
+    worker.process_once(st, _FakeApi(_WorkerClient({"product": _PRODUCT})))
+    assert st.finished[0]["status"] == store.STATUS_FAILED
+    assert "999" in st.finished[0]["error"]
+
+
+def test_worker_stops_when_nothing_due():
+    st = _FakeStore([])
+    assert worker.process_once(st, _FakeApi(_WorkerClient())) == 0
+
+
+def _run_all():
+    fns = [v for k, v in sorted(globals().items()) if k.startswith("test_") and callable(v)]
+    for fn in fns:
+        fn()
+        print("PASS", fn.__name__)
+    print(f"\n{len(fns)} tests passed.")
+
+
+if __name__ == "__main__":
+    _run_all()

app/modules/cafe24/worker.py

@@ -0,0 +1,198 @@
+"""카페24 예약 실행 worker.
+
+    python -m app.modules.cafe24.worker --loop 60    # 60초마다 확인 (운영)
+    python -m app.modules.cafe24.worker --once       # 한 번만 처리하고 종료
+
+왜 별도 프로세스인가
+    예약은 브라우저를 닫아도, 아무도 화면을 보고 있지 않아도 그 시각에 실행돼야 한다.
+    웹 요청 안에서 기다리는 방식은 프록시 타임아웃·재기동에 그대로 무너진다.
+    compose 서비스 `dbx-cafe24-worker` 가 web 과 같은 이미지로 이 모듈을 돌린다.
+
+한 번에 한 건씩 처리한다
+    `claim_due_schedule` 이 `FOR UPDATE SKIP LOCKED` 로 한 건을 잠그고 PROCESSING 으로
+    바꾼다. worker 가 실수로 두 개 떠도 같은 예약이 두 번 적용되지 않는다.
+
+적용 순서는 화면 편집과 같다
+    카페24 현재값 재조회 → BACKUP revision → PUT → SUCCESS + 감사로그
+    실패하면 재시도 예산(store.MAX_RETRY) 안에서 간격을 두고 다시 시도하고,
+    소진되면 FAILED 로 확정한다. 되돌리기는 쓰지 않는다.
+
+토큰 갱신은 TokenService 가 행 잠금 안에서 하므로 web 과 동시에 떠 있어도 안전하다.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+import time
+from datetime import timedelta
+from typing import Any
+
+from app.integrations.cafe24 import Cafe24Error, build_cafe24_api, products
+from app.timezone import now_kst
+
+from . import store
+
+logger = logging.getLogger("cafe24.worker")
+
+ACTOR = "SCHEDULER"
+
+
+def _apply(store_db: Any, api: Any, row: dict[str, Any]) -> str:
+    """예약 1건 적용. 성공 시 사람이 읽을 요약 문자열."""
+    schedule_id = int(row["id"])
+    product_no = int(row["product_no"])
+    revision_id = row.get("revision_id")
+    set_display = row.get("set_display")
+    set_selling = row.get("set_selling")
+
+    html: str | None = None
+    if revision_id:
+        revision = store_db.get_revision(int(revision_id))
+        if not revision:
+            raise Cafe24Error(f"예약이 가리키는 버전 {revision_id} 을 찾을 수 없습니다.")
+        html = revision.get("html_content") or ""
+        if not html.strip():
+            raise Cafe24Error(f"버전 {revision_id} 의 내용이 비어 있습니다.")
+
+    # 상세설명을 바꿀 때는 쓰기 직전 현재값을 읽어 백업한다(로컬 값을 믿지 않는다).
+    backup_id = 0
+    mobile_html: str | None = None
+    if html is not None:
+        current = products.fetch_descriptions(api.client, product_no)
+        backup_id = store_db.add_revision(
+            product_no=product_no,
+            html_content=current.description,
+            revision_type=store.REVISION_BACKUP,
+            memo=f"예약 #{schedule_id} 적용 직전 자동 백업",
+            created_by=ACTOR,
+        )
+        if current.mobile_description and current.mobile_description != current.description:
+            store_db.add_revision(
+                product_no=product_no,
+                html_content=current.mobile_description,
+                revision_type=store.REVISION_BACKUP,
+                memo=f"예약 #{schedule_id} 적용 직전 자동 백업 (모바일)",
+                created_by=ACTOR,
+            )
+        # PC/모바일은 구분하지 않는다 — 화면 편집과 같은 방침.
+        mobile_html = html
+
+    products.update_product(
+        api.client,
+        product_no,
+        description=html,
+        mobile_description=mobile_html,
+        display=set_display,
+        selling=set_selling,
+    )
+
+    summary = store.describe_schedule_action(
+        has_html=html is not None, set_display=set_display, set_selling=set_selling
+    )
+    store_db.log_audit(
+        actor=ACTOR,
+        action="schedule_apply",
+        product_no=product_no,
+        revision_id=int(revision_id) if revision_id else None,
+        schedule_id=schedule_id,
+        result="SUCCESS",
+        detail=summary + (f" (백업 {backup_id})" if backup_id else ""),
+    )
+    return summary
+
+
+def process_once(store_db: Any, api: Any) -> int:
+    """실행할 예약을 모두 처리한다. 처리한 건수를 돌려준다."""
+    handled = 0
+    while True:
+        with store_db.claim_due_schedule(now=now_kst()) as row:
+            if row is None:
+                return handled
+        # 잠금은 여기서 이미 풀렸다. 상태가 PROCESSING 이라 다른 worker 가 집지 않는다.
+        schedule_id = int(row["id"])
+        product_no = int(row["product_no"])
+        try:
+            summary = _apply(store_db, api, row)
+        except Cafe24Error as exc:
+            retry_count = int(row.get("retry_count") or 0)
+            if store.can_retry(retry_count):
+                wait = store.retry_backoff_seconds(retry_count)
+                store_db.finish_schedule(
+                    schedule_id,
+                    status=store.STATUS_PENDING,
+                    error=str(exc),
+                    next_retry_at=now_kst() + timedelta(seconds=wait),
+                    retry_count=retry_count + 1,
+                )
+                logger.warning(
+                    "예약 #%s 상품 %s 실패 — %s초 후 재시도 (%s/%s): %s",
+                    schedule_id, product_no, wait, retry_count + 1, store.MAX_RETRY, exc,
+                )
+            else:
+                store_db.finish_schedule(
+                    schedule_id, status=store.STATUS_FAILED, error=str(exc)
+                )
+                store_db.log_audit(
+                    actor=ACTOR, action="schedule_apply", product_no=product_no,
+                    schedule_id=schedule_id, result="FAIL", detail=str(exc),
+                )
+                logger.error("예약 #%s 상품 %s 최종 실패: %s", schedule_id, product_no, exc)
+        except Exception as exc:  # noqa: BLE001 — 한 건의 사고가 worker 를 죽이면 안 된다.
+            store_db.finish_schedule(
+                schedule_id, status=store.STATUS_FAILED, error=f"{type(exc).__name__}: {exc}"
+            )
+            logger.exception("예약 #%s 처리 중 예상치 못한 오류", schedule_id)
+        else:
+            store_db.finish_schedule(schedule_id, status=store.STATUS_SUCCESS)
+            logger.info("예약 #%s 상품 %s 적용 완료 — %s", schedule_id, product_no, summary)
+        handled += 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="카페24 예약 실행 worker")
+    parser.add_argument("--loop", type=int, default=0, help="확인 간격(초). 0 이면 한 번만")
+    parser.add_argument("--once", action="store_true", help="한 번만 처리하고 종료")
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+        stream=sys.stdout,
+    )
+
+    dsn = (os.getenv("CAFE24_DB_URL") or "").strip()
+    if not dsn:
+        logger.error("CAFE24_DB_URL 이 설정되지 않았습니다. worker 를 시작할 수 없습니다.")
+        return 1
+
+    # 지연 import — psycopg 가 없는 개발 환경에서도 이 모듈을 열어볼 수 있게.
+    from .db import Cafe24Store  # noqa: WPS433
+
+    store_db = Cafe24Store(dsn)
+    api = build_cafe24_api(store_db)
+    interval = 0 if args.once else max(0, int(args.loop))
+    logger.info("카페24 예약 worker 시작 (간격 %s초)", interval or "단발")
+
+    try:
+        while True:
+            try:
+                count = process_once(store_db, api)
+                if count:
+                    logger.info("예약 %s건 처리", count)
+            except Exception:  # noqa: BLE001 — DB 순간 장애로 죽지 않게
+                logger.exception("예약 처리 루프에서 오류 — 다음 주기에 다시 시도")
+            if not interval:
+                return 0
+            time.sleep(interval)
+    except KeyboardInterrupt:
+        logger.info("종료 요청 — worker 를 멈춥니다.")
+        return 0
+    finally:
+        store_db.close()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

app/modules/cupang/router.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import calendar as _calendar
 import json
+from fractions import Fraction
 from typing import Any
 
 from app.timezone import today_kst
@@ -568,6 +569,165 @@ async def box_rule_delete(
     return RedirectResponse(url="/cupang/box-rules", status_code=303)
 
 
+# ════════════════════════════════════════════════════════════
+# 박스 계산기 — 제품명 + 수량 → 박스 수 / 남은 낱개
+#   저장하지 않는 계산 전용 화면. 규칙은 cupang_box_rules 를 그대로 사용한다.
+# ════════════════════════════════════════════════════════════
+@router.get("/box-calc", response_class=HTMLResponse)
+async def box_calc_page(request: Request) -> HTMLResponse:
+    from app.main import build_erp_nav, render_template  # noqa: WPS433
+    from app.store import is_admin  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard
+    store, user = guard
+    return render_template(
+        request,
+        "cupang/box_calc.html",
+        {
+            "user": user,
+            "is_admin": is_admin(user),
+            "nav_items": build_erp_nav(user, active="cupang"),
+            "page_title": "쿠팡 밀크런 — 박스 계산",
+            "page_subtitle": "제품명과 수량을 넣으면 박스 수와 남은 낱개를 계산합니다.",
+            "box_rules": store.list_box_rules(),
+            # 센터 선택 드롭다운은 가나다순 (한글 음절은 코드포인트 순 = 가나다순)
+            "centers": sorted(store.list_centers(), key=lambda c: (c.get("name") or "")),
+        },
+    )
+
+
+@router.post("/api/box-calc")
+async def box_calc_api(
+    request: Request,
+    payload: dict[str, Any] = Body(...),
+    user: dict[str, Any] = Depends(_require_user),
+) -> JSONResponse:
+    """[{product_code, quantity}] → 제품별 박스 계산 + 박스명별 합계.
+
+    클라이언트 계산을 신뢰하지 않고 store.compute_boxes 로 서버에서 계산한다.
+    """
+    from .store import compute_boxes  # noqa: WPS433
+
+    store = _store(request)
+    if store is None:
+        raise HTTPException(status_code=503, detail="cupang_db 미설정")
+
+    raw_items = payload.get("items")
+    if not isinstance(raw_items, list):
+        raise HTTPException(status_code=400, detail="items 는 배열이어야 합니다.")
+
+    rules = {r["product_code"]: r for r in store.list_box_rules()}
+
+    results: list[dict[str, Any]] = []
+    totals: dict[str, dict[str, Any]] = {}
+    for raw in raw_items:
+        if not isinstance(raw, dict):
+            continue
+        code = str(raw.get("product_code") or "").strip()
+        if not code:
+            continue
+        try:
+            qty = int(raw.get("quantity") or 0)
+        except (TypeError, ValueError):
+            qty = 0
+        qty = max(qty, 0)
+
+        rule = rules.get(code)
+        upb = rule["units_per_box"] if rule else None
+        calc = compute_boxes(qty, upb)
+        box_name = (rule or {}).get("box_name") or ""
+        results.append(
+            {
+                "product_code": code,
+                "product_name": (rule or {}).get("product_name_snapshot") or code,
+                "box_name": box_name,
+                "units_per_box": calc["units_per_box"],
+                "quantity": qty,
+                "configured": calc["configured"],
+                "full_boxes": calc["full_boxes"],
+                "remainder_units": calc["remainder_units"],
+                "required_boxes": calc["required_boxes"],
+            }
+        )
+        if calc["configured"]:
+            agg = totals.setdefault(
+                box_name, {"box_name": box_name, "full_boxes": 0, "required_boxes": 0, "remainder_units": 0}
+            )
+            agg["full_boxes"] += calc["full_boxes"]
+            agg["required_boxes"] += calc["required_boxes"]
+            agg["remainder_units"] += calc["remainder_units"]
+
+    mixes = _pack_leftovers(results)
+    grand_total = sum(r["full_boxes"] or 0 for r in results if r["configured"])
+    grand_total += sum(m["box_count"] for m in mixes)
+
+    return JSONResponse(
+        {
+            "results": results,
+            "totals": sorted(totals.values(), key=lambda t: t["box_name"]),
+            "mixes": mixes,
+            "grand_total_boxes": grand_total,
+        }
+    )
+
+
+def _pack_leftovers(results: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """제품별 자투리(remainder_units)를 같은 박스명끼리 모아 혼합 박스에 담는다.
+
+    - 한 박스의 용량을 1 로 두고, 제품 1개가 차지하는 부피를 1/units_per_box 로 본다.
+      (예: 쿠팡 2호 = 8개들이 → 1개 = 1/8 박스)
+    - 같은 박스명끼리만 섞는다. 서로 다른 입수량이 섞여도 부피 합으로 정확히 계산된다.
+    - 한 제품의 자투리가 두 박스에 나뉘어 담기는 것은 허용(그래야 박스 수가 최소).
+    - 오차 없이 계산하려고 float 대신 Fraction 을 쓴다.
+    """
+    groups: dict[str, list[dict[str, Any]]] = {}
+    for r in results:
+        if not r["configured"] or not r["remainder_units"]:
+            continue
+        groups.setdefault(r["box_name"], []).append(r)
+
+    out: list[dict[str, Any]] = []
+    for box_name in sorted(groups):
+        # 자투리가 많은 제품부터 담아 박스 안 품목 수를 줄인다.
+        items = sorted(groups[box_name], key=lambda r: -r["remainder_units"])
+        boxes: list[dict[str, Any]] = []
+        cur: list[dict[str, Any]] = []
+        free = Fraction(1)
+
+        for r in items:
+            unit = Fraction(1, int(r["units_per_box"]))
+            left = int(r["remainder_units"])
+            while left > 0:
+                take = min(left, int(free / unit))
+                if take == 0:  # 남은 자리 없음 → 새 박스
+                    boxes.append({"items": cur, "fill_percent": float(round((1 - free) * 100, 1))})
+                    cur, free = [], Fraction(1)
+                    continue
+                cur.append(
+                    {
+                        "product_code": r["product_code"],
+                        "product_name": r["product_name"],
+                        "quantity": take,
+                    }
+                )
+                free -= unit * take
+                left -= take
+        if cur:
+            boxes.append({"items": cur, "fill_percent": float(round((1 - free) * 100, 1))})
+
+        out.append(
+            {
+                "box_name": box_name,
+                "box_count": len(boxes),
+                "leftover_units": sum(int(r["remainder_units"]) for r in items),
+                "boxes": boxes,
+            }
+        )
+    return out
+
+
 # ════════════════════════════════════════════════════════════
 # 설정 — 제품명 카탈로그 관리 (itemcode_db 에서 등록)
 # ════════════════════════════════════════════════════════════

app/modules/cupang/templates/cupang/box_calc.html

@@ -0,0 +1,691 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260829g" />{% endblock %}
+
+{% block content %}
+<section class="cpg">
+
+  <div class="erp-page-actions">
+    <a class="erp-btn erp-btn-primary" href="/cupang/">◀◀ 달력</a>
+    <a class="erp-btn erp-btn-outline" href="/cupang/box-rules">박스 입수량 설정</a>
+    <a class="erp-btn erp-btn-outline" href="/cupang/centers">입고센터 관리</a>
+  </div>
+
+  {% if not box_rules %}
+  <div class="erp-card cpg-form-card">
+    <p class="erp-muted">
+      등록된 박스 입수량 규칙이 없습니다.
+      <a href="/cupang/box-rules">박스 입수량 설정</a>에서 먼저 제품별 입수량을 등록하세요.
+    </p>
+  </div>
+  {% else %}
+
+  <div class="cpg-calc3">
+
+    <!-- ① 박스 계산 — 제품명 + 수량만 입력 -->
+    <div class="erp-card cpg-form-card cpg-calc-card">
+      <div class="cpg-card-head">
+        <h2>① 박스 계산</h2>
+        <span class="erp-muted">수량 칸에서 Tab = 다음 상품 수량, Enter = 계산</span>
+      </div>
+
+      <div class="erp-table-wrap">
+        <table class="erp-table cpg-calc-table">
+          <colgroup>
+            <col class="cpg-col-name" />
+            <col class="cpg-col-qty" />
+            <col class="cpg-col-act" />
+          </colgroup>
+          <thead>
+            <tr>
+              <th>제품명</th>
+              <th>수량</th>
+              <th></th>
+            </tr>
+          </thead>
+          <tbody id="cpg-calc-rows"></tbody>
+        </table>
+      </div>
+
+      <div class="erp-page-actions cpg-calc-actions">
+        <button type="button" class="erp-btn erp-btn-primary" id="cpg-calc-run">계산 / 재계산</button>
+        <button type="button" class="erp-btn erp-btn-outline" id="cpg-calc-add">+ 제품 추가</button>
+        <button type="button" class="erp-btn erp-btn-outline" id="cpg-calc-reset">초기화</button>
+        <span class="erp-muted" id="cpg-calc-msg"></span>
+      </div>
+    </div>
+
+    <!-- ② 박스 요약 — 센터에 배분하고 남은 수량이 실시간 반영 -->
+    <div class="erp-card cpg-form-card cpg-calc-sum">
+      <div class="cpg-card-head">
+        <h2>② 박스 요약</h2>
+        <span class="erp-muted">카드를 ③ 센터로 끌어다 놓거나, 카드를 클릭해 담습니다.</span>
+      </div>
+
+      <div id="cpg-sum-empty" class="erp-muted">왼쪽에서 제품과 수량을 넣고 계산하세요.</div>
+
+      <div id="cpg-sum-body" hidden>
+        <div class="cpg-sum-kpis" id="cpg-sum-kpis"></div>
+
+        <h3 class="cpg-sum-h3">제품별 박스 <span class="erp-muted">잔여 기준</span></h3>
+        <div class="cpg-sum-prods" id="cpg-sum-prods"></div>
+
+        <h3 class="cpg-sum-h3">자투리 혼합 박스 <span class="erp-muted" id="cpg-sum-mix-note"></span></h3>
+        <div class="cpg-sum-boxes" id="cpg-sum-boxes"></div>
+      </div>
+    </div>
+
+    <!-- ③ 센터 분배 — 선택한 센터만 표시 -->
+    <div class="erp-card cpg-form-card cpg-dist-card">
+      <div class="cpg-card-head">
+        <h2>③ 센터 분배</h2>
+        <span class="erp-muted">담을 센터를 골라 추가하세요.</span>
+      </div>
+
+      {% if not centers %}
+      <p class="erp-muted">
+        등록된 입고센터가 없습니다. <a href="/cupang/centers">입고센터 관리</a>에서 먼저 센터를 추가하세요.
+      </p>
+      {% else %}
+      <div class="cpg-inline-form cpg-center-pick">
+        <select class="erp-select" id="cpg-center-pick">
+          {% for c in centers %}
+          <option value="{{ c.id }}">{{ c.name }}</option>
+          {% endfor %}
+        </select>
+        <button type="button" class="erp-btn erp-btn-primary" id="cpg-center-add">+ 센터 추가</button>
+      </div>
+      <div class="cpg-dist-list" id="cpg-dist-list"></div>
+      <p class="erp-muted" id="cpg-dist-empty">추가한 센터가 여기에 표시됩니다.</p>
+      {% endif %}
+    </div>
+
+  </div><!-- /cpg-calc3 -->
+
+  <!-- 담을 박스 수량 입력 대화상자 -->
+  <div class="cpg-modal" id="cpg-dlg" hidden>
+    <div class="cpg-modal-back" data-dlg-close></div>
+    <div class="cpg-modal-box" role="dialog" aria-modal="true" aria-labelledby="cpg-dlg-title">
+      <h3 id="cpg-dlg-title">센터에 담기</h3>
+      <p class="cpg-dlg-item" id="cpg-dlg-item"></p>
+      <label class="erp-field"><span>센터</span>
+        <select class="erp-select" id="cpg-dlg-center"></select></label>
+      <label class="erp-field"><span>박스 수량</span>
+        <input class="erp-input" type="number" id="cpg-dlg-qty" min="1" step="1" /></label>
+      <p class="erp-muted" id="cpg-dlg-hint"></p>
+      <div class="erp-page-actions cpg-dlg-actions">
+        <button type="button" class="erp-btn erp-btn-primary" id="cpg-dlg-ok">담기</button>
+        <button type="button" class="erp-btn erp-btn-outline" id="cpg-dlg-all">잔여 전부 담기</button>
+        <button type="button" class="erp-btn erp-btn-outline" data-dlg-close>취소</button>
+      </div>
+    </div>
+  </div>
+
+  <script type="application/json" id="cpg-calc-rules">{{ box_rules | tojson }}</script>
+  <script type="application/json" id="cpg-centers">{{ centers | tojson }}</script>
+  <script>
+  // 박스 계산 3열 화면.
+  //  ① 제품명·수량 입력 → 서버(POST /cupang/api/box-calc)에서 계산
+  //  ② 계산 결과 요약 — 드래그(또는 클릭) 소스
+  //  ③ 선택한 센터에만 분배. 담은 수량만큼 ② 의 잔여가 즉시 줄어든다.
+  // 분배 내역은 화면 안에서만 유지된다(DB 저장 없음).
+  (function () {
+    var tbody = document.getElementById("cpg-calc-rows");
+    if (!tbody) return;
+    var runBtn = document.getElementById("cpg-calc-run");
+    var addBtn = document.getElementById("cpg-calc-add");
+    var resetBtn = document.getElementById("cpg-calc-reset");
+    var msg = document.getElementById("cpg-calc-msg");
+    var sumEmpty = document.getElementById("cpg-sum-empty");
+    var sumBody = document.getElementById("cpg-sum-body");
+    var sumKpis = document.getElementById("cpg-sum-kpis");
+    var sumProds = document.getElementById("cpg-sum-prods");
+    var sumBoxes = document.getElementById("cpg-sum-boxes");
+    var sumMixNote = document.getElementById("cpg-sum-mix-note");
+    var distList = document.getElementById("cpg-dist-list");
+    var distCard = document.querySelector(".cpg-dist-card");
+    var distEmpty = document.getElementById("cpg-dist-empty");
+    var centerPick = document.getElementById("cpg-center-pick");
+    var centerAdd = document.getElementById("cpg-center-add");
+    var dlg = document.getElementById("cpg-dlg");
+    var dlgItem = document.getElementById("cpg-dlg-item");
+    var dlgCenter = document.getElementById("cpg-dlg-center");
+    var dlgQty = document.getElementById("cpg-dlg-qty");
+    var dlgHint = document.getElementById("cpg-dlg-hint");
+    var dlgOk = document.getElementById("cpg-dlg-ok");
+    var dlgAll = document.getElementById("cpg-dlg-all");
+
+    function readJson(id) {
+      var el = document.getElementById(id);
+      try { return JSON.parse((el && el.textContent) || "[]"); } catch (e) { return []; }
+    }
+    var rules = readJson("cpg-calc-rules");
+    var centers = readJson("cpg-centers");
+
+    function esc(s) { var d = document.createElement("div"); d.textContent = s == null ? "" : s; return d.innerHTML; }
+
+    var optionsHtml = '<option value="">— 제품명 선택 —</option>';
+    rules.forEach(function (r) {
+      optionsHtml += '<option value="' + esc(r.product_code) + '">' +
+                     esc(r.product_name_snapshot || r.product_code) + "</option>";
+    });
+
+    // ── 상태 ─────────────────────────────────────────
+    var calc = { results: [], mixes: [] };   // 서버 계산 결과
+    var units = {};                          // key -> 박스 1개당 상품 수
+    var labels = {};                         // key -> 표시 이름
+    var openCenters = [];                    // ③ 에 추가한 센터 id (문자열)
+    var alloc = {};                          // centerId -> [{id, key, count}]
+    var seq = 0;
+    var pending = null;                      // 대화상자 대상 {key, centerId}
+
+    function prodKey(code) { return "p:" + code; }
+    function mixKey(boxName, idx) { return "m:" + boxName + "#" + idx; }
+
+    function centerName(cid) {
+      var hit = centers.filter(function (c) { return String(c.id) === String(cid); })[0];
+      return hit ? hit.name : cid;
+    }
+
+    // ── ① 입력 표 ─────────────────────────────────────
+    function addRow(code, qty) {
+      var tr = document.createElement("tr");
+      tr.className = "cpg-calc-row";
+      tr.innerHTML =
+        '<td><select class="erp-select cpg-calc-name">' + optionsHtml + "</select></td>" +
+        '<td><input class="erp-input cpg-calc-qty" type="number" min="0" step="1" value="' + (qty || 0) + '" /></td>' +
+        '<td class="cpg-calc-act"><button type="button" class="erp-btn erp-btn-danger cpg-calc-del" title="행 삭제" aria-label="행 삭제">✕</button></td>';
+      tbody.appendChild(tr);
+      if (code) tr.querySelector(".cpg-calc-name").value = code;
+      return tr;
+    }
+
+    function rowsArr() {
+      return Array.prototype.slice.call(tbody.querySelectorAll(".cpg-calc-row"));
+    }
+
+    function collect() {
+      var items = [];
+      rowsArr().forEach(function (tr) {
+        var code = tr.querySelector(".cpg-calc-name").value;
+        if (!code) return;
+        items.push({ product_code: code, quantity: parseInt(tr.querySelector(".cpg-calc-qty").value, 10) || 0 });
+      });
+      return items;
+    }
+
+    function run() {
+      var items = collect();
+      if (!items.length) { msg.textContent = "제품명을 하나 이상 선택하세요."; return; }
+      msg.textContent = "계산 중…";
+      runBtn.disabled = true;
+      fetch("/cupang/api/box-calc", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ items: items })
+      })
+        .then(function (r) { if (!r.ok) throw new Error("http " + r.status); return r.json(); })
+        .then(function (data) {
+          calc.results = ((data && data.results) || []).filter(function (r) { return r.configured; });
+          calc.mixes = (data && data.mixes) || [];
+          units = {};
+          labels = {};
+          calc.results.forEach(function (r) {
+            units[prodKey(r.product_code)] = r.units_per_box;
+            labels[prodKey(r.product_code)] = r.product_name;
+          });
+          calc.mixes.forEach(function (m) {
+            m.boxes.forEach(function (b, i) {
+              var n = 0;
+              b.items.forEach(function (it) { n += it.quantity; });
+              units[mixKey(m.box_name, i)] = n;
+              labels[mixKey(m.box_name, i)] = m.box_name + " 혼합 #" + (i + 1);
+            });
+          });
+          var had = Object.keys(alloc).some(function (k) { return alloc[k].length; });
+          alloc = {};   // 계산이 바뀌면 이전 배분은 근거가 사라지므로 비운다.
+          render();
+          msg.textContent = "계산 완료 (" + calc.results.length + "건)" + (had ? " — 센터 분배 초기화됨" : "");
+        })
+        .catch(function () { msg.textContent = "계산 실패 — 새로고침 후 다시 시도하세요."; })
+        .then(function () { runBtn.disabled = false; });
+    }
+
+    // ── 배분 집계 ─────────────────────────────────────
+    function allocatedFor(key) {
+      var n = 0;
+      Object.keys(alloc).forEach(function (cid) {
+        alloc[cid].forEach(function (a) { if (a.key === key) n += a.count; });
+      });
+      return n;
+    }
+
+    function totalFor(key) {
+      if (key.indexOf("p:") === 0) {
+        var code = key.slice(2);
+        var hit = calc.results.filter(function (r) { return r.product_code === code; })[0];
+        return hit ? hit.full_boxes : 0;
+      }
+      return 1;   // 혼합 박스는 1장 = 1박스
+    }
+
+    function remainFor(key) { return Math.max(0, totalFor(key) - allocatedFor(key)); }
+
+    function addAlloc(cid, key, count) {
+      cid = String(cid);
+      var room = remainFor(key);
+      var n = Math.min(Math.max(parseInt(count, 10) || 0, 0), room);
+      if (n <= 0) return 0;
+      alloc[cid] = alloc[cid] || [];
+      var same = alloc[cid].filter(function (a) { return a.key === key; })[0];
+      if (same) { same.count += n; }
+      else { seq += 1; alloc[cid].push({ id: seq, key: key, count: n }); }
+      return n;
+    }
+
+    // ── ② 요약 렌더 ───────────────────────────────────
+    function boxSvg(fill, label) {
+      var f = Math.max(0, Math.min(100, fill || 0));
+      var h = 40 * f / 100;
+      return '' +
+        '<svg class="cpg-box-svg" viewBox="0 0 72 64" role="img" aria-label="' + esc(label) + '">' +
+          '<rect class="cpg-box-fill" x="10" y="' + (54 - h) + '" width="52" height="' + h + '" rx="2" />' +
+          '<path class="cpg-box-body" d="M10 20 H62 V54 H10 Z" />' +
+          '<path class="cpg-box-flapL" d="M10 20 L2 8 H30 L36 20 Z" />' +
+          '<path class="cpg-box-flapR" d="M62 20 L70 8 H42 L36 20 Z" />' +
+          '<line class="cpg-box-seam" x1="36" y1="20" x2="36" y2="54" />' +
+          '<text class="cpg-box-label" x="36" y="42" text-anchor="middle">쿠팡박스</text>' +
+        "</svg>";
+    }
+
+    function kpi(label, value, hint) {
+      return '<div class="cpg-kpi"><span class="cpg-kpi-label">' + esc(label) + "</span>" +
+             '<strong class="cpg-kpi-value">' + esc(value) + "</strong>" +
+             '<span class="cpg-kpi-hint">' + esc(hint) + "</span></div>";
+    }
+
+    function renderSummary() {
+      if (!calc.results.length) {
+        sumEmpty.hidden = false;
+        sumBody.hidden = true;
+        return;
+      }
+      sumEmpty.hidden = true;
+      sumBody.hidden = false;
+
+      var totalProd = 0, remainProd = 0, leftoverUnits = 0;
+      calc.results.forEach(function (r) {
+        totalProd += r.full_boxes;
+        remainProd += remainFor(prodKey(r.product_code));
+        leftoverUnits += r.remainder_units;
+      });
+      var totalMix = 0, remainMix = 0;
+      calc.mixes.forEach(function (m) {
+        m.boxes.forEach(function (b, i) {
+          totalMix += 1;
+          remainMix += remainFor(mixKey(m.box_name, i));
+        });
+      });
+      var assigned = (totalProd + totalMix) - (remainProd + remainMix);
+
+      sumKpis.innerHTML =
+        kpi("총 박스", (totalProd + totalMix) + "박스", "제품별 " + totalProd + " + 혼합 " + totalMix) +
+        kpi("센터 배분", assigned + "박스", "③ 에 담긴 수량") +
+        kpi("미배분 잔여", (remainProd + remainMix) + "박스", "자투리 " + leftoverUnits + "개 포함");
+
+      var ph = "";
+      calc.results.forEach(function (r) {
+        var key = prodKey(r.product_code);
+        var remain = remainFor(key);
+        var used = r.full_boxes - remain;
+        ph += '<div class="cpg-sum-prod' + (remain ? " is-draggable" : " is-done") + '"' +
+                ' data-key="' + esc(key) + '">' +
+                '<div class="cpg-sum-prod-head">' +
+                  '<span class="cpg-sum-prod-name">' + esc(r.product_name) + "</span>" +
+                  '<span class="erp-badge erp-badge-neutral">' + esc(r.box_name) + "</span>" +
+                "</div>" +
+                '<div class="cpg-sum-prod-nums">' +
+                  "<strong>" + remain + "박스</strong>" +
+                  '<span class="erp-muted">' + (remain * r.units_per_box) + "개 · 총 " + r.full_boxes + "박스" +
+                    (used ? " · 배분 " + used : "") + "</span>" +
+                  (r.remainder_units
+                    ? '<span class="cpg-sum-left">자투리 ' + r.remainder_units + "개</span>"
+                    : '<span class="cpg-sum-exact">딱 맞음</span>') +
+                "</div>" +
+              "</div>";
+      });
+      sumProds.innerHTML = ph;
+
+      if (!calc.mixes.length) {
+        sumMixNote.textContent = "— 자투리 없음";
+        sumBoxes.innerHTML = '<p class="erp-muted">남는 낱개가 없습니다.</p>';
+      } else {
+        sumMixNote.textContent = "— 1장 = 1박스";
+        var bh = "", n = 0;
+        calc.mixes.forEach(function (m) {
+          m.boxes.forEach(function (b, i) {
+            var key = mixKey(m.box_name, i);
+            var remain = remainFor(key);
+            var items = b.items.map(function (it) {
+              return "<li><span>" + esc(it.product_name) + "</span><b>" + it.quantity + "개</b></li>";
+            }).join("");
+            bh += '<div class="cpg-box-card' + (remain ? " is-draggable" : " is-done") + '"' +
+                    ' data-key="' + esc(key) + '"' +
+                    ' style="animation-delay:' + (n * 60) + 'ms">' +
+                    '<div class="cpg-box-art">' + boxSvg(b.fill_percent, m.box_name) + "</div>" +
+                    '<div class="cpg-box-info">' +
+                      '<div class="cpg-box-title">' + esc(m.box_name) + " 혼합 #" + (i + 1) +
+                        (remain ? "" : ' <span class="erp-badge erp-badge-success">배분됨</span>') + "</div>" +
+                      '<ul class="cpg-box-items">' + items + "</ul>" +
+                      '<div class="cpg-box-bar"><span style="width:' + b.fill_percent + '%"></span></div>' +
+                      '<div class="cpg-box-fillnum">' + b.fill_percent + "% 채움 · " + units[key] + "개</div>" +
+                    "</div>" +
+                  "</div>";
+            n += 1;
+          });
+        });
+        sumBoxes.innerHTML = bh;
+      }
+    }
+
+    // ── ③ 센터 분배 렌더 ──────────────────────────────
+    function renderDist() {
+      if (!distList) return;
+      if (distEmpty) distEmpty.hidden = openCenters.length > 0;
+
+      var html = "";
+      openCenters.forEach(function (cid) {
+        var rows = alloc[cid] || [];
+        var boxes = 0, pieces = 0, items = "";
+        rows.forEach(function (a) {
+          var per = units[a.key] || 0;
+          boxes += a.count;
+          pieces += a.count * per;
+          items += '<li class="cpg-dist-item" data-entry="' + a.id + '">' +
+                     '<span class="cpg-dist-name">' + esc(labels[a.key] || a.key) + "</span>" +
+                     '<input class="erp-input cpg-dist-qty" type="number" min="1" step="1" value="' + a.count + '" />' +
+                     '<span class="cpg-dist-unit">박스 · ' + (a.count * per) + "개</span>" +
+                     '<button type="button" class="erp-btn erp-btn-danger cpg-dist-del" title="빼기" aria-label="빼기">✕</button>' +
+                   "</li>";
+        });
+        html += '<div class="cpg-dist-center' + (rows.length ? " has-items" : "") + '" data-drop-for="' + esc(cid) + '">' +
+                  '<div class="cpg-dist-head">' +
+                    "<strong>" + esc(centerName(cid)) + "</strong>" +
+                    '<span class="cpg-dist-sum">' +
+                      '<span class="erp-badge erp-badge-neutral">' + boxes + "박스</span>" +
+                      '<span class="erp-badge erp-badge-neutral">' + pieces + "개</span>" +
+                      '<button type="button" class="erp-btn erp-btn-outline cpg-dist-close" title="센터 빼기" aria-label="센터 빼기">✕</button>' +
+                    "</span>" +
+                  "</div>" +
+                  (rows.length
+                    ? '<ul class="cpg-dist-items">' + items + "</ul>"
+                    : '<p class="cpg-dist-hint">여기로 박스를 끌어다 놓기</p>') +
+                "</div>";
+      });
+      distList.innerHTML = html;
+    }
+
+    function render() { renderSummary(); renderDist(); }
+
+    // ── 수량 대화상자 ─────────────────────────────────
+    function openDialog(key, centerId) {
+      if (!openCenters.length) { msg.textContent = "먼저 ③ 에서 센터를 추가하세요."; return; }
+      var remain = remainFor(key);
+      if (remain <= 0) { msg.textContent = "남은 박스가 없습니다."; return; }
+
+      pending = { key: key };
+      dlgItem.textContent = (labels[key] || key) + " — 잔여 " + remain + "박스 (" + (remain * (units[key] || 0)) + "개)";
+      dlgCenter.innerHTML = openCenters.map(function (cid) {
+        return '<option value="' + esc(cid) + '"' + (String(cid) === String(centerId) ? " selected" : "") + ">" +
+               esc(centerName(cid)) + "</option>";
+      }).join("");
+      dlgQty.max = remain;
+      dlgQty.value = key.indexOf("m:") === 0 ? 1 : remain;
+      dlgHint.textContent = "1박스 = " + (units[key] || 0) + "개 · 최대 " + remain + "박스";
+      dlg.hidden = false;
+      dlgQty.focus();
+      dlgQty.select();
+    }
+
+    function closeDialog() { dlg.hidden = true; pending = null; }
+
+    function commitDialog(all) {
+      if (!pending) return;
+      var key = pending.key;
+      var cid = dlgCenter.value;
+      var want = all ? remainFor(key) : parseInt(dlgQty.value, 10);
+      var got = addAlloc(cid, key, want);
+      closeDialog();
+      render();
+      msg.textContent = got
+        ? centerName(cid) + " ← " + (labels[key] || key) + " " + got + "박스"
+        : "담을 수량이 없습니다.";
+    }
+
+    dlgOk.addEventListener("click", function () { commitDialog(false); });
+    dlgAll.addEventListener("click", function () { commitDialog(true); });
+    dlg.addEventListener("click", function (e) {
+      if (e.target.hasAttribute && e.target.hasAttribute("data-dlg-close")) closeDialog();
+    });
+    dlgQty.addEventListener("keydown", function (e) {
+      if (e.key === "Enter") { e.preventDefault(); commitDialog(false); }
+    });
+    document.addEventListener("keydown", function (e) {
+      if (e.key === "Escape" && !dlg.hidden) closeDialog();
+    });
+
+    // ── 드래그 (마우스 이벤트 기반) ───────────────────
+    // HTML5 네이티브 DnD(draggable + dragstart)는 브라우저에 따라 드래그가
+    // 아예 시작되지 않는다(웨일에서 미리보기조차 안 생김) → 직접 구현한다.
+    //  · mousedown 후 4px 이상 움직이면 드래그 시작, 카드 복제본(고스트)이 커서를 따라온다
+    //  · 커서 아래 요소를 elementFromPoint 로 찾아 센터 패널을 강조
+    //  · mouseup 위치의 센터에 놓으면 수량 대화상자가 열린다
+    //  · 드래그 없이 클릭하면 첫 번째 센터를 기본값으로 대화상자가 열린다
+    var drag = null;              // {key, card, ghost, startX, startY, moved}
+    var suppressClickOn = null;   // 드래그로 끝난 카드의 잔여 click 1회 무시
+    var DRAG_THRESHOLD = 4;
+
+    function clearOver() {
+      if (!distList) return;
+      Array.prototype.forEach.call(distList.querySelectorAll(".is-over"), function (el) {
+        el.classList.remove("is-over");
+      });
+    }
+
+    function zoneAt(x, y) {
+      if (!distList) return null;
+      var el = document.elementFromPoint ? document.elementFromPoint(x, y) : null;
+      var zone = el && el.closest ? el.closest("[data-drop-for]") : null;
+      if (zone) return zone;
+      // ③ 영역 안(패널 사이 여백 포함)에서 놓았고 센터가 하나뿐이면 그 센터로.
+      if (el && el.closest && el.closest(".cpg-dist-card") && openCenters.length === 1) {
+        return distList.querySelector("[data-drop-for]");
+      }
+      return null;
+    }
+
+    function moveGhost(x, y) {
+      if (!drag || !drag.ghost) return;
+      drag.ghost.style.left = (x + 12) + "px";
+      drag.ghost.style.top = (y + 12) + "px";
+    }
+
+    function startDrag(card, x, y) {
+      var ghost = card.cloneNode(true);
+      ghost.className = card.className + " cpg-drag-ghost";
+      ghost.removeAttribute("style");
+      ghost.style.width = card.offsetWidth ? card.offsetWidth + "px" : "240px";
+      document.body.appendChild(ghost);
+      drag.ghost = ghost;
+      drag.moved = true;
+      card.classList.add("is-dragging");
+      document.body.classList.add("cpg-dragging");
+      if (distCard) distCard.classList.add("is-drop-ready");
+      moveGhost(x, y);
+    }
+
+    function endDrag(commit, x, y, upTarget) {
+      if (!drag) return;
+      var key = drag.key, moved = drag.moved, card = drag.card;
+      if (drag.ghost && drag.ghost.parentNode) drag.ghost.parentNode.removeChild(drag.ghost);
+      if (drag.card) drag.card.classList.remove("is-dragging");
+      document.body.classList.remove("cpg-dragging");
+      if (distCard) distCard.classList.remove("is-drop-ready");
+      clearOver();
+      drag = null;
+      if (!moved) return;                  // 움직이지 않았으면 클릭으로 처리
+      // 카드 위에서 손을 뗀 경우에만 뒤따르는 click 을 1회 무시한다.
+      suppressClickOn = (card && upTarget && card.contains(upTarget)) ? card : null;
+      if (!commit) return;
+      var zone = zoneAt(x, y);
+      if (!zone) { msg.textContent = "센터 위에 놓아야 담깁니다."; return; }
+      openDialog(key, zone.getAttribute("data-drop-for"));
+    }
+
+    sumBody.addEventListener("mousedown", function (e) {
+      if (e.button !== 0) return;
+      var card = e.target.closest("[data-key]");
+      if (!card || card.classList.contains("is-done")) return;
+      drag = { key: card.getAttribute("data-key"), card: card, startX: e.clientX, startY: e.clientY, moved: false, ghost: null };
+      e.preventDefault();   // 텍스트 선택 방지
+    });
+
+    document.addEventListener("mousemove", function (e) {
+      if (!drag) return;
+      if (!drag.moved) {
+        if (Math.abs(e.clientX - drag.startX) < DRAG_THRESHOLD &&
+            Math.abs(e.clientY - drag.startY) < DRAG_THRESHOLD) return;
+        startDrag(drag.card, e.clientX, e.clientY);
+      }
+      moveGhost(e.clientX, e.clientY);
+      var zone = zoneAt(e.clientX, e.clientY);
+      clearOver();
+      if (zone) zone.classList.add("is-over");
+    });
+
+    document.addEventListener("mouseup", function (e) {
+      if (!drag) return;
+      endDrag(true, e.clientX, e.clientY, e.target);
+    });
+
+    document.addEventListener("keydown", function (e) {
+      if (e.key === "Escape" && drag) endDrag(false, 0, 0, null);
+    });
+
+    // 드래그하지 않고 클릭한 경우 — 첫 센터를 기본값으로 대화상자를 연다.
+    // (드래그를 끝낸 카드에서 브라우저가 한 번 더 쏘는 click 은 1회만 무시)
+    sumBody.addEventListener("click", function (e) {
+      var card = e.target.closest("[data-key]");
+      if (!card) return;
+      if (card === suppressClickOn) { suppressClickOn = null; return; }
+      openDialog(card.getAttribute("data-key"), openCenters[0]);
+    });
+
+    if (distList) {
+      distList.addEventListener("input", function (e) {
+        if (!e.target.classList.contains("cpg-dist-qty")) return;
+        var li = e.target.closest(".cpg-dist-item");
+        var cid = e.target.closest("[data-drop-for]").getAttribute("data-drop-for");
+        var entry = (alloc[cid] || []).filter(function (a) { return String(a.id) === li.getAttribute("data-entry"); })[0];
+        if (!entry) return;
+        var want = parseInt(e.target.value, 10);
+        if (isNaN(want) || want < 1) want = 1;
+        var max = entry.count + remainFor(entry.key);
+        if (want > max) { want = max; e.target.value = max; }
+        entry.count = want;
+        li.querySelector(".cpg-dist-unit").textContent = "박스 · " + (want * (units[entry.key] || 0)) + "개";
+        renderSummary();
+        updateCenterTotals(cid);
+      });
+
+      distList.addEventListener("click", function (e) {
+        var zone = e.target.closest("[data-drop-for]");
+        if (!zone) return;
+        var cid = zone.getAttribute("data-drop-for");
+        if (e.target.closest(".cpg-dist-close")) {         // 센터 자체를 목록에서 뺀다
+          openCenters = openCenters.filter(function (x) { return x !== cid; });
+          delete alloc[cid];
+          render();
+          return;
+        }
+        if (e.target.closest(".cpg-dist-del")) {           // 담은 항목 제거 → 잔여로 복귀
+          var li = e.target.closest(".cpg-dist-item");
+          alloc[cid] = (alloc[cid] || []).filter(function (a) { return String(a.id) !== li.getAttribute("data-entry"); });
+          render();
+        }
+      });
+    }
+
+    function updateCenterTotals(cid) {
+      var zone = distList.querySelector('[data-drop-for="' + cid + '"]');
+      if (!zone) return;
+      var boxes = 0, pieces = 0;
+      (alloc[cid] || []).forEach(function (a) {
+        boxes += a.count;
+        pieces += a.count * (units[a.key] || 0);
+      });
+      var badges = zone.querySelectorAll(".cpg-dist-sum .erp-badge");
+      if (badges[0]) badges[0].textContent = boxes + "박스";
+      if (badges[1]) badges[1].textContent = pieces + "개";
+    }
+
+    if (centerAdd) {
+      centerAdd.addEventListener("click", function () {
+        var cid = centerPick.value;
+        if (!cid) return;
+        if (openCenters.indexOf(cid) >= 0) { msg.textContent = "이미 추가된 센터입니다."; return; }
+        openCenters.push(cid);
+        renderDist();
+      });
+    }
+
+    // ── 입력 표 이벤트 ────────────────────────────────
+    tbody.addEventListener("click", function (e) {
+      if (!e.target.closest(".cpg-calc-del")) return;
+      if (rowsArr().length <= 1) addRow("", 0);
+      e.target.closest("tr").remove();
+      msg.textContent = "";
+    });
+
+    tbody.addEventListener("input", function (e) {
+      if (e.target.classList.contains("cpg-calc-qty")) msg.textContent = "수량 변경됨 — 재계산하세요.";
+    });
+    tbody.addEventListener("change", function (e) {
+      if (e.target.classList.contains("cpg-calc-name")) msg.textContent = "제품 변경됨 — 재계산하세요.";
+    });
+
+    // 수량 칸: Tab = 다음 행 수량(마지막 행이면 새 행 추가), Enter = 계산
+    tbody.addEventListener("keydown", function (e) {
+      if (!e.target.classList.contains("cpg-calc-qty")) return;
+      if (e.key === "Enter") { e.preventDefault(); run(); return; }
+      if (e.key !== "Tab" || e.shiftKey) return;
+      e.preventDefault();
+      var rows = rowsArr();
+      var idx = rows.indexOf(e.target.closest("tr"));
+      var next = rows[idx + 1] || addRow("", 0);
+      var input = next.querySelector(".cpg-calc-qty");
+      input.focus();
+      input.select();
+    });
+
+    runBtn.addEventListener("click", run);
+    addBtn.addEventListener("click", function () {
+      addRow("", 0).querySelector(".cpg-calc-name").focus();
+    });
+    resetBtn.addEventListener("click", function () {
+      tbody.innerHTML = "";
+      addRow("", 0);
+      calc = { results: [], mixes: [] };
+      alloc = {};
+      render();
+      msg.textContent = "";
+    });
+
+    addRow("", 0);
+    render();
+  })();
+  </script>
+  {% endif %}
+
+</section>
+{% endblock %}

app/modules/cupang/templates/cupang/box_rules.html

@@ -1,6 +1,6 @@
 {% extends "erp_base.html" %}
 
-{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260530p" />{% endblock %}
+{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260829g" />{% endblock %}
 
 {% block content %}
 <section class="cpg">

app/modules/cupang/templates/cupang/centers.html

@@ -1,6 +1,6 @@
 {% extends "erp_base.html" %}
 
-{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260530p" />{% endblock %}
+{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260829g" />{% endblock %}
 
 {% block content %}
 <section class="cpg">

app/modules/cupang/templates/cupang/detail.html

@@ -1,6 +1,6 @@
 {% extends "erp_base.html" %}
 
-{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260530p" />{% endblock %}
+{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260829g" />{% endblock %}
 
 {% block content %}
 <section class="cpg">

app/modules/cupang/templates/cupang/form.html

@@ -1,6 +1,6 @@
 {% extends "erp_base.html" %}
 
-{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260530p" />{% endblock %}
+{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260829g" />{% endblock %}
 
 {% block content %}
 <section class="cpg">

app/modules/cupang/templates/cupang/index.html

@@ -1,6 +1,6 @@
 {% extends "erp_base.html" %}
 
-{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260530p" />{% endblock %}
+{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260829g" />{% endblock %}
 
 {% block content %}
 <section class="cpg">
@@ -13,6 +13,7 @@
         <a class="erp-btn erp-btn-outline" href="/cupang/products">제품명 설정</a>
         <a class="erp-btn erp-btn-outline" href="/cupang/centers">입고센터 관리</a>
         <a class="erp-btn erp-btn-outline" href="/cupang/box-rules">박스 입수량 설정</a>
+        <a class="erp-btn erp-btn-outline" href="/cupang/box-calc">박스 계산</a>
       </span>
     </div>
     <div class="cpg-actions-spacer"></div>

app/modules/cupang/templates/cupang/products.html

@@ -1,6 +1,6 @@
 {% extends "erp_base.html" %}
 
-{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260530p" />{% endblock %}
+{% block head_extra %}<link rel="stylesheet" href="/static/cupang.css?v=20260829g" />{% endblock %}
 
 {% block content %}
 <section class="cpg">
@@ -21,6 +21,21 @@
         </span>
       </div>
 
+      <!-- 수기 추가: itemcode_db 에 없는 상품도 직접 등록 -->
+      <form method="post" action="/cupang/products" class="cpg-prod-manual">
+        <div class="cpg-prod-manual-head">
+          <strong>수기 추가</strong>
+          <span class="erp-muted">아래 목록에 없는 상품을 직접 등록합니다. 같은 제품코드는 덮어씁니다.</span>
+        </div>
+        <div class="cpg-prod-manual-row">
+          <label class="erp-field"><span>제품명 *</span>
+            <input class="erp-input" type="text" name="product_name" required placeholder="예: 미라네 12호 세트" /></label>
+          <label class="erp-field"><span>제품코드 *</span>
+            <input class="erp-input" type="text" name="product_code" required placeholder="예: MS-1012" /></label>
+          <button type="submit" class="erp-btn erp-btn-primary">추가</button>
+        </div>
+      </form>
+
       {% if search_enabled %}
       <div class="cpg-inline-form" style="margin-bottom:10px;">
         <input class="erp-input" type="text" id="cpg-prod-q" placeholder="이름/코드 필터" style="min-width:200px" />
@@ -38,10 +53,17 @@
         <span class="erp-muted">폼의 제품명 드롭다운에 노출</span></div>
       <div class="erp-table-wrap cpg-reg-scroll">
         <table class="erp-table">
-          <thead><tr><th>제품명</th><th>제품코드</th><th>상태</th><th>동작</th></tr></thead>
+          <thead>
-          <tbody>
+            <tr>
+              <th><button type="button" class="cpg-sort" data-sort-key="name">제품명<span class="cpg-sort-ind" aria-hidden="true"></span></button></th>
+              <th><button type="button" class="cpg-sort" data-sort-key="code">제품코드<span class="cpg-sort-ind" aria-hidden="true"></span></button></th>
+              <th>상태</th>
+              <th>동작</th>
+            </tr>
+          </thead>
+          <tbody id="cpg-prod-tbody">
             {% for p in products %}
-            <tr {% if not p.active %}style="opacity:.55"{% endif %}>
+            <tr data-name="{{ p.product_name }}" data-code="{{ p.product_code }}" {% if not p.active %}style="opacity:.55"{% endif %}>
               <td>{{ p.product_name }}</td>
               <td>{{ p.product_code }}</td>
               <td>{% if p.active %}<span class="erp-badge erp-badge-success">활성</span>{% else %}<span class="erp-badge erp-badge-neutral">비활성</span>{% endif %}</td>
@@ -67,7 +89,7 @@
             </tr>
             {% endfor %}
             {% if not products %}
-            <tr><td colspan="4" class="erp-muted">등록된 제품명이 없습니다. 왼쪽에서 선택해 등록하세요.</td></tr>
+            <tr class="cpg-no-sort"><td colspan="4" class="erp-muted">등록된 제품명이 없습니다. 왼쪽에서 선택해 등록하세요.</td></tr>
             {% endif %}
           </tbody>
         </table>
@@ -77,6 +99,43 @@
   </div>
 </section>
 
+<script>
+// 등록된 제품명 표 — 제품명/제품코드 오름차순·내림차순 정렬 (클라이언트).
+(function () {
+  var tbody = document.getElementById("cpg-prod-tbody");
+  if (!tbody) return;
+  var buttons = Array.prototype.slice.call(document.querySelectorAll(".cpg-sort"));
+  var state = { key: null, dir: 1 };
+  var collator = new Intl.Collator("ko", { numeric: true, sensitivity: "base" });
+
+  function apply() {
+    var rows = Array.prototype.slice.call(tbody.querySelectorAll("tr:not(.cpg-no-sort)"));
+    if (rows.length < 2) return;
+    rows.sort(function (a, b) {
+      var av = a.getAttribute("data-" + state.key) || "";
+      var bv = b.getAttribute("data-" + state.key) || "";
+      return collator.compare(av, bv) * state.dir;
+    });
+    rows.forEach(function (r) { tbody.appendChild(r); });
+  }
+
+  buttons.forEach(function (btn) {
+    btn.addEventListener("click", function () {
+      var key = btn.getAttribute("data-sort-key");
+      if (state.key === key) { state.dir = -state.dir; }
+      else { state.key = key; state.dir = 1; }
+      buttons.forEach(function (b) {
+        var on = b === btn;
+        b.classList.toggle("is-asc", on && state.dir === 1);
+        b.classList.toggle("is-desc", on && state.dir === -1);
+        b.closest("th").setAttribute("aria-sort", on ? (state.dir === 1 ? "ascending" : "descending") : "none");
+      });
+      apply();
+    });
+  });
+})();
+</script>
+
 {% if search_enabled %}
 <script type="application/json" id="cpg-registered">{{ registered_codes | tojson }}</script>
 <script>

app/modules/dispatch/__init__.py

@@ -0,0 +1,47 @@
+"""말레이시아 TikTok 출고관리(dispatch) 모듈.
+
+라우터/저장소/파서/템플릿을 한 디렉토리에서 관리한다.
+- 라우터: `router.py` (FastAPI APIRouter, prefix=/dispatch)
+- 저장소: `db.py` (dispatch_db / PostgreSQL 전용)
+- 파서:   `parser.py` (TikTok Order Export XLSX → 박스 묶기, openpyxl)
+- 순수 로직: `store.py` (컬럼 정규화/박스 묶기/SKU 합산/상태 상수)
+- 템플릿: `templates/dispatch/`
+
+데이터 저장은 dispatch_db 전용이다. DISPATCH_DB_URL 미설정 시
+build_dispatch_store 는 None 을 반환하고, 라우터가 "설정 필요" 안내 페이지를
+보여준다(앱은 죽지 않음).
+
+업로드 원본 파일은 DATA_DIR/dispatch/<날짜>/<배치>/ 아래에 저장하고, DB 에는
+경로만 기록한다. 고객 이름/주소/전화 등 개인정보는 저장하지 않는다.
+"""
+
+from typing import Any
+
+from . import store
+from .parser import ParseError, parse_order_export
+from .router import router
+from .store import STATUS_FIELDS, STATUS_LABELS, group_parcels, sku_summary
+
+__all__ = [
+    "router",
+    "store",
+    "STATUS_FIELDS",
+    "STATUS_LABELS",
+    "group_parcels",
+    "sku_summary",
+    "parse_order_export",
+    "ParseError",
+    "build_dispatch_store",
+]
+
+
+def build_dispatch_store(*, dsn: str | None) -> Any:
+    """DISPATCH_DB_URL 이 있으면 DispatchStore, 없으면 None.
+
+    JSON 폴백을 두지 않는다(운영 데이터 분기 방지). None 이면 라우터가 안내 표시.
+    """
+    if not dsn:
+        return None
+    from .db import DispatchStore  # 지연 import (개발 환경 deps 없을 수 있음)
+
+    return DispatchStore(dsn)

app/modules/dispatch/db.py

@@ -0,0 +1,469 @@
+"""dispatch_db PostgreSQL 저장소.
+
+- 드라이버: psycopg 3 (`psycopg[binary,pool]`) — 다른 모듈과 동일 패턴.
+- 연결 정보: 환경변수 `DISPATCH_DB_URL`
+  (예: postgresql://dispatch_app:<pwd>@postgres-db:5432/dispatch_db)
+- 스키마는 앱이 만들지 않는다. `scripts/sql/dispatch_db_init.sql` 을 superuser 가
+  사전 적용한다. 앱 계정(dispatch_app)은 CRUD 권한만 받는다.
+- 연결 풀은 lazy open — 부팅 시 DB 가 잠시 끊겨도 컨테이너가 죽지 않게.
+
+박스 묶기/SKU 합산 등 순수 로직은 `store.py` 에 있고, 여기서는 DB I/O 와
+조립만 담당한다.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date, datetime
+from typing import Any
+
+from psycopg.rows import dict_row
+from psycopg_pool import ConnectionPool
+
+from app.timezone import KST
+
+from . import store
+
+logger = logging.getLogger("dispatch.db")
+
+
+class DispatchStore:
+    def __init__(self, dsn: str, *, min_size: int = 1, max_size: int = 5):
+        self._pool = ConnectionPool(
+            conninfo=dsn,
+            min_size=min_size,
+            max_size=max_size,
+            kwargs={"row_factory": dict_row, "autocommit": True},
+            open=False,
+        )
+        self._pool.open(wait=False)
+
+    def close(self) -> None:
+        self._pool.close()
+
+    # ════════════════════════════════════════════════════════════
+    # 배치
+    # ════════════════════════════════════════════════════════════
+    def create_batch(
+        self,
+        *,
+        platform: str,
+        dispatch_date: str,
+        batch_name: str,
+        picking_pdf_path: str = "",
+        label_pdf_path: str = "",
+        order_export_path: str = "",
+    ) -> dict[str, Any]:
+        if not (dispatch_date or "").strip():
+            raise ValueError("출고 날짜는 필수입니다.")
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                """
+                INSERT INTO dispatch_batches
+                    (platform, dispatch_date, batch_name,
+                     picking_pdf_path, label_pdf_path, order_export_path)
+                VALUES (%s,%s,%s,%s,%s,%s)
+                RETURNING *
+                """,
+                (
+                    (platform or "TikTok").strip(),
+                    dispatch_date.strip(),
+                    (batch_name or "").strip(),
+                    (picking_pdf_path or "").strip(),
+                    (label_pdf_path or "").strip(),
+                    (order_export_path or "").strip(),
+                ),
+            ).fetchone()
+        return self._serialize(row)
+
+    def add_parcels(self, *, batch_id: int, parcels: list[dict[str, Any]]) -> int:
+        """파서 결과(parcels)를 박스+상품으로 일괄 저장. 반환: 저장한 박스 수.
+
+        한 트랜잭션. 같은 박스 안 같은 SKU 는 파서가 이미 합산해서 들어온다.
+        """
+        saved = 0
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                for p in parcels:
+                    parcel_row = conn.execute(
+                        """
+                        INSERT INTO dispatch_parcels
+                            (batch_id, seq, order_id, package_id,
+                             tracking_id, shipping_provider,
+                             recipient_name, recipient_phone, recipient_address)
+                        VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s)
+                        RETURNING id
+                        """,
+                        (
+                            batch_id,
+                            int(p.get("seq") or (saved + 1)),
+                            (p.get("order_id") or "").strip(),
+                            (p.get("package_id") or "").strip(),
+                            (p.get("tracking_id") or "").strip(),
+                            (p.get("shipping_provider") or "").strip(),
+                            (p.get("recipient_name") or "").strip(),
+                            (p.get("recipient_phone") or "").strip(),
+                            (p.get("recipient_address") or "").strip(),
+                        ),
+                    ).fetchone()
+                    parcel_id = parcel_row["id"]
+                    for it in p.get("items", []):
+                        conn.execute(
+                            """
+                            INSERT INTO dispatch_items
+                                (parcel_id, seller_sku, product_name, quantity)
+                            VALUES (%s,%s,%s,%s)
+                            """,
+                            (
+                                parcel_id,
+                                (it.get("seller_sku") or "").strip(),
+                                (it.get("product_name") or "").strip(),
+                                int(it.get("quantity") or 1),
+                            ),
+                        )
+                    saved += 1
+        return saved
+
+    def list_batches(self, *, limit: int = 200) -> list[dict[str, Any]]:
+        """배치 목록 + 박스 수/완료(택배스캔) 수 요약."""
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                """
+                SELECT b.*,
+                       COUNT(p.id) AS parcel_count,
+                       COUNT(p.id) FILTER (
+                           WHERE p.label_attached AND p.handed_to_kagayaku
+                       ) AS done_count
+                FROM dispatch_batches b
+                LEFT JOIN dispatch_parcels p ON p.batch_id = b.id
+                GROUP BY b.id
+                ORDER BY b.dispatch_date DESC, b.id DESC
+                LIMIT %s
+                """,
+                (int(limit),),
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def get_batch(self, *, batch_id: int) -> dict[str, Any] | None:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT * FROM dispatch_batches WHERE id = %s", (batch_id,)
+            ).fetchone()
+        return self._serialize(row) if row else None
+
+    def delete_batch(self, *, batch_id: int) -> None:
+        """배치 + 하위 박스/상품/로그 전체 삭제(CASCADE)."""
+        with self._pool.connection() as conn:
+            cur = conn.execute("DELETE FROM dispatch_batches WHERE id = %s", (batch_id,))
+            if cur.rowcount == 0:
+                raise KeyError(batch_id)
+
+    # ════════════════════════════════════════════════════════════
+    # 박스(parcel)
+    # ════════════════════════════════════════════════════════════
+    def list_parcels(self, *, batch_id: int) -> list[dict[str, Any]]:
+        """배치의 박스 전체 + 각 박스의 상품 목록(seq 순)."""
+        with self._pool.connection() as conn:
+            parcel_rows = conn.execute(
+                "SELECT * FROM dispatch_parcels WHERE batch_id = %s "
+                "ORDER BY seq ASC, id ASC",
+                (batch_id,),
+            ).fetchall()
+            item_rows = conn.execute(
+                """
+                SELECT i.* FROM dispatch_items i
+                JOIN dispatch_parcels p ON p.id = i.parcel_id
+                WHERE p.batch_id = %s
+                ORDER BY i.seller_sku ASC, i.id ASC
+                """,
+                (batch_id,),
+            ).fetchall()
+        items_by_parcel: dict[int, list[dict[str, Any]]] = {}
+        for r in item_rows:
+            items_by_parcel.setdefault(r["parcel_id"], []).append(self._serialize(r))
+        parcels: list[dict[str, Any]] = []
+        for r in parcel_rows:
+            p = self._serialize(r)
+            p["items"] = items_by_parcel.get(r["id"], [])
+            parcels.append(p)
+        return parcels
+
+    def sku_summary(self, *, batch_id: int) -> list[dict[str, Any]]:
+        """배치 전체 SKU별 총 수량(피킹 요약). seller_sku 오름차순."""
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                """
+                SELECT i.seller_sku,
+                       MAX(i.product_name)  AS product_name,
+                       SUM(i.quantity)::int AS total_qty
+                FROM dispatch_items i
+                JOIN dispatch_parcels p ON p.id = i.parcel_id
+                WHERE p.batch_id = %s
+                GROUP BY i.seller_sku
+                ORDER BY i.seller_sku ASC
+                """,
+                (batch_id,),
+            ).fetchall()
+        return [
+            {
+                "seller_sku": r["seller_sku"],
+                "product_name": r["product_name"] or "",
+                "total_qty": int(r["total_qty"] or 0),
+            }
+            for r in rows
+        ]
+
+    def toggle_status(
+        self, *, parcel_id: int, field: str, worker_name: str = ""
+    ) -> dict[str, Any]:
+        """박스의 작업 상태 boolean 1개를 토글하고 로그를 남긴다.
+
+        반환: {"parcel_id", "field", "value"(토글 후 값)}.
+        field 는 store.STATUS_FIELDS 화이트리스트 검증(SQL 식별자 안전).
+        """
+        if field not in store.STATUS_FIELDS:
+            raise ValueError(f"허용되지 않는 작업 상태: {field}")
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                cur = conn.execute(
+                    # field 는 화이트리스트라 인젝션 위험 없음. RETURNING 으로 새 값 확인.
+                    f"UPDATE dispatch_parcels SET {field} = NOT {field} "
+                    "WHERE id = %s RETURNING " + field,
+                    (parcel_id,),
+                ).fetchone()
+                if cur is None:
+                    raise KeyError(parcel_id)
+                new_value = bool(cur[field])
+                conn.execute(
+                    """
+                    INSERT INTO dispatch_logs
+                        (parcel_id, action, old_value, new_value, worker_name)
+                    VALUES (%s,%s,%s,%s,%s)
+                    """,
+                    (
+                        parcel_id,
+                        field,
+                        str(not new_value).lower(),
+                        str(new_value).lower(),
+                        (worker_name or "").lower().strip(),
+                    ),
+                )
+        return {"parcel_id": parcel_id, "field": field, "value": new_value}
+
+    def bulk_set_status(
+        self, *, batch_id: int, field: str, value: bool = True, worker_name: str = ""
+    ) -> int:
+        """배치 내 모든 박스의 작업 상태 1개를 value 로 일괄 설정. 변경된 박스만 로그.
+
+        반환: 실제로 바뀐 박스 수(이미 value 인 박스는 건드리지 않음).
+        field 는 store.STATUS_FIELDS 화이트리스트 검증(SQL 식별자 안전).
+        """
+        if field not in store.STATUS_FIELDS:
+            raise ValueError(f"허용되지 않는 작업 상태: {field}")
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                rows = conn.execute(
+                    # field 는 화이트리스트라 인젝션 위험 없음.
+                    f"UPDATE dispatch_parcels SET {field} = %s "
+                    f"WHERE batch_id = %s AND {field} = %s RETURNING id",
+                    (value, batch_id, not value),
+                ).fetchall()
+                ids = [r["id"] for r in rows]
+                if ids:
+                    conn.execute(
+                        """
+                        INSERT INTO dispatch_logs
+                            (parcel_id, action, old_value, new_value, worker_name)
+                        SELECT unnest(%s::bigint[]), %s, %s, %s, %s
+                        """,
+                        (
+                            ids,
+                            field,
+                            str(not value).lower(),
+                            str(value).lower(),
+                            (worker_name or "").lower().strip(),
+                        ),
+                    )
+        return len(ids)
+
+    def stock_aggregate_for_date(self, *, dispatch_date: str) -> list[dict[str, Any]]:
+        """해당 날짜 모든 배치의 SKU별 합산 수량.
+
+        반환: [{"seller_sku", "qty"}]. _N 배수/콤보 분해는 호출부(export)에서 적용.
+        """
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                """
+                SELECT i.seller_sku, SUM(i.quantity)::int AS qty
+                FROM dispatch_items i
+                JOIN dispatch_parcels p ON p.id = i.parcel_id
+                JOIN dispatch_batches b ON b.id = p.batch_id
+                WHERE b.dispatch_date = %s
+                GROUP BY i.seller_sku
+                ORDER BY i.seller_sku ASC
+                """,
+                (dispatch_date,),
+            ).fetchall()
+        return [
+            {"seller_sku": r["seller_sku"] or "", "qty": int(r["qty"] or 0)}
+            for r in rows
+        ]
+
+    # ════════════════════════════════════════════════════════════
+    # 말레이시아 재고 차감 1회성 가드
+    # ════════════════════════════════════════════════════════════
+    def deduction_exists(self, *, dispatch_date: str) -> bool:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT 1 FROM dispatch_stock_deductions WHERE dispatch_date = %s",
+                (dispatch_date,),
+            ).fetchone()
+        return row is not None
+
+    def list_deducted_dates(self) -> list[str]:
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                "SELECT dispatch_date FROM dispatch_stock_deductions "
+                "ORDER BY dispatch_date DESC"
+            ).fetchall()
+        out: list[str] = []
+        for r in rows:
+            d = r["dispatch_date"]
+            out.append(d.isoformat() if isinstance(d, date) else str(d))
+        return out
+
+    def record_deduction(
+        self,
+        *,
+        dispatch_date: str,
+        warehouse_code: str,
+        single_lines: int,
+        combo_lines: int,
+        worker_name: str = "",
+    ) -> None:
+        """차감 완료 기록. 이미 있으면 충돌(재차감 차단)."""
+        with self._pool.connection() as conn:
+            conn.execute(
+                """
+                INSERT INTO dispatch_stock_deductions
+                    (dispatch_date, warehouse_code, single_lines, combo_lines, worker_name)
+                VALUES (%s,%s,%s,%s,%s)
+                """,
+                (
+                    dispatch_date,
+                    (warehouse_code or "").strip(),
+                    int(single_lines),
+                    int(combo_lines),
+                    (worker_name or "").lower().strip(),
+                ),
+            )
+
+    def search_parcels(self, *, query: str, limit: int = 50) -> list[dict[str, Any]]:
+        """주문번호/패키지번호/송장번호/받는 사람 이름(부분 일치)로 박스를 찾는다.
+
+        4개 필드 어디든 query 가 포함되면 매칭. 받는 사람(이름/전화/주소)과
+        소속 배치(날짜/플랫폼/배치명/id) + 박스 seq 를 함께 돌려준다.
+        최신 출고일/배치 우선. query 가 비면 빈 리스트.
+        """
+        q = (query or "").strip()
+        if not q:
+            return []
+        like = f"%{q}%"
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                """
+                SELECT p.id            AS parcel_id,
+                       p.seq,
+                       p.order_id,
+                       p.package_id,
+                       p.tracking_id,
+                       p.shipping_provider,
+                       p.recipient_name,
+                       p.recipient_phone,
+                       p.recipient_address,
+                       p.label_attached,
+                       p.handed_to_kagayaku,
+                       b.id            AS batch_id,
+                       b.dispatch_date,
+                       b.platform,
+                       b.batch_name
+                FROM dispatch_parcels p
+                JOIN dispatch_batches b ON b.id = p.batch_id
+                WHERE p.order_id       ILIKE %(like)s
+                   OR p.package_id     ILIKE %(like)s
+                   OR p.tracking_id    ILIKE %(like)s
+                   OR p.recipient_name ILIKE %(like)s
+                ORDER BY b.dispatch_date DESC, b.id DESC, p.seq ASC
+                LIMIT %(limit)s
+                """,
+                {"like": like, "limit": int(limit)},
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def parcel_batch_id(self, *, parcel_id: int) -> int | None:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT batch_id FROM dispatch_parcels WHERE id = %s", (parcel_id,)
+            ).fetchone()
+        return int(row["batch_id"]) if row else None
+
+    # ════════════════════════════════════════════════════════════
+    # Kagayaku 전달 요약
+    # ════════════════════════════════════════════════════════════
+    def handover_summary(self, *, batch_id: int) -> dict[str, Any]:
+        """배송사별 박스 수 + Tracking ID 목록(전달 리스트/인쇄용)."""
+        with self._pool.connection() as conn:
+            provider_rows = conn.execute(
+                """
+                SELECT COALESCE(NULLIF(shipping_provider, ''), '(미지정)') AS provider,
+                       COUNT(*)::int AS box_count
+                FROM dispatch_parcels
+                WHERE batch_id = %s
+                GROUP BY provider
+                ORDER BY box_count DESC, provider ASC
+                """,
+                (batch_id,),
+            ).fetchall()
+            tracking_rows = conn.execute(
+                """
+                SELECT seq, order_id, tracking_id, shipping_provider
+                FROM dispatch_parcels
+                WHERE batch_id = %s
+                ORDER BY seq ASC, id ASC
+                """,
+                (batch_id,),
+            ).fetchall()
+        total = sum(int(r["box_count"]) for r in provider_rows)
+        return {
+            "total_boxes": total,
+            "by_provider": [
+                {"provider": r["provider"], "box_count": int(r["box_count"])}
+                for r in provider_rows
+            ],
+            "tracking_list": [self._serialize(r) for r in tracking_rows],
+        }
+
+    # ════════════════════════════════════════════════════════════
+    # 직렬화
+    # ════════════════════════════════════════════════════════════
+    @staticmethod
+    def _serialize(row: dict[str, Any] | None) -> dict[str, Any] | None:
+        if row is None:
+            return None
+        out = dict(row)
+        for k, v in list(out.items()):
+            if isinstance(v, datetime):
+                out[k] = v.astimezone(KST).isoformat(timespec="seconds")
+            elif isinstance(v, date):
+                out[k] = v.isoformat()
+        for k in ("id", "batch_id", "parcel_id", "seq", "quantity",
+                  "parcel_count", "done_count", "total_qty", "box_count"):
+            if k in out and out[k] is not None:
+                try:
+                    out[k] = int(out[k])
+                except (TypeError, ValueError):
+                    pass
+        for k in store.STATUS_FIELDS:
+            if k in out:
+                out[k] = bool(out[k])
+        return out

app/modules/dispatch/export.py

@@ -0,0 +1,279 @@
+"""출고 배치 → 취합 엑셀(openpyxl) 생성.
+
+다운로드 zip 에 업로드 원본과 함께 넣는 '출고 엑셀'을 만든다. 1박스 안에 여러
+SKU 가 있으면 SKU 당 1행으로 펼치고 박스 단위(받는 사람/주문/택배) 정보는 반복한다.
+
+파일명 형식: 2026.06.22(Mon)_tictoc.xlsx  (Shopee 는 끝이 _shopee).
+  - TikTok 은 운영 요청 철자에 맞춰 'tictoc' 을 쓴다.
+"""
+
+from __future__ import annotations
+
+import io
+import re
+from datetime import date, datetime
+from typing import Any
+
+# 엑셀 컬럼(요청 순서). (헤더, 박스/배치/상품 키)
+_COLUMNS: tuple[tuple[str, str], ...] = (
+    ("발송 날짜", "dispatch_date"),
+    ("고객 이름", "recipient_name"),
+    ("전화번호", "recipient_phone"),
+    ("주소", "recipient_address"),
+    ("상품이름", "product_name"),
+    ("아이템 코드", "seller_sku"),
+    ("주문 수량", "quantity"),
+    ("오더번호", "order_id"),
+    ("택배사", "shipping_provider"),
+    ("택배송장번호", "tracking_id"),
+    ("주문처", "platform"),
+)
+
+# 플랫폼 → 파일명 접미사.
+_PLATFORM_SUFFIX: dict[str, str] = {
+    "TikTok": "tictoc",
+    "Shopee": "shopee",
+}
+
+
+def export_filename(*, dispatch_date: str, platform: str) -> str:
+    """2026.06.22(Mon)_tictoc.xlsx 형식 파일명. 날짜 파싱 실패 시 원문 사용."""
+    d = _parse_date(dispatch_date)
+    if d is not None:
+        stamp = d.strftime("%Y.%m.%d(%a)")
+    else:
+        stamp = (dispatch_date or "").strip() or "dispatch"
+    suffix = _PLATFORM_SUFFIX.get((platform or "").strip(), (platform or "dispatch").strip().lower())
+    return f"{stamp}_{suffix}.xlsx"
+
+
+def split_sku(seller_sku: str) -> tuple[str, int]:
+    """seller_sku → (아이템코드, 배수).
+
+    끝의 `_<숫자>` 는 '같은 상품 N개'를 뜻한다(예: MT-0320_3 → 코드 MT-0320, 3개).
+    접미사가 없으면 배수 1.
+    """
+    s = (seller_sku or "").strip()
+    m = re.search(r"_(\d+)$", s)
+    if m:
+        return s[: m.start()], int(m.group(1))
+    return s, 1
+
+
+def resolve_product_name(seller_sku: str, name_map: dict[str, str], fallback: str = "") -> str:
+    """아이템코드(seller_sku)로 itemcode_db 상품명을 찾는다.
+
+    seller_sku 는 변형 접미사가 붙을 수 있다(예: MT-0320_3 → DB 는 MT-0320).
+    정확 일치 → 접미사(_숫자) 제거 후 일치 → 없으면 fallback(파싱된 상품명).
+    """
+    key = (seller_sku or "").strip().upper()
+    if not key:
+        return fallback
+    if key in name_map:
+        return name_map[key]
+    base = re.sub(r"_\d+$", "", key)
+    if base != key and base in name_map:
+        return name_map[base]
+    return fallback
+
+
+def build_workbook_bytes(
+    *,
+    batch: dict[str, Any],
+    parcels: list[dict[str, Any]],
+    name_map: dict[str, str] | None = None,
+) -> bytes:
+    """배치 + 박스(상품 포함) → xlsx 바이트.
+
+    parcels 각 항목은 db.list_parcels 결과(items 포함, recipient_* 포함).
+    name_map: itemcode_db 의 {코드(대문자): 상품명}. 있으면 아이템코드로 상품명을
+    조회해 채운다(없으면 파싱된 상품명 사용).
+    """
+    name_map = name_map or {}
+    from openpyxl import Workbook  # noqa: WPS433 — 지연 import
+    from openpyxl.styles import Font
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "출고"
+
+    headers = [h for h, _ in _COLUMNS]
+    ws.append(headers)
+    for cell in ws[1]:
+        cell.font = Font(bold=True)
+
+    dispatch_date = batch.get("dispatch_date", "") or ""
+    platform = batch.get("platform", "") or ""
+
+    for p in parcels:
+        box = {
+            "dispatch_date": dispatch_date,
+            "platform": platform,
+            "recipient_name": p.get("recipient_name", "") or "",
+            "recipient_phone": p.get("recipient_phone", "") or "",
+            "recipient_address": p.get("recipient_address", "") or "",
+            "order_id": p.get("order_id", "") or "",
+            "shipping_provider": p.get("shipping_provider", "") or "",
+            "tracking_id": p.get("tracking_id", "") or "",
+        }
+        items = p.get("items") or [{}]
+        for it in items:
+            row_data = dict(box)
+            sku = it.get("seller_sku", "") or ""
+            base_code, mult = split_sku(sku)
+            row_data["product_name"] = resolve_product_name(
+                base_code, name_map, fallback=it.get("product_name", "") or ""
+            )
+            row_data["seller_sku"] = base_code  # 접미사(_N) 제거한 실제 아이템코드
+            qty = it.get("quantity")
+            row_data["quantity"] = (int(qty) * mult) if qty is not None else ""
+            ws.append([_cell(row_data.get(key, "")) for _, key in _COLUMNS])
+
+    _autosize(ws, headers)
+
+    buf = io.BytesIO()
+    wb.save(buf)
+    return buf.getvalue()
+
+
+# ── 사방넷 재고 업로드 엑셀(낱개 분해) ──
+_STOCK_HEADERS: tuple[str, ...] = ("상품코드[필수]", "가용수량", "불용수량", "바코드")
+_LID_PREFIX = "MD-"  # 뚜껑 — 재고 집계 제외
+_SET_PREFIX = "MY-"  # 콤보(세트)
+
+
+def split_singles_combos(
+    rows: list[dict[str, Any]],
+) -> tuple[dict[str, int], dict[str, int]]:
+    """SKU별 합산 행 → (낱개 {code: qty}, 콤보 {code: qty}).
+
+    _N 배수 반영, MD-(뚜껑) 제외. 콤보는 MY- 접두사. 분해는 하지 않는다
+    (말레이시아 재고관리가 세트 OUT 시 BOM 으로 분해하므로 콤보 그대로 넘긴다).
+    """
+    singles: dict[str, int] = {}
+    combos: dict[str, int] = {}
+    for r in rows:
+        base, mult = split_sku(r.get("seller_sku", ""))
+        base = base.upper()
+        if not base:
+            continue
+        pieces = int(r.get("qty", 0)) * mult
+        if pieces <= 0 or base.startswith(_LID_PREFIX):
+            continue
+        if base.startswith(_SET_PREFIX):
+            combos[base] = combos.get(base, 0) + pieces
+        else:
+            singles[base] = singles.get(base, 0) + pieces
+    return singles, combos
+
+
+def explode_to_singles(
+    rows: list[dict[str, Any]],
+    set_bom: dict[str, list[dict[str, Any]]],
+) -> dict[str, int]:
+    """SKU별 합산 행 → 낱개 코드별 수량.
+
+    - seller_sku 의 _N 접미사는 배수(같은 상품 N개)로 곱한다.
+    - 콤보(세트, set_bom 에 존재)는 구성 낱개로 분해해 (배수 × 구성수량) 더한다.
+    - MD-(뚜껑)은 재고 집계에서 제외한다.
+    반환: {낱개코드(대문자): 수량}.
+    """
+    singles: dict[str, int] = {}
+    for r in rows:
+        base, mult = split_sku(r.get("seller_sku", ""))
+        base = base.upper()
+        if not base:
+            continue
+        pieces = int(r.get("qty", 0)) * mult
+        if pieces <= 0 or base.startswith(_LID_PREFIX):
+            continue
+        comps = set_bom.get(base)
+        if comps:  # 콤보 → 낱개 분해
+            for c in comps:
+                cc = str(c.get("component_code", "")).strip().upper()
+                if not cc or cc.startswith(_LID_PREFIX):
+                    continue
+                singles[cc] = singles.get(cc, 0) + pieces * int(c.get("component_qty", 0) or 0)
+        else:
+            singles[base] = singles.get(base, 0) + pieces
+    return {k: v for k, v in singles.items() if v > 0}
+
+
+def build_stock_xlsx(
+    *,
+    rows: list[dict[str, Any]],
+    set_bom: dict[str, list[dict[str, Any]]],
+    sabangnet_map: dict[str, str],
+) -> bytes:
+    """사방넷 재고 업로드용 xlsx(낱개 분해). 4열: 상품코드[필수]/가용수량/불용수량/바코드.
+
+    A=사방넷코드, B=수량, C=0(불용), D=아이템코드(바코드). 코드 오름차순.
+    """
+    from openpyxl import Workbook  # noqa: WPS433
+    from openpyxl.styles import Alignment, Font, PatternFill
+
+    singles = explode_to_singles(rows, set_bom)
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "재고"
+    ws.append(list(_STOCK_HEADERS))
+    head_fill = PatternFill("solid", fgColor="C55A11")  # 사방넷 템플릿 주황
+    head_font = Font(bold=True, color="FFFFFF")
+    for cell in ws[1]:
+        cell.fill = head_fill
+        cell.font = head_font
+        cell.alignment = Alignment(horizontal="center", vertical="center")
+
+    for code in sorted(singles):
+        sabangnet = sabangnet_map.get(code, "")
+        ws.append([sabangnet, singles[code], 0, code])
+
+    widths = [22, 12, 12, 18]
+    from openpyxl.utils import get_column_letter
+    for i, w in enumerate(widths, start=1):
+        ws.column_dimensions[get_column_letter(i)].width = w
+
+    buf = io.BytesIO()
+    wb.save(buf)
+    return buf.getvalue()
+
+
+def stock_filename(dispatch_date: str) -> str:
+    """사방넷 출고 엑셀 파일명: 2026.06.22(Mon)_sabangnet_outbound.xlsx."""
+    d = _parse_date(dispatch_date)
+    stamp = d.strftime("%Y.%m.%d(%a)") if d else (dispatch_date or "outbound").strip()
+    return f"{stamp}_sabangnet_outbound.xlsx"
+
+
+def _cell(value: Any) -> Any:
+    """송장/전화번호 등이 숫자로 보이면 엑셀이 과학표기/반올림 하므로 문자열 보존."""
+    if isinstance(value, int):
+        return value
+    return "" if value is None else str(value)
+
+
+def _autosize(ws: Any, headers: list[str]) -> None:
+    """대략적인 컬럼 폭. 주소는 길어 상한을 둔다."""
+    from openpyxl.utils import get_column_letter
+
+    widths: list[int] = [len(h) for h in headers]
+    for row in ws.iter_rows(min_row=2, values_only=True):
+        for i, val in enumerate(row):
+            ln = len(str(val)) if val is not None else 0
+            if ln > widths[i]:
+                widths[i] = ln
+    for i, w in enumerate(widths, start=1):
+        ws.column_dimensions[get_column_letter(i)].width = min(max(w + 2, 8), 50)
+
+
+def _parse_date(value: str) -> date | None:
+    s = (value or "").strip()
+    if not s:
+        return None
+    for fmt in ("%Y-%m-%d", "%Y.%m.%d", "%Y/%m/%d"):
+        try:
+            return datetime.strptime(s, fmt).date()
+        except ValueError:
+            continue
+    return None

app/modules/dispatch/parser.py

@@ -0,0 +1,264 @@
+"""출고 XLSX 파서 (openpyxl) — TikTok / Shopee 공용.
+
+pandas 대신 레포에 이미 있는 openpyxl 로 읽어 의존성을 가볍게 유지한다
+(동작: 헤더 정규화 → 표준키 매핑 → 박스 묶기).
+
+- TikTok: 03_TikTok_Order_Export.xlsx, Shopee: Packing List.Doorstep Delivery.xlsx.
+  두 포맷 모두 같은 표준키로 매핑된다(store.COLUMN_ALIASES). 헤더가 첫 행이 아닐
+  수 있어(Shopee 는 제목 행이 위에 붙는 경우가 있다) 상단 몇 행을 훑어 필수 컬럼이
+  잡히는 첫 행을 헤더로 본다.
+- 받는 사람(이름/전화/주소) 컬럼은 매핑되면 보존한다(작업 카드 표시 + 출고 엑셀).
+- Tracking ID 는 숫자로 읽혀도 문자열로 보존(store.clean_text).
+- Quantity 가 비면 1, NaN/None 은 빈 문자열로 처리.
+- 필수 컬럼이 없으면 어떤 컬럼이 없는지 ParseError 로 알린다.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import store
+
+
+class ParseError(Exception):
+    """엑셀 파싱 실패. message 는 사용자에게 그대로 보여줄 한국어 메시지."""
+
+
+# 헤더가 첫 행이 아닐 수 있어 상단에서 헤더 행을 찾을 때 훑는 최대 행 수.
+_HEADER_SCAN_ROWS = 15
+
+# Shopee SPX 송장번호 접두사 → 배송사. xlsx 에 배송사 컬럼이 없어 송장으로 추론.
+_SHOPEE_DEFAULT_PROVIDER = "SPX"
+
+
+def parse_export(path: str, platform: str = "") -> dict[str, Any]:
+    """출고 XLSX 경로 → {"parcels": [...], "row_count": int}.
+
+    parcels 는 store.group_parcels 결과(1박스=1항목). 실패 시 ParseError.
+    - Shopee: SKU/수량이 product_info 한 셀에 묶여 있어 별도 경로.
+    - Manual: 받는 사람/상품/수량이 첫 시트 한 행에 있는 수동 오더(1행=1박스).
+    """
+    p = (platform or "").strip()
+    if p == store.PLATFORM_SHOPEE:
+        return _parse_shopee(path)
+    if p == store.PLATFORM_MANUAL:
+        return _parse_manual(path)
+    return _parse_generic(path)
+
+
+# 메뉴얼 오더 엑셀 컬럼 별칭(헤더 정규화 후 비교). 받는 사람 정보가 엑셀에 직접 있다.
+_MANUAL_ALIASES: dict[str, tuple[str, ...]] = {
+    "recipient_name":    ("receiver name", "recipient name", "recipient", "받는 사람", "받는사람", "수취인", "이름", "name"),
+    "recipient_phone":   ("phone", "phone number", "phone #", "contact", "전화", "전화번호", "연락처"),
+    "recipient_address": ("address", "delivery address", "주소", "배송지", "배송주소"),
+    "product_name":      ("product name", "item name", "product", "상품명", "상품이름"),
+    "seller_sku":        ("item code", "seller sku", "sku", "아이템코드", "아이템 코드", "상품코드", "코드"),
+    "quantity":          ("quantity", "qty", "수량", "주문수량"),
+}
+
+
+def _parse_manual(path: str) -> dict[str, Any]:
+    """메뉴얼 오더 엑셀(첫 시트). 1행 = 1박스.
+
+    컬럼: Receiver Name / Phone / Address / Product Name / Item Code / Quantity.
+    받는 사람 정보가 엑셀에 직접 있어 PDF 없이 카드/엑셀에 표시된다. 묶음키
+    (Order/Tracking/Package)가 없으므로 행마다 별도 박스(seq)로 만든다.
+    """
+    all_rows = _load_rows(path)
+
+    header_idx = None
+    mapping: dict[str, int] = {}
+    for idx, raw in enumerate(all_rows[:_HEADER_SCAN_ROWS]):
+        if raw is None:
+            continue
+        m = {
+            key: store.find_column(raw, aliases)
+            for key, aliases in _MANUAL_ALIASES.items()
+        }
+        # 최소: 아이템코드 컬럼이 잡혀야 한다.
+        if m.get("seller_sku") is not None:
+            header_idx = idx
+            mapping = {k: v for k, v in m.items() if v is not None}
+            break
+
+    if header_idx is None:
+        raise ParseError(
+            "메뉴얼 오더 엑셀에서 컬럼을 찾지 못했습니다. "
+            "필요 컬럼: Item Code(필수), Receiver Name, Phone, Address, Product Name, Quantity"
+        )
+
+    def cell(raw: Any, key: str) -> str:
+        idx = mapping.get(key)
+        if idx is None or idx >= len(raw):
+            return ""
+        return store.clean_text(raw[idx])
+
+    parcels: list[dict[str, Any]] = []
+    seq = 0
+    for raw in all_rows[header_idx + 1:]:
+        if raw is None:
+            continue
+        sku = cell(raw, "seller_sku")
+        name = cell(raw, "recipient_name")
+        if not sku and not name:
+            continue  # 빈 행
+        if not sku:
+            continue  # 아이템코드 없으면 출고 대상 아님
+        seq += 1
+        parcels.append(
+            {
+                "seq": seq,
+                "order_id": "",
+                "package_id": "",
+                "tracking_id": "",
+                "shipping_provider": "",
+                "recipient_name": name,
+                "recipient_phone": cell(raw, "recipient_phone"),
+                "recipient_address": cell(raw, "recipient_address"),
+                "items": [
+                    {
+                        "seller_sku": sku,
+                        "product_name": cell(raw, "product_name"),
+                        "quantity": store.normalize_quantity(cell(raw, "quantity")),
+                    }
+                ],
+            }
+        )
+
+    return {"parcels": parcels, "row_count": len(parcels)}
+
+
+def _load_rows(path: str) -> list:
+    """첫 시트 전체 행(values_only). 열기/빈 파일 예외는 ParseError 로."""
+    try:
+        from openpyxl import load_workbook  # noqa: WPS433 — 지연 import
+    except ImportError as exc:  # pragma: no cover
+        raise ParseError("openpyxl 이 설치되어 있지 않습니다.") from exc
+
+    # read_only=True 는 쓰지 않는다: TikTok export 는 워크시트 <dimension> 메타가
+    # 부실해 read_only 모드가 A열만 읽고 끊기는 openpyxl 버그가 있다(실제 54열인데
+    # 1열만 반환). 일일 출고량(수백~수천 행)이라 일반 모드로 충분하다.
+    try:
+        wb = load_workbook(path, data_only=True)
+    except Exception as exc:  # noqa: BLE001
+        raise ParseError(f"엑셀 파일을 열 수 없습니다: {type(exc).__name__}") from exc
+    try:
+        rows = list(wb.worksheets[0].iter_rows(values_only=True))
+    finally:
+        wb.close()
+    if not rows:
+        raise ParseError("엑셀에 데이터가 없습니다(빈 파일).")
+    return rows
+
+
+def _parse_generic(path: str) -> dict[str, Any]:
+    """TikTok 등 표준 컬럼형 엑셀: 헤더 행 자동탐지 → 표준키 매핑 → 박스 묶기."""
+    all_rows = _load_rows(path)
+    header_idx, mapping = _find_header(all_rows)
+    if header_idx is None:
+        missing = store.missing_required({})
+        raise ParseError("엑셀에서 필요한 컬럼을 찾지 못했습니다: " + ", ".join(missing))
+
+    norm_rows: list[dict[str, str]] = []
+    for raw in all_rows[header_idx + 1:]:
+        if raw is None:
+            continue
+        # 표준키만 추출(매핑 안 된 열은 버린다).
+        record = {
+            key: store.clean_text(raw[idx]) if idx < len(raw) else ""
+            for key, idx in mapping.items()
+        }
+        # 완전 빈 행 스킵
+        if not any(record.get(k) for k in ("order_id", "package_id", "tracking_id", "seller_sku")):
+            continue
+        # 헤더 바로 아래 '컬럼 설명' 행 스킵(TikTok export 2번째 행).
+        #   주문/송장/패키지 ID 는 공백을 포함하지 않는다. 설명 문장은 공백을
+        #   포함하므로, 채워진 ID 값에 공백이 있으면 데이터가 아니라 설명 행이다.
+        if _is_description_row(record):
+            continue
+        norm_rows.append(record)
+
+    parcels = store.group_parcels(norm_rows)
+    return {"parcels": parcels, "row_count": len(norm_rows)}
+
+
+def _parse_shopee(path: str) -> dict[str, Any]:
+    """Shopee Packing List.Doorstep Delivery.xlsx 파싱.
+
+    컬럼: order_sn, tracking_number, product_info(상품 N개가 한 셀에 묶임).
+    1행 = 1주문 = 1박스. product_info 를 펼쳐 상품별 행을 만든 뒤 박스로 묶는다.
+    이름/주소/전화는 xlsx 에 없으므로 라벨 PDF 단계에서 채운다(여기선 빈 값).
+    """
+    all_rows = _load_rows(path)
+
+    header_idx = order_idx = track_idx = pinfo_idx = None
+    for idx, raw in enumerate(all_rows[:_HEADER_SCAN_ROWS]):
+        if raw is None:
+            continue
+        oi = store.find_column(raw, store.COLUMN_ALIASES["order_id"])
+        ti = store.find_column(raw, store.COLUMN_ALIASES["tracking_id"])
+        pi = store.find_column(raw, store.PRODUCT_INFO_ALIASES)
+        if pi is not None and (oi is not None or ti is not None):
+            header_idx, order_idx, track_idx, pinfo_idx = idx, oi, ti, pi
+            break
+
+    if header_idx is None:
+        raise ParseError(
+            "Shopee 엑셀에서 필요한 컬럼을 찾지 못했습니다: "
+            "product_info + (order_sn 또는 tracking_number)"
+        )
+
+    norm_rows: list[dict[str, str]] = []
+    for raw in all_rows[header_idx + 1:]:
+        if raw is None:
+            continue
+        order = store.clean_text(raw[order_idx]) if order_idx is not None and order_idx < len(raw) else ""
+        tracking = store.clean_text(raw[track_idx]) if track_idx is not None and track_idx < len(raw) else ""
+        blob = raw[pinfo_idx] if pinfo_idx < len(raw) else ""
+        if not (order or tracking):
+            continue
+        for it in store.parse_shopee_product_info(blob):
+            norm_rows.append(
+                {
+                    "order_id": order,
+                    "tracking_id": tracking,
+                    "shipping_provider": _SHOPEE_DEFAULT_PROVIDER,
+                    "seller_sku": it["seller_sku"],
+                    "product_name": it["product_name"],
+                    "quantity": it["quantity"],
+                }
+            )
+
+    parcels = store.group_parcels(norm_rows)
+    return {"parcels": parcels, "row_count": len(norm_rows)}
+
+
+# 하위 호환 별칭(기존 호출부/테스트가 쓰던 이름).
+parse_order_export = parse_export
+
+
+def _find_header(rows: list) -> tuple[int | None, dict[str, int]]:
+    """상단 행들을 훑어 필수 컬럼이 잡히는 첫 행을 헤더로 본다.
+
+    반환: (헤더 행 인덱스, {표준키: 열 인덱스}). 못 찾으면 (None, {}).
+    """
+    for idx, raw in enumerate(rows[:_HEADER_SCAN_ROWS]):
+        if raw is None:
+            continue
+        mapping = store.resolve_columns(raw)
+        if not store.missing_required(mapping):
+            return idx, mapping
+    return None, {}
+
+
+def _is_description_row(record: dict[str, str]) -> bool:
+    """헤더 아래 '컬럼 설명' 행 판별.
+
+    Order/Tracking/Package ID 는 공백 없는 식별자다. 채워진 ID 값 중 하나라도
+    공백을 포함하면(예: 'Platform unique order ID.') 데이터가 아닌 설명 행이다.
+    """
+    for key in ("order_id", "tracking_id", "package_id"):
+        val = (record.get(key) or "").strip()
+        if val and any(ch.isspace() for ch in val):
+            return True
+    return False

app/modules/dispatch/pdf_parser.py

@@ -0,0 +1,209 @@
+"""라벨 PDF → 주문별 받는 사람(이름/전화/주소) 추출 (pdfplumber).
+
+xlsx 는 박스/SKU/수량/주문/송장을 담당하고, 받는 사람 개인정보는 가려져 있거나
+컬럼이 없어 라벨 PDF 에서 가져온다. 추출 결과는 Order ID 로 박스와 조인한다.
+
+- Shopee(SPX 라벨): 1주문 = 라벨 1p + 패킹리스트 1p. 라벨 페이지에
+  'Recipient Details (Penerima)' 블록이 있다. 2단 레이아웃이라 왼쪽 열만 본다.
+  전화는 표시되지 않는다(빈 값).
+- TikTok: 1주문 = 1p. 'To <이름> (+60)<전화>' 줄 + 그 아래 주소. 전화는 일부
+  마스킹될 수 있다(보이는 그대로 보존).
+
+좌표 의존 파서라 라벨 양식이 바뀌면 조정이 필요하다(상단 상수만 손보면 됨).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+logger = logging.getLogger("dispatch.pdf")
+
+# Shopee 라벨 2단 중 왼쪽 열 경계(x0 < 값). 오른쪽 열의 바코드/코드(SPXMY…,
+# Seller Details, KV6-…)를 배제한다.
+_SHOPEE_LEFT_MAX = 185
+# 같은 줄로 묶을 top 좌표 허용 오차(px).
+_LINE_TOL = 3
+# 전화번호 토큰: (+60)193819581 / (+60)11******36 등.
+_PHONE_RE = re.compile(r"\(\+?\d[\d()*\- ]*")
+
+
+class PdfParseError(Exception):
+    """PDF 파싱 실패. message 는 사용자에게 보여줄 한국어 메시지."""
+
+
+def extract_recipients(path: str, platform: str) -> dict[str, dict[str, str]]:
+    """라벨 PDF → {order_id: {recipient_name, recipient_phone, recipient_address}}.
+
+    실패해도 빈 dict 를 반환할 수 있다(호출부는 PII 없이 진행). 열기 자체 실패는
+    PdfParseError.
+    """
+    try:
+        import pdfplumber  # noqa: WPS433 — 지연 import
+    except ImportError as exc:  # pragma: no cover
+        raise PdfParseError("pdfplumber 가 설치되어 있지 않습니다.") from exc
+
+    try:
+        pdf = pdfplumber.open(path)
+    except Exception as exc:  # noqa: BLE001
+        raise PdfParseError(f"PDF 를 열 수 없습니다: {type(exc).__name__}") from exc
+
+    out: dict[str, dict[str, str]] = {}
+    try:
+        for page in pdf.pages:
+            try:
+                words = page.extract_words()
+            except Exception:  # noqa: BLE001
+                continue
+            if not words:
+                continue
+            if platform == "Shopee":
+                rec = _shopee_page(words)
+            else:
+                rec = _tiktok_page(words)
+            if rec and rec.get("order_id"):
+                oid = rec.pop("order_id")
+                # 이미 있으면 빈 값만 보강(중복 페이지 방어).
+                cur = out.setdefault(oid, {"recipient_name": "", "recipient_phone": "", "recipient_address": ""})
+                for k, v in rec.items():
+                    if v and not cur.get(k):
+                        cur[k] = v
+    finally:
+        pdf.close()
+    return out
+
+
+# ────────────────────────────────────────────────────────────
+# 줄 단위 헬퍼
+# ────────────────────────────────────────────────────────────
+def _lines(words: list[dict[str, Any]], *, x_max: float | None = None) -> list[tuple[float, list[dict[str, Any]]]]:
+    """단어들을 top 좌표로 묶어 줄 리스트로. 각 줄: (top, [word,...]) x0 오름차순."""
+    ws = [w for w in words if x_max is None or w["x0"] < x_max]
+    ws.sort(key=lambda w: (round(w["top"]), w["x0"]))
+    lines: list[tuple[float, list[dict[str, Any]]]] = []
+    for w in ws:
+        if lines and abs(w["top"] - lines[-1][0]) <= _LINE_TOL:
+            lines[-1][1].append(w)
+        else:
+            lines.append((w["top"], [w]))
+    return lines
+
+
+def _text(line_words: list[dict[str, Any]]) -> str:
+    return " ".join(w["text"] for w in sorted(line_words, key=lambda w: w["x0"])).strip()
+
+
+# ────────────────────────────────────────────────────────────
+# Shopee 라벨 페이지
+# ────────────────────────────────────────────────────────────
+def _shopee_page(words: list[dict[str, Any]]) -> dict[str, str] | None:
+    lines = _lines(words, x_max=_SHOPEE_LEFT_MAX)
+    texts = [_text(lw) for _, lw in lines]
+    joined = " ".join(texts)
+    if "Recipient Details" not in joined and "Penerima" not in joined:
+        return None  # 라벨 페이지 아님(패킹리스트 등)
+
+    order_id = ""
+    rec_idx = None
+    for i, t in enumerate(texts):
+        if not order_id:
+            m = re.search(r"Order\s*ID\s*:\s*([A-Za-z0-9]+)", t)
+            if m:
+                order_id = m.group(1)
+        if rec_idx is None and ("Recipient Details" in t or "Penerima" in t):
+            rec_idx = i
+
+    if rec_idx is None:
+        return None
+
+    name = ""
+    addr_parts: list[str] = []
+    postcode = ""
+    collecting = False
+    for t in texts[rec_idx + 1:]:
+        if t.startswith("Name:"):
+            name = t[len("Name:"):].strip()
+            continue
+        if t.startswith("Address:"):
+            collecting = True
+            addr_parts.append(t[len("Address:"):].strip())
+            continue
+        if t.startswith("Postcode:"):
+            postcode = t[len("Postcode:"):].strip()
+            break  # 받는 사람 우편번호에서 주소 끝
+        if collecting:
+            # 프로모/푸터 시작 전까지 주소 줄로 본다.
+            if t.startswith(("Select", "Scan", "Seller Details")):
+                break
+            addr_parts.append(t)
+
+    address = ", ".join(p for p in addr_parts if p)
+    if postcode and postcode not in address:
+        address = f"{address}, {postcode}" if address else postcode
+    address = _tidy(address)
+    return {"order_id": order_id, "recipient_name": name, "recipient_phone": "", "recipient_address": address}
+
+
+# ────────────────────────────────────────────────────────────
+# TikTok 라벨 페이지
+# ────────────────────────────────────────────────────────────
+# 주소 수집을 멈추는 키워드(섹션 경계). TikTok 라벨은 배송사마다 양식이 달라
+# 넉넉히 둔다.
+_TIKTOK_STOP = ("CASHLESS", "CASH ON", "COD", "Order ID", "Shipping Date",
+                "Product Name", "Estimated", "In transit", "DROP-OFF", "PICK-UP",
+                "Self Collect", "Order Created", "Return for", "Scan me", "Sender")
+# 받는 사람 앵커: 'To <이름> (+60)…'(Ninja) 또는 'Receiver <이름>'(NDD 등).
+_TIKTOK_ANCHOR = re.compile(r"^(To|Receiver)\b\s*(.*)$")
+
+
+def _tiktok_page(words: list[dict[str, Any]]) -> dict[str, str] | None:
+    lines = _lines(words)
+    texts = [_text(lw) for _, lw in lines]
+
+    order_id = ""
+    for t in texts:
+        m = re.search(r"Order\s*ID\s*:\s*(\d+)", t)
+        if m:
+            order_id = m.group(1)
+            break
+    if not order_id:
+        return None
+
+    anchor_idx = None
+    for i, t in enumerate(texts):
+        m = _TIKTOK_ANCHOR.match(t)
+        if m and (m.group(1) == "Receiver" or _PHONE_RE.search(t)):
+            anchor_idx = i
+            break
+    if anchor_idx is None:
+        return {"order_id": order_id, "recipient_name": "", "recipient_phone": "", "recipient_address": ""}
+
+    rest = _TIKTOK_ANCHOR.match(texts[anchor_idx]).group(2).strip()
+    phone = ""
+    name = rest
+    pm = _PHONE_RE.search(rest)
+    if pm:  # 'To <이름> (+60)<전화>' 형식
+        phone = rest[pm.start():].strip()
+        name = rest[:pm.start()].strip()
+
+    addr_parts: list[str] = []
+    for t in texts[anchor_idx + 1:]:
+        if any(k in t for k in _TIKTOK_STOP):
+            break
+        if t.strip():
+            addr_parts.append(t.strip())
+
+    # 일부 배송사 라벨은 바코드/송장 숫자가 주소 영역에 섞인다. 10자리 이상
+    # 숫자열은 주소가 아니라 바코드이므로 제거(우편번호 5자리는 보존).
+    address = re.sub(r"\b\d{10,}\b", "", ", ".join(addr_parts))
+    address = _tidy(address)
+    return {"order_id": order_id, "recipient_name": name, "recipient_phone": phone, "recipient_address": address}
+
+
+def _tidy(s: str) -> str:
+    """중복 공백/콤마 정리."""
+    s = re.sub(r"\s+", " ", s)
+    s = re.sub(r"\s*,\s*", ", ", s)
+    s = re.sub(r"(,\s*){2,}", ", ", s)
+    return s.strip().strip(",").strip()

app/modules/dispatch/router.py

@@ -0,0 +1,773 @@
+"""말레이시아 TikTok 출고관리 모듈 라우터.
+
+- 경로: /dispatch
+- 권한: 로그인 + `dispatch` 모듈 권한 (관리자는 항상 통과). 서버 측 검사.
+- 데이터: DispatchStore (dispatch_db / PostgreSQL) 전용.
+  DISPATCH_DB_URL 미설정 시 store 가 None 이며, 각 페이지는 "설정 필요" 안내.
+- 업로드 원본은 DATA_DIR/dispatch/<날짜>/<배치slug>/ 에 저장, DB 엔 경로만 기록.
+
+초보 물류 직원용 화면. 작업 기준 키는 Order ID / Package ID / Tracking ID /
+Seller SKU / Quantity 이고, 받는 사람(이름/전화/주소)은 작업 카드 표시 + 취합
+출고 엑셀 생성을 위해 박스 단위로 보관한다(개인정보).
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import re
+import shutil
+import unicodedata
+import zipfile
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
+from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse, Response
+
+from app.timezone import now_kst, today_kst
+
+from . import export, store
+from .parser import ParseError, parse_export
+from .pdf_parser import PdfParseError, extract_recipients
+
+logger = logging.getLogger("dispatch.router")
+
+router = APIRouter(prefix="/dispatch", tags=["dispatch"])
+
+# 업로드 슬롯 (저장 파일명, 허용 확장자). 플랫폼마다 올리는 파일이 다르다.
+#   - 데이터 슬롯(필수): 자동 출고 리스트의 기준 엑셀.
+#   - 라벨 슬롯(선택): 실제 포장/라벨 원본 PDF(보관용).
+#   TikTok 의 01_Picking_List.pdf 는 쓰지 않으므로 업로드 받지 않는다.
+_DATA_SLOTS: dict[str, tuple[str, tuple[str, ...]]] = {
+    store.PLATFORM_TIKTOK: ("03_TikTok_Order_Export.xlsx", (".xlsx",)),
+    store.PLATFORM_SHOPEE: ("Packing_List.Doorstep_Delivery.xlsx", (".xlsx",)),
+    store.PLATFORM_MANUAL: ("Manual_Order.xlsx", (".xlsx",)),
+}
+# 라벨(PDF) 슬롯이 없는 플랫폼(Manual)은 받는 사람 정보가 데이터 엑셀에 직접 있다.
+_LABEL_SLOTS: dict[str, tuple[str, tuple[str, ...]]] = {
+    store.PLATFORM_TIKTOK: ("02_Shipping_Label_Packing_Slip.pdf", (".pdf",)),
+    store.PLATFORM_SHOPEE: ("Shopee_Seller_Centre.pdf", (".pdf",)),
+}
+
+
+# ────────────────────────────────────────────────────────────
+# 공용 헬퍼
+# ────────────────────────────────────────────────────────────
+def _store(request: Request) -> Any:
+    return getattr(request.app.state, "dispatch_store", None)
+
+
+def _data_dir(request: Request) -> Path:
+    return Path(getattr(request.app.state, "data_dir", Path("app/data")))
+
+
+def _itemcode_name_map(request: Request) -> dict[str, str]:
+    """itemcode_db {코드(대문자): 상품명}. 미설정/실패 시 빈 dict.
+
+    malaysia 모듈의 읽기 전용 리더(single_items + set_items)를 재사용한다.
+    """
+    reader = getattr(request.app.state, "malaysia_itemcode", None)
+    if reader is None or not getattr(reader, "enabled", False):
+        return {}
+    try:
+        return reader.name_map()
+    except Exception:  # noqa: BLE001 — 다운로드를 막지 않는다.
+        logger.exception("itemcode name_map 조회 실패")
+        return {}
+
+
+def _itemcode_bom_and_sabangnet(request: Request) -> tuple[dict[str, Any], dict[str, str]]:
+    """(세트 BOM map, item_code→사방넷코드 map). 미설정/실패 시 빈 dict."""
+    reader = getattr(request.app.state, "malaysia_itemcode", None)
+    if reader is None or not getattr(reader, "enabled", False):
+        return {}, {}
+    bom: dict[str, Any] = {}
+    sab: dict[str, str] = {}
+    try:
+        bom = reader.set_bom_map()
+    except Exception:  # noqa: BLE001
+        logger.exception("itemcode set_bom_map 조회 실패")
+    try:
+        sab = reader.sabangnet_code_map()
+    except Exception:  # noqa: BLE001
+        logger.exception("itemcode sabangnet_code_map 조회 실패")
+    return bom, sab
+
+
+def _require_user(request: Request) -> dict[str, Any]:
+    from app.main import get_current_user_record  # noqa: WPS433
+    from app.store import has_module  # noqa: WPS433
+
+    user = get_current_user_record(request)
+    if user is None:
+        raise HTTPException(status_code=401, detail="로그인이 필요합니다.")
+    if not has_module(user, "dispatch"):
+        raise HTTPException(status_code=403, detail="말레이시아 배송 모듈 권한이 없습니다.")
+    return user
+
+
+def _render_config_needed(request: Request, user: dict[str, Any]) -> HTMLResponse:
+    from app.main import build_erp_nav, render_template  # noqa: WPS433
+    from app.store import is_admin  # noqa: WPS433
+
+    return render_template(
+        request,
+        "denied.html",
+        {
+            "reason": "말레이시아 배송 모듈이 아직 설정되지 않았습니다. "
+            "DISPATCH_DB_URL 환경변수를 설정하고 "
+            "scripts/sql/dispatch_db_init.sql 로 dispatch_db 를 초기화한 뒤 "
+            "컨테이너를 재기동하세요.",
+            "user": user,
+            "is_admin": is_admin(user),
+            "nav_items": build_erp_nav(user, active="dispatch"),
+        },
+        status_code=503,
+    )
+
+
+def _guard(request: Request):
+    """로그인+권한+store 점검. 페이지 핸들러 진입부에서 사용."""
+    from app.main import get_current_user_record, render_template  # noqa: WPS433
+    from app.store import has_module, is_admin  # noqa: WPS433
+
+    user = get_current_user_record(request)
+    if user is None:
+        return RedirectResponse(url="/login", status_code=303)
+    if not has_module(user, "dispatch"):
+        return render_template(
+            request,
+            "denied.html",
+            {"reason": "말레이시아 배송 모듈 접근 권한이 없습니다.", "is_admin": is_admin(user)},
+            status_code=403,
+        )
+    st = _store(request)
+    if st is None:
+        return _render_config_needed(request, user)
+    return st, user
+
+
+def _base_ctx(request: Request, user: dict[str, Any]) -> dict[str, Any]:
+    from app.main import build_erp_nav  # noqa: WPS433
+    from app.store import is_admin  # noqa: WPS433
+
+    return {
+        "user": user,
+        "is_admin": is_admin(user),
+        "is_super": bool(user.get("is_super_admin")),
+        "nav_items": build_erp_nav(user, active="dispatch"),
+        "status_fields": store.STATUS_FIELDS,
+        "status_labels": store.STATUS_LABELS,
+    }
+
+
+def _slugify(value: str) -> str:
+    """배치명 → 폴더/파일 안전한 슬러그. 비면 'batch'."""
+    text = unicodedata.normalize("NFKC", value or "").strip()
+    text = re.sub(r"[^\w\-.가-힣]+", "_", text, flags=re.UNICODE)
+    text = text.strip("._")
+    return text or "batch"
+
+
+def _save_upload(upload: UploadFile | None, *, dest_dir: Path, slot: tuple) -> str:
+    """업로드 파일 1개 저장. 반환: 저장 경로(없으면 ""). 확장자 검증."""
+    filename, allowed_ext = slot
+    if upload is None or not (upload.filename or "").strip():
+        return ""
+    ext = Path(upload.filename).suffix.lower()
+    if ext not in allowed_ext:
+        raise HTTPException(
+            status_code=400,
+            detail=f"{filename} 는 {', '.join(allowed_ext)} 형식이어야 합니다. (업로드: {upload.filename})",
+        )
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / filename
+    with dest.open("wb") as f:
+        shutil.copyfileobj(upload.file, f)
+    return str(dest)
+
+
+# ════════════════════════════════════════════════════════════
+# 배치 목록 (메인)
+# ════════════════════════════════════════════════════════════
+@router.get("/", response_class=HTMLResponse)
+async def batches_index(request: Request) -> HTMLResponse:
+    from app.main import render_template  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard
+    st, user = guard
+    batches = st.list_batches()
+    ctx = _base_ctx(request, user)
+    ctx.update(
+        {
+            "page_title": "말레이시아 배송 — 출고 배치",
+            "page_subtitle": "TikTok 일일 출고 배치 목록",
+            "batches": batches,
+            "batch_dates": sorted({b["dispatch_date"] for b in batches if b.get("dispatch_date")}),
+            "deducted_dates": st.list_deducted_dates(),
+            "active_tab": "batches",
+        }
+    )
+    return render_template(request, "dispatch/batches.html", ctx)
+
+
+@router.get("/batches/new", response_class=HTMLResponse)
+async def batch_new(request: Request) -> HTMLResponse:
+    from app.main import render_template  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard
+    _st, user = guard
+    ctx = _base_ctx(request, user)
+    ctx.update(
+        {
+            "page_title": "말레이시아 배송 — 업로드",
+            "page_subtitle": "플랫폼 파일 업로드 → 출고 배치 자동 생성",
+            "today": today_kst().isoformat(),
+            "platforms": store.PLATFORMS,
+            "active_tab": "new",
+        }
+    )
+    return render_template(request, "dispatch/new.html", ctx)
+
+
+@router.post("/batches")
+async def batch_create(
+    request: Request,
+    dispatch_date: str = Form(...),
+    platform: str = Form("TikTok"),
+    batch_name: str = Form(""),
+    label_pdf: UploadFile | None = File(None),
+    data_xlsx: UploadFile | None = File(None),
+    user: dict[str, Any] = Depends(_require_user),
+) -> RedirectResponse:
+    """파일 업로드 + 배치 생성 + 엑셀 파싱 + 박스 저장.
+
+    플랫폼별 슬롯:
+      - TikTok: 데이터=03_TikTok_Order_Export.xlsx(필수), 라벨=Shipping Label PDF(선택)
+      - Shopee: 데이터=Packing List.Doorstep Delivery.xlsx(필수), 라벨=Shopee Seller Centre.pdf(선택)
+    같은 날짜/플랫폼이라도 새 배치로 생성한다(덮어쓰지 않음).
+    """
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="dispatch_db 미설정")
+
+    platform = (platform or store.PLATFORM_TIKTOK).strip()
+    if platform not in _DATA_SLOTS:
+        raise HTTPException(status_code=400, detail=f"지원하지 않는 플랫폼입니다: {platform}")
+    data_slot = _DATA_SLOTS[platform]
+    label_slot = _LABEL_SLOTS.get(platform)  # Manual 은 라벨 없음(None)
+
+    if data_xlsx is None or not (data_xlsx.filename or "").strip():
+        raise HTTPException(
+            status_code=400,
+            detail=f"{data_slot[0]} 는 필수입니다(자동 출고 리스트 기준 데이터).",
+        )
+
+    # 저장 폴더: DATA_DIR/dispatch/<날짜>/<배치slug>_<HHMMSS>/
+    name = (batch_name or "").strip() or f"{platform} 출고"
+    stamp = now_kst().strftime("%H%M%S")
+    dest_dir = _data_dir(request) / "dispatch" / dispatch_date.strip() / f"{_slugify(name)}_{stamp}"
+
+    label_path = _save_upload(label_pdf, dest_dir=dest_dir, slot=label_slot) if label_slot else ""
+    order_path = _save_upload(data_xlsx, dest_dir=dest_dir, slot=data_slot)
+
+    # 엑셀 파싱 — 실패 시 사용자에게 한국어 메시지 그대로 보여준다.
+    try:
+        parsed = parse_export(order_path, platform=platform)
+    except ParseError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+    parcels = parsed["parcels"]
+    if not parcels:
+        raise HTTPException(
+            status_code=400,
+            detail="엑셀에서 출고할 박스를 찾지 못했습니다. 컬럼/데이터를 확인하세요.",
+        )
+
+    # 라벨 PDF 가 있으면 받는 사람(이름/전화/주소)을 추출해 Order ID 로 박스에 채운다.
+    # 이름/주소는 xlsx 에 없거나 가려져 있어 PDF 가 출처. PDF 없거나 실패 시 빈 값.
+    if label_path:
+        try:
+            recipients = extract_recipients(label_path, platform)
+        except PdfParseError as exc:
+            logger.warning("라벨 PDF 파싱 실패 — PII 없이 진행: %s", exc)
+            recipients = {}
+        # PDF 가 받는 사람 정보의 정본(authoritative). xlsx 의 가려진 이름/주소는
+        # 신뢰하지 않으므로 PDF 값이 있으면 덮어쓴다.
+        for p in parcels:
+            rec = recipients.get((p.get("order_id") or "").strip())
+            if not rec:
+                continue
+            for field in ("recipient_name", "recipient_phone", "recipient_address"):
+                if rec.get(field):
+                    p[field] = rec[field]
+
+    batch = st.create_batch(
+        platform=platform,
+        dispatch_date=dispatch_date,
+        batch_name=name,
+        picking_pdf_path="",
+        label_pdf_path=label_path,
+        order_export_path=order_path,
+    )
+    st.add_parcels(batch_id=batch["id"], parcels=parcels)
+    return RedirectResponse(url=f"/dispatch/batches/{batch['id']}", status_code=303)
+
+
+@router.post("/batches/{batch_id:int}/delete")
+async def batch_delete(
+    request: Request, batch_id: int, user: dict[str, Any] = Depends(_require_user)
+) -> RedirectResponse:
+    """배치 삭제 — 슈퍼 관리자 전용(박스/상품/로그 CASCADE)."""
+    if not bool(user.get("is_super_admin")):
+        raise HTTPException(status_code=403, detail="배치 삭제는 슈퍼 관리자만 가능합니다.")
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="dispatch_db 미설정")
+    try:
+        st.delete_batch(batch_id=batch_id)
+    except KeyError:
+        raise HTTPException(status_code=404, detail="배치를 찾을 수 없습니다.")
+    return RedirectResponse(url="/dispatch/", status_code=303)
+
+
+@router.get("/batches/{batch_id:int}/download")
+async def batch_download(
+    request: Request, batch_id: int, user: dict[str, Any] = Depends(_require_user)
+) -> Response:
+    """배치 다운로드: 업로드 원본(라벨 PDF + 데이터 엑셀) + 취합 출고 엑셀을 zip 으로 묶음."""
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="dispatch_db 미설정")
+    batch = st.get_batch(batch_id=batch_id)
+    if batch is None:
+        raise HTTPException(status_code=404, detail="배치를 찾을 수 없습니다.")
+
+    # 저장된 경로 중 실제로 존재하는 파일만 묶는다. 같은 파일명 충돌 시 번호 부여.
+    paths = [
+        batch.get("picking_pdf_path"),
+        batch.get("label_pdf_path"),
+        batch.get("order_export_path"),
+    ]
+    buf = io.BytesIO()
+    used: set[str] = set()
+    count = 0
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        for raw in paths:
+            p = Path(raw) if raw else None
+            if not p or not p.is_file():
+                continue
+            arcname = p.name
+            n = 1
+            while arcname in used:
+                arcname = f"{p.stem}_{n}{p.suffix}"
+                n += 1
+            used.add(arcname)
+            zf.write(p, arcname=arcname)
+            count += 1
+
+        # 취합 출고 엑셀(발송날짜/고객/주소/상품/택배 등)을 생성해 함께 넣는다.
+        #   상품이름은 아이템코드로 itemcode_db 에서 조회해 채운다.
+        parcels = st.list_parcels(batch_id=batch_id)
+        name_map = _itemcode_name_map(request)
+        xlsx_name = export.export_filename(
+            dispatch_date=batch.get("dispatch_date", ""),
+            platform=batch.get("platform", ""),
+        )
+        try:
+            xlsx_bytes = export.build_workbook_bytes(
+                batch=batch, parcels=parcels, name_map=name_map
+            )
+            zf.writestr(xlsx_name, xlsx_bytes)
+            count += 1
+        except Exception:  # noqa: BLE001 — 엑셀 생성 실패해도 원본 다운로드는 살린다.
+            logger.exception("출고 엑셀 생성 실패 batch_id=%s", batch_id)
+
+    if count == 0:
+        raise HTTPException(status_code=404, detail="다운로드할 파일이 없습니다.")
+
+    slug = _slugify(batch.get("batch_name") or "dispatch")
+    fname = f"{batch.get('dispatch_date', '')}_{slug}.zip".lstrip("_")
+    headers = {
+        "Content-Disposition": (
+            f"attachment; filename=\"dispatch_{batch_id}.zip\"; "
+            f"filename*=UTF-8''{quote(fname)}"
+        )
+    }
+    return Response(
+        content=buf.getvalue(), media_type="application/zip", headers=headers
+    )
+
+
+@router.get("/stock-export")
+async def stock_export(
+    request: Request, date: str, user: dict[str, Any] = Depends(_require_user)
+) -> Response:
+    """선택한 날짜의 전 배치 출고 수량을 낱개로 분해해 사방넷 재고 업로드 xlsx 다운로드.
+
+    콤보(세트)는 BOM 으로 낱개 분해, _N 배수 반영, MD-(뚜껑) 제외.
+    A=사방넷코드 / B=수량 / C=불용수량(0) / D=아이템코드.
+    """
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="dispatch_db 미설정")
+    d = (date or "").strip()
+    if not d:
+        raise HTTPException(status_code=400, detail="날짜가 필요합니다.")
+
+    rows = st.stock_aggregate_for_date(dispatch_date=d)
+    if not rows:
+        raise HTTPException(status_code=404, detail="해당 날짜의 출고 데이터가 없습니다.")
+
+    set_bom, sabangnet_map = _itemcode_bom_and_sabangnet(request)
+
+    # 세트(MY-)인데 BOM 을 못 찾으면 낱개 분해가 안 된 채 파일이 만들어진다.
+    # 조용히 잘못된 파일을 주지 말고, 어떤 세트가 분해 안 되는지 명확히 알린다.
+    missing_sets = sorted({
+        b for b in (
+            export.split_sku(r.get("seller_sku", ""))[0].strip().upper() for r in rows
+        )
+        if b.startswith(export._SET_PREFIX) and b not in set_bom
+    })
+    if missing_sets:
+        reader = getattr(request.app.state, "malaysia_itemcode", None)
+        hint = getattr(reader, "last_error", "") or getattr(reader, "reason", "")
+        detail = (
+            "세트 BOM 을 찾지 못해 낱개로 분해할 수 없습니다: "
+            + ", ".join(missing_sets)
+            + ". itemcode_db 의 set_components 에 해당 세트 BOM 이 등록돼 있는지, "
+            "읽기 전용 역할(itemcode_ro)에 set_components SELECT 권한이 있는지 확인하세요."
+        )
+        if hint:
+            detail += f" (itemcode 리더 오류: {hint})"
+        raise HTTPException(status_code=422, detail=detail)
+
+    # 사방넷 코드 맵이 통째로 비어 있으면 A열(상품코드[필수])이 전부 공란이 된다.
+    # 보통 itemcode_ro 의 single_items/set_items SELECT 권한 누락이 원인.
+    reader = getattr(request.app.state, "malaysia_itemcode", None)
+    if getattr(reader, "enabled", False) and not sabangnet_map:
+        hint = getattr(reader, "last_error", "") or getattr(reader, "reason", "")
+        detail = (
+            "사방넷 코드 맵이 비어 있어 상품코드[필수] 열을 채울 수 없습니다. "
+            "itemcode_db 의 single_items/set_items 에 sabangnet_code 가 등록돼 있는지, "
+            "읽기 전용 역할(itemcode_ro)에 두 테이블 SELECT 권한이 있는지 확인하세요."
+        )
+        if hint:
+            detail += f" (itemcode 리더 오류: {hint})"
+        raise HTTPException(status_code=422, detail=detail)
+
+    xlsx_bytes = export.build_stock_xlsx(rows=rows, set_bom=set_bom, sabangnet_map=sabangnet_map)
+    fname = export.stock_filename(d)
+    headers = {
+        "Content-Disposition": (
+            f"attachment; filename=\"stock_{d}.xlsx\"; "
+            f"filename*=UTF-8''{quote(fname)}"
+        )
+    }
+    return Response(
+        content=xlsx_bytes,
+        media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        headers=headers,
+    )
+
+
+@router.post("/stock-deduct")
+async def stock_deduct(
+    request: Request,
+    date: str = Form(...),
+    user: dict[str, Any] = Depends(_require_user),
+) -> JSONResponse:
+    """선택 날짜의 출고를 말레이시아 재고관리에 OUT 으로 반영(1회성).
+
+    - 낱개(MT/MX/MZ)는 낱개 OUT, 콤보(MY-)는 세트 OUT(BOM 으로 낱개 분해).
+    - _N 배수 반영, MD-(뚜껑) 제외. movement_date = 해당 날짜.
+    - dispatch_stock_deductions 로 날짜당 1회만 — 재실행 시 재고 이중 차감 방지.
+    """
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="dispatch_db 미설정")
+    d = (date or "").strip()
+    if not d:
+        raise HTTPException(status_code=400, detail="날짜가 필요합니다.")
+
+    if st.deduction_exists(dispatch_date=d):
+        raise HTTPException(status_code=409, detail=f"{d} 는 이미 재고 차감되었습니다.")
+
+    ms = getattr(request.app.state, "malaysia_store", None)
+    if ms is None:
+        raise HTTPException(status_code=503, detail="말레이시아 재고관리(MALAYSIA_STOCK_DB_URL) 미설정")
+
+    # 낱개/콤보 분리(_N 배수, MD- 제외)
+    rows = st.stock_aggregate_for_date(dispatch_date=d)
+    singles, combos = export.split_singles_combos(rows)
+    if not singles and not combos:
+        raise HTTPException(status_code=404, detail="해당 날짜의 출고 데이터가 없습니다.")
+
+    # 창고 결정(첫 활성 창고)
+    warehouses = ms.list_warehouses()
+    if not warehouses:
+        raise HTTPException(status_code=400, detail="등록된 창고가 없습니다.")
+    wh = warehouses[0]["warehouse_code"]
+
+    # 콤보 BOM 사전검증(누락 시 아무 것도 쓰지 않고 중단)
+    bom_map, _sab = _itemcode_bom_and_sabangnet(request)
+    missing = [c for c in combos if c not in bom_map]
+    if missing:
+        # 'BOM 누락'을 원인별로 쪼개 정확히 알린다. 그동안 이 메시지가
+        # (a)미등록 (b)구성품없음 (c)권한/조회실패 를 한 덩어리로 가려서
+        # "고쳐도 또 난다"가 반복됐다.
+        reader = getattr(request.app.state, "malaysia_itemcode", None)
+        registered: set[str] = set()
+        if reader is not None and getattr(reader, "enabled", False):
+            try:
+                registered = reader.set_codes_present()
+            except Exception:  # noqa: BLE001
+                logger.exception("set_codes_present 조회 실패")
+        query_failed = bool(getattr(reader, "last_error", "")) if reader else False
+
+        if query_failed:
+            # set_components 조회 자체가 실패 — 보통 itemcode_ro 권한 문제.
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    "itemcode_db 의 세트구성(set_components) 조회에 실패해 콤보를 분해할 수 "
+                    "없습니다. 읽기 전용 역할(itemcode_ro)에 set_components SELECT 권한이 "
+                    f"있는지 확인하세요. (상세: {reader.last_error})"
+                ),
+            )
+
+        no_components = sorted(c for c in missing if c in registered)
+        not_registered = sorted(c for c in missing if c not in registered)
+        parts: list[str] = []
+        if not_registered:
+            parts.append(
+                "세트구성 미등록(itemcode_db.set_components 에 코드 자체가 없음): "
+                + ", ".join(not_registered)
+            )
+        if no_components:
+            parts.append(
+                "세트는 등록됐으나 유효한 낱개(MT-/MX-/MZ-) 구성품이 없습니다"
+                "(구성품 코드·수량 확인): " + ", ".join(no_components)
+            )
+        raise HTTPException(status_code=400, detail="콤보 BOM 문제 — " + " / ".join(parts))
+
+    # 마커 선점(레이스/재실행 차단). 충돌 시 이미 차감됨.
+    try:
+        st.record_deduction(
+            dispatch_date=d, warehouse_code=wh,
+            single_lines=len(singles), combo_lines=len(combos),
+            worker_name=user.get("email", ""),
+        )
+    except Exception:  # noqa: BLE001 — unique 위반 등 = 이미 차감
+        raise HTTPException(status_code=409, detail=f"{d} 는 이미 재고 차감되었습니다.")
+
+    # 실제 OUT 반영. 실패해도 마커는 남겨 재고 이중 차감을 막는다(원인은 로그).
+    memo = f"배송 출고 {d}"
+    try:
+        for code, qty in combos.items():
+            ms.create_set_out(
+                movement_date=d, warehouse_code=wh, set_code=code, set_qty=qty,
+                bom_map=bom_map, ref_type="dispatch", ref_no=d, memo=memo,
+                created_by=user.get("email", ""),
+            )
+        for code, qty in singles.items():
+            ms.create_movement(
+                movement_date=d, warehouse_code=wh, item_code=code,
+                movement_type="OUT", qty=qty, ref_type="dispatch", ref_no=d,
+                memo=memo, created_by=user.get("email", ""),
+            )
+    except Exception as exc:  # noqa: BLE001
+        logger.exception("재고 차감 중 오류 date=%s", d)
+        raise HTTPException(
+            status_code=500,
+            detail=f"일부 반영 중 오류가 발생했습니다(재차감 방지를 위해 차감완료로 표시됨). 재고관리 이동이력을 확인하세요: {type(exc).__name__}",
+        )
+
+    return JSONResponse({
+        "ok": True, "date": d, "warehouse": wh,
+        "singles": len(singles), "combos": len(combos),
+    })
+
+
+# ════════════════════════════════════════════════════════════
+# 출고 작업 리스트 (1박스 = 1카드)
+# ════════════════════════════════════════════════════════════
+@router.get("/batches/{batch_id:int}", response_class=HTMLResponse)
+async def batch_detail(request: Request, batch_id: int) -> HTMLResponse:
+    from app.main import render_template  # noqa: WPS433
+    from app.store import is_admin  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard
+    st, user = guard
+    batch = st.get_batch(batch_id=batch_id)
+    if batch is None:
+        return render_template(
+            request, "denied.html",
+            {"reason": "출고 배치를 찾을 수 없습니다.", "is_admin": is_admin(user)},
+            status_code=404,
+        )
+    parcels = st.list_parcels(batch_id=batch_id)
+    done_count = sum(1 for p in parcels if all(p[f] for f in store.STATUS_FIELDS))
+    ctx = _base_ctx(request, user)
+    ctx.update(
+        {
+            "page_title": f"출고 작업 — {batch['batch_name']}",
+            "page_subtitle": f"{batch['dispatch_date']} · {batch['platform']} · 박스 {len(parcels)}개",
+            "batch": batch,
+            "parcels": parcels,
+            "done_count": done_count,
+            "active_tab": "work",
+        }
+    )
+    return render_template(request, "dispatch/detail.html", ctx)
+
+
+@router.get("/batches/{batch_id:int}/picking", response_class=HTMLResponse)
+async def batch_picking(request: Request, batch_id: int) -> HTMLResponse:
+    from app.main import render_template  # noqa: WPS433
+    from app.store import is_admin  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard
+    st, user = guard
+    batch = st.get_batch(batch_id=batch_id)
+    if batch is None:
+        return render_template(
+            request, "denied.html",
+            {"reason": "출고 배치를 찾을 수 없습니다.", "is_admin": is_admin(user)},
+            status_code=404,
+        )
+    summary = st.sku_summary(batch_id=batch_id)
+    ctx = _base_ctx(request, user)
+    ctx.update(
+        {
+            "page_title": f"피킹 요약 — {batch['batch_name']}",
+            "page_subtitle": f"{batch['dispatch_date']} · SKU별 총 수량",
+            "batch": batch,
+            "summary": summary,
+            "total_qty": sum(r["total_qty"] for r in summary),
+            "active_tab": "picking",
+        }
+    )
+    return render_template(request, "dispatch/picking.html", ctx)
+
+
+@router.get("/batches/{batch_id:int}/handover", response_class=HTMLResponse)
+async def batch_handover(request: Request, batch_id: int) -> HTMLResponse:
+    from app.main import render_template  # noqa: WPS433
+    from app.store import is_admin  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard
+    st, user = guard
+    batch = st.get_batch(batch_id=batch_id)
+    if batch is None:
+        return render_template(
+            request, "denied.html",
+            {"reason": "출고 배치를 찾을 수 없습니다.", "is_admin": is_admin(user)},
+            status_code=404,
+        )
+    summary = st.handover_summary(batch_id=batch_id)
+    ctx = _base_ctx(request, user)
+    ctx.update(
+        {
+            "page_title": f"Kagayaku 전달 — {batch['batch_name']}",
+            "page_subtitle": f"{batch['dispatch_date']} · {batch['platform']}",
+            "batch": batch,
+            "handover": summary,
+            "active_tab": "handover",
+        }
+    )
+    return render_template(request, "dispatch/handover.html", ctx)
+
+
+# ════════════════════════════════════════════════════════════
+# 상태 토글 (AJAX) + JSON API
+# ════════════════════════════════════════════════════════════
+@router.post("/parcels/{parcel_id:int}/toggle")
+async def parcel_toggle(
+    request: Request,
+    parcel_id: int,
+    field: str = Form(...),
+    user: dict[str, Any] = Depends(_require_user),
+) -> JSONResponse:
+    """박스 작업 상태 1개 토글 → 즉시 DB 저장 + 로그. JSON 반환(버튼 색 갱신용)."""
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="dispatch_db 미설정")
+    try:
+        result = st.toggle_status(
+            parcel_id=parcel_id, field=field, worker_name=user.get("email", "")
+        )
+    except KeyError:
+        raise HTTPException(status_code=404, detail="박스를 찾을 수 없습니다.")
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return JSONResponse({"ok": True, **result})
+
+
+@router.post("/batches/{batch_id:int}/bulk")
+async def parcels_bulk(
+    request: Request,
+    batch_id: int,
+    field: str = Form(...),
+    value: str = Form("true"),
+    user: dict[str, Any] = Depends(_require_user),
+) -> JSONResponse:
+    """배치 내 모든 박스의 작업 상태 1개를 value(완료/해제)로 일괄 설정. JSON 반환."""
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="dispatch_db 미설정")
+    target = str(value).strip().lower() in ("true", "1", "on", "yes")
+    try:
+        count = st.bulk_set_status(
+            batch_id=batch_id, field=field, value=target, worker_name=user.get("email", "")
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return JSONResponse({"ok": True, "field": field, "value": target, "count": count})
+
+
+@router.get("/api/batches/{batch_id:int}/parcels")
+async def api_parcels(
+    request: Request, batch_id: int, _: dict[str, Any] = Depends(_require_user)
+) -> JSONResponse:
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="dispatch_db 미설정")
+    return JSONResponse({"parcels": st.list_parcels(batch_id=batch_id)})
+
+
+@router.get("/api/search")
+async def api_search(
+    request: Request, q: str = "", _: dict[str, Any] = Depends(_require_user)
+) -> JSONResponse:
+    """주문번호/패키지번호/송장번호(부분 일치)로 박스 검색 → 받는 사람/배치 반환."""
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="dispatch_db 미설정")
+    query = (q or "").strip()
+    if len(query) < 2:
+        return JSONResponse({"query": query, "results": []})
+    results = st.search_parcels(query=query)
+    # 송장 조회 딥링크는 배송사 맵(store)에서 만든다 — 프런트엔 맵이 없다.
+    for r in results:
+        r["tracking_url"] = store.courier_tracking_url(
+            r.get("tracking_id", ""), r.get("shipping_provider", "")
+        )
+    return JSONResponse({"query": query, "results": results})
+
+
+@router.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok", "module": "dispatch"}

app/modules/dispatch/store.py

@@ -0,0 +1,392 @@
+"""말레이시아 TikTok 출고관리 모듈 — 상수 및 순수 계산/검증 헬퍼.
+
+- 데이터 저장은 dispatch_db(PostgreSQL) 전용이다(`db.py`).
+- 엑셀 읽기는 `parser.py`(openpyxl)가 담당하고, 여기에는 DB/파일 의존이 없는
+  순수 함수(컬럼 정규화, 박스 묶기, SKU 합산)만 둔다(테스트 용이).
+
+핵심 업무 규칙:
+  - 03_TikTok_Order_Export.xlsx 가 자동 출고 리스트의 기준 데이터다.
+  - 엑셀 1줄 ≠ 1박스. 1박스 묶음 기준은 아래 우선순위로 정한다:
+        1순위 package_id → 2순위 tracking_id → 3순위 order_id
+  - 같은 박스 안 같은 SKU 는 수량을 합산한다.
+  - 고객 이름/주소/전화 등 개인정보는 절대 보관하지 않는다(허용 컬럼만 사용).
+"""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Iterable
+from urllib.parse import quote
+
+# ── 작업 상태 필드(토글 대상) ──
+#   순서 = 작업 진행 순서. label_ko/label_en 은 버튼 표기.
+#   상품은 미리 제작·박스 포장까지 끝난 상태로 들어오므로 product_ready/packed
+#   단계는 화면에서 쓰지 않는다(DB 컬럼은 보존 — 과거 데이터/확장 대비).
+#   실제 작업: 송장 라벨 부착 → Kagayaku 전달 → 택배 스캔 확인.
+STATUS_FIELDS: tuple[str, ...] = (
+    "label_attached",
+    "handed_to_kagayaku",
+)
+
+STATUS_LABELS: dict[str, dict[str, str]] = {
+    "product_ready":      {"ko": "상품준비",            "en": "Product Ready"},
+    "packed":             {"ko": "포장완료",            "en": "Packed"},
+    "label_attached":     {"ko": "라벨부착",            "en": "Label Attached"},
+    "handed_to_kagayaku": {"ko": "Kagayaku 전달",       "en": "Handed to Kagayaku"},
+    "courier_scanned":    {"ko": "택배스캔 확인",       "en": "Courier Scanned"},
+}
+
+# ── 플랫폼 ──
+#   주문처(엑셀 '주문처' 컬럼)이자 업로드 슬롯/파서 선택의 기준값.
+PLATFORM_TIKTOK = "TikTok"
+PLATFORM_SHOPEE = "Shopee"
+PLATFORM_MANUAL = "Manual"
+PLATFORMS: tuple[str, ...] = (PLATFORM_TIKTOK, PLATFORM_SHOPEE, PLATFORM_MANUAL)
+
+
+# ── 엑셀 컬럼명(앞뒤 공백 제거 후, 소문자 비교). 표준키 → 가능한 헤더들 ──
+#   TikTok(03_TikTok_Order_Export.xlsx)·Shopee(Packing List.Doorstep Delivery.xlsx)
+#   두 포맷의 헤더를 한 테이블에 모은다(매칭되는 것만 사용). 헤더가 다르면
+#   해당 표준키 줄에 별칭 1개만 추가하면 된다.
+#   받는 사람(recipient_*) 정보는 작업 카드 표시 + 출고 엑셀 생성을 위해 보관한다.
+COLUMN_ALIASES: dict[str, tuple[str, ...]] = {
+    "order_id":          ("order id", "order_id", "order sn", "order_sn", "ordersn", "order no.", "order number", "주문번호"),
+    "package_id":        ("package id", "package_id", "package number", "패키지번호"),
+    "tracking_id":       ("tracking id", "tracking_id", "tracking number", "tracking_number", "tracking no", "tracking no.", "awb", "awb no.", "송장번호"),
+    "shipping_provider": ("shipping provider name", "shipping provider", "shipping_provider_name",
+                          "shipping option", "courier", "carrier", "logistics", "배송사", "택배사"),
+    "seller_sku":        ("seller sku", "seller_sku", "sku", "sku reference no.", "sku reference no",
+                          "parent sku reference no.", "판매자 sku", "상품코드"),
+    "product_name":      ("product name", "product_name", "item name", "product", "상품명"),
+    "quantity":          ("quantity", "qty", "수량", "수량(개)"),
+    # 받는 사람(이름/전화/주소)은 xlsx 에서 매핑하지 않는다 — xlsx 값은 가려져 있어
+    # 신뢰할 수 없다. PII 는 라벨 PDF 에서만 가져온다(pdf_parser, Order ID 조인).
+}
+
+# 사용자에게 보여줄 컬럼 이름(누락 안내 메시지용). 비교키는 소문자라 별도 표기.
+COLUMN_DISPLAY: dict[str, str] = {
+    "order_id": "Order ID",
+    "package_id": "Package ID",
+    "tracking_id": "Tracking ID",
+    "shipping_provider": "Shipping Provider Name",
+    "seller_sku": "Seller SKU",
+    "product_name": "Product Name",
+    "quantity": "Quantity",
+    "recipient_name": "Recipient",
+    "recipient_phone": "Phone",
+    "recipient_address": "Address",
+}
+
+# 박스 단위로 보존하는 받는 사람 필드(같은 박스의 첫 비어있지 않은 값 사용).
+RECIPIENT_FIELDS: tuple[str, ...] = ("recipient_name", "recipient_phone", "recipient_address")
+
+# Shopee Packing List 의 상품 정보 컬럼(헤더 정규화 후 비교).
+PRODUCT_INFO_ALIASES: tuple[str, ...] = ("product_info", "product info", "상품정보")
+
+# Shopee product_info 한 셀에 여러 상품이 [1]…[2]… 로 들어온다. 각 상품은
+# "Key:Value" 들이 ';' 로 구분된다(예: Product Name:…; Variation Name:…; Price:…;
+# Quantity:1; SKU Reference No.: MT-0320_3;).
+_SHOPEE_ITEM_SPLIT = re.compile(r"\[\d+\]\s*")
+_SHOPEE_KEY_MAP: dict[str, str] = {
+    "product name": "product_name",
+    "variation name": "variation",
+    "quantity": "quantity",
+    "sku reference no": "seller_sku",  # 끝의 '.' 은 비교 전에 제거
+}
+
+
+def parse_shopee_product_info(blob: Any) -> list[dict[str, Any]]:
+    """Shopee product_info 셀 → 상품 리스트.
+
+    반환 각 항목: {seller_sku, product_name, variation, quantity}.
+    상품명 안에 ';' 이 들어가면 필드 분리가 깨질 수 있으나 Shopee 상품명에는
+    드물어 허용한다(필요 시 별도 처리).
+    """
+    s = clean_text(blob)
+    if not s:
+        return []
+    items: list[dict[str, Any]] = []
+    for chunk in _SHOPEE_ITEM_SPLIT.split(s):
+        chunk = chunk.strip()
+        if not chunk:
+            continue
+        fields: dict[str, str] = {}
+        for part in chunk.split(";"):
+            if ":" not in part:
+                continue
+            raw_key, _, value = part.partition(":")
+            key = raw_key.strip().lower().rstrip(".").strip()
+            std = _SHOPEE_KEY_MAP.get(key)
+            if std:
+                fields[std] = value.strip()
+        sku = fields.get("seller_sku", "")
+        if not sku and not fields.get("product_name"):
+            continue  # 식별 불가한 빈 항목 스킵
+        items.append(
+            {
+                "seller_sku": sku,
+                "product_name": fields.get("product_name", ""),
+                "variation": fields.get("variation", ""),
+                "quantity": normalize_quantity(fields.get("quantity")),
+            }
+        )
+    return items
+
+
+def find_column(headers: Iterable[Any], aliases: tuple[str, ...]) -> int | None:
+    """헤더에서 별칭에 맞는 첫 열 인덱스. 없으면 None."""
+    for idx, h in enumerate(headers):
+        if normalize_header(h) in aliases:
+            return idx
+    return None
+
+# 박스 묶음 기준 우선순위. 앞에서부터 비어있지 않은 첫 값으로 묶는다.
+BOX_KEY_PRIORITY: tuple[str, ...] = ("package_id", "tracking_id", "order_id")
+
+# 파싱에 최소한 필요한 표준키. (개인정보는 불필요)
+#   - SKU/수량이 없으면 포장할 상품을 못 만든다 → seller_sku 필수.
+#   - 박스 묶음을 위해 묶음키 3개 중 최소 하나는 있어야 한다.
+REQUIRED_COLUMNS: tuple[str, ...] = ("seller_sku",)
+
+
+def clean_text(value: Any) -> str:
+    """셀 값 → 안전한 문자열. None/NaN 은 빈 문자열. 양끝 공백 제거.
+
+    숫자는 과학적 표기/불필요한 .0 없이 보존한다(예: 송장번호가 float 로 읽혀도
+    '12345678901' 로 보존). Tracking ID 보존 요구사항을 만족한다.
+    """
+    if value is None:
+        return ""
+    # pandas/openpyxl NaN(float('nan')) 방어
+    if isinstance(value, float):
+        if value != value:  # NaN
+            return ""
+        if value.is_integer():
+            return str(int(value))
+        return repr(value)
+    if isinstance(value, int):
+        return str(value)
+    s = str(value).strip()
+    if s.lower() in ("nan", "none"):
+        return ""
+    return s
+
+
+def normalize_header(value: Any) -> str:
+    """헤더 셀 → 비교용 키(공백 제거 + 소문자)."""
+    return clean_text(value).lower()
+
+
+def resolve_columns(headers: Iterable[Any]) -> dict[str, int]:
+    """헤더 행 → {표준키: 열 인덱스}. 매핑 안 되는 열은 무시(개인정보 포함)."""
+    norm = [normalize_header(h) for h in headers]
+    mapping: dict[str, int] = {}
+    for std_key, aliases in COLUMN_ALIASES.items():
+        for idx, h in enumerate(norm):
+            if h in aliases:
+                mapping[std_key] = idx
+                break
+    return mapping
+
+
+def missing_required(mapping: dict[str, int]) -> list[str]:
+    """필수 컬럼 누락 목록(원문 헤더 형태로). 묶음키 전무도 누락으로 본다."""
+    missing: list[str] = []
+    for key in REQUIRED_COLUMNS:
+        if key not in mapping:
+            missing.append(COLUMN_DISPLAY[key])
+    if not any(k in mapping for k in BOX_KEY_PRIORITY):
+        missing.append("Package ID / Tracking ID / Order ID (최소 1개)")
+    return missing
+
+
+def box_key(row: dict[str, str]) -> str:
+    """박스 묶음 키 — package_id > tracking_id > order_id 우선순위."""
+    for key in BOX_KEY_PRIORITY:
+        v = (row.get(key) or "").strip()
+        if v:
+            return f"{key}:{v}"
+    return ""
+
+
+def group_parcels(rows: list[dict[str, str]]) -> list[dict[str, Any]]:
+    """정규화된 행 리스트 → 박스(parcel) 리스트.
+
+    rows 각 항목 키: order_id/package_id/tracking_id/shipping_provider/
+                     seller_sku/product_name/quantity(이미 문자열/int 정리됨).
+
+    반환(등장 순서 유지, seq 1..N 부여):
+      [{seq, order_id, package_id, tracking_id, shipping_provider,
+        items: [{seller_sku, product_name, quantity}, ...]}, ...]
+    같은 박스 안 같은 SKU 는 수량 합산. 묶음키가 전혀 없는 행은 버린다.
+    """
+    boxes: dict[str, dict[str, Any]] = {}
+    for row in rows:
+        key = box_key(row)
+        if not key:
+            continue
+        box = boxes.get(key)
+        if box is None:
+            box = {
+                "key": key,
+                "order_id": (row.get("order_id") or "").strip(),
+                "package_id": (row.get("package_id") or "").strip(),
+                "tracking_id": (row.get("tracking_id") or "").strip(),
+                "shipping_provider": (row.get("shipping_provider") or "").strip(),
+                "recipient_name": (row.get("recipient_name") or "").strip(),
+                "recipient_phone": (row.get("recipient_phone") or "").strip(),
+                "recipient_address": (row.get("recipient_address") or "").strip(),
+                "_items": {},  # sku -> {product_name, quantity}
+            }
+            boxes[key] = box
+        else:
+            # 같은 박스인데 식별값이 빈 경우 뒤늦게 채운다(누락 보강).
+            for field in ("order_id", "package_id", "tracking_id", "shipping_provider",
+                          "recipient_name", "recipient_phone", "recipient_address"):
+                if not box[field] and (row.get(field) or "").strip():
+                    box[field] = (row.get(field) or "").strip()
+
+        sku = (row.get("seller_sku") or "").strip()
+        if not sku:
+            continue
+        qty = normalize_quantity(row.get("quantity"))
+        item = box["_items"].get(sku)
+        if item is None:
+            box["_items"][sku] = {
+                "seller_sku": sku,
+                "product_name": (row.get("product_name") or "").strip(),
+                "quantity": qty,
+            }
+        else:
+            item["quantity"] += qty
+            if not item["product_name"] and (row.get("product_name") or "").strip():
+                item["product_name"] = (row.get("product_name") or "").strip()
+
+    parcels: list[dict[str, Any]] = []
+    for seq, box in enumerate(boxes.values(), start=1):
+        items = sorted(box["_items"].values(), key=lambda it: it["seller_sku"])
+        parcels.append(
+            {
+                "seq": seq,
+                "order_id": box["order_id"],
+                "package_id": box["package_id"],
+                "tracking_id": box["tracking_id"],
+                "shipping_provider": box["shipping_provider"],
+                "recipient_name": box["recipient_name"],
+                "recipient_phone": box["recipient_phone"],
+                "recipient_address": box["recipient_address"],
+                "items": items,
+            }
+        )
+    return parcels
+
+
+def normalize_quantity(value: Any) -> int:
+    """수량 정규화. 비어있으면 1. 음수/0/파싱불가도 1 로 보정(요구사항 11)."""
+    s = clean_text(value)
+    if s == "":
+        return 1
+    try:
+        n = int(float(s))
+    except (TypeError, ValueError):
+        return 1
+    return n if n > 0 else 1
+
+
+# ── 배송사 로고 ──
+#   배송사명(부분 일치, 소문자) → 슬러그. 슬러그 이름의 이미지 파일이 실제로
+#   있으면 이미지로 렌더하고, 없으면 텍스트 배지로 폴백한다(깨진 이미지 방지).
+#   새 배송사 로고 추가: 파일 1개 + 키워드 1줄.
+#     1) app/static/dispatch/courier/<슬러그>.png (또는 .svg) 추가
+#     2) 아래 _COURIER_KEYWORDS 에 (배송사명키워드, 슬러그) 추가
+_COURIER_KEYWORDS: tuple[tuple[str, str], ...] = (
+    ("ninja", "ninjavan"),
+    ("j&t", "jnt"),
+    ("jnt", "jnt"),
+    ("flash", "flash"),
+    ("city", "citylink"),
+    ("pos laju", "poslaju"),
+    ("poslaju", "poslaju"),
+    ("gdex", "gdex"),
+    ("gd express", "gdex"),
+    ("shopee", "spx"),
+    ("spx", "spx"),
+)
+
+# 로고 파일 디렉토리(app/static/dispatch/courier). png 를 svg 보다 우선한다.
+_COURIER_DIR = Path(__file__).resolve().parents[2] / "static" / "dispatch" / "courier"
+_COURIER_EXTS: tuple[str, ...] = (".png", ".svg")
+
+
+def courier_slug(provider: Any) -> str:
+    """배송사명 → 로고 슬러그(부분 일치). 매칭 없으면 ""."""
+    name = clean_text(provider).lower()
+    if not name:
+        return ""
+    for keyword, slug in _COURIER_KEYWORDS:
+        if keyword in name:
+            return slug
+    return ""
+
+
+@lru_cache(maxsize=128)
+def _logo_url_for_slug(slug: str) -> str:
+    """슬러그에 해당하는 실제 로고 파일 URL(png 우선). 없으면 ""."""
+    if not slug:
+        return ""
+    for ext in _COURIER_EXTS:
+        if (_COURIER_DIR / f"{slug}{ext}").exists():
+            return f"/static/dispatch/courier/{slug}{ext}"
+    return ""
+
+
+def courier_logo_url(provider: Any) -> str:
+    """배송사명 → 로고 이미지 URL. 파일 없으면 ""(템플릿이 텍스트로 폴백)."""
+    return _logo_url_for_slug(courier_slug(provider))
+
+
+# ── 배송사별 송장 조회 딥링크 ──
+#   {t} 자리에 송장번호를 넣어 조회 페이지로 바로 이동(자동 입력 효과).
+#   ⚠️ 배송사 사이트 URL 은 바뀔 수 있다. 안 열리면 여기만 고치면 된다.
+#   매핑 없는 배송사는 링크 없이 텍스트로 표시(courier_tracking_url 가 "" 반환).
+_COURIER_TRACK_URL: dict[str, str] = {
+    "ninjavan": "https://www.ninjavan.co/en-my/tracking?id={t}",
+    # J&T MY 는 경로(path)에 송장번호를 붙이면 자동 조회된다(쿼리 파라미터는 무시).
+    "jnt": "https://www.jtexpress.my/tracking/{t}",
+    "flash": "https://www.flashexpress.my/fle/tracking?se={t}",
+    "citylink": "https://www.citylinkexpress.com/tracking-result/?track_no={t}",
+    "poslaju": "https://track.pos.com.my/postal-services/quick-access/?track-trace&trackingNo03={t}",
+    "gdex": "https://web.gdexpress.com/official/web/ConsignmentSearch.html?capcheck=true&input_search={t}",
+    "spx": "https://spx.com.my/track?tracking_number={t}",
+}
+
+
+def courier_tracking_url(tracking: Any, provider: Any = "") -> str:
+    """송장번호 + 배송사명 → 조회 딥링크. 매핑/번호 없으면 ""."""
+    t = clean_text(tracking)
+    tmpl = _COURIER_TRACK_URL.get(courier_slug(provider))
+    if not t or not tmpl:
+        return ""
+    return tmpl.replace("{t}", quote(t, safe=""))
+
+
+def sku_summary(parcels: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """전체 박스 기준 SKU별 총 수량(피킹 요약). seller_sku 오름차순."""
+    totals: dict[str, dict[str, Any]] = {}
+    for p in parcels:
+        for it in p.get("items", []):
+            sku = it["seller_sku"]
+            row = totals.get(sku)
+            if row is None:
+                totals[sku] = {
+                    "seller_sku": sku,
+                    "product_name": it.get("product_name", ""),
+                    "total_qty": int(it["quantity"]),
+                }
+            else:
+                row["total_qty"] += int(it["quantity"])
+                if not row["product_name"] and it.get("product_name"):
+                    row["product_name"] = it["product_name"]
+    return sorted(totals.values(), key=lambda r: r["seller_sku"])

app/modules/dispatch/templates/dispatch/_nav.html

@@ -0,0 +1,84 @@
+{# 말레이시아 배송 공용 상단 바: 목록/업로드 + (배치 진입 시) 작업/피킹/전달 서브탭
+   + 한글/영문 토글(localStorage 저장, 전 페이지 공통). #}
+<div class="erp-page-actions" style="display:flex;gap:8px;flex-wrap:wrap;align-items:center;">
+  <a class="erp-btn {% if active_tab=='batches' %}erp-btn-primary{% else %}erp-btn-outline{% endif %}" href="/dispatch/"
+     data-ko="출고 배치" data-en="Batches">출고 배치</a>
+  <a class="erp-btn {% if active_tab=='new' %}erp-btn-primary{% else %}erp-btn-outline{% endif %}" href="/dispatch/batches/new"
+     data-ko="＋ 새 업로드" data-en="+ New Upload">＋ 새 업로드</a>
+
+  {% if active_tab=='batches' %}
+  {# 받는 사람 찾기: 배치 목록 페이지에서만. 마크업/스타일/스크립트는 batches.html. #}
+  <div class="dsp-search" id="dsp-search">
+    <div class="dsp-search-box">
+      <span class="dsp-q-ico">🔎</span>
+      <input type="text" id="dsp-q" autocomplete="off"
+             data-ko-ph="이름 · 주문번호 · 패키지번호 · 송장번호로 받는 사람 찾기"
+             data-en-ph="Find recipient by name / order / package / tracking no."
+             placeholder="이름 · 주문번호 · 패키지번호 · 송장번호로 받는 사람 찾기" />
+      <button type="button" class="dsp-q-clear" id="dsp-q-clear" aria-label="clear">×</button>
+    </div>
+    <div class="dsp-search-results" id="dsp-search-results"></div>
+  </div>
+  {% endif %}
+
+  {% if batch %}
+  <span style="width:1px;height:24px;background:#e2e8f0;margin:0 4px;"></span>
+  <a class="erp-btn {% if active_tab=='work' %}erp-btn-primary{% else %}erp-btn-outline{% endif %}" href="/dispatch/batches/{{ batch.id }}"
+     data-ko="출고 작업" data-en="Dispatch Work">출고 작업</a>
+  <a class="erp-btn {% if active_tab=='picking' %}erp-btn-primary{% else %}erp-btn-outline{% endif %}" href="/dispatch/batches/{{ batch.id }}/picking"
+     data-ko="피킹 요약" data-en="Picking Summary">피킹 요약</a>
+  <a class="erp-btn {% if active_tab=='handover' %}erp-btn-primary{% else %}erp-btn-outline{% endif %}" href="/dispatch/batches/{{ batch.id }}/handover"
+     data-ko="Kagayaku 전달" data-en="Kagayaku Handover">Kagayaku 전달</a>
+  {% endif %}
+
+  <button id="dsp-lang-btn" type="button" class="erp-btn erp-btn-outline" style="margin-left:auto;font-weight:700;"
+          onclick="dspToggleLang()">EN</button>
+</div>
+
+<script>
+// 한글/영문 토글. data-ko/data-en(텍스트), data-ko-ph/data-en-ph(placeholder) 교체.
+(function () {
+  var KEY = 'dsp_lang';
+  window.dspApplyLang = function (lang) {
+    if (lang !== 'ko' && lang !== 'en') lang = 'ko';
+    document.querySelectorAll('[data-ko]').forEach(function (el) {
+      var v = el.getAttribute('data-' + lang);
+      if (v !== null) el.textContent = v;
+    });
+    document.querySelectorAll('[data-ko-ph]').forEach(function (el) {
+      var v = el.getAttribute('data-' + lang + '-ph');
+      if (v !== null) el.placeholder = v;
+    });
+    // 배치명은 저장된 데이터라 정적 번역 불가. 자동 기본 이름의 '출고'/'(이름없음)'만
+    // 영문에서 치환(직접 입력한 다른 한글 이름은 그대로 둔다).
+    document.querySelectorAll('[data-raw]').forEach(function (el) {
+      var raw = el.getAttribute('data-raw') || '';
+      el.textContent = (lang === 'en')
+        ? raw.replace(/출고/g, 'Dispatch').replace('(이름없음)', '(no name)')
+        : raw;
+    });
+    var btn = document.getElementById('dsp-lang-btn');
+    if (btn) btn.textContent = (lang === 'ko') ? 'EN' : '한국어';
+    try { localStorage.setItem(KEY, lang); } catch (e) {}
+    document.documentElement.setAttribute('data-dsp-lang', lang);
+    document.dispatchEvent(new CustomEvent('dsp:lang', { detail: { lang: lang } }));
+  };
+  // 현재 언어(동적 텍스트 생성용).
+  window.dspLang = function () {
+    try { return localStorage.getItem(KEY) || 'ko'; } catch (e) { return 'ko'; }
+  };
+  window.dspToggleLang = function () {
+    var cur = 'ko';
+    try { cur = localStorage.getItem(KEY) || 'ko'; } catch (e) {}
+    window.dspApplyLang(cur === 'ko' ? 'en' : 'ko');
+  };
+  var init = 'ko';
+  try { init = localStorage.getItem(KEY) || 'ko'; } catch (e) {}
+  // DOM 준비 후 적용(스크립트가 상단이라 본문 요소가 아직일 수 있어 보강).
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () { window.dspApplyLang(init); });
+  } else {
+    window.dspApplyLang(init);
+  }
+})();
+</script>

app/modules/dispatch/templates/dispatch/batches.html

@@ -0,0 +1,382 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<style>
+  /* 배치 목록 가독성: 표 글자 약간 키움 */
+  .dsp-batches.erp-table td { font-size:15px; }
+  .dsp-batches.erp-table th { font-size:13px; }
+  /* 플랫폼 로고: 아이콘마다 여백이 달라 시각 크기를 맞춘다 */
+  .dsp-pf-logo { height:26px;width:auto;max-width:120px;vertical-align:middle;object-fit:contain; }
+  .dsp-pf-logo[src*="shopee"] { height:34px; }
+  /* 좌(리스트) / 우(달력) 2단 */
+  .dsp-layout { display:flex;gap:16px;align-items:flex-start;flex-wrap:wrap; }
+  .dsp-list { flex:1 1 620px;min-width:320px; }
+  .dsp-calwrap { flex:0 1 340px;min-width:280px; }
+  /* 달력 */
+  .dsp-cal-head { display:flex;align-items:center;justify-content:space-between;gap:8px;margin-bottom:8px; }
+  .dsp-cal-grid { display:grid;grid-template-columns:repeat(7,1fr);gap:4px; }
+  .dsp-cal-wd { text-align:center;font-size:12px;color:#94a3b8;padding:2px 0;font-weight:600; }
+  .dsp-cal-day { text-align:center;padding:8px 0;border-radius:8px;font-size:14px;color:#cbd5e1; }
+  .dsp-cal-day.has { color:#0f172a;background:#eef2ff;font-weight:700;cursor:pointer;border:1px solid #c7d2fe; }
+  .dsp-cal-day.has:hover { background:#e0e7ff; }
+  .dsp-cal-day.sel { background:#16a34a !important;border-color:#16a34a !important;color:#fff !important; }
+  /* 검색: _nav 행에서 「＋ 새 업로드」오른쪽 30px, 결과는 절대위치 드롭다운 */
+  .dsp-search { position:relative;flex:0 1 420px;min-width:240px;margin-left:30px; }
+  .dsp-search-box { position:relative; }
+  .dsp-search-box .dsp-q-ico { position:absolute;left:11px;top:50%;transform:translateY(-50%);font-size:14px;color:#94a3b8;pointer-events:none; }
+  .dsp-search-box input { width:100%;padding:9px 30px 9px 32px;border:1px solid #cbd5e1;border-radius:8px;font-size:14px;box-sizing:border-box; }
+  .dsp-search-box input:focus { outline:none;border-color:#6366f1;box-shadow:0 0 0 3px rgba(99,102,241,.15); }
+  .dsp-q-clear { position:absolute;right:8px;top:50%;transform:translateY(-50%);border:0;background:transparent;color:#94a3b8;font-size:18px;cursor:pointer;line-height:1;padding:0 4px;display:none; }
+  .dsp-search-results { position:absolute;left:0;right:0;top:calc(100% + 4px);z-index:40;background:#fff;border:1px solid #e2e8f0;border-radius:10px;box-shadow:0 8px 24px rgba(15,23,42,.12);max-height:64vh;overflow:auto;display:none;padding:6px; }
+  .dsp-search-results.open { display:block; }
+  .dsp-hit { border-radius:8px;padding:11px 12px;display:flex;justify-content:space-between;gap:12px;align-items:flex-start; }
+  .dsp-hit + .dsp-hit { border-top:1px solid #f1f5f9; }
+  .dsp-hit:hover { background:#f8fafc; }
+  .dsp-hit-body { min-width:0; }
+  .dsp-hit-name { font-weight:700;font-size:17px;color:#0f172a; }
+  .dsp-hit-meta { font-size:14px;color:#475569;margin-top:3px;line-height:1.5; }
+  /* Order / Pkg / 송장 — 한 줄씩 */
+  .dsp-id { font-size:14.5px;margin-top:4px;display:flex;gap:8px;align-items:baseline;flex-wrap:wrap; }
+  .dsp-id-k { color:#94a3b8;font-size:12px;min-width:42px;flex:0 0 auto; }
+  .dsp-id code { background:#f1f5f9;padding:2px 7px;border-radius:5px;font-size:14px;color:#0f172a; }
+  .dsp-id-track code { font-weight:700; }
+  .dsp-track-lnk { text-decoration:none; }
+  .dsp-track-lnk code { color:#4f46e5;text-decoration:underline;cursor:pointer; }
+  .dsp-track-lnk:hover code { background:#e0e7ff; }
+  .dsp-courier { font-size:12.5px;font-weight:600;color:#475569;background:#eef2ff;border:1px solid #c7d2fe;border-radius:999px;padding:1px 9px; }
+  .dsp-hit mark { background:#fde68a;padding:0 1px;border-radius:2px; }
+  .dsp-hit-batch { font-size:13px;color:#475569;margin-top:5px; }
+  .dsp-hit-go { white-space:nowrap;flex:0 0 auto;align-self:center; }
+  .dsp-hit-empty { color:#94a3b8;font-size:14.5px;padding:11px; }
+</style>
+{% endblock %}
+
+{% block content %}
+<section class="dsp">
+  {% include "dispatch/_nav.html" %}
+
+  <div class="dsp-layout">
+  <div class="erp-card dsp-list">
+    <div class="cpg-card-head" style="display:flex;justify-content:space-between;align-items:center;">
+      <h2><span data-ko="출고 배치" data-en="Batches">출고 배치</span> ({{ batches|length }})</h2>
+      <a class="erp-btn erp-btn-primary" href="/dispatch/batches/new" data-ko="＋ 새 업로드" data-en="+ New Upload">＋ 새 업로드</a>
+    </div>
+    <div class="erp-table-wrap">
+      <table class="erp-table dsp-batches">
+        <thead>
+          <tr>
+            <th data-ko="날짜" data-en="Date">날짜</th>
+            <th data-ko="플랫폼" data-en="Platform">플랫폼</th>
+            <th data-ko="배치명" data-en="Batch">배치명</th>
+            <th style="text-align:right" data-ko="박스" data-en="Boxes">박스</th>
+            <th style="text-align:right" data-ko="완료" data-en="Done">완료</th>
+            <th data-ko="생성시각" data-en="Created">생성시각</th><th></th>
+          </tr>
+        </thead>
+        <tbody>
+          {% for b in batches %}
+          <tr>
+            <td style="white-space:nowrap;">{{ b.dispatch_date }}</td>
+            <td>
+              {% set pf = (b.platform or '')|lower %}
+              {% if pf in ['tiktok', 'shopee'] %}
+              <img class="dsp-pf-logo" src="/static/dispatch/courier/{{ pf }}.png" alt="{{ b.platform }}" title="{{ b.platform }}" />
+              {% else %}{{ b.platform }}{% endif %}
+            </td>
+            <td><a href="/dispatch/batches/{{ b.id }}" style="font-weight:600;" class="dsp-bname"
+                   data-raw="{{ b.batch_name or '(이름없음)' }}">{{ b.batch_name or '(이름없음)' }}</a></td>
+            <td style="text-align:right;">{{ b.parcel_count }}</td>
+            <td style="text-align:right;">
+              {% if b.parcel_count and b.done_count == b.parcel_count %}
+              <span style="color:#16a34a;font-weight:600;">{{ b.done_count }} ✓</span>
+              {% else %}{{ b.done_count }}{% endif %}
+            </td>
+            <td class="erp-muted" style="white-space:nowrap;">{{ (b.created_at[:19].replace('T',' ')) if b.created_at else '' }}</td>
+            <td style="text-align:right;white-space:nowrap;">
+              <a class="erp-btn erp-btn-outline" href="/dispatch/batches/{{ b.id }}" data-ko="작업" data-en="Work">작업</a>
+              <a class="erp-btn erp-btn-outline" href="/dispatch/batches/{{ b.id }}/picking" data-ko="피킹" data-en="Picking">피킹</a>
+              <a class="erp-btn erp-btn-outline" href="/dispatch/batches/{{ b.id }}/handover" data-ko="전달" data-en="Handover">전달</a>
+              <a class="erp-btn erp-btn-outline" href="/dispatch/batches/{{ b.id }}/download" data-ko="다운로드" data-en="Download">다운로드</a>
+              {% if is_super %}
+              <form method="post" action="/dispatch/batches/{{ b.id }}/delete" style="display:inline;"
+                    onsubmit="return confirm('배치 「{{ b.batch_name or '(이름없음)' }}」 와 모든 박스/상품/로그를 삭제합니다. 되돌릴 수 없습니다. 계속할까요?');">
+                <button type="submit" class="erp-btn erp-btn-outline" style="color:#dc2626;border-color:#fca5a5;" data-ko="삭제" data-en="Delete">삭제</button>
+              </form>
+              {% endif %}
+            </td>
+          </tr>
+          {% endfor %}
+          {% if not batches %}
+          <tr><td colspan="7" class="erp-muted" data-ko="아직 출고 배치가 없습니다. 위 ＋ 새 업로드로 시작하세요." data-en="No batches yet. Start with + New Upload above.">아직 출고 배치가 없습니다. 위 ＋ 새 업로드로 시작하세요.</td></tr>
+          {% endif %}
+        </tbody>
+      </table>
+    </div>
+  </div>
+
+  <div class="erp-card dsp-calwrap">
+    <div class="cpg-card-head"><h3 style="margin:0;" data-ko="사방넷 출고 다운로드" data-en="Sabangnet Outbound Download">사방넷 출고 다운로드</h3></div>
+    <p class="erp-muted" style="margin:4px 0 10px;font-size:13px;"
+       data-ko="날짜를 클릭하면 그날 출고를 낱개로 분해한 사방넷 출고 엑셀을 받습니다. 사방넷에 올리면 출고로 잡혀 재고가 차감됩니다."
+       data-en="Pick a date for the Sabangnet outbound Excel (combos split into singles). Upload it to Sabangnet to register the shipment and deduct stock.">날짜를 클릭하면 그날 출고를 낱개로 분해한 사방넷 출고 엑셀을 받습니다. 사방넷에 올리면 출고로 잡혀 재고가 차감됩니다.</p>
+
+    <div class="dsp-cal" id="dsp-cal">
+      <div class="dsp-cal-head">
+        <button type="button" class="erp-btn erp-btn-outline" id="dsp-cal-prev">‹</button>
+        <span id="dsp-cal-title" style="font-weight:700;"></span>
+        <button type="button" class="erp-btn erp-btn-outline" id="dsp-cal-next">›</button>
+      </div>
+      <div class="dsp-cal-grid" id="dsp-cal-grid"></div>
+    </div>
+
+    <div style="margin-top:12px;display:flex;flex-direction:column;gap:8px;">
+      <div class="erp-muted" style="font-size:13px;">
+        <span data-ko="선택한 날짜" data-en="Selected">선택한 날짜</span>:
+        <b id="dsp-cal-sel">—</b>
+      </div>
+      <a id="dsp-cal-dl" class="erp-btn erp-btn-primary" href="#"
+         data-ko="📥 사방넷 출고 엑셀 다운로드" data-en="📥 Download Sabangnet Outbound Excel"
+         style="pointer-events:none;opacity:.5;">📥 사방넷 출고 엑셀 다운로드</a>
+      <button id="dsp-cal-deduct" type="button" class="erp-btn erp-btn-outline" onclick="dspDeduct()"
+              data-ko="📦 말레이시아 재고 차감" data-en="📦 Deduct Malaysia Stock"
+              style="pointer-events:none;opacity:.5;">📦 말레이시아 재고 차감</button>
+      <div id="dsp-cal-deduct-note" class="erp-muted" style="font-size:12px;"></div>
+    </div>
+  </div>
+  </div>
+</section>
+{% endblock %}
+
+{% block scripts %}
+<script>
+(function () {
+  // 배치가 있는 날짜(YYYY-MM-DD)
+  var BATCH_DATES = {{ batch_dates|tojson }};
+  var DEDUCTED = {};
+  ({{ deducted_dates|tojson }}).forEach(function (d) { DEDUCTED[d] = true; });
+  var dateSet = {};
+  BATCH_DATES.forEach(function (d) { dateSet[d] = true; });
+
+  var grid = document.getElementById('dsp-cal-grid');
+  var title = document.getElementById('dsp-cal-title');
+  var selLabel = document.getElementById('dsp-cal-sel');
+  var dlBtn = document.getElementById('dsp-cal-dl');
+  var dedBtn = document.getElementById('dsp-cal-deduct');
+  var dedNote = document.getElementById('dsp-cal-deduct-note');
+  var selected = null;
+
+  // 초기 표시 월: 가장 최근 배치 날짜 기준(없으면 오늘)
+  var base = BATCH_DATES.length ? new Date(BATCH_DATES[BATCH_DATES.length - 1] + 'T00:00:00') : new Date();
+  var viewY = base.getFullYear(), viewM = base.getMonth();
+
+  var WD = { ko: ['일','월','화','수','목','금','토'], en: ['Su','Mo','Tu','We','Th','Fr','Sa'] };
+  function lang() { return (window.dspLang && window.dspLang() === 'en') ? 'en' : 'ko'; }
+  function pad(n) { return (n < 10 ? '0' : '') + n; }
+
+  function render() {
+    var l = lang();
+    title.textContent = viewY + '.' + pad(viewM + 1);
+    grid.innerHTML = '';
+    WD[l].forEach(function (w) {
+      var c = document.createElement('div');
+      c.className = 'dsp-cal-wd'; c.textContent = w; grid.appendChild(c);
+    });
+    var first = new Date(viewY, viewM, 1).getDay();
+    var days = new Date(viewY, viewM + 1, 0).getDate();
+    for (var i = 0; i < first; i++) grid.appendChild(document.createElement('div'));
+    for (var d = 1; d <= days; d++) {
+      var iso = viewY + '-' + pad(viewM + 1) + '-' + pad(d);
+      var cell = document.createElement('div');
+      cell.className = 'dsp-cal-day';
+      cell.textContent = d;
+      if (dateSet[iso]) {
+        cell.classList.add('has');
+        cell.setAttribute('data-iso', iso);
+        cell.onclick = function () { pick(this.getAttribute('data-iso')); };
+      }
+      if (iso === selected) cell.classList.add('sel');
+      grid.appendChild(cell);
+    }
+  }
+
+  function pick(iso) {
+    selected = iso;
+    selLabel.textContent = iso;
+    dlBtn.href = '/dispatch/stock-export?date=' + encodeURIComponent(iso);
+    dlBtn.style.pointerEvents = '';
+    dlBtn.style.opacity = '';
+    updateDeductBtn();
+    render();
+  }
+
+  function updateDeductBtn() {
+    var en = (window.dspLang && window.dspLang() === 'en');
+    if (!selected) {
+      dedBtn.style.pointerEvents = 'none'; dedBtn.style.opacity = '.5';
+      dedNote.textContent = '';
+      return;
+    }
+    if (DEDUCTED[selected]) {
+      dedBtn.style.pointerEvents = 'none'; dedBtn.style.opacity = '.5';
+      dedNote.textContent = en ? 'Already deducted (cannot run again).' : '이미 차감됨 (재실행 불가).';
+    } else {
+      dedBtn.style.pointerEvents = ''; dedBtn.style.opacity = '';
+      dedNote.textContent = '';
+    }
+  }
+
+  window.dspDeduct = function () {
+    if (!selected || DEDUCTED[selected]) return;
+    var en = (window.dspLang && window.dspLang() === 'en');
+    var msg = en
+      ? ('Deduct Malaysia stock for ' + selected + '? This runs ONCE only and cannot be undone.')
+      : (selected + ' 출고를 말레이시아 재고에서 차감할까요?\n한 번만 실행되며 되돌릴 수 없습니다.');
+    if (!confirm(msg)) return;
+    dedBtn.style.pointerEvents = 'none'; dedBtn.style.opacity = '.5';
+    dedNote.textContent = en ? 'Processing…' : '처리 중…';
+    var body = new URLSearchParams(); body.set('date', selected);
+    fetch('/dispatch/stock-deduct', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+    })
+      .then(function (r) { return r.json().then(function (j) { return { ok: r.ok, j: j }; }); })
+      .then(function (res) {
+        if (!res.ok) throw new Error((res.j && res.j.detail) || '실패');
+        DEDUCTED[selected] = true;
+        updateDeductBtn();
+        alert((en ? 'Done. singles ' : '완료. 낱개 ') + res.j.singles + (en ? ', combos ' : '종, 콤보 ') + res.j.combos + (en ? '' : '종 반영'));
+      })
+      .catch(function (e) {
+        dedNote.textContent = (e && e.message) || '실패';
+        updateDeductBtn();
+        alert((en ? 'Failed: ' : '실패: ') + ((e && e.message) || ''));
+      });
+  };
+
+  document.getElementById('dsp-cal-prev').onclick = function () {
+    viewM--; if (viewM < 0) { viewM = 11; viewY--; } render();
+  };
+  document.getElementById('dsp-cal-next').onclick = function () {
+    viewM++; if (viewM > 11) { viewM = 0; viewY++; } render();
+  };
+  document.addEventListener('dsp:lang', function () { render(); updateDeductBtn(); });
+  render();
+})();
+
+// ── 받는 사람 찾기(이름/주문/패키지/송장 번호 부분 일치) ──
+(function () {
+  var wrap = document.getElementById('dsp-search');
+  var input = document.getElementById('dsp-q');
+  var box = document.getElementById('dsp-search-results');
+  var clearBtn = document.getElementById('dsp-q-clear');
+  if (!input || !box) return;
+  var timer = null, lastQ = '';
+
+  function open() { box.classList.add('open'); }
+  function close() { box.classList.remove('open'); }
+
+  function esc(s) {
+    return String(s == null ? '' : s)
+      .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+  // 매칭된 부분만 강조(이미 escape 된 문자열에 대해 안전하게 처리).
+  function hi(value, q) {
+    var s = esc(value);
+    if (!q) return s;
+    var i = s.toLowerCase().indexOf(q.toLowerCase());
+    if (i < 0) return s;
+    return s.slice(0, i) + '<mark>' + s.slice(i, i + q.length) + '</mark>' + s.slice(i + q.length);
+  }
+  function en() { return (window.dspLang && window.dspLang() === 'en'); }
+
+  function idLine(label, value, q) {
+    if (!value) return '';
+    return '<div class="dsp-id"><span class="dsp-id-k">' + label + '</span>'
+      + '<code>' + hi(value, q) + '</code></div>';
+  }
+  function trackLine(r, q) {
+    if (!r.tracking_id) return '';
+    var num = '<code>' + hi(r.tracking_id, q) + '</code>';
+    // 송장번호 클릭 → 배송사 조회 페이지(딥링크 있으면).
+    var inner = r.tracking_url
+      ? '<a href="' + esc(r.tracking_url) + '" target="_blank" rel="noopener" class="dsp-track-lnk">' + num + '</a>'
+      : num;
+    var courier = r.shipping_provider
+      ? '<span class="dsp-courier">' + esc(r.shipping_provider) + '</span>'
+      : '';
+    return '<div class="dsp-id dsp-id-track"><span class="dsp-id-k">' + (en() ? 'Track' : '송장') + '</span>'
+      + inner + courier + '</div>';
+  }
+
+  function row(r, q) {
+    var name = r.recipient_name
+      ? hi(r.recipient_name, q)
+      : esc(en() ? '(no recipient name)' : '(받는 사람 정보 없음)');
+    var contact = [];
+    if (r.recipient_phone)   contact.push(esc(r.recipient_phone));
+    if (r.recipient_address) contact.push(esc(r.recipient_address));
+    var done = r.label_attached && r.handed_to_kagayaku;
+    // 날짜·쇼핑몰은 굵게.
+    var batchLine = '<b>' + esc(r.dispatch_date) + '</b> · <b>' + esc(r.platform) + '</b> · '
+      + esc(r.batch_name || '') + ' · ' + (en() ? 'Box #' : '박스 #') + esc(r.seq)
+      + (done ? ' · <span style="color:#16a34a;font-weight:700;">✓</span>' : '');
+    return '<div class="dsp-hit">'
+      + '<div class="dsp-hit-body">'
+      +   '<div class="dsp-hit-name">' + name + '</div>'
+      +   (contact.length ? '<div class="dsp-hit-meta">' + contact.join(' · ') + '</div>' : '')
+      +   idLine('Order', r.order_id, q)
+      +   idLine('Pkg', r.package_id, q)
+      +   trackLine(r, q)
+      +   '<div class="dsp-hit-batch">' + batchLine + '</div>'
+      + '</div>'
+      + '<a class="erp-btn erp-btn-outline dsp-hit-go" href="/dispatch/batches/' + encodeURIComponent(r.batch_id) + '">'
+      +   (en() ? 'Open' : '작업 열기') + '</a>'
+      + '</div>';
+  }
+
+  function run(q) {
+    fetch('/dispatch/api/search?q=' + encodeURIComponent(q))
+      .then(function (r) { return r.json(); })
+      .then(function (j) {
+        if (j.query !== input.value.trim()) return; // 더 최신 입력이 있으면 무시
+        var rs = j.results || [];
+        if (!rs.length) {
+          box.innerHTML = '<div class="dsp-hit-empty">'
+            + (en() ? 'No match.' : '일치하는 박스가 없습니다.') + '</div>';
+        } else {
+          box.innerHTML = rs.map(function (r) { return row(r, q); }).join('');
+        }
+        open();
+      })
+      .catch(function () {
+        box.innerHTML = '<div class="dsp-hit-empty">'
+          + (en() ? 'Search failed.' : '검색 실패.') + '</div>';
+        open();
+      });
+  }
+
+  function reset() {
+    box.innerHTML = ''; close(); lastQ = '';
+    if (clearBtn) clearBtn.style.display = 'none';
+  }
+
+  input.addEventListener('input', function () {
+    var q = input.value.trim();
+    if (clearBtn) clearBtn.style.display = q ? 'block' : 'none';
+    if (timer) clearTimeout(timer);
+    if (q.length < 2) { box.innerHTML = ''; close(); lastQ = ''; return; }
+    if (q === lastQ) { open(); return; }
+    lastQ = q;
+    timer = setTimeout(function () { run(q); }, 250);
+  });
+  // 결과가 있으면 포커스 시 다시 펼친다.
+  input.addEventListener('focus', function () { if (box.innerHTML) open(); });
+  if (clearBtn) clearBtn.addEventListener('click', function () { input.value = ''; reset(); input.focus(); });
+  input.addEventListener('keydown', function (e) { if (e.key === 'Escape') { close(); input.blur(); } });
+  // 바깥 클릭 시 닫기.
+  document.addEventListener('click', function (e) { if (!wrap.contains(e.target)) close(); });
+})();
+</script>
+{% endblock %}

app/modules/dispatch/templates/dispatch/detail.html

@@ -0,0 +1,274 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<style>
+  .dsp-toolbar { display:flex;gap:8px;flex-wrap:wrap;align-items:center;margin:12px 0; }
+  .dsp-filter { display:flex;gap:6px;flex-wrap:wrap; }
+  .dsp-search { flex:0 1 240px;min-width:150px; }
+  .dsp-bulk { margin-left:auto;display:flex;gap:8px;flex-wrap:wrap; }
+  .dsp-bulk .dsp-btn-status { padding:8px 16px; }
+  .dsp-cards { display:grid;grid-template-columns:repeat(auto-fill,minmax(300px,1fr));gap:14px; }
+  .dsp-card { border:1px solid #e2e8f0;border-radius:12px;padding:14px;background:#fff;display:flex;flex-direction:column;gap:10px; }
+  .dsp-card { position:relative; }
+  .dsp-card.is-done { border-color:#86efac;background:#f0fdf4; }
+  .dsp-no { font-size:20px;font-weight:700;color:#0f172a; }
+  .dsp-courier-text { position:absolute;top:12px;right:14px; }
+  .dsp-meta { font-size:13px;line-height:1.5;color:#334155;word-break:break-all; }
+  .dsp-meta b { color:#0f172a; }
+  .dsp-order { font-size:15px;line-height:1.3;color:#334155;word-break:break-all; }
+  .dsp-order b { display:block;font-size:14px;font-weight:700;color:#475569;letter-spacing:.5px; }
+  .dsp-order span { font-size:27px;font-weight:800;color:#0f172a;letter-spacing:.2px; }
+  .dsp-recipient { border-top:1px dashed #e2e8f0;padding-top:8px; }
+  .dsp-rname { display:block;font-size:22px;font-weight:800;color:#0f172a;line-height:1.2;word-break:break-word; }
+  .dsp-raddr { font-size:14px;line-height:1.45;color:#334155;white-space:normal;word-break:break-word;margin-top:3px; }
+  .dsp-rphone { font-size:13px;color:#475569;margin-top:2px; }
+  .dsp-track-link { color:#2563eb !important;font-size:18px;font-weight:800;
+                    text-decoration:underline !important;text-decoration-line:underline !important;
+                    text-decoration-thickness:2px;text-underline-offset:3px;cursor:pointer; }
+  .dsp-track-link:hover { color:#1d4ed8 !important; }
+  .dsp-items { list-style:none;margin:0;padding:8px 0;border-top:1px dashed #e2e8f0;border-bottom:1px dashed #e2e8f0; }
+  .dsp-items li { font-size:16px;font-weight:600;color:#0f172a;padding:2px 0; }
+  .dsp-items .qty { color:#2563eb; }
+  .dsp-status { display:grid;grid-template-columns:1fr 1fr;gap:6px; }
+  .dsp-status .full { grid-column:1 / -1; }
+  .dsp-btn-status { border:1px solid #cbd5e1;border-radius:8px;padding:8px 6px;background:#f1f5f9;color:#475569;
+                    font-weight:600;cursor:pointer;text-align:center;line-height:1.25;transition:background .12s,border-color .12s,color .12s; }
+  .dsp-btn-status small { display:block;font-size:10px;font-weight:500;opacity:.8; }
+  .dsp-btn-status.on { background:#16a34a;border-color:#16a34a;color:#fff; }
+  .dsp-btn-status:disabled { opacity:.6;cursor:wait; }
+  .dsp-courier { position:absolute;top:12px;right:14px;height:44px;width:auto;max-width:180px;object-fit:contain; }
+  /* SPX 로고는 가로로 넓어 같은 높이에서 더 커 보인다 — 틱톡 로고와 시각 크기 맞춤 */
+  .dsp-courier[src*="spx"] { height:30px;top:18px; }
+  .dsp-hidden { display:none !important; }
+  @media (max-width:480px){ .dsp-cards{grid-template-columns:1fr;} }
+</style>
+{% endblock %}
+
+{% block content %}
+<section class="dsp" data-batch="{{ batch.id }}">
+  {% include "dispatch/_nav.html" %}
+
+  <div class="erp-card">
+    <div class="cpg-card-head" style="display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:8px;">
+      <h2><span data-ko="출고 작업 · 박스" data-en="Dispatch Work · Boxes">출고 작업 · 박스</span> {{ parcels|length }}</h2>
+      <span class="erp-muted" id="dsp-done-label"
+            data-done="{{ done_count }}" data-total="{{ parcels|length }}">완료 {{ done_count }} / {{ parcels|length }}</span>
+    </div>
+
+    <div class="dsp-toolbar">
+      <div class="dsp-filter" id="dsp-filter">
+        <button class="erp-btn erp-btn-primary" data-filter="all" type="button" data-ko="전체" data-en="All">전체</button>
+        <button class="erp-btn erp-btn-outline" data-filter="incomplete" type="button" data-ko="미완료" data-en="Incomplete">미완료</button>
+        <button class="erp-btn erp-btn-outline" data-filter="label_attached" type="button" data-ko="라벨부착" data-en="Label Attached">라벨부착</button>
+        <button class="erp-btn erp-btn-outline" data-filter="handed_to_kagayaku" type="button" data-ko="Kagayaku 전달" data-en="Kagayaku Handover">Kagayaku 전달</button>
+      </div>
+      <input class="erp-input dsp-search" id="dsp-search" type="search"
+             data-ko-ph="검색: Order ID / Tracking ID / 받는 사람 / SKU"
+             data-en-ph="Search: Order ID / Tracking ID / Recipient / SKU"
+             placeholder="검색: Order ID / Tracking ID / 받는 사람 / SKU" />
+      <div class="dsp-bulk">
+        <button class="dsp-btn-status" type="button" data-bulk="label_attached" onclick="dspBulk(this,'label_attached')"
+                data-ko="모두 라벨 부착" data-en="Label All">모두 라벨 부착</button>
+        <button class="dsp-btn-status" type="button" data-bulk="handed_to_kagayaku" onclick="dspBulk(this,'handed_to_kagayaku')"
+                data-ko="모두 Kagayaku 전달" data-en="Handover All">모두 Kagayaku 전달</button>
+      </div>
+    </div>
+
+    <div class="dsp-cards" id="dsp-cards">
+      {% for p in parcels %}
+      {% set is_done = p.label_attached and p.handed_to_kagayaku %}
+      <article class="dsp-card {% if is_done %}is-done{% endif %}"
+               data-parcel="{{ p.id }}"
+               data-label_attached="{{ p.label_attached|lower }}"
+               data-handed_to_kagayaku="{{ p.handed_to_kagayaku|lower }}"
+               data-search="{{ (p.order_id ~ ' ' ~ p.tracking_id ~ ' ' ~ p.recipient_name ~ ' ' ~ (p['items']|map(attribute='seller_sku')|join(' ')))|lower }}">
+        {% set logo = p.shipping_provider | courier_logo %}
+        {% if logo %}
+        <img class="dsp-courier" src="{{ logo }}" alt="{{ p.shipping_provider }}" title="{{ p.shipping_provider }}" />
+        {% elif p.shipping_provider %}
+        <span class="dsp-courier-text erp-badge">{{ p.shipping_provider }}</span>
+        {% endif %}
+        <div class="dsp-no">No. {{ p.seq }}</div>
+        {% if p.order_id %}
+        <div class="dsp-order"><b>Order ID</b><span>{{ p.order_id }}</span></div>
+        {% endif %}
+        {% if p.tracking_id %}
+        <div class="dsp-meta">
+          <div><b>Tracking</b>
+            {% set turl = p.tracking_id | courier_track(p.shipping_provider) %}
+            {% if turl %}<a class="dsp-track-link" href="{{ turl }}" target="_blank" rel="noopener noreferrer">{{ p.tracking_id }}</a>
+            {% else %}{{ p.tracking_id }}{% endif %}
+          </div>
+        </div>
+        {% endif %}
+        <div class="dsp-recipient">
+          <span class="dsp-rname">{{ p.recipient_name or '—' }}</span>
+          {% if p.recipient_address %}<div class="dsp-raddr">{{ p.recipient_address }}</div>{% endif %}
+          {% if p.recipient_phone %}<div class="dsp-rphone">{{ p.recipient_phone }}</div>{% endif %}
+        </div>
+        <ul class="dsp-items">
+          {% for it in p['items'] %}
+          <li>{% if batch.platform == 'Manual' %}{{ it.product_name or it.seller_sku }}{% else %}{{ it.seller_sku }}{% endif %} <span class="qty">× {{ it.quantity }}</span></li>
+          {% else %}
+          <li class="erp-muted" style="font-weight:400;" data-ko="상품 없음" data-en="No items">상품 없음</li>
+          {% endfor %}
+        </ul>
+        <div class="dsp-status">
+          {% for field in status_fields %}
+          <button type="button"
+                  class="dsp-btn-status {% if (field == status_fields[-1]) and (status_fields|length % 2 == 1) %}full{% endif %} {% if p[field] %}on{% endif %}"
+                  data-field="{{ field }}"
+                  onclick="dspToggle(this)">
+            {{ status_labels[field].ko }}
+            <small>{{ status_labels[field].en }}</small>
+          </button>
+          {% endfor %}
+        </div>
+      </article>
+      {% endfor %}
+      {% if not parcels %}
+      <p class="erp-muted">이 배치에는 박스가 없습니다.</p>
+      {% endif %}
+    </div>
+  </div>
+</section>
+{% endblock %}
+
+{% block scripts %}
+<script>
+(function () {
+  var STATUS_FIELDS = {{ status_fields|list|tojson }};
+  var BATCH_ID = document.querySelector('.dsp').getAttribute('data-batch');
+
+  // ── 일괄 토글 처리 (전부 완료면 해제, 아니면 완료) ──
+  var BULK_LABELS = {
+    ko: { label_attached: '라벨 부착', handed_to_kagayaku: 'Kagayaku 전달' },
+    en: { label_attached: 'Label Attached', handed_to_kagayaku: 'Kagayaku Handover' },
+  };
+
+  function allOn(field) {
+    var cards = document.querySelectorAll('.dsp-card');
+    if (!cards.length) return false;
+    return Array.prototype.every.call(cards, function (c) {
+      return c.getAttribute('data-' + field) === 'true';
+    });
+  }
+
+  // 버튼 상태(초록/외곽선) 동기화. 전부 완료면 on.
+  function refreshBulkButtons() {
+    document.querySelectorAll('.dsp-bulk [data-bulk]').forEach(function (btn) {
+      btn.classList.toggle('on', allOn(btn.getAttribute('data-bulk')));
+    });
+  }
+
+  window.dspBulk = function (btn, field) {
+    var target = !allOn(field);  // 전부 완료면 해제, 아니면 완료
+    var en = (window.dspLang && window.dspLang() === 'en');
+    var label = BULK_LABELS[en ? 'en' : 'ko'][field] || field;
+    var msg = en
+      ? ('Set ALL boxes "' + label + '" to ' + (target ? 'done' : 'not done') + '?')
+      : ('이 배치의 모든 박스를 "' + label + '" ' + (target ? '완료로 표시' : '완료 해제') + '할까요?');
+    if (!confirm(msg)) return;
+    document.querySelectorAll('.dsp-bulk button').forEach(function (b) { b.disabled = true; });
+    var body = new URLSearchParams();
+    body.set('field', field);
+    body.set('value', target ? 'true' : 'false');
+    fetch('/dispatch/batches/' + BATCH_ID + '/bulk', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+    })
+      .then(function (r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json(); })
+      .then(function () { location.reload(); })
+      .catch(function () {
+        alert('일괄 처리에 실패했습니다. 다시 시도하세요.');
+        document.querySelectorAll('.dsp-bulk button').forEach(function (b) { b.disabled = false; });
+      });
+  };
+
+  // ── 상태 토글 (즉시 DB 저장) ──
+  window.dspToggle = function (btn) {
+    var card = btn.closest('.dsp-card');
+    var parcelId = card.getAttribute('data-parcel');
+    var field = btn.getAttribute('data-field');
+    btn.disabled = true;
+    var body = new URLSearchParams();
+    body.set('field', field);
+    fetch('/dispatch/parcels/' + parcelId + '/toggle', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: body.toString(),
+    })
+      .then(function (r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json(); })
+      .then(function (data) {
+        btn.classList.toggle('on', data.value);
+        card.setAttribute('data-' + field, data.value ? 'true' : 'false');
+        refreshDone(card);
+        applyFilter();
+      })
+      .catch(function () { alert('저장에 실패했습니다. 다시 시도하세요.'); })
+      .finally(function () { btn.disabled = false; });
+  };
+
+  function refreshDone(card) {
+    var done = STATUS_FIELDS.every(function (f) {
+      return card.getAttribute('data-' + f) === 'true';
+    });
+    card.classList.toggle('is-done', done);
+    updateDoneLabel();
+    refreshBulkButtons();
+  }
+
+  function updateDoneLabel() {
+    var cards = document.querySelectorAll('.dsp-card');
+    var done = document.querySelectorAll('.dsp-card.is-done').length;
+    var label = document.getElementById('dsp-done-label');
+    if (!label) return;
+    label.setAttribute('data-done', done);
+    label.setAttribute('data-total', cards.length);
+    var prefix = (window.dspLang && window.dspLang() === 'en') ? 'Done ' : '완료 ';
+    label.textContent = prefix + done + ' / ' + cards.length;
+  }
+
+  // 언어 변경 시 동적 라벨(완료 N/M) 다시 그림.
+  document.addEventListener('dsp:lang', updateDoneLabel);
+
+  // ── 필터 ──
+  var currentFilter = 'all';
+  function matchesFilter(card) {
+    switch (currentFilter) {
+      case 'all': return true;
+      case 'incomplete':
+        return !STATUS_FIELDS.every(function (f) {
+          return card.getAttribute('data-' + f) === 'true';
+        });
+      default: return card.getAttribute('data-' + currentFilter) === 'true';
+    }
+  }
+
+  function applyFilter() {
+    var term = (document.getElementById('dsp-search').value || '').trim().toLowerCase();
+    document.querySelectorAll('.dsp-card').forEach(function (card) {
+      var ok = matchesFilter(card) &&
+        (term === '' || (card.getAttribute('data-search') || '').indexOf(term) !== -1);
+      card.classList.toggle('dsp-hidden', !ok);
+    });
+  }
+
+  document.getElementById('dsp-filter').addEventListener('click', function (e) {
+    var btn = e.target.closest('[data-filter]');
+    if (!btn) return;
+    currentFilter = btn.getAttribute('data-filter');
+    this.querySelectorAll('[data-filter]').forEach(function (b) {
+      b.classList.toggle('erp-btn-primary', b === btn);
+      b.classList.toggle('erp-btn-outline', b !== btn);
+    });
+    applyFilter();
+  });
+
+  document.getElementById('dsp-search').addEventListener('input', applyFilter);
+
+  refreshBulkButtons();  // 초기 버튼 상태(전부 완료면 초록)
+})();
+</script>
+{% endblock %}

app/modules/dispatch/templates/dispatch/handover.html

@@ -0,0 +1,81 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<style>
+  .dsp-ho-grid { display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));gap:12px;margin:12px 0; }
+  .dsp-ho-stat { border:1px solid #e2e8f0;border-radius:10px;padding:12px;text-align:center;background:#fff; }
+  .dsp-ho-stat .n { font-size:26px;font-weight:700;color:#0f172a; }
+  .dsp-ho-stat .l { font-size:13px;color:#64748b; }
+  .dsp-track td { font-family:ui-monospace,SFMono-Regular,Menlo,monospace;white-space:nowrap; }
+  @media print {
+    .erp-sidebar, .erp-topbar, .erp-page-actions, .dsp-noprint { display:none !important; }
+    .erp-content, .erp-page, .erp-app { margin:0 !important;padding:0 !important;display:block !important; }
+    .erp-card { border:none !important;box-shadow:none !important;padding:0 !important; }
+    body { background:#fff !important; }
+    .dsp-print-head { display:block !important; }
+    @page { size:A4;margin:14mm; }
+  }
+  .dsp-print-head { display:none; }
+</style>
+{% endblock %}
+
+{% block content %}
+<section class="dsp">
+  {% include "dispatch/_nav.html" %}
+
+  <div class="dsp-noprint" style="margin:8px 0;">
+    <button class="erp-btn erp-btn-primary" type="button" onclick="window.print()" data-ko="🖨 인쇄하기" data-en="🖨 Print">🖨 인쇄하기</button>
+  </div>
+
+  <div class="erp-card">
+    <div class="dsp-print-head" style="margin-bottom:10px;">
+      <h2 style="margin:0;" data-ko="Kagayaku 전달 리스트" data-en="Kagayaku Handover List">Kagayaku 전달 리스트</h2>
+    </div>
+    <div class="cpg-card-head">
+      <h2 data-raw="{{ batch.batch_name or 'TikTok 출고' }}">{{ batch.batch_name or 'TikTok 출고' }}</h2>
+    </div>
+    <p class="erp-muted" style="margin:4px 0 4px;">
+      <span data-ko="날짜" data-en="Date">날짜</span> <b>{{ batch.dispatch_date }}</b> ·
+      <span data-ko="플랫폼" data-en="Platform">플랫폼</span> <b>{{ batch.platform }}</b>
+    </p>
+
+    <div class="dsp-ho-grid">
+      <div class="dsp-ho-stat">
+        <div class="n">{{ handover.total_boxes }}</div>
+        <div class="l" data-ko="총 박스 수" data-en="Total Boxes">총 박스 수</div>
+      </div>
+      {% for pv in handover.by_provider %}
+      <div class="dsp-ho-stat">
+        {% set logo = pv.provider | courier_logo %}
+        {% if logo %}<img src="{{ logo }}" alt="{{ pv.provider }}" style="height:40px;width:auto;max-width:260px;margin:0 auto 4px;display:block;" />{% endif %}
+        <div class="n">{{ pv.box_count }}</div>
+        <div class="l">{{ pv.provider }}</div>
+      </div>
+      {% endfor %}
+    </div>
+
+    <h3 style="margin:16px 0 8px;"><span data-ko="Tracking ID 목록" data-en="Tracking ID List">Tracking ID 목록</span> ({{ handover.tracking_list|length }})</h3>
+    <div class="erp-table-wrap">
+      <table class="erp-table dsp-track">
+        <thead>
+          <tr><th style="text-align:right">No</th><th>Tracking ID</th>
+              <th data-ko="배송사" data-en="Courier">배송사</th><th>Order ID</th></tr>
+        </thead>
+        <tbody>
+          {% for t in handover.tracking_list %}
+          <tr>
+            <td style="text-align:right">{{ t.seq }}</td>
+            <td>{{ t.tracking_id or '—' }}</td>
+            <td>{{ t.shipping_provider or '—' }}</td>
+            <td>{{ t.order_id or '—' }}</td>
+          </tr>
+          {% endfor %}
+          {% if not handover.tracking_list %}
+          <tr><td colspan="4" class="erp-muted" data-ko="전달할 박스가 없습니다." data-en="No boxes to hand over.">전달할 박스가 없습니다.</td></tr>
+          {% endif %}
+        </tbody>
+      </table>
+    </div>
+  </div>
+</section>
+{% endblock %}

app/modules/dispatch/templates/dispatch/new.html

@@ -0,0 +1,109 @@
+{% extends "erp_base.html" %}
+
+{% block content %}
+<section class="dsp">
+  {% include "dispatch/_nav.html" %}
+
+  <div class="erp-card" style="max-width:640px;">
+    <div class="cpg-card-head"><h2 data-ko="출고 파일 업로드" data-en="Upload Dispatch Files">출고 파일 업로드</h2></div>
+    <p class="erp-muted" id="dsp-intro" style="margin:4px 0 16px;"></p>
+
+    <form method="post" action="/dispatch/batches" enctype="multipart/form-data" style="display:flex;flex-direction:column;gap:14px;">
+      <label style="display:flex;flex-direction:column;gap:4px;">
+        <span><span data-ko="출고 날짜" data-en="Dispatch Date">출고 날짜</span> <span style="color:#dc2626;">*</span></span>
+        <input class="erp-input" type="date" name="dispatch_date" value="{{ today }}" required />
+      </label>
+
+      <label style="display:flex;flex-direction:column;gap:4px;">
+        <span data-ko="플랫폼" data-en="Platform">플랫폼</span>
+        <select class="erp-select" name="platform" id="dsp-platform">
+          {% for pf in platforms %}
+          <option value="{{ pf }}">{{ pf }}</option>
+          {% endfor %}
+        </select>
+      </label>
+
+      <label style="display:flex;flex-direction:column;gap:4px;">
+        <span><span data-ko="배치명" data-en="Batch name">배치명</span>
+          <span class="erp-muted" data-ko="(예: 2026-06-19 오전 출고)" data-en="(e.g. 2026-06-19 AM)">(예: 2026-06-19 오전 출고)</span></span>
+        <input class="erp-input" type="text" name="batch_name"
+               data-ko-ph="오전 출고 / 오후 출고 등으로 구분" data-en-ph="e.g. AM dispatch / PM dispatch"
+               placeholder="오전 출고 / 오후 출고 등으로 구분" />
+      </label>
+
+      <label id="dsp-label-row" style="display:flex;flex-direction:column;gap:4px;">
+        <span id="dsp-label-lbl"></span>
+        <input class="erp-input" type="file" name="label_pdf" id="dsp-label" accept="application/pdf" />
+      </label>
+
+      <label style="display:flex;flex-direction:column;gap:4px;">
+        <span id="dsp-data-lbl"></span>
+        <input class="erp-input" type="file" name="data_xlsx" id="dsp-data"
+               accept="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" required />
+      </label>
+
+      <div style="display:flex;gap:8px;margin-top:8px;">
+        <button class="erp-btn erp-btn-primary" type="submit" data-ko="업로드 후 배치 생성" data-en="Upload &amp; Create">업로드 후 배치 생성</button>
+        <a class="erp-btn erp-btn-outline" href="/dispatch/" data-ko="취소" data-en="Cancel">취소</a>
+      </div>
+    </form>
+  </div>
+</section>
+{% endblock %}
+
+{% block scripts %}
+<script>
+(function () {
+  // 플랫폼별 안내/파일 라벨(한/영). 데이터 엑셀 필수, 라벨 PDF 선택(보관·PII 추출용).
+  var CFG = {
+    ko: {
+      "TikTok": {
+        intro: "TikTok: Order Export.xlsx 로 출고 리스트가 생성됩니다. 받는 사람 이름/주소는 라벨 PDF 에서 가져오니 PDF 도 함께 올리세요.",
+        label: "📄 Shipping label + Packing slip.pdf <span class='erp-muted'>(받는 사람 이름/주소 추출 · 권장)</span>",
+        data:  "📊 TikTok Order Export.xlsx <span style='color:#dc2626;'>*</span> <span class='erp-muted'>(자동 출고 리스트 기준)</span>"
+      },
+      "Shopee": {
+        intro: "Shopee: Packing List.Doorstep Delivery.xlsx 로 출고 리스트가 생성됩니다. 받는 사람 이름/주소는 Shopee Seller Centre.pdf 에서 가져오니 PDF 도 함께 올리세요.",
+        label: "📄 Shopee Seller Centre.pdf <span class='erp-muted'>(받는 사람 이름/주소 추출 · 권장)</span>",
+        data:  "📊 Packing List.Doorstep Delivery.xlsx <span style='color:#dc2626;'>*</span> <span class='erp-muted'>(자동 출고 리스트 기준)</span>"
+      },
+      "Manual": {
+        intro: "메뉴얼 오더: 엑셀 파일만 올리세요. 첫 시트의 받는 사람/전화/주소/상품/수량을 읽어 출고 리스트를 만듭니다(PDF 불필요).",
+        label: "",
+        data:  "📊 Manual Order.xlsx <span style='color:#dc2626;'>*</span> <span class='erp-muted'>(받는사람·상품·수량 포함)</span>"
+      }
+    },
+    en: {
+      "TikTok": {
+        intro: "TikTok: the dispatch list is built from Order Export.xlsx. Recipient name/address come from the label PDF, so please upload the PDF too.",
+        label: "📄 Shipping label + Packing slip.pdf <span class='erp-muted'>(recipient name/address · recommended)</span>",
+        data:  "📊 TikTok Order Export.xlsx <span style='color:#dc2626;'>*</span> <span class='erp-muted'>(dispatch list source)</span>"
+      },
+      "Shopee": {
+        intro: "Shopee: the dispatch list is built from Packing List.Doorstep Delivery.xlsx. Recipient name/address come from Shopee Seller Centre.pdf, so please upload the PDF too.",
+        label: "📄 Shopee Seller Centre.pdf <span class='erp-muted'>(recipient name/address · recommended)</span>",
+        data:  "📊 Packing List.Doorstep Delivery.xlsx <span style='color:#dc2626;'>*</span> <span class='erp-muted'>(dispatch list source)</span>"
+      },
+      "Manual": {
+        intro: "Manual order: upload the Excel file only. Recipient/phone/address/product/qty are read from the first sheet (no PDF needed).",
+        label: "",
+        data:  "📊 Manual Order.xlsx <span style='color:#dc2626;'>*</span> <span class='erp-muted'>(includes recipient, product, qty)</span>"
+      }
+    }
+  };
+  var sel = document.getElementById('dsp-platform');
+  function apply() {
+    var lang = (window.dspLang && window.dspLang() === 'en') ? 'en' : 'ko';
+    var c = (CFG[lang] && CFG[lang][sel.value]) || CFG[lang]["TikTok"];
+    document.getElementById('dsp-intro').textContent = c.intro;
+    document.getElementById('dsp-label-lbl').innerHTML = c.label;
+    document.getElementById('dsp-data-lbl').innerHTML = c.data;
+    // 라벨(PDF) 슬롯이 없는 플랫폼(Manual)은 라벨 업로드 칸을 숨긴다.
+    document.getElementById('dsp-label-row').style.display = c.label ? '' : 'none';
+  }
+  sel.addEventListener('change', apply);
+  document.addEventListener('dsp:lang', apply);  // 언어 토글 시 재적용
+  apply();
+})();
+</script>
+{% endblock %}

app/modules/dispatch/templates/dispatch/picking.html

@@ -0,0 +1,43 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<style>
+  .dsp-pick td.sku { font-size:18px;font-weight:700;color:#0f172a;white-space:nowrap; }
+  .dsp-pick td.qty { font-size:18px;font-weight:700;text-align:right;color:#2563eb;white-space:nowrap; }
+</style>
+{% endblock %}
+
+{% block content %}
+<section class="dsp">
+  {% include "dispatch/_nav.html" %}
+
+  <div class="erp-card" style="max-width:560px;">
+    <div class="cpg-card-head" style="display:flex;justify-content:space-between;align-items:center;">
+      <h2 data-ko="피킹 요약 (SKU별 총 수량)" data-en="Picking Summary (total qty by SKU)">피킹 요약 (SKU별 총 수량)</h2>
+      <span class="erp-muted"><span data-ko="총" data-en="Total">총</span> {{ total_qty }} · {{ summary|length }} SKU</span>
+    </div>
+    <p class="erp-muted" style="margin:4px 0 12px;" data-ko="이 화면을 보고 먼저 전체 상품을 꺼내세요."
+       data-en="Pick all items first using this list.">이 화면을 보고 먼저 전체 상품을 꺼내세요.</p>
+    <div class="erp-table-wrap">
+      <table class="erp-table dsp-pick">
+        <thead>
+          <tr><th>Seller SKU</th><th data-ko="상품명" data-en="Product">상품명</th>
+              <th style="text-align:right" data-ko="수량" data-en="Qty">수량</th></tr>
+        </thead>
+        <tbody>
+          {% for r in summary %}
+          <tr>
+            <td class="sku">{{ r.seller_sku }}</td>
+            <td class="erp-muted">{{ r.product_name or '—' }}</td>
+            <td class="qty">{{ r.total_qty }}</td>
+          </tr>
+          {% endfor %}
+          {% if not summary %}
+          <tr><td colspan="3" class="erp-muted" data-ko="피킹할 상품이 없습니다." data-en="No items to pick.">피킹할 상품이 없습니다.</td></tr>
+          {% endif %}
+        </tbody>
+      </table>
+    </div>
+  </div>
+</section>
+{% endblock %}

app/modules/dispatch/tests/test_grouping.py

@@ -0,0 +1,121 @@
+"""dispatch 모듈 박스 묶기/SKU 합산 순수 로직 테스트.
+
+DB/엑셀 없이 store.py 의 규칙만 검증한다.
+    python -m app.modules.dispatch.tests.test_grouping
+또는 pytest 로 실행 가능.
+"""
+
+from __future__ import annotations
+
+from app.modules.dispatch import store
+
+
+def test_package_id_priority():
+    """묶음키 우선순위: package_id > tracking_id > order_id."""
+    rows = [
+        {"order_id": "O1", "package_id": "P1", "tracking_id": "T1", "seller_sku": "MT-0320", "quantity": "1"},
+        {"order_id": "O1", "package_id": "P1", "tracking_id": "T1", "seller_sku": "MT-0320", "quantity": "1"},
+        {"order_id": "O1", "package_id": "P2", "tracking_id": "T2", "seller_sku": "MY-0001", "quantity": "1"},
+    ]
+    parcels = store.group_parcels(rows)
+    assert len(parcels) == 2, parcels  # P1, P2 → 박스 2개
+    p1 = next(p for p in parcels if p["package_id"] == "P1")
+    # 같은 박스 같은 SKU 수량 합산 → 2
+    assert p1["items"][0]["quantity"] == 2, p1
+
+
+def test_tracking_then_order_fallback():
+    """package_id 없으면 tracking_id, 그것도 없으면 order_id 로 묶는다."""
+    rows = [
+        {"order_id": "O9", "package_id": "", "tracking_id": "TRK", "seller_sku": "MT-0550", "quantity": ""},
+        {"order_id": "O9", "package_id": "", "tracking_id": "TRK", "seller_sku": "MX-0001", "quantity": "3"},
+        {"order_id": "O8", "package_id": "", "tracking_id": "", "seller_sku": "MT-0750", "quantity": "2"},
+    ]
+    parcels = store.group_parcels(rows)
+    assert len(parcels) == 2, parcels
+    trk = next(p for p in parcels if p["tracking_id"] == "TRK")
+    assert len(trk["items"]) == 2  # 다른 SKU 2종
+    # quantity 빈칸 → 1 로 보정
+    qty_by_sku = {it["seller_sku"]: it["quantity"] for it in trk["items"]}
+    assert qty_by_sku["MT-0550"] == 1
+    assert qty_by_sku["MX-0001"] == 3
+
+
+def test_quantity_and_tracking_preserved_as_string():
+    """수량 비면 1, 송장번호 숫자로 들어와도 문자열 보존."""
+    assert store.normalize_quantity("") == 1
+    assert store.normalize_quantity(None) == 1
+    assert store.normalize_quantity("0") == 1
+    assert store.normalize_quantity("5") == 5
+    # 큰 송장번호가 float 로 읽혀도 과학표기/.0 없이 보존
+    assert store.clean_text(12345678901.0) == "12345678901"
+    assert store.clean_text(float("nan")) == ""
+
+
+def test_sku_summary():
+    rows = [
+        {"order_id": "A", "package_id": "PA", "tracking_id": "", "seller_sku": "MT-0320_3", "quantity": "1"},
+        {"order_id": "B", "package_id": "PB", "tracking_id": "", "seller_sku": "MT-0320_3", "quantity": "1"},
+        {"order_id": "C", "package_id": "PC", "tracking_id": "", "seller_sku": "MY-0001", "quantity": "5"},
+    ]
+    parcels = store.group_parcels(rows)
+    summary = store.sku_summary(parcels)
+    totals = {r["seller_sku"]: r["total_qty"] for r in summary}
+    assert totals == {"MT-0320_3": 2, "MY-0001": 5}, totals
+
+
+def test_missing_required_columns():
+    """필수 컬럼 누락 감지: seller_sku 없거나 묶음키 전무."""
+    mapping = store.resolve_columns(["Order ID", "Product Name", "Quantity"])
+    missing = store.missing_required(mapping)
+    assert any("Seller SKU" in m for m in missing), missing
+    # 묶음키(order id) 는 있으므로 그 누락 메시지는 없어야 함
+    assert not any("최소 1개" in m for m in missing), missing
+
+
+def test_column_alias_strip_and_case():
+    """헤더 앞뒤 공백/대소문자 무시하고 매핑."""
+    mapping = store.resolve_columns(["  Order ID  ", "TRACKING ID", "Seller SKU", "Quantity"])
+    assert "order_id" in mapping
+    assert "tracking_id" in mapping
+    assert "seller_sku" in mapping
+
+
+def test_shopee_product_info_single():
+    blob = ("[1] Product Name:[1+1=3] Mira's Kitchen Korean Grade Miracle Food "
+            "Container Launch PROMO; Variation Name:3x 320ml; Price: RM 20.00; "
+            "Quantity: 1; SKU Reference No.: MT-0320_3;")
+    items = store.parse_shopee_product_info(blob)
+    assert len(items) == 1, items
+    it = items[0]
+    assert it["seller_sku"] == "MT-0320_3", it
+    assert it["quantity"] == 1, it
+    assert it["variation"] == "3x 320ml", it
+    assert "Mira's Kitchen" in it["product_name"], it
+
+
+def test_shopee_product_info_multi():
+    blob = ("[1] Product Name:Item A; Variation Name:S; Quantity: 2; "
+            "SKU Reference No.: MT-0001; "
+            "[2] Product Name:Item B; Variation Name:L; Quantity: 3; "
+            "SKU Reference No.: MX-0002;")
+    items = store.parse_shopee_product_info(blob)
+    skus = {i["seller_sku"]: i["quantity"] for i in items}
+    assert skus == {"MT-0001": 2, "MX-0002": 3}, skus
+
+
+def test_shopee_product_info_empty():
+    assert store.parse_shopee_product_info("") == []
+    assert store.parse_shopee_product_info(None) == []
+
+
+def _run_all():
+    fns = [v for k, v in sorted(globals().items()) if k.startswith("test_") and callable(v)]
+    for fn in fns:
+        fn()
+        print("PASS", fn.__name__)
+    print(f"\n{len(fns)} tests passed.")
+
+
+if __name__ == "__main__":
+    _run_all()

app/modules/malaysia/README.md

@@ -0,0 +1,120 @@
+# 말레이시아 창고 재고관리 모듈 (`malaysia`)
+
+말레이시아 현지 창고의 입고/출고/조정과 세트 BOM, 일일 재고조사를 관리한다.
+cupang 모듈과 동일한 패턴: **malaysia_stock_db(PostgreSQL) 전용**, JSON 폴백 없음.
+상품명은 기존 `itemcode_db`(읽기 전용)을 재사용한다.
+
+- 경로(prefix): `/malaysia`
+- 권한키: `malaysia` (admin 은 항상 통과)
+- 환경변수: `MALAYSIA_STOCK_DB_URL` (미설정 시 "설정 필요" 안내), `ITEMCODE_DB_URL`(세트 BOM/이름)
+- DB: `malaysia_stock_db` / 역할 `malaysia_app`
+
+> **세트 구성(BOM)은 별도 관리하지 않는다.** itemcode_db `set_components`
+> (set_code / single_code / quantity)에서 읽는다. 모듈 안에 세트구성 메뉴 없음.
+> `malaysia_stock_db.set_bom` 테이블은 더 이상 쓰지 않는다(레거시, 무시).
+> 입출고·재고조사는 전체 아이템(+세트) 그리드에 **수량만 키인**해 일괄 등록한다.
+
+---
+
+## 재고 원칙
+
+- **입고/출고/조정은 낱개 아이템(MT-/MX-/MZ-) 기준**으로만 movement 저장.
+- **세트(MY-)는 movement 불가.** 세트는 ① 재고조사 입력, ② BOM 구성 계산에만 사용.
+- 세트 주문 출고는 `set_bom` 으로 분해해 구성품별 `OUT` movement 를 생성(`/malaysia/movements/set-out`).
+- 뚜껑(MD-)은 재고관리 대상에서 **완전 제외**(어디에도 사용 불가).
+
+### 현재고 계산
+
+```
+현재고 = SUM(IN) - SUM(OUT) + SUM(ADJUST) + SUM(STOCKTAKE)
+```
+
+- `IN`/`OUT` qty 는 양수만. `ADJUST`/`STOCKTAKE` 는 음수(±) 허용.
+- 재고조사 확정 시 **시스템 재고와 조사 최종치의 "차이"만** `STOCKTAKE` movement 로 기록 → 이력 보존 + 계산 단순.
+
+### 일일 재고조사 집계
+
+```
+낱개 최종 재고(total_qty)
+  = direct_qty(낱개 직접 조사)
+  + from_set_qty(세트 수량을 set_bom 으로 분해한 합)
+```
+
+예) `MT-0320` 낱개 100 + `MY-0002`(MT-0320 1개 포함) 20세트 → `MT-0320` total = **120**.
+> 낱개 입력 시 **세트 안에 든 건 빼고** 낱개 보관분만 입력한다. 세트 안 상품은 BOM 으로 자동 계산.
+
+### 랙(rack) 입력 — 재고조사 상세
+
+재고조사 상세는 평면 수량 그리드 대신 **창고 랙 그림(A/B 두 면, 각 3행×3열×2분할 = 36칸)**
+으로 입력한다. 각 칸에 `아이템 · 박스당 입수량 · 박스 수`를 넣고, 한 칸에 여러 아이템은
+`+` 로 행을 추가한다. 저장하면 서버가 SKU별로
+
+```
+qty = SUM(units_per_box × box_count)
+```
+
+집계해 `daily_stocktake_line`을 **재생성**한다(랙이 라인의 단일 출처). 낱개·콤보(MY-)
+모두 랙에 입력 가능하며, 이후 분해/확정 로직(`compute_result`/`finalize`)은 라인 기준으로
+기존과 동일하게 동작한다. 칸 코드 형식: `{면}{행}-{열}-{분할}` (예 `A3-1-1`).
+
+---
+
+## 테이블 (`scripts/sql/malaysia_stock_db_init.sql`)
+
+| 테이블 | 용도 |
+| --- | --- |
+| `warehouses` | 창고. seed: `MY-WH-01 / Malaysia Warehouse` |
+| `malaysia_items` | 관리 대상 코드 스코프(낱개/세트) + 이름 스냅샷. seed: 낱개 12 + 세트 5 |
+| `set_bom` | 세트 구성표. `UNIQUE(set_code, component_code)`. prefix CHECK 내장 |
+| `stock_movement` | 입고/출고/조정/조사 이력. `item_code` 는 낱개만(CHECK) |
+| `daily_stocktake` | 재고조사 헤더. 같은 날짜+창고 finalized 1건(부분 유니크) |
+| `daily_stocktake_line` | 조사 라인(SKU별 최종 qty). 랙 입력 집계로 **재생성**됨. `UNIQUE(stocktake_id, sku_code)` |
+| `daily_stocktake_rack` | 랙 칸별 입력(셀×SKU×입수량×박스수). 라인의 단일 출처. `cell_code` 예 `A3-1-1` |
+
+검증 규칙(요구사항 8)은 **DB CHECK + 서비스 레이어(`store.py`)** 양쪽에 걸려 있다.
+
+---
+
+## 주요 화면 / API
+
+화면: `/malaysia/`(재고 현황) · `/malaysia/movements`(입출고) · `/malaysia/stocktakes`(재고조사) · `/malaysia/sets`(세트 구성)
+
+JSON API:
+
+| Method | 경로 | 설명 |
+| --- | --- | --- |
+| GET | `/malaysia/api/warehouses` | 창고 목록 |
+| GET | `/malaysia/api/items?kind=individual\|set` | 아이템 목록 |
+| GET/POST | `/malaysia/api/bom` | 세트 구성 조회/등록 |
+| GET | `/malaysia/api/stock?wh=` | 현재고 현황 |
+| POST | `/malaysia/api/movements` | 낱개 movement 등록 |
+| POST | `/malaysia/api/movements/set-out` | 세트 출고(BOM 분해) |
+| GET | `/malaysia/api/stocktakes/{id}/result` | 재고조사 최종 계산 |
+| POST | `/malaysia/stocktakes/{id}/rack/bulk` | 랙 입력 일괄 저장(병렬배열 `rk_cell/rk_sku/rk_upb/rk_box`) → 라인 재생성 |
+
+---
+
+## 초기화 (운영, 1회 — 사용자 승인 후)
+
+```bash
+read -s -p "malaysia_app password: " APP_PWD; echo
+docker exec -i postgres-db psql -U postgres \
+  -v app_password="$APP_PWD" \
+  < scripts/sql/malaysia_stock_db_init.sql
+
+# main-app .env 에 추가:
+#   MALAYSIA_STOCK_DB_URL=postgresql://malaysia_app:<APP_PWD>@postgres-db:5432/malaysia_stock_db
+cd /opt/www/main && docker compose up -d --build
+```
+
+> 멱등 스크립트. 기존 DB 가 있으면 DROP 하지 않음. itemcode_db 는 건드리지 않음.
+> **랙 입력 추가(`daily_stocktake_rack`)** 후 기존 운영 DB 에 반영하려면 위 init 스크립트를
+> 그대로 1회 재실행한다(`CREATE TABLE IF NOT EXISTS` + grant 만 적용, 기존 데이터 보존).
+
+## 테스트
+
+```bash
+python -m pytest tests/test_malaysia_stock.py -v   # pytest 있으면
+python tests/test_malaysia_stock.py                # 없으면 standalone 폴백
+```
+순수 로직(코드 검증 / 세트 분해 / 재고조사 집계)만 검증하므로 DB 불필요.

app/modules/malaysia/__init__.py

@@ -0,0 +1,55 @@
+"""말레이시아 창고 재고관리(malaysia) 모듈.
+
+라우터/저장소/템플릿을 한 디렉토리에서 관리한다.
+- 라우터: `router.py` (FastAPI APIRouter, prefix=/malaysia)
+- 저장소: `db.py` (malaysia_stock_db / PostgreSQL 전용) + `store.py` (상수/순수 계산)
+- 상품명: 전역 `app.state.itemcode_reader`(itemcode_db 읽기 전용) 재사용
+- 템플릿: `templates/malaysia/`
+
+데이터 저장은 malaysia_stock_db 전용이다. MALAYSIA_STOCK_DB_URL 미설정 시
+build_malaysia_store 는 None 을 반환하고, 라우터가 "설정 필요" 안내 페이지를
+보여준다(앱은 죽지 않음).
+"""
+
+from typing import Any
+
+from . import store
+from .router import router
+from .store import (
+    MOVEMENT_TYPES,
+    STOCKTAKE_STATUSES,
+    explode_set,
+    explode_stocktake,
+    missing_bom_sets,
+)
+
+__all__ = [
+    "router",
+    "store",
+    "MOVEMENT_TYPES",
+    "STOCKTAKE_STATUSES",
+    "explode_set",
+    "explode_stocktake",
+    "missing_bom_sets",
+    "build_malaysia_store",
+    "build_malaysia_itemcode",
+]
+
+
+def build_malaysia_store(*, dsn: str | None) -> Any:
+    """MALAYSIA_STOCK_DB_URL 이 있으면 MalaysiaStockStore, 없으면 None.
+
+    JSON 폴백을 두지 않는다(운영 데이터 분기 방지). None 이면 라우터가 안내 페이지 표시.
+    """
+    if not dsn:
+        return None
+    from .db import MalaysiaStockStore  # 지연 import (개발 환경 deps 없을 수 있음)
+
+    return MalaysiaStockStore(dsn)
+
+
+def build_malaysia_itemcode() -> Any:
+    """itemcode_db 읽기 전용 세트 BOM 리더. ITEMCODE_DB_URL 없으면 비활성."""
+    from .itemcode import MalaysiaItemcodeReader  # 지연 import
+
+    return MalaysiaItemcodeReader()

app/modules/malaysia/db.py

@@ -0,0 +1,999 @@
+"""malaysia_stock_db PostgreSQL 저장소.
+
+- 드라이버: psycopg 3 (`psycopg[binary,pool]`) — cupang/expense 모듈과 동일 패턴.
+- 연결 정보: 환경변수 `MALAYSIA_STOCK_DB_URL`
+  (예: postgresql://malaysia_app:<pwd>@postgres-db:5432/malaysia_stock_db)
+- 스키마(테이블/인덱스/트리거/seed)는 앱이 만들지 않는다.
+  `scripts/sql/malaysia_stock_db_init.sql` 을 superuser 가 사전 적용한다.
+  앱 계정(malaysia_app)은 SELECT/INSERT/UPDATE/DELETE 권한만 받는다.
+- 연결 풀은 lazy open — 부팅 시 DB 가 잠시 끊겨도 컨테이너가 죽지 않게.
+
+재고 계산 / BOM 분해의 순수 로직은 `store.py` 에 있고, 여기서는 DB I/O 와
+조립만 담당한다(클라이언트 계산을 신뢰하지 않고 서버에서 재계산).
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date, datetime
+from typing import Any
+
+from psycopg.rows import dict_row
+from psycopg_pool import ConnectionPool
+
+from app.timezone import KST, now_kst
+
+from . import store
+
+logger = logging.getLogger("malaysia.db")
+
+
+class MalaysiaStockStore:
+    def __init__(self, dsn: str, *, min_size: int = 1, max_size: int = 5):
+        self._pool = ConnectionPool(
+            conninfo=dsn,
+            min_size=min_size,
+            max_size=max_size,
+            kwargs={"row_factory": dict_row, "autocommit": True},
+            open=False,
+        )
+        self._pool.open(wait=False)
+
+    def close(self) -> None:
+        self._pool.close()
+
+    # ════════════════════════════════════════════════════════════
+    # 창고 (warehouses)
+    # ════════════════════════════════════════════════════════════
+    def list_warehouses(self, *, include_inactive: bool = False) -> list[dict[str, Any]]:
+        where = "" if include_inactive else "WHERE active = TRUE"
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                f"SELECT * FROM warehouses {where} "
+                "ORDER BY active DESC, warehouse_code ASC"
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def get_warehouse(self, *, warehouse_code: str) -> dict[str, Any] | None:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT * FROM warehouses WHERE warehouse_code = %s",
+                (warehouse_code,),
+            ).fetchone()
+        return self._serialize(row) if row else None
+
+    def create_warehouse(
+        self, *, warehouse_code: str, warehouse_name: str, country: str = "MY"
+    ) -> dict[str, Any]:
+        code = (warehouse_code or "").strip()
+        name = (warehouse_name or "").strip()
+        if not code or not name:
+            raise ValueError("창고코드와 창고명은 필수입니다.")
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                """
+                INSERT INTO warehouses (warehouse_code, warehouse_name, country)
+                VALUES (%s, %s, %s)
+                ON CONFLICT (warehouse_code) DO UPDATE
+                   SET warehouse_name = EXCLUDED.warehouse_name,
+                       country        = EXCLUDED.country,
+                       active         = TRUE
+                RETURNING *
+                """,
+                (code, name, (country or "MY").strip()),
+            ).fetchone()
+        return self._serialize(row)
+
+    # ════════════════════════════════════════════════════════════
+    # 재고관리 대상 아이템 (malaysia_items)
+    # ════════════════════════════════════════════════════════════
+    def list_items(
+        self, *, kind: str | None = None, include_inactive: bool = False
+    ) -> list[dict[str, Any]]:
+        """kind: 'individual' | 'set' | None(전체)."""
+        clauses: list[str] = []
+        params: list[Any] = []
+        if not include_inactive:
+            clauses.append("active = TRUE")
+        if kind in ("individual", "set"):
+            clauses.append("kind = %s")
+            params.append(kind)
+        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                f"SELECT * FROM malaysia_items {where} "
+                "ORDER BY sort_order ASC, item_code ASC",
+                params,
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def item_name_map(self) -> dict[str, str]:
+        """item_code → item_name (이름 붙이기용)."""
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                "SELECT item_code, item_name FROM malaysia_items"
+            ).fetchall()
+        return {r["item_code"]: (r["item_name"] or r["item_code"]) for r in rows}
+
+    def upsert_item(
+        self, *, item_code: str, item_name: str, kind: str, sort_order: int = 0
+    ) -> dict[str, Any]:
+        code = store._norm(item_code)
+        name = (item_name or "").strip()
+        if kind not in ("individual", "set"):
+            raise ValueError("kind 는 'individual' 또는 'set' 이어야 합니다.")
+        # prefix 와 kind 정합성 검증
+        if kind == "individual" and not store.is_individual_code(code):
+            raise ValueError(f"낱개 아이템은 MT-/MX-/MZ- 만 가능합니다: {code}")
+        if kind == "set" and not store.is_set_code(code):
+            raise ValueError(f"세트 아이템은 MY- 만 가능합니다: {code}")
+        if store.is_blocked_code(code):
+            raise ValueError(f"뚜껑 코드(MD-)는 등록할 수 없습니다: {code}")
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                """
+                INSERT INTO malaysia_items (item_code, item_name, kind, sort_order)
+                VALUES (%s, %s, %s, %s)
+                ON CONFLICT (item_code) DO UPDATE
+                   SET item_name  = EXCLUDED.item_name,
+                       kind       = EXCLUDED.kind,
+                       sort_order = EXCLUDED.sort_order,
+                       active     = TRUE
+                RETURNING *
+                """,
+                (code, name or code, kind, sort_order),
+            ).fetchone()
+        return self._serialize(row)
+
+    def sync_item_names(self, name_lookup: dict[str, str]) -> int:
+        """itemcode_db 등 외부 소스에서 받은 {code: name} 으로 이름 갱신.
+
+        등록된 코드만 갱신(신규 추가 안 함). 반환: 갱신 건수.
+        """
+        updated = 0
+        with self._pool.connection() as conn:
+            for code, name in name_lookup.items():
+                if not code or not name:
+                    continue
+                cur = conn.execute(
+                    "UPDATE malaysia_items SET item_name = %s "
+                    "WHERE item_code = %s AND item_name <> %s",
+                    (name.strip(), store._norm(code), name.strip()),
+                )
+                updated += cur.rowcount or 0
+        return updated
+
+    # ════════════════════════════════════════════════════════════
+    # 세트 구성표 (BOM)
+    #   별도 테이블/메뉴를 두지 않고 itemcode_db(set_components)에서 읽는다.
+    #   라우터가 MalaysiaItemcodeReader.set_bom_map() 결과를 아래 메서드들에
+    #   bom_map 인자로 주입한다(cross-DB 조인 회피, store 는 DB I/O 만 담당).
+    # ════════════════════════════════════════════════════════════
+
+    # ════════════════════════════════════════════════════════════
+    # 재고 이동 (stock_movement)
+    # ════════════════════════════════════════════════════════════
+    def create_movement(
+        self,
+        *,
+        movement_date: str,
+        warehouse_code: str,
+        item_code: str,
+        movement_type: str,
+        qty: int,
+        ref_type: str = "",
+        ref_no: str = "",
+        memo: str = "",
+        created_by: str = "",
+    ) -> dict[str, Any]:
+        """단일 낱개 아이템 movement 1건 생성. 세트 코드는 차단."""
+        if movement_type not in store.MOVEMENT_TYPES:
+            raise ValueError(f"허용되지 않는 이동 종류: {movement_type}")
+        code = store.validate_movement_code(item_code)  # MY-/MD- 차단
+        # IN/OUT 은 양수, ADJUST/STOCKTAKE 는 ± 허용
+        if movement_type in ("IN", "OUT"):
+            n = store.validate_qty(qty, allow_zero=False, allow_negative=False)
+        else:
+            n = store.validate_qty(qty, allow_zero=True, allow_negative=True)
+        if not (movement_date or "").strip():
+            raise ValueError("이동일자는 필수입니다.")
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                """
+                INSERT INTO stock_movement
+                    (movement_date, warehouse_code, item_code, movement_type,
+                     qty, ref_type, ref_no, memo, created_by)
+                VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s)
+                RETURNING *
+                """,
+                (
+                    movement_date.strip(),
+                    warehouse_code.strip(),
+                    code,
+                    movement_type,
+                    n,
+                    (ref_type or "").strip(),
+                    (ref_no or "").strip(),
+                    (memo or "").strip(),
+                    (created_by or "").lower().strip(),
+                ),
+            ).fetchone()
+        return self._serialize(row)
+
+    def create_set_out(
+        self,
+        *,
+        movement_date: str,
+        warehouse_code: str,
+        set_code: str,
+        set_qty: int,
+        bom_map: dict[str, list[dict[str, Any]]],
+        ref_type: str = "",
+        ref_no: str = "",
+        memo: str = "",
+        created_by: str = "",
+    ) -> list[dict[str, Any]]:
+        """세트 주문 출고 → BOM(itemcode_db)으로 분해해 구성품별 OUT movement 생성.
+
+        예: MY-0002 1세트 출고 → MT-0320, MT-0550 ... 각각 OUT.
+        콤보는 입고 불가(낱개로만 입고). 출고만 BOM 분해한다.
+        bom_map 은 라우터가 itemcode 리더에서 받아 주입. 구성 없으면 ValueError.
+        """
+        sc = store.validate_bom_set_code(set_code)
+        q = store.validate_qty(set_qty, allow_zero=False)
+        exploded = store.explode_set(sc, q, bom_map)
+        if not exploded:
+            raise ValueError(f"세트 {sc} 의 BOM 구성이 없습니다. 세트구성을 먼저 등록하세요.")
+        ref_t = (ref_type or "set").strip() or "set"
+        results: list[dict[str, Any]] = []
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                for comp_code, comp_qty in exploded.items():
+                    row = conn.execute(
+                        # 구성 낱개는 콤보 분해분 — ref_type 을 SET_COMPONENT_REF 로 고정해
+                        # 이동이력에서 '낱개 입력' 줄과 구분(숨김)한다. 재고 계산엔 포함.
+                        """
+                        INSERT INTO stock_movement
+                            (movement_date, warehouse_code, item_code, movement_type,
+                             qty, ref_type, ref_no, memo, created_by)
+                        VALUES (%s,%s,%s,'OUT',%s,%s,%s,%s,%s)
+                        RETURNING *
+                        """,
+                        (
+                            movement_date.strip(),
+                            warehouse_code.strip(),
+                            comp_code,
+                            comp_qty,
+                            store.SET_COMPONENT_REF,
+                            (ref_no or "").strip(),
+                            (memo or f"{sc} {q}세트 분해").strip(),
+                            (created_by or "").lower().strip(),
+                        ),
+                    ).fetchone()
+                    results.append(self._serialize(row))
+                # 콤보(세트) 단위 출고 원장 — 콤보 재고현황 차감용.
+                conn.execute(
+                    """
+                    INSERT INTO set_movement
+                        (movement_date, warehouse_code, set_code, movement_type,
+                         qty, ref_type, ref_no, memo, created_by)
+                    VALUES (%s,%s,%s,'OUT',%s,%s,%s,%s,%s)
+                    """,
+                    (
+                        movement_date.strip(),
+                        warehouse_code.strip(),
+                        sc,
+                        q,
+                        ref_t,
+                        (ref_no or "").strip(),
+                        (memo or f"{sc} {q}세트 출고").strip(),
+                        (created_by or "").lower().strip(),
+                    ),
+                )
+        return results
+
+    def list_movements(
+        self,
+        *,
+        warehouse_code: str | None = None,
+        item_code: str | None = None,
+        movement_type: str | None = None,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        limit: int = 500,
+    ) -> list[dict[str, Any]]:
+        clauses: list[str] = []
+        params: list[Any] = []
+        if warehouse_code:
+            clauses.append("warehouse_code = %s")
+            params.append(warehouse_code)
+        if item_code:
+            clauses.append("item_code = %s")
+            params.append(store._norm(item_code))
+        if movement_type in store.MOVEMENT_TYPES:
+            clauses.append("movement_type = %s")
+            params.append(movement_type)
+        if date_from:
+            clauses.append("movement_date >= %s")
+            params.append(date_from)
+        if date_to:
+            clauses.append("movement_date <= %s")
+            params.append(date_to)
+        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+        params.append(int(limit))
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                f"SELECT * FROM stock_movement {where} "
+                "ORDER BY movement_date DESC, id DESC LIMIT %s",
+                params,
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def list_set_movements(
+        self,
+        *,
+        warehouse_code: str | None = None,
+        movement_type: str | None = None,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        limit: int = 500,
+    ) -> list[dict[str, Any]]:
+        """콤보(세트) 출고 원장(set_movement) 목록. 이동이력 콤보 줄 표시용."""
+        clauses: list[str] = []
+        params: list[Any] = []
+        if warehouse_code:
+            clauses.append("warehouse_code = %s")
+            params.append(warehouse_code)
+        if movement_type in store.MOVEMENT_TYPES:
+            clauses.append("movement_type = %s")
+            params.append(movement_type)
+        if date_from:
+            clauses.append("movement_date >= %s")
+            params.append(date_from)
+        if date_to:
+            clauses.append("movement_date <= %s")
+            params.append(date_to)
+        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+        params.append(int(limit))
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                f"SELECT * FROM set_movement {where} "
+                "ORDER BY movement_date DESC, id DESC LIMIT %s",
+                params,
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def daily_movement_totals(
+        self, *, warehouse_code: str, movement_date: str, movement_type: str
+    ) -> dict[str, int]:
+        """특정 일자/종류의 낱개 아이템별 합계 수량.
+
+        세트 OUT 은 생성 시 이미 구성품 OUT 으로 분해 저장되므로 그대로 합산된다.
+        반환: { item_code: 합계수량 }
+        """
+        if movement_type not in store.MOVEMENT_TYPES:
+            raise ValueError(f"허용되지 않는 이동 종류: {movement_type}")
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                """
+                SELECT item_code, SUM(qty) AS qty
+                FROM stock_movement
+                WHERE warehouse_code = %s
+                  AND movement_date = %s
+                  AND movement_type = %s
+                GROUP BY item_code
+                ORDER BY item_code
+                """,
+                (warehouse_code, movement_date, movement_type),
+            ).fetchall()
+        return {r["item_code"]: int(r["qty"] or 0) for r in rows}
+
+    def current_stock(self, *, warehouse_code: str) -> dict[str, int]:
+        """창고별 현재고(낱개 아이템 기준).
+
+        현재고 = SUM(IN) - SUM(OUT) + SUM(ADJUST) + SUM(STOCKTAKE)
+        반환: { item_code: qty }
+        """
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                """
+                SELECT item_code,
+                       SUM(CASE
+                             WHEN movement_type = 'IN'  THEN qty
+                             WHEN movement_type = 'OUT' THEN -qty
+                             ELSE qty                       -- ADJUST/STOCKTAKE 는 부호 포함 저장
+                           END) AS qty
+                FROM stock_movement
+                WHERE warehouse_code = %s
+                GROUP BY item_code
+                """,
+                (warehouse_code,),
+            ).fetchall()
+        return {r["item_code"]: int(r["qty"] or 0) for r in rows}
+
+    def stock_status(self, *, warehouse_code: str) -> list[dict[str, Any]]:
+        """재고 현황 — 등록된 낱개 아이템 전체 + 현재고 + 마지막 조사일.
+
+        등록 아이템 기준으로 0 재고도 표시(좌측 조인 효과).
+        """
+        stock = self.current_stock(warehouse_code=warehouse_code)
+        last_dates = self._last_stocktake_dates(warehouse_code=warehouse_code)
+        items = self.list_items(kind="individual")
+        out: list[dict[str, Any]] = []
+        for it in items:
+            code = it["item_code"]
+            out.append(
+                {
+                    "item_code": code,
+                    "item_name": it.get("item_name") or code,
+                    "current_qty": stock.get(code, 0),
+                    "last_stocktake_date": last_dates.get(code),
+                }
+            )
+        # 등록 아이템에 없지만 movement 가 있는 코드도 노출(누락 방지)
+        for code, qty in stock.items():
+            if code not in {i["item_code"] for i in out}:
+                out.append(
+                    {
+                        "item_code": code,
+                        "item_name": code,
+                        "current_qty": qty,
+                        "last_stocktake_date": last_dates.get(code),
+                    }
+                )
+        out.sort(key=lambda x: x["item_code"])
+        return out
+
+    def latest_stocktake(self, *, warehouse_code: str) -> dict[str, Any] | None:
+        """가장 최근(취소 제외) 재고조사 헤더. 없으면 None."""
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT * FROM daily_stocktake "
+                "WHERE warehouse_code = %s AND status <> 'cancelled' "
+                "ORDER BY stocktake_date DESC, id DESC LIMIT 1",
+                (warehouse_code,),
+            ).fetchone()
+        return self._serialize(row) if row else None
+
+    def latest_rack_stocktake(self, *, warehouse_code: str) -> dict[str, Any] | None:
+        """랙 입력을 가장 최근에 저장한(취소 제외) 재고조사 헤더. 없으면 None.
+
+        랙보기 전용. '최근'을 조사 날짜가 아니라 랙 저장 시각으로 판단한다.
+        replace_rack 은 매 저장마다 daily_stocktake_rack 을 delete+insert 하므로
+        그 created_at MAX 가 곧 마지막 랙 저장 시각이 된다. 랙 항목이 없는
+        조사는 보여줄 게 없으므로 자연히 제외된다.
+        """
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT s.* FROM daily_stocktake s "
+                "JOIN daily_stocktake_rack r ON r.stocktake_id = s.id "
+                "WHERE s.warehouse_code = %s AND s.status <> 'cancelled' "
+                "GROUP BY s.id "
+                "ORDER BY MAX(r.created_at) DESC, s.id DESC LIMIT 1",
+                (warehouse_code,),
+            ).fetchone()
+        return self._serialize(row) if row else None
+
+    def previous_rack_entries(
+        self, *, warehouse_code: str, exclude_stocktake_id: int
+    ) -> list[dict[str, Any]]:
+        """직전(현재 조사 제외, 취소 제외, 랙 입력 있는) 재고조사의 랙 항목.
+
+        '이전값 불러오기' 버튼용. 조사 날짜 기준 가장 최근 다른 조사를 고른다.
+        replace_rack 의 entries 형식(cell_code/sku_code/units_per_box/box_count)과
+        호환되는 list_rack_entries 결과를 그대로 반환. 없으면 [].
+        """
+        with self._pool.connection() as conn:
+            head = conn.execute(
+                "SELECT s.id FROM daily_stocktake s "
+                "JOIN daily_stocktake_rack r ON r.stocktake_id = s.id "
+                "WHERE s.warehouse_code = %s AND s.id <> %s AND s.status <> 'cancelled' "
+                "GROUP BY s.id "
+                "ORDER BY MAX(r.created_at) DESC, s.id DESC LIMIT 1",
+                (warehouse_code, exclude_stocktake_id),
+            ).fetchone()
+        if not head:
+            return []
+        return self.list_rack_entries(stocktake_id=head["id"])
+
+    def reposition_rack(
+        self, *, stocktake_id: int, entries: list[dict[str, Any]]
+    ) -> dict[str, Any]:
+        """랙 위치 재배치 전용(랙 보기 드래그 저장).
+
+        daily_stocktake_rack 의 칸(cell_code) 배치만 교체한다. 위치 이동은
+        SKU 총수량을 바꾸지 않으므로 daily_stocktake_line 은 건드리지 않는다
+        (확정본의 집계/전산재고 보존). 확정(finalized) 조사도 허용 — 위치만
+        변경. 취소된 조사는 불가. entries 형식은 replace_rack 과 동일.
+        """
+        valid_cells = set(store.rack_cell_codes())
+        clean: list[tuple[str, str, int, int]] = []
+        for e in entries:
+            cell = (e.get("cell_code") or "").strip().upper()
+            if cell not in valid_cells:
+                raise ValueError(f"알 수 없는 랙 위치: {cell or '(빈값)'}")
+            code = store.validate_rack_code(str(e.get("sku_code") or ""))
+            upb = store.validate_qty(
+                e.get("units_per_box"), allow_zero=False, allow_negative=False
+            )
+            box = store.validate_qty(
+                e.get("box_count"), allow_zero=False, allow_negative=False
+            )
+            clean.append((cell, code, upb, box))
+
+        cell_seq: dict[str, int] = {}
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                head = conn.execute(
+                    "SELECT status FROM daily_stocktake WHERE id = %s FOR UPDATE",
+                    (stocktake_id,),
+                ).fetchone()
+                if not head:
+                    raise KeyError(stocktake_id)
+                if head["status"] == "cancelled":
+                    raise ValueError("취소된 조사는 수정할 수 없습니다.")
+                conn.execute(
+                    "DELETE FROM daily_stocktake_rack WHERE stocktake_id = %s",
+                    (stocktake_id,),
+                )
+                for cell, code, upb, box in clean:
+                    ln = cell_seq.get(cell, 0)
+                    cell_seq[cell] = ln + 1
+                    conn.execute(
+                        """
+                        INSERT INTO daily_stocktake_rack
+                            (stocktake_id, cell_code, line_no, sku_code,
+                             units_per_box, box_count)
+                        VALUES (%s,%s,%s,%s,%s,%s)
+                        """,
+                        (stocktake_id, cell, ln, code, upb, box),
+                    )
+        return {"entries": len(clean)}
+
+    def delete_stocktake(self, *, stocktake_id: int) -> None:
+        """재고조사 완전 삭제(헤더+라인 CASCADE). 슈퍼관리자 전용 동작.
+
+        주의: finalize 시 생성된 STOCKTAKE movement 는 별도이므로 같이 지우지 않는다
+        (재고 이력 보존). 헤더/라인만 제거.
+        """
+        with self._pool.connection() as conn:
+            cur = conn.execute("DELETE FROM daily_stocktake WHERE id = %s", (stocktake_id,))
+            if cur.rowcount == 0:
+                raise KeyError(stocktake_id)
+
+    def latest_set_quantities(self, *, warehouse_code: str) -> dict[str, Any]:
+        """콤보(MY-) 단위 재고현황 — 우측 패널용.
+
+        콤보는 movement 테이블(낱개 전용)에 직접 안 들어가므로, 재고조사 입력을
+        기준점으로 set_movement(콤보 출고 원장)를 차감해 현재 콤보 재고를 낸다.
+
+          콤보재고 = 최근(취소 제외) 재고조사 콤보수량 − 재고조사 기록 이후 콤보 OUT 합
+
+        차감 기준은 날짜가 아니라 재고조사 생성시각(created_at)이다. 같은 날
+        재고조사 후 출고해도 반영되도록(날짜만 비교하면 당일 출고가 누락됨).
+        재고조사를 다시 카운트하면 기준점이 갱신돼 이전 출고는 자동 리셋된다.
+
+        반환: {"stocktake_date": str|None,
+               "rows": [{set_code, set_name, stocktake_qty, out_qty, qty}]}
+        """
+        with self._pool.connection() as conn:
+            head = conn.execute(
+                "SELECT id, stocktake_date, created_at FROM daily_stocktake "
+                "WHERE warehouse_code = %s AND status <> 'cancelled' "
+                "ORDER BY stocktake_date DESC, id DESC LIMIT 1",
+                (warehouse_code,),
+            ).fetchone()
+            if not head:
+                return {"stocktake_date": None, "rows": []}
+            lines = conn.execute(
+                "SELECT sku_code, qty FROM daily_stocktake_line "
+                "WHERE stocktake_id = %s AND sku_code LIKE 'MY-%%' "
+                "ORDER BY sku_code ASC",
+                (head["id"],),
+            ).fetchall()
+            # 재고조사 기록 시점 이후의 콤보 출고(OUT)/조정(ADJUST) 합.
+            # created_at 비교라 같은 날 출고도 반영된다.
+            out_rows = conn.execute(
+                """
+                SELECT set_code,
+                       SUM(CASE WHEN movement_type = 'OUT' THEN qty ELSE -qty END) AS out_qty
+                FROM set_movement
+                WHERE warehouse_code = %s AND created_at > %s
+                GROUP BY set_code
+                """,
+                (warehouse_code, head["created_at"]),
+            ).fetchall()
+        out_map = {r["set_code"]: int(r["out_qty"] or 0) for r in out_rows}
+        names = self.item_name_map()
+        d = head["stocktake_date"]
+        date_str = d.isoformat() if isinstance(d, date) else str(d)
+        rows = [
+            {
+                "set_code": r["sku_code"],
+                "set_name": names.get(r["sku_code"], r["sku_code"]),
+                "stocktake_qty": int(r["qty"]),
+                "out_qty": out_map.get(r["sku_code"], 0),
+                "qty": int(r["qty"]) - out_map.get(r["sku_code"], 0),
+            }
+            for r in lines
+        ]
+        return {"stocktake_date": date_str, "rows": rows}
+
+    def _last_stocktake_dates(self, *, warehouse_code: str) -> dict[str, str]:
+        """아이템별 마지막 STOCKTAKE movement 날짜."""
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                """
+                SELECT item_code, MAX(movement_date) AS d
+                FROM stock_movement
+                WHERE warehouse_code = %s AND movement_type = 'STOCKTAKE'
+                GROUP BY item_code
+                """,
+                (warehouse_code,),
+            ).fetchall()
+        out: dict[str, str] = {}
+        for r in rows:
+            d = r["d"]
+            out[r["item_code"]] = d.isoformat() if isinstance(d, date) else str(d)
+        return out
+
+    # ════════════════════════════════════════════════════════════
+    # 일일 재고조사 (daily_stocktake + daily_stocktake_line)
+    # ════════════════════════════════════════════════════════════
+    def list_stocktakes(
+        self, *, warehouse_code: str | None = None, limit: int = 200
+    ) -> list[dict[str, Any]]:
+        clauses: list[str] = []
+        params: list[Any] = []
+        if warehouse_code:
+            clauses.append("warehouse_code = %s")
+            params.append(warehouse_code)
+        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+        params.append(int(limit))
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                f"SELECT * FROM daily_stocktake {where} "
+                "ORDER BY stocktake_date DESC, id DESC LIMIT %s",
+                params,
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def get_stocktake(
+        self, *, stocktake_id: int, with_lines: bool = True
+    ) -> dict[str, Any] | None:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT * FROM daily_stocktake WHERE id = %s", (stocktake_id,)
+            ).fetchone()
+            if not row:
+                return None
+            head = self._serialize(row)
+            if with_lines:
+                line_rows = conn.execute(
+                    "SELECT * FROM daily_stocktake_line WHERE stocktake_id = %s "
+                    "ORDER BY sku_code ASC",
+                    (stocktake_id,),
+                ).fetchall()
+                head["lines"] = [self._serialize(r) for r in line_rows]
+        return head
+
+    def create_stocktake(
+        self,
+        *,
+        stocktake_date: str,
+        warehouse_code: str,
+        memo: str = "",
+        created_by: str = "",
+    ) -> dict[str, Any]:
+        if not (stocktake_date or "").strip():
+            raise ValueError("조사 날짜는 필수입니다.")
+        if not (warehouse_code or "").strip():
+            raise ValueError("창고는 필수입니다.")
+        # 같은 날짜+창고에 이미 finalized 가 있으면 신규 생성 차단(요구사항 8)
+        with self._pool.connection() as conn:
+            dup = conn.execute(
+                "SELECT 1 FROM daily_stocktake "
+                "WHERE stocktake_date = %s AND warehouse_code = %s AND status = 'finalized' "
+                "LIMIT 1",
+                (stocktake_date.strip(), warehouse_code.strip()),
+            ).fetchone()
+            if dup:
+                raise ValueError(
+                    f"{stocktake_date} / {warehouse_code} 에 이미 확정된 재고조사가 있습니다."
+                )
+            row = conn.execute(
+                """
+                INSERT INTO daily_stocktake
+                    (stocktake_date, warehouse_code, status, memo, created_by)
+                VALUES (%s, %s, 'draft', %s, %s)
+                RETURNING *
+                """,
+                (
+                    stocktake_date.strip(),
+                    warehouse_code.strip(),
+                    (memo or "").strip(),
+                    (created_by or "").lower().strip(),
+                ),
+            ).fetchone()
+        return self._serialize(row)
+
+    def _assert_draft(self, conn: Any, stocktake_id: int) -> dict[str, Any]:
+        row = conn.execute(
+            "SELECT * FROM daily_stocktake WHERE id = %s", (stocktake_id,)
+        ).fetchone()
+        if not row:
+            raise KeyError(stocktake_id)
+        if row["status"] != "draft":
+            raise ValueError("확정/취소된 재고조사는 라인을 수정할 수 없습니다.")
+        return row
+
+    def upsert_line(
+        self, *, stocktake_id: int, sku_code: str, qty: int, memo: str = ""
+    ) -> dict[str, Any]:
+        code = store.validate_stocktake_code(sku_code)  # MD- 차단, MY/낱개 허용
+        n = store.validate_qty(qty, allow_zero=True, allow_negative=False)
+        with self._pool.connection() as conn:
+            self._assert_draft(conn, stocktake_id)
+            row = conn.execute(
+                """
+                INSERT INTO daily_stocktake_line (stocktake_id, sku_code, qty, memo)
+                VALUES (%s, %s, %s, %s)
+                ON CONFLICT (stocktake_id, sku_code) DO UPDATE
+                   SET qty = EXCLUDED.qty, memo = EXCLUDED.memo
+                RETURNING *
+                """,
+                (stocktake_id, code, n, (memo or "").strip()),
+            ).fetchone()
+        return self._serialize(row)
+
+    def delete_line(self, *, stocktake_id: int, line_id: int) -> None:
+        with self._pool.connection() as conn:
+            self._assert_draft(conn, stocktake_id)
+            cur = conn.execute(
+                "DELETE FROM daily_stocktake_line WHERE id = %s AND stocktake_id = %s",
+                (line_id, stocktake_id),
+            )
+            if cur.rowcount == 0:
+                raise KeyError(line_id)
+
+    # ════════════════════════════════════════════════════════════
+    # 재고조사 랙(rack) 입력 (daily_stocktake_rack)
+    #   랙 칸 단위로 SKU×입수량×박스수 를 저장하고, 그 집계로
+    #   daily_stocktake_line(SKU별 qty)을 재생성한다(랙이 라인의 단일 출처).
+    # ════════════════════════════════════════════════════════════
+    def list_rack_entries(self, *, stocktake_id: int) -> list[dict[str, Any]]:
+        """재고조사의 랙 입력 항목 전체. 칸→순서대로 정렬."""
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                "SELECT * FROM daily_stocktake_rack WHERE stocktake_id = %s "
+                "ORDER BY cell_code ASC, line_no ASC, id ASC",
+                (stocktake_id,),
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def replace_rack(
+        self, *, stocktake_id: int, entries: list[dict[str, Any]]
+    ) -> dict[str, Any]:
+        """랙 입력 전체 교체 → SKU별 집계로 재고조사 라인 재생성.
+
+        entries: [{"cell_code","sku_code","units_per_box","box_count"}, ...]
+          (입력 순서가 칸 안 line_no 가 된다.)
+        한 트랜잭션:
+          1) 기존 랙 항목 + 라인 전체 삭제
+          2) 검증한 랙 항목 삽입(칸별 line_no 부여)
+          3) aggregate_rack 결과를 daily_stocktake_line 으로 삽입
+        draft 가 아니면 ValueError. 알 수 없는 칸/코드도 ValueError.
+        """
+        valid_cells = set(store.rack_cell_codes())
+        clean: list[tuple[str, str, int, int]] = []
+        for e in entries:
+            cell = (e.get("cell_code") or "").strip().upper()
+            if cell not in valid_cells:
+                raise ValueError(f"알 수 없는 랙 위치: {cell or '(빈값)'}")
+            code = store.validate_rack_code(str(e.get("sku_code") or ""))
+            upb = store.validate_qty(
+                e.get("units_per_box"), allow_zero=False, allow_negative=False
+            )
+            box = store.validate_qty(
+                e.get("box_count"), allow_zero=False, allow_negative=False
+            )
+            clean.append((cell, code, upb, box))
+
+        totals = store.aggregate_rack(
+            [
+                {"sku_code": c, "units_per_box": u, "box_count": b}
+                for (_cell, c, u, b) in clean
+            ]
+        )
+
+        cell_seq: dict[str, int] = {}
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                self._assert_draft(conn, stocktake_id)
+                conn.execute(
+                    "DELETE FROM daily_stocktake_rack WHERE stocktake_id = %s",
+                    (stocktake_id,),
+                )
+                conn.execute(
+                    "DELETE FROM daily_stocktake_line WHERE stocktake_id = %s",
+                    (stocktake_id,),
+                )
+                for cell, code, upb, box in clean:
+                    ln = cell_seq.get(cell, 0)
+                    cell_seq[cell] = ln + 1
+                    conn.execute(
+                        """
+                        INSERT INTO daily_stocktake_rack
+                            (stocktake_id, cell_code, line_no, sku_code,
+                             units_per_box, box_count)
+                        VALUES (%s,%s,%s,%s,%s,%s)
+                        """,
+                        (stocktake_id, cell, ln, code, upb, box),
+                    )
+                for code in sorted(totals.keys()):
+                    qty = totals[code]
+                    if qty <= 0:
+                        continue
+                    conn.execute(
+                        """
+                        INSERT INTO daily_stocktake_line (stocktake_id, sku_code, qty)
+                        VALUES (%s,%s,%s)
+                        """,
+                        (stocktake_id, code, qty),
+                    )
+        return {"entries": len(clean), "lines": {k: v for k, v in totals.items() if v > 0}}
+
+    def cancel_stocktake(self, *, stocktake_id: int) -> dict[str, Any]:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "UPDATE daily_stocktake SET status = 'cancelled' "
+                "WHERE id = %s AND status <> 'finalized' RETURNING *",
+                (stocktake_id,),
+            ).fetchone()
+        if not row:
+            raise ValueError("확정된 조사는 취소할 수 없거나, 대상이 없습니다.")
+        return self._serialize(row)
+
+    def compute_result(
+        self, *, stocktake_id: int, bom_map: dict[str, list[dict[str, Any]]]
+    ) -> dict[str, Any]:
+        """재고조사 최종 계산 결과(낱개 아이템 기준).
+
+        bom_map 은 라우터가 itemcode 리더에서 받아 주입.
+        반환:
+          {
+            "stocktake": {...헤더...},
+            "rows": [{item_code,item_name,direct_qty,from_set_qty,total_qty}, ...],
+            "missing_bom": [MY-... BOM 없는 세트],
+          }
+        """
+        head = self.get_stocktake(stocktake_id=stocktake_id, with_lines=True)
+        if not head:
+            raise KeyError(stocktake_id)
+        lines = head.get("lines", [])
+        exploded = store.explode_stocktake(lines, bom_map)
+        missing = store.missing_bom_sets(lines, bom_map)
+        names = self.item_name_map()
+        rows = []
+        for code in sorted(exploded.keys()):
+            v = exploded[code]
+            rows.append(
+                {
+                    "stocktake_id": stocktake_id,
+                    "stocktake_date": head["stocktake_date"],
+                    "warehouse_code": head["warehouse_code"],
+                    "item_code": code,
+                    "item_name": names.get(code, code),
+                    "direct_qty": v["direct_qty"],
+                    "from_set_qty": v["from_set_qty"],
+                    "total_qty": v["total_qty"],
+                }
+            )
+        return {"stocktake": head, "rows": rows, "missing_bom": missing}
+
+    def finalize_stocktake(
+        self, *, stocktake_id: int, bom_map: dict[str, list[dict[str, Any]]]
+    ) -> dict[str, Any]:
+        """재고조사 확정 — 최종 낱개 total_qty 와 현재 시스템 재고의 '차이'만
+        STOCKTAKE movement 로 생성한다(요구사항 7).
+
+        - 차이 = total_qty - current_system_qty → qty 부호 그대로 STOCKTAKE 저장
+        - movement 이력이 남고, 현재고 계산은 단순 합산으로 유지된다.
+        - BOM 없는 MY- 세트는 확정을 막지 않는다(경고만). 해당 세트는 낱개로
+          분해되지 않아 낱개 재고에 0 으로 반영된다. BOM 은 itemcode_db
+          (set_components)에서 등록해야 분해가 적용된다.
+        반환: {"stocktake": {...}, "adjustments": [{item_code, before, after, diff}], "rows": [...]}
+        """
+        computed = self.compute_result(stocktake_id=stocktake_id, bom_map=bom_map)
+        head = computed["stocktake"]
+        if head["status"] != "draft":
+            raise ValueError("이미 확정/취소된 재고조사입니다.")
+        if computed["missing_bom"]:
+            logger.warning(
+                "재고조사 #%s 확정 — BOM 없는 세트 무시(낱개 0 반영): %s",
+                stocktake_id,
+                ", ".join(computed["missing_bom"]),
+            )
+        wh = head["warehouse_code"]
+        st_date = head["stocktake_date"]
+        current = self.current_stock(warehouse_code=wh)
+        rows = computed["rows"]
+        adjustments: list[dict[str, Any]] = []
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                for r in rows:
+                    code = r["item_code"]
+                    before = current.get(code, 0)
+                    after = r["total_qty"]
+                    diff = after - before
+                    if diff != 0:
+                        conn.execute(
+                            """
+                            INSERT INTO stock_movement
+                                (movement_date, warehouse_code, item_code, movement_type,
+                                 qty, ref_type, ref_no, memo, created_by)
+                            VALUES (%s,%s,%s,'STOCKTAKE',%s,'stocktake',%s,%s,%s)
+                            """,
+                            (
+                                st_date,
+                                wh,
+                                code,
+                                diff,
+                                str(stocktake_id),
+                                f"재고조사 #{stocktake_id} 반영(차이 {diff:+d})",
+                                head.get("created_by", ""),
+                            ),
+                        )
+                    adjustments.append(
+                        {"item_code": code, "before": before, "after": after, "diff": diff}
+                    )
+                conn.execute(
+                    "UPDATE daily_stocktake SET status = 'finalized', finalized_at = %s "
+                    "WHERE id = %s",
+                    (now_kst(), stocktake_id),
+                )
+        head = self.get_stocktake(stocktake_id=stocktake_id, with_lines=True)
+        return {"stocktake": head, "adjustments": adjustments, "rows": rows}
+
+    # ════════════════════════════════════════════════════════════
+    # 데이터 초기화 (슈퍼관리자 전용 — 라우터에서 권한 검사)
+    # ════════════════════════════════════════════════════════════
+    def reset_all_data(self) -> dict[str, int]:
+        """전체 창고의 재고 수량 데이터 초기화.
+
+        삭제 대상: stock_movement(입고/출고/조정/조사반영) +
+                   set_movement(콤보 출고 원장) +
+                   daily_stocktake/daily_stocktake_line(재고조사).
+        보존 대상: warehouses, malaysia_items(마스터).
+        한 트랜잭션으로 처리. 반환: 삭제 건수.
+        """
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                mv = conn.execute("DELETE FROM stock_movement").rowcount or 0
+                sm = conn.execute("DELETE FROM set_movement").rowcount or 0
+                ln = conn.execute("DELETE FROM daily_stocktake_line").rowcount or 0
+                hd = conn.execute("DELETE FROM daily_stocktake").rowcount or 0
+        return {"movements": mv, "set_movements": sm, "stocktake_lines": ln, "stocktakes": hd}
+
+    # ════════════════════════════════════════════════════════════
+    # 직렬화
+    # ════════════════════════════════════════════════════════════
+    @staticmethod
+    def _serialize(row: dict[str, Any] | None) -> dict[str, Any] | None:
+        if row is None:
+            return None
+        out = dict(row)
+        for k, v in list(out.items()):
+            if isinstance(v, datetime):
+                out[k] = v.astimezone(KST).isoformat(timespec="seconds")
+            elif isinstance(v, date):
+                out[k] = v.isoformat()
+        for k in ("id", "stocktake_id", "qty", "component_qty", "sort_order", "line_no"):
+            if k in out and out[k] is not None:
+                try:
+                    out[k] = int(out[k])
+                except (TypeError, ValueError):
+                    pass
+        if "active" in out:
+            out["active"] = bool(out["active"])
+        return out

app/modules/malaysia/itemcode.py

@@ -0,0 +1,163 @@
+"""itemcode_db 읽기 전용 — 세트 BOM(set_components) 조회.
+
+말레이시아 재고관리는 세트 구성(어느 세트에 어떤 낱개가 몇 개)을 별도로
+관리하지 않고 itemcode_db 에서 직접 읽는다.
+
+itemcode_db 실제 스키마(운영 확인됨):
+  set_items(item_code, sabangnet_code, name)            -- 세트 마스터
+  single_items(item_code, sabangnet_code, name)         -- 낱개 마스터
+  set_components(set_code, single_code, quantity)        -- 세트 ↔ 낱개 구성(BOM)
+      FK: set_code → set_items, single_code → single_items
+
+환경변수 `ITEMCODE_DB_URL`(읽기 전용 역할 itemcode_ro). cupang 모듈과 공유.
+미설정/실패 시 enabled=False, 빈 결과(앱/모듈을 죽이지 않음).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+logger = logging.getLogger("malaysia.itemcode")
+
+# BOM 구성품으로 인정할 prefix (낱개). MD- 뚜껑은 제외.
+_COMPONENT_PREFIXES = ("MT-", "MX-", "MZ-")
+
+
+class MalaysiaItemcodeReader:
+    """itemcode_db 읽기 전용 풀 + 세트 BOM 조회.
+
+    설정이 없으면 enabled=False, 메서드는 빈 결과를 돌려준다.
+    """
+
+    def __init__(self) -> None:
+        self._pool: Any = None
+        self.enabled = False
+        self.reason = ""
+        self.last_error = ""
+        self._configure()
+
+    def _configure(self) -> None:
+        dsn = os.getenv("ITEMCODE_DB_URL", "").strip()
+        if not dsn:
+            self.reason = "ITEMCODE_DB_URL 미설정 — 세트 BOM 조회 비활성."
+            return
+        try:
+            from psycopg.rows import dict_row
+            from psycopg_pool import ConnectionPool
+
+            self._pool = ConnectionPool(
+                conninfo=dsn,
+                min_size=1,
+                max_size=3,
+                kwargs={"row_factory": dict_row, "autocommit": True},
+                open=False,
+            )
+            self._pool.open(wait=False)
+            self.enabled = True
+            self.reason = ""
+        except Exception as exc:  # noqa: BLE001 — 설정/드라이버 문제로 모듈을 죽이지 않음
+            self.reason = f"itemcode_db 연결 풀 생성 실패: {type(exc).__name__}"
+
+    def set_bom_map(self) -> dict[str, list[dict[str, Any]]]:
+        """MY- 세트의 BOM 전체.
+
+        반환: { set_code: [{"component_code","component_qty"}, ...] }
+        store.explode_stocktake / explode_set 에 그대로 전달 가능.
+        구성품은 낱개(MT/MX/MZ)만 포함(혹시 모를 비낱개/뚜껑은 제외).
+        """
+        if not self.enabled or not self._pool:
+            return {}
+        try:
+            with self._pool.connection() as conn:
+                rows = conn.execute(
+                    "SELECT set_code, single_code, quantity "
+                    "FROM set_components WHERE set_code LIKE 'MY-%'"
+                ).fetchall()
+            self.last_error = ""
+        except Exception as exc:  # noqa: BLE001 — 모듈을 죽이지 않음
+            self.last_error = f"{type(exc).__name__}: {exc}"
+            logger.exception("itemcode set_components 조회 실패")
+            return {}
+        out: dict[str, list[dict[str, Any]]] = {}
+        for r in rows:
+            comp = str(r.get("single_code") or "").strip().upper()
+            if not comp.startswith(_COMPONENT_PREFIXES):
+                continue
+            try:
+                qty = int(r.get("quantity") or 0)
+            except (TypeError, ValueError):
+                qty = 0
+            if qty <= 0:
+                continue
+            out.setdefault(str(r["set_code"]).strip().upper(), []).append(
+                {"component_code": comp, "component_qty": qty}
+            )
+        return out
+
+    def set_codes_present(self) -> set[str]:
+        """set_components 에 등록된 MY- 세트 코드 전체(구성품 유효성 무관).
+
+        set_bom_map() 은 낱개(MT/MX/MZ) 구성품이 하나도 없는 세트를 결과에서
+        떨어뜨린다. 그래서 'BOM 누락'이 두 가지 원인을 가린다:
+          (a) set_components 에 set_code 자체가 없음        → 세트구성 미등록
+          (b) set_code 는 있으나 유효 낱개 구성품이 없음     → 구성품 점검 필요
+        이 메서드로 (a)/(b)를 구분해 정확한 에러 메시지를 만든다.
+        """
+        if not self.enabled or not self._pool:
+            return set()
+        try:
+            with self._pool.connection() as conn:
+                rows = conn.execute(
+                    "SELECT DISTINCT set_code FROM set_components "
+                    "WHERE set_code LIKE 'MY-%'"
+                ).fetchall()
+            self.last_error = ""
+        except Exception as exc:  # noqa: BLE001 — 모듈을 죽이지 않음
+            self.last_error = f"{type(exc).__name__}: {exc}"
+            logger.exception("itemcode set_components set_code 조회 실패")
+            return set()
+        return {str(r["set_code"]).strip().upper() for r in rows}
+
+    def name_map(self) -> dict[str, str]:
+        """낱개+세트 코드 → 이름(itemcode_db 기준). 표시 보강용(선택)."""
+        if not self.enabled or not self._pool:
+            return {}
+        try:
+            with self._pool.connection() as conn:
+                rows = conn.execute(
+                    "SELECT item_code, name FROM single_items "
+                    "UNION ALL SELECT item_code, name FROM set_items"
+                ).fetchall()
+            self.last_error = ""
+        except Exception as exc:  # noqa: BLE001
+            self.last_error = f"{type(exc).__name__}: {exc}"
+            return {}
+        return {
+            str(r["item_code"]).strip().upper(): str(r.get("name") or "").strip()
+            for r in rows
+        }
+
+    def sabangnet_code_map(self) -> dict[str, str]:
+        """낱개+세트 item_code → 사방넷 코드(itemcode_db). 엑셀 내보내기용."""
+        if not self.enabled or not self._pool:
+            return {}
+        try:
+            with self._pool.connection() as conn:
+                rows = conn.execute(
+                    "SELECT item_code, sabangnet_code FROM single_items "
+                    "UNION ALL SELECT item_code, sabangnet_code FROM set_items"
+                ).fetchall()
+            self.last_error = ""
+        except Exception as exc:  # noqa: BLE001
+            self.last_error = f"{type(exc).__name__}: {exc}"
+            return {}
+        return {
+            str(r["item_code"]).strip().upper(): str(r.get("sabangnet_code") or "").strip()
+            for r in rows
+        }
+
+    def close(self) -> None:
+        if self._pool is not None:
+            self._pool.close()

app/modules/malaysia/router.py

@@ -0,0 +1,985 @@
+"""말레이시아 창고 재고관리 모듈 라우터.
+
+- 경로: /malaysia
+- 권한: 로그인 + `malaysia` 모듈 권한 (관리자는 항상 통과). 서버 측 검사.
+- 데이터: MalaysiaStockStore (malaysia_stock_db / PostgreSQL) 전용.
+  MALAYSIA_STOCK_DB_URL 미설정 시 store 가 None 이며, 각 페이지는 "설정 필요" 안내.
+- 세트 BOM: itemcode_db(set_components) 읽기 전용(MalaysiaItemcodeReader). 별도 관리 메뉴 없음.
+
+입력 방식: 입출고/재고조사 모두 전체 아이템(+세트) 그리드에 수량만 키인 → 일괄 등록.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Body, Depends, Form, HTTPException, Request
+from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse, StreamingResponse
+
+from app.timezone import today_kst
+
+from . import store
+
+router = APIRouter(prefix="/malaysia", tags=["malaysia"])
+
+
+# ────────────────────────────────────────────────────────────
+# 공용 헬퍼
+# ────────────────────────────────────────────────────────────
+def _store(request: Request) -> Any:
+    return getattr(request.app.state, "malaysia_store", None)
+
+
+def _reader(request: Request) -> Any:
+    return getattr(request.app.state, "malaysia_itemcode", None)
+
+
+def _bom_map(request: Request) -> dict[str, list[dict[str, Any]]]:
+    """itemcode_db(set_components)에서 MY- 세트 BOM 을 읽어 반환. 리더 없으면 {}."""
+    r = _reader(request)
+    return r.set_bom_map() if r else {}
+
+
+_WEEKDAYS_KO = ("월", "화", "수", "목", "금", "토", "일")
+
+
+def _date_label(iso: str | None) -> str:
+    """'2026-06-11' → '2026-06-11 (목)'. 파싱 실패 시 원문."""
+    from datetime import date as _date  # noqa: WPS433
+
+    s = (iso or "").strip()
+    try:
+        d = _date.fromisoformat(s[:10])
+    except (ValueError, TypeError):
+        return s
+    return f"{d.isoformat()} ({_WEEKDAYS_KO[d.weekday()]})"
+
+
+def _require_user(request: Request) -> dict[str, Any]:
+    from app.main import get_current_user_record  # noqa: WPS433
+    from app.store import has_module  # noqa: WPS433
+
+    user = get_current_user_record(request)
+    if user is None:
+        raise HTTPException(status_code=401, detail="로그인이 필요합니다.")
+    if not has_module(user, "malaysia"):
+        raise HTTPException(status_code=403, detail="말레이시아 재고관리 모듈 권한이 없습니다.")
+    return user
+
+
+def _render_config_needed(request: Request, user: dict[str, Any]) -> HTMLResponse:
+    from app.main import build_erp_nav, render_template  # noqa: WPS433
+    from app.store import is_admin  # noqa: WPS433
+
+    return render_template(
+        request,
+        "denied.html",
+        {
+            "reason": "말레이시아 재고관리 모듈이 아직 설정되지 않았습니다. "
+            "MALAYSIA_STOCK_DB_URL 환경변수를 설정하고 "
+            "scripts/sql/malaysia_stock_db_init.sql 로 malaysia_stock_db 를 "
+            "초기화한 뒤 컨테이너를 재기동하세요.",
+            "user": user,
+            "is_admin": is_admin(user),
+            "nav_items": build_erp_nav(user, active="malaysia"),
+        },
+        status_code=503,
+    )
+
+
+def _guard(request: Request) -> tuple[Any, dict[str, Any]] | HTMLResponse | RedirectResponse:
+    """로그인+권한+store 점검. 페이지 핸들러 진입부에서 사용."""
+    from app.main import get_current_user_record, render_template  # noqa: WPS433
+    from app.store import has_module, is_admin  # noqa: WPS433
+
+    user = get_current_user_record(request)
+    if user is None:
+        return RedirectResponse(url="/login", status_code=303)
+    if not has_module(user, "malaysia"):
+        return render_template(
+            request,
+            "denied.html",
+            {"reason": "말레이시아 재고관리 모듈 접근 권한이 없습니다.", "is_admin": is_admin(user)},
+            status_code=403,
+        )
+    st = _store(request)
+    if st is None:
+        return _render_config_needed(request, user)
+    return st, user
+
+
+def _selected_wh(request: Request, st: Any) -> str:
+    """쿼리 ?wh= 또는 기본(첫 활성 창고)."""
+    wh = (request.query_params.get("wh") or "").strip()
+    codes = [w["warehouse_code"] for w in st.list_warehouses()]
+    if wh in codes:
+        return wh
+    return codes[0] if codes else "MY-WH-01"
+
+
+def _base_ctx(request: Request, user: dict[str, Any], st: Any, *, wh: str) -> dict[str, Any]:
+    from app.main import build_erp_nav  # noqa: WPS433
+    from app.store import is_admin  # noqa: WPS433
+
+    reader = _reader(request)
+    ko_names = reader.name_map() if reader else {}
+    return {
+        "user": user,
+        "is_admin": is_admin(user),
+        "is_super": bool(user.get("is_super_admin")),
+        "nav_items": build_erp_nav(user, active="malaysia"),
+        "warehouses": st.list_warehouses(),
+        "selected_wh": wh,
+        "ko_names": ko_names,
+    }
+
+
+# ════════════════════════════════════════════════════════════
+# 재고 현황 (메인)
+# ════════════════════════════════════════════════════════════
+@router.get("/", response_class=HTMLResponse)
+async def index(request: Request) -> HTMLResponse:
+    from app.main import render_template  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard
+    st, user = guard
+    wh = _selected_wh(request, st)
+    ctx = _base_ctx(request, user, st, wh=wh)
+    rows = st.stock_status(warehouse_code=wh)
+    # 마지막 재고조사(취소 제외) 의 낱개 기준 total 과 전산재고 차이
+    latest = st.latest_stocktake(warehouse_code=wh)
+    last_date = latest["stocktake_date"] if latest else None
+    last_map: dict[str, int] = {}
+    if latest:
+        comp = st.compute_result(stocktake_id=latest["id"], bom_map=_bom_map(request))
+        last_map = {r["item_code"]: r["total_qty"] for r in comp["rows"]}
+    for r in rows:
+        code = r["item_code"]
+        lq = last_map.get(code)
+        r["last_stocktake_date"] = last_date
+        r["last_qty"] = lq
+        r["diff"] = (lq - r["current_qty"]) if lq is not None else None
+    set_stock = st.latest_set_quantities(warehouse_code=wh)
+    ctx.update(
+        {
+            "page_title": "말레이시아 재고관리",
+            "page_subtitle": f"{wh} · 재고 현황",
+            "rows": rows,
+            "set_rows": set_stock["rows"],
+            "set_stocktake_date": set_stock["stocktake_date"],
+        }
+    )
+    return render_template(request, "malaysia/index.html", ctx)
+
+
+@router.get("/rack", response_class=HTMLResponse)
+async def rack_view(request: Request) -> HTMLResponse:
+    """창고 랙 보기 — 최근(취소 제외) 재고조사의 랙 입력을 칸별로 한눈에.
+
+    읽기 전용. 각 칸에 어떤 상품이 몇 박스(× 입수량 = 총개수) 있는지 표시.
+    """
+    from app.main import render_template  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard
+    st, user = guard
+    wh = _selected_wh(request, st)
+    # 랙보기는 '랙을 가장 최근에 저장한' 조사 기준(조사 날짜 아님).
+    latest = st.latest_rack_stocktake(warehouse_code=wh)
+    rack_by_cell: dict[str, list[dict[str, Any]]] = {}
+    # 뚜껑(MD-)은 malaysia_items 에 없으므로 이름맵에 병합해 코드 대신 이름 표시.
+    names = {**st.item_name_map(), **store.lid_name_map()}
+    if latest:
+        for e in st.list_rack_entries(stocktake_id=latest["id"]):
+            e["item_name"] = names.get(e["sku_code"], e["sku_code"])
+            e["total"] = int(e["units_per_box"]) * int(e["box_count"])
+            rack_by_cell.setdefault(e["cell_code"], []).append(e)
+    ctx = _base_ctx(request, user, st, wh=wh)
+    ctx.update(
+        {
+            "page_title": "말레이시아 재고관리 — 창고 랙",
+            "page_subtitle": f"{wh} · 랙 보기",
+            "rack_layout": store.rack_layout(),
+            "rack_by_cell": rack_by_cell,
+            "stocktake": latest,
+        }
+    )
+    return render_template(request, "malaysia/rack_view.html", ctx)
+
+
+@router.post("/rack/save")
+async def rack_save(
+    request: Request, user: dict[str, Any] = Depends(_require_user)
+) -> RedirectResponse:
+    """랙 보기에서 드래그로 재배치한 칸 구성을 저장(위치만 변경).
+
+    대상은 랙 보기가 보여주는 조사(latest_rack_stocktake). 수량 합계는
+    불변이며 확정본도 허용. 폼은 stocktake_detail 과 동일한 병렬배열
+    (rk_cell/rk_sku/rk_upb/rk_box) → _parse_rack_form 재사용.
+    """
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    form = await request.form()
+    wh = str(form.get("warehouse_code") or "").strip() or _selected_wh(request, st)
+    latest = st.latest_rack_stocktake(warehouse_code=wh)
+    if not latest:
+        raise HTTPException(status_code=400, detail="저장할 랙 재고조사가 없습니다.")
+    entries = _parse_rack_form(form)
+    try:
+        st.reposition_rack(stocktake_id=latest["id"], entries=entries)
+    except (KeyError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return RedirectResponse(url=f"/malaysia/rack?wh={wh}", status_code=303)
+
+
+@router.post("/reset")
+async def reset_data(
+    request: Request, user: dict[str, Any] = Depends(_require_user)
+) -> RedirectResponse:
+    """전체 창고 재고 수량 데이터 초기화 — 슈퍼관리자 전용.
+
+    stock_movement + daily_stocktake(+line) 전체 삭제(현재고/조사값 0).
+    마스터(warehouses, malaysia_items)는 보존.
+    """
+    if not user.get("is_super_admin"):
+        raise HTTPException(status_code=403, detail="재고 데이터 초기화는 슈퍼관리자만 가능합니다.")
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    st.reset_all_data()
+    return RedirectResponse(url="/malaysia/", status_code=303)
+
+
+# ════════════════════════════════════════════════════════════
+# 입고 / 출고 등록 (그리드 일괄)
+# ════════════════════════════════════════════════════════════
+@router.get("/movements", response_class=HTMLResponse)
+async def movements_page(request: Request) -> HTMLResponse:
+    from app.main import render_template  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard
+    st, user = guard
+    wh = _selected_wh(request, st)
+    mtype = (request.query_params.get("type") or "").strip().upper()
+    fdate = (request.query_params.get("date") or "").strip()
+    mt = mtype if mtype in store.MOVEMENT_TYPES else None
+    raw_singles = st.list_movements(
+        warehouse_code=wh, movement_type=mt,
+        date_from=fdate or None, date_to=fdate or None, limit=300,
+    )
+    # 콤보 분해로 생긴 구성 낱개(ref_type=SET_COMPONENT_REF)는 '낱개 입력'이 아니므로
+    # 이동이력에서 숨긴다. 콤보는 아래 set_movement 줄로 표시된다.
+    singles = [m for m in raw_singles if (m.get("ref_type") or "") != store.SET_COMPONENT_REF]
+    for m in singles:
+        m["kind"] = "individual"
+    # 콤보(세트) 출고 원장도 함께 보여준다(낱개/콤보 분리 표시).
+    combos = st.list_set_movements(
+        warehouse_code=wh, movement_type=mt,
+        date_from=fdate or None, date_to=fdate or None, limit=300,
+    )
+    for m in combos:
+        m["kind"] = "set"
+        m["item_code"] = m.get("set_code", "")
+    # 날짜(그다음 id) 내림차순 병합.
+    movements = sorted(
+        singles + combos,
+        key=lambda m: (str(m.get("movement_date") or ""), int(m.get("id") or 0)),
+        reverse=True,
+    )
+    for m in movements:
+        m["date_label"] = _date_label(m.get("movement_date"))
+    ctx = _base_ctx(request, user, st, wh=wh)
+    ctx.update(
+        {
+            "page_title": "말레이시아 재고관리 — 입출고",
+            "page_subtitle": f"{wh} · 입고/출고/조정 일괄 등록",
+            "individual_items": st.list_items(kind="individual"),
+            "set_items": st.list_items(kind="set"),
+            "movements": movements,
+            "today": today_kst().isoformat(),
+            "filter_type": mtype if mtype in store.MOVEMENT_TYPES else "",
+            "filter_date": fdate,
+        }
+    )
+    return render_template(request, "malaysia/movements.html", ctx)
+
+
+@router.post("/movements/apply")
+async def movements_apply(request: Request, user: dict[str, Any] = Depends(_require_user)) -> RedirectResponse:
+    """낱개 + 세트 한 화면 일괄 적용 (버튼 하나).
+
+    form: movement_type(낱개용 IN/OUT/ADJUST), movement_date, warehouse_code,
+          ref_type, ref_no, memo, qty_<CODE>...
+
+    - 낱개(individual): 선택한 movement_type 으로 등록. IN/OUT 양수만, ADJUST ±(0 스킵).
+    - 세트(set): 항상 OUT 으로 처리 — BOM(itemcode_db) 분해해 구성품별 OUT 생성.
+      콤보는 입고 불가(낱개로 분리 입고). IN 선택 + 콤보 수량 입력 시 400 안내.
+    빈칸/0 은 스킵. 코드별 에러는 모아서 부분 적용 후 안내.
+    """
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    form = await request.form()
+    mtype = str(form.get("movement_type") or "").strip().upper()
+    if mtype not in ("IN", "OUT", "ADJUST"):
+        raise HTTPException(status_code=400, detail="이동 종류 오류")
+    wh = str(form.get("warehouse_code") or "").strip()
+    mdate = str(form.get("movement_date") or "").strip()
+    ref_type = str(form.get("ref_type") or "").strip()
+    ref_no = str(form.get("ref_no") or "").strip()
+    memo = str(form.get("memo") or "").strip()
+    bmap = _bom_map(request)
+
+    # 콤보는 입고 불가 — IN 선택 + 세트 수량 입력 시 차단(낱개로 분리 입고 안내)
+    if mtype == "IN":
+        set_codes_keyed = [
+            it["item_code"]
+            for it in st.list_items(kind="set")
+            if str(form.get(f"qty_{it['item_code']}") or "").strip() not in ("", "0")
+        ]
+        if set_codes_keyed:
+            raise HTTPException(
+                status_code=400,
+                detail="콤보 상품은 입고할 수 없습니다. 낱개로 분리해서 입고하세요. "
+                "(입고 불가 콤보: " + ", ".join(set_codes_keyed) + ")",
+            )
+
+    applied = 0
+    errors: list[str] = []
+
+    # 낱개 — 선택한 종류로
+    for it in st.list_items(kind="individual"):
+        code = it["item_code"]
+        raw = str(form.get(f"qty_{code}") or "").strip()
+        if raw == "":
+            continue
+        try:
+            n = int(raw)
+        except ValueError:
+            errors.append(f"{code}: 숫자 아님")
+            continue
+        if n == 0:
+            continue
+        try:
+            st.create_movement(
+                movement_date=mdate, warehouse_code=wh, item_code=code,
+                movement_type=mtype, qty=n, ref_type=ref_type, ref_no=ref_no,
+                memo=memo, created_by=user["email"],
+            )
+            applied += 1
+        except ValueError as exc:
+            errors.append(f"{code}: {exc}")
+
+    # 세트 — 항상 OUT(BOM 분해). 콤보 입고는 위에서 이미 차단됨.
+    for it in st.list_items(kind="set"):
+        code = it["item_code"]
+        raw = str(form.get(f"qty_{code}") or "").strip()
+        if raw == "":
+            continue
+        try:
+            n = int(raw)
+        except ValueError:
+            errors.append(f"{code}: 숫자 아님")
+            continue
+        if n <= 0:
+            continue
+        try:
+            st.create_set_out(
+                movement_date=mdate, warehouse_code=wh, set_code=code, set_qty=n,
+                bom_map=bmap, ref_type="set", ref_no=ref_no, memo=memo,
+                created_by=user["email"],
+            )
+            applied += 1
+        except ValueError as exc:
+            errors.append(f"{code}: {exc}")
+
+    if errors and applied == 0:
+        raise HTTPException(status_code=400, detail="; ".join(errors[:10]))
+    return RedirectResponse(url=f"/malaysia/movements?wh={wh}&type={mtype}", status_code=303)
+
+
+@router.get("/movements/export")
+async def movements_export(request: Request) -> StreamingResponse:
+    """해당 일자/종류(IN/OUT)에 입출고된 낱개 수량을 엑셀로 내보낸다.
+
+    컬럼: A=사방넷 코드, B=수량, C=이름.
+    세트 OUT 은 생성 시 구성품 OUT 으로 분해 저장되므로 낱개 기준으로 합산된다.
+    """
+    import io  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard  # type: ignore[return-value]
+    st, _user = guard
+    wh = _selected_wh(request, st)
+    mtype = (request.query_params.get("type") or "OUT").strip().upper()
+    if mtype not in ("IN", "OUT"):
+        raise HTTPException(status_code=400, detail="type 은 IN 또는 OUT 이어야 합니다.")
+    mdate = (request.query_params.get("date") or today_kst().isoformat()).strip()
+
+    totals = st.daily_movement_totals(
+        warehouse_code=wh, movement_date=mdate, movement_type=mtype
+    )
+    reader = _reader(request)
+    sabang = reader.sabangnet_code_map() if reader else {}
+    names = reader.name_map() if reader else {}
+    item_names = st.item_name_map()
+
+    from openpyxl import Workbook  # noqa: WPS433
+    from openpyxl.styles import Alignment, Font, PatternFill  # noqa: WPS433
+    from openpyxl.utils import get_column_letter  # noqa: WPS433
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = f"{mtype}_{mdate}"
+    header = ["사방넷코드", "수량", "이름"]
+    ws.append(header)
+    for code in sorted(totals.keys()):
+        qty = totals[code]
+        if qty == 0:
+            continue
+        ws.append([
+            sabang.get(code, ""),
+            int(qty),
+            names.get(code) or item_names.get(code) or code,
+        ])
+
+    # 제목행(A1~C1): 파랑 배경 + 흰색 굵은글씨 + 가운데 정렬
+    fill = PatternFill(start_color="FF4472C4", end_color="FF4472C4", fill_type="solid")
+    font = Font(color="FFFFFFFF", bold=True)
+    center = Alignment(horizontal="center", vertical="center")
+    for col in range(1, len(header) + 1):
+        cell = ws.cell(row=1, column=col)
+        cell.fill = fill
+        cell.font = font
+        cell.alignment = center
+
+    # 열너비 자동(내용 길이 기준, 한글 폭 보정). 최소 8 ~ 최대 50.
+    for col in range(1, len(header) + 1):
+        letter = get_column_letter(col)
+        longest = 0
+        for cell in ws[letter]:
+            v = "" if cell.value is None else str(cell.value)
+            width = sum(2 if ord(ch) > 0x1100 else 1 for ch in v)
+            longest = max(longest, width)
+        ws.column_dimensions[letter].width = max(8, min(50, longest + 2))
+
+    buf = io.BytesIO()
+    wb.save(buf)
+    buf.seek(0)
+    fname = f"malaysia_{mtype}_{mdate}.xlsx"
+    return StreamingResponse(
+        buf,
+        media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        headers={"Content-Disposition": f'attachment; filename="{fname}"'},
+    )
+
+
+@router.get("/rack/export")
+async def rack_export(request: Request) -> StreamingResponse:
+    """창고 랙 보기 데이터를 엑셀로 내보낸다.
+
+    랙 보기와 동일 기준(latest_rack_stocktake)의 모든 칸 항목을 한 행씩.
+    컬럼: 아이템 코드 / 이름 / 수량 / 랙번호. 표 전체에 자동필터,
+    각 열은 내용 길이에 맞춰 너비 자동.
+    """
+    import io  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard  # type: ignore[return-value]
+    st, _user = guard
+    wh = _selected_wh(request, st)
+    latest = st.latest_rack_stocktake(warehouse_code=wh)
+    names = {**st.item_name_map(), **store.lid_name_map()}
+
+    rows: list[tuple[str, str, int, str]] = []
+    if latest:
+        for e in st.list_rack_entries(stocktake_id=latest["id"]):
+            code = e["sku_code"]
+            qty = int(e["units_per_box"]) * int(e["box_count"])
+            rows.append((code, names.get(code, code), qty, e["cell_code"]))
+    # 랙번호 → 아이템코드 순 정렬(보기 흐름과 동일하게 칸 기준).
+    rows.sort(key=lambda r: (r[3], r[0]))
+
+    from openpyxl import Workbook  # noqa: WPS433
+    from openpyxl.styles import Alignment, Font, PatternFill  # noqa: WPS433
+    from openpyxl.utils import get_column_letter  # noqa: WPS433
+
+    # 아이템별 합계(코드 기준 수량 합산). 코드→이름 보존, 코드순 정렬.
+    summary: dict[str, int] = {}
+    for code, _name, qty, _cell in rows:
+        summary[code] = summary.get(code, 0) + qty
+    summary_rows = sorted(
+        ((code, names.get(code, code), total) for code, total in summary.items()),
+        key=lambda r: r[0],
+    )
+
+    fill = PatternFill(start_color="FF4472C4", end_color="FF4472C4", fill_type="solid")
+    font = Font(color="FFFFFFFF", bold=True)
+    center = Alignment(horizontal="center", vertical="center")
+
+    def _style_header(row_idx: int, ncols: int) -> None:
+        for col in range(1, ncols + 1):
+            cell = ws.cell(row=row_idx, column=col)
+            cell.fill = fill
+            cell.font = font
+            cell.alignment = center
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "rack"
+
+    # ── 상세 표 ──
+    header = ["아이템 코드", "이름", "수량", "랙번호"]
+    ws.append(header)
+    for code, name, qty, cell in rows:
+        ws.append([code, name, qty, cell])
+    _style_header(1, len(header))
+    detail_last = ws.max_row  # 자동필터 범위(상세표만)
+    ws.auto_filter.ref = f"A1:{get_column_letter(len(header))}{detail_last}"
+
+    # ── 아이템별 합계 표 (상세표 아래, 한 줄 띄움) ──
+    # 빈 셀 행으로 한 줄 띄움(append([]) 은 셀이 없어 max_row 가 안 늘어 위치가
+    # 어긋나므로 빈 문자열 셀을 넣는다).
+    ws.append([""])
+    sum_header = ["아이템 코드", "이름", "합계 수량"]
+    ws.append(sum_header)
+    sum_header_row = ws.max_row  # 방금 추가한 합계 제목행(셀이 있어 정확)
+    for code, name, total in summary_rows:
+        ws.append([code, name, total])
+    _style_header(sum_header_row, len(sum_header))
+
+    # 열너비 자동(내용 길이 기준, 한글 폭 보정). 최소 8 ~ 최대 50.
+    for col in range(1, len(header) + 1):
+        letter = get_column_letter(col)
+        longest = 0
+        for cell in ws[letter]:
+            v = "" if cell.value is None else str(cell.value)
+            width = sum(2 if ord(ch) > 0x1100 else 1 for ch in v)
+            longest = max(longest, width)
+        ws.column_dimensions[letter].width = max(8, min(50, longest + 2))
+
+    buf = io.BytesIO()
+    wb.save(buf)
+    buf.seek(0)
+    sdate = (latest or {}).get("stocktake_date", today_kst().isoformat())
+    fname = f"malaysia_rack_{wh}_{sdate}.xlsx"
+    return StreamingResponse(
+        buf,
+        media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        headers={"Content-Disposition": f'attachment; filename="{fname}"'},
+    )
+
+
+# ════════════════════════════════════════════════════════════
+# 일일 재고조사
+# ════════════════════════════════════════════════════════════
+@router.get("/stocktakes", response_class=HTMLResponse)
+async def stocktakes_page(request: Request) -> HTMLResponse:
+    from app.main import render_template  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard
+    st, user = guard
+    wh = _selected_wh(request, st)
+    ctx = _base_ctx(request, user, st, wh=wh)
+    ctx.update(
+        {
+            "page_title": "말레이시아 재고관리 — 일일 재고조사",
+            "page_subtitle": f"{wh} · 조사 목록",
+            "stocktakes": st.list_stocktakes(warehouse_code=wh),
+            "today": today_kst().isoformat(),
+        }
+    )
+    return render_template(request, "malaysia/stocktakes.html", ctx)
+
+
+@router.post("/stocktakes")
+async def stocktake_create(
+    request: Request,
+    stocktake_date: str = Form(...),
+    warehouse_code: str = Form(...),
+    memo: str = Form(""),
+    user: dict[str, Any] = Depends(_require_user),
+) -> RedirectResponse:
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    try:
+        head = st.create_stocktake(
+            stocktake_date=stocktake_date, warehouse_code=warehouse_code,
+            memo=memo, created_by=user["email"],
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return RedirectResponse(url=f"/malaysia/stocktakes/{head['id']}", status_code=303)
+
+
+@router.get("/stocktakes/{stocktake_id:int}", response_class=HTMLResponse)
+async def stocktake_detail(request: Request, stocktake_id: int) -> HTMLResponse:
+    from app.main import render_template  # noqa: WPS433
+    from app.store import is_admin  # noqa: WPS433
+
+    guard = _guard(request)
+    if not isinstance(guard, tuple):
+        return guard
+    st, user = guard
+    try:
+        computed = st.compute_result(stocktake_id=stocktake_id, bom_map=_bom_map(request))
+    except KeyError:
+        return render_template(
+            request, "denied.html",
+            {"reason": "재고조사를 찾을 수 없습니다.", "is_admin": is_admin(user)},
+            status_code=404,
+        )
+    head = computed["stocktake"]
+    wh = head["warehouse_code"]
+    # 입력된 라인 qty 를 코드별 dict 로 (그리드 기본값)
+    entered = {ln["sku_code"]: ln["qty"] for ln in head.get("lines", [])}
+    # 랙 입력 항목을 칸별로 묶어 전달(그림 안 입력행 복원용)
+    rack_by_cell: dict[str, list[dict[str, Any]]] = {}
+    for e in st.list_rack_entries(stocktake_id=stocktake_id):
+        rack_by_cell.setdefault(e["cell_code"], []).append(e)
+    is_draft = head["status"] == "draft"
+    # 작성중일 때만 '이전값 불러오기' 가능 여부 계산(직전 조사에 랙 입력이 있을 때)
+    has_prev_rack = bool(
+        is_draft
+        and st.previous_rack_entries(warehouse_code=wh, exclude_stocktake_id=stocktake_id)
+    )
+    ctx = _base_ctx(request, user, st, wh=wh)
+    ctx.update(
+        {
+            "page_title": f"재고조사 #{stocktake_id}",
+            "page_subtitle": f"{head['stocktake_date']} · {wh} · {head['status']}",
+            "stocktake": head,
+            "rack_layout": store.rack_layout(),
+            "rack_by_cell": rack_by_cell,
+            # 낱개·세트 + 뚜껑(MD-, 위치확인용). 뚜껑은 재고 집계엔 빠진다.
+            "rack_items": st.list_items() + list(store.LID_ITEMS),
+            "entered": entered,
+            "result_rows": computed["rows"],
+            "missing_bom": computed["missing_bom"],
+            "is_draft": is_draft,
+            "has_prev_rack": has_prev_rack,
+        }
+    )
+    return render_template(request, "malaysia/stocktake_detail.html", ctx)
+
+
+@router.post("/stocktakes/{stocktake_id:int}/lines/bulk")
+async def stocktake_lines_bulk(
+    request: Request, stocktake_id: int, user: dict[str, Any] = Depends(_require_user)
+) -> RedirectResponse:
+    """그리드 일괄 저장. form: qty_<SKUCODE>... (낱개+세트). 빈칸은 스킵, 0 허용."""
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    form = await request.form()
+    codes = [i["item_code"] for i in st.list_items(kind="individual")]
+    codes += [i["item_code"] for i in st.list_items(kind="set")]
+    errors: list[str] = []
+    for code in codes:
+        raw = str(form.get(f"qty_{code}") or "").strip()
+        if raw == "":
+            continue
+        try:
+            n = int(raw)
+        except ValueError:
+            errors.append(f"{code}: 숫자 아님")
+            continue
+        try:
+            st.upsert_line(stocktake_id=stocktake_id, sku_code=code, qty=n)
+        except KeyError:
+            raise HTTPException(status_code=404, detail="재고조사를 찾을 수 없습니다.")
+        except ValueError as exc:
+            errors.append(f"{code}: {exc}")
+    if errors:
+        raise HTTPException(status_code=400, detail="; ".join(errors[:10]))
+    return RedirectResponse(url=f"/malaysia/stocktakes/{stocktake_id}", status_code=303)
+
+
+def _parse_rack_form(form: Any) -> list[dict[str, Any]]:
+    """랙 폼 병렬배열(rk_cell/rk_sku/rk_upb/rk_box) → 입력 항목 리스트.
+
+    SKU 미선택/입수량·박스수 ≤ 0 인 행은 스킵(미입력 행 취급).
+    """
+    cells = form.getlist("rk_cell")
+    skus = form.getlist("rk_sku")
+    upbs = form.getlist("rk_upb")
+    boxes = form.getlist("rk_box")
+    entries: list[dict[str, Any]] = []
+    for cell, sku, upb, box in zip(cells, skus, upbs, boxes):
+        code = str(sku or "").strip()
+        if not code:
+            continue
+        try:
+            u = int(str(upb).strip() or 0)
+            b = int(str(box).strip() or 0)
+        except ValueError:
+            continue
+        if u <= 0 or b <= 0:
+            continue
+        entries.append(
+            {"cell_code": cell, "sku_code": code, "units_per_box": u, "box_count": b}
+        )
+    return entries
+
+
+@router.post("/stocktakes/{stocktake_id:int}/rack/bulk")
+async def stocktake_rack_bulk(
+    request: Request, stocktake_id: int, user: dict[str, Any] = Depends(_require_user)
+) -> RedirectResponse:
+    """랙 입력 일괄 저장.
+
+    저장 시 랙 항목 교체 + SKU별 집계로 daily_stocktake_line 재생성.
+    """
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    form = await request.form()
+    entries = _parse_rack_form(form)
+    try:
+        st.replace_rack(stocktake_id=stocktake_id, entries=entries)
+    except KeyError:
+        raise HTTPException(status_code=404, detail="재고조사를 찾을 수 없습니다.")
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return RedirectResponse(url=f"/malaysia/stocktakes/{stocktake_id}", status_code=303)
+
+
+@router.post("/stocktakes/{stocktake_id:int}/rack/load-previous")
+async def stocktake_rack_load_previous(
+    request: Request, stocktake_id: int, user: dict[str, Any] = Depends(_require_user)
+) -> RedirectResponse:
+    """직전 재고조사의 랙 저장값을 현재(작성중) 조사로 불러와 채운다.
+
+    이전 랙 항목을 그대로 replace_rack 으로 적용 → 화면에 복원되어 표시된다.
+    사용자는 이어서 수정 후 저장/확정한다. 현재 입력은 덮어쓰므로 화면에서 confirm.
+    """
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    head = st.get_stocktake(stocktake_id=stocktake_id, with_lines=False)
+    if head is None:
+        raise HTTPException(status_code=404, detail="재고조사를 찾을 수 없습니다.")
+    if head["status"] != "draft":
+        raise HTTPException(status_code=400, detail="작성중인 조사만 불러올 수 있습니다.")
+    entries = st.previous_rack_entries(
+        warehouse_code=head["warehouse_code"], exclude_stocktake_id=stocktake_id
+    )
+    if not entries:
+        raise HTTPException(status_code=400, detail="불러올 이전 재고조사 랙 데이터가 없습니다.")
+    try:
+        st.replace_rack(stocktake_id=stocktake_id, entries=entries)
+    except (KeyError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return RedirectResponse(url=f"/malaysia/stocktakes/{stocktake_id}", status_code=303)
+
+
+@router.post("/stocktakes/{stocktake_id:int}/rack/finalize")
+async def stocktake_rack_finalize(
+    request: Request, stocktake_id: int, user: dict[str, Any] = Depends(_require_user)
+) -> RedirectResponse:
+    """랙 입력 저장 + 즉시 확정(한 번에).
+
+    확정 버튼이 랙 폼과 별개라 랙 데이터가 누락되는 문제를 막기 위해,
+    화면의 랙 입력을 먼저 저장(replace_rack)한 뒤 finalize 한다.
+    """
+    from app.store import is_admin  # noqa: WPS433
+
+    if not is_admin(user):
+        raise HTTPException(status_code=403, detail="전산 재고 반영은 관리자만 가능합니다.")
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    form = await request.form()
+    entries = _parse_rack_form(form)
+    try:
+        st.replace_rack(stocktake_id=stocktake_id, entries=entries)
+        st.finalize_stocktake(stocktake_id=stocktake_id, bom_map=_bom_map(request))
+    except KeyError:
+        raise HTTPException(status_code=404, detail="재고조사를 찾을 수 없습니다.")
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return RedirectResponse(url=f"/malaysia/stocktakes/{stocktake_id}", status_code=303)
+
+
+@router.post("/stocktakes/{stocktake_id:int}/lines/{line_id:int}/delete")
+async def stocktake_line_delete(
+    request: Request, stocktake_id: int, line_id: int,
+    user: dict[str, Any] = Depends(_require_user),
+) -> RedirectResponse:
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    try:
+        st.delete_line(stocktake_id=stocktake_id, line_id=line_id)
+    except KeyError:
+        raise HTTPException(status_code=404, detail="라인을 찾을 수 없습니다.")
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return RedirectResponse(url=f"/malaysia/stocktakes/{stocktake_id}", status_code=303)
+
+
+@router.post("/stocktakes/{stocktake_id:int}/finalize")
+async def stocktake_finalize(
+    request: Request, stocktake_id: int, user: dict[str, Any] = Depends(_require_user)
+) -> RedirectResponse:
+    from app.store import is_admin  # noqa: WPS433
+
+    if not is_admin(user):
+        raise HTTPException(status_code=403, detail="전산 재고 반영은 관리자만 가능합니다.")
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    try:
+        st.finalize_stocktake(stocktake_id=stocktake_id, bom_map=_bom_map(request))
+    except KeyError:
+        raise HTTPException(status_code=404, detail="재고조사를 찾을 수 없습니다.")
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return RedirectResponse(url=f"/malaysia/stocktakes/{stocktake_id}", status_code=303)
+
+
+@router.post("/stocktakes/{stocktake_id:int}/cancel")
+async def stocktake_cancel(
+    request: Request, stocktake_id: int, user: dict[str, Any] = Depends(_require_user)
+) -> RedirectResponse:
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    try:
+        st.cancel_stocktake(stocktake_id=stocktake_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return RedirectResponse(url=f"/malaysia/stocktakes/{stocktake_id}", status_code=303)
+
+
+@router.post("/stocktakes/{stocktake_id:int}/delete")
+async def stocktake_delete(
+    request: Request, stocktake_id: int, user: dict[str, Any] = Depends(_require_user)
+) -> RedirectResponse:
+    """재고조사 완전 삭제 — 슈퍼관리자 전용."""
+    if not user.get("is_super_admin"):
+        raise HTTPException(status_code=403, detail="재고조사 삭제는 슈퍼관리자만 가능합니다.")
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    wh = _selected_wh(request, st)
+    try:
+        st.delete_stocktake(stocktake_id=stocktake_id)
+    except KeyError:
+        raise HTTPException(status_code=404, detail="재고조사를 찾을 수 없습니다.")
+    return RedirectResponse(url=f"/malaysia/stocktakes?wh={wh}", status_code=303)
+
+
+# ════════════════════════════════════════════════════════════
+# JSON API
+# ════════════════════════════════════════════════════════════
+@router.get("/api/warehouses")
+async def api_warehouses(request: Request, _: dict[str, Any] = Depends(_require_user)) -> JSONResponse:
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    return JSONResponse({"warehouses": st.list_warehouses()})
+
+
+@router.get("/api/items")
+async def api_items(request: Request, kind: str = "", _: dict[str, Any] = Depends(_require_user)) -> JSONResponse:
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    k = kind if kind in ("individual", "set") else None
+    return JSONResponse({"items": st.list_items(kind=k)})
+
+
+@router.get("/api/bom")
+async def api_bom(request: Request, _: dict[str, Any] = Depends(_require_user)) -> JSONResponse:
+    """itemcode_db(set_components)에서 읽은 MY- 세트 BOM (읽기 전용)."""
+    return JSONResponse({"bom": _bom_map(request)})
+
+
+@router.get("/api/stock")
+async def api_stock(request: Request, wh: str = "", _: dict[str, Any] = Depends(_require_user)) -> JSONResponse:
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    wh = wh.strip() or _selected_wh(request, st)
+    return JSONResponse({"warehouse_code": wh, "rows": st.stock_status(warehouse_code=wh)})
+
+
+@router.post("/api/movements")
+async def api_movement_create(
+    request: Request, payload: dict[str, Any] = Body(...), user: dict[str, Any] = Depends(_require_user)
+) -> JSONResponse:
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    try:
+        row = st.create_movement(
+            movement_date=str(payload.get("movement_date") or ""),
+            warehouse_code=str(payload.get("warehouse_code") or ""),
+            item_code=str(payload.get("item_code") or ""),
+            movement_type=str(payload.get("movement_type") or ""),
+            qty=int(payload.get("qty") or 0),
+            ref_type=str(payload.get("ref_type") or ""),
+            ref_no=str(payload.get("ref_no") or ""),
+            memo=str(payload.get("memo") or ""),
+            created_by=user["email"],
+        )
+    except (ValueError, TypeError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return JSONResponse({"ok": True, "movement": row})
+
+
+@router.post("/api/movements/set-out")
+async def api_set_out(
+    request: Request, payload: dict[str, Any] = Body(...), user: dict[str, Any] = Depends(_require_user)
+) -> JSONResponse:
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    try:
+        rows = st.create_set_out(
+            movement_date=str(payload.get("movement_date") or ""),
+            warehouse_code=str(payload.get("warehouse_code") or ""),
+            set_code=str(payload.get("set_code") or ""),
+            set_qty=int(payload.get("set_qty") or 0),
+            bom_map=_bom_map(request),
+            ref_type=str(payload.get("ref_type") or "set"),
+            ref_no=str(payload.get("ref_no") or ""),
+            memo=str(payload.get("memo") or ""),
+            created_by=user["email"],
+        )
+    except (ValueError, TypeError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return JSONResponse({"ok": True, "movements": rows})
+
+
+@router.get("/api/stocktakes/{stocktake_id:int}/result")
+async def api_stocktake_result(
+    request: Request, stocktake_id: int, _: dict[str, Any] = Depends(_require_user)
+) -> JSONResponse:
+    st = _store(request)
+    if st is None:
+        raise HTTPException(status_code=503, detail="malaysia_stock_db 미설정")
+    try:
+        computed = st.compute_result(stocktake_id=stocktake_id, bom_map=_bom_map(request))
+    except KeyError:
+        raise HTTPException(status_code=404, detail="재고조사를 찾을 수 없습니다.")
+    return JSONResponse(
+        {"stocktake": computed["stocktake"], "rows": computed["rows"], "missing_bom": computed["missing_bom"]}
+    )
+
+
+@router.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok", "module": "malaysia"}

app/modules/malaysia/store.py

@@ -0,0 +1,335 @@
+"""말레이시아 창고 재고관리 모듈 — 상수 및 순수 계산/검증 헬퍼.
+
+- 데이터 저장은 malaysia_stock_db(PostgreSQL) 전용이다(`db.py`).
+  운영 데이터가 JSON 과 DB 로 갈라지는 것을 막기 위해 JSON 폴백을 두지 않는다.
+  MALAYSIA_STOCK_DB_URL 미설정 시 라우터가 "설정 필요" 안내 페이지를 보여준다.
+- 이 모듈에는 DB 의존이 없는 상수와 순수 함수만 둔다(테스트 용이).
+  prefix 검증, 세트 BOM 분해, 재고조사 집계가 모두 여기 있다.
+
+코드 prefix 규칙(요구사항 8 검증):
+  - 낱개(개별) 아이템 : MT-, MX-, MZ-   → 입고/출고/조정 movement 가능
+  - 세트 아이템        : MY-            → movement 불가, 재고조사/BOM 만 가능
+  - 뚜껑(제외)         : MD-            → 어디에도 사용 불가
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+# ── 이동(movement) 종류 ──
+MOVEMENT_TYPES: tuple[str, ...] = ("IN", "OUT", "ADJUST", "STOCKTAKE")
+
+# 콤보(세트) 출고를 BOM 분해해 생성한 '구성 낱개' movement 의 ref_type 마커.
+# 이동이력에서 이 낱개 줄은 콤보 입력의 분해분이므로 '낱개 입력'으로 표시하지
+# 않고 숨긴다(콤보는 set_movement 줄로 따로 표시). 재고 계산엔 그대로 포함된다.
+SET_COMPONENT_REF: str = "set"
+
+# ── 재고조사 상태 ──
+STOCKTAKE_STATUSES: tuple[str, ...] = ("draft", "finalized", "cancelled")
+
+# ── 코드 prefix ──
+INDIVIDUAL_PREFIXES: tuple[str, ...] = ("MT-", "MX-", "MZ-")
+SET_PREFIX: str = "MY-"
+BLOCKED_PREFIX: str = "MD-"  # 뚜껑 — 재고(입출고/조사 집계) 대상에서 제외
+
+# 뚜껑(MD-) 아이템 목록 — 재고에는 반영하지 않고 '창고 랙 위치 확인' 용도로만
+# 랙 칸에 배치할 수 있다(드롭다운 노출). malaysia_items 테이블엔 넣지 않는다.
+LID_ITEMS: tuple[dict[str, str], ...] = (
+    {"item_code": "MD-0000", "item_name": "Lid XS", "kind": "lid"},
+    {"item_code": "MD-0001", "item_name": "Lid S", "kind": "lid"},
+    {"item_code": "MD-0002", "item_name": "Lid M", "kind": "lid"},
+    {"item_code": "MD-0003", "item_name": "Lid L", "kind": "lid"},
+    {"item_code": "MD-0005", "item_name": "Lid 5ℓ", "kind": "lid"},
+)
+
+
+def lid_name_map() -> dict[str, str]:
+    """뚜껑 코드 → 이름(랙 보기 표시용)."""
+    return {it["item_code"]: it["item_name"] for it in LID_ITEMS}
+
+# ── 창고 랙 레이아웃 (재고조사 랙 입력용) ──
+# 그림 고정: A/B 두 면, 각 면 3행 × 3열, 각 열은 2분할 → 면당 18칸, 총 36칸.
+# 행은 위→아래로 3,2,1 (그림과 동일). 칸 코드: '{면}{행}-{열}-{분할}' 예) A3-1-1.
+RACK_SIDES: tuple[str, ...] = ("A", "B")
+RACK_ROWS: tuple[int, ...] = (3, 2, 1)
+RACK_COLS: tuple[int, ...] = (1, 2, 3)
+RACK_SUBS: tuple[int, ...] = (1, 2)
+# Side B 아래 바닥(Ground) 파렛트 6칸. 코드: 'G1' ~ 'G6'.
+RACK_GROUND: tuple[str, ...] = ("G1", "G2", "G3", "G4", "G5", "G6")
+
+
+def rack_cell_codes() -> list[str]:
+    """모든 랙 칸 코드 목록(검증용). 예: 'A3-1-1' ... 'B1-3-2', 'G1'~'G6'."""
+    codes = [
+        f"{side}{row}-{col}-{sub}"
+        for side in RACK_SIDES
+        for row in RACK_ROWS
+        for col in RACK_COLS
+        for sub in RACK_SUBS
+    ]
+    codes.extend(RACK_GROUND)
+    return codes
+
+
+def rack_layout() -> list[dict[str, Any]]:
+    """템플릿 렌더용 중첩 구조.
+
+    [{"side":"A","rows":[{"row":3,"cols":[["A3-1-1","A3-1-2"], ...]}, ...]}, ...]
+    """
+    out: list[dict[str, Any]] = []
+    for side in RACK_SIDES:
+        rows: list[dict[str, Any]] = []
+        for row in RACK_ROWS:
+            cols = [
+                [f"{side}{row}-{col}-{sub}" for sub in RACK_SUBS]
+                for col in RACK_COLS
+            ]
+            rows.append({"row": row, "cols": cols})
+        out.append({"side": side, "label": f"Side {side}", "rows": rows})
+    # Side B 아래 Ground: 6칸(G1~G6)을 한 줄에. 각 칸은 분할 없는 단일 파렛트.
+    out.append({
+        "side": "Ground",
+        "label": "Ground",
+        "rows": [{"row": 0, "cols": [[code] for code in RACK_GROUND]}],
+    })
+    return out
+
+
+def aggregate_rack(entries: Iterable[dict[str, Any]]) -> dict[str, int]:
+    """랙 입력 항목을 SKU 코드별 총수량으로 집계.
+
+    각 항목: {"sku_code", "units_per_box", "box_count"}.
+    qty = SUM(units_per_box * box_count). 입수량/박스수 ≤ 0 또는 코드 공백은 스킵.
+    반환: { sku_code: total_qty }  (낱개·세트 코드 모두 포함 가능)
+    """
+    totals: dict[str, int] = {}
+    for e in entries:
+        code = _norm(e.get("sku_code"))
+        if not code:
+            continue
+        # 뚜껑(MD-)은 위치 확인용일 뿐 재고에 반영하지 않으므로 집계 제외.
+        if is_blocked_code(code):
+            continue
+        try:
+            upb = int(e.get("units_per_box") or 0)
+            box = int(e.get("box_count") or 0)
+        except (TypeError, ValueError):
+            continue
+        if upb <= 0 or box <= 0:
+            continue
+        totals[code] = totals.get(code, 0) + upb * box
+    return totals
+
+
+# ════════════════════════════════════════════════════════════
+# 코드 분류 / 검증 (순수 함수)
+# ════════════════════════════════════════════════════════════
+def _norm(code: str) -> str:
+    return (code or "").strip().upper()
+
+
+def is_individual_code(code: str) -> bool:
+    """낱개 아이템(MT-/MX-/MZ-) 여부."""
+    return _norm(code).startswith(INDIVIDUAL_PREFIXES)
+
+
+def is_set_code(code: str) -> bool:
+    """세트 아이템(MY-) 여부."""
+    return _norm(code).startswith(SET_PREFIX)
+
+
+def is_blocked_code(code: str) -> bool:
+    """제외 대상(MD- 뚜껑) 여부."""
+    return _norm(code).startswith(BLOCKED_PREFIX)
+
+
+def classify_code(code: str) -> str:
+    """코드 종류를 반환. 'individual' | 'set' | 'blocked' | 'unknown'."""
+    if is_blocked_code(code):
+        return "blocked"
+    if is_individual_code(code):
+        return "individual"
+    if is_set_code(code):
+        return "set"
+    return "unknown"
+
+
+def validate_movement_code(code: str) -> str:
+    """입고/출고/조정 movement 에 쓸 수 있는 코드인지 검증.
+
+    낱개(MT-/MX-/MZ-)만 허용. MY-/MD-/기타는 ValueError.
+    반환: 정규화된 코드(대문자/trim).
+    """
+    c = _norm(code)
+    if not c:
+        raise ValueError("아이템 코드가 비어 있습니다.")
+    kind = classify_code(c)
+    if kind == "blocked":
+        raise ValueError(f"뚜껑 코드(MD-)는 재고관리 대상이 아닙니다: {c}")
+    if kind == "set":
+        raise ValueError(f"세트 코드(MY-)는 입고/출고에 직접 쓸 수 없습니다: {c}")
+    if kind != "individual":
+        raise ValueError(f"허용되지 않는 코드입니다(MT-/MX-/MZ- 만 가능): {c}")
+    return c
+
+
+def validate_stocktake_code(code: str) -> str:
+    """재고조사 라인(daily_stocktake_line)에 쓸 수 있는 코드인지 검증.
+
+    낱개(MT-/MX-/MZ-) 또는 세트(MY-) 허용. MD-/기타는 ValueError.
+    """
+    c = _norm(code)
+    if not c:
+        raise ValueError("SKU 코드가 비어 있습니다.")
+    kind = classify_code(c)
+    if kind == "blocked":
+        raise ValueError(f"뚜껑 코드(MD-)는 재고조사 대상이 아닙니다: {c}")
+    if kind not in ("individual", "set"):
+        raise ValueError(f"허용되지 않는 코드입니다(MT-/MX-/MZ-/MY- 만 가능): {c}")
+    return c
+
+
+def validate_rack_code(code: str) -> str:
+    """창고 랙 칸에 배치할 수 있는 코드 검증.
+
+    낱개(MT-/MX-/MZ-)·세트(MY-)에 더해 뚜껑(MD-)도 허용한다.
+    뚜껑은 위치 확인 용도로만 랙에 두며, aggregate_rack 에서 집계 제외되어
+    재고(daily_stocktake_line)에는 반영되지 않는다.
+    """
+    c = _norm(code)
+    if not c:
+        raise ValueError("SKU 코드가 비어 있습니다.")
+    kind = classify_code(c)
+    if kind not in ("individual", "set", "blocked"):
+        raise ValueError(f"허용되지 않는 코드입니다(MT-/MX-/MZ-/MY-/MD- 만 가능): {c}")
+    return c
+
+
+def validate_bom_set_code(code: str) -> str:
+    """set_bom 의 set_code 검증 — MY- 만 허용."""
+    c = _norm(code)
+    if not is_set_code(c):
+        raise ValueError(f"세트 코드는 MY- 로 시작해야 합니다: {c}")
+    return c
+
+
+def validate_bom_component_code(code: str) -> str:
+    """set_bom 의 component_code 검증 — MT-/MX-/MZ- 만 허용(MY-/MD- 금지)."""
+    c = _norm(code)
+    if is_blocked_code(c):
+        raise ValueError(f"뚜껑 코드(MD-)는 세트 구성품이 될 수 없습니다: {c}")
+    if is_set_code(c):
+        raise ValueError(f"세트(MY-)가 세트의 구성품이 될 수 없습니다(중첩 불가): {c}")
+    if not is_individual_code(c):
+        raise ValueError(f"구성품은 MT-/MX-/MZ- 만 가능합니다: {c}")
+    return c
+
+
+def validate_qty(qty: Any, *, allow_zero: bool = True, allow_negative: bool = False) -> int:
+    """수량 검증/정규화. 정수 변환 + 음수/0 정책 적용."""
+    try:
+        n = int(qty)
+    except (TypeError, ValueError):
+        raise ValueError(f"수량은 정수여야 합니다: {qty!r}")
+    if not allow_negative and n < 0:
+        raise ValueError(f"수량은 음수가 될 수 없습니다: {n}")
+    if not allow_zero and n == 0:
+        raise ValueError("수량은 0이 될 수 없습니다.")
+    return n
+
+
+# ════════════════════════════════════════════════════════════
+# 세트 BOM 분해 / 재고조사 집계 (순수 함수 — DB 무관, 테스트 용이)
+# ════════════════════════════════════════════════════════════
+def explode_set(
+    set_code: str, set_qty: int, bom_map: dict[str, list[dict[str, Any]]]
+) -> dict[str, int]:
+    """세트 1종 × 수량을 BOM 기준으로 낱개 아이템 수량으로 분해.
+
+    bom_map: { set_code: [{"component_code": str, "component_qty": int}, ...] }
+    반환: { component_code: 분해수량 }
+    BOM 이 없으면 빈 dict(호출측에서 경고 처리).
+    """
+    out: dict[str, int] = {}
+    for comp in bom_map.get(_norm(set_code), []):
+        code = _norm(comp.get("component_code"))
+        try:
+            per = int(comp.get("component_qty") or 0)
+        except (TypeError, ValueError):
+            per = 0
+        if not code or per <= 0:
+            continue
+        out[code] = out.get(code, 0) + per * int(set_qty)
+    return out
+
+
+def explode_stocktake(
+    lines: Iterable[dict[str, Any]],
+    bom_map: dict[str, list[dict[str, Any]]],
+) -> dict[str, dict[str, Any]]:
+    """재고조사 라인을 낱개 아이템 기준 최종 수량으로 집계.
+
+    입력 라인: [{"sku_code": str, "qty": int}, ...]
+      - 낱개 코드(MT/MX/MZ) qty → direct_qty 로 누적
+      - 세트 코드(MY) qty       → set_bom 으로 분해해 from_set_qty 로 누적
+
+    반환(낱개 아이템 코드 기준):
+      { item_code: {
+          "direct_qty":   직접 조사 수량 합,
+          "from_set_qty": 세트 분해 수량 합,
+          "total_qty":    direct_qty + from_set_qty,
+        } }
+
+    추가로 결과에 포함되는 진단 키는 없다(순수 수량만). 세트 BOM 누락
+    경고는 `missing_bom_sets()` 로 별도 확인한다.
+    """
+    result: dict[str, dict[str, int]] = {}
+
+    def _bucket(code: str) -> dict[str, int]:
+        return result.setdefault(code, {"direct_qty": 0, "from_set_qty": 0})
+
+    for ln in lines:
+        code = _norm(ln.get("sku_code"))
+        try:
+            qty = int(ln.get("qty") or 0)
+        except (TypeError, ValueError):
+            qty = 0
+        if not code or qty < 0:
+            continue
+        if is_individual_code(code):
+            _bucket(code)["direct_qty"] += qty
+        elif is_set_code(code):
+            for comp_code, comp_qty in explode_set(code, qty, bom_map).items():
+                _bucket(comp_code)["from_set_qty"] += comp_qty
+        # blocked/unknown 은 무시(검증 단계에서 이미 막힘)
+
+    out: dict[str, dict[str, Any]] = {}
+    for code, v in result.items():
+        total = v["direct_qty"] + v["from_set_qty"]
+        out[code] = {
+            "item_code": code,
+            "direct_qty": v["direct_qty"],
+            "from_set_qty": v["from_set_qty"],
+            "total_qty": total,
+        }
+    return out
+
+
+def missing_bom_sets(
+    lines: Iterable[dict[str, Any]],
+    bom_map: dict[str, list[dict[str, Any]]],
+) -> list[str]:
+    """재고조사에 입력된 MY- 세트 중 BOM 구성이 없는 코드 목록.
+
+    요구사항 8: 'BOM 이 없는 MY- 코드가 재고조사에 입력되면 경고/오류'.
+    """
+    missing: list[str] = []
+    seen: set[str] = set()
+    for ln in lines:
+        code = _norm(ln.get("sku_code"))
+        if not is_set_code(code) or code in seen:
+            continue
+        seen.add(code)
+        if not bom_map.get(code):
+            missing.append(code)
+    return missing

app/modules/malaysia/templates/malaysia/_i18n.html

@@ -0,0 +1,35 @@
+{# 한글/영문 토글 버튼 + i18n 스크립트 + 모바일 최적화 CSS. 모든 말레이시아 화면 상단에 include. #}
+<style>
+  /* ── 말레이시아 재고관리 모바일 최적화 ── */
+  @media (max-width: 820px) {
+    /* 고정 폭 다단 그리드 → 1단 적층 */
+    .mys-grid { grid-template-columns: 1fr !important; }
+
+    /* 상단 탭/창고선택 바 — 창고 폼 한 줄 풀폭 */
+    .mys .erp-page-actions form { flex: 1 1 100%; }
+    .mys .erp-page-actions .erp-select { width: 100%; }
+
+    /* 재고조사 상세 정보 바 — 줄바꿈 허용 */
+    .mys-info-bar { flex-wrap: wrap !important; row-gap: 8px; }
+    .mys-info-bar .mys-hint { flex: 1 1 100%; white-space: normal !important; }
+
+    /* 데이터 테이블 — 카드 적층 대신 가로 스크롤 유지(열 정렬 보존) */
+    .mys .erp-table-wrap { overflow-x: auto; -webkit-overflow-scrolling: touch; }
+    .mys .erp-table { min-width: 440px; }
+    .mys .erp-table thead { display: table-header-group; }
+    .mys .erp-table tbody tr { display: table-row; padding: 0; }
+    .mys .erp-table tbody td { display: table-cell; border-bottom: 1px solid var(--color-subtle-ash); padding: 4px 8px; }
+
+    /* 랙 칸 — 6열 → 3열 */
+    .rack-row, .rv-row { grid-template-columns: repeat(3, 1fr) !important; }
+  }
+  @media (max-width: 480px) {
+    /* 랙 칸 — 3열 → 2열, 코드열 폭 자동 */
+    .rack-row, .rv-row { grid-template-columns: repeat(2, 1fr) !important; }
+    .mys-compact th.ccol, .mys-compact td.ccol { width: auto !important; }
+  }
+</style>
+<div style="display:flex;justify-content:flex-end;margin-bottom:8px;">
+  <button type="button" id="mys-lang-toggle" class="erp-btn erp-btn-outline">ENG</button>
+</div>
+<script src="/static/malaysia.js?v=20260622a"></script>

app/modules/malaysia/templates/malaysia/_nav.html

@@ -0,0 +1,18 @@
+{# 말레이시아 재고관리 공용 상단 바: 서브탭 + 창고 선택 #}
+<div class="erp-page-actions" style="display:flex;gap:8px;flex-wrap:wrap;align-items:center;">
+  <a class="erp-btn {% if active_tab=='status' %}erp-btn-primary{% else %}erp-btn-outline{% endif %}" href="/malaysia/?wh={{ selected_wh }}">재고 현황</a>
+  <a class="erp-btn {% if active_tab=='move' %}erp-btn-primary{% else %}erp-btn-outline{% endif %}" href="/malaysia/movements?wh={{ selected_wh }}">입출고</a>
+  <a class="erp-btn {% if active_tab=='stocktake' %}erp-btn-primary{% else %}erp-btn-outline{% endif %}" href="/malaysia/stocktakes?wh={{ selected_wh }}">일일 재고조사</a>
+  <a class="erp-btn {% if active_tab=='rack' %}erp-btn-primary{% else %}erp-btn-outline{% endif %}" href="/malaysia/rack?wh={{ selected_wh }}">창고 랙 보기</a>
+
+  <span style="flex:1 1 auto"></span>
+
+  <form method="get" style="display:flex;gap:6px;align-items:center;">
+    <label class="erp-muted" for="wh-sel">창고</label>
+    <select class="erp-select" id="wh-sel" name="wh" onchange="this.form.submit()">
+      {% for w in warehouses %}
+      <option value="{{ w.warehouse_code }}" {% if w.warehouse_code==selected_wh %}selected{% endif %}>{{ w.warehouse_code }} · {{ w.warehouse_name }}</option>
+      {% endfor %}
+    </select>
+  </form>
+</div>

app/modules/malaysia/templates/malaysia/index.html

@@ -0,0 +1,117 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<style>
+  .mys-compact .erp-table th,
+  .mys-compact .erp-table td { padding-top:4px; padding-bottom:4px; }
+  .mys-compact td.nm { white-space:nowrap; }
+  .mys-compact th.ccol, .mys-compact td.ccol { white-space:nowrap; width:88px; }
+  /* Last Stocktake 열 좁게(날짜 고정폭) — 콤보 영역에 공간 양보 */
+  .mys-compact th.stk, .mys-compact td.stk { white-space:nowrap; width:96px; }
+  /* 콤보 표 숫자열 compact + 줄바꿈 방지 → 가로 스크롤 제거 */
+  .mys-combo th.num, .mys-combo td.num { white-space:nowrap; width:52px; text-align:right; }
+  .mys-combo td.nm { white-space:normal; }
+</style>
+{% endblock %}
+
+{% block content %}
+<section class="mys mys-compact">
+  {% include "malaysia/_i18n.html" %}
+  {% set active_tab = 'status' %}
+  {% include "malaysia/_nav.html" %}
+
+  <div class="mys-grid" style="display:grid;grid-template-columns:minmax(0,1fr) 520px;gap:16px;align-items:start;">
+
+    <!-- 좌: 낱개로 분리된 전체 재고 -->
+    <div class="erp-card">
+      <div class="cpg-card-head" style="display:flex;justify-content:space-between;align-items:center;">
+        <h2><span class="i18n">전산 재고 현황 — 낱개 기준</span> ({{ rows|length }})</h2>
+        <span class="erp-muted">현재고 = 입고 − 출고 + 조정 + 재고조사반영 (콤보는 낱개로 분해 반영됨)</span>
+      </div>
+      <div class="erp-table-wrap">
+        <table class="erp-table">
+          <thead>
+            <tr>
+              <th class="ccol">Item Code</th><th>Product Name</th>
+              <th style="text-align:right">전산재고</th>
+              <th class="stk">Last Stocktake</th>
+              <th style="text-align:right">조사수량</th>
+              <th style="text-align:right">차이</th>
+            </tr>
+          </thead>
+          <tbody>
+            {% for r in rows %}
+            <tr>
+              <td class="ccol">{{ r.item_code }}</td>
+              <td class="nm" data-en="{{ r.item_name }}" data-ko="{{ ko_names.get(r.item_code, r.item_name) }}">{{ r.item_name }}</td>
+              <td style="text-align:right;font-weight:600;">{{ "{:,}".format(r.current_qty) }}</td>
+              <td class="stk">{{ r.last_stocktake_date or '—' }}</td>
+              <td style="text-align:right">{{ "{:,}".format(r.last_qty) if r.last_qty is not none else '—' }}</td>
+              <td style="text-align:right;font-weight:600;{% if r.diff %}color:#b91c1c;{% endif %}">
+                {% if r.diff is not none %}{{ "{:+,}".format(r.diff) }}{% else %}—{% endif %}
+              </td>
+            </tr>
+            {% endfor %}
+            {% if not rows %}
+            <tr><td colspan="6" class="erp-muted">표시할 재고가 없습니다.</td></tr>
+            {% endif %}
+          </tbody>
+        </table>
+      </div>
+    </div>
+
+    <!-- 우: 콤보(세트) 단위 재고 -->
+    <div class="erp-card">
+      <div class="cpg-card-head"><h2>콤보 재고 (세트 단위)</h2></div>
+      <span class="erp-muted">
+        {% if set_stocktake_date %}<span class="i18n">콤보재고 = 재고조사</span>({{ set_stocktake_date }}) <span class="i18n">− 이후 출고</span>{% else %}재고조사 입력 없음{% endif %}
+      </span>
+      <div class="erp-table-wrap" style="margin-top:8px;">
+        <table class="erp-table mys-combo">
+          <thead><tr>
+            <th class="ccol">Set Code</th><th>Set Name</th>
+            <th class="num" data-ko="조사" data-en="Counted">조사</th>
+            <th class="num" data-ko="출고" data-en="OUT">출고</th>
+            <th class="num" data-ko="재고" data-en="Stock">재고</th>
+          </tr></thead>
+          <tbody>
+            {% for s in set_rows %}
+            <tr>
+              <td class="ccol">{{ s.set_code }}</td>
+              <td class="nm" data-en="{{ s.set_name }}" data-ko="{{ ko_names.get(s.set_code, s.set_name) }}">{{ s.set_name }}</td>
+              <td class="num" style="color:#64748b;">{{ "{:,}".format(s.stocktake_qty) }}</td>
+              <td class="num">{% if s.out_qty %}<span style="color:#b91c1c;">−{{ "{:,}".format(s.out_qty) }}</span>{% else %}<span style="color:#94a3b8;">—</span>{% endif %}</td>
+              <td class="num" style="font-weight:600;">{{ "{:,}".format(s.qty) }}</td>
+            </tr>
+            {% endfor %}
+            {% if not set_rows %}
+            <tr><td colspan="5" class="erp-muted">콤보 재고 입력이 없습니다.</td></tr>
+            {% endif %}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  </div>
+
+  {% if is_super %}
+  <div class="erp-card" style="margin-top:16px;border:1px solid #fecaca;background:#fef2f2;">
+    <div class="cpg-card-head"><h2 style="color:#b91c1c;">위험 구역 (슈퍼관리자)</h2></div>
+    <p class="erp-muted" style="margin:4px 0 12px;">
+      전체 창고의 입출고 이력·재고조사 데이터를 모두 삭제해 재고 수량을 0으로 초기화합니다.
+      창고/아이템 마스터는 유지됩니다. <strong>되돌릴 수 없습니다.</strong>
+    </p>
+    <form method="post" action="/malaysia/reset" onsubmit="return mysConfirmReset()">
+      <button type="submit" class="erp-btn" style="background:#b91c1c;color:#fff;">재고 초기화</button>
+    </form>
+  </div>
+  <script>
+    function mysConfirmReset() {
+      if (!confirm('전체 창고의 입출고 이력과 재고조사 데이터를 모두 삭제합니다.\n재고 수량이 0으로 초기화되며 되돌릴 수 없습니다.\n\n계속하시겠습니까?')) return false;
+      var t = prompt('정말 초기화하려면 RESET 을 입력하세요.');
+      if (t !== 'RESET') { alert('초기화가 취소되었습니다.'); return false; }
+      return true;
+    }
+  </script>
+  {% endif %}
+</section>
+{% endblock %}

app/modules/malaysia/templates/malaysia/movements.html

@@ -0,0 +1,174 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<style>
+  .mys-compact .erp-table th,
+  .mys-compact .erp-table td { padding-top:4px; padding-bottom:4px; }
+  .mys-compact .erp-input { padding-top:4px; padding-bottom:4px; }
+  .mys-compact td.nm { white-space:nowrap; }
+  .mys-compact th.ccol, .mys-compact td.ccol { white-space:nowrap; width:88px; }
+  .mys-compact .qcol { width:110px; }
+  .mys-compact .qcol .erp-input { width:100px; }
+  .mys-compact .optfields .erp-field { width:100%; }
+  .mys-compact .optfields .erp-input,
+  .mys-compact .optfields .erp-select { width:100%; box-sizing:border-box; }
+</style>
+{% endblock %}
+
+{% block content %}
+<section class="mys mys-compact">
+  {% include "malaysia/_i18n.html" %}
+  {% set active_tab = 'move' %}
+  {% include "malaysia/_nav.html" %}
+
+  <!-- 3분할: 좌(옵션) · 중(낱개) · 우(세트), 버튼 하나 -->
+  <form method="post" action="/malaysia/movements/apply" onsubmit="return mysCheckComboIn(this)">
+    <input type="hidden" name="warehouse_code" value="{{ selected_wh }}" />
+
+    <div class="mys-grid" style="display:grid;grid-template-columns:280px 1fr 1fr;gap:16px;align-items:start;">
+
+      <!-- 좌: 종류 / 날짜 / 메모 -->
+      <div class="erp-card">
+        <div class="cpg-card-head"><h2>등록 옵션</h2></div>
+        <div class="optfields" style="display:flex;flex-direction:column;gap:10px;margin-top:8px;">
+          <label class="erp-field"><span>이동 종류 (낱개)</span>
+            <select class="erp-select" name="movement_type" required>
+              <option value="IN">IN (입고)</option>
+              <option value="OUT">OUT (출고)</option>
+              <option value="ADJUST">ADJUST (조정 ±)</option>
+            </select></label>
+          <label class="erp-field"><span>날짜</span>
+            <input class="erp-input" type="date" name="movement_date" value="{{ today }}" required /></label>
+          <label class="erp-field"><span>메모</span>
+            <input class="erp-input" type="text" name="memo" /></label>
+        </div>
+        <div class="erp-page-actions" style="margin-top:12px;display:flex;gap:8px;">
+          <button type="submit" class="erp-btn erp-btn-primary">입력</button>
+          <button type="button" class="erp-btn erp-btn-outline" onclick="mysDownloadMovements(this)">다운로드</button>
+        </div>
+      </div>
+
+      <!-- 중: 낱개 -->
+      <div class="erp-card">
+        <div class="cpg-card-head"><h2>낱개 상품</h2></div>
+        <div class="erp-table-wrap" style="margin-top:8px;">
+          <table class="erp-table">
+            <thead><tr><th class="ccol">Code</th><th>Name</th><th class="qcol">Qty</th></tr></thead>
+            <tbody>
+              {% for it in individual_items %}
+              <tr>
+                <td class="ccol">{{ it.item_code }}</td>
+                <td class="nm" data-en="{{ it.item_name }}" data-ko="{{ ko_names.get(it.item_code, it.item_name) }}">{{ it.item_name }}</td>
+                <td class="qcol"><input class="erp-input" type="number" name="qty_{{ it.item_code }}" placeholder="—" /></td>
+              </tr>
+              {% endfor %}
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <!-- 우: 세트 -->
+      <div class="erp-card">
+        <div class="cpg-card-head"><h2>콤보 상품</h2></div>
+        <div class="erp-table-wrap" style="margin-top:8px;">
+          <table class="erp-table">
+            <thead><tr><th class="ccol">Set Code</th><th>Set Name</th><th class="qcol">Qty</th></tr></thead>
+            <tbody>
+              {% for it in set_items %}
+              <tr>
+                <td class="ccol">{{ it.item_code }}</td>
+                <td class="nm" data-en="{{ it.item_name }}" data-ko="{{ ko_names.get(it.item_code, it.item_name) }}">{{ it.item_name }}</td>
+                <td class="qcol"><input class="erp-input" type="number" min="0" name="qty_{{ it.item_code }}" placeholder="—" /></td>
+              </tr>
+              {% endfor %}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  </form>
+
+  <script>
+    // 콤보(MY-)는 입고 불가 — IN 선택 + 콤보 수량 입력 시 안내 후 제출 차단
+    function mysCheckComboIn(form) {
+      var type = form.querySelector('[name=movement_type]').value;
+      if (type !== 'IN') return true;
+      var keyed = [];
+      form.querySelectorAll('input[name^="qty_MY-"]').forEach(function (inp) {
+        var v = (inp.value || '').trim();
+        if (v !== '' && v !== '0') keyed.push(inp.name.replace('qty_', ''));
+      });
+      if (keyed.length) {
+        var en = localStorage.getItem('mys_lang') === 'en';
+        alert(en
+          ? 'Combo products cannot be received.\nReceive them as separate single items.\n\nNot allowed: ' + keyed.join(', ')
+          : '콤보 상품은 입고할 수 없습니다.\n낱개로 분리해서 입고하세요.\n\n입고 불가 콤보: ' + keyed.join(', '));
+        return false;
+      }
+      return true;
+    }
+
+    function mysDownloadMovements(btn) {
+      var form = btn.closest('form');
+      var type = form.querySelector('[name=movement_type]').value;
+      var date = form.querySelector('[name=movement_date]').value;
+      var wh = form.querySelector('[name=warehouse_code]').value;
+      if (type !== 'IN' && type !== 'OUT') {
+        alert('다운로드는 IN(입고) 또는 OUT(출고)만 가능합니다.');
+        return;
+      }
+      if (!date) { alert('날짜를 선택하세요.'); return; }
+      var url = '/malaysia/movements/export?wh=' + encodeURIComponent(wh)
+        + '&type=' + encodeURIComponent(type)
+        + '&date=' + encodeURIComponent(date);
+      window.location.href = url;
+    }
+  </script>
+
+  <!-- 이동 이력 -->
+  <div class="erp-card" style="margin-top:16px;">
+    <div class="cpg-card-head" style="display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:8px;">
+      <h2><span class="i18n">이동 이력</span>{% if filter_date %} · {{ filter_date }}{% endif %}</h2>
+      <span style="display:flex;gap:6px;align-items:center;flex-wrap:wrap;">
+        <form method="get" style="display:flex;gap:6px;align-items:center;">
+          <input type="hidden" name="wh" value="{{ selected_wh }}" />
+          {% if filter_type %}<input type="hidden" name="type" value="{{ filter_type }}" />{% endif %}
+          <input class="erp-input" type="date" name="date" value="{{ filter_date }}" onchange="this.form.submit()" />
+          {% if filter_date %}<a class="erp-btn erp-btn-outline" href="/malaysia/movements?wh={{ selected_wh }}{% if filter_type %}&type={{ filter_type }}{% endif %}">날짜해제</a>{% endif %}
+        </form>
+        <a class="erp-btn erp-btn-outline" href="/malaysia/movements?wh={{ selected_wh }}{% if filter_date %}&date={{ filter_date }}{% endif %}">전체</a>
+        {% for t in ['IN','OUT','ADJUST','STOCKTAKE'] %}
+        <a class="erp-btn {% if filter_type==t %}erp-btn-primary{% else %}erp-btn-outline{% endif %}" href="/malaysia/movements?wh={{ selected_wh }}&type={{ t }}{% if filter_date %}&date={{ filter_date }}{% endif %}">{{ t }}</a>
+        {% endfor %}
+      </span>
+    </div>
+    <div class="erp-table-wrap">
+      <table class="erp-table">
+        <thead><tr><th>Date</th><th class="i18n">구분</th><th>Type</th><th>Item</th><th style="text-align:right">Qty</th><th>Memo</th><th>By</th></tr></thead>
+        <tbody>
+          {% for m in movements %}
+          <tr>
+            <td>{{ m.date_label }}</td>
+            <td>
+              {% if m.kind == 'set' %}
+              <span class="i18n erp-badge" style="background:#fef3c7;color:#92400e;">콤보</span>
+              {% else %}
+              <span class="i18n erp-badge" style="background:#e0e7ff;color:#3730a3;">낱개</span>
+              {% endif %}
+            </td>
+            <td>{{ m.movement_type }}</td>
+            <td>{{ m.item_code }}</td>
+            <td style="text-align:right">{{ m.qty }}</td>
+            <td>{{ m.memo or '—' }}</td>
+            <td>{{ m.created_by or '—' }}</td>
+          </tr>
+          {% endfor %}
+          {% if not movements %}
+          <tr><td colspan="7" class="erp-muted">이동 이력이 없습니다.</td></tr>
+          {% endif %}
+        </tbody>
+      </table>
+    </div>
+  </div>
+</section>
+{% endblock %}

app/modules/malaysia/templates/malaysia/rack_view.html

@@ -0,0 +1,291 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<style>
+  .rv-board { display:flex; flex-direction:column; gap:18px; }
+  .rv-side { width:100%; }
+  .rv-side h3 { text-align:center; margin:0 0 8px; }
+  .rv-row { display:grid; grid-template-columns:repeat(6, 1fr); gap:6px; margin-bottom:6px; }
+  .rv-cell {
+    border:1px solid #cbd5e1; border-radius:6px; padding:7px;
+    background:#f8fafc; min-height:104px; display:flex; flex-direction:column; min-width:0;
+    cursor:grab; transition:box-shadow .12s, border-color .12s, background .12s;
+  }
+  .rv-cell.is-empty { background:#fff; }
+  .rv-cell.is-selected { border-color:#2563eb; box-shadow:0 0 0 2px #93c5fd inset; background:#eff6ff; }
+  .rv-cell.is-dragover { border-color:#2563eb; background:#dbeafe; }
+  .rv-cell.dragging { opacity:.45; }
+  .rv-cell-head {
+    display:flex; align-items:center; justify-content:space-between;
+    font-size:14px; font-weight:700; color:#475569; margin-bottom:5px;
+    border-bottom:1px solid #e2e8f0; padding-bottom:4px;
+  }
+  .rv-cell-head .rv-pick {
+    flex:0 0 auto; width:16px; height:16px; margin:0; cursor:pointer;
+  }
+  .rv-items { display:flex; flex-direction:column; gap:4px; }
+  .rv-item { font-size:14px; line-height:1.3; }
+  .rv-item .rv-name { font-weight:700; color:#0f172a; }
+  .rv-item .rv-calc { color:#475569; }
+  .rv-item .rv-qty { color:#2563eb; font-weight:700; }
+  .rv-empty-note { font-size:13px; color:#cbd5e1; }
+
+  /* 수정됨 표시: 저장 버튼을 빨강으로 강조 */
+  #rv-save-btn.is-dirty {
+    background:#dc2626 !important; border-color:#dc2626 !important; color:#fff !important;
+  }
+  #rv-save-btn.is-dirty:hover { background:#b91c1c !important; border-color:#b91c1c !important; }
+
+  /* ── 인쇄 미리보기 모달 ── */
+  .rvp-overlay {
+    display:none; position:fixed; inset:0; z-index:2000;
+    background:rgba(15,23,42,.55); overflow:auto; padding:24px;
+  }
+  .rvp-overlay.is-open { display:block; }
+  .rvp-toolbar {
+    position:sticky; top:0; display:flex; gap:8px; justify-content:flex-end;
+    align-items:center; margin-bottom:16px;
+  }
+  .rvp-toolbar .rvp-title { margin-right:auto; color:#fff; font-weight:700; font-size:16px; }
+  .rvp-pages { display:flex; flex-direction:column; gap:18px; align-items:center; }
+  /* 화면 미리보기: A4 가로 비율(297:210) 시트 — 여백 최소, 글자 최대 */
+  .rvp-sheet {
+    background:#fff; width:min(100%, 1000px); aspect-ratio:297/210;
+    box-shadow:0 8px 24px rgba(0,0,0,.3); border-radius:4px;
+    display:flex; flex-direction:column; padding:1.5%; box-sizing:border-box;
+  }
+  .rvp-list { flex:1 1 auto; display:flex; flex-direction:column; justify-content:center; gap:4%; }
+  .rvp-line { display:flex; flex-direction:column; align-items:center; text-align:center; gap:0.5%; }
+  .rvp-line .rvp-name { font-weight:900; font-size:7vmin; color:#0f172a; line-height:1.05; }
+  .rvp-line .rvp-size { font-weight:900; font-size:14vmin; color:#0f172a; line-height:1; }
+  .rvp-line .rvp-calc { font-weight:800; font-size:6vmin; color:#1e293b; margin-top:1.5%; }
+  .rvp-line .rvp-calc .rvp-box { font-size:9.5vmin; font-weight:900; }
+  .rvp-empty { text-align:center; font-weight:900; font-size:9vmin; color:#94a3b8; margin:auto 0; }
+
+  /* ── 실제 인쇄 ── */
+  @media print {
+    /* 가로 인쇄: 상하 여백(=프린터 좌우)을 0으로, 좌우만 4mm 유지해 세로 공간 최대 확보 */
+    @page { size: A4 landscape; margin: 0 4mm; }
+    /* 비인쇄 요소는 display:none 으로 공간까지 제거 — visibility:hidden 은
+       공간이 남아 overlay(static)가 아래로 밀려 1페이지가 비던 문제 방지. */
+    .erp-sidebar, .erp-topbar { display:none !important; }
+    /* 앱 셸이 height:100vh + overflow:hidden 으로 한 화면만 보이게 잘라서,
+       인쇄 시 둘째 칸부터 잘려 1장만 나오던 문제. 인쇄에선 조상들의
+       높이·오버플로 제한을 풀어 모든 칸(sheet)이 흐르게 한다. */
+    html, body.erp-app-body, .erp-app, .erp-content, .erp-page, .mys {
+      height:auto !important; min-height:0 !important; max-height:none !important;
+      overflow:visible !important;
+    }
+    .erp-content { margin:0 !important; }
+    .erp-page { padding:0 !important; }
+    body.printing-cells .mys > *:not(.rvp-overlay) { display:none !important; }
+    body.printing-cells .rvp-overlay {
+      display:block !important; position:static !important; padding:0 !important;
+      background:#fff !important; overflow:visible !important;
+    }
+    .rvp-toolbar { display:none !important; }
+    /* flex 컨테이너면 Chrome이 자식의 page-break를 무시해 여러 칸이 한 장에
+       뭉쳐 잘림. block 으로 바꿔 칸(파렛트)마다 한 장씩 끊어 인쇄. */
+    .rvp-pages { display:block !important; gap:0 !important; }
+    .rvp-sheet {
+      width:100% !important; height:100vh !important; aspect-ratio:auto !important;
+      box-shadow:none !important; border-radius:0 !important;
+      padding:2mm !important;
+      /* break-before 가 Chrome에서 더 안정적: 첫 칸 제외 매 칸을 새 장으로. */
+      break-before:page; page-break-before:always;
+    }
+    .rvp-sheet:first-child { break-before:auto; page-break-before:auto; }
+    /* 인쇄 시 글씨 더 크게(멀리서도 보이게) — cm 기준.
+       칸에 상품이 1개일 때 기준. 2개·3개 이상이면 한 장에 다 들어가도록 단계 축소. */
+    .rvp-line .rvp-name { font-size:2.6cm; }
+    .rvp-line .rvp-size { font-size:5.5cm; }
+    .rvp-line .rvp-calc { font-size:1.8cm; }
+    .rvp-line .rvp-calc .rvp-box { font-size:3cm; }
+    .rvp-empty { font-size:3cm; }
+    /* 상품 2개: 절반 가량으로 축소(2개 합쳐도 A4 가로 1장에 맞게) */
+    .rvp-sheet.rvp-multi .rvp-line .rvp-name { font-size:1.5cm; }
+    .rvp-sheet.rvp-multi .rvp-line .rvp-size { font-size:3.1cm; }
+    .rvp-sheet.rvp-multi .rvp-line .rvp-calc { font-size:1.05cm; }
+    .rvp-sheet.rvp-multi .rvp-line .rvp-calc .rvp-box { font-size:1.7cm; }
+    /* 상품 3개 이상: 더 작게 */
+    .rvp-sheet.rvp-many .rvp-line .rvp-name { font-size:1cm; }
+    .rvp-sheet.rvp-many .rvp-line .rvp-size { font-size:2cm; }
+    .rvp-sheet.rvp-many .rvp-line .rvp-calc { font-size:0.75cm; }
+    .rvp-sheet.rvp-many .rvp-line .rvp-calc .rvp-box { font-size:1.2cm; }
+  }
+
+  /* ── 창고 POG (전체 도면 A4 가로 1장) ── */
+  .pog-overlay {
+    display:none; position:fixed; inset:0; z-index:2000;
+    background:rgba(15,23,42,.55); overflow:auto; padding:24px;
+  }
+  .pog-overlay.is-open { display:block; }
+  .pog-toolbar {
+    position:sticky; top:0; display:flex; gap:8px; justify-content:flex-end;
+    align-items:center; margin-bottom:16px;
+  }
+  .pog-toolbar .pog-title { margin-right:auto; color:#fff; font-weight:700; font-size:16px; }
+  .pog-pages { display:flex; flex-direction:column; gap:18px; align-items:center; }
+  /* A4 가로(297:210) 시트 — 면(Side A/B/Ground)마다 1장.
+     container-type:size → 자식이 cqh/cqw 로 시트 크기에 맞춰 확대/축소 */
+  .pog-sheet {
+    background:#fff; width:min(100%, 1180px); aspect-ratio:297/210;
+    box-shadow:0 8px 24px rgba(0,0,0,.3); border-radius:4px;
+    padding:1.8cqh 1.4cqw; box-sizing:border-box;
+    display:flex; flex-direction:column; overflow:hidden;
+    container-type:size;
+  }
+  .pog-sheet .pog-sheet-head {
+    display:flex; justify-content:space-between; align-items:baseline;
+    font-weight:800; color:#0f172a; margin-bottom:1.2cqh; flex:0 0 auto;
+  }
+  .pog-sheet .pog-sheet-head .pog-t { font-size:2.8cqh; }
+  .pog-sheet .pog-sheet-head .pog-meta { font-size:1.7cqh; color:#475569; font-weight:600; }
+  /* 면 1개가 시트 높이를 꽉 채운다(행 flex 균등 분배 → 칸 커짐) */
+  .pog-sheet .rv-side { flex:1 1 auto; display:flex; flex-direction:column; min-height:0; }
+  .pog-sheet .rv-side h3 { display:none; }
+  .pog-sheet .rv-row { flex:1 1 0; gap:1cqw; margin:0 0 1cqh; min-height:0; }
+  .pog-sheet .rv-row:last-child { margin-bottom:0; }
+  .pog-sheet .rv-cell {
+    height:auto; min-height:0; padding:0.7cqh 0.8cqw; border-radius:4px;
+    cursor:default; overflow:hidden; background:#f8fafc; justify-content:flex-start;
+  }
+  .pog-sheet .rv-cell.is-empty { background:#fff; }
+  .pog-sheet .rv-cell-head {
+    font-size:1.55cqh; font-weight:800; margin-bottom:0.5cqh; padding-bottom:0.35cqh;
+  }
+  .pog-sheet .rv-pick { display:none !important; }
+  .pog-sheet .rv-items { gap:0.4cqh; }
+  .pog-sheet .rv-item { font-size:1.55cqh; line-height:1.25; }
+  .pog-sheet .rv-empty-note { font-size:1.55cqh; }
+
+  @media print {
+    body.printing-pog .erp-sidebar, body.printing-pog .erp-topbar { display:none !important; }
+    body.printing-pog .mys > *:not(.pog-overlay) { display:none !important; }
+    body.printing-pog .pog-overlay {
+      display:block !important; position:static !important; padding:0 !important;
+      background:#fff !important; overflow:visible !important;
+    }
+    body.printing-pog .pog-toolbar { display:none !important; }
+    body.printing-pog .pog-pages { display:block !important; }
+    /* 면(시트)마다 한 장(A4 가로). container-type:size 가 인쇄 시 자식 grid 를
+       깨는 Chrome 버그 회피 → containment 해제하고 글자/여백은 mm 로 고정.
+       (화면 미리보기는 위쪽 cqh 그대로 사용) */
+    body.printing-pog .pog-sheet {
+      container-type:normal !important;
+      width:100% !important; height:auto !important; aspect-ratio:auto !important;
+      padding:4mm 4mm !important;
+      box-shadow:none !important; border-radius:0 !important;
+      break-before:page; page-break-before:always; page-break-inside:avoid;
+    }
+    body.printing-pog .pog-sheet:first-child { break-before:auto; page-break-before:auto; }
+    /* 면 자연 높이로 흐르게(flex 해제) → 프린터 여백 변동에도 한 면=한 장 */
+    body.printing-pog .pog-sheet .rv-side { display:block !important; flex:none !important; }
+    /* 6열 강제(인쇄에서 3열로 덮이는 문제 차단) */
+    body.printing-pog .pog-sheet .rv-row {
+      display:grid !important; grid-template-columns:repeat(6, 1fr) !important;
+      gap:2mm !important; margin:0 0 2mm !important;
+    }
+    body.printing-pog .pog-sheet .pog-sheet-head { margin-bottom:4mm !important; }
+    body.printing-pog .pog-sheet .pog-sheet-head .pog-t { font-size:8mm !important; }
+    body.printing-pog .pog-sheet .pog-sheet-head .pog-meta { font-size:4.5mm !important; }
+    body.printing-pog .pog-sheet .rv-cell {
+      min-height:50mm !important; height:auto !important; padding:1.5mm 2mm !important;
+    }
+    body.printing-pog .pog-sheet .rv-cell-head {
+      font-size:3.6mm !important; margin-bottom:1mm !important; padding-bottom:0.8mm !important;
+    }
+    body.printing-pog .pog-sheet .rv-items { gap:1mm !important; }
+    body.printing-pog .pog-sheet .rv-item { font-size:3.6mm !important; }
+    body.printing-pog .pog-sheet .rv-empty-note { font-size:3.6mm !important; }
+  }
+</style>
+{% endblock %}
+
+{% block content %}
+<section class="mys mys-compact">
+  {% include "malaysia/_i18n.html" %}
+  {% set active_tab = 'rack' %}
+  {% include "malaysia/_nav.html" %}
+
+  <div class="erp-card">
+    <div class="cpg-card-head" style="display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:8px;">
+      <h2>창고 랙 보기</h2>
+      <span class="erp-muted">
+        {% if stocktake %}
+          <span class="i18n">기준 재고조사</span>: #{{ stocktake.id }} · {{ stocktake.stocktake_date }}
+          {% if stocktake.status=='finalized' %}<span class="erp-badge erp-badge-success">확정</span>
+          {% elif stocktake.status=='cancelled' %}<span class="erp-badge erp-badge-neutral">취소</span>
+          {% else %}<span class="erp-badge erp-badge-inverse">작성중</span>{% endif %}
+        {% else %}
+          <span class="i18n">표시할 재고조사가 없습니다.</span>
+        {% endif %}
+      </span>
+    </div>
+
+    {% if stocktake %}
+    <div class="erp-page-actions" style="margin-top:8px;display:flex;gap:8px;flex-wrap:wrap;align-items:center;">
+      <span class="erp-muted i18n" style="flex:1 1 auto;min-width:0;">칸을 드래그해 다른 칸으로 옮기면 구성이 이동(채워진 칸끼리는 맞교환)됩니다. 칸 번호는 그대로입니다. 인쇄할 칸은 체크 후 인쇄하세요.</span>
+      <a href="/malaysia/rack/export?wh={{ selected_wh }}" class="erp-btn erp-btn-outline">다운로드</a>
+      <button type="button" id="rv-print-btn" class="erp-btn erp-btn-outline">인쇄 미리보기</button>
+      <button type="button" id="rv-pog-btn" class="erp-btn erp-btn-outline">POG 출력</button>
+      <button type="button" id="rv-save-btn" class="erp-btn erp-btn-primary">저장</button>
+    </div>
+    {% endif %}
+
+    <form id="rv-save-form" method="post" action="/malaysia/rack/save" style="display:none;">
+      <input type="hidden" name="warehouse_code" value="{{ selected_wh }}" />
+      <div id="rv-save-fields"></div>
+    </form>
+
+    <div class="rv-board" id="rv-board" style="margin-top:10px;"
+         data-wh="{{ selected_wh }}"
+         data-stocktake="{% if stocktake %}#{{ stocktake.id }} · {{ stocktake.stocktake_date }}{% endif %}">
+      {% for side in rack_layout %}
+      <div class="rv-side">
+        <h3>{{ side.label }}</h3>
+        {% for row in side.rows %}
+        <div class="rv-row">
+          {% for col in row.cols %}
+            {% for cell in col %}
+            {% set entries = rack_by_cell.get(cell, []) %}
+            <div class="rv-cell {% if not entries %}is-empty{% endif %}"
+                 data-cell="{{ cell }}" draggable="true"
+                 data-entries='[{% for e in entries %}{"sku":"{{ e.sku_code }}","ko":{{ (ko_names.get(e.sku_code, e.item_name)) | tojson }},"en":{{ e.item_name | tojson }},"upb":{{ e.units_per_box }},"box":{{ e.box_count }}}{% if not loop.last %},{% endif %}{% endfor %}]'>
+              <div class="rv-cell-head">
+                <span class="rv-code">{{ cell }}</span>
+                <input type="checkbox" class="rv-pick" title="인쇄 선택" draggable="false" />
+              </div>
+              <div class="rv-items"><!-- JS 렌더 --></div>
+            </div>
+            {% endfor %}
+          {% endfor %}
+        </div>
+        {% endfor %}
+      </div>
+      {% endfor %}
+    </div>
+  </div>
+
+  <!-- 인쇄 미리보기 모달 -->
+  <div class="rvp-overlay" id="rvp-overlay">
+    <div class="rvp-toolbar">
+      <span class="rvp-title i18n">인쇄 미리보기</span>
+      <button type="button" id="rvp-print" class="erp-btn erp-btn-primary">인쇄</button>
+      <button type="button" id="rvp-close" class="erp-btn erp-btn-outline">닫기</button>
+    </div>
+    <div class="rvp-pages" id="rvp-pages"></div>
+  </div>
+
+  <!-- 창고 POG 미리보기 모달 (전체 도면 1장) -->
+  <div class="pog-overlay" id="pog-overlay">
+    <div class="pog-toolbar">
+      <span class="pog-title i18n">창고 POG 미리보기</span>
+      <button type="button" id="pog-print" class="erp-btn erp-btn-primary">인쇄</button>
+      <button type="button" id="pog-close" class="erp-btn erp-btn-outline">닫기</button>
+    </div>
+    <div class="pog-pages" id="pog-pages"></div>
+  </div>
+</section>
+<script src="/static/malaysia_rack_view.js?v=20260619c"></script>
+{% endblock %}

app/modules/malaysia/templates/malaysia/stocktake_detail.html

@@ -0,0 +1,203 @@
+{% extends "erp_base.html" %}
+
+{% macro rack_row(cell, items, entry=None, disabled=False) %}
+<div class="rk-row">
+  <input type="hidden" name="rk_cell" value="{{ cell }}">
+  <select name="rk_sku" class="erp-input rk-sku" {% if disabled %}disabled{% endif %}>
+    <option value="">— 선택 —</option>
+    {% for it in items %}
+    <option value="{{ it.item_code }}" {% if entry and entry.sku_code == it.item_code %}selected{% endif %}>{{ it.item_name }}</option>
+    {% endfor %}
+  </select>
+  <div class="rk-line">
+    <label class="rk-f"><span>입수량</span>
+      <input class="erp-input rk-upb" type="number" min="1" name="rk_upb"
+             value="{{ entry.units_per_box if entry else '' }}" {% if disabled %}disabled{% endif %} /></label>
+    <label class="rk-f"><span>박스</span>
+      <input class="erp-input rk-box" type="number" min="1" name="rk_box"
+             value="{{ entry.box_count if entry else '' }}" {% if disabled %}disabled{% endif %} /></label>
+  </div>
+  <div class="rk-foot">
+    <span><span class="i18n">합계</span> <b class="rk-sub">{{ "{:,}".format(entry.units_per_box * entry.box_count) if entry else 0 }}</b></span>
+    {% if not disabled %}<button type="button" class="rk-del" title="행 삭제">× <span class="i18n">삭제</span></button>{% endif %}
+  </div>
+</div>
+{% endmacro %}
+
+{% block head_extra %}
+<style>
+  .mys-compact .erp-table th,
+  .mys-compact .erp-table td { padding-top:4px; padding-bottom:4px; }
+  /* 상단 정보 바 — 한 줄 */
+  .mys-info-bar {
+    display:flex; align-items:center; gap:16px; flex-wrap:nowrap;
+    border:1px solid #e2e8f0; border-radius:10px; background:#fff; padding:10px 14px;
+  }
+  .mys-info-bar h2 { margin:0; white-space:nowrap; }
+  .mys-info-bar > div { white-space:nowrap; }
+  .mys-info-bar .mys-hint {
+    flex:1 1 auto; min-width:0; overflow:hidden; text-overflow:ellipsis;
+    white-space:nowrap; font-size:12px;
+  }
+  .mys-info-bar > button { flex:0 0 auto; }
+
+  /* 랙 보드 — 두 면을 세로로 적층(각 면 풀폭 → 칸 넓게) */
+  .rack-board { display:flex; flex-direction:column; gap:18px; }
+  .rack-side { width:100%; }
+  .rack-side h3 { text-align:center; margin:0 0 8px; }
+  .rack-row { display:grid; grid-template-columns:repeat(6, 1fr); gap:6px; margin-bottom:6px; }
+  .rack-cell {
+    border:1px solid #cbd5e1; border-radius:6px; padding:4px;
+    background:#f8fafc; min-height:70px; display:flex; flex-direction:column; min-width:0;
+  }
+  .rack-cell-head {
+    display:flex; align-items:center; gap:4px; justify-content:space-between;
+    font-size:11px; font-weight:600; color:#475569; margin-bottom:4px;
+  }
+  .rack-cell-head .rk-add {
+    border:1px solid #94a3b8; background:#fff; border-radius:4px;
+    width:20px; height:20px; line-height:1; padding:0; cursor:pointer; font-weight:700; flex:0 0 auto;
+  }
+  .rk-rows { display:flex; flex-direction:column; gap:6px; }
+  /* 입력란 세로 배치 — 좁은 칸에서도 레이블이 보이게 */
+  .rk-row {
+    display:flex; flex-direction:column; gap:3px;
+    border:1px solid #e2e8f0; border-radius:5px; background:#fff; padding:4px;
+  }
+  .rk-row .rk-sku { font-size:12px; padding:2px 4px; width:100%; min-width:0; }
+  .rk-row .rk-line { display:flex; gap:6px; }
+  .rk-row .rk-f { display:flex; align-items:center; gap:3px; font-size:11px; margin:0; flex:1 1 0; min-width:0; }
+  .rk-row .rk-f > span { flex:0 0 auto; color:#64748b; }
+  .rk-row .rk-upb, .rk-row .rk-box {
+    flex:1 1 auto; min-width:0; font-size:12px; padding:2px 4px; text-align:right;
+  }
+  .rk-row .rk-foot {
+    display:flex; align-items:center; justify-content:space-between;
+    font-size:11px; color:#475569; margin-top:1px;
+  }
+  .rk-row .rk-sub { color:#2563eb; font-weight:600; }
+  .rk-row .rk-del {
+    border:none; background:transparent; color:#dc2626; cursor:pointer;
+    font-size:11px; line-height:1; padding:0;
+  }
+</style>
+{% endblock %}
+
+{% block content %}
+<section class="mys mys-compact">
+  {% include "malaysia/_i18n.html" %}
+  <div class="erp-page-actions">
+    <a class="erp-btn erp-btn-primary" href="/malaysia/stocktakes?wh={{ stocktake.warehouse_code }}">◀◀ 조사 목록</a>
+  </div>
+
+  <form method="post" action="/malaysia/stocktakes/{{ stocktake.id }}/rack/bulk">
+    <!-- 상단 정보 스트립 (한 줄) -->
+    <div class="mys-info-bar">
+      <h2><span class="i18n">재고조사</span> #{{ stocktake.id }}</h2>
+      <div><span class="erp-muted">날짜</span> {{ stocktake.stocktake_date }}</div>
+      <div><span class="erp-muted">창고</span> {{ stocktake.warehouse_code }}</div>
+      <div><span class="erp-muted">상태</span>
+        {% if stocktake.status=='finalized' %}<span class="erp-badge erp-badge-success">확정</span>
+        {% elif stocktake.status=='cancelled' %}<span class="erp-badge erp-badge-neutral">취소</span>
+        {% else %}<span class="erp-badge erp-badge-inverse">작성중</span>{% endif %}
+      </div>
+      {% if stocktake.finalized_at %}<div><span class="erp-muted">확정시각</span> {{ stocktake.finalized_at }}</div>{% endif %}
+      {% if missing_bom %}<span style="color:#b91c1c;font-weight:600;white-space:nowrap;">⚠ BOM 누락: {{ missing_bom|join(', ') }}</span>{% endif %}
+      <span class="erp-muted i18n mys-hint">랙 칸에 아이템·입수량(박스당 개수)·박스 수를 입력하면 낱개/콤보 수량이 자동 집계됩니다. 한 칸에 여러 아이템은 + 로 추가하세요. 저장 또는 확정 시 화면 입력이 함께 반영됩니다.</span>
+      {% if is_draft and has_prev_rack %}
+      <button type="submit" class="erp-btn erp-btn-outline"
+              formaction="/malaysia/stocktakes/{{ stocktake.id }}/rack/load-previous"
+              formnovalidate
+              onclick="return confirm('이전 재고조사의 저장값을 불러옵니다. 현재 화면에 입력한 내용은 사라지고 이전값으로 대체됩니다. 계속?');">이전값 불러오기</button>
+      {% endif %}
+      {% if is_draft %}<button type="submit" class="erp-btn erp-btn-outline">입력 저장</button>{% endif %}
+      {% if is_draft and is_admin %}
+      <button type="submit" class="erp-btn erp-btn-primary"
+              formaction="/malaysia/stocktakes/{{ stocktake.id }}/rack/finalize"
+              onclick="return confirm('현재 입력한 랙 내용을 저장하고 확정합니다. 확정하면 전산 재고와의 차이가 STOCKTAKE 이동으로 기록되고 이후 수정 불가합니다. 계속?');">확정 (전산 반영)</button>
+      {% endif %}
+    </div>
+
+    <!-- 랙 보드 -->
+    <div class="erp-card" style="margin-top:12px;">
+      <div class="cpg-card-head"><h2>랙 입력 (박스 단위)</h2></div>
+      <div class="rack-board" style="margin-top:10px;">
+          {% for side in rack_layout %}
+          <div class="rack-side">
+            <h3>{{ side.label }}</h3>
+            {% for row in side.rows %}
+            <div class="rack-row">
+              {% for col in row.cols %}
+                {% for cell in col %}
+                <div class="rack-cell" data-cell="{{ cell }}">
+                  <div class="rack-cell-head">
+                    <span>{{ cell }}</span>
+                    {% if is_draft %}<button type="button" class="rk-add" title="아이템 추가">+</button>{% endif %}
+                  </div>
+                  <div class="rk-rows">
+                    {% set entries = rack_by_cell.get(cell, []) %}
+                    {% for e in entries %}
+                      {{ rack_row(cell, rack_items, entry=e, disabled=(not is_draft)) }}
+                    {% endfor %}
+                    {% if is_draft and not entries %}
+                      {{ rack_row(cell, rack_items) }}
+                    {% endif %}
+                  </div>
+                </div>
+                {% endfor %}
+              {% endfor %}
+            </div>
+            {% endfor %}
+          </div>
+          {% endfor %}
+        </div>
+      </div>
+  </form>
+
+  <!-- JS 클론용 빈 행 템플릿(옵션 1벌만 보유) -->
+  <template id="rk-row-tpl">
+    {{ rack_row('', rack_items) }}
+  </template>
+
+  <!-- 확정/취소/삭제 -->
+  <div class="erp-page-actions" style="margin-top:12px;display:flex;gap:8px;flex-wrap:wrap;">
+    {% if is_draft %}
+      <form method="post" action="/malaysia/stocktakes/{{ stocktake.id }}/cancel" onsubmit="return confirm('이 조사를 취소합니다. 계속?');">
+        <button type="submit" class="erp-btn erp-btn-danger">취소</button>
+      </form>
+    {% endif %}
+    {% if is_super %}
+    <form method="post" action="/malaysia/stocktakes/{{ stocktake.id }}/delete"
+          onsubmit="return confirm('이 재고조사를 완전 삭제합니다(되돌릴 수 없음). 계속?');">
+      <button type="submit" class="erp-btn erp-btn-danger">삭제 (슈퍼관리자)</button>
+    </form>
+    {% endif %}
+  </div>
+
+  <!-- 최종 계산 결과 (낱개 기준) -->
+  <div class="erp-card" style="margin-top:16px;">
+    <div class="cpg-card-head"><h2>최종 계산 (낱개 기준)</h2></div>
+    <span class="erp-muted">total_qty = direct_qty(낱개 직접) + from_set_qty(콤보 분해)</span>
+    <div class="erp-table-wrap">
+      <table class="erp-table">
+        <thead><tr><th>Item Code</th><th>Product Name</th><th style="text-align:right">Direct</th><th style="text-align:right">From Set</th><th style="text-align:right">Total</th></tr></thead>
+        <tbody>
+          {% for r in result_rows %}
+          <tr>
+            <td>{{ r.item_code }}</td>
+            <td>{{ r.item_name }}</td>
+            <td style="text-align:right">{{ "{:,}".format(r.direct_qty) }}</td>
+            <td style="text-align:right">{{ "{:,}".format(r.from_set_qty) }}</td>
+            <td style="text-align:right;font-weight:600;">{{ "{:,}".format(r.total_qty) }}</td>
+          </tr>
+          {% endfor %}
+          {% if not result_rows %}
+          <tr><td colspan="5" class="erp-muted">입력된 수량이 없습니다.</td></tr>
+          {% endif %}
+        </tbody>
+      </table>
+    </div>
+  </div>
+</section>
+<script src="/static/malaysia_rack.js?v=20260614c"></script>
+{% endblock %}

app/modules/malaysia/templates/malaysia/stocktakes.html

@@ -0,0 +1,80 @@
+{% extends "erp_base.html" %}
+
+{% block content %}
+<section class="mys mys-compact">
+  {% include "malaysia/_i18n.html" %}
+  {% set active_tab = 'stocktake' %}
+  {% include "malaysia/_nav.html" %}
+
+  <div class="mys-grid" style="display:grid;grid-template-columns:340px 1fr;gap:16px;align-items:start;">
+
+    <!-- 신규 조사 생성 -->
+    <div class="erp-card">
+      <div class="cpg-card-head"><h2>재고조사 생성</h2></div>
+      <form method="post" action="/malaysia/stocktakes" onsubmit="return mysCheckFinalizedDate(this)" style="margin-top:10px;display:flex;flex-direction:column;gap:8px;">
+        <input type="hidden" name="warehouse_code" value="{{ selected_wh }}" />
+        <label class="erp-field"><span>조사 날짜</span>
+          <input class="erp-input" type="date" name="stocktake_date" value="{{ today }}" required /></label>
+        <label class="erp-field"><span>메모</span>
+          <input class="erp-input" type="text" name="memo" /></label>
+        <div class="erp-page-actions"><button type="submit" class="erp-btn erp-btn-primary">생성</button></div>
+      </form>
+      <p class="erp-muted">생성 후 상세에서 낱개/세트 수량을 입력하고 확정하세요.</p>
+    </div>
+
+    <!-- 조사 목록 -->
+    <div class="erp-card">
+      <div class="cpg-card-head"><h2><span class="i18n">조사 목록</span> ({{ stocktakes|length }})</h2></div>
+      <div class="erp-table-wrap">
+        <table class="erp-table">
+          <thead><tr><th>#</th><th>Date</th><th>Warehouse</th><th>Status</th><th>By</th><th></th></tr></thead>
+          <tbody>
+            {% for s in stocktakes %}
+            <tr>
+              <td>{{ s.id }}</td>
+              <td>{{ s.stocktake_date }}</td>
+              <td>{{ s.warehouse_code }}</td>
+              <td>
+                {% if s.status=='finalized' %}<span class="erp-badge erp-badge-success">확정</span>
+                {% elif s.status=='cancelled' %}<span class="erp-badge erp-badge-neutral">취소</span>
+                {% else %}<span class="erp-badge erp-badge-inverse">작성중</span>{% endif %}
+              </td>
+              <td>{{ s.created_by or '—' }}</td>
+              <td style="display:flex;gap:6px;">
+                <a class="erp-btn erp-btn-outline" href="/malaysia/stocktakes/{{ s.id }}">열기</a>
+                {% if is_super %}
+                <form method="post" action="/malaysia/stocktakes/{{ s.id }}/delete" onsubmit="return confirm('재고조사 #{{ s.id }} 완전 삭제. 계속?');">
+                  <button type="submit" class="erp-btn erp-btn-danger">삭제</button>
+                </form>
+                {% endif %}
+              </td>
+            </tr>
+            {% endfor %}
+            {% if not stocktakes %}
+            <tr><td colspan="6" class="erp-muted">재고조사가 없습니다.</td></tr>
+            {% endif %}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    // 이미 확정된 날짜 목록(현재 창고). 그 날짜로 생성 시도 시 안내 후 차단.
+    var MYS_FINALIZED_DATES = [
+      {% for s in stocktakes %}{% if s.status == 'finalized' %}"{{ s.stocktake_date }}",{% endif %}{% endfor %}
+    ];
+    function mysCheckFinalizedDate(form) {
+      var d = (form.querySelector('[name=stocktake_date]').value || '').trim();
+      if (MYS_FINALIZED_DATES.indexOf(d) !== -1) {
+        var en = localStorage.getItem('mys_lang') === 'en';
+        alert(en
+          ? d + ' is already finalized; you cannot create another stocktake for this date.'
+          : d + ' 은 재고조사가 확정되어 다시 재고조사를 생성할 수 없습니다.');
+        return false;
+      }
+      return true;
+    }
+  </script>
+</section>
+{% endblock %}

app/modules/project/__init__.py

@@ -0,0 +1,34 @@
+"""프로젝트 관리(아사나식) 모듈.
+
+라우터/저장소/템플릿을 한 디렉토리에서 관리한다(malaysia/dispatch 패턴).
+- 라우터: `router.py` (FastAPI APIRouter, prefix=/project)
+- 저장소: `db.py` (project_db / PostgreSQL 전용) + `store.py` (상수/순수 검증)
+- 템플릿: `templates/project/`
+- 메일: 전역 `app.mail.send_email` (업무 배정/완료 시 관리자 알림)
+
+데이터 저장은 project_db 전용이다. PROJECT_DB_URL 미설정 시
+build_project_store 는 None 을 반환하고, 라우터가 "설정 필요" 안내 페이지를
+보여준다(앱은 죽지 않음).
+
+권한: 로그인한 회사(dbxcorp.co.kr) 직원은 모듈 진입 가능. 프로젝트 생성/삭제·
+사용자 배정은 ERP 관리자(is_admin)만. 배정된 멤버는 서브프로젝트/업무/단계 관리.
+"""
+
+from typing import Any
+
+from . import store
+from .router import router
+
+__all__ = ["router", "store", "build_project_store"]
+
+
+def build_project_store(*, dsn: str | None) -> Any:
+    """PROJECT_DB_URL 이 있으면 ProjectStore, 없으면 None.
+
+    JSON 폴백을 두지 않는다(운영 데이터 분기 방지). None 이면 라우터가 안내 페이지 표시.
+    """
+    if not dsn:
+        return None
+    from .db import ProjectStore  # 지연 import (개발 환경 deps 없을 수 있음)
+
+    return ProjectStore(dsn)

app/modules/project/db.py

@@ -0,0 +1,743 @@
+"""project_db PostgreSQL 저장소.
+
+- 드라이버: psycopg 3 (`psycopg[binary,pool]`) — 다른 모듈과 동일 패턴.
+- 연결 정보: 환경변수 `PROJECT_DB_URL`
+  (예: postgresql://project_app:<pwd>@postgres-db:5432/project_db)
+- 스키마는 앱이 만들지 않는다. `scripts/sql/project_db_init.sql` 을 superuser 가
+  사전 적용한다. 앱 계정(project_app)은 CRUD 권한만 받는다.
+- 연결 풀은 lazy open.
+
+순수 검증/상수는 store.py 에 있고, 여기서는 DB I/O 와 직렬화만 담당한다.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date, datetime, time
+from typing import Any
+
+from psycopg.rows import dict_row
+from psycopg_pool import ConnectionPool
+
+from app.timezone import KST, now_kst
+
+from . import store
+
+logger = logging.getLogger("project.db")
+
+
+class ProjectStore:
+    def __init__(self, dsn: str, *, min_size: int = 1, max_size: int = 5):
+        self._pool = ConnectionPool(
+            conninfo=dsn,
+            min_size=min_size,
+            max_size=max_size,
+            kwargs={"row_factory": dict_row, "autocommit": True},
+            open=False,
+        )
+        self._pool.open(wait=False)
+
+    def close(self) -> None:
+        self._pool.close()
+
+    # ════════════════════════════════════════════════════════════
+    # 프로젝트 / 서브프로젝트
+    # ════════════════════════════════════════════════════════════
+    def list_projects(
+        self, *, include_archived: bool = False, member_email: str | None = None
+    ) -> list[dict[str, Any]]:
+        """전체 프로젝트(서브 포함) 평면 목록. member_email 지정 시 그 사용자가
+        멤버이거나 owner 인 프로젝트만(관리자는 라우터에서 None 으로 전체 조회).
+        """
+        clauses: list[str] = []
+        params: list[Any] = []
+        if not include_archived:
+            clauses.append("p.status <> 'archived'")
+        if member_email:
+            clauses.append(
+                "(p.owner_email = %s OR EXISTS ("
+                "  SELECT 1 FROM project_members m "
+                "  WHERE m.project_id = p.id AND m.user_email = %s))"
+            )
+            params.extend([member_email, member_email])
+        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                f"SELECT p.* FROM projects p {where} "
+                "ORDER BY p.parent_id NULLS FIRST, p.sort_order ASC, p.id ASC",
+                params,
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def get_project(self, *, project_id: int) -> dict[str, Any] | None:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT * FROM projects WHERE id = %s", (project_id,)
+            ).fetchone()
+        return self._serialize(row) if row else None
+
+    def create_project(
+        self,
+        *,
+        name: str,
+        parent_id: int | None = None,
+        description: str = "",
+        color: str = "",
+        owner_email: str = "",
+        start_date: str | None = None,
+        due_date: str | None = None,
+        created_by: str = "",
+        seed_stages: bool = True,
+    ) -> dict[str, Any]:
+        nm = store.validate_project_name(name)
+        col = store.validate_color(color)
+        sd = store.validate_date(start_date)
+        dd = store.validate_date(due_date)
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                if parent_id is not None:
+                    parent = conn.execute(
+                        "SELECT id FROM projects WHERE id = %s", (parent_id,)
+                    ).fetchone()
+                    if not parent:
+                        raise KeyError(f"상위 프로젝트를 찾을 수 없습니다: {parent_id}")
+                row = conn.execute(
+                    """
+                    INSERT INTO projects
+                        (parent_id, name, description, color, owner_email,
+                         start_date, due_date, created_by)
+                    VALUES (%s,%s,%s,%s,%s,%s,%s,%s)
+                    RETURNING *
+                    """,
+                    (
+                        parent_id,
+                        nm,
+                        store.norm_str(description),
+                        col,
+                        store.norm_str(owner_email, lower=True),
+                        sd,
+                        dd,
+                        store.norm_str(created_by, lower=True),
+                    ),
+                ).fetchone()
+                pid = row["id"]
+                if seed_stages:
+                    for i, (stage_name, is_done) in enumerate(store.DEFAULT_STAGES):
+                        conn.execute(
+                            "INSERT INTO project_stages "
+                            "(project_id, name, sort_order, is_done_stage) "
+                            "VALUES (%s,%s,%s,%s)",
+                            (pid, stage_name, i, is_done),
+                        )
+                self._log(conn, project_id=pid, actor=created_by,
+                          action=store.ACTION_CREATED, detail=nm)
+        return self._serialize(row)
+
+    def update_project(self, *, project_id: int, fields: dict[str, Any]) -> dict[str, Any]:
+        allowed = {
+            "name": lambda v: store.validate_project_name(v),
+            "description": lambda v: store.norm_str(v),
+            "color": lambda v: store.validate_color(v),
+            "owner_email": lambda v: store.norm_str(v, lower=True),
+            "start_date": lambda v: store.validate_date(v),
+            "due_date": lambda v: store.validate_date(v),
+            "status": lambda v: (store.norm_str(v, lower=True)
+                                 if store.norm_str(v, lower=True) in store.PROJECT_STATUSES
+                                 else "active"),
+        }
+        sets: list[str] = []
+        params: list[Any] = []
+        for key, fn in allowed.items():
+            if key in fields:
+                sets.append(f"{key} = %s")
+                params.append(fn(fields[key]))
+        if not sets:
+            existing = self.get_project(project_id=project_id)
+            if existing is None:
+                raise KeyError(project_id)
+            return existing
+        params.append(project_id)
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                f"UPDATE projects SET {', '.join(sets)} WHERE id = %s RETURNING *",
+                params,
+            ).fetchone()
+        if not row:
+            raise KeyError(project_id)
+        return self._serialize(row)
+
+    def delete_project(self, *, project_id: int) -> None:
+        """프로젝트(서브프로젝트·단계·업무 CASCADE) 삭제."""
+        with self._pool.connection() as conn:
+            cur = conn.execute("DELETE FROM projects WHERE id = %s", (project_id,))
+            if cur.rowcount == 0:
+                raise KeyError(project_id)
+
+    # ════════════════════════════════════════════════════════════
+    # 멤버
+    # ════════════════════════════════════════════════════════════
+    def list_members(self, *, project_id: int) -> list[dict[str, Any]]:
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                "SELECT * FROM project_members WHERE project_id = %s "
+                "ORDER BY role DESC, user_email ASC",
+                (project_id,),
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def is_member(self, *, project_id: int, user_email: str) -> bool:
+        email = store.norm_str(user_email, lower=True)
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT 1 FROM projects p "
+                "LEFT JOIN project_members m "
+                "  ON m.project_id = p.id AND m.user_email = %s "
+                "WHERE p.id = %s AND (p.owner_email = %s OR m.id IS NOT NULL) LIMIT 1",
+                (email, project_id, email),
+            ).fetchone()
+        return bool(row)
+
+    def add_member(
+        self, *, project_id: int, user_email: str, user_name: str = "", role: str = "member"
+    ) -> dict[str, Any]:
+        email = store.norm_str(user_email, lower=True)
+        if not email or "@" not in email:
+            raise ValueError("올바른 이메일이 아닙니다.")
+        rl = store.validate_role(role)
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                """
+                INSERT INTO project_members (project_id, user_email, user_name, role)
+                VALUES (%s,%s,%s,%s)
+                ON CONFLICT (project_id, user_email) DO UPDATE
+                   SET role = EXCLUDED.role, user_name = EXCLUDED.user_name
+                RETURNING *
+                """,
+                (project_id, email, store.norm_str(user_name), rl),
+            ).fetchone()
+        return self._serialize(row)
+
+    def remove_member(self, *, project_id: int, user_email: str) -> None:
+        email = store.norm_str(user_email, lower=True)
+        with self._pool.connection() as conn:
+            conn.execute(
+                "DELETE FROM project_members WHERE project_id = %s AND user_email = %s",
+                (project_id, email),
+            )
+
+    # ════════════════════════════════════════════════════════════
+    # 단계 (stages)
+    # ════════════════════════════════════════════════════════════
+    def list_stages(self, *, project_id: int) -> list[dict[str, Any]]:
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                "SELECT * FROM project_stages WHERE project_id = %s "
+                "ORDER BY sort_order ASC, id ASC",
+                (project_id,),
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def add_stage(
+        self, *, project_id: int, name: str, is_done_stage: bool = False
+    ) -> dict[str, Any]:
+        nm = store.norm_str(name)
+        if not nm:
+            raise ValueError("단계 이름은 필수입니다.")
+        with self._pool.connection() as conn:
+            nxt = conn.execute(
+                "SELECT COALESCE(MAX(sort_order), -1) + 1 AS n "
+                "FROM project_stages WHERE project_id = %s",
+                (project_id,),
+            ).fetchone()
+            row = conn.execute(
+                "INSERT INTO project_stages (project_id, name, sort_order, is_done_stage) "
+                "VALUES (%s,%s,%s,%s) RETURNING *",
+                (project_id, nm, int(nxt["n"]), bool(is_done_stage)),
+            ).fetchone()
+        return self._serialize(row)
+
+    def delete_stage(self, *, stage_id: int) -> None:
+        with self._pool.connection() as conn:
+            cur = conn.execute("DELETE FROM project_stages WHERE id = %s", (stage_id,))
+            if cur.rowcount == 0:
+                raise KeyError(stage_id)
+
+    # ════════════════════════════════════════════════════════════
+    # 업무 (tasks)
+    # ════════════════════════════════════════════════════════════
+    def list_tasks(
+        self,
+        *,
+        project_id: int | None = None,
+        assignee_email: str | None = None,
+        include_subprojects: bool = False,
+        limit: int = 1000,
+    ) -> list[dict[str, Any]]:
+        clauses: list[str] = []
+        params: list[Any] = []
+        if project_id is not None:
+            if include_subprojects:
+                clauses.append(
+                    "t.project_id IN ("
+                    "  WITH RECURSIVE tree AS ("
+                    "    SELECT id FROM projects WHERE id = %s "
+                    "    UNION ALL "
+                    "    SELECT p.id FROM projects p JOIN tree ON p.parent_id = tree.id"
+                    "  ) SELECT id FROM tree)"
+                )
+                params.append(project_id)
+            else:
+                clauses.append("t.project_id = %s")
+                params.append(project_id)
+        if assignee_email:
+            clauses.append("t.assignee_email = %s")
+            params.append(store.norm_str(assignee_email, lower=True))
+        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+        params.append(int(limit))
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                f"SELECT t.*, p.name AS project_name, p.color AS project_color, "
+                f"       s.name AS stage_name, s.is_done_stage, "
+                f"       (SELECT COUNT(*) FROM task_comments c WHERE c.task_id = t.id) AS comment_count "
+                f"FROM tasks t "
+                f"JOIN projects p ON p.id = t.project_id "
+                f"LEFT JOIN project_stages s ON s.id = t.stage_id "
+                f"{where} "
+                "ORDER BY t.sort_order ASC, t.id ASC LIMIT %s",
+                params,
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def get_task(self, *, task_id: int) -> dict[str, Any] | None:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT t.*, p.name AS project_name, p.color AS project_color, "
+                "       s.name AS stage_name, s.is_done_stage, "
+                "       (SELECT COUNT(*) FROM task_comments c WHERE c.task_id = t.id) AS comment_count "
+                "FROM tasks t JOIN projects p ON p.id = t.project_id "
+                "LEFT JOIN project_stages s ON s.id = t.stage_id "
+                "WHERE t.id = %s",
+                (task_id,),
+            ).fetchone()
+        return self._serialize(row) if row else None
+
+    def create_task(
+        self,
+        *,
+        project_id: int,
+        title: str,
+        stage_id: int | None = None,
+        description: str = "",
+        assignee_email: str = "",
+        assignee_name: str = "",
+        priority: str = "normal",
+        start_date: str | None = None,
+        due_date: str | None = None,
+        start_time: str | None = None,
+        due_time: str | None = None,
+        created_by: str = "",
+    ) -> dict[str, Any]:
+        ttl = store.validate_task_title(title)
+        pr = store.validate_priority(priority)
+        sd = store.validate_date(start_date)
+        dd = store.validate_date(due_date)
+        sti = store.validate_time(start_time)
+        dti = store.validate_time(due_time)
+        assignee = store.norm_str(assignee_email, lower=True)
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                # stage 미지정 시 프로젝트의 첫 단계로
+                if stage_id is None:
+                    st = conn.execute(
+                        "SELECT id FROM project_stages WHERE project_id = %s "
+                        "ORDER BY sort_order ASC, id ASC LIMIT 1",
+                        (project_id,),
+                    ).fetchone()
+                    stage_id = st["id"] if st else None
+                nxt = conn.execute(
+                    "SELECT COALESCE(MAX(sort_order), -1) + 1 AS n FROM tasks "
+                    "WHERE project_id = %s",
+                    (project_id,),
+                ).fetchone()
+                row = conn.execute(
+                    """
+                    INSERT INTO tasks
+                        (project_id, stage_id, title, description, assignee_email,
+                         assignee_name, priority, start_date, due_date,
+                         start_time, due_time, sort_order, created_by)
+                    VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s)
+                    RETURNING *
+                    """,
+                    (
+                        project_id, stage_id, ttl, store.norm_str(description),
+                        assignee, store.norm_str(assignee_name), pr, sd, dd,
+                        sti, dti, int(nxt["n"]), store.norm_str(created_by, lower=True),
+                    ),
+                ).fetchone()
+                if assignee:
+                    self._log(conn, project_id=project_id, task_id=row["id"],
+                              actor=created_by, action=store.ACTION_ASSIGNED,
+                              detail=f"{ttl} → {assignee}")
+        return self.get_task(task_id=row["id"])
+
+    def update_task(
+        self, *, task_id: int, fields: dict[str, Any], actor: str = ""
+    ) -> dict[str, Any]:
+        """업무 수정. 반환에 알림 힌트를 담는다(라우터가 메일 발송 판단).
+
+        반환 dict 에 추가되는 키:
+          _newly_assigned: 새 담당자 이메일 or None
+          _newly_completed: 완료로 전환됐으면 True
+        """
+        prev = self.get_task(task_id=task_id)
+        if prev is None:
+            raise KeyError(task_id)
+
+        sets: list[str] = []
+        params: list[Any] = []
+        newly_assigned: str | None = None
+        newly_completed = False
+
+        if "title" in fields:
+            sets.append("title = %s")
+            params.append(store.validate_task_title(fields["title"]))
+        if "description" in fields:
+            sets.append("description = %s")
+            params.append(store.norm_str(fields["description"]))
+        if "priority" in fields:
+            sets.append("priority = %s")
+            params.append(store.validate_priority(fields["priority"]))
+        if "start_date" in fields:
+            sets.append("start_date = %s")
+            params.append(store.validate_date(fields["start_date"]))
+        if "due_date" in fields:
+            sets.append("due_date = %s")
+            params.append(store.validate_date(fields["due_date"]))
+        if "start_time" in fields:
+            sets.append("start_time = %s")
+            params.append(store.validate_time(fields["start_time"]))
+        if "due_time" in fields:
+            sets.append("due_time = %s")
+            params.append(store.validate_time(fields["due_time"]))
+        if "assignee_email" in fields:
+            new_assignee = store.norm_str(fields["assignee_email"], lower=True)
+            sets.append("assignee_email = %s")
+            params.append(new_assignee)
+            if "assignee_name" in fields:
+                sets.append("assignee_name = %s")
+                params.append(store.norm_str(fields["assignee_name"]))
+            if new_assignee and new_assignee != (prev.get("assignee_email") or ""):
+                newly_assigned = new_assignee
+        elif "assignee_name" in fields:
+            sets.append("assignee_name = %s")
+            params.append(store.norm_str(fields["assignee_name"]))
+
+        # 단계 변경 → 완료단계 진입 시 completed_at 자동 세팅
+        if "stage_id" in fields:
+            new_stage = fields["stage_id"]
+            sets.append("stage_id = %s")
+            params.append(new_stage)
+            done = self._stage_is_done(new_stage)
+            if done and not prev.get("completed_at"):
+                sets.append("completed_at = %s")
+                params.append(now_kst())
+                newly_completed = True
+            elif not done and prev.get("completed_at"):
+                sets.append("completed_at = NULL")
+
+        if not sets:
+            return {**prev, "_newly_assigned": None, "_newly_completed": False}
+
+        params.append(task_id)
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                conn.execute(
+                    f"UPDATE tasks SET {', '.join(sets)} WHERE id = %s", params
+                )
+                if newly_assigned:
+                    self._log(conn, project_id=prev["project_id"], task_id=task_id,
+                              actor=actor, action=store.ACTION_ASSIGNED,
+                              detail=f"{prev['title']} → {newly_assigned}")
+                if newly_completed:
+                    self._log(conn, project_id=prev["project_id"], task_id=task_id,
+                              actor=actor, action=store.ACTION_COMPLETED,
+                              detail=prev["title"])
+        out = self.get_task(task_id=task_id)
+        out["_newly_assigned"] = newly_assigned
+        out["_newly_completed"] = newly_completed
+        return out
+
+    def delete_task(self, *, task_id: int) -> None:
+        with self._pool.connection() as conn:
+            cur = conn.execute("DELETE FROM tasks WHERE id = %s", (task_id,))
+            if cur.rowcount == 0:
+                raise KeyError(task_id)
+
+    def _stage_is_done(self, stage_id: Any) -> bool:
+        if stage_id is None:
+            return False
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT is_done_stage FROM project_stages WHERE id = %s", (stage_id,)
+            ).fetchone()
+        return bool(row and row["is_done_stage"])
+
+    # ════════════════════════════════════════════════════════════
+    # 활동 이력
+    # ════════════════════════════════════════════════════════════
+    def list_activity(self, *, project_id: int, limit: int = 100) -> list[dict[str, Any]]:
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                "SELECT * FROM project_activity WHERE project_id = %s "
+                "ORDER BY created_at DESC, id DESC LIMIT %s",
+                (project_id, int(limit)),
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    @staticmethod
+    def _log(
+        conn: Any, *, project_id: int | None = None, task_id: int | None = None,
+        actor: str = "", action: str = "", detail: str = "",
+    ) -> None:
+        conn.execute(
+            "INSERT INTO project_activity "
+            "(project_id, task_id, actor_email, action, detail) "
+            "VALUES (%s,%s,%s,%s,%s)",
+            (project_id, task_id, store.norm_str(actor, lower=True), action,
+             store.norm_str(detail)),
+        )
+
+    # ════════════════════════════════════════════════════════════
+    # 댓글 (task_comments)
+    # ════════════════════════════════════════════════════════════
+    def list_comments(self, *, task_id: int) -> list[dict[str, Any]]:
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                "SELECT * FROM task_comments WHERE task_id = %s "
+                "ORDER BY created_at ASC, id ASC",
+                (task_id,),
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def add_comment(
+        self, *, task_id: int, author_email: str, author_name: str, body: str
+    ) -> dict[str, Any]:
+        text = store.norm_str(body)
+        if not text:
+            raise ValueError("댓글 내용이 비었습니다.")
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "INSERT INTO task_comments (task_id, author_email, author_name, body) "
+                "VALUES (%s,%s,%s,%s) RETURNING *",
+                (task_id, store.norm_str(author_email, lower=True),
+                 store.norm_str(author_name), text),
+            ).fetchone()
+        return self._serialize(row)
+
+    def update_comment(
+        self, *, comment_id: int, requester: str, is_admin: bool, body: str
+    ) -> dict[str, Any]:
+        text = store.norm_str(body)
+        if not text:
+            raise ValueError("댓글 내용이 비었습니다.")
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT author_email FROM task_comments WHERE id = %s", (comment_id,)
+            ).fetchone()
+            if not row:
+                raise KeyError(comment_id)
+            if not is_admin and row["author_email"] != store.norm_str(requester, lower=True):
+                raise PermissionError("본인 댓글만 수정할 수 있습니다.")
+            out = conn.execute(
+                "UPDATE task_comments SET body = %s WHERE id = %s RETURNING *",
+                (text, comment_id),
+            ).fetchone()
+        return self._serialize(out)
+
+    def delete_comment(self, *, comment_id: int, requester: str, is_admin: bool) -> None:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT author_email FROM task_comments WHERE id = %s", (comment_id,)
+            ).fetchone()
+            if not row:
+                raise KeyError(comment_id)
+            if not is_admin and row["author_email"] != store.norm_str(requester, lower=True):
+                raise PermissionError("본인 댓글만 삭제할 수 있습니다.")
+            conn.execute("DELETE FROM task_comments WHERE id = %s", (comment_id,))
+
+    # ════════════════════════════════════════════════════════════
+    # 첨부 (task_attachments) — 메타만 저장. 파일은 라우터가 디스크 처리.
+    # ════════════════════════════════════════════════════════════
+    def list_attachments(self, *, task_id: int) -> list[dict[str, Any]]:
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                "SELECT * FROM task_attachments WHERE task_id = %s "
+                "ORDER BY created_at DESC, id DESC",
+                (task_id,),
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def add_attachment(
+        self, *, task_id: int, filename: str, stored_name: str,
+        content_type: str, size_bytes: int, uploaded_by: str,
+    ) -> dict[str, Any]:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "INSERT INTO task_attachments "
+                "(task_id, filename, stored_name, content_type, size_bytes, uploaded_by) "
+                "VALUES (%s,%s,%s,%s,%s,%s) RETURNING *",
+                (task_id, store.norm_str(filename), stored_name,
+                 store.norm_str(content_type), int(size_bytes),
+                 store.norm_str(uploaded_by, lower=True)),
+            ).fetchone()
+        return self._serialize(row)
+
+    def get_attachment(self, *, attachment_id: int) -> dict[str, Any] | None:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT * FROM task_attachments WHERE id = %s", (attachment_id,)
+            ).fetchone()
+        return self._serialize(row) if row else None
+
+    def delete_attachment(self, *, attachment_id: int) -> dict[str, Any]:
+        """삭제 후 행(파일 경로 정리용 stored_name 포함)을 반환."""
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "DELETE FROM task_attachments WHERE id = %s RETURNING *", (attachment_id,)
+            ).fetchone()
+        if not row:
+            raise KeyError(attachment_id)
+        return self._serialize(row)
+
+    # ════════════════════════════════════════════════════════════
+    # 단계 순서/이름 편집
+    # ════════════════════════════════════════════════════════════
+    def update_stage(
+        self, *, stage_id: int, name: str | None = None,
+        is_done_stage: bool | None = None,
+    ) -> dict[str, Any]:
+        sets: list[str] = []
+        params: list[Any] = []
+        if name is not None:
+            nm = store.norm_str(name)
+            if not nm:
+                raise ValueError("단계 이름은 필수입니다.")
+            sets.append("name = %s")
+            params.append(nm)
+        if is_done_stage is not None:
+            sets.append("is_done_stage = %s")
+            params.append(bool(is_done_stage))
+        if not sets:
+            raise ValueError("변경할 내용이 없습니다.")
+        params.append(stage_id)
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                f"UPDATE project_stages SET {', '.join(sets)} WHERE id = %s RETURNING *",
+                params,
+            ).fetchone()
+        if not row:
+            raise KeyError(stage_id)
+        return self._serialize(row)
+
+    def reorder_stages(self, *, project_id: int, ordered_ids: list[int]) -> None:
+        """주어진 순서대로 sort_order 재배정. 해당 프로젝트 단계만 갱신."""
+        with self._pool.connection() as conn:
+            with conn.transaction():
+                for i, sid in enumerate(ordered_ids):
+                    conn.execute(
+                        "UPDATE project_stages SET sort_order = %s "
+                        "WHERE id = %s AND project_id = %s",
+                        (i, int(sid), project_id),
+                    )
+
+    # ════════════════════════════════════════════════════════════
+    # 알림센터 (project_notifications)
+    # ════════════════════════════════════════════════════════════
+    def add_notification(
+        self, *, recipient_email: str, actor_email: str = "",
+        project_id: int | None = None, task_id: int | None = None,
+        type: str = "", title: str = "", body: str = "",
+    ) -> None:
+        rcpt = store.norm_str(recipient_email, lower=True)
+        if not rcpt:
+            return
+        # 본인이 본인에게 보내는 알림은 생략(아사나도 자기 행동은 알림 안 함)
+        if rcpt == store.norm_str(actor_email, lower=True):
+            return
+        with self._pool.connection() as conn:
+            conn.execute(
+                "INSERT INTO project_notifications "
+                "(recipient_email, actor_email, project_id, task_id, type, title, body) "
+                "VALUES (%s,%s,%s,%s,%s,%s,%s)",
+                (rcpt, store.norm_str(actor_email, lower=True), project_id, task_id,
+                 type, store.norm_str(title), store.norm_str(body)),
+            )
+
+    def list_notifications(
+        self, *, recipient_email: str, unread_only: bool = False, limit: int = 100
+    ) -> list[dict[str, Any]]:
+        rcpt = store.norm_str(recipient_email, lower=True)
+        clause = "WHERE recipient_email = %s"
+        params: list[Any] = [rcpt]
+        if unread_only:
+            clause += " AND is_read = FALSE"
+        params.append(int(limit))
+        with self._pool.connection() as conn:
+            rows = conn.execute(
+                f"SELECT * FROM project_notifications {clause} "
+                "ORDER BY created_at DESC, id DESC LIMIT %s",
+                params,
+            ).fetchall()
+        return [self._serialize(r) for r in rows]
+
+    def count_unread(self, *, recipient_email: str) -> int:
+        with self._pool.connection() as conn:
+            row = conn.execute(
+                "SELECT COUNT(*) AS n FROM project_notifications "
+                "WHERE recipient_email = %s AND is_read = FALSE",
+                (store.norm_str(recipient_email, lower=True),),
+            ).fetchone()
+        return int(row["n"] or 0)
+
+    def mark_read(self, *, notification_id: int, recipient_email: str) -> None:
+        with self._pool.connection() as conn:
+            conn.execute(
+                "UPDATE project_notifications SET is_read = TRUE "
+                "WHERE id = %s AND recipient_email = %s",
+                (notification_id, store.norm_str(recipient_email, lower=True)),
+            )
+
+    def mark_all_read(self, *, recipient_email: str) -> int:
+        with self._pool.connection() as conn:
+            cur = conn.execute(
+                "UPDATE project_notifications SET is_read = TRUE "
+                "WHERE recipient_email = %s AND is_read = FALSE",
+                (store.norm_str(recipient_email, lower=True),),
+            )
+        return cur.rowcount or 0
+
+    # ════════════════════════════════════════════════════════════
+    # 직렬화
+    # ════════════════════════════════════════════════════════════
+    @staticmethod
+    def _serialize(row: dict[str, Any] | None) -> dict[str, Any] | None:
+        if row is None:
+            return None
+        out = dict(row)
+        for k, v in list(out.items()):
+            if isinstance(v, datetime):
+                out[k] = v.astimezone(KST).isoformat(timespec="seconds")
+            elif isinstance(v, time):
+                out[k] = v.strftime("%H:%M")
+            elif isinstance(v, date):
+                out[k] = v.isoformat()
+        for k in ("id", "parent_id", "project_id", "stage_id", "task_id", "sort_order"):
+            if k in out and out[k] is not None:
+                try:
+                    out[k] = int(out[k])
+                except (TypeError, ValueError):
+                    pass
+        for k in ("is_done_stage", "is_read"):
+            if k in out and out[k] is not None:
+                out[k] = bool(out[k])
+        return out

app/modules/project/store.py

@@ -0,0 +1,136 @@
+"""프로젝트 관리 모듈 — 상수 / 기본값 / 순수 검증 로직.
+
+DB I/O 는 db.py(ProjectStore)가 담당하고, 여기서는 상수와 입력 검증 등
+DB 없이 단위 테스트 가능한 순수 함수만 둔다(malaysia.store 패턴).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# 프로젝트 생성 시 자동으로 깔리는 기본 진행 단계(칸반 컬럼).
+# (name, is_done_stage) — 마지막 '완료' 단계로 옮기면 업무 완료 처리.
+DEFAULT_STAGES: tuple[tuple[str, bool], ...] = (
+    ("할 일", False),
+    ("진행 중", False),
+    ("검토", False),
+    ("완료", True),
+)
+
+# 업무 우선순위
+PRIORITIES: tuple[str, ...] = ("low", "normal", "high")
+PRIORITY_LABELS: dict[str, str] = {"low": "낮음", "normal": "보통", "high": "높음"}
+
+# 프로젝트 상태
+PROJECT_STATUSES: tuple[str, ...] = ("active", "completed", "archived")
+
+# 멤버 역할
+MEMBER_ROLES: tuple[str, ...] = ("manager", "member")
+
+# 활동(activity) 종류 — 메일 트리거/타임라인 표시용
+ACTION_CREATED = "created"
+ACTION_ASSIGNED = "assigned"
+ACTION_COMPLETED = "completed"
+ACTION_STAGE_CHANGED = "stage_changed"
+ACTION_REOPENED = "reopened"
+
+# 프로젝트 색상 팔레트(아사나 느낌) — UI 선택지
+COLOR_PALETTE: tuple[str, ...] = (
+    "#4573d2",  # blue
+    "#37a3a3",  # teal
+    "#62a420",  # green
+    "#e8a33d",  # amber
+    "#e8384f",  # red
+    "#aa62e3",  # purple
+    "#f06a6a",  # coral
+    "#5a6772",  # slate
+)
+
+
+def norm_str(s: Any, *, lower: bool = False) -> str:
+    out = str(s or "").strip()
+    return out.lower() if lower else out
+
+
+def validate_priority(p: Any) -> str:
+    v = norm_str(p, lower=True)
+    return v if v in PRIORITIES else "normal"
+
+
+def validate_role(r: Any) -> str:
+    v = norm_str(r, lower=True)
+    return v if v in MEMBER_ROLES else "member"
+
+
+def validate_project_name(name: Any) -> str:
+    v = norm_str(name)
+    if not v:
+        raise ValueError("프로젝트 이름은 필수입니다.")
+    if len(v) > 200:
+        raise ValueError("프로젝트 이름이 너무 깁니다(200자 이내).")
+    return v
+
+
+def validate_task_title(title: Any) -> str:
+    v = norm_str(title)
+    if not v:
+        raise ValueError("업무 제목은 필수입니다.")
+    if len(v) > 300:
+        raise ValueError("업무 제목이 너무 깁니다(300자 이내).")
+    return v
+
+
+def validate_color(color: Any) -> str:
+    v = norm_str(color)
+    if not v:
+        return COLOR_PALETTE[0]
+    # 매우 단순한 hex 검증 — #RGB / #RRGGBB
+    if v.startswith("#") and len(v) in (4, 7):
+        try:
+            int(v[1:], 16)
+            return v.lower()
+        except ValueError:
+            pass
+    return COLOR_PALETTE[0]
+
+
+def validate_date(d: Any) -> str | None:
+    """'YYYY-MM-DD' 형식만 통과. 빈값은 None."""
+    from datetime import date as _date  # noqa: WPS433
+
+    v = norm_str(d)
+    if not v:
+        return None
+    try:
+        _date.fromisoformat(v[:10])
+    except (ValueError, TypeError):
+        raise ValueError(f"날짜 형식이 올바르지 않습니다: {d}")
+    return v[:10]
+
+
+def validate_time(t: Any) -> str | None:
+    """'HH:MM' 형식만 통과(초는 버림). 빈값/None 은 None(=종일)."""
+    v = norm_str(t)
+    if not v:
+        return None
+    parts = v.split(":")
+    try:
+        hh = int(parts[0])
+        mm = int(parts[1]) if len(parts) > 1 else 0
+    except (ValueError, IndexError):
+        raise ValueError(f"시간 형식이 올바르지 않습니다: {t}")
+    if not (0 <= hh <= 23 and 0 <= mm <= 59):
+        raise ValueError(f"시간 범위가 올바르지 않습니다: {t}")
+    return f"{hh:02d}:{mm:02d}"
+
+
+def build_subject_assigned(*, project_name: str, task_title: str, assignee: str) -> str:
+    return f"[DBX 프로젝트] 업무 배정: {project_name} · {task_title} → {assignee}"
+
+
+def build_subject_completed(*, project_name: str, task_title: str) -> str:
+    return f"[DBX 프로젝트] 업무 완료: {project_name} · {task_title}"
+
+
+def build_subject_project_done(*, project_name: str) -> str:
+    return f"[DBX 프로젝트] 프로젝트 완료: {project_name}"

app/modules/project/templates/project/inbox.html

@@ -0,0 +1,49 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<link rel="stylesheet" href="/static/project.css?v=20260625p" />
+<link rel="stylesheet" href="/static/vendor/material-symbols/material-symbols.css" />
+{% endblock %}
+
+{% block content %}
+<div class="pj-wrap">
+  <div class="pj-section-head">
+    <h2>알림센터</h2>
+    <div style="display:flex; gap:8px;">
+      <a class="pj-btn" href="/project/">← 프로젝트</a>
+      <button type="button" class="pj-btn pj-btn-primary" id="pj-readall">모두 읽음</button>
+    </div>
+  </div>
+
+  {% if not notifications %}
+  <div class="pj-empty">알림이 없습니다.</div>
+  {% else %}
+  <ul class="pj-inbox" id="pj-inbox">
+    {% for n in notifications %}
+    <li class="pj-inbox-item {% if not n.is_read %}is-unread{% endif %}"
+        data-id="{{ n.id }}"
+        {% if n.task_id %}data-project="{{ n.project_id }}"{% endif %}>
+      <span class="material-symbols-outlined pj-inbox-icon">
+        {% if n.type == 'assigned' %}assignment_ind
+        {% elif n.type == 'completed' %}task_alt
+        {% elif n.type == 'comment' %}chat_bubble
+        {% else %}notifications{% endif %}
+      </span>
+      <div class="pj-inbox-body">
+        <div class="pj-inbox-title">{{ n.title }}</div>
+        {% if n.body %}<div class="pj-inbox-sub">{{ n.body }}</div>{% endif %}
+        <div class="pj-inbox-meta">
+          {% if n.actor_email %}{{ n.actor_email.split('@')[0] }} · {% endif %}{{ n.created_at[:16].replace('T',' ') }}
+        </div>
+      </div>
+      {% if n.project_id %}
+      <a class="pj-btn pj-inbox-go" href="/project/p/{{ n.project_id }}">이동</a>
+      {% endif %}
+    </li>
+    {% endfor %}
+  </ul>
+  {% endif %}
+</div>
+
+<script src="/static/project.js?v=20260625p" defer></script>
+{% endblock %}

app/modules/project/templates/project/index.html

@@ -0,0 +1,171 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<link rel="stylesheet" href="/static/project.css?v=20260626b" />
+<link rel="stylesheet" href="/static/vendor/material-symbols/material-symbols.css" />
+{% endblock %}
+
+{% block content %}
+<div class="pj-wrap" data-is-admin="{{ 'true' if is_admin else 'false' }}"
+     data-is-super="{{ 'true' if user.is_super_admin else 'false' }}"
+     data-me="{{ user.email }}">
+
+  <div class="pj-home">
+    <!-- 프로젝트 목록 -->
+    <section class="pj-home-main">
+      <div class="pj-section-head">
+        <h2>프로젝트</h2>
+        <div class="pj-toolbar-right">
+          {% set done_count = tree | selectattr('status', 'equalto', 'completed') | list | length %}
+          {% if done_count %}
+          <button type="button" class="pj-btn" id="pj-toggle-done" data-count="{{ done_count }}">
+            완료 {{ done_count }}개 숨기기
+          </button>
+          {% endif %}
+          <a class="pj-bell" href="/project/inbox" title="알림센터">
+            <span class="material-symbols-outlined">notifications</span>
+            <span class="pj-bell-badge" id="pj-bell-badge" hidden>0</span>
+          </a>
+          {% if is_admin %}
+          <button type="button" class="pj-btn pj-btn-primary" id="pj-new-project">
+            + 새 프로젝트
+          </button>
+          {% endif %}
+        </div>
+      </div>
+
+      {% if not tree %}
+      <div class="pj-empty">
+        아직 프로젝트가 없습니다.
+        {% if is_admin %}상단의 <b>새 프로젝트</b> 버튼으로 만들어 보세요.
+        {% else %}관리자가 프로젝트에 배정하면 여기에 표시됩니다.{% endif %}
+      </div>
+      {% endif %}
+
+      <div class="pj-project-grid" id="pj-project-grid">
+        {% for p in tree %}
+        <div class="pj-project-card {% if p.status == 'completed' %}is-done{% endif %}"
+             style="--pj-color: {{ p.color }}"
+             data-id="{{ p.id }}"
+             data-name="{{ p.name }}"
+             data-desc="{{ p.description or '' }}"
+             data-start="{{ p.start_date or '' }}"
+             data-due="{{ p.due_date or '' }}"
+             data-color="{{ p.color }}"
+             data-status="{{ p.status or 'active' }}"
+             data-creator="{{ p.created_by or '' }}">
+          <a class="pj-project-cardlink" href="/project/p/{{ p.id }}">
+            <span class="pj-project-dot"></span>
+            <div class="pj-project-body">
+              <div class="pj-project-name">{{ p.name }}
+                {% if p.status == 'completed' %}<span class="pj-chip pj-chip-sm">완료</span>{% endif %}
+              </div>
+              {% if p.description %}<div class="pj-project-desc">{{ p.description }}</div>{% endif %}
+              <div class="pj-project-meta">
+                {% if p.due_date %}<span class="pj-chip">마감 {{ p.due_date }}</span>{% endif %}
+              </div>
+            </div>
+          </a>
+          {% if is_admin %}
+          <button type="button" class="pj-icon-btn pj-card-edit" title="프로젝트 수정">
+            <span class="material-symbols-outlined">edit</span>
+          </button>
+          {% endif %}
+        </div>
+        {% endfor %}
+      </div>
+    </section>
+
+    <!-- 내 업무 -->
+    <aside class="pj-home-side">
+      <div class="pj-section-head"><h2>내 업무</h2></div>
+      {% if not my_projects %}
+      <div class="pj-empty pj-empty-sm">배정된 업무가 없습니다.</div>
+      {% else %}
+      <div class="pj-mytree">
+        {% for p in my_projects %}
+        <div class="pj-mytree-group">
+          <a class="pj-mytree-proj" href="/project/p/{{ p.id }}">
+            <span class="material-symbols-outlined" style="color: {{ p.color }}; font-size:18px;">folder</span>
+            <span class="pj-mytree-proj-name">{{ p.name }}</span>
+          </a>
+          <ul class="pj-mytree-tasks">
+            {% for t in p.tasks %}
+            <li class="pj-mytree-task {% if t.completed_at %}is-done{% endif %}">
+              <a href="/project/p/{{ t.project_id }}?task={{ t.id }}">
+                <span class="material-symbols-outlined pj-mytree-ic" style="color: {{ t.project_color }};">{% if t.completed_at %}task_alt{% else %}radio_button_unchecked{% endif %}</span>
+                <span class="pj-mytree-body">
+                  <span class="pj-mytree-title">{{ t.title }}</span>
+                  {% if t.start_date or t.due_date %}
+                  <span class="pj-mytree-dates">
+                    {% if t.start_date and t.due_date %}{{ t.start_date }} ~ {{ t.due_date }}
+                    {% elif t.due_date %}~ {{ t.due_date }}
+                    {% else %}{{ t.start_date }} ~{% endif %}
+                  </span>
+                  {% endif %}
+                </span>
+              </a>
+            </li>
+            {% endfor %}
+          </ul>
+        </div>
+        {% endfor %}
+      </div>
+      {% endif %}
+    </aside>
+  </div>
+</div>
+
+<!-- 새 프로젝트 모달 -->
+{% if is_admin %}
+<div class="pj-modal" id="pj-modal-project" hidden>
+  <div class="pj-modal-card">
+    <h3>새 프로젝트</h3>
+    <label>이름<input type="text" id="pj-f-name" placeholder="프로젝트 이름" /></label>
+    <label>설명<textarea id="pj-f-desc" rows="2"></textarea></label>
+    <div class="pj-form-row">
+      <label>시작일<input type="date" id="pj-f-start" /></label>
+      <label>마감일<input type="date" id="pj-f-due" /></label>
+    </div>
+    <label>색상
+      <span class="pj-color-palette" id="pj-f-colors"></span>
+    </label>
+    <div class="pj-modal-actions">
+      <button type="button" class="pj-btn" data-close>취소</button>
+      <button type="button" class="pj-btn pj-btn-primary" id="pj-save-project">만들기</button>
+    </div>
+  </div>
+</div>
+
+<!-- 프로젝트 수정 모달 -->
+<div class="pj-modal" id="pj-modal-edit" hidden>
+  <div class="pj-modal-card">
+    <h3>프로젝트 수정</h3>
+    <input type="hidden" id="pj-e-id" />
+    <label>이름<input type="text" id="pj-e-name" placeholder="프로젝트 이름" /></label>
+    <label>설명<textarea id="pj-e-desc" rows="2"></textarea></label>
+    <div class="pj-form-row">
+      <label>시작일<input type="date" id="pj-e-start" /></label>
+      <label>마감일<input type="date" id="pj-e-due" /></label>
+    </div>
+    <label>색상
+      <span class="pj-color-palette" id="pj-e-colors"></span>
+    </label>
+    <label class="pj-time-toggle">
+      <input type="checkbox" id="pj-e-done" /> 프로젝트 완료 (목록 끝으로 이동·비활성)
+    </label>
+    <div class="pj-modal-actions">
+      <button type="button" class="pj-btn pj-btn-danger" id="pj-delete-project">삭제</button>
+      <span style="flex:1"></span>
+      <button type="button" class="pj-btn" data-close>취소</button>
+      <button type="button" class="pj-btn pj-btn-primary" id="pj-save-edit">저장</button>
+    </div>
+  </div>
+</div>
+{% endif %}
+
+<script>
+  window.PJ_COLORS = {{ ["#4573d2","#37a3a3","#62a420","#e8a33d","#e8384f","#aa62e3","#f06a6a","#5a6772"] | tojson }};
+</script>
+<script src="/static/project.js?v=20260626b" defer></script>
+{% endblock %}

app/modules/project/templates/project/project.html

@@ -0,0 +1,295 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}
+<link rel="stylesheet" href="/static/project.css?v=20260626b" />
+<!-- 구글 머티리얼 심볼(담당자 아이콘 등) — self-host -->
+<link rel="stylesheet" href="/static/vendor/material-symbols/material-symbols.css" />
+<!-- 타임라인 vis-timeline — self-host -->
+<link href="/static/vendor/vis-timeline/vis-timeline-graph2d.min.css" rel="stylesheet" />
+{% endblock %}
+
+{% block topbar_actions %}
+<a class="pj-bell" href="/project/inbox" title="알림센터">
+  <span class="material-symbols-outlined">notifications</span>
+  <span class="pj-bell-badge" id="pj-bell-badge" hidden>0</span>
+</a>
+{% if can_manage %}
+<button type="button" class="pj-btn pj-btn-primary" id="pj-new-task">+ 업무 추가</button>
+{% endif %}
+{% endblock %}
+
+{% block content %}
+<div class="pj-wrap pj-project-view"
+     data-project-id="{{ project.id }}"
+     data-can-manage="{{ 'true' if can_manage else 'false' }}"
+     data-is-admin="{{ 'true' if is_admin else 'false' }}"
+     data-is-super="{{ 'true' if user.is_super_admin else 'false' }}"
+     data-me="{{ user.email }}">
+
+  <div class="pj-layout">
+    <!-- ── 좌측: 프로젝트 트리 + 멤버 ── -->
+    <aside class="pj-side">
+      <div class="pj-side-block">
+        <div class="pj-side-head">
+          <span>프로젝트</span>
+          {% if is_admin %}
+          <button type="button" class="pj-icon-btn" id="pj-new-project-side" title="새 프로젝트">+</button>
+          {% endif %}
+        </div>
+        {% if nav_projects %}
+        <ul class="pj-tree" id="pj-tree-root">
+          {% for p in nav_projects %}
+          <li class="pj-tree-li" data-id="{{ p.id }}">
+            <div class="pj-tree-row {% if p.id == project.id %}is-active{% endif %}">
+              {% if p.tasks %}
+              <button type="button" class="pj-tree-caret" aria-expanded="false" title="펼치기/접기">
+                <span class="material-symbols-outlined">chevron_right</span>
+              </button>
+              {% else %}
+              <span class="pj-tree-caret-spacer"></span>
+              {% endif %}
+              <a class="pj-tree-link" href="/project/p/{{ p.id }}">
+                <span class="pj-tree-icon material-symbols-outlined" style="color: {{ p.color }}">folder</span>
+                <span class="pj-tree-name">{{ p.name }}</span>
+              </a>
+              {% if is_admin %}
+              <span class="pj-tree-acts">
+                <button type="button" class="pj-icon-btn pj-tree-del" data-id="{{ p.id }}" data-name="{{ p.name }}" data-creator="{{ p.created_by }}" title="프로젝트 삭제">×</button>
+              </span>
+              {% endif %}
+            </div>
+            {% if p.tasks %}
+            <div class="pj-tree-children" hidden>
+              <ul class="pj-tree">
+                {% for t in p.tasks %}
+                <li class="pj-tree-li pj-tree-task">
+                  <div class="pj-tree-row" style="--pj-indent: 1">
+                    <span class="pj-tree-caret-spacer"></span>
+                    <a class="pj-tree-link pj-tree-tasklink"
+                       href="/project/p/{{ p.id }}?task={{ t.id }}"
+                       data-project="{{ p.id }}" data-task="{{ t.id }}">
+                      <span class="pj-tree-icon material-symbols-outlined" style="color: {{ t.color }}">{% if t.completed %}task_alt{% else %}radio_button_unchecked{% endif %}</span>
+                      <span class="pj-tree-name {% if t.completed %}pj-tree-done{% endif %}">{{ t.title }}</span>
+                    </a>
+                  </div>
+                </li>
+                {% endfor %}
+              </ul>
+            </div>
+            {% endif %}
+          </li>
+          {% endfor %}
+        </ul>
+        {% else %}
+        <div class="pj-empty-sm">프로젝트 없음</div>
+        {% endif %}
+      </div>
+
+      <div class="pj-side-block">
+        <div class="pj-side-head">
+          <span>멤버</span>
+          {% if is_admin %}
+          <button type="button" class="pj-icon-btn" id="pj-add-member" title="멤버 배정">+</button>
+          {% endif %}
+        </div>
+        <ul class="pj-member-list" id="pj-member-list">
+          {% for m in members %}
+          <li>
+            <span class="material-symbols-outlined pj-gicon">account_circle</span>
+            <span class="pj-member-name">{{ m.user_email.split('@')[0] }}</span>
+            {% if m.role == 'manager' %}<span class="pj-chip pj-chip-sm">관리</span>{% endif %}
+            {% if is_admin %}
+            <button type="button" class="pj-icon-btn pj-del-member" data-email="{{ m.user_email }}" title="제외">×</button>
+            {% endif %}
+          </li>
+          {% else %}
+          <li class="pj-empty-sm">없음</li>
+          {% endfor %}
+        </ul>
+      </div>
+    </aside>
+
+    <!-- ── 우측: 뷰 ── -->
+    <section class="pj-main">
+      <div class="pj-toolbar">
+        <div class="pj-view-tabs" id="pj-view-tabs">
+          <button type="button" class="pj-tab is-active" data-view="calendar">달력</button>
+          <button type="button" class="pj-tab" data-view="timeline">타임라인</button>
+          <button type="button" class="pj-tab" data-view="board">보드</button>
+          <button type="button" class="pj-tab" data-view="list">리스트</button>
+        </div>
+      </div>
+
+      <!-- 달력 (휴가 모듈과 동일한 월간 그리드) -->
+      <div class="pj-view" data-view="calendar">
+        <div class="pj-cal-head">
+          <a class="pj-btn pj-nav-btn" href="/project/p/{{ project.id }}?y={{ prev_y }}&m={{ prev_m }}">‹</a>
+          <h2 class="pj-cal-title">{{ year }}년 {{ month }}월</h2>
+          <a class="pj-btn pj-nav-btn" href="/project/p/{{ project.id }}?y={{ next_y }}&m={{ next_m }}">›</a>
+          <a class="pj-btn pj-today-btn" href="/project/p/{{ project.id }}">오늘</a>
+        </div>
+
+        <div class="pj-cal">
+          <div class="pj-wd-row">
+            {% for wd in weekdays %}
+            <div class="pj-wd {% if loop.index0 == 0 %}pj-red{% elif loop.index0 == 6 %}pj-blue{% endif %}">{{ wd }}</div>
+            {% endfor %}
+          </div>
+
+          {% for week in weeks %}
+          <div class="pj-week">
+            <div class="pj-week-days">
+              {% for cell in week.days %}
+              <div class="pj-day {% if not cell.in_month %}pj-out{% endif %} {% if cell.is_today %}pj-today{% endif %}"
+                   data-date="{{ cell.date }}">
+                <span class="pj-day-num
+                             {% if cell.is_sunday %}pj-red{% elif cell.is_saturday %}pj-blue{% endif %}">{{ cell.day }}</span>
+              </div>
+              {% endfor %}
+            </div>
+
+            <!-- 막대는 클라이언트(JS)가 그린다 — 깔끔한 칩 + 행 제한(+N) + 드래그 이동 -->
+            <div class="pj-week-bars"></div>
+          </div>
+          {% endfor %}
+        </div>
+      </div>
+      <!-- 타임라인 -->
+      <div class="pj-view" data-view="timeline" hidden>
+        <div id="pj-timeline"></div>
+      </div>
+      <!-- 보드(칸반) -->
+      <div class="pj-view" data-view="board" hidden>
+        <div class="pj-board" id="pj-board"></div>
+      </div>
+      <!-- 리스트 -->
+      <div class="pj-view" data-view="list" hidden>
+        <table class="pj-table" id="pj-list">
+          <thead>
+            <tr><th>업무</th><th>담당자</th><th>단계</th><th>우선순위</th><th>시작</th><th>마감</th></tr>
+          </thead>
+          <tbody></tbody>
+        </table>
+      </div>
+    </section>
+  </div>
+</div>
+
+<!-- 업무 모달 -->
+<div class="pj-modal" id="pj-modal-task" hidden>
+  <div class="pj-modal-card">
+    <h3 id="pj-task-modal-title">새 업무</h3>
+    <input type="hidden" id="pj-t-id" />
+    <label>제목<input type="text" id="pj-t-title" placeholder="업무 제목" /></label>
+    <label>설명<textarea id="pj-t-desc" rows="2"></textarea></label>
+    <div class="pj-form-row">
+      <label>담당자
+        <select id="pj-t-assignee">
+          <option value="">(미지정)</option>
+          {% for m in members %}
+          <option value="{{ m.user_email }}" data-name="{{ m.user_email.split('@')[0] }}">
+            {{ m.user_email.split('@')[0] }}
+          </option>
+          {% endfor %}
+        </select>
+      </label>
+      <label>단계
+        <select id="pj-t-stage">
+          {% for s in stages %}
+          <option value="{{ s.id }}">{{ s.name }}</option>
+          {% endfor %}
+        </select>
+      </label>
+    </div>
+    <div class="pj-form-row">
+      <label>우선순위
+        <select id="pj-t-priority">
+          <option value="low">낮음</option>
+          <option value="normal" selected>보통</option>
+          <option value="high">높음</option>
+        </select>
+      </label>
+      <label>시작일<input type="date" id="pj-t-start" /></label>
+      <label>마감일<input type="date" id="pj-t-due" /></label>
+    </div>
+    <label class="pj-time-toggle">
+      <input type="checkbox" id="pj-t-usetime" /> 시간 지정 (체크 안 하면 종일)
+    </label>
+    <div class="pj-form-row" id="pj-time-row">
+      <label>시작 시간<input type="time" id="pj-t-stime" disabled /></label>
+      <label>마감 시간<input type="time" id="pj-t-dtime" disabled /></label>
+    </div>
+    <!-- 첨부파일 (기존 업무 편집 시에만) -->
+    <div class="pj-task-extra" id="pj-attach-block" hidden>
+      <div class="pj-extra-head">
+        <span class="material-symbols-outlined pj-gicon pj-gicon-sm">attach_file</span> 첨부파일
+        <label class="pj-upload-btn">
+          파일 추가<input type="file" id="pj-attach-input" hidden />
+        </label>
+      </div>
+      <ul class="pj-attach-list" id="pj-attach-list"></ul>
+    </div>
+
+    <!-- 댓글 (기존 업무 편집 시에만) -->
+    <div class="pj-task-extra" id="pj-comment-block" hidden>
+      <div class="pj-extra-head">
+        <span class="pj-cmt-emoji">💬</span> 댓글
+      </div>
+      <ul class="pj-comment-list" id="pj-comment-list"></ul>
+      <div class="pj-comment-form">
+        <input type="text" id="pj-comment-input" placeholder="댓글 입력…" />
+        <button type="button" class="pj-btn pj-btn-primary" id="pj-comment-send">등록</button>
+      </div>
+    </div>
+
+    <div class="pj-modal-actions">
+      <button type="button" class="pj-btn pj-btn-danger" id="pj-delete-task" hidden>삭제</button>
+      <span style="flex:1"></span>
+      <button type="button" class="pj-btn" data-close>취소</button>
+      <button type="button" class="pj-btn pj-btn-primary" id="pj-save-task">저장</button>
+    </div>
+  </div>
+</div>
+
+{% if is_admin %}
+<!-- 멤버 배정 모달 — 등록된 사용자(프로젝트 권한 보유)를 자동 목록화 -->
+<div class="pj-modal" id="pj-modal-member" hidden>
+  <div class="pj-modal-card">
+    <h3>멤버 배정</h3>
+    <p class="pj-modal-hint">관리자 페이지에서 <b>프로젝트 관리</b> 권한을 켠 직원이 후보로 나옵니다.</p>
+    <label>직원
+      <select id="pj-m-user"><option value="">불러오는 중…</option></select>
+    </label>
+    <label>역할
+      <select id="pj-m-role">
+        <option value="member" selected>멤버</option>
+        <option value="manager">관리(서브·업무 관리)</option>
+      </select>
+    </label>
+    <div class="pj-modal-actions">
+      <span style="flex:1"></span>
+      <button type="button" class="pj-btn" data-close>취소</button>
+      <button type="button" class="pj-btn pj-btn-primary" id="pj-save-member">배정</button>
+    </div>
+  </div>
+</div>
+{% endif %}
+
+<!-- 데이터 -->
+<script id="pj-data" type="application/json">
+{
+  "project": {{ project | tojson }},
+  "stages": {{ stages | tojson }},
+  "tasks": {{ tasks | tojson }},
+  "members": {{ members | tojson }},
+  "priorityLabels": {{ priority_labels | tojson }},
+  "projects": {{ projects_meta | tojson }},
+  "stagesByProject": {{ stages_by_project | tojson }},
+  "boardStages": {{ board_stage_names | tojson }},
+  "avatars": {{ avatars | tojson }}
+}
+</script>
+
+<script src="/static/vendor/vis-timeline/vis-timeline-graph2d.min.js"></script>
+<script src="/static/project.js?v=20260626b" defer></script>
+{% endblock %}

app/static/cafe24.css

@@ -0,0 +1,805 @@
+/* 카페24 상품관리 모듈 전용 스타일.
+   전역(erp.css) 은 건드리지 않는다. 클래스 접두사: cf24-
+   색상은 erp.css 의 :root 토큰을 재사용한다. */
+
+/* .erp-page 는 flex column + overflow-y:auto 다. 자식의 flex-shrink 기본값이
+   1 이라 내용이 화면보다 길면 카드가 눌려 잘리고(스크롤도 안 생긴다),
+   시스템 화면의 [카페24 연결] 버튼처럼 카드 아래쪽이 사라진다.
+   축소를 막아 넘친 만큼 .erp-page 가 스크롤하게 한다.
+   이 파일은 카페24 템플릿에서만 로드되므로 다른 모듈에는 영향이 없다. */
+.erp-page > * {
+  flex-shrink: 0;
+}
+
+/* 2분할 화면은 편집 영역을 최대한 넓게 쓴다 — 이 페이지에서만 폭 제한을 푼다.
+   box-sizing 을 함께 바꿔야 한다: .erp-page 는 width:100% + padding:24px 라서
+   max-width 를 풀면 padding 이 폭에 더해져 문서 전체에 가로 스크롤이 생긴다. */
+.erp-page {
+  max-width: none;
+  box-sizing: border-box;
+}
+
+.cf24-card {
+  margin-bottom: var(--sp-16, 16px);
+}
+
+/* ════════════════════════════════════════════════════════════
+   좌우 2분할: 왼쪽 목록(좁게) | 오른쪽 상세페이지 편집(넓게)
+   각 칸이 따로 스크롤되고, 전체 높이는 화면에 맞춘다.
+   ════════════════════════════════════════════════════════════ */
+.cf24-split {
+  display: grid;
+  grid-template-columns: 550px minmax(0, 1fr);
+  gap: var(--sp-12, 12px);
+  align-items: stretch;
+}
+
+/* .erp-page 는 flex column 이다. 위 flex-shrink:0 규칙의 예외로, 분할 영역만은
+   남은 높이를 모두 차지하고 안에서 스크롤되게 한다(휴가/쿠팡 모듈과 같은 방식). */
+.erp-page > .cf24-split {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+.cf24-pane {
+  min-height: 0;
+  overflow: auto;
+  margin-bottom: 0;
+  padding: var(--sp-12, 12px);
+}
+
+.cf24-pane-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-8, 8px);
+  overflow: hidden; /* 표만 스크롤 — 검색/필터는 고정 */
+}
+
+.cf24-pane-editor {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-8, 8px);
+  padding: var(--sp-16, 16px);
+}
+
+@media (max-width: 1100px) {
+  .cf24-split {
+    grid-template-columns: minmax(0, 1fr);
+  }
+  .cf24-pane {
+    overflow: visible;
+  }
+  .cf24-pane-list {
+    max-height: 45vh;
+  }
+}
+
+/* ── 왼쪽: 검색·필터 ── */
+.cf24-filters {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sp-8, 8px);
+  flex: 0 0 auto;
+}
+
+.cf24-checks {
+  display: flex;
+  gap: var(--sp-12, 12px);
+  font-size: var(--text-caption, 12px);
+}
+
+.cf24-checks label {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  cursor: pointer;
+}
+
+.cf24-list-count {
+  font-size: var(--text-caption, 12px);
+  color: var(--color-midtone-gray, #737373);
+}
+
+/* ── 왼쪽: 목록 표 (좁게) ── */
+.cf24-list-scroll {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+.cf24-list-table {
+  font-size: 12px;
+  table-layout: fixed;
+  width: 100%;
+}
+
+.cf24-list-table thead th {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  padding: 6px 4px;
+  white-space: nowrap;
+}
+
+.cf24-list-table tbody td {
+  padding: 6px 4px;
+  vertical-align: top;
+}
+
+/* 목록 폭 550px 기준. 고정폭을 뺀 나머지(약 290px)가 상품명 몫이다.
+   진열/판매 칸은 제목(2글자) + 정렬 화살표가 들어갈 만큼만. */
+.cf24-col-no   { width: 40px; text-align: right; color: var(--color-midtone-gray, #737373); }
+.cf24-col-flag { width: 40px; text-align: center; }
+.cf24-col-date { width: 78px; white-space: nowrap; color: var(--color-midtone-gray, #737373); }
+.cf24-col-name { word-break: break-word; }
+
+/* 긴 상품명은 2줄까지만 — 행 높이를 고르게 유지해 목록을 훑기 쉽게 한다.
+   전체 이름은 title 툴팁과 오른쪽 편집기 제목에서 확인한다. */
+.cf24-col-name a {
+  color: inherit;
+  text-decoration: none;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  line-height: 1.4;
+}
+
+.cf24-row {
+  cursor: pointer;
+}
+
+.cf24-row:hover {
+  background: var(--color-ghost-gray, #f2f2f2);
+}
+
+.cf24-row.is-active {
+  background: var(--color-rich-black, #0a0a0a);
+}
+
+/* 선택된 행은 마우스를 올려도 그대로 둔다. erp-shell.css 의
+   `.erp-table tbody tr:hover` 가 특이도가 더 높아 검은 배경을 덮어쓰므로
+   여기서 더 구체적인 선택자로 되돌린다. */
+.cf24-list-table tbody tr.cf24-row.is-active:hover {
+  background: var(--color-rich-black, #0a0a0a);
+}
+
+.cf24-row.is-active td,
+.cf24-row.is-active .cf24-col-name a {
+  color: #fff;
+}
+
+/* 진열/판매 표시는 좁은 칸이라 배지 대신 점으로 */
+.cf24-dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--color-subtle-ash, #e5e5e5);
+}
+
+.cf24-dot-on {
+  background: var(--color-success-green, #10c22b);
+}
+
+/* 제목행 클릭 정렬 */
+.cf24-sortable {
+  cursor: pointer;
+  user-select: none;
+}
+
+.cf24-sortable::after {
+  content: "↕";
+  opacity: 0.35;
+  margin-left: 2px;
+}
+
+.cf24-sortable.is-asc::after  { content: "▲"; opacity: 1; }
+.cf24-sortable.is-desc::after { content: "▼"; opacity: 1; }
+
+/* ── 오른쪽: 편집기 ── */
+.cf24-editor-head {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: var(--sp-12, 12px);
+  flex: 0 0 auto;
+}
+
+.cf24-editor-title {
+  margin: 0;
+  font-size: var(--text-heading, 18px);
+  letter-spacing: -0.45px;
+}
+
+/* 상품명 수정 — 평소엔 제목, 연필을 누르면 입력칸으로 바뀐다 */
+/* 입력칸이 남는 폭을 다 쓰게 한다(min-width:0 이 없으면 긴 이름이 배지를 밀어낸다) */
+.cf24-name-box {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.cf24-name-box .is-hidden {
+  display: none;
+}
+
+.cf24-name-edit {
+  margin-left: var(--sp-6, 6px);
+  padding: 0 4px;
+  border: 0;
+  border-radius: var(--r-sm, 4px);
+  background: transparent;
+  color: var(--color-midtone-gray, #737373);
+  font-size: var(--text-body, 14px);
+  line-height: 1.4;
+  cursor: pointer;
+  vertical-align: middle;
+}
+
+.cf24-name-edit:hover {
+  background: var(--color-ghost-gray, #f2f2f2);
+  color: var(--color-rich-black, #0a0a0a);
+}
+
+.cf24-name-form {
+  display: flex;
+  align-items: center;
+  gap: var(--sp-6, 6px);
+}
+
+.cf24-name-input {
+  flex: 1 1 auto;
+  min-width: 200px;
+  padding: var(--sp-6, 6px) var(--sp-8, 8px);
+  border: 1px solid var(--color-subtle-ash, #e5e5e5);
+  border-radius: var(--r-md, 6px);
+  font-size: var(--text-heading, 18px);
+  letter-spacing: -0.45px;
+}
+
+.cf24-name-input:focus {
+  outline: none;
+  border-color: var(--color-rich-black, #0a0a0a);
+}
+
+.cf24-editor-sub {
+  margin: 4px 0 0;
+  font-size: var(--text-caption, 12px);
+  color: var(--color-midtone-gray, #737373);
+}
+
+.cf24-editor-badges {
+  display: flex;
+  gap: 4px;
+  flex: 0 0 auto;
+}
+
+/* 편집기 단축키 안내 — 옅은 파랑으로 본문과 구분한다 */
+.cf24-shortcuts {
+  font-size: var(--text-caption, 12px);
+  color: #79a6dd;
+  white-space: nowrap;
+}
+
+/* 편집 폼과 코드 칸은 **줄어들지 않는다.** 아래 「예약 적용」·「버전 이력」을 펼치면
+   코드 칸이 눌리는 대신 내용이 아래로 밀리고 오른쪽 칸(.cf24-pane-editor)이 스크롤된다.
+   flex: 1 1 auto 였을 때는 펼칠 때마다 편집기가 작아져 작업하던 위치를 잃었다. */
+.cf24-editor-form {
+  display: flex;
+  flex-direction: column;
+  flex: 0 0 auto;
+  gap: var(--sp-8, 8px);
+}
+
+.cf24-editor-bar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: var(--sp-8, 8px);
+  flex-wrap: wrap;
+  flex: 0 0 auto;
+}
+
+.cf24-editor-bar-right {
+  display: flex;
+  gap: var(--sp-8, 8px);
+  align-items: center;
+}
+
+.cf24-check-inline {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  margin-left: var(--sp-12, 12px);
+  cursor: pointer;
+  color: var(--color-rich-black, #0a0a0a);
+}
+
+.cf24-memo {
+  width: 260px;
+  padding: 6px var(--sp-10, 10px);
+  border: 1px solid var(--color-subtle-ash, #e5e5e5);
+  border-radius: var(--r-lg, 10px);
+  font-size: 12px;
+}
+
+.cf24-html-main {
+  flex: 1 1 auto;
+  min-height: 340px;
+}
+
+/* ════════════════════════════════════════════════════════════
+   문법 강조 편집기
+   투명한 <textarea> 를 색칠된 <pre> 위에 정확히 겹쳐 놓는 방식이다.
+   두 요소의 폰트·줄높이·여백·줄바꿈 규칙이 **완전히 같아야** 글자가 어긋나지
+   않는다. 아래 두 선택자에 붙은 속성을 바꿀 때는 반드시 함께 바꿀 것.
+   외부 라이브러리를 쓰지 않는다(자체 호스팅 원칙 + CDN 의존 제거).
+   ════════════════════════════════════════════════════════════ */
+/* 스크롤은 **textarea 가** 담당하고, 색칠 층과 줄 번호가 transform 으로 따라간다.
+   폭·높이를 계산해 맞추는 방식은 flex 안에서 `width: max-content` 가 기대대로
+   동작하지 않아 실패했다 — 긴 줄이 있으면 textarea 만 내부 스크롤되고 색칠 층은
+   제자리에 남아, 커서 위치와 보이는 글자가 어긋났다(실측 706 vs 686).
+   스크롤 동기화 방식은 크기 계산이 아예 필요 없어 어긋날 여지가 없다. */
+.cf24-code {
+  position: relative;
+  /* 화면 높이에 맞춰 크되(창 크기에 적응), 무엇을 펼쳐도 이 높이를 유지한다.
+     56vh 는 접힌 상태에서 「예약 적용」·「버전 이력」 요약줄까지 스크롤 없이
+     들어오는 값이다(실측: 62vh 는 51px 넘쳤고 56vh 는 0). */
+  flex: 0 0 auto;
+  height: 56vh;
+  min-height: 340px;
+  overflow: hidden;
+  border: 1px solid var(--color-subtle-ash, #e5e5e5);
+  border-radius: var(--r-lg, 10px);
+  background: var(--color-canvas-white, #fff);
+}
+
+/* 줄 번호 — 코드 영역 왼쪽에 고정된 별도 칸(가로 스크롤과 무관) */
+.cf24-gutter {
+  position: absolute;
+  left: 0;
+  top: 0;
+  bottom: 0;
+  width: 42px;
+  overflow: hidden;
+  padding: var(--sp-12, 12px) var(--sp-8, 8px) 0 0;
+  text-align: right;
+  background: var(--color-ghost-gray, #f6f8fa);
+  border-right: 1px solid var(--color-subtle-ash, #e5e5e5);
+  color: #8c959f;
+  user-select: none;
+  white-space: pre;
+}
+
+.cf24-gutter-inner {
+  will-change: transform; /* 세로 스크롤을 따라 움직인다 */
+}
+
+.cf24-code-body {
+  position: absolute;
+  left: 43px; /* 줄 번호 칸 + 경계선 */
+  right: 0;
+  top: 0;
+  bottom: 0;
+  overflow: hidden;
+}
+
+/* 두 층의 글자가 정확히 겹치려면 아래 속성이 전부 같아야 한다.
+   줄 번호(.cf24-gutter)도 같은 글꼴 지표를 써야 줄이 맞는다. */
+.cf24-gutter,
+.cf24-code-hl,
+.cf24-code-input {
+  margin: 0;
+  border: 0;
+  box-sizing: border-box;
+  font-family: var(--font-geist-mono, ui-monospace, "Consolas", monospace);
+  font-size: 12px;
+  line-height: 1.6;
+  tab-size: 2;
+}
+
+.cf24-code-hl,
+.cf24-code-input {
+  padding: var(--sp-12, 12px);
+  white-space: pre; /* 줄바꿈하지 않는다 — 줄 번호가 어긋나지 않게 */
+  overflow-wrap: normal;
+}
+
+/* 색칠 층 — textarea 의 스크롤량만큼 transform 으로 이동한다. */
+.cf24-code-hl {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: max-content;
+  min-width: 100%;
+  pointer-events: none;
+  color: var(--color-rich-black, #0a0a0a);
+  will-change: transform;
+}
+
+/* textarea 가 실제 스크롤 주체다. */
+.cf24-code-input {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  display: block;
+  background: transparent;
+  color: transparent;
+  caret-color: var(--color-rich-black, #0a0a0a);
+  resize: none;
+  overflow: auto;
+}
+
+.cf24-code-input:focus {
+  outline: none;
+}
+
+.cf24-code:focus-within {
+  border-color: var(--color-rich-black, #0a0a0a);
+}
+
+/* 선택 영역은 **반투명**이어야 한다.
+   textarea 의 글자는 투명이고 실제 글자는 아래 <pre> 가 그린다. 선택 배경은
+   textarea(위층)가 칠하므로 불투명하면 아래 글자를 덮어 "선택하면 글자가 사라지는"
+   현상이 생긴다. 알파를 줘서 색칠된 글자가 비쳐 보이게 한다. */
+.cf24-code-input::selection {
+  background: rgba(51, 122, 226, 0.28);
+}
+
+.cf24-code-input::-moz-selection {
+  background: rgba(51, 122, 226, 0.28);
+}
+
+/* 토큰 색 — GitHub 라이트 계열 */
+.cf24-t-tag  { color: #116329; }            /* 태그 이름 */
+.cf24-t-attr { color: #953800; }            /* 속성 이름 */
+.cf24-t-val  { color: #0a3069; }            /* 속성 값 */
+.cf24-t-pun  { color: #57606a; }            /* < > / = */
+.cf24-t-com  { color: #6e7781; font-style: italic; }  /* 주석 */
+.cf24-t-doc  { color: #6639ba; }            /* DOCTYPE 등 선언 */
+
+.cf24-code-hint {
+  font-size: var(--text-caption, 12px);
+  color: var(--color-midtone-gray, #737373);
+}
+
+.cf24-details {
+  flex: 0 0 auto;
+  border-top: 1px solid var(--color-subtle-ash, #e5e5e5);
+  padding-top: var(--sp-8, 8px);
+}
+
+.cf24-details > summary {
+  cursor: pointer;
+  font-size: var(--text-caption, 12px);
+  color: var(--color-midtone-gray, #737373);
+}
+
+.cf24-compact {
+  font-size: 12px;
+}
+
+.cf24-compact tbody td,
+.cf24-compact thead th {
+  padding: 6px 8px;
+}
+
+.cf24-empty-pane {
+  margin: auto;
+  text-align: center;
+  padding: var(--sp-24, 24px);
+}
+
+.cf24-empty-pane h3 {
+  margin: 0 0 var(--sp-8, 8px);
+}
+
+.cf24-card-head {
+  display: flex;
+  align-items: center;
+  gap: var(--sp-8, 8px);
+  margin-bottom: var(--sp-12, 12px);
+}
+
+.cf24-card-head h3 {
+  margin: 0;
+  font-size: var(--text-heading, 18px);
+  letter-spacing: -0.45px;
+}
+
+.cf24-muted {
+  color: var(--color-midtone-gray, #737373);
+  font-size: var(--text-caption, 12px);
+}
+
+.cf24-err {
+  color: var(--color-callout-red, #c22b10);
+}
+
+.cf24-nowrap {
+  white-space: nowrap;
+}
+
+/* 상태 배지 */
+.cf24-badge-ok {
+  background: var(--color-success-green, #10c22b);
+  color: #fff;
+}
+
+.cf24-badge-off {
+  background: var(--color-ghost-gray, #f2f2f2);
+  color: var(--color-rich-black, #0a0a0a);
+}
+
+/* 클릭으로 진열/판매를 토글하는 배지. 눌리는 것임을 커서·테두리로 알린다. */
+.cf24-badge-btn {
+  border: 1px solid transparent;
+  font: inherit;
+  font-size: var(--text-caption, 12px);
+  cursor: pointer;
+  transition: filter 0.12s ease, box-shadow 0.12s ease;
+}
+
+.cf24-badge-btn:hover:not(:disabled) {
+  filter: brightness(0.94);
+  box-shadow: 0 0 0 2px rgba(0, 0, 0, 0.08);
+}
+
+.cf24-badge-btn:disabled {
+  opacity: 0.55;
+  cursor: progress;
+}
+
+/* 안내/오류 배너 */
+.cf24-flash {
+  padding: var(--sp-10, 10px) var(--sp-12, 12px);
+  border-radius: var(--r-lg, 10px);
+  margin-bottom: var(--sp-12, 12px);
+  font-size: var(--text-body, 14px);
+}
+
+.cf24-flash-ok {
+  background: #eefaf0;
+  border: 1px solid var(--color-success-green, #10c22b);
+}
+
+.cf24-flash-err {
+  background: #fdefec;
+  border: 1px solid var(--color-callout-red, #c22b10);
+}
+
+/* 키-값 표 */
+.cf24-kv th {
+  width: 180px;
+  text-align: left;
+  color: var(--color-midtone-gray, #737373);
+  font-weight: 500;
+  white-space: nowrap;
+}
+
+.cf24-actions {
+  display: flex;
+  gap: var(--sp-8, 8px);
+  align-items: center;
+  margin-top: var(--sp-12, 12px);
+}
+
+.cf24-warn {
+  color: var(--color-callout-red, #c22b10);
+  font-size: var(--text-caption, 12px);
+  font-weight: 500;
+}
+
+/* 검색 도구모음 / 페이지 이동 */
+.cf24-toolbar {
+  display: flex;
+  gap: var(--sp-8, 8px);
+  align-items: center;
+  flex-wrap: wrap;
+  margin-bottom: var(--sp-12, 12px);
+}
+
+/* 한 줄 높이로 고정한다. 세로 flex 안에서 flex-basis 를 주면 그 값이 '높이'로
+   적용돼 입력란이 거대해진다(실제로 그랬다 — flex 방향을 항상 확인할 것). */
+.cf24-search {
+  flex: 0 0 auto;
+  width: 100%;
+  box-sizing: border-box;
+  height: 32px;
+  padding: 0 var(--sp-10, 10px);
+  border: 1px solid var(--color-subtle-ash, #e5e5e5);
+  border-radius: var(--r-lg, 10px);
+  font-size: var(--text-body, 14px);
+}
+
+.cf24-pager {
+  display: flex;
+  gap: var(--sp-12, 12px);
+  align-items: center;
+  justify-content: center;
+  margin-top: var(--sp-16, 16px);
+}
+
+/* 상세설명 HTML 원문 */
+.cf24-label {
+  display: block;
+  margin: var(--sp-16, 16px) 0 var(--sp-8, 8px);
+  font-size: var(--text-caption, 12px);
+  font-weight: 500;
+  color: var(--color-midtone-gray, #737373);
+}
+
+.cf24-html {
+  width: 100%;
+  box-sizing: border-box;
+  padding: var(--sp-12, 12px);
+  border: 1px solid var(--color-subtle-ash, #e5e5e5);
+  border-radius: var(--r-lg, 10px);
+  background: var(--color-canvas-white, #fff);
+  font-family: var(--font-geist-mono, ui-monospace, monospace);
+  font-size: 12px;
+  line-height: 1.6;
+  white-space: pre;
+  overflow: auto;
+  resize: vertical;
+}
+
+/* 읽기 전용은 배경으로 구분 — 편집 가능한 칸과 헷갈리지 않게 */
+.cf24-html[readonly] {
+  background: var(--color-ghost-gray, #f2f2f2);
+}
+
+.cf24-note {
+  margin: var(--sp-12, 12px) 0 0;
+  padding: var(--sp-10, 10px) var(--sp-12, 12px);
+  border-left: 3px solid var(--color-subtle-ash, #e5e5e5);
+  background: var(--color-ghost-gray, #f2f2f2);
+  border-radius: var(--r-sm, 6px);
+  color: var(--color-midtone-gray, #737373);
+  font-size: var(--text-caption, 12px);
+  line-height: 1.7;
+}
+
+/* 넓은 로그 표는 카드 안에서만 가로 스크롤 */
+.cf24-scroll {
+  overflow-x: auto;
+}
+
+.cf24-scroll code {
+  font-family: var(--font-geist-mono, ui-monospace, monospace);
+  font-size: 12px;
+}
+
+.cf24-empty {
+  padding: var(--sp-24, 24px);
+}
+
+.cf24-empty h3 {
+  margin: 0 0 var(--sp-8, 8px);
+}
+
+/* ── 예약 폼 ── */
+.cf24-schedule-form {
+  padding-top: var(--sp-8, 8px);
+}
+
+.cf24-schedule-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+  gap: var(--sp-8, 8px);
+}
+
+.cf24-schedule-grid label {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  font-size: var(--text-caption, 12px);
+  color: var(--color-midtone-gray, #737373);
+}
+
+.cf24-schedule-wide {
+  grid-column: 1 / -1;
+}
+
+/* 날짜/시간을 별도 input 으로 나눈다 — datetime-local 은 한국어 로캘에서
+   "2026. 08. 14. 오후 07:00" 형태로 길어져 auto-fit minmax(160px, 1fr) 칸에
+   잘렸다(실측). 지금은 표시 텍스트를 우리가 직접 그리므로(아래 .cf24-dt-*) 폭을
+   내용에 맞춰 조절한다. */
+.cf24-schedule-datetime {
+  grid-column: span 2;
+  max-width: 300px;
+}
+
+.cf24-schedule-datetime-row {
+  display: flex;
+  gap: 6px;
+}
+
+/* ── 날짜/시간 표시 형식을 직접 그리는 오버레이 ──
+   네이티브 date/time input 은 표시 형식을 CSS 로 바꿀 수 없다(브라우저·로캘가
+   강제). 코드 편집기(.cf24-code-input 위 .cf24-code-hl)와 같은 원리로, 투명한
+   네이티브 input 을 우리가 그린 텍스트 위에 완전히 겹쳐 클릭·키보드·달력 팝업은
+   네이티브 그대로 쓰고 보이는 글자만 형식화한다. */
+.cf24-dt-field {
+  position: relative;
+  min-width: 0;
+  height: 32px;
+}
+
+/* 날짜 칸에 요일까지 표시("2026년 08월 20일 (목)")하므로 시간 칸보다 넓게 잡는다. */
+.cf24-dt-field-date {
+  flex: 1.7 1 0;
+}
+
+.cf24-dt-field-time {
+  flex: 1 1 0;
+}
+
+.cf24-dt-display {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  box-sizing: border-box;
+  padding: 0 6px;
+  border: 1px solid var(--color-subtle-ash, #e5e5e5);
+  border-radius: var(--r-lg, 10px);
+  background: var(--color-canvas-white, #fff);
+  color: var(--color-rich-black, #0a0a0a);
+  /* 12px 는 실측으로 고른 값 — 날짜 칸에 요일까지 들어가도 잘리지 않는 폭·글자크기
+     조합이다. */
+  font-size: 12px;
+  white-space: nowrap;
+  overflow: hidden;
+  pointer-events: none; /* 클릭은 위에 겹친 네이티브 input 이 받는다 */
+}
+
+.cf24-dt-native {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  opacity: 0; /* 완전히 투명 — 아래 .cf24-dt-display 가 그대로 비쳐 보인다 */
+  cursor: pointer;
+}
+
+.cf24-schedule-input {
+  height: 32px;
+  box-sizing: border-box;
+  padding: 0 var(--sp-8, 8px);
+  border: 1px solid var(--color-subtle-ash, #e5e5e5);
+  border-radius: var(--r-lg, 10px);
+  font-size: var(--text-body, 14px);
+  color: var(--color-rich-black, #0a0a0a);
+  background: var(--color-canvas-white, #fff);
+}
+
+/* ── 상품 다이렉트 주소 ── */
+.cf24-url-row {
+  display: flex;
+  gap: var(--sp-8, 8px);
+  align-items: center;
+  flex: 0 0 auto;
+  flex-wrap: wrap;
+}
+
+.cf24-url {
+  flex: 1 1 260px;
+  min-width: 0;
+  height: 30px;
+  box-sizing: border-box;
+  padding: 0 var(--sp-10, 10px);
+  border: 1px solid var(--color-subtle-ash, #e5e5e5);
+  border-radius: var(--r-lg, 10px);
+  background: var(--color-ghost-gray, #f6f8fa);
+  color: var(--color-midtone-gray, #737373);
+  font-family: var(--font-geist-mono, ui-monospace, monospace);
+  font-size: 12px;
+}

app/static/cupang.css

@@ -305,3 +305,393 @@
 .cpg-upb-unit { font-size: 13px; color: var(--color-midtone-gray); }
 /* 메모: 프레임 전체 너비 */
 .cpg .cpg-brule-fields .cpg-brule-memo { width: 100%; min-width: 0; max-width: 100%; box-sizing: border-box; }
+
+/* 등록된 제품명 표 — 정렬 가능한 헤더 */
+.cpg-sort {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 0;
+  border: 0;
+  background: none;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+}
+.cpg-sort:hover { text-decoration: underline; }
+.cpg-sort-ind::after {
+  content: "↕";
+  opacity: .35;
+  font-size: .85em;
+}
+.cpg-sort.is-asc .cpg-sort-ind::after  { content: "▲"; opacity: 1; }
+.cpg-sort.is-desc .cpg-sort-ind::after { content: "▼"; opacity: 1; }
+
+/* 박스 계산기 — 가로 스크롤이 생기지 않게 열 폭·여백을 좁게 잡는다. */
+.cpg-calc-table { table-layout: fixed; width: 100%; }
+.cpg-calc-table th, .cpg-calc-table td { padding: 8px 6px; }
+.cpg-calc-table .cpg-calc-num { text-align: right; white-space: nowrap; }
+
+.cpg-calc-table .cpg-calc-name { width: 100%; min-width: 0; }
+.cpg-calc-table .cpg-calc-qty { width: 100%; min-width: 0; text-align: right; padding-left: 6px; padding-right: 6px; }
+.cpg-calc-table .cpg-calc-box { white-space: nowrap; font-size: 13px; }
+.cpg-calc-table .cpg-calc-act { text-align: center; }
+.cpg-calc-table .cpg-calc-del { padding: 2px 8px; line-height: 1.4; }
+/* 제품명 칸을 좁게 고정하고, 나머지 열은 헤더가 잘리지 않을 폭을 준다.
+   fixed 레이아웃이라 남는 폭은 지정 폭 비율대로 나눠 가진다. */
+.cpg-calc-table col.cpg-col-name { width: 180px; }
+.cpg-calc-table col.cpg-col-qty { width: 78px; }
+.cpg-calc-table col.cpg-col-box { width: 116px; }
+.cpg-calc-table col.cpg-col-n   { width: 64px; }
+.cpg-calc-table col.cpg-col-act { width: 40px; }
+/* fixed 레이아웃에서 내용이 셀 밖으로 삐져나와 가로 스크롤이 생기는 것을 막는다.
+   말줄임(…)은 글자 셀에만 준다 — input/button 이 든 셀에 주면 빈 "…" 이 그려진다. */
+.cpg-calc-table th, .cpg-calc-table td { overflow: hidden; }
+.cpg-calc-table thead th { white-space: nowrap; text-align: center; font-weight: 700; color: var(--color-rich-black); }
+.cpg-calc-table .cpg-calc-box { text-overflow: ellipsis; }
+/* 숫자열 헤더도 가운데 정렬(본문 셀은 우측 정렬 유지) */
+.cpg-calc-table thead th.cpg-calc-num { text-align: center; }
+.cpg-calc-row.cpg-calc-warn { background: color-mix(in srgb, var(--color-callout-red) 8%, transparent); }
+.cpg-calc-actions { margin-top: 12px; gap: 8px; align-items: center; }
+/* 상단선 정렬: 2열 그리드에서는 위 여백을 주지 않는다. */
+.cpg-calc-sum { margin-top: 0; }
+
+/* ── 박스 계산 요약 ─────────────────────────────── */
+.cpg-sum-h3 {
+  margin: 20px 0 10px;
+  font-size: 15px;
+  font-weight: 700;
+}
+.cpg-sum-h3 .erp-muted { font-weight: 400; font-size: 13px; }
+
+.cpg-sum-kpis {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+  gap: 10px;
+}
+.cpg-kpi {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  padding: 12px 14px;
+  border: 1px solid var(--color-subtle-ash);
+  border-radius: 10px;
+  background: var(--color-ghost-gray);
+}
+.cpg-kpi-label { font-size: 12px; color: var(--color-midtone-gray); }
+.cpg-kpi-value { font-size: 24px; line-height: 1.2; }
+.cpg-kpi-hint { font-size: 12px; color: var(--color-midtone-gray); }
+
+.cpg-sum-prods {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(230px, 1fr));
+  gap: 8px;
+}
+.cpg-sum-prod {
+  padding: 10px 12px;
+  border: 1px solid var(--color-subtle-ash);
+  border-radius: 10px;
+}
+.cpg-sum-prod-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 6px;
+}
+.cpg-sum-prod-name { font-weight: 600; }
+.cpg-sum-prod-nums {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  flex-wrap: wrap;
+  font-size: 13px;
+}
+.cpg-sum-prod-nums strong { font-size: 17px; }
+.cpg-sum-left { color: var(--color-callout-red); font-weight: 600; }
+.cpg-sum-exact { color: var(--color-success-green); font-weight: 600; }
+
+/* 혼합 박스 카드 */
+.cpg-sum-boxes {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
+  gap: 12px;
+}
+.cpg-box-card {
+  display: flex;
+  gap: 12px;
+  padding: 12px;
+  border: 1px solid var(--color-subtle-ash);
+  border-radius: 12px;
+  background: var(--color-canvas-white);
+  opacity: 0;
+  animation: cpg-box-in .38s ease-out forwards;
+}
+@keyframes cpg-box-in {
+  from { opacity: 0; transform: translateY(10px) scale(.96); }
+  to   { opacity: 1; transform: none; }
+}
+.cpg-box-art { flex: 0 0 auto; }
+.cpg-box-svg { width: 72px; height: 64px; }
+.cpg-box-body {
+  fill: #f6e2c3;
+  stroke: #b98a4a;
+  stroke-width: 2;
+}
+.cpg-box-flapL, .cpg-box-flapR {
+  fill: #e8cfa6;
+  stroke: #b98a4a;
+  stroke-width: 2;
+  transform-origin: 36px 20px;
+  animation: cpg-flap .5s ease-out both;
+}
+.cpg-box-flapL { animation-delay: .12s; }
+.cpg-box-flapR { animation-delay: .2s; }
+@keyframes cpg-flap {
+  from { transform: rotate(0deg) translateY(6px); opacity: .3; }
+  to   { transform: none; opacity: 1; }
+}
+.cpg-box-fill {
+  fill: var(--color-rich-black);
+  opacity: .16;
+  animation: cpg-fill-up .55s ease-out both;
+  transform-origin: 36px 54px;
+}
+@keyframes cpg-fill-up {
+  from { transform: scaleY(0); }
+  to   { transform: scaleY(1); }
+}
+.cpg-box-seam { stroke: #b98a4a; stroke-width: 1.5; opacity: .5; }
+
+.cpg-box-info { min-width: 0; flex: 1 1 auto; }
+.cpg-box-title { font-weight: 700; margin-bottom: 6px; }
+.cpg-box-items {
+  list-style: none;
+  margin: 0 0 8px;
+  padding: 0;
+  font-size: 13px;
+}
+.cpg-box-items li {
+  display: flex;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 2px 0;
+  border-bottom: 1px dashed var(--color-subtle-ash);
+}
+.cpg-box-items li:last-child { border-bottom: 0; }
+.cpg-box-bar {
+  height: 6px;
+  border-radius: 3px;
+  background: var(--color-ghost-gray);
+  overflow: hidden;
+}
+.cpg-box-bar span {
+  display: block;
+  height: 100%;
+  background: var(--color-rich-black);
+  animation: cpg-bar-grow .6s ease-out both;
+  transform-origin: left center;
+}
+@keyframes cpg-bar-grow {
+  from { transform: scaleX(0); }
+  to   { transform: scaleX(1); }
+}
+.cpg-box-fillnum {
+  margin-top: 4px;
+  font-size: 12px;
+  color: var(--color-midtone-gray);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .cpg-box-card, .cpg-box-fill, .cpg-box-flapL, .cpg-box-flapR, .cpg-box-bar span {
+    animation: none;
+    opacity: 1;
+  }
+  .cpg-box-fill { opacity: .16; }
+}
+
+/* 박스 계산 2열 레이아웃 — 왼쪽 입력표 / 오른쪽 요약. 좁으면 세로로 쌓임. */
+.cpg-calc-layout {
+  display: grid;
+  grid-template-columns: minmax(0, 1.05fr) minmax(0, 1fr);
+  gap: 16px;
+  align-items: start;
+}
+.cpg-calc-layout > .erp-card { margin-bottom: 0; }
+@media (max-width: 1280px) {
+  .cpg-calc-layout { grid-template-columns: minmax(0, 1fr); }
+}
+
+/* 행이 많아도 카드가 잘리지 않도록 표 자체를 스크롤시킨다. */
+.cpg-calc-card .erp-table-wrap {
+  overflow-x: hidden;
+  overflow-y: auto;
+  max-height: min(58vh, 560px);
+}
+.cpg-calc-card .cpg-calc-table thead th {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  background: var(--color-canvas-white);
+}
+.cpg-calc-actions { flex-wrap: wrap; }
+
+/* 1열/2열 카드 높이를 맞춘다(요약이 비어 있을 때는 왼쪽만 표시). */
+.cpg-calc-layout { align-items: stretch; }
+.cpg-calc-layout > .erp-card { display: flex; flex-direction: column; }
+.cpg-calc-card .erp-table-wrap { flex: 1 1 auto; }
+.cpg-calc-sum { overflow: auto; max-height: min(78vh, 900px); }
+
+/* 제품명 설정 — 수기 추가 폼 */
+.cpg-prod-manual {
+  padding: 12px;
+  margin-bottom: 12px;
+  border: 1px solid var(--color-subtle-ash);
+  border-radius: 10px;
+  background: var(--color-ghost-gray);
+}
+.cpg-prod-manual-head {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-bottom: 8px;
+}
+.cpg-prod-manual-head .erp-muted { font-size: 12px; }
+.cpg-prod-manual-row {
+  display: flex;
+  gap: 10px;
+  align-items: flex-end;
+  flex-wrap: wrap;
+}
+.cpg-prod-manual-row .erp-field { flex: 1 1 160px; min-width: 0; }
+.cpg-prod-manual-row .erp-input { min-width: 0; width: 100%; }
+
+/* 상자 그림 안 박스 호수 라벨 (예: 2호) */
+.cpg-box-label {
+  font-family: inherit;
+  font-size: 11px;
+  font-weight: 700;
+  fill: #8a5a1e;
+  paint-order: stroke;
+  stroke: rgba(255, 255, 255, .85);
+  stroke-width: 3px;
+  stroke-linejoin: round;
+}
+
+/* ── 박스 계산 3열 작업 영역 (① 계산 / ② 요약 / ③ 센터 분배) ── */
+.cpg-calc3 {
+  display: grid;
+  grid-template-columns: minmax(0, 0.85fr) minmax(0, 1.25fr) minmax(0, 0.9fr);
+  gap: 16px;
+  align-items: stretch;
+}
+.cpg-calc3 > .erp-card { margin-bottom: 0; display: flex; flex-direction: column; }
+@media (max-width: 1500px) {
+  .cpg-calc3 { grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); }
+  .cpg-calc3 > .cpg-dist-card { grid-column: 1 / -1; }
+}
+@media (max-width: 1000px) {
+  .cpg-calc3 { grid-template-columns: minmax(0, 1fr); }
+  .cpg-calc3 > .cpg-dist-card { grid-column: auto; }
+}
+
+/* ② 요약: 카드가 드래그 가능함을 알린다 */
+.cpg-sum-prod.is-draggable, .cpg-box-card.is-draggable { cursor: grab; }
+.cpg-sum-prod.is-draggable:hover, .cpg-box-card.is-draggable:hover {
+  border-color: var(--color-rich-black);
+}
+.cpg-sum-prod.is-dragging, .cpg-box-card.is-dragging { opacity: .35; }
+.cpg-sum-prod.is-done, .cpg-box-card.is-done { opacity: .5; }
+
+/* 커서를 따라다니는 복제 카드 */
+body.cpg-dragging { cursor: grabbing; user-select: none; }
+.cpg-drag-ghost {
+  position: fixed;
+  z-index: 1300;
+  pointer-events: none;
+  opacity: .9;
+  max-width: 320px;
+  background: var(--color-canvas-white);
+  border: 1px solid var(--color-rich-black);
+  border-radius: 10px;
+  box-shadow: 0 12px 28px rgba(0, 0, 0, .25);
+  transform: rotate(-1.5deg);
+  animation: none;
+}
+
+/* ③ 센터 분배 */
+.cpg-dist-list {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  overflow-y: auto;
+  max-height: min(72vh, 820px);
+}
+.cpg-dist-center {
+  border: 1px solid var(--color-subtle-ash);
+  border-radius: 10px;
+  padding: 10px 12px;
+}
+.cpg-dist-center.has-items { border-color: var(--color-rich-black); }
+.cpg-dist-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 8px;
+  font-size: 14px;
+}
+/* 드롭 대상은 센터 패널 전체 */
+.cpg-dist-center { transition: background .15s ease, border-color .15s ease; }
+.cpg-dist-center.is-over {
+  border-color: var(--color-rich-black);
+  background: var(--color-ghost-gray);
+}
+.cpg-dist-hint {
+  margin: 0;
+  padding: 10px 8px;
+  border: 1.5px dashed var(--color-subtle-ash);
+  border-radius: 8px;
+  font-size: 12px;
+  color: var(--color-midtone-gray);
+  text-align: center;
+}
+.cpg-dist-sum { display: inline-flex; align-items: center; gap: 6px; }
+.cpg-dist-close { padding: 0 6px; line-height: 1.5; }
+.cpg-center-pick { display: flex; gap: 8px; margin-bottom: 10px; }
+.cpg-center-pick .erp-select { flex: 1 1 auto; min-width: 0; }
+.cpg-dist-items { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 6px; }
+.cpg-dist-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 13px;
+}
+.cpg-dist-name { flex: 1 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.cpg-dist-qty { width: 62px; min-width: 0; text-align: right; padding: 2px 6px; }
+.cpg-dist-unit { font-size: 12px; color: var(--color-midtone-gray); }
+.cpg-dist-del { padding: 2px 8px; line-height: 1.4; }
+
+/* 박스 수량 입력 대화상자 */
+.cpg-modal { position: fixed; inset: 0; z-index: 1200; display: flex; align-items: center; justify-content: center; }
+.cpg-modal[hidden] { display: none; }
+.cpg-modal-back { position: absolute; inset: 0; background: rgba(10, 10, 10, .45); }
+.cpg-modal-box {
+  position: relative;
+  width: min(420px, calc(100vw - 32px));
+  background: var(--color-canvas-white);
+  border-radius: 12px;
+  box-shadow: 0 18px 48px rgba(0, 0, 0, .28);
+  padding: 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.cpg-modal-box h3 { margin: 0; font-size: 17px; }
+.cpg-dlg-item { margin: 0; font-weight: 600; }
+.cpg-dlg-actions { margin: 4px 0 0; flex-wrap: wrap; }
+.cpg-modal-box .erp-input, .cpg-modal-box .erp-select { width: 100%; min-width: 0; }
+
+/* 드래그 중일 때 ③ 영역을 강조 — 어디에 놓아야 하는지 보이게 */
+.cpg-dist-card.is-drop-ready { outline: 2px dashed var(--color-rich-black); outline-offset: 2px; }
+.cpg-dist-card.is-drop-ready .cpg-dist-center { border-color: var(--color-midtone-gray); }

app/static/dispatch/courier/jnt.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 122 28" role="img" aria-label="J&T Express">
+  <rect x="0.6" y="0.6" width="120.8" height="26.8" rx="6" fill="#fff" stroke="#E2231A" stroke-width="1.2"/>
+  <text x="9" y="20" font-family="Arial, 'Helvetica Neue', sans-serif" font-size="16"
+        font-weight="800" fill="#E2231A" letter-spacing="0.2">J&amp;T</text>
+  <text x="42" y="19" font-family="Arial, 'Helvetica Neue', sans-serif" font-size="11"
+        font-weight="700" fill="#1f2937" letter-spacing="1">EXPRESS</text>
+</svg>

app/static/dispatch/courier/ninjavan.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 138 28" role="img" aria-label="Ninja Van">
+  <rect x="0" y="0" width="138" height="28" rx="6" fill="#D6242C"/>
+  <!-- 간이 닌자 머리(흰 원 + 빨강 눈띠) -->
+  <g transform="translate(14,14)">
+    <circle r="9" fill="#fff"/>
+    <rect x="-9" y="-2.4" width="18" height="4.8" fill="#D6242C"/>
+    <rect x="-7" y="-1.1" width="4.2" height="2.2" rx="1.1" fill="#fff"/>
+    <rect x="2.8" y="-1.1" width="4.2" height="2.2" rx="1.1" fill="#fff"/>
+  </g>
+  <text x="29" y="19" font-family="Arial, 'Helvetica Neue', sans-serif" font-size="14"
+        font-weight="700" fill="#fff" letter-spacing="0.3">Ninja Van</text>
+</svg>

app/static/erp-dialog.css

@@ -0,0 +1,98 @@
+/* ════════════════════════════════════════════════════
+   ERP 공용 확인/경고 창
+   브라우저 기본 confirm()/alert() 은 제목에 도메인이 찍히고 위치·모양을 바꿀 수
+   없다. 화면 정중앙에 같은 모양으로 띄우기 위해 직접 그린다(erp-dialog.js).
+   ════════════════════════════════════════════════════ */
+
+.erp-dialog-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 9999;
+  display: flex;
+  align-items: center;      /* 화면 정중앙 */
+  justify-content: center;
+  padding: var(--sp-16, 16px);
+  background: rgba(10, 10, 10, 0.45);
+  font-family: var(--font-geist, system-ui, sans-serif);
+  animation: erp-dialog-fade 0.12s ease-out;
+}
+
+.erp-dialog {
+  width: 100%;
+  max-width: 420px;
+  background: var(--color-canvas-white, #fff);
+  border-radius: var(--r-card, 14px);
+  box-shadow: 0 18px 48px rgba(0, 0, 0, 0.28);
+  overflow: hidden;
+  text-align: center;       /* 제목·본문·버튼 모두 가운데 정렬 */
+  animation: erp-dialog-pop 0.12s ease-out;
+}
+
+.erp-dialog-title {
+  margin: 0;
+  padding: var(--sp-12, 12px) var(--sp-20, 20px);
+  border-bottom: 1px solid var(--color-subtle-ash, #e5e5e5);
+  background: var(--color-ghost-gray, #f2f2f2);
+  font-size: var(--text-body, 14px);
+  font-weight: 600;
+  letter-spacing: var(--tracking-heading, -0.45px);
+  color: var(--color-rich-black, #0a0a0a);
+}
+
+/* 아이콘은 글 왼쪽에 고정하고, 글 묶음만 가운데 정렬한다. */
+.erp-dialog-body {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--sp-12, 12px);
+  padding: var(--sp-24, 24px) var(--sp-20, 20px);
+}
+
+.erp-dialog-icon {
+  flex: 0 0 auto;
+  line-height: 0;
+  color: var(--color-callout-red, #c22b10);
+}
+
+/* 확인(질문)용은 붉은 경고색 대신 차분한 검정으로 */
+.erp-dialog-ask .erp-dialog-icon {
+  color: var(--color-rich-black, #0a0a0a);
+}
+
+.erp-dialog-message {
+  margin: 0;
+  font-size: var(--text-body, 14px);
+  line-height: var(--leading-body, 1.43);
+  color: var(--color-rich-black, #0a0a0a);
+  /* 메시지의 줄바꿈(\n)을 그대로 살린다 */
+  white-space: pre-line;
+  word-break: break-word;
+}
+
+.erp-dialog-actions {
+  display: flex;
+  justify-content: center;
+  gap: var(--sp-8, 8px);
+  padding: 0 var(--sp-20, 20px) var(--sp-20, 20px);
+}
+
+.erp-dialog-actions .erp-btn {
+  min-width: 88px;
+  padding: 9px 18px;
+  font-size: var(--text-body, 14px);
+}
+
+@keyframes erp-dialog-fade {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+
+@keyframes erp-dialog-pop {
+  from { opacity: 0; transform: translateY(6px) scale(0.98); }
+  to   { opacity: 1; transform: none; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .erp-dialog-backdrop,
+  .erp-dialog { animation: none; }
+}

app/static/erp-dialog.js

@@ -0,0 +1,156 @@
+/* ════════════════════════════════════════════════════
+   ERP 공용 확인/경고 창 — window.confirm()/alert() 대체
+   ────────────────────────────────────────────────────
+   브라우저 기본 창은 제목에 도메인("dbx.no1king.freeddns.org 내용:")이 찍히고
+   위치·정렬·아이콘을 바꿀 수 없다. 그래서 같은 역할의 창을 직접 그린다.
+
+   쓰는 법 (기본 창과 달리 **비동기**다 — Promise 를 돌려준다):
+       erpConfirm("지울까요?").then(function (ok) { if (ok) ... });
+       erpAlert("실패했습니다.").then(...)
+
+   HTML 만으로 쓰려면 form 에 data-erp-confirm 을 달면 된다. 제출을 가로채
+   확인을 받은 뒤 통과시킨다(가로챈 제출은 form.submit() 으로 다시 보내므로
+   이 스크립트의 submit 리스너를 다시 타지 않는다).
+       <form ... data-erp-confirm="정말 지울까요?">
+   ════════════════════════════════════════════════════ */
+(function () {
+  "use strict";
+
+  var TITLE = "No.1 King ERP 프로그램";
+
+  // 경고 삼각형. 외부 아이콘 라이브러리를 쓰지 않는다(자체 호스팅 원칙).
+  var ICON =
+    '<svg width="32" height="32" viewBox="0 0 24 24" fill="none" aria-hidden="true">' +
+    '<path d="M12 3.2 1.8 20.4h20.4L12 3.2Z" stroke="currentColor" stroke-width="1.6"' +
+    ' stroke-linejoin="round"/>' +
+    '<path d="M12 9.4v4.8" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/>' +
+    '<circle cx="12" cy="17.1" r="1.05" fill="currentColor"/>' +
+    "</svg>";
+
+  function build(message, options) {
+    var backdrop = document.createElement("div");
+    backdrop.className = "erp-dialog-backdrop";
+
+    var box = document.createElement("div");
+    box.className = "erp-dialog" + (options.ask ? " erp-dialog-ask" : "");
+    box.setAttribute("role", "alertdialog");
+    box.setAttribute("aria-modal", "true");
+    box.setAttribute("aria-label", TITLE);
+
+    var title = document.createElement("h2");
+    title.className = "erp-dialog-title";
+    title.textContent = TITLE;
+
+    var body = document.createElement("div");
+    body.className = "erp-dialog-body";
+
+    var icon = document.createElement("span");
+    icon.className = "erp-dialog-icon";
+    icon.innerHTML = ICON;
+
+    var text = document.createElement("p");
+    text.className = "erp-dialog-message";
+    // 메시지는 반드시 textContent 로 넣는다 — 서버/사용자 문자열이 들어와도
+    // HTML 로 해석되지 않게.
+    text.textContent = String(message == null ? "" : message);
+
+    var actions = document.createElement("div");
+    actions.className = "erp-dialog-actions";
+
+    var cancel = null;
+    if (options.ask) {
+      cancel = document.createElement("button");
+      cancel.type = "button";
+      cancel.className = "erp-btn erp-btn-outline";
+      cancel.textContent = options.cancelText || "취소";
+      actions.appendChild(cancel);
+    }
+
+    var ok = document.createElement("button");
+    ok.type = "button";
+    ok.className = "erp-btn erp-btn-primary";
+    ok.textContent = options.okText || "확인";
+    actions.appendChild(ok);
+
+    body.appendChild(icon);
+    body.appendChild(text);
+    box.appendChild(title);
+    box.appendChild(body);
+    box.appendChild(actions);
+    backdrop.appendChild(box);
+
+    return { backdrop: backdrop, box: box, ok: ok, cancel: cancel };
+  }
+
+  function open(message, options) {
+    return new Promise(function (resolve) {
+      var el = build(message, options);
+      var previous = document.activeElement;
+      var closed = false;
+
+      function close(result) {
+        if (closed) return;
+        closed = true;
+        document.removeEventListener("keydown", onKey, true);
+        el.backdrop.remove();
+        if (previous && typeof previous.focus === "function") previous.focus();
+        resolve(result);
+      }
+
+      function onKey(e) {
+        if (e.key === "Escape") {
+          e.preventDefault();
+          close(false);          // 확인창의 Esc = 취소, 알림창의 Esc = 닫기
+        } else if (e.key === "Enter") {
+          e.preventDefault();
+          close(true);
+        } else if (e.key === "Tab") {
+          // 포커스가 창 밖으로 나가지 않게 두 버튼 사이에서만 돈다.
+          var focusable = el.cancel ? [el.cancel, el.ok] : [el.ok];
+          var index = focusable.indexOf(document.activeElement);
+          e.preventDefault();
+          var next = e.shiftKey ? index - 1 : index + 1;
+          if (next < 0) next = focusable.length - 1;
+          if (next >= focusable.length) next = 0;
+          focusable[next].focus();
+        }
+      }
+
+      el.ok.addEventListener("click", function () { close(true); });
+      if (el.cancel) el.cancel.addEventListener("click", function () { close(false); });
+      // 바깥을 누르면 취소(= 안전한 쪽). 창 안쪽 클릭은 그대로 둔다.
+      el.backdrop.addEventListener("mousedown", function (e) {
+        if (e.target === el.backdrop) close(false);
+      });
+      document.addEventListener("keydown", onKey, true);
+
+      document.body.appendChild(el.backdrop);
+      el.ok.focus();
+    });
+  }
+
+  window.erpConfirm = function (message, options) {
+    var opts = options || {};
+    opts.ask = true;
+    return open(message, opts);
+  };
+
+  window.erpAlert = function (message, options) {
+    var opts = options || {};
+    opts.ask = false;
+    return open(message, opts).then(function () { return undefined; });
+  };
+
+  // data-erp-confirm 이 달린 폼은 제출 전에 확인을 받는다.
+  document.addEventListener("submit", function (e) {
+    var form = e.target;
+    if (!form || !form.dataset || !form.dataset.erpConfirm) return;
+    if (form.dataset.erpConfirmed === "1") return;   // 확인을 마치고 다시 보낸 것
+    e.preventDefault();
+    window.erpConfirm(form.dataset.erpConfirm).then(function (ok) {
+      if (!ok) return;
+      form.dataset.erpConfirmed = "1";
+      form.submit();                                  // submit 이벤트를 다시 타지 않는다
+    });
+  });
+})();

app/static/erp-shell.css

@@ -285,16 +285,23 @@ body.erp-app-body { background: var(--color-canvas-white); height: 100vh; overfl
 
 /* ── 반응형 ── */
 @media (max-width: 900px) {
-  .erp-app { grid-template-columns: 0 1fr; }
+  /* 모바일: grid 자체 해제(데스크탑 collapsed :has 규칙과의 특이도 싸움 회피).
+     사이드바는 흐름 밖 떠있는 오버레이, 본문은 풀폭 block. */
+  body.erp-app-body { height: auto; overflow: auto; }
+  .erp-app,
+  .erp-app:has(.erp-sidebar[data-collapsed="true"]) { display: block; }
   .erp-sidebar {
-    position: fixed; left: 0; top: 0; height: 100vh;
+    position: fixed; left: 0; top: 0; height: 100vh; z-index: 1000;
     width: var(--erp-sidebar-w);
     transform: translateX(-100%);
     transition: transform .2s ease;
     box-shadow: 0 0 0 1px var(--color-subtle-ash);
   }
+  /* 모바일선 데스크탑 접힘 무시 — 메뉴 열면 풀폭으로 */
+  .erp-sidebar[data-collapsed="true"] { width: var(--erp-sidebar-w); }
   .erp-sidebar.is-open { transform: translateX(0); }
   .erp-sidebar-mobile-toggle { display: inline-flex; }
+  .erp-content { width: 100%; min-width: 0; }
   .erp-form-grid { grid-template-columns: 1fr 1fr; }
   .erp-field-wide { grid-column: span 2; }
 }

app/static/malaysia.js

@@ -0,0 +1,191 @@
+/* 말레이시아 재고관리 — 화면 한글/영문 실시간 토글.
+ *
+ * - UI 고정 문구: 아래 KO_EN 사전으로 치환(요소 텍스트 = 한글 키).
+ *   대상 셀렉터는 UI 크롬(제목/헤더/버튼/라벨/배지/옵션/안내문)으로 한정 →
+ *   데이터 셀(상품코드/수량)은 건드리지 않음.
+ * - 상품명: 서버가 data-ko / data-en 을 함께 렌더 → 언어에 맞게 textContent 교체.
+ * - 선택값은 localStorage('mys_lang') 에 저장, 모든 화면 공통 적용.
+ */
+(function () {
+  "use strict";
+
+  var KO_EN = {
+    // 사이드바 메뉴 / 페이지 제목
+    "말레이시아 재고관리": "Malaysia Stock",
+    "입고/출고/조정 일괄 등록": "IN/OUT/ADJUST bulk",
+    // 탭 / 공통
+    "재고 현황": "Stock Status",
+    "입출고": "In / Out",
+    "일일 재고조사": "Daily Stocktake",
+    "창고 랙 보기": "Rack View",
+    "창고 랙": "Warehouse Rack",
+    "랙 보기": "Rack View",
+    "인쇄 미리보기": "Print Preview",
+    "인쇄": "Print",
+    "저장": "Save",
+    "닫기": "Close",
+    "칸을 드래그해 다른 칸으로 옮기면 구성이 이동(채워진 칸끼리는 맞교환)됩니다. 칸 번호는 그대로입니다. 인쇄할 칸은 체크 후 인쇄하세요.":
+      "Drag a cell onto another to move its contents (filled cells swap). Cell numbers stay. Check cells, then print.",
+    "기준 재고조사": "Based on stocktake",
+    "표시할 재고조사가 없습니다.": "No stocktake to display.",
+    "박스": "box",
+    "개": "ea",
+    "입수량": "Units/box",
+    "합계": "Subtotal",
+    "창고": "Warehouse",
+    "날짜": "Date",
+    "메모": "Memo",
+    "상태": "Status",
+    // 재고현황
+    "전산 재고 현황 — 낱개 기준": "System Stock — by Single",
+    "현재고 = 입고 − 출고 + 조정 + 재고조사반영 (콤보는 낱개로 분해 반영됨)":
+      "Current = IN − OUT + ADJUST + Stocktake (combos exploded to singles)",
+    "전산재고": "System Qty",
+    "조사수량": "Stocktake Qty",
+    "차이": "Diff",
+    "콤보 재고 (세트 단위)": "Combo Stock (by set)",
+    "콤보재고 = 재고조사": "Combo stock = stocktake",
+    "− 이후 출고": "− OUT since",
+    "재고조사 입력 없음": "No stocktake input",
+    "표시할 재고가 없습니다.": "No stock to display.",
+    "콤보 재고 입력이 없습니다.": "No combo stock input.",
+    "위험 구역 (슈퍼관리자)": "Danger Zone (Super Admin)",
+    "재고 초기화": "Reset Stock",
+    // 입출고
+    "등록 옵션": "Options",
+    "이동 종류 (낱개)": "Type (single)",
+    "IN (입고)": "IN (In)",
+    "OUT (출고)": "OUT (Out)",
+    "ADJUST (조정 ±)": "ADJUST (±)",
+    "입력": "Input",
+    "다운로드": "Download",
+    "낱개 상품": "Single Products",
+    "콤보 상품": "Combo Products",
+    "이동 이력": "Movement History",
+    "구분": "Kind",
+    "낱개": "Single",
+    "콤보": "Combo",
+    "전체": "All",
+    "날짜해제": "Clear date",
+    "이동 이력이 없습니다.": "No movements.",
+    // 재고조사 목록
+    "재고조사 생성": "New Stocktake",
+    "조사 날짜": "Date",
+    "생성": "Create",
+    "생성 후 상세에서 낱개/세트 수량을 입력하고 확정하세요.":
+      "After creating, enter single/set qty in detail and finalize.",
+    "조사 목록": "Stocktake List",
+    "열기": "Open",
+    "삭제": "Delete",
+    "재고조사가 없습니다.": "No stocktakes.",
+    "확정": "Final",
+    "취소": "Cancel",
+    "작성중": "Draft",
+    // 재고조사 상세
+    "재고조사": "Stocktake",
+    "◀◀ 조사 목록": "◀◀ List",
+    "확정시각": "Finalized at",
+    "이전값 불러오기": "Load previous",
+    "입력 저장": "Save",
+    "확정 (전산 반영)": "Finalize (apply)",
+    "삭제 (슈퍼관리자)": "Delete (super)",
+    "랙 입력 (박스 단위)": "Rack Input (by box)",
+    "랙 칸에 아이템·입수량(박스당 개수)·박스 수를 입력하면 낱개/콤보 수량이 자동 집계됩니다. 한 칸에 여러 아이템은 + 로 추가하세요.":
+      "Enter item · units-per-box · box count in each rack cell; single/combo qty is auto-summed. Use + to add more items in one cell.",
+    "최종 계산 (낱개 기준)": "Final Calc (by single)",
+    "total_qty = direct_qty(낱개 직접) + from_set_qty(콤보 분해)":
+      "total_qty = direct_qty (single) + from_set_qty (combo)",
+    "입력된 수량이 없습니다.": "No quantities entered.",
+    // 표 헤더(한글만)
+    "이동일": "Date",
+    // 창고 랙 / POG
+    "POG 출력": "POG Print",
+    "창고 POG 미리보기": "Warehouse POG Preview",
+  };
+
+  var EN_KO = {};
+  Object.keys(KO_EN).forEach(function (k) { EN_KO[KO_EN[k]] = k; });
+
+  // 부분치환용 키 — 긴 키부터(부분 매칭 충돌 방지)
+  var RICH_KEYS = Object.keys(KO_EN).sort(function (a, b) { return b.length - a.length; });
+
+  // 헤더/사이드바처럼 .mys 밖이면서 KO 문구가 다른 텍스트와 섞인 요소.
+  // 사이드바는 현재 활성(말레이시아) 항목만 번역 → 다른 메뉴는 그대로 유지.
+  var RICH_SEL = [
+    ".erp-topbar-title h1",
+    ".erp-topbar-title p",
+    ".erp-sidebar-item.is-active .erp-sidebar-label",
+  ].join(",");
+
+  function applyRich(lang) {
+    document.querySelectorAll(RICH_SEL).forEach(function (el) {
+      if (el.getAttribute("data-o") === null) {
+        el.setAttribute("data-o", (el.textContent || "").trim());
+      }
+      var ko = el.getAttribute("data-o");
+      if (lang !== "en") { el.textContent = ko; return; }
+      var s = ko;
+      RICH_KEYS.forEach(function (k) {
+        if (s.indexOf(k) !== -1) s = s.split(k).join(KO_EN[k]);
+      });
+      el.textContent = s;
+    });
+  }
+
+  var SEL = [
+    ".mys h1", ".mys h2", ".mys h3",
+    ".mys th",
+    ".mys label > span",
+    ".mys button",
+    ".mys a.erp-btn",
+    ".mys .erp-muted",
+    ".mys option",
+    ".mys .erp-badge",
+    ".mys .i18n",
+  ].join(",");
+
+  function applyLang(lang) {
+    // 1) 상품명(한/영 동시 보유)
+    document.querySelectorAll(".mys [data-ko][data-en]").forEach(function (el) {
+      el.textContent = (lang === "en") ? el.getAttribute("data-en")
+                                       : el.getAttribute("data-ko");
+    });
+    // 2) UI 고정 문구
+    document.querySelectorAll(SEL).forEach(function (el) {
+      // 자식 요소가 있는 컨테이너는 건너뜀(.i18n 로 명시한 경우만 허용)
+      if (el.children.length && !el.classList.contains("i18n")) return;
+      if (el.hasAttribute("data-ko") && el.hasAttribute("data-en")) return; // 이미 처리됨
+      if (el.getAttribute("data-o") === null) {
+        el.setAttribute("data-o", (el.textContent || "").trim());
+      }
+      var ko = el.getAttribute("data-o");
+      if (lang === "en") {
+        if (KO_EN[ko] !== undefined) el.textContent = KO_EN[ko];
+      } else {
+        el.textContent = ko;
+      }
+    });
+    // 3) 헤더/사이드바(부분 치환)
+    applyRich(lang);
+    // 4) 토글 버튼 라벨
+    var btn = document.getElementById("mys-lang-toggle");
+    if (btn) btn.textContent = (lang === "en") ? "한글" : "ENG";
+    document.documentElement.setAttribute("data-mys-lang", lang);
+  }
+
+  function current() {
+    return localStorage.getItem("mys_lang") === "en" ? "en" : "ko";
+  }
+
+  function toggle() {
+    var next = current() === "en" ? "ko" : "en";
+    localStorage.setItem("mys_lang", next);
+    applyLang(next);
+  }
+
+  document.addEventListener("DOMContentLoaded", function () {
+    var btn = document.getElementById("mys-lang-toggle");
+    if (btn) btn.addEventListener("click", toggle);
+    applyLang(current());
+  });
+})();

app/static/malaysia_rack.js

@@ -0,0 +1,69 @@
+/* 말레이시아 재고조사 — 랙(rack) 입력 보조 스크립트.
+ *
+ * - 칸(.rack-cell) 헤더의 + 버튼: 빈 입력행을 칸에 추가(템플릿 #rk-row-tpl 클론).
+ *   클론 시 숨김필드 rk_cell 에 해당 칸 코드를 채워 서버 병렬배열과 정렬.
+ * - 행의 × 버튼: 그 행 제거(칸에 행이 0개여도 무방 — 서버가 빈 칸 스킵).
+ * - 입수량/박스수 입력 시 행 소계(rk-sub)만 실시간 갱신.
+ *   (칸 합계는 서로 다른 상품을 더하게 되어 의미 없으므로 표시하지 않음.)
+ * 저장은 폼 제출(서버에서 SKU별 집계 → 재고조사 라인 재생성).
+ */
+(function () {
+  "use strict";
+
+  function num(el) {
+    var v = parseInt((el && el.value) || "0", 10);
+    return isNaN(v) || v < 0 ? 0 : v;
+  }
+
+  function comma(n) {
+    return n.toLocaleString("en-US");
+  }
+
+  function recalcRow(row) {
+    var upb = num(row.querySelector(".rk-upb"));
+    var box = num(row.querySelector(".rk-box"));
+    var sub = row.querySelector(".rk-sub");
+    if (sub) sub.textContent = comma(upb * box);
+  }
+
+  function wireRow(row) {
+    row.querySelectorAll(".rk-upb, .rk-box").forEach(function (inp) {
+      inp.addEventListener("input", function () {
+        recalcRow(row);
+      });
+    });
+    var del = row.querySelector(".rk-del");
+    if (del) {
+      del.addEventListener("click", function () {
+        row.remove();
+      });
+    }
+  }
+
+  function addRow(cell) {
+    var tpl = document.getElementById("rk-row-tpl");
+    if (!tpl) return;
+    var frag = tpl.content.cloneNode(true);
+    var row = frag.querySelector(".rk-row");
+    if (!row) return;
+    var hidden = row.querySelector('input[name="rk_cell"]');
+    if (hidden) hidden.value = cell.getAttribute("data-cell") || "";
+    cell.querySelector(".rk-rows").appendChild(row);
+    wireRow(row);
+    var sku = row.querySelector(".rk-sku");
+    if (sku) sku.focus();
+  }
+
+  document.addEventListener("DOMContentLoaded", function () {
+    document.querySelectorAll(".rack-cell .rk-row").forEach(function (row) {
+      wireRow(row);
+      recalcRow(row);
+    });
+    document.querySelectorAll(".rack-cell .rk-add").forEach(function (btn) {
+      btn.addEventListener("click", function () {
+        var cell = btn.closest(".rack-cell");
+        if (cell) addRow(cell);
+      });
+    });
+  });
+})();

app/static/malaysia_rack_view.js

@@ -0,0 +1,296 @@
+/* 말레이시아 창고 랙 보기 — 드래그 재배치 + 저장 + 인쇄 미리보기.
+ *
+ * - 각 .rv-cell 의 data-entries(JSON)가 진실원천. 드래그 드롭으로 두 칸의
+ *   구성(entries)을 맞교환(빈 칸이면 이동). 칸 번호(cell)는 그대로.
+ * - 저장: 모든 칸의 현재 구성을 rk_cell/rk_sku/rk_upb/rk_box 병렬배열 hidden
+ *   으로 만들어 POST /malaysia/rack/save (서버 reposition_rack).
+ * - 인쇄: 체크한 칸을 칸마다 A4 가로 1장으로 미리보기 후 window.print().
+ * - 언어: localStorage('mys_lang'). 셀/미리보기 텍스트를 현재 언어로 렌더.
+ */
+(function () {
+  "use strict";
+
+  function lang() { return localStorage.getItem("mys_lang") === "en" ? "en" : "ko"; }
+  function t(ko, en) { return lang() === "en" ? en : ko; }
+  function fmt(n) { return Number(n || 0).toLocaleString(); }
+  function nameOf(e) { return (lang() === "en" ? e.en : e.ko) || e.sku; }
+  // 상품명 끝의 용량 토큰(숫자 포함, 예 750ml)을 분리 → {main, size}
+  function splitName(full) {
+    var m = String(full || "").match(/^(.*\S)\s+(\S*\d\S*)$/);
+    if (m) return { main: m[1], size: m[2] };
+    return { main: full || "", size: "" };
+  }
+
+  function getEntries(cell) {
+    try { return JSON.parse(cell.getAttribute("data-entries") || "[]"); }
+    catch (_) { return []; }
+  }
+  function setEntries(cell, arr) {
+    cell.setAttribute("data-entries", JSON.stringify(arr));
+  }
+
+  function renderCell(cell) {
+    var items = cell.querySelector(".rv-items");
+    if (!items) return;
+    var arr = getEntries(cell);
+    items.innerHTML = "";
+    if (!arr.length) {
+      cell.classList.add("is-empty");
+      var s = document.createElement("span");
+      s.className = "rv-empty-note";
+      s.textContent = "—";
+      items.appendChild(s);
+      return;
+    }
+    cell.classList.remove("is-empty");
+    arr.forEach(function (e) {
+      var total = (Number(e.upb) || 0) * (Number(e.box) || 0);
+      var wrap = document.createElement("div");
+      wrap.className = "rv-item";
+      var nm = document.createElement("span");
+      nm.className = "rv-name";
+      nm.textContent = nameOf(e);
+      var calc = document.createElement("span");
+      calc.className = "rv-calc";
+      calc.innerHTML = fmt(e.upb) + t("개", "ea") + " × " + fmt(e.box) + t("박스", "box")
+        + " = <span class=\"rv-qty\">" + fmt(total) + "</span>";
+      wrap.appendChild(nm);
+      wrap.appendChild(document.createElement("br"));
+      wrap.appendChild(calc);
+      items.appendChild(wrap);
+    });
+  }
+  function renderAll() {
+    document.querySelectorAll(".rv-cell").forEach(renderCell);
+  }
+
+  // ── 드래그 재배치 ──
+  var dragSrc = null;
+  var dirty = false;
+  function markDirty() {
+    dirty = true;
+    var b = document.getElementById("rv-save-btn");
+    if (b) b.classList.add("is-dirty");
+  }
+  function cleanup() {
+    if (dragSrc) dragSrc.classList.remove("dragging");
+    dragSrc = null;
+    document.querySelectorAll(".rv-cell.is-dragover")
+      .forEach(function (c) { c.classList.remove("is-dragover"); });
+  }
+  function onDragStart(e) {
+    var cell = e.target.closest(".rv-cell");
+    if (!cell) return;
+    dragSrc = cell;
+    cell.classList.add("dragging");
+    e.dataTransfer.effectAllowed = "move";
+    try { e.dataTransfer.setData("text/plain", cell.getAttribute("data-cell")); } catch (_) {}
+  }
+  function onDragOver(e) {
+    if (!dragSrc) return;
+    e.preventDefault();
+    e.dataTransfer.dropEffect = "move";
+    var cell = e.target.closest(".rv-cell");
+    if (cell && cell !== dragSrc) cell.classList.add("is-dragover");
+  }
+  function onDragLeave(e) {
+    var cell = e.target.closest(".rv-cell");
+    if (cell) cell.classList.remove("is-dragover");
+  }
+  function onDrop(e) {
+    e.preventDefault();
+    var dst = e.target.closest(".rv-cell");
+    if (!dst || !dragSrc || dst === dragSrc) { cleanup(); return; }
+    var a = getEntries(dragSrc);
+    var b = getEntries(dst);
+    setEntries(dragSrc, b);
+    setEntries(dst, a);
+    renderCell(dragSrc);
+    renderCell(dst);
+    markDirty();
+    cleanup();
+  }
+
+  // ── 인쇄 선택(체크박스) → 셀 강조 ──
+  function onChange(e) {
+    var cb = e.target;
+    if (!cb.classList || !cb.classList.contains("rv-pick")) return;
+    var cell = cb.closest(".rv-cell");
+    if (cell) cell.classList.toggle("is-selected", cb.checked);
+  }
+
+  // ── 저장 ──
+  function addHidden(parent, name, val) {
+    var i = document.createElement("input");
+    i.type = "hidden";
+    i.name = name;
+    i.value = val;
+    parent.appendChild(i);
+  }
+  function save() {
+    var fields = document.getElementById("rv-save-fields");
+    var form = document.getElementById("rv-save-form");
+    if (!fields || !form) return;
+    fields.innerHTML = "";
+    document.querySelectorAll(".rv-cell").forEach(function (cell) {
+      var cc = cell.getAttribute("data-cell");
+      getEntries(cell).forEach(function (e) {
+        addHidden(fields, "rk_cell", cc);
+        addHidden(fields, "rk_sku", e.sku);
+        addHidden(fields, "rk_upb", e.upb);
+        addHidden(fields, "rk_box", e.box);
+      });
+    });
+    dirty = false;
+    var b = document.getElementById("rv-save-btn");
+    if (b) b.classList.remove("is-dirty");
+    alert(t("저장되었습니다.", "Saved."));
+    form.submit();
+  }
+
+  // ── 인쇄 미리보기 ──
+  function openPreview() {
+    var picked = [].slice.call(document.querySelectorAll(".rv-cell")).filter(function (c) {
+      var cb = c.querySelector(".rv-pick");
+      return cb && cb.checked;
+    });
+    if (!picked.length) {
+      alert(t("인쇄할 칸을 먼저 선택하세요.", "Select cells to print first."));
+      return;
+    }
+    // 빈 칸은 인쇄 대상에서 제외. 내용 있는 칸만 인쇄.
+    var withItems = picked.filter(function (c) { return getEntries(c).length > 0; });
+    if (!withItems.length) {
+      alert(t("인쇄할 문서가 없습니다. (선택한 칸이 모두 비어 있습니다)",
+              "Nothing to print. (All selected cells are empty.)"));
+      return;
+    }
+    var pages = document.getElementById("rvp-pages");
+    pages.innerHTML = "";
+    withItems.forEach(function (cell) {
+      var arr = getEntries(cell);
+      var sheet = document.createElement("div");
+      sheet.className = "rvp-sheet";
+      // 인쇄 시 칸에 담긴 상품 수에 따라 글자 크기 단계 지정(한 장에 다 들어가게)
+      if (arr.length >= 3) sheet.classList.add("rvp-many");
+      else if (arr.length === 2) sheet.classList.add("rvp-multi");
+      var list = document.createElement("div");
+      list.className = "rvp-list";
+      {
+        arr.forEach(function (e) {
+          var total = (Number(e.upb) || 0) * (Number(e.box) || 0);
+          var nm = splitName(nameOf(e));
+          var line = document.createElement("div");
+          line.className = "rvp-line";
+          var main = document.createElement("span");
+          main.className = "rvp-name";
+          main.textContent = nm.main;
+          line.appendChild(main);
+          if (nm.size) {
+            var size = document.createElement("span");
+            size.className = "rvp-size";
+            size.textContent = nm.size;
+            line.appendChild(size);
+          }
+          var calc = document.createElement("span");
+          calc.className = "rvp-calc";
+          calc.innerHTML = fmt(e.upb) + t("개", "ea") + " &times; "
+            + "<b class=\"rvp-box\">" + fmt(e.box) + t("박스", "box") + "</b>"
+            + " = " + fmt(total);
+          line.appendChild(calc);
+          list.appendChild(line);
+        });
+      }
+      sheet.appendChild(list);
+      pages.appendChild(sheet);
+    });
+    document.body.classList.add("printing-cells");
+    document.getElementById("rvp-overlay").classList.add("is-open");
+  }
+  function closePreview() {
+    document.getElementById("rvp-overlay").classList.remove("is-open");
+    document.body.classList.remove("printing-cells");
+  }
+
+  // ── 창고 POG: 면(Side A/B/Ground)마다 A4 가로 1장 미리보기 ──
+  function openPOG() {
+    var board = document.getElementById("rv-board");
+    var pages = document.getElementById("pog-pages");
+    if (!board || !pages) return;
+
+    var wh = board.getAttribute("data-wh") || "";
+    var st = board.getAttribute("data-stocktake") || "";
+    var metaTxt = [wh, st].filter(Boolean).join("  |  ");
+
+    pages.innerHTML = "";
+    [].slice.call(board.querySelectorAll(".rv-side")).forEach(function (side) {
+      var sheet = document.createElement("div");
+      sheet.className = "pog-sheet";
+
+      // 머리말: 면 이름(Side A/B/Ground) + 창고/기준 재고조사
+      var head = document.createElement("div");
+      head.className = "pog-sheet-head";
+      var ttl = document.createElement("span");
+      ttl.className = "pog-t";
+      var h3 = side.querySelector("h3");
+      ttl.textContent = h3 ? h3.textContent.trim() : t("창고 POG", "Warehouse POG");
+      var meta = document.createElement("span");
+      meta.className = "pog-meta";
+      meta.textContent = metaTxt;
+      head.appendChild(ttl);
+      head.appendChild(meta);
+      sheet.appendChild(head);
+
+      // 면 복제 → 인터랙티브 요소 제거(체크박스/드래그)
+      var clone = side.cloneNode(true);
+      [].slice.call(clone.querySelectorAll(".rv-cell")).forEach(function (c) {
+        c.removeAttribute("draggable");
+        c.classList.remove("is-selected", "is-dragover", "dragging");
+      });
+      [].slice.call(clone.querySelectorAll(".rv-pick")).forEach(function (cb) {
+        cb.parentNode && cb.parentNode.removeChild(cb);
+      });
+      sheet.appendChild(clone);
+      pages.appendChild(sheet);
+    });
+
+    document.body.classList.add("printing-pog");
+    document.getElementById("pog-overlay").classList.add("is-open");
+  }
+  function closePOG() {
+    document.getElementById("pog-overlay").classList.remove("is-open");
+    document.body.classList.remove("printing-pog");
+  }
+
+  document.addEventListener("DOMContentLoaded", function () {
+    renderAll();
+    var board = document.getElementById("rv-board");
+    if (board) {
+      board.addEventListener("dragstart", onDragStart);
+      board.addEventListener("dragover", onDragOver);
+      board.addEventListener("dragleave", onDragLeave);
+      board.addEventListener("drop", onDrop);
+      board.addEventListener("dragend", cleanup);
+      board.addEventListener("change", onChange);
+    }
+    var sb = document.getElementById("rv-save-btn");
+    if (sb) sb.addEventListener("click", save);
+    var pb = document.getElementById("rv-print-btn");
+    if (pb) pb.addEventListener("click", openPreview);
+    var pc = document.getElementById("rvp-close");
+    if (pc) pc.addEventListener("click", closePreview);
+    var pp = document.getElementById("rvp-print");
+    if (pp) pp.addEventListener("click", function () { window.print(); });
+    var gb = document.getElementById("rv-pog-btn");
+    if (gb) gb.addEventListener("click", openPOG);
+    var gc = document.getElementById("pog-close");
+    if (gc) gc.addEventListener("click", closePOG);
+    var gp = document.getElementById("pog-print");
+    if (gp) gp.addEventListener("click", function () { window.print(); });
+    var lt = document.getElementById("mys-lang-toggle");
+    if (lt) lt.addEventListener("click", function () { setTimeout(renderAll, 0); });
+    window.addEventListener("beforeunload", function (ev) {
+      if (dirty) { ev.preventDefault(); ev.returnValue = ""; }
+    });
+  });
+})();

app/static/project.css

@@ -0,0 +1,319 @@
+/* 프로젝트 관리(아사나식) 모듈 스타일.
+ * 기존 erp.css 토큰 위에 아사나 느낌(밝은 캔버스, 색 점, 칸반 컬럼)을 얹는다. */
+
+.pj-wrap { padding: 4px 2px 40px; }
+
+/* ── 버튼 ── */
+.pj-btn {
+  border: 1px solid #d8dce2; background: #fff; color: #1e1f21;
+  padding: 7px 14px; border-radius: 8px; font-size: 13px; font-weight: 600;
+  cursor: pointer; transition: background .12s, border-color .12s;
+}
+.pj-btn:hover { background: #f6f7f8; }
+.pj-btn-primary { background: #1e1f21; color: #fff; border-color: #1e1f21; }
+.pj-btn-primary:hover { background: #000; }
+.pj-btn-danger { background: #fff; color: #c22b10; border-color: #e6c4bd; }
+.pj-btn-danger:hover { background: #fbecea; }
+.pj-icon-btn {
+  border: none; background: transparent; color: #6b7280; cursor: pointer;
+  font-size: 16px; line-height: 1; width: 24px; height: 24px; border-radius: 6px;
+}
+.pj-icon-btn:hover { background: #eceef0; color: #1e1f21; }
+
+.pj-section-head { display: flex; align-items: center; justify-content: space-between; margin: 8px 0 14px; }
+.pj-section-head h2 { font-size: 16px; font-weight: 700; margin: 0; }
+
+.pj-empty { padding: 28px; text-align: center; color: #6b7280; background: #f7f8f9; border-radius: 12px; }
+.pj-empty-sm { padding: 10px 2px; color: #9aa1a9; font-size: 13px; }
+
+.pj-chip { display: inline-block; padding: 2px 8px; border-radius: 999px; background: #eef0f2; color: #525860; font-size: 11px; font-weight: 600; }
+.pj-chip-sm { padding: 1px 6px; font-size: 10px; }
+
+/* ── 홈 ── */
+.pj-home { display: grid; grid-template-columns: 1fr 320px; gap: 28px; align-items: start; }
+@media (max-width: 980px) { .pj-home { grid-template-columns: 1fr; } }
+
+.pj-project-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 14px; }
+.pj-project-card {
+  position: relative; border: 1px solid #e7e9ec; border-radius: 14px;
+  background: #fff; transition: box-shadow .14s, transform .1s;
+}
+.pj-project-card:hover { box-shadow: 0 4px 16px rgba(0,0,0,.08); transform: translateY(-1px); }
+.pj-project-cardlink { display: flex; gap: 12px; padding: 16px; text-decoration: none; color: inherit; }
+/* 완료 프로젝트 — 비활성(흐리게) */
+.pj-project-card.is-done { background: #f6f7f8; opacity: .62; }
+.pj-project-card.is-done:hover { opacity: .85; }
+.pj-project-card.is-done .pj-project-dot { background: #9aa5b1; }
+/* 완료 숨기기 토글 */
+.pj-project-grid.pj-hide-done .pj-project-card.is-done { display: none; }
+/* 카드 수정 버튼 */
+.pj-card-edit {
+  position: absolute; top: 8px; right: 8px; width: 28px; height: 28px;
+  display: inline-flex; align-items: center; justify-content: center;
+  border-radius: 8px; color: #6b7280; opacity: 0; transition: opacity .12s;
+}
+.pj-card-edit .material-symbols-outlined { font-size: 18px; }
+.pj-project-card:hover .pj-card-edit { opacity: 1; }
+.pj-card-edit:hover { background: #eceef0; color: #1e1f21; }
+.pj-project-dot { width: 10px; height: 10px; border-radius: 50%; background: var(--pj-color, #4573d2); margin-top: 5px; flex: 0 0 auto; }
+.pj-project-name { font-weight: 700; font-size: 15px; }
+.pj-project-desc { color: #6b7280; font-size: 12.5px; margin-top: 3px; }
+.pj-project-meta { margin-top: 10px; display: flex; gap: 6px; flex-wrap: wrap; }
+
+.pj-home-side { border-left: 1px solid #eef0f2; padding-left: 24px; }
+@media (max-width: 980px) { .pj-home-side { border-left: none; padding-left: 0; } }
+.pj-mytask-list { list-style: none; margin: 0; padding: 0; }
+.pj-mytask a { display: flex; align-items: center; gap: 8px; padding: 9px 6px; border-radius: 8px; text-decoration: none; color: inherit; }
+.pj-mytask a:hover { background: #f6f7f8; }
+.pj-mytask.is-done .pj-mytask-title { text-decoration: line-through; color: #9aa1a9; }
+.pj-mytask-dot { width: 8px; height: 8px; border-radius: 50%; flex: 0 0 auto; }
+.pj-mytask-title { font-size: 13.5px; font-weight: 600; }
+.pj-mytask-meta { margin-left: auto; font-size: 11px; color: #9aa1a9; }
+
+/* ── 프로젝트 페이지 레이아웃 ── */
+.pj-layout { display: grid; grid-template-columns: 230px 1fr; gap: 22px; align-items: start; }
+@media (max-width: 900px) { .pj-layout { grid-template-columns: 1fr; } }
+
+.pj-side-block { margin-bottom: 22px; }
+.pj-side-head { display: flex; align-items: center; justify-content: space-between; font-size: 12px; font-weight: 700; color: #6b7280; text-transform: uppercase; letter-spacing: .04em; margin-bottom: 8px; }
+.pj-member-list { list-style: none; margin: 0; padding: 0; }
+.pj-member-list li { display: flex; align-items: center; gap: 8px; padding: 5px 4px; border-radius: 7px; }
+.pj-member-list li:hover { background: #f6f7f8; }
+.pj-member-name { font-size: 13px; flex: 1; }
+
+/* ── 아사나식 프로젝트 트리 ── */
+.pj-tree { list-style: none; margin: 0; padding: 0; }
+.pj-tree .pj-tree { padding-left: 0; }   /* 들여쓰기는 row 패딩으로 처리 */
+.pj-tree-row { display: flex; align-items: center; gap: 2px; border-radius: 7px; padding-right: 2px;
+               padding-left: calc(var(--pj-indent, 0) * 16px); position: relative; }
+.pj-tree-row:hover { background: #f1f2f4; }
+.pj-tree-row.is-active { background: #ececf8; }
+.pj-tree-row.is-active .pj-tree-name { font-weight: 700; color: #1e1f21; }
+.pj-tree-caret { border: none; background: transparent; cursor: pointer; width: 20px; height: 26px;
+                 display: inline-flex; align-items: center; justify-content: center; color: #6b7280; padding: 0; }
+.pj-tree-caret .material-symbols-outlined { font-size: 18px; transition: transform .12s; }
+.pj-tree-caret.is-open .material-symbols-outlined { transform: rotate(90deg); }
+.pj-tree-caret-spacer { width: 20px; flex: 0 0 auto; }
+.pj-tree-link { display: flex; align-items: center; gap: 7px; flex: 1; min-width: 0;
+                text-decoration: none; color: inherit; padding: 5px 2px; }
+.pj-tree-icon { font-size: 18px; flex: 0 0 auto; }
+.pj-tree-name { font-size: 13.5px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pj-tree-acts { display: none; gap: 0; flex: 0 0 auto; }
+.pj-tree-row:hover .pj-tree-acts { display: inline-flex; }
+.pj-tree-acts .pj-icon-btn { width: 22px; height: 22px; font-size: 14px; }
+.pj-tree-done { text-decoration: line-through; color: #9aa1a9; }
+.pj-tree-task .pj-tree-name { font-size: 13px; color: #444; }
+
+/* 구글 머티리얼 심볼 아이콘(담당자) */
+.material-symbols-outlined { font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24; line-height: 1; vertical-align: middle; }
+.pj-gicon { font-size: 24px; color: #5f6368; flex: 0 0 auto; }
+.pj-gicon-sm { font-size: 20px; }
+.pj-assignee { display: inline-flex; align-items: center; gap: 4px; font-size: 12px; color: #5f6368; }
+/* 구글 프로필 이미지 — 원형 */
+.pj-avatar { width: 22px; height: 22px; border-radius: 50%; object-fit: cover; flex: 0 0 auto; vertical-align: middle; background: #e7e9ec; }
+.pj-avatar.pj-gicon-sm { width: 18px; height: 18px; }
+
+/* ── 툴바 + 탭 ── */
+.pj-toolbar { display: flex; align-items: center; justify-content: space-between; margin-bottom: 16px; }
+.pj-view-tabs { display: inline-flex; background: #eef0f2; border-radius: 10px; padding: 3px; gap: 2px; }
+.pj-tab { border: none; background: transparent; padding: 7px 16px; border-radius: 8px; font-size: 13px; font-weight: 600; color: #525860; cursor: pointer; }
+.pj-tab.is-active { background: #1e1f21; color: #fff; box-shadow: 0 1px 3px rgba(0,0,0,.18); }
+
+/* 알림 벨 흔들림(미읽음 있을 때) */
+@keyframes pj-bell-ring {
+  0%, 50%, 100% { transform: rotate(0); }
+  10%, 30% { transform: rotate(14deg); }
+  20%, 40% { transform: rotate(-14deg); }
+}
+.pj-bell.has-unread .material-symbols-outlined {
+  animation: pj-bell-ring 1.4s ease-in-out infinite;
+  transform-origin: top center;
+}
+
+/* ── 보드(칸반) ── */
+.pj-board { display: flex; gap: 14px; overflow-x: auto; padding-bottom: 8px; align-items: flex-start; }
+.pj-col { flex: 0 0 272px; background: #f7f8f9; border-radius: 12px; padding: 10px; }
+.pj-col-head { display: flex; align-items: center; gap: 6px; font-weight: 700; font-size: 13px; padding: 4px 6px 10px; }
+.pj-col-count { margin-left: auto; color: #9aa1a9; font-weight: 600; }
+.pj-col-body { display: flex; flex-direction: column; gap: 8px; min-height: 40px; border-radius: 8px; }
+.pj-col-body.is-over { background: #e6ecfa; outline: 2px dashed #aebfe6; }
+.pj-card { background: #fff; border: 1px solid #e7e9ec; border-radius: 10px; padding: 10px 12px; cursor: pointer; box-shadow: 0 1px 2px rgba(0,0,0,.04); }
+.pj-card:hover { border-color: #c9cdd3; }
+.pj-card.is-dragging { opacity: .5; }
+.pj-card.is-done .pj-card-title { text-decoration: line-through; color: #9aa1a9; }
+.pj-card-title { font-size: 13.5px; font-weight: 600; }
+.pj-card-meta { display: flex; align-items: center; gap: 6px; margin-top: 8px; }
+.pj-card-due { margin-left: auto; font-size: 11px; color: #9aa1a9; }
+.pj-pri { padding: 1px 7px; border-radius: 999px; font-size: 10px; font-weight: 700; }
+.pj-pri-high { background: #fbe3df; color: #c22b10; }
+.pj-pri-low { background: #e6eef0; color: #4a6066; }
+
+/* ── 리스트 ── */
+.pj-table { width: 100%; border-collapse: collapse; font-size: 13.5px; }
+.pj-table th { text-align: left; padding: 9px 10px; border-bottom: 2px solid #eef0f2; color: #1e1f21; font-size: 14px; font-weight: 700; position: relative; }
+.pj-table td { padding: 10px; border-bottom: 1px solid #f1f2f4; }
+.pj-table tr.is-done td { color: #9aa1a9; text-decoration: line-through; }
+.pj-table-fixed { table-layout: fixed; }
+.pj-table-fixed th, .pj-table-fixed td { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pj-th-label { cursor: pointer; user-select: none; display: inline-flex; align-items: center; gap: 4px; }
+.pj-th-label:hover { color: #4573d2; }
+.pj-th-sort { font-size: 11px; color: #9aa1a9; }
+.pj-th-resize { position: absolute; top: 0; right: -3px; width: 8px; height: 100%; cursor: col-resize; z-index: 2; }
+.pj-th-resize:hover { background: linear-gradient(90deg, transparent 40%, #c9d4ea 40%, #c9d4ea 60%, transparent 60%); }
+
+/* ── 내 업무 트리(홈) ── */
+.pj-mytree-group { margin-bottom: 14px; }
+.pj-mytree-proj { display: flex; align-items: center; gap: 7px; text-decoration: none; color: #1e1f21; font-weight: 700; font-size: 13.5px; padding: 4px 2px; border-radius: 7px; }
+.pj-mytree-proj:hover { background: #f6f7f8; }
+.pj-mytree-tasks { list-style: none; margin: 2px 0 0; padding: 0 0 0 8px; border-left: 2px solid #eef0f2; margin-left: 10px; }
+.pj-mytree-task a { display: flex; align-items: flex-start; gap: 7px; padding: 6px 6px; border-radius: 7px; text-decoration: none; color: inherit; }
+.pj-mytree-task a:hover { background: #f6f7f8; }
+.pj-mytree-ic { font-size: 16px; flex: 0 0 auto; margin-top: 1px; }
+.pj-mytree-body { display: flex; flex-direction: column; min-width: 0; }
+.pj-mytree-title { font-size: 13px; font-weight: 600; }
+.pj-mytree-dates { font-size: 11px; color: #9aa1a9; margin-top: 1px; }
+.pj-mytree-task.is-done .pj-mytree-title { text-decoration: line-through; color: #9aa1a9; }
+
+/* ── 달력 (휴가 모듈과 동일한 월간 그리드 룩) ── */
+.pj-cal-head { display: flex; align-items: center; gap: 10px; margin-bottom: 12px; }
+.pj-cal-title { font-size: 18pt; font-weight: 600; margin: 0; letter-spacing: -0.45px; }
+.pj-nav-btn { padding: 2px 12px; font-size: 18pt; line-height: 1; }
+.pj-today-btn { margin-left: auto; }
+
+.pj-cal { border: 1px solid #e5e5e5; border-radius: 10px; overflow: hidden; display: flex; flex-direction: column; }
+.pj-wd-row { display: grid; grid-template-columns: repeat(7, minmax(0, 1fr)); background: #f2f2f2; border-bottom: 1px solid #e5e5e5; }
+.pj-wd { text-align: center; padding: 8px 0; font-size: 15px; font-weight: 600; color: #0a0a0a; border-right: 1px solid #e5e5e5; }
+.pj-wd:last-child { border-right: none; }
+
+/* 주(week) — 날짜 셀 위에 bar 레이어 오버레이. 6주가 높이 균등 분할. */
+.pj-week { position: relative; border-bottom: 1px solid #e5e5e5; flex: 1 1 0; min-height: 134px; display: flex; flex-direction: column; }
+.pj-week:last-child { border-bottom: none; }
+.pj-week-days { display: grid; grid-template-columns: repeat(7, minmax(0, 1fr)); flex: 1 1 auto; min-height: 0; }
+.pj-day { height: 100%; border-right: 1px solid #e5e5e5; padding: 6px 8px; box-sizing: border-box; }
+.pj-day:last-child { border-right: none; }
+.pj-day-num { font-size: 20px; font-weight: 600; color: #0a0a0a; }
+.pj-out { background: #fafafa; }
+.pj-out .pj-day-num { color: #bbb; }
+.pj-today { background: #f5f5f5; }
+.pj-today .pj-day-num { background: #0a0a0a; color: #fff !important; border-radius: 9999px; padding: 2px 9px; }
+.pj-today .pj-day-num.pj-red { background: #c22b10; }
+.pj-today .pj-day-num.pj-blue { background: #1d4ed8; }
+.pj-red { color: #c22b10 !important; }
+.pj-blue { color: #1d4ed8 !important; }
+
+/* bar 오버레이 — 날짜 숫자 아래(top)부터 7열 그리드로 겹쳐 그림 */
+.pj-week-bars { position: absolute; left: 0; right: 0; top: 34px; bottom: 4px; display: grid; grid-template-columns: repeat(7, minmax(0, 1fr)); grid-auto-rows: 22px; row-gap: 2px; pointer-events: none; }
+.pj-bar { margin: 0 3px; padding: 0 7px; height: 20px; line-height: 20px; border-radius: 5px; font-size: 12.5px; font-weight: 500; color: #fff; text-decoration: none; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; align-self: center; pointer-events: auto; cursor: pointer; }
+.pj-bar:hover { filter: brightness(.93); }
+.pj-bar-label { pointer-events: none; }
+/* "+N 더" 칩 — 넘친 업무. 클릭 시 그날 목록 팝오버 */
+.pj-bar-more { margin: 0 3px; height: 18px; line-height: 18px; align-self: center; font-size: 11.5px; font-weight: 600; color: #5a6772; cursor: pointer; pointer-events: auto; padding: 0 4px; border-radius: 5px; }
+.pj-bar-more:hover { background: #eceef0; color: #1e1f21; }
+/* 그날 업무 팝오버 */
+.pj-daypop { position: absolute; z-index: 2100; min-width: 200px; max-width: 280px; background: #fff; border: 1px solid #e2e5e9; border-radius: 12px; box-shadow: 0 8px 28px rgba(0,0,0,.16); padding: 8px; }
+.pj-daypop-head { font-size: 12px; font-weight: 700; color: #525860; padding: 4px 6px 8px; }
+.pj-daypop-item { display: flex; align-items: center; gap: 8px; padding: 6px 6px; border-radius: 8px; cursor: pointer; font-size: 13px; }
+.pj-daypop-item:hover { background: #f2f4f6; }
+.pj-daypop-item.is-done .pj-daypop-title { text-decoration: line-through; color: #9aa1a9; }
+.pj-daypop-dot { width: 9px; height: 9px; border-radius: 50%; flex: 0 0 auto; }
+.pj-daypop-title { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pj-bar-l { border-top-left-radius: 0; border-bottom-left-radius: 0; margin-left: 0; }
+.pj-bar-r { border-top-right-radius: 0; border-bottom-right-radius: 0; margin-right: 0; }
+.pj-bar-done { opacity: .75; text-decoration: line-through; }
+/* 드래그 이동(포인터 기반) — 드래그 중엔 bar 가 이벤트 가로채지 않게(elementFromPoint 가 날짜 셀 반환) */
+.pj-cal-dragging { cursor: grabbing; }
+.pj-cal-dragging .pj-bar { pointer-events: none; }
+.pj-project-view[data-can-manage="true"] .pj-bar { cursor: grab; }
+.pj-day.pj-drop-over { background: #e6ecfa; box-shadow: inset 0 0 0 2px #aebfe6; }
+/* 드래그 중 따라다니는 고스트 라벨 */
+.pj-bar-ghost { position: fixed; z-index: 2000; pointer-events: none; padding: 2px 10px; border-radius: 6px; background: #1e1f21; color: #fff; font-size: 12px; box-shadow: 0 4px 14px rgba(0,0,0,.3); white-space: nowrap; }
+
+/* ── 타임라인 컨테이너 ── */
+#pj-timeline { background: #fff; border-radius: 12px; padding: 6px; }
+
+/* ── 모달 ── */
+.pj-modal { position: fixed; inset: 0; background: rgba(20,22,26,.46); display: flex; align-items: center; justify-content: center; z-index: 1000; }
+.pj-modal[hidden] { display: none; }
+.pj-modal-card { background: #fff; border-radius: 16px; padding: 22px; width: min(480px, 92vw); box-shadow: 0 20px 60px rgba(0,0,0,.25); }
+.pj-modal-card h3 { margin: 0 0 16px; font-size: 17px; }
+.pj-modal-hint { margin: -6px 0 14px; font-size: 12px; color: #6b7280; }
+.pj-modal-card label { display: block; font-size: 12.5px; font-weight: 600; color: #525860; margin-bottom: 12px; }
+.pj-modal-card input[type=text], .pj-modal-card input[type=date], .pj-modal-card textarea, .pj-modal-card select {
+  display: block; width: 100%; margin-top: 5px; padding: 8px 10px; border: 1px solid #d8dce2; border-radius: 8px; font-size: 13.5px; font-family: inherit; box-sizing: border-box;
+}
+.pj-form-row { display: flex; gap: 12px; }
+.pj-form-row label { flex: 1; }
+.pj-time-toggle { display: flex; align-items: center; gap: 7px; font-size: 12.5px; font-weight: 600; color: #525860; margin-bottom: 12px; cursor: pointer; }
+.pj-time-toggle input { width: auto; margin: 0; }
+.pj-form-row input[type="time"] { display: block; width: 100%; margin-top: 5px; padding: 8px 10px; border: 1px solid #d8dce2; border-radius: 8px; font-size: 13.5px; font-family: inherit; box-sizing: border-box; }
+.pj-form-row input[type="time"]:disabled { background: #f2f2f2; color: #aaa; cursor: not-allowed; }
+#pj-time-row:has(input:disabled) label { color: #aaa; }
+.pj-modal-actions { display: flex; align-items: center; gap: 8px; margin-top: 8px; }
+.pj-modal-actions .pj-btn:last-child { }
+
+.pj-color-palette, #pj-f-colors { display: flex; gap: 8px; margin-top: 6px; }
+.pj-color-swatch { width: 24px; height: 24px; border-radius: 50%; border: 2px solid transparent; cursor: pointer; }
+.pj-color-swatch.is-active { border-color: #1e1f21; box-shadow: 0 0 0 2px #fff inset; }
+
+/* ── 알림 벨 ── */
+.pj-toolbar-right { display: flex; align-items: center; gap: 12px; }
+.pj-bell { position: relative; display: inline-flex; align-items: center; justify-content: center; width: 38px; height: 38px; border-radius: 10px; color: #525860; text-decoration: none; }
+.pj-bell:hover { background: #eceef0; }
+.pj-bell-badge { position: absolute; top: 3px; right: 3px; min-width: 16px; height: 16px; padding: 0 4px; border-radius: 999px; background: #e8384f; color: #fff; font-size: 10px; font-weight: 700; line-height: 16px; text-align: center; }
+
+/* ── 업무 모달 댓글/첨부 ── */
+.pj-task-extra { border-top: 1px solid #eef0f2; margin-top: 14px; padding-top: 12px; }
+.pj-extra-head { display: flex; align-items: center; gap: 6px; font-size: 13px; font-weight: 700; color: #525860; margin-bottom: 8px; }
+.pj-upload-btn { margin-left: auto; font-size: 12px; font-weight: 600; color: #4573d2; cursor: pointer; padding: 3px 8px; border: 1px solid #cdd9f0; border-radius: 7px; }
+.pj-upload-btn:hover { background: #eef3fc; }
+
+.pj-attach-list, .pj-comment-list { list-style: none; margin: 0 0 6px; padding: 0; max-height: 160px; overflow-y: auto; }
+.pj-attach-item { display: flex; align-items: center; gap: 8px; padding: 5px 4px; font-size: 13px; }
+.pj-attach-item a { color: #2b4a85; text-decoration: none; flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pj-attach-item a:hover { text-decoration: underline; }
+.pj-attach-size { font-size: 11px; color: #9aa1a9; }
+
+.pj-comment-item { display: flex; align-items: flex-start; gap: 8px; padding: 7px 2px; }
+.pj-comment-main { flex: 1; }
+.pj-comment-head { font-size: 12.5px; font-weight: 700; color: #1e1f21; }
+.pj-comment-time { font-weight: 400; color: #9aa1a9; font-size: 11px; margin-left: 6px; }
+.pj-comment-body { font-size: 13px; color: #333; margin-top: 1px; white-space: pre-wrap; }
+.pj-comment-form { display: flex; gap: 6px; }
+.pj-comment-form input { flex: 1; padding: 7px 10px; border: 1px solid #d8dce2; border-radius: 8px; font-size: 13px; font-family: inherit; }
+.pj-comment-acts { display: inline-flex; gap: 1px; flex: 0 0 auto; }
+.pj-comment-edit-box { margin-top: 5px; }
+.pj-comment-edit-box textarea { width: 100%; box-sizing: border-box; padding: 7px 9px; border: 1px solid #d8dce2; border-radius: 8px; font-size: 13px; font-family: inherit; resize: vertical; }
+.pj-comment-edit-actions { display: flex; gap: 6px; justify-content: flex-end; margin-top: 6px; }
+.pj-comment-edit-actions .pj-btn { padding: 4px 12px; font-size: 12px; }
+
+/* 보드 카드 — 전체 뷰에서 어느 프로젝트인지 배지 표시 */
+.pj-card-proj { font-size: 11px; font-weight: 700; margin-bottom: 3px; letter-spacing: -.2px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+/* 댓글 말풍선(💬 이모지) 표시 */
+.pj-cmt-ic { font-size: 12px; vertical-align: middle; margin-left: 4px; line-height: 1; }
+.pj-cmt-n { font-size: 11px; font-weight: 700; vertical-align: middle; margin-left: 1px; }
+.pj-card-cmt { display: inline-flex; align-items: center; color: #6b7280; }
+
+/* ── 보드 단계 컨트롤 ── */
+.pj-col-head { position: relative; }
+.pj-col-name { font-weight: 700; }
+.pj-col-ctrls { display: none; gap: 1px; margin-left: 6px; }
+.pj-col:hover .pj-col-ctrls { display: inline-flex; }
+.pj-col-ctrls .pj-icon-btn { width: 20px; height: 20px; font-size: 13px; }
+.pj-icon-btn[disabled] { opacity: .3; cursor: default; }
+.pj-col-add { background: transparent; flex: 0 0 180px; }
+.pj-add-stage { width: 100%; padding: 10px; border: 1px dashed #c9cdd3; border-radius: 12px; background: #fff; color: #6b7280; font-size: 13px; font-weight: 600; cursor: pointer; }
+.pj-add-stage:hover { border-color: #1e1f21; color: #1e1f21; }
+
+/* ── 알림센터 ── */
+.pj-inbox { list-style: none; margin: 0; padding: 0; }
+.pj-inbox-item { display: flex; align-items: flex-start; gap: 12px; padding: 14px 12px; border: 1px solid #eef0f2; border-radius: 12px; margin-bottom: 8px; cursor: pointer; background: #fff; }
+.pj-inbox-item:hover { border-color: #d8dce2; }
+.pj-inbox-item.is-unread { background: #f4f8ff; border-color: #d6e2fb; }
+.pj-inbox-icon { color: #4573d2; font-size: 22px; flex: 0 0 auto; }
+.pj-inbox-body { flex: 1; }
+.pj-inbox-title { font-size: 14px; font-weight: 600; }
+.pj-inbox-item.is-unread .pj-inbox-title::before { content: "●"; color: #4573d2; font-size: 9px; vertical-align: middle; margin-right: 6px; }
+.pj-inbox-sub { font-size: 12.5px; color: #525860; margin-top: 2px; }
+.pj-inbox-meta { font-size: 11px; color: #9aa1a9; margin-top: 4px; }
+.pj-inbox-go { align-self: center; padding: 4px 12px; font-size: 12px; }

app/static/vendor/material-symbols/material-symbols.css

@@ -0,0 +1,26 @@
+/* Material Symbols Outlined — self-host (구글 CDN 대체).
+   원본: https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined
+   폰트 파일은 같은 폴더 material-symbols-outlined.woff2. */
+@font-face {
+  font-family: 'Material Symbols Outlined';
+  font-style: normal;
+  font-weight: 400;
+  src: url(material-symbols-outlined.woff2) format('woff2');
+}
+
+.material-symbols-outlined {
+  font-family: 'Material Symbols Outlined';
+  font-weight: normal;
+  font-style: normal;
+  font-size: 24px;
+  line-height: 1;
+  letter-spacing: normal;
+  text-transform: none;
+  display: inline-block;
+  white-space: nowrap;
+  word-wrap: normal;
+  direction: ltr;
+  -webkit-font-feature-settings: 'liga';
+  -webkit-font-smoothing: antialiased;
+  font-variation-settings: 'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24;
+}

app/store.py

@@ -28,6 +28,10 @@ MODULE_KEYS: tuple[str, ...] = (
     "expense",
     "vacation",
     "cupang",
+    "malaysia",
+    "dispatch",
+    "project",
+    "cafe24",
     "expense_approver",
     "vacation_approver",
 )
@@ -79,14 +83,14 @@ class UserStore:
 
     @staticmethod
     def _normalize_modules(modules: dict[str, Any] | None, *, is_admin: bool) -> dict[str, bool]:
+        # 신규(modules 미지정) 사용자는 역할 기본값(admin=전체ON / user=전체OFF)으로 시작.
+        # 기존 값이 있으면 그대로 존중한다 — admin 이라도 슈퍼관리자가 개별 모듈을
+        # 끌 수 있다(예전엔 admin 을 무조건 전체 ON 으로 덮어썼다).
         base = UserStore._default_modules(is_admin)
         if isinstance(modules, dict):
             for key in MODULE_KEYS:
                 if key in modules:
                     base[key] = bool(modules[key])
-        if is_admin:
-            for key in MODULE_KEYS:
-                base[key] = True
         return base
 
     def get(self, email: str) -> dict[str, Any] | None:
@@ -227,7 +231,9 @@ def is_admin(user_rec: dict[str, Any] | None) -> bool:
 def has_module(user_rec: dict[str, Any] | None, module: str) -> bool:
     if not user_rec:
         return False
-    if is_admin(user_rec):
+    # 슈퍼관리자는 항상 전체 접근. 일반 admin 은 칩(modules) 상태를 따른다 —
+    # 슈퍼관리자가 admin 의 개별 프로그램 접근을 제어할 수 있도록.
+    if user_rec.get("is_super_admin"):
         return True
     mods = user_rec.get("modules") or {}
     if mods.get(module):

app/templates/admin.html

@@ -24,11 +24,30 @@
         font-family: inherit;
       }
 
-      .erp-mod-th { text-align: center; font-size: 11px; padding: 6px 4px; }
+      .erp-mod-group { display: inline-block; margin-left: 6px; padding: 2px 6px; border-radius: 6px;
-      .erp-mod-cell { text-align: center; padding: 4px; }
-      .erp-mod-group { display: inline-block; padding: 2px 6px; border-radius: 6px;
                        background: var(--color-ghost-gray); color: var(--color-midtone-gray);
-                       font-size: 10px; font-weight: 500; }
+                       font-size: 10px; font-weight: 500; vertical-align: middle; }
+
+      /* 권한 칩 — 모듈 수가 늘어도 줄바꿈되어 가로로 안 넓어짐 */
+      .erp-perm-cell { padding: 8px 6px; }
+      .erp-perm-chip {
+        display: inline-flex; align-items: center; gap: 4px;
+        margin: 3px; padding: 4px 11px; border-radius: 999px;
+        border: 1px solid var(--color-subtle-ash); background: #fff;
+        color: var(--color-midtone-gray); font-size: 12px; font-weight: 500;
+        font-family: inherit; cursor: pointer; user-select: none;
+        transition: background .1s, color .1s, border-color .1s;
+      }
+      .erp-perm-chip:hover { border-color: var(--color-midtone-gray); }
+      .erp-perm-chip.is-on {
+        background: var(--color-rich-black); color: #fff; border-color: var(--color-rich-black);
+      }
+      /* 승인 권한 칩 — 켜지면 파랑 강조로 구분 */
+      .erp-perm-chip.is-approver.is-on {
+        background: #1d4ed8; border-color: #1d4ed8;
+      }
+      .erp-perm-chip[data-locked="true"] { opacity: .5; cursor: not-allowed; }
+      .erp-perm-chip[data-locked="true"]:hover { border-color: var(--color-subtle-ash); }
     </style>
   </head>
   <body class="erp-body">
@@ -89,15 +108,10 @@
           <table class="erp-table" id="users-table">
             <thead>
               <tr>
-                <th style="width: 22%;">사용자</th>
+                <th style="width: 200px;">사용자</th>
                 <th style="width: 80px;">역할</th>
-                {% for key in module_keys %}
+                <th>접근 권한 <span class="erp-mod-group">클릭하여 토글</span></th>
-                <th class="erp-mod-th">
+                <th style="width: 110px;">최근 로그인</th>
-                  {{ module_labels.get(key, key) }}
-                  {% if key in approver_keys %}<br><span class="erp-mod-group">승인</span>{% endif %}
-                </th>
-                {% endfor %}
-                <th style="width: 120px;">최근 로그인</th>
                 <th style="width: 130px; text-align: right;">동작</th>
               </tr>
             </thead>
@@ -130,18 +144,19 @@
                     <option value="admin" {% if u.role == 'admin' %}selected{% endif %}>admin</option>
                   </select>
                 </td>
-                {% for key in module_keys %}
+                <td class="erp-perm-cell">
-                <td class="erp-mod-cell">
+                  {% for key in module_keys %}
-                  <label class="erp-switch">
+                  <button type="button"
-                    <input type="checkbox"
+                          class="erp-perm-chip
-                           data-field="module"
+                                 {% if u.modules[key] %}is-on{% endif %}
-                           data-module="{{ key }}"
+                                 {% if key in approver_keys %}is-approver{% endif %}"
-                           {% if u.modules[key] %}checked{% endif %}
+                          data-module="{{ key }}"
-                           {% if u.is_super_admin or u.role == 'admin' %}disabled{% endif %} />
+                          aria-pressed="{{ 'true' if u.modules[key] else 'false' }}"
-                    <span class="erp-switch-slider"></span>
+                          {% if u.is_super_admin %}data-locked="true"{% endif %}>
-                  </label>
+                    {{ module_labels.get(key, key) }}{% if key in approver_keys %} 승인{% endif %}
+                  </button>
+                  {% endfor %}
                 </td>
-                {% endfor %}
                 <td style="font-size:12px; color: var(--color-midtone-gray);">
                   {{ (u.last_login or '미접속')[:16].replace('T', ' ') }}
                 </td>
@@ -160,8 +175,8 @@
         </div>
 
         <p class="erp-section-meta" style="margin-top: var(--sp-16);">
-          ※ <strong>{{ super_admin_email }}</strong> 은(는) 슈퍼 관리자, 권한 변경/삭제 불가.
+          ※ <strong>{{ super_admin_email }}</strong> 은(는) 슈퍼 관리자, 권한 변경/삭제 불가(항상 전체 접근).
-          admin 역할은 모든 모듈 권한 자동 부여.
+          admin 역할은 기본 전체 ON 이지만 슈퍼관리자가 개별 프로그램 접근을 끌 수 있다.
           <code>expense_approver</code> / <code>vacation_approver</code> 는 결재 승인 권한.
         </p>
 
@@ -188,15 +203,22 @@
         showToast._t = setTimeout(() => { toastEl.dataset.visible = "false"; }, 2400);
       }
 
-      function syncModuleSwitches(tr) {
+      function syncPermChips(tr) {
+        // 슈퍼관리자만 전체 ON + 잠금. 일반 admin 은 슈퍼관리자가 개별 제어 가능.
+        // 역할을 admin 으로 바꾸면 편의상 전체 ON(잠금 아님 — 다시 끌 수 있음).
         const isSuper = tr.dataset.super === "true";
-        const role = tr.querySelector("select[data-field='role']").value;
+        const adminRole = tr.querySelector("select[data-field='role']").value === "admin";
-        const adminRole = role === "admin";
+        tr.querySelectorAll(".erp-perm-chip").forEach((chip) => {
-        tr.querySelectorAll("input[data-field='module']").forEach((cb) => {
+          if (isSuper) {
-          if (isSuper || adminRole) {
+            chip.classList.add("is-on");
-            cb.checked = true; cb.disabled = true;
+            chip.setAttribute("aria-pressed", "true");
+            chip.setAttribute("data-locked", "true");
           } else {
-            cb.disabled = false;
+            chip.removeAttribute("data-locked");
+            if (adminRole) {
+              chip.classList.add("is-on");
+              chip.setAttribute("aria-pressed", "true");
+            }
           }
         });
       }
@@ -204,12 +226,22 @@
       tbody.addEventListener("change", (e) => {
         const tr = e.target.closest("tr");
         if (!tr) return;
-        if (e.target.dataset.field === "role") syncModuleSwitches(tr);
+        if (e.target.dataset.field === "role") syncPermChips(tr);
         markDirty(tr);
       });
 
       tbody.addEventListener("click", async (e) => {
-        const btn = e.target.closest("button");
+        // 권한 칩 토글 (잠금 상태 제외)
+        const chip = e.target.closest(".erp-perm-chip");
+        if (chip) {
+          if (chip.getAttribute("data-locked") === "true") return;
+          const on = chip.classList.toggle("is-on");
+          chip.setAttribute("aria-pressed", on ? "true" : "false");
+          markDirty(chip.closest("tr"));
+          return;
+        }
+
+        const btn = e.target.closest("button[data-action]");
         if (!btn) return;
         const tr = btn.closest("tr");
         const email = tr.dataset.email;
@@ -217,8 +249,8 @@
         if (btn.dataset.action === "save") {
           const role = tr.querySelector("select[data-field='role']").value;
           const modules = {};
-          tr.querySelectorAll("input[data-field='module']").forEach((cb) => {
+          tr.querySelectorAll(".erp-perm-chip").forEach((c) => {
-            modules[cb.dataset.module] = cb.checked;
+            modules[c.dataset.module] = c.classList.contains("is-on");
           });
           btn.disabled = true; btn.textContent = "저장 중…";
           try {

app/templates/erp_base.html

@@ -4,9 +4,10 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>{{ page_title or "ERP" }} — DBX Corporation</title>
-    <link rel="stylesheet" href="/static/erp.css?v=20260530q" />
+    <link rel="stylesheet" href="/static/erp.css?v=20260615b" />
-    <link rel="stylesheet" href="/static/erp-shell.css?v=20260530q" />
+    <link rel="stylesheet" href="/static/erp-shell.css?v=20260615b" />
     <link rel="stylesheet" href="/static/erp-attach-viewer.css" />
+    <link rel="stylesheet" href="/static/erp-dialog.css?v=20260819a" />
     {% block head_extra %}{% endblock %}
   </head>
   <body class="erp-body erp-app-body">
@@ -115,6 +116,7 @@
           </div>
 
           <div class="erp-topbar-right">
+            {% block topbar_actions %}{% endblock %}
             <div class="erp-user-chip">
               {% if user.picture %}
               <img class="erp-user-avatar" src="{{ user.picture }}" alt="{{ user.name }}" />
@@ -160,6 +162,9 @@
       })();
     </script>
 
+    {# 공용 확인/경고 창. defer 를 쓰지 않는다 — 아래 {% block scripts %} 의
+       인라인 스크립트가 곧바로 erpConfirm/erpAlert 을 쓸 수 있어야 한다. #}
+    <script src="/static/erp-dialog.js?v=20260819a"></script>
     <script src="/static/erp-attach-viewer.js" defer></script>
     {% block scripts %}{% endblock %}
   </body>

docker-compose.yml

@@ -18,6 +18,27 @@ services:
       - default
       - postgres_default   # postgres-db 컨테이너와 통신 (DSN host=postgres-db)
 
+  # 카페24 예약 실행기 — web 과 같은 이미지로 worker 모듈만 돌린다.
+  # 예약은 브라우저를 닫아도 그 시각에 실행돼야 하므로 별도 프로세스가 필요하다.
+  # CAFE24_DB_URL 이 없으면 즉시 종료하며 로그로 사유를 남긴다.
+  cafe24-worker:
+    build: .
+    image: dbx-main:latest
+    container_name: dbx-cafe24-worker
+    restart: unless-stopped
+    command: ["python", "-m", "app.modules.cafe24.worker", "--loop", "60"]
+    env_file:
+      - .env
+    environment:
+      DATA_DIR: /data
+    volumes:
+      - dbx-main-data:/data
+    depends_on:
+      - web
+    networks:
+      - default
+      - postgres_default
+
 volumes:
   dbx-main-data:
 

docs/CAFE24_MODULE.md

@@ -0,0 +1,404 @@
+# 카페24 상품 상세페이지 관리 모듈 (cafe24)
+
+> 카페24 관리자 페이지에 직접 들어가지 않고 상품 상세페이지를 조회·편집·예약
+> 적용하고, 언제든 이전 상태로 되돌리기 위한 운영용 모듈.
+> main-app ERP 에 편입된 **모듈**이다(별도 앱/포트 아님). 인증은 기존 Google
+> OAuth + 권한키 `cafe24` 를 재사용한다.
+
+---
+
+## 1. 구조 — 왜 두 곳으로 나눴나
+
+향후 **카페24 주문관리**(주문 조회·송장 일괄등록·취소/반품/교환)를 같은
+프로젝트에 추가할 예정이다. 그래서 카페24 인증/전송은 상품관리에 종속시키지
+않고 공통 계층으로 분리했다.
+
+```
+app/integrations/cafe24/        ← 공통 (상품관리 + 향후 주문관리 공유)
+├─ config.py    환경변수 → Cafe24Config (하드코딩 금지)
+├─ crypto.py    토큰 Fernet 암복호화
+├─ oauth.py     인증 URL / code→token / refresh
+├─ tokens.py    TokenService — 저장·만료판정·자동갱신(행 잠금)
+├─ client.py    Cafe24Client — 전송·재시도·401/429/5xx·호출간격·API 로그
+├─ products.py  상품 엔드포인트 래퍼   (향후 orders.py 를 형제로 추가)
+└─ errors.py    공통 예외
+
+app/modules/cafe24/             ← 상품관리 모듈
+├─ router.py           루트 라우터(prefix=/cafe24) + 서브 라우터 결합
+├─ routes_products.py  2분할 화면 · 편집기 조각 · 적용(쓰기)
+├─ routes_schedules.py 예약 등록·목록·취소
+├─ worker.py           예약 실행기 (compose 서비스 dbx-cafe24-worker)
+├─ routes_system.py    연결(OAuth)·상태·API 로그·작업 로그
+├─ common.py           가드/컨텍스트 헬퍼 (순환 import 방지로 분리)
+├─ db.py               Cafe24Store (cafe24_db, psycopg3 raw SQL)
+├─ store.py            순수 로직 — 상수·상태전이·재시도 규칙·검증
+├─ tests/              DB/네트워크 없는 유닛테스트
+└─ templates/cafe24/   _nav.html · products.html(2분할) ·
+                       _editor.html(오른쪽 조각) ·
+                       schedules.html · system.html
+```
+
+**규칙: 라우터에서 `httpx`/`requests` 를 직접 부르지 않는다.** 반드시
+`app.integrations.cafe24` 의 `Cafe24Client` 를 통한다(재시도·로그·토큰 갱신이
+한 곳에 모여 있어야 하기 때문).
+
+핸들러는 `async def` 가 아니라 **`def`(동기)** 로 선언한다. 카페24 API·DB 호출이
+블로킹이므로 FastAPI 스레드풀에서 돌게 두는 편이 이벤트 루프를 막지 않는다.
+
+---
+
+## 2. 화면 / 경로
+
+| 경로 | 화면 | 권한 |
+| --- | --- | --- |
+| `GET /cafe24/` | 2분할 화면 (`q`, `display`, `selling`, `selected`) | `cafe24` |
+| `GET /cafe24/products/{product_no}/pane` | 오른쪽 편집기 조각 (JS 가 가져감) | `cafe24` |
+| `GET /cafe24/products/{product_no}` | → `/cafe24/?selected=` 로 리다이렉트(옛 주소) | `cafe24` |
+| `POST /cafe24/products/{product_no}/apply` | 편집한 HTML 을 카페24에 즉시 적용 | `cafe24` |
+| `POST /cafe24/products/{product_no}/status` | 진열/판매 토글 (JSON: `{field, value}` → 적용 후 상태) | `cafe24` |
+| `POST /cafe24/products/{product_no}/name` | 상품명 변경 (JSON: `{name}` → 적용된 이름). 이전 이름은 감사로그 `rename_product` | `cafe24` |
+| `GET /cafe24/schedules` | 예약 목록 · 취소 | `cafe24` |
+| `POST /cafe24/schedules` | 예약 등록 (편집기에서) | `cafe24` |
+| `POST /cafe24/schedules/{id}/cancel` | 대기 중 예약 취소 | `cafe24` |
+| `GET /cafe24/schedules/preview/{product_no}` | 현재 진열/판매 상태 (JSON) | `cafe24` |
+| `GET /cafe24/system` | 연결 상태 · API 로그 · 작업 로그 | `cafe24` |
+| `GET /cafe24/system/oauth/start` | 카페24 인증 시작 | **admin** |
+| `GET /cafe24/oauth/callback` | 카페24 콜백 (code→토큰) | **admin** |
+| `POST /cafe24/system/oauth/disconnect` | 저장된 토큰 삭제 | **admin** |
+| `GET /cafe24/health` | 포털 카드 상태 점 | 없음 |
+
+---
+
+### 2-1. 상품관리 화면 구성 (2분할)
+
+```
+┌─ 550px ───────────────────┬───────── 남은 폭 전부 ─────────┐
+│ 상품명 검색(한 줄)         │ 상품 이름 · 번호 · 진열/판매    │
+│ ☑진열중 ☑판매중 (기본 체크) │ 상세설명 HTML 편집기            │
+│ ── 목록(전체, 스크롤) ──   │  (PC/모바일 공통 · 문법 강조)   │
+│ 번호 상품명 진열 판매 수정 │ [메모][복사][다시 읽기][적용]   │
+│ (제목행 클릭 = 정렬)       │ ▸ 버전 이력                     │
+│                            │                                 │
+└───────────────────────────┴─────────────────────────────────┘
+```
+
+- 검색 입력란은 **한 줄 높이로 고정**한다(`height: 32px`). `.cf24-filters` 가 세로
+  flex 이므로 `flex-basis` 를 주면 그 값이 **높이**로 적용돼 입력란이 거대해진다.
+  실제로 그 사고가 있었다 — flex 방향을 항상 확인할 것.
+
+- **왼쪽은 전체 목록**(페이지 없음). `list_all_products` 로 페이지를 넘겨가며 전부
+  받는다(1회 100개, 상한 1000개). 필터를 한 페이지에만 적용하면 다음 페이지의
+  해당 상품이 빠지기 때문이다.
+- **필터**는 `진열중`/`판매중` 체크박스이며 **중복 선택 시 AND** 다. 문서에 없는 API
+  파라미터에 기대지 않고 받아온 뒤 파이썬에서 걸러낸다.
+  **기본값은 둘 다 체크**다. 체크박스는 해제 상태면 아무 값도 보내지 않으므로,
+  폼에 표식(`f=1`)을 함께 넣어 "첫 방문"과 "사용자가 일부러 해제함"을 구분한다.
+  표식이 없으면 기본값(둘 다 체크)으로 보고, 있으면 실제 체크 상태를 따른다.
+  이 표식은 `_list_query` 가 링크·리다이렉트에도 이어 붙여 해제 상태가 유지된다.
+- **정렬**은 제목행 클릭(오름↔내림 토글). 브라우저에서 처리하므로 전체를 받아둔
+  덕분에 목록 전체가 대상이 된다.
+- **상품 클릭 시 오른쪽만 교체**한다(`/pane` 조각을 fetch → 삽입). 목록을 다시 받지
+  않으므로 카페24 호출이 1회로 끝난다. JS 실패 시 각 행의 링크로 정상 동작한다.
+- 편집기 상단에 **상품 다이렉트 주소**(고객이 보는 상세페이지 URL)와 「주소 복사」·
+  「쇼핑몰에서 열기」를 둔다. 주소는 `CAFE24_SHOP_URL` 기준으로 만들고, 미설정 시
+  카페24 기본 도메인(`https://<mall_id>.cafe24.com`)으로 대체한다 — 커스텀 도메인은
+  `mall_id` 로 알 수 없으므로 환경변수가 필요하다.
+- 편집 중 다른 상품을 클릭하거나 페이지를 벗어나면 **저장 안 됨 경고**가 뜬다.
+- **캐시 금지.** 화면·조각 응답에 `Cache-Control: no-store` 를 붙이고 조각 fetch 에도
+  `cache: "no-store"` 를 건다. 캐시된 조각이 다시 그려지면 카페24 관리자에서 값을 바꾼
+  뒤에도 예전 소스가 보이고, 그것을 그대로 편집하면 남의 수정을 덮어쓴다.
+  편집기의 **[다시 읽기]** 버튼으로 언제든 현재값을 강제로 다시 받을 수 있다.
+- `.erp-page` 의 `max-width` 를 이 화면에서만 풀어 편집 영역을 넓게 쓴다. 이때
+  `box-sizing: border-box` 를 함께 줘야 한다(안 주면 padding 이 폭에 더해져 문서에
+  가로 스크롤이 생긴다).
+
+---
+
+### 2-2. 편집기 (문법 강조 · 소스 정리)
+
+**문법 강조** — 색칠된 `<pre>` 위에 **투명한 `<textarea>`** 를 정확히 겹쳐 놓는
+방식이다. 외부 라이브러리를 쓰지 않는다(자체 호스팅 원칙).
+
+- 두 층의 **폰트·글자크기·줄높이·padding·`white-space`·`tab-size` 가 완전히 같아야**
+  글자가 어긋나지 않는다. 줄 번호 칸(`.cf24-gutter`)도 같은 글꼴 지표를 써야 줄이
+  맞는다. `cafe24.css` 의 세 선택자를 항상 함께 수정할 것.
+- **스크롤 주체는 `textarea` 다.** 색칠 층과 줄 번호를 `transform` 으로 같은 양만큼
+  이동시켜 맞춘다(`scroll` 이벤트에서 `translate(-scrollLeft, -scrollTop)`).
+  크기를 계산해 맞추는 방식은 두 번 실패했다 — ① textarea 의 `scrollHeight` 는
+  브라우저가 한두 줄 더 잡는다(실측 830 vs 792), ② flex 자식에서 `width: max-content`
+  가 기대대로 적용되지 않아 긴 줄이 있으면 textarea 만 내부 스크롤되고 색칠 층은
+  제자리에 남는다(실측 706 vs 686). 그 상태에서는 **커서를 둔 곳과 다른 위치에 글자가
+  입력된다.** 스크롤 동기화는 크기 계산이 없어 어긋날 여지가 없다.
+- **줄바꿈하지 않고 가로로 스크롤한다**(`white-space: pre` + `wrap="off"`).
+  줄바꿈을 허용하면 한 논리 줄이 여러 행이 되어 줄 번호가 맞지 않는다.
+- 줄 번호 칸은 코드 영역 왼쪽의 **독립 박스**다(가로 스크롤과 무관하며 세로만 따라간다).
+- 코드 칸 높이는 `56vh` **고정**이다(`flex: 0 0 auto`). 아래 「예약 적용」·「버전 이력」을
+  펼쳐도 편집기가 눌리지 않고 내용이 아래로 밀리며 오른쪽 칸이 스크롤된다. `flex: 1 1 auto`
+  였을 때는 펼칠 때마다 편집기가 작아져 작업 위치를 잃었다. 56vh 는 접힌 상태에서 두
+  요약줄까지 스크롤 없이 들어오는 값이다(실측: 62vh 는 51px 넘침, 56vh 는 0).
+- 20만 자를 넘으면 강조를 끄고 평문으로 보여준다(타이핑마다 재색칠하면 느려짐).
+- 색: 태그 초록 / 속성이름 갈색 / 속성값 남색 / 주석 회색 기울임 / 기호 회색.
+
+**소스 정리** — `store.format_html()`. 화면에 보여줄 때와 저장할 때 **같은 함수**를
+쓰므로, 화면에서 본 소스가 그대로 카페24에 저장된다.
+
+- 줄을 나누는 것은 **블록 요소 경계에서만** 한다. HTML 에서 공백은 의미가 있어서
+  인라인 요소 사이에 줄바꿈을 넣으면 화면에 공백이 생긴다(이미지 사이가 벌어지는
+  고전적인 사고). `img`·`br`·`span`·`a` 는 블록 목록에서 **의도적으로 제외**했다.
+- **원문에 이미 있던 줄바꿈은 살리고, 각 줄을 현재 깊이로 들여쓴다.** 상세페이지는
+  `<img>` 를 한 줄에 하나씩 적어두는 경우가 많고 그 모양이 저자의 의도다. 줄 앞
+  공백은 렌더링에 영향이 없으므로 들여쓰기는 안전하다.
+- 주석은 줄을 강제로 나누지 않는다. `<!-- 대파_타임랩스 --><img ...>` 처럼 바로 뒤
+  요소를 설명하는 주석이 많아, 나누면 라벨과 대상이 떨어져 오히려 읽기 나빠진다.
+- 구획용 **빈 줄은 한 줄까지 유지**한다(여러 줄은 하나로 줄인다).
+- `<style>`·`<script>`·`<pre>`·`<textarea>` 안쪽은 한 글자도 건드리지 않는다.
+- 내용이 한 줄뿐인 짧은 블록은 다시 한 줄로 합친다(`<td>1</td>`).
+- **멱등**이다 — 편집하지 않고 다시 적용해도 저장값이 계속 바뀌지 않는다(테스트로 고정).
+- 닫는 태그가 빠진 HTML 이 흔하므로 들여쓰기 깊이에 상한(12)을 둔다. 어떤 이유로든
+  실패하면 **원본을 그대로** 돌려준다(정리보다 안 깨지는 게 중요).
+
+---
+
+### 2-3. 예약관리 (지정 시각 자동 적용)
+
+**되돌리기(자동 복원)는 쓰지 않는다.** 예약은 "그 시각에 이 내용을 적용" 하나뿐이다.
+한 예약에서 세 가지를 각각 고를 수 있고, 하나 이상은 반드시 골라야 한다(DB CHECK 제약).
+
+| 항목 | 값 |
+| --- | --- |
+| 상세페이지 HTML | 편집기 내용을 적용 / 적용 안 함 |
+| 진열 | 진열 · 미진열 · 변경 없음 |
+| 판매 | 판매 · 중지 · 변경 없음 |
+
+- **등록**은 편집기 아래 「예약 적용」에서 한다. HTML 을 적용하는 예약이면 그 시점의
+  편집기 내용을 **DRAFT revision 으로 저장해 고정**한다 — 이후 편집기를 더 고쳐도
+  예약된 내용은 바뀌지 않는다(예약해둔 것이 조용히 달라지면 안 된다).
+  단건 적용과 같은 다듬기(URL 인코딩 → 소스 정리)를 거치므로 화면에서 본 값이 저장된다.
+- 예약 폼은 적용 폼과 **형제**로 둔다(HTML 은 폼 중첩을 허용하지 않는다). 편집기 내용은
+  JS 가 hidden 에 복사해 함께 보낸다.
+- **입력은 날짜/시간 별도 input** 이다(`type=date` + `type=time`). `datetime-local`
+  단일 입력은 한국어 로캘에서 표시 폭이 브라우저마다 달라 잘리는 사고가 있었다(실제
+  발생 — "2026. 08. 14. 오후 07:00" 형태).
+- **보이는 글자는 우리가 직접 그린다** — 네이티브 date/time input 은 표시 형식을
+  CSS 로 바꿀 수 없어서(브라우저·로캘가 강제), 코드 편집기(`.cf24-code-input` 위
+  `.cf24-code-hl`)와 같은 원리로 투명한(`opacity:0`) 네이티브 input 을 형식화한
+  텍스트(`.cf24-dt-display`, `"2026년 08월 20일 (목)"` / `"오후 07시 30분"`) 위에
+  완전히 겹친다. `input`/`change` 이벤트마다 JS(`paintDate`/`paintTime`)가 다시
+  그린다. 날짜에는 요일도 붙인다(`new Date(y, mo-1, d).getDay()` — 문자열을 그대로
+  `new Date("YYYY-MM-DD")` 로 파싱하면 UTC 로 해석돼 하루 밀릴 수 있어 연/월/일을
+  분해해 로컬 시간대로 만든다).
+- **클릭은 칸 전체 어디서든 반응한다.** 네이티브 date/time input 은 기본적으로
+  자신의 달력 아이콘(우측 끝 작은 영역)을 클릭해야만 팝업이 뜨고, 칸 전체를
+  덮도록 늘려도 그 작은 아이콘 영역만 반응한다(실제 겪은 문제 — "오른쪽 부분을
+  선택해야 나온다"). `showPicker()` 를 클릭 핸들러에서 직접 호출해 칸 어디를
+  클릭해도 팝업이 뜨게 했다. 미지원 브라우저에서는 조용히 무시되고 기존처럼
+  포커스만 이동한다(기능 저하 없이 안전하게 대체).
+- 글자크기 12px, 날짜 칸은 시간 칸보다 넓게(`flex: 1.7` vs `1`) 잡는다 — 날짜 칸에
+  요일까지 들어가 더 길기 때문이다. 값은 실측으로 잘리지 않는 조합을 골랐다.
+- 제출 직전 JS 가 두 input 의 `value`(형식과 무관하게 항상 `YYYY-MM-DD` / `HH:MM`)를
+  `"YYYY-MM-DD" + "T" + "HH:MM"` 로 합쳐 hidden `scheduled_at` 에 넣는다 —
+  서버(`store.parse_schedule_at`)는 예전과 같은 형식을 받으므로 백엔드는 그대로다.
+- **시각은 KST 로 해석**한다. 과거 시각은 거부하되
+  폼을 채우는 동안 시간이 흐른 경우를 위해 1분 여유를 둔다.
+- **실행은 `app/modules/cafe24/worker.py`** — compose 서비스 `dbx-cafe24-worker` 가
+  `--loop 60` 으로 돈다. 웹 요청 안에서 기다리는 방식은 프록시 타임아웃·재기동에
+  무너지므로 별도 프로세스여야 한다.
+- worker 는 `claim_due_schedule` 로 **한 건씩 `FOR UPDATE SKIP LOCKED`** 로 잠그고
+  PROCESSING 으로 바꾼 뒤 잠금을 푼다. worker 가 둘 떠 있어도 같은 예약을 두 번
+  적용하지 않고, 긴 API 호출 동안 DB 잠금을 쥐고 있지도 않는다.
+- 적용 순서는 화면 편집과 같다: **현재값 재조회 → BACKUP revision → PUT → SUCCESS +
+  감사로그**(`actor=SCHEDULER`, `action=schedule_apply`). HTML 없이 진열/판매만 바꾸는
+  예약은 상세설명을 읽지도, 백업하지도 않는다.
+- 실패는 `store.MAX_RETRY`(3) 안에서 1분 → 5분 → 15분 간격으로 재시도하고, 소진되면
+  `FAILED` 로 확정한다. 한 건의 오류가 worker 를 죽이지 않는다.
+- **대기(PENDING) 상태만 취소**할 수 있다. 실행 중/완료된 예약은 건드리지 않는다.
+
+---
+
+## 3. OAuth 흐름
+
+```
+관리자 [카페24 연결]
+   ↓  state 생성 → 세션 저장
+GET /cafe24/system/oauth/start  → 302 카페24 인증 페이지
+   ↓  사용자 승인
+GET /cafe24/oauth/callback?code=&state=
+   ↓  세션 state 와 대조 (불일치 시 토큰 교환 거부 — CSRF 방어)
+code → access/refresh token 교환
+   ↓  Fernet 암호화
+cafe24_oauth_tokens 저장
+```
+
+- scope 는 `app/integrations/cafe24/config.py` 의 `PRODUCT_SCOPES` =
+  `mall.read_product`, `mall.write_product`.
+  주문관리 추가 시 `ORDER_SCOPES` 를 합쳐 넘기고, 카페24 개발자센터 앱에서도
+  권한을 추가한 뒤 **재인증**하면 된다.
+- access token 은 만료 2분 전부터 자동 갱신된다. 갱신은 토큰 행을
+  `SELECT ... FOR UPDATE` 로 잠근 채 수행 — web 컨테이너와 worker 컨테이너가
+  동시에 refresh 해서 한쪽 토큰이 무효화되는 것을 막는다(카페24는 refresh
+  token 을 회전시킨다).
+- refresh token 이 만료되면 자동 복구가 불가능하므로 화면에 "재연결 필요"를
+  표시한다.
+
+---
+
+## 3-1. 상세설명 API 사실 (실물 확인 결과 — 추측 금지)
+
+운영 쇼핑몰(`miraskitchen`)에서 직접 확인한 내용이다. 문서에 없는 경로를
+추측해서 쓰지 말 것.
+
+- **`/admin/products/{no}/description` 서브리소스는 존재하지 않는다.**
+  호출하면 `No API found.` 가 온다. 상세설명은 **상품 리소스의 필드**다.
+
+  ```
+  GET  /admin/products/{no}   → description · mobile_description ·
+                                separated_mobile_description
+  PUT  /admin/products/{no}   → {"request": {"description": "..."}}
+  ```
+
+- **목록 API(`GET /admin/products`) 응답에는 `description` 이 없다.**
+  그래서 상세설명은 상품 1건씩 조회해야 하고, 목록 화면에 미리보기를 뿌리지
+  않는다(상품 87개 × 1호출 = 호출 제한 위험).
+
+- **PC/모바일 상세설명이 분리되어 있다.** `separated_mobile_description`
+  (`'T'`/`'F'`) 이 분리 사용 여부다. `'F'`(미분리) 상품을 수정할 때는
+  `description` 과 `mobile_description` 을 같은 HTML 로 함께 맞춘다.
+  `'T'` 면 두 값을 따로 관리해야 한다.
+
+- 그 밖에 상세 응답에만 있는 참고 필드: `translated_description`(다국어),
+  `summary_description`(요약설명), `simple_description`, `shop_no`(멀티쇼핑몰).
+
+- **이미지 경로의 한글은 퍼센트 인코딩되어 저장된다.**
+
+  ```
+  src="/web/product/big/%EC%9A%A9%EA%B8%B0…(%ED%99%A9%ED%86%A0)_12.gif"
+  ```
+
+  사람이 읽을 수 없으므로 화면에서는 `store.decode_html_urls` 로 풀어서 보여주고,
+  저장할 때 `store.encode_html_urls` 로 되돌린다. 두 함수는 서로의 역이며
+  **왕복이 보존된다**(편집하지 않고 적용해도 저장값이 바뀌지 않는다 — 테스트로 고정).
+  안전 규칙: 디코딩은 non-ASCII(`%80`~`%FF`)만, 인코딩은 URL 속성값 안만.
+  `%20`·`%3C` 를 풀거나 본문 한글을 인코딩하면 페이지가 깨진다.
+
+---
+
+## 3-2. 편집·적용 규칙 (`POST /products/{no}/apply`)
+
+이 순서를 절대 바꾸지 않는다.
+
+0. 제출된 HTML 을 `encode_html_urls` → `format_html` 순으로 다듬는다(화면에서 본
+   정리된 소스가 그대로 저장된다).
+1. **카페24에서 현재 HTML 을 다시 읽는다.** 로컬 DB 의 마지막 버전을 "지금
+   올라간 값"으로 가정하지 않는다(카페24 관리자에서 직접 고쳤을 수 있다).
+2. 그 값으로 **BACKUP revision** 을 남긴다. 유일한 복구 수단이다.
+3. **지문 대조** — 편집 화면을 열 때의 `fingerprint`(sha256 앞 32자)와 지금
+   카페24 값의 지문이 다르면 적용을 거부한다. 편집 중 남이 바꾼 내용을 조용히
+   덮어쓰는 것을 막는 낙관적 잠금이다.
+4. 내용이 같으면 호출하지 않는다(불필요한 쓰기·API 호출 방지).
+5. PUT 적용 → **MANUAL revision** + 감사로그(`apply_description`).
+
+추가 규칙:
+
+- 빈 내용은 거부한다(상세페이지 전체를 날리는 실수 방지).
+- **PC/모바일을 구분하지 않는다.** `description` 과 `mobile_description` 에 항상 같은
+  HTML 을 쓴다(운영 방침). `separated_mobile_description` 값과 무관하며, 편집 화면에도
+  모바일 소스를 따로 보여주지 않는다 — 한쪽만 바뀌어 어긋나는 사고가 없어진다.
+  분리 사용 상품의 모바일 내용이 PC 와 달랐다면 덮어쓰기 전에 **그 내용도 BACKUP
+  revision 으로 남긴다**(백업이 없으면 되찾을 방법이 없다).
+- 실패해도 BACKUP 은 이미 남아 있으므로 오류 메시지에 버전 번호를 알려준다.
+
+---
+
+## 4. 보안 규칙 (반드시 지킬 것)
+
+- `client_secret`·토큰을 코드에 하드코딩하지 않는다. 전부 `.env`.
+- **로그·예외 메시지·템플릿에 토큰/시크릿을 절대 출력하지 않는다.**
+  `cafe24_api_logs` 에도 Authorization 헤더를 기록하지 않는다.
+- 토큰은 DB 에 Fernet 암호문으로만 저장한다(`CAFE24_TOKEN_SECRET`).
+- 카페24 연결/해제는 `is_admin` 전용.
+- OAuth 콜백은 세션 `state` 대조 후에만 code 를 교환한다.
+- SQL 은 `%s` 플레이스홀더만 사용한다(문자열 조립 금지).
+
+---
+
+## 5. 설치 / 실행
+
+### 5-1. 카페24 개발자센터 앱 등록 (사람이 해야 하는 일)
+
+1. <https://developers.cafe24.com> 로그인 → 앱 생성
+2. Redirect URI 를 `.env` 의 `CAFE24_REDIRECT_URI` 와 **정확히 동일하게** 등록
+   (운영: `https://dbx.no1king.freeddns.org/cafe24/oauth/callback`)
+3. 권한(Scope)에 `mall.read_product`, `mall.write_product` 체크
+4. 발급된 Client ID / Client Secret 을 `.env` 에 기입
+
+### 5-2. DB 초기화 (superuser 로 1회)
+
+```bash
+read -s -p "cafe24_app password: " APP_PWD; echo
+docker exec -i postgres-db psql -U postgres \
+    -v app_password="$APP_PWD" \
+    < scripts/sql/cafe24_db_init.sql
+```
+
+### 5-3. .env
+
+```
+CAFE24_DB_URL=postgresql://cafe24_app:<APP_PWD>@postgres-db:5432/cafe24_db
+CAFE24_MALL_ID=miraskitchen
+CAFE24_CLIENT_ID=...
+CAFE24_CLIENT_SECRET=...
+CAFE24_REDIRECT_URI=https://dbx.no1king.freeddns.org/cafe24/oauth/callback
+CAFE24_API_VERSION=2026-03-01
+CAFE24_TOKEN_SECRET=<openssl rand -hex 32>
+CAFE24_SHOP_URL=https://miras.co.kr          # 선택 — 다이렉트 주소용 커스텀 도메인
+```
+
+### 5-4. 재기동 + 권한 부여
+
+```bash
+cd /opt/www/main && docker compose up -d --build web cafe24-worker
+```
+
+예약 기능을 쓰려면 마이그레이션 002 를 먼저 적용해야 한다(진열/판매 예약 컬럼).
+
+```bash
+docker exec -i postgres-db psql -U postgres -d cafe24_db < scripts/sql/cafe24_db_002_schedule_flags.sql
+```
+
+worker 가 도는지 확인:
+
+```bash
+cd /opt/www/main && docker compose logs --tail=20 cafe24-worker
+```
+
+관리자 페이지(`/admin`)에서 직원에게 **카페24 상품관리** 권한을 부여한다.
+
+---
+
+## 6. 테스트
+
+```bash
+python -m app.modules.cafe24.tests.test_cafe24
+```
+
+DB·네트워크 없이 암호화 왕복, 토큰 만료/자동갱신, 상태 노출(토큰 미유출),
+재시도 예산, 예약 상태 전이를 검증한다.
+
+---
+
+## 7. 진행 상태
+
+| Phase | 내용 | 상태 |
+| --- | --- | --- |
+| 1 | 공통 Integration · cafe24_db · OAuth 연결 화면 | ✅ 완료 |
+| 2 | 상품 목록·검색·현재 HTML 조회 | ✅ 완료 |
+| 3 | 편집기 · 미리보기 · Diff · 초안 | ◐ 문법 강조 편집기 + 소스 정리 완료. 미리보기·Diff·초안 예정 |
+| 4 | 즉시 적용 · BACKUP · Revision · 감사로그 | ✅ 완료 |
+| 5 | 예약 DB · Worker(compose 서비스) · 예약관리 화면 | ✅ 완료 |
+| 6 | 자동 종료/복원 · 롤백 | ✖ 되돌리기는 쓰지 않기로 결정. 버전 선택 복원만 남음 |
+| 7 | 일괄 수정 · 일괄 예약 · Rate limit 제어 | ✖ 일괄수정은 사용하지 않기로 제거. 필요해지면 다시 논의 |
+
+Phase 5 의 worker 는 `app/modules/cafe24/worker.py` 에 둔다 — `Dockerfile` 이
+`COPY app/ ./app/` 만 하므로 `scripts/` 에 두면 이미지에 포함되지 않는다.
+`docker-compose.yml` 에 같은 이미지로 `dbx-cafe24-worker` 서비스를 추가해
+`python -m app.modules.cafe24.worker --loop 60` 으로 돌린다.

docs/DATABASES.md

@@ -9,6 +9,8 @@
 | `return_db` | 반품·교환·CS 데이터 |
 | `expense_db` | 개인경비 / 법인카드 사용내역 / 정산 |
 | `cupang_db` | 쿠팡 밀크런 출고 묶음 / 출고 라인 / 입고센터 / 박스 입수량 규칙 |
+| `malaysia_stock_db` | 말레이시아 창고 재고관리 — 창고/아이템/세트 BOM/입출고 이력/일일 재고조사 |
+| `cafe24_db` | 카페24 연동 — OAuth 토큰/상품 캐시/상세페이지 버전/예약/감사·API 로그 |
 
 ---
 
@@ -256,6 +258,79 @@ cd /opt/www/main && docker compose up -d --build
 
 ---
 
+## malaysia_stock_db 스키마 / 초기화
+
+DDL: `scripts/sql/malaysia_stock_db_init.sql` (멱등). DB·역할(`malaysia_app`)·테이블·인덱스·트리거·창고/아이템 seed 를 한 번에 생성. **JSON 폴백 없음** — `MALAYSIA_STOCK_DB_URL` 미설정 시 모듈이 "설정 필요" 안내만 표시. 상품명은 `itemcode_db` 읽기 전용 재사용.
+
+테이블:
+
+| 테이블 | 용도 |
+| --- | --- |
+| `warehouses` | 창고(`warehouse_code` UNIQUE). seed: `MY-WH-01 / Malaysia Warehouse` |
+| `malaysia_items` | 관리 대상 코드 스코프 + 종류(`individual`/`set`) + 이름 스냅샷. prefix CHECK. seed: 낱개 12 + 세트 5 |
+| `set_bom` | 세트 구성표. `set_code`(MY-)·`component_code`(MT/MX/MZ) prefix CHECK, `UNIQUE(set_code, component_code)` |
+| `stock_movement` | 입고/출고/조정/조사 이력. `item_code` 낱개만(CHECK), `movement_type` IN/OUT/ADJUST/STOCKTAKE. `ref_type`·`ref_no`(Shopee/Lazada 연동용) |
+| `daily_stocktake` | 재고조사 헤더. `status` draft/finalized/cancelled. 같은 날짜+창고 finalized 1건(부분 유니크 인덱스) |
+| `daily_stocktake_line` | 조사 라인. `sku_code` 낱개+세트 허용(MD- 금지), `qty>=0`, `UNIQUE(stocktake_id, sku_code)` |
+
+현재고 = `SUM(IN) - SUM(OUT) + SUM(ADJUST) + SUM(STOCKTAKE)`. 재고조사 확정 시 시스템 재고와 조사 최종치의 **차이만** STOCKTAKE movement 로 기록. 세트는 movement 불가, 재고조사/BOM 계산 전용. MD- 뚜껑은 전 영역 제외.
+
+### 운영 서버 초기화 (1회, 사용자 승인 후)
+
+```bash
+read -s -p "malaysia_app password: " APP_PWD; echo
+docker exec -i postgres-db psql -U postgres \
+  -v app_password="$APP_PWD" \
+  < scripts/sql/malaysia_stock_db_init.sql
+# main-app .env 에 추가:
+#   MALAYSIA_STOCK_DB_URL=postgresql://malaysia_app:<APP_PWD>@postgres-db:5432/malaysia_stock_db
+cd /opt/www/main && docker compose up -d --build
+```
+
+> 멱등 스크립트. 기존 DB 가 있으면 DROP 하지 않음. itemcode_db 는 건드리지 않음.
+
+---
+
+## cafe24_db 스키마 / 초기화
+
+DDL: `scripts/sql/cafe24_db_init.sql` (멱등). DB·역할(`cafe24_app`)·테이블·인덱스·트리거를 한 번에 생성. **JSON 폴백 없음** — `CAFE24_DB_URL` 미설정 시 모듈이 "설정 필요" 안내만 표시.
+
+테이블:
+
+| 테이블 | 용도 |
+| --- | --- |
+| `cafe24_oauth_tokens` | 쇼핑몰별 OAuth 토큰(`mall_id` UNIQUE). access/refresh 는 **Fernet 암호문**으로 저장. 상품관리 + 향후 주문관리가 공유 |
+| `cafe24_products` | 상품 캐시(`product_no` UNIQUE). 목록/검색 속도용이며 source of truth 는 언제나 카페24 |
+| `cafe24_product_revisions` | 상세페이지 HTML 버전(append-only). `revision_type` SYNC/DRAFT/**BACKUP**/MANUAL/SCHEDULED/ROLLBACK |
+| `cafe24_product_schedules` | 예약 작업. `status` PENDING/PROCESSING/SUCCESS/FAILED/CANCELLED, 재시도·자동종료·복원 대상 포함 |
+| `cafe24_audit_logs` | 누가 무엇을 바꿨나. worker 수행분은 `actor='SCHEDULER'` |
+| `cafe24_api_logs` | 카페24 API 호출 기록. **토큰/Authorization/client_secret 미기록** |
+
+핵심 규칙:
+
+- 카페24에 쓰기 직전 **반드시 현재 HTML 을 다시 조회해 `BACKUP` revision 으로 저장**한다. 로컬 DB 의 마지막 값을 현재값으로 가정하지 않는다.
+- 예약의 `restore_revision_id` 는 **예약 실행 순간** 만든 BACKUP 을 가리킨다(예약 생성 시점 값이 아님).
+- 일괄 예약은 상품 1건당 1행 + 공통 `parent_job_id` — 한 상품 실패가 나머지를 막지 않는다.
+- 토큰 암호화 키는 `.env` 의 `CAFE24_TOKEN_SECRET`. **값을 바꾸면 기존 토큰을 복호화할 수 없어 카페24 재연결이 필요하다.**
+
+### 운영 서버 초기화 (1회, 사용자 승인 후)
+
+```bash
+read -s -p "cafe24_app password: " APP_PWD; echo
+docker exec -i postgres-db psql -U postgres \
+  -v app_password="$APP_PWD" \
+  < scripts/sql/cafe24_db_init.sql
+# main-app .env 에 추가:
+#   CAFE24_DB_URL=postgresql://cafe24_app:<APP_PWD>@postgres-db:5432/cafe24_db
+#   CAFE24_MALL_ID / CAFE24_CLIENT_ID / CAFE24_CLIENT_SECRET / CAFE24_REDIRECT_URI
+#   CAFE24_TOKEN_SECRET=$(openssl rand -hex 32)
+cd /opt/www/main && docker compose up -d --build web
+```
+
+> 멱등 스크립트. 기존 DB 가 있으면 DROP 하지 않음. 상세는 `docs/CAFE24_MODULE.md`.
+
+---
+
 ## 백업 / 복구 (안전 절차)
 
 ### 백업