fix(migrations): s1 dedup 287->317 renumber (main 287=study_memo_cards 충돌 회피)

migrations/317_documents_dedup_fields.sql

@@ -0,0 +1,18 @@
+-- 317_documents_dedup_fields.sql
+-- S1-ADD (plan ds-s1-backend-1, A-1): 원본 파일명 + 중복검사 메타 3컬럼.
+-- 계약: ds-app contract/CONTRACT.md [S1-ADD] — original_filename / duplicate_of / duplicate_count.
+--
+-- asyncpg exec_driver_sql 단일 statement 제약 — ALTER TABLE 다중 ADD COLUMN 절은 단일 statement 라 허용.
+-- BEGIN/COMMIT 금지. PG 16: ADD COLUMN ... DEFAULT <constant> 는 fast path (table rewrite 없음).
+-- duplicate_of self-FK 는 신규 all-NULL 컬럼이라 검증 스캔 trivial (NOT VALID 불요).
+--   ON DELETE SET NULL: 원본(canonical) hard delete 허용 (RESTRICT=삭제 차단 / CASCADE=사본 연쇄삭제 위험 회피).
+-- 기존 dup 그룹(law_monitor 제외)의 duplicate_of/duplicate_count backfill 은 B-4 별 배치 스크립트.
+--   28,941행 대량 UPDATE 를 startup migration(단일 트랜잭션)에 넣지 않는다.
+--
+-- original_filename 은 original_format(ODF 변환용)·original_path/original_hash(migration 007 legacy dead,
+--   app 코드 미참조 — P0-1 grep 0건) 와 의미가 다르다: 업로드 시점 원본 파일명(다운로드 라벨용).
+
+ALTER TABLE documents
+    ADD COLUMN IF NOT EXISTS original_filename TEXT,
+    ADD COLUMN IF NOT EXISTS duplicate_of      BIGINT REFERENCES documents(id) ON DELETE SET NULL,
+    ADD COLUMN IF NOT EXISTS duplicate_count   INTEGER NOT NULL DEFAULT 0;