chore(cafe24): 정리 전 완료된 작업 보존

Cafe24 수정, 테스트 및 DB 마이그레이션 파일을 함께 기록한다.
This commit is contained in:
2026-10-01 02:29:19 +09:00
parent 81b1204693
commit 91bdc12e78
20 changed files with 4632 additions and 845 deletions
+155
View File
@@ -0,0 +1,155 @@
-- =====================================================================
-- cafe24_db 005 — 쓰기 안전장치
-- 1) 상품·디자인 파일별 쓰기 잠금(lease) cafe24_write_locks
-- 2) 카페24 쓰기 시도 기록(원격 결과·기록 단계) cafe24_write_attempts
-- 3) 버전(revision)의 쇼핑몰·출처 메타데이터 cafe24_product_revisions
-- 4) 예약 실행 lease + "확인 필요" 상태 cafe24_product_schedules
-- =====================================================================
-- 멱등(idempotent): 여러 번 실행해도 안전. 데이터 DROP/TRUNCATE/DELETE 없음.
-- (예약 상태 CHECK 제약만 새 값 목록으로 교체한다 — 데이터는 그대로다.)
--
-- ⚠️ 운영 적용은 사용자 승인 + 백업 확인 후. 코드 배포 **전에** 적용한다
-- (새 코드는 이 표가 없으면 카페24 쓰기를 거부한다 — 잠금 없이 쓰지 않기 위해).
--
-- 실행:
-- docker exec -i postgres-db psql -U postgres -d cafe24_db \
-- < scripts/sql/cafe24_db_005_write_safety.sql
--
-- 배경 (docs/CAFE24_MODULE.md 3-5):
-- - 같은 상품을 두 사람(또는 웹 + 예약 worker)이 동시에 적용하면 둘 다 성공하고
-- 나중 것이 앞의 것을 조용히 덮었다 → 상품별 DB 잠금(만료시각이 있는 lease).
-- 프로세스가 죽어도 만료되면 다른 요청이 가져간다.
-- - 읽기 지연 판정이 "우리가 아는 값" 목록에 충돌로 거절된 적용의 백업·초안까지
-- 넣어, 관리자에서 직접 고친 값을 지연으로 오판했다 → 원격 쓰기가 **성공한**
-- 시도만 판정 근거로 쓴다(이 표의 status).
-- - 원격 쓰기는 성공했는데 로컬 기록이 실패하면 FAILED 로 보이고 재적용됐다
-- → 원격 결과와 기록 단계를 나눠 남긴다.
-- - worker 가 PROCESSING 중에 죽으면 영구히 남았다 → lease 만료 후 시도 기록을
-- 보고 성공/재시도/확인 필요로 나눈다(무조건 PENDING 으로 돌리지 않는다).
-- =====================================================================
\set ON_ERROR_STOP on
-- ── updated_at 트리거 함수 (init 에 있지만 단독 실행 대비) ──
CREATE OR REPLACE FUNCTION cafe24_set_updated_at() RETURNS trigger AS $$
BEGIN
NEW.updated_at := now();
RETURN NEW;
END;
$$ LANGUAGE plpgsql;
-- ════════════════════════════════════════════════════════════
-- 1) 쓰기 잠금 — lock_key 예: 'product:131', 'design:pc_detail'
-- 잡기: INSERT … ON CONFLICT DO UPDATE … WHERE expires_at < now()
-- 풀기: DELETE … WHERE lock_key = ? AND token = ?
-- 원격 쓰기 직전 token 으로 연장(펜싱) — 만료돼 남에게 넘어갔으면 쓰지 않는다.
-- ════════════════════════════════════════════════════════════
CREATE TABLE IF NOT EXISTS cafe24_write_locks (
lock_key TEXT PRIMARY KEY,
owner TEXT NOT NULL DEFAULT '',
token TEXT NOT NULL,
purpose TEXT NOT NULL DEFAULT '',
acquired_at TIMESTAMPTZ NOT NULL DEFAULT now(),
expires_at TIMESTAMPTZ NOT NULL
);
-- ════════════════════════════════════════════════════════════
-- 2) 쓰기 시도 기록 (상세설명·진열/판매를 카페24에 PUT 하는 작업)
-- status
-- STARTED PUT 직전에 남김. 이 상태로 남아 있으면 결과를 모른다.
-- REMOTE_OK 카페24 PUT 성공. 로컬 버전 기록은 아직(기록 복구 필요).
-- RECORDED PUT 성공 + 버전(MANUAL/SCHEDULED/ROLLBACK) 기록 완료.
-- REMOTE_FAILED 카페24가 거절(요청이 반영되지 않음이 확실).
-- UNKNOWN 네트워크 끊김·5xx 등으로 반영 여부를 모름 → 사람 확인.
-- ABANDONED 사람이 "반영 안 됨"으로 확정했거나 재실행으로 대체됨.
-- target_html 은 기록(RECORDED) 전까지만 보관한다(기록 복구용). 기록 후 비운다.
-- ════════════════════════════════════════════════════════════
CREATE TABLE IF NOT EXISTS cafe24_write_attempts (
id BIGSERIAL PRIMARY KEY,
product_no BIGINT NOT NULL,
mall_id TEXT NOT NULL DEFAULT '',
shop_no INTEGER NOT NULL DEFAULT 1,
origin TEXT NOT NULL DEFAULT 'MANUAL',
schedule_id BIGINT,
actor TEXT NOT NULL DEFAULT '',
status TEXT NOT NULL DEFAULT 'STARTED',
backup_revision_id BIGINT,
observed_digest TEXT NOT NULL DEFAULT '',
base_digest TEXT NOT NULL DEFAULT '',
target_digest TEXT NOT NULL DEFAULT '',
target_html TEXT NOT NULL DEFAULT '',
target_revision_id BIGINT,
applied_revision_id BIGINT,
set_display BOOLEAN,
set_selling BOOLEAN,
memo TEXT NOT NULL DEFAULT '',
remote_updated_at TEXT NOT NULL DEFAULT '',
error TEXT NOT NULL DEFAULT '',
resolved_by TEXT NOT NULL DEFAULT '',
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
remote_at TIMESTAMPTZ,
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
CONSTRAINT chk_cafe24_attempt_status CHECK (
status IN ('STARTED','REMOTE_OK','RECORDED','REMOTE_FAILED','UNKNOWN','ABANDONED')
),
CONSTRAINT chk_cafe24_attempt_origin CHECK (
origin IN ('MANUAL','SCHEDULED','ROLLBACK')
)
);
CREATE INDEX IF NOT EXISTS idx_cafe24_attempts_product
ON cafe24_write_attempts (product_no, created_at DESC, id DESC);
CREATE INDEX IF NOT EXISTS idx_cafe24_attempts_schedule
ON cafe24_write_attempts (schedule_id) WHERE schedule_id IS NOT NULL;
CREATE INDEX IF NOT EXISTS idx_cafe24_attempts_open
ON cafe24_write_attempts (product_no, created_at DESC)
WHERE status IN ('STARTED','REMOTE_OK','UNKNOWN');
DROP TRIGGER IF EXISTS trg_cafe24_write_attempts_updated ON cafe24_write_attempts;
CREATE TRIGGER trg_cafe24_write_attempts_updated
BEFORE UPDATE ON cafe24_write_attempts
FOR EACH ROW EXECUTE FUNCTION cafe24_set_updated_at();
-- ════════════════════════════════════════════════════════════
-- 3) 버전 메타데이터 (append-only 는 그대로 — INSERT 시점에만 채운다)
-- mall_id / shop_no 어느 쇼핑몰의 버전인가(복원 시 일치 검사). 기존 행은 ''/1
-- source BACKUP 의 출처
-- OBSERVED 카페24 GET 으로 읽은 값
-- LAST_WRITE 카페24가 읽기 지연 중이라 우리 마지막 쓰기(확인된
-- 적용값)를 현재값으로 본 것
-- ROLLBACK 은 'REVISION'(source_revision_id = 복원한 버전)
-- source_revision_id LAST_WRITE 백업이 근거로 삼은 버전 / ROLLBACK 원본 버전
-- ════════════════════════════════════════════════════════════
ALTER TABLE cafe24_product_revisions
ADD COLUMN IF NOT EXISTS mall_id TEXT NOT NULL DEFAULT '',
ADD COLUMN IF NOT EXISTS shop_no INTEGER NOT NULL DEFAULT 1,
ADD COLUMN IF NOT EXISTS source TEXT NOT NULL DEFAULT '',
ADD COLUMN IF NOT EXISTS source_revision_id BIGINT;
-- ════════════════════════════════════════════════════════════
-- 4) 예약 lease + 상태 NEEDS_REVIEW(확인 필요)
-- PROCESSING 은 lease_expires_at 까지만 유효하다. 만료되면 worker 가 시도 기록을 보고
-- 기록 완료/원격 성공 → SUCCESS, 원격 거절 → 재시도 규칙, 원격 전 중단 → 재시도 규칙,
-- 결과 모름 → NEEDS_REVIEW (사람이 카페24를 보고 확정)
-- lease 컬럼이 비어 있는 옛 PROCESSING 행은 started_at 기준으로 만료를 판정한다.
-- ════════════════════════════════════════════════════════════
ALTER TABLE cafe24_product_schedules
ADD COLUMN IF NOT EXISTS lease_owner TEXT NOT NULL DEFAULT '',
ADD COLUMN IF NOT EXISTS lease_token TEXT NOT NULL DEFAULT '',
ADD COLUMN IF NOT EXISTS lease_expires_at TIMESTAMPTZ;
ALTER TABLE cafe24_product_schedules
DROP CONSTRAINT IF EXISTS chk_cafe24_schedule_status;
ALTER TABLE cafe24_product_schedules
ADD CONSTRAINT chk_cafe24_schedule_status CHECK (
status IN ('PENDING','PROCESSING','SUCCESS','FAILED','CANCELLED','NEEDS_REVIEW')
);
CREATE INDEX IF NOT EXISTS idx_cafe24_schedules_processing
ON cafe24_product_schedules (lease_expires_at)
WHERE status = 'PROCESSING';
-- ── 권한 (cafe24_app: CRUD only) ──
GRANT SELECT, INSERT, UPDATE, DELETE ON cafe24_write_locks, cafe24_write_attempts TO cafe24_app;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO cafe24_app;
SELECT 'cafe24_db 005 applied' AS status;