# 장소 DB 설계 (v1.7, 2026-11-03)

WanderGo 의 장소·축제 데이터를 어떻게 저장하고, 갱신하고, 앱에 노출하는지 정한다.
1단계(엔티티·마이그레이션)와 2·3단계(관광공사 국문·반려동물·상가정보 동기화 명령), 중복 병합, 조회 API(§11), 축제·행사 동기화·API와 KOPIS 공연 동기화(§12)를 구현했다 — `backend/src/modules/place/`, `backend/src/commands/place-sync.ts`, `backend/src/migrations/`.
이 문서와 코드가 다르면 코드가 기준이다. 바꿀 때는 이 문서도 함께 고친다.

## 0. 전제 (이미 정한 것)

| 전제 | 근거 |
| --- | --- |
| 장소 데이터는 **공공데이터(자동 갱신) + 운영자 큐레이션**만 저장한다 | 카카오는 ID·place_url·사용자가 입력한 글자 외 저장 금지 (`docs/research/pre-dev-check/kakao_place_id.md`) |
| 카카오 응답은 LLM 에 보내지 않는다 → AI 후보는 자체 장소 DB 에서만 | 같은 문서 |
| AI 추천은 **큐레이션 O 장소 우선 + 관광공사 장소(보조)**. 확인 안 된 상가정보 매장은 추천하지 않는다 | 2026-11-02 합의 |
| 확인 안 된 공공데이터 장소도 **검색·지도에는 노출**, "영업시간 미확인 · 방문 전 확인" | 2026-11-02 합의 |
| 관광공사 적재는 **지역 목록·동기화 API** 로 한다. 위치 검색은 반경 안 장소의 15–38%만 돌려준다 | `docs/research/data-check/` 정정 메모, 2026-11-02 실측 |
| 1차 지역은 대구(도심·수성못·앞산), 한국어·영어 출시, 4개 언어 전제 | MVP 결정 |
| 영업시간 문장은 `backend/src/shared/utils/opening-hours.ts` 로 해석한다 | 구현·테스트 완료 |

## 1. 전체 구조

```
 [공공데이터 API]                         [운영자]
  관광공사 국문·영문·반려동물              큐레이션 표(CSV)
  상가정보 · 축제(searchFestival2)              │
        │  동기화 명령(일·주·분기)              │  가져오기 명령
        ▼                                       ▼
  ┌───────────┐  1:0..1  ┌────────────────┐
  │  place    │──────────│ place_curation │   ← 동기화가 절대 건드리지 않는다
  └───────────┘          └────────────────┘
     │   │ 1:N                   │
     │   └── place_i18n(영·일·중) │
     ▼                           ▼
  place_listing (뷰) — 공공 값과 큐레이션 값을 합친 "앱이 보는 값" + 노출 플래그
     │
     ▼
  검색·지도·상세 API / AI 후보 조회 / 홈 동네 추천

  festival_event — 축제·공연·행사 (홈·장소 상세의 축제 칸)
  place_sync_run — 동기화 기록
```

핵심은 두 가지다.

1. **공공 원본(`place`)과 사람이 확인한 값(`place_curation`)을 테이블로 나눈다.** 동기화가 아무리 덮어써도 큐레이션은 남는다.
2. **"앱이 보는 값"은 뷰 하나에서만 정한다.** 큐레이션 값 > 공공 값 > 미확인 순서를 여기서만 적용한다(규칙을 서비스마다 따로 적지 않는다).

```mermaid
erDiagram
  place ||--o| place_curation : "확인 정보"
  place ||--o{ place_i18n : "언어별 텍스트"
  place ||--o{ festival_event : "개최 장소(선택)"
  place {
    uuid id PK
    text source "tour | store"
    text source_id "UK(source, source_id)"
    text category
    text name
    float lat
    float lng
    text status "active | hidden | gone"
  }
  place_curation {
    uuid place_id PK
    text verdict "recommend | not_recommend | pending"
    date verified_at
  }
  place_i18n {
    uuid place_id PK
    text lang PK
    text name
  }
  festival_event {
    uuid id PK
    text source_id UK
    date start_date
    date end_date
  }
```

## 2. 테이블

### 2.1 `place` — 공공데이터 장소 (출처 1건 = 1행)

| 컬럼 | 타입 | 설명 |
| --- | --- | --- |
| `id` | uuid PK | 앱·공유 링크에 노출하는 ID |
| `source` | text | `tour`(관광공사) · `store`(상가정보) |
| `source_id` | text | contentid / bizesId. **`(source, source_id)` 유니크** — 동기화·큐레이션 가져오기의 연결 키 |
| `category` | text | 자체 분류(§2.6). 검색 탭·AI 슬롯에 쓴다 |
| `source_category` | text | 원본 코드(lclsSystm3 / indsSclsCd) — 분류 규칙을 바꿔도 다시 계산할 수 있게 |
| `source_type` | text | 관광공사 관광타입(contenttypeid). 소개정보(detailIntro2) 조회에 필요하다 |
| `name`, `branch_name` | text | 한국어 이름, 지점명(상가정보 brchNm) |
| `address_road`, `address_jibun` | text | |
| `lat`, `lng` | double precision | WGS84. §5 위치 검색 |
| `ldong_regn_cd`, `ldong_signgu_cd`, `adong_cd` | text | 법정동 시도(2)·시군구(3), 행정동(상가 8자리). 지역 필터·동기화 범위 |
| `phone`, `homepage` | text | 관광공사만 |
| `overview` | text | 소개(detailCommon2) |
| `public_hours_text`, `public_rest_text` | text | 영업시간·쉬는날 **원문** (유형별 필드 매핑은 `tools/data-check/curation_candidates.py` 의 `INTRO_FIELDS`) |
| `public_hours` | jsonb | 원문을 파서로 해석한 결과(`ParsedOpeningHours`). 동기화 때 다시 계산 |
| `public_pet` | jsonb | 관광공사 반려동물 동반 정보 원문(acmpyTypeCd·acmpyPsblCpam·acmpyNeedMtr 등). 없으면 null = **미확인**(불가 아님) |
| `public_pet_policy` | text | 위 원문을 동기화 때 요약한 값: `allowed`(전구역) · `partial`(일부구역) · null. 뷰는 이 값만 본다 |
| `public_extra` | jsonb | 유형별 부가 정보(입장료·주차 등). 필터로 승격할 항목은 §8 |
| `image_url`, `image_thumb_url` | text | firstimage / firstimage2 |
| `image_license` | text | `Type1` · `Type3` · null. 화면에 출처 표시 필수 |
| `status` | text | `active` · `hidden`(관광공사 비표출 showflag=0) · `gone`(다음 스냅샷에서 사라짐·폐업 추정) |
| `source_modified_at` | timestamptz | 관광공사 modifiedtime |
| `source_snapshot` | text | 상가정보 기준년월(stdrYm) |
| `last_seen_at` | timestamptz | 마지막 동기화에서 확인된 시각 |
| `merged_into_id` | uuid | 같은 가게를 다른 출처가 이미 가지고 있으면 그 장소 id(상가정보 → 관광공사). 값이 있으면 검색·추천에 나오지 않는다 — §4.2 |
| `detail_synced_at` | timestamptz | 상세(개요·영업시간)를 받은 시각. null 이면 아직 못 받았거나 원본이 바뀌어 다시 받아야 한다 — 하루 한도로 나뉜 적재를 이어서 받는 기준 |
| `created_at`, `updated_at` | timestamptz | |

- **지우지 않는다.** 사라진 장소는 `status=gone` 으로 숨긴다. 큐레이션과 코스가 그 장소를 가리키고 있을 수 있다.
- 숙박도 저장한다(검색의 '숙소' 탭). AI 코스·큐레이션 대상에서는 뺀다.

### 2.2 `place_curation` — 운영자가 확인한 정보 (place 1 : 0..1)

큐레이션 표의 오른쪽 12칸이 그대로 옮겨 온다.

| 컬럼 | 타입 | 큐레이션 표 칸 | 설명 |
| --- | --- | --- | --- |
| `place_id` | uuid PK, FK | 출처+출처ID 로 찾음 | |
| `verdict` | text | 데이트추천(O/X) | `recommend` · `not_recommend` · `pending` |
| `reason_ko` | text | 추천이유 | **큐레이터가 직접 쓴 문장만** (리뷰 문장 복사 금지) |
| `reason_i18n` | jsonb | — | `{en: …}`. 자체 작성 글이라 기계 번역 가능 |
| `hours_text`, `rest_text` | text | 영업시간(확인)·휴무(확인) | |
| `hours` | jsonb | — | 위 문장을 파서로 해석한 결과 |
| `pet_policy` | text | 반려동물(가능/일부/불가/미확인) | `allowed` · `partial` · `not_allowed` · `unknown` |
| `pet_sizes` | text[] | 반려동물 조건 | `small` · `medium` · `large` (디자인의 소형·중형·대형견) |
| `pet_conditions` | text | 반려동물 조건 | "테라스석만", "켄넬 필수" 등 |
| `setting` | text | 실내/실외 | `indoor` · `outdoor` · `both` — 비 오는 날 실내 우선 |
| `official_url` | text | 공식채널URL | 업체 본인 채널만 |
| `verified_method` | text | 확인방법 | `phone` · `official_channel` · `visit` |
| `verified_at` | date | 확인일 | 화면에 "11월 2일 확인"으로 노출 |
| `verified_by` | text | 확인자 | 운영자 식별자 |
| `recheck_due_at` | date | — | `verified_at + 6개월`(제안). 폐업 의심 시 앞당김 |
| `memo` | text | 메모 | 내부용, API 로 내보내지 않는다 |
| `updated_at` | timestamptz | | |

- 카카오·네이버에서 본 정보는 어떤 칸에도 옮기지 않는다. 확인 근거는 업체 본인 채널·전화·방문뿐이다.

### 2.3 `place_i18n` — 언어별 표시 텍스트

| 컬럼 | 설명 |
| --- | --- |
| `place_id`, `lang` | PK. `lang` = `en` · `ja` · `zh-Hans` · `zh-Hant` |
| `name`, `address`, `overview` | |
| `origin` | `tour_en`(관광공사 영문) · `machine`(기계 번역) · `curator` |
| `origin_id` | 영문 contentid (국문과 다르다) |
| `updated_at` | |

- 한국어는 `place` 본체에 둔다.
- 관광공사 영문은 국문과 연결 필드가 없어 **좌표(50m 안) + 분류 코드**로 맞춘다. 맞지 않은 영문 항목은 기록만 하고 붙이지 않는다(첫 적재 때 매칭률을 잰다).

### 2.4 `festival_event` — 축제·공연·행사·전시

| 컬럼 | 설명 |
| --- | --- |
| `id` uuid PK, `source_id` 유니크 | 관광공사 contentid |
| `kind` | `festival`(EV01) · `performance`(EV02) · `event`(EV03) |
| `name`, `start_date`, `end_date`, `lat`, `lng`, `address` | |
| `place_id` | 개최 장소가 `place` 에 있으면 연결(선택) |
| `fee_text`, `playtime_text`, `overview`, `image_url`, `image_license` | `usetimefestival` 은 **요금**이다(시간 아님) |
| `i18n` | jsonb `{en: {name, overview}}` |
| `status`, `last_seen_at` | |

- "상시 프로그램 제외"는 **조회할 때** 종류별 기간 상한으로 적용한다(저장은 그대로): 축제·공연·행사 60일, 전시 183일(`EVENT_MAX_SPAN_DAYS`).
- **여러 출처**(2026-11-03, 마이그레이션 `1793704967449-AddEventSourceAndVenue`): `source`(tour 관광공사 · kopis 공연예술통합전산망 ·
  kcisa 한국문화정보원 · dgfca 대구문화예술진흥원) + `(source, source_id)` 유니크. 종류에 `exhibition`, 장르(`genre`)·예매 링크(`booking_url`)·
  공연장(`venue_id` → `event_venue`) 추가. KOPIS 공연은 좌표가 공연장 상세에만 있어 `event_venue`(출처별 시설 id 유니크)에 캐시한다.
- 출처별 동기화는 자기 출처 행사만 숨긴다(관광공사 동기화가 KOPIS 공연을 숨기지 않게).

### 2.5 `place_sync_run` — 동기화 기록

`id`, `job`(tour_kor·tour_eng·tour_pet·store·event), `scope`(예: `27`), `started_at`, `finished_at`, `fetched`, `inserted`, `updated`, `hidden`, `gone`, `calls`(오퍼레이션별 호출 수 jsonb), `errors`(앞 20건), `snapshot`.
문의가 오면 "언제 받은 데이터인가"를 여기서 답한다.

### 2.6 자체 분류 (`category`)

검색 탭(관광지 · 축제 · 맛집·카페 · 숙소 · 산책·자연)과 AI 코스 슬롯을 이 값으로 고른다.

관광공사 대응은 「신분류체계정보 관광타입정보 연계 정의서」(`docs/data-openapi/`, 소분류 240개)를 보고 확정했다.
**소분류 → 중분류 → 대분류 → 관광타입** 순서로 찾는다. 코드는 `backend/src/modules/place/sync/tour-mapper.ts` 가 기준이다.

| category | 관광공사 | 상가정보 | 검색 탭 | AI 2순위 |
| --- | --- | --- | --- | --- |
| `nature` | NA 자연관광 전체 · VE03 도시공원 · VE040300 둘레길 | — | 산책·자연 | O |
| `attraction` | HS 역사관광 · VE01 랜드마크 · VE02 테마공원 · VE04 골목길·문화거리·마을 · VE05 관광단지 | — | 관광지 | O |
| `culture` | VE06 공연장·영화관 · VE07 박물관·전시관·미술관 · VE12 서점·기타문화시설 | — | 관광지 | O |
| `leisure` | LS 레저스포츠 · EX 체험관광(공예·템플스테이·웰니스) · VE10 경기장·스포츠센터 | — | 관광지 | O |
| `food` | FD 음식(아래 제외) | 그 외 음식 업종(지금은 적재하지 않음) | 맛집·카페 | O |
| `cafe` | FD05 카페·찻집 · FD030100 제과 | I21201 카페 · I21001 빵/도넛 · I21008 아이스크림/빙수 · I21005 샌드위치/샐러드 | 맛집·카페 | O(관광공사만) |
| `bar` | FD04 바·펍·주점 | I21104 요리 주점 · I21103 생맥주 | 맛집·카페 | — |
| `shopping` | SH 쇼핑(백화점·쇼핑몰·시장·사후면세점…) | — | 관광지 | — |
| `lodging` | AC 숙박 | — | 숙소 | — |
| `other` | VE08 연회장 · VE09 문화원·도서관·학교 | — | (전체에만) | — |

- 저장하지 않는 것: EV 축제·공연·행사(→ `festival_event`), 관광타입 25 여행코스, 좌표가 없거나 한국 밖인 항목.
- 2026-11-02 대구 도심 쇼핑 135곳 대부분이 `SH040300` **사후면세점**(더현대 입점 브랜드 매장)이었다. 쇼핑은 큐레이션으로만 AI 후보가 된다.
- 분류 코드가 비면 관광타입(12 관광지·14 문화시설·28 레포츠·32 숙박·38 쇼핑·39 음식점)으로 대신한다.

## 3. "앱이 보는 값" — `place_listing` 뷰

`place` LEFT JOIN `place_curation` 으로 만든다. API·AI 는 이 뷰만 읽는다.

**값의 우선순위**

| 항목 | 규칙 | 화면 표기 |
| --- | --- | --- |
| 영업시간 | 큐레이션 `hours` → 공공 `public_hours`(해석 성공 시) → 미확인 | "11월 2일 확인" / "출처 한국관광공사" / "영업시간 미확인 · 방문 전 확인" |
| 반려동물 | 큐레이션 `pet_policy` → 공공 `public_pet` 있으면 해당 값 → `unknown` | 같은 방식 |
| 실내/실외 | 큐레이션 `setting` → null | |

**노출 플래그** (2026-11-02 합의를 그대로 옮긴 것)

| 플래그 | 조건 | 쓰는 곳 |
| --- | --- | --- |
| `is_searchable` | `status = active` 이고 `merged_into_id` 없음 | 검색·지도·상세 |
| `is_brand_store` | 사후면세점(`SH040300`)이고 백화점·쇼핑몰 자체가 아님 | 목록·필터에서 빼고 이름 검색(q)에만 낸다 |
| `is_home_pick` | `verdict = recommend` **이고 `verified_at` 있음** | 홈 동네 추천 |
| `ai_tier` | 1: `verdict = recommend` 이고 `verified_at` 있음 / 2: `source = tour` 이고 코스 분류(숙박·쇼핑 매장 제외)이며 `verdict` 가 `not_recommend` 가 아님 / null: 그 외(**상가정보 미확인 매장 포함**) | AI 후보 조회 |

- `not_recommend` 는 추천에서만 빠지고 검색에는 남는다.
- 추천(O)만 표시하고 아직 확인하지 않은 상가정보 매장은 AI·홈 어디에도 쓰지 않는다(O/X 표시와 확인은 큐레이션의 서로 다른 단계다). 관광공사 장소는 확인 전이라도 2순위로 남는다.
- 큐레이션 행이 있어도 `verified_at` 이 비었으면 영업시간·반려동물 값을 쓰지 않는다(확인 안 된 값을 확인된 것처럼 보이지 않게).
- 2026-11-02 임시 DB 에서 8가지 경우(관광공사·상가 × 큐레이션 없음/추천+확인/추천만/X/사라짐, 숙소, 점포별 상이)로 규칙을 확인했다.
  조회 API 를 만들 때 같은 경우를 DB 를 쓰는 e2e 테스트로 고정한다.

## 4. 동기화

모두 **Nest 애플리케이션 컨텍스트로 도는 CLI 명령**으로 만든다. API 서버 프로세스 안에서 돌리지 않는다. 운영 서버의 cron 이 부른다.
키는 backend env 의 `PUBLIC_DATA_SERVICE_KEY`(이미 example 에 있음). 호출 수는 `place_sync_run.calls` 에 남기고, **오퍼레이션별 하루 상한**(개발 계정 1,000)에 닿으면 멈춘 뒤 다음 날 이어서 한다.

| 작업 | 주기 | 방법 | 대구 규모(2026-11-02) |
| --- | --- | --- | --- |
| 관광공사 국문 초기 적재 | 1회 | `areaBasedList2`(lDongRegnCd=27) 전체 → 항목마다 `detailCommon2`·`detailIntro2` | 목록 1,193건 · 상세 오퍼레이션별 약 1,200회 → **개발 계정으로 2일** |
| 관광공사 국문 변경분 | 매일 | `areaBasedSyncList2`(modifiedtime=어제) → 바뀐 것만 상세 재조회, `showflag=0` → `hidden` | 하루 수십 건 예상 |
| 반려동물 | 매주 | `detailPetTour2` contentId 없이 전체(약 9,700건, 10회) → contentid 로 붙임 | 10회 |
| 관광공사 영문 | 매주 | 영문 `areaBasedList2` → 좌표+분류로 매칭 → `place_i18n(en)` | |
| 상가정보 | 분기 | 대상 행정동 `storeListInDong`(divId=adongCd) × 데이트 업종 → bizesId 로 upsert. **새 스냅샷에 없는 ID → `gone`** | 도심·수성못·앞산 행정동 |
| 축제·행사 | 매일 | `searchFestival2`(오늘 ~ 오늘+90일, 대구+경북) | 대구 1 · 경북 7 (90일) |
| KOPIS 공연 | 매일 | `pblprfr`(오늘 ~ 오늘+90일) → 새·바뀐 공연만 상세 → 새 공연장만 시설 상세 | 대구 153 · 경북 91 (90일) |
| 폐업 대조 | 분기 | 행안부 인허가(휴게음식점·제과점·일반음식점) 영업상태와 주소·상호로 대조 → `gone` 후보 | 활용신청 후 |

- 비표출 레코드는 법정동이 비어 있으므로 비표출 확인은 지역 필터 없이 한다(매뉴얼 검토 노트).
- 동기화는 `place` 만 쓴다. `place_curation` 은 읽지도 쓰지도 않는다.

### 4.1 실행 방법 (구현됨: 관광공사 국문·반려동물·상가정보·축제·KOPIS 공연)

```bash
# 개발 — 키가 있는 백엔드 컨테이너 안에서 (dc = docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.development)
dc exec backend npm run migration:run                       # 스키마 먼저
dc exec backend npm run place:sync -- tour-kor              # 대구(27) 목록 → 상세. 한도에 닿으면 멈춘다
dc exec backend npm run place:sync -- tour-pet              # 반려동물 동반 정보(약 10회)
dc exec backend npm run place:sync -- store                 # 상가정보 데이트 업종(대구 중구·남구·수성구, 30회 안팎). 분기마다
dc exec backend npm run place:sync -- event                 # 축제·공연·행사(대구+경북, 오늘부터 90일 안). 매일. 새로 생기거나 바뀐 행사만 상세
dc exec backend npm run place:sync -- kopis                 # KOPIS 공연(대구+경북, 90일). 매일. KOPIS_SERVICE_KEY 필요. 첫 실행은 상세 250회 안팎(0.6초 간격, 약 4분)
dc exec backend npm run place:sync -- dedupe                # 같은 가게 병합(키 불필요). tour-kor·store 가 끝날 때도 자동으로 돈다
dc exec backend npm run place:sync -- reparse-hours         # 저장된 영업시간 원문을 지금의 파서로 다시 해석(키 불필요). 파서를 고친 뒤 한 번
dc exec backend npm run place:sync -- status                # 적재 현황·오늘 쓴 호출 수
# 다음 날 같은 tour-kor 명령을 다시 실행하면 남은 상세를 이어서 받는다

# 운영 — cron
node dist/commands/place-sync.js tour-kor
```

- 한도: `TOUR_API_DAILY_LIMIT`(비우면 1,000) − 여유분 20. 오늘(KST) `place_sync_run` 에 기록된 호출부터 센다.
  같은 키를 점검 스크립트 등 다른 곳에서 쓴 호출은 기록에 없으므로, 서버가 한도 초과(코드 22)로 거부하면 그때 멈춘다.
- 상세는 nature → attraction → culture → cafe → food … 순서로 받는다(이틀에 나뉘어도 앱에 먼저 필요한 것부터).
- 목록을 끝까지 받았을 때만 사라진 장소를 숨긴다. 사라진 수가 5건을 넘고 기존의 20% 도 넘거나, 기존이 전부 사라졌으면
  원본 장애로 보고 숨기지 않는다(`sync/removal-guard.ts`, 관광공사·상가정보·축제 공통). 비율만 보면 항목이 적은 곳의 정상 취소가 막혀서 바꿨다.
- 원본 수정일(modifiedtime)이 바뀐 장소는 `detail_synced_at` 을 비워 상세를 다시 받는다.
- 영업시간 해석(2026-11-03 대구 관광공사 1,174곳): 시간표 809 · 상시 개방 210 · 점포별 상이 75 · 영업시간 아닌 문장 20 · 원문 없음(숙소) 60.
  원문은 구간이 구분 없이 붙거나("…20:00금요일~일요일 …"), 줄바꿈으로만 나뉘거나, "[토요일]" 머리말 다음 줄에 시간이 오는 등 형식이 제각각이다.
  파서를 고친 뒤 `reparse-hours` 로 124곳을 바로잡았다(API 재호출 없음).
- 상가정보는 `storeListInDong`(divId=signguCd, 소분류 업종 필터)로 시군구 × 데이트 업종 6개를 받는다(`--signgu=` 로 범위 변경).
  끝까지 받은 (시군구, 업종) 묶음에서만 이번에 보이지 않은 업소를 `gone`(폐업 추정)으로 바꾼다(원본 장애 판단은 위와 같다).
  업종이 바뀐 업소(예: 카페 → 빵집)는 같은 bizesId 로 갱신되어 그대로 노출된다. 기준년월(stdrYm)은 `source_snapshot` 에 남긴다.
- 2026-11-02 임시 DB + 가짜 상가정보 API 로 확인: 첫 적재 → 다음 분기 폐업 추정·업종 변경·신규 → 급감 시 폐업 처리 건너뜀 → 한도 0 이면 아무것도 바꾸지 않음.
- 2026-11-02 임시 DB + 가짜 API 로 확인한 흐름: 한도 3회로 멈춤 → 같은 날 재실행 시 추가 호출 없음 → 다음 날 이어받기 → 수정 1곳만 재조회·사라진 1곳 숨김 → 반려동물 반영.

### 4.2 중복 병합 (같은 가게)

같은 가게를 관광공사·상가정보가 둘 다 가진 경우(2026-11-02 대구 약 21곳) 상가정보 쪽 `merged_into_id` 에 관광공사 장소 id 를 넣는다.
관광공사 쪽에 영업시간·사진·소개가 있어서 그쪽을 남긴다. 규칙(`modules/place/shop-name.ts`, `sync/place-dedupe.ts`):

- 관광공사 쪽이 카페·식당·주점일 때만 — 박물관·공원·경기장 안의 카페("이디야커피 국립대구박물관점")를 그 시설과 합치지 않는다
- 100m 안
- 상호가 같거나(공백·괄호·기호 무시), 한쪽이 다른 쪽을 포함하고 짧은 쪽이 2글자 이상 — 한 글자 상호 '동'·'문' 오탐 방지
- 후보가 여럿이면 가장 가까운 곳. 매번 전부 다시 계산한다(관광공사 장소가 숨겨지면 병합도 풀린다)
- 상세 API 는 병합된 id 로 들어와도 병합 대상 장소를 보여 준다(공유 링크가 깨지지 않게)
- ⚠️ 큐레이션 가져오기(4단계)는 병합된 상가정보 행을 가리키는 큐레이션을 병합 대상 장소로 옮겨야 한다

## 5. 위치 검색

- `lat`·`lng` double precision + 인덱스. 조회는 "경계 사각형으로 1차 필터 → 하버사인 거리로 정렬".
- 대구 규모(수천 건)에서는 충분하다. **PostGIS 는 지금 도입하지 않는다.**
  전국 확장으로 수십만 건이 되거나 다각형(동네 경계) 검색이 필요해지면 `DB_IMAGE` 를 PostGIS 이미지로 바꾸고 geography 컬럼 + GiST 인덱스를 추가한다.

## 6. 큐레이션 가져오기

- MVP 는 **CSV 가져오기 명령**으로 시작한다. 운영자 웹 화면은 2단계.
- 입력: `data/curation/<지역>/*.csv` (정렬표·시범표 형식 그대로).
- `(출처, 출처ID)` → `place(source, source_id)` 로 찾는다. 장소가 없으면(아직 적재 전·사라짐) 건너뛰고 보고한다.
- 값 검증: `O/X`, `가능/일부/불가/미확인`, `실내/실외`, `전화/공식채널/방문`, 날짜 형식. 틀린 행은 반영하지 않고 행 번호와 함께 보고한다.
- 먼저 **미리보기(dry-run)** 로 바뀔 내용을 보여 주고, 확인 후 반영한다.
- 큐레이션 표는 운영 자산이다. 저장소에 커밋할지(공공데이터 + 우리가 확인한 사실만 담김), 구글 시트로 옮길지는 따로 정한다.

## 7. 다른 테이블과의 연결 (코스 설계 때 확정)

코스의 장소 한 칸(`course_stop`)은 **둘 중 하나**만 가진다.

- `place_id` — 자체 장소 DB 의 장소
- `kakao_place_id` + `kakao_place_url` + `user_label`(사용자가 직접 입력한 이름) — 카카오 검색으로 직접 추가한 장소

카카오 장소는 이름·주소·좌표를 저장할 수 없다. **지도에 어떻게 표시할지는 코스 설계 때 정한다**(예: 사용자가 지도에서 직접 찍은 위치).

## 8. MVP 에서 하지 않는 것

- 카카오·네이버 데이터 저장, UGC 리뷰
- 운영자 웹 관리 화면(CSV 가져오기로 대신)
- 상가정보 전국 적재(대상 행정동만)
- 입장료·주차 필터의 정규화(`public_extra` 에 원문으로 두고, 디자인의 '무료 입장'·'주차' 필터는 큐레이션 칸 추가 또는 원문 해석으로 2차에 결정)

## 9. 확인이 필요한 것

| 항목 | 언제 |
| --- | --- |
| `areaBasedSyncList2` 의 modifiedtime 이 "그날"인지 "그 이후"인지 | 변경분 동기화 첫 실행 |
| 영문 ↔ 국문 매칭률 | 영문 첫 적재 |
| Type3(변경금지) 이미지를 카드에서 잘라 보여 주는 것이 '변경'인지 | 화면 구현 전 (공공누리 기준) |
| 상가정보 반경·행정동 API 가 빠뜨리는 업소가 있는지 | 상가정보 첫 적재 (동 단위 결과와 반경 결과 비교) |
| 큐레이션 표 보관 위치(저장소 / 구글 시트) | 큐레이션 본격 시작 전 |

## 10. 구현 순서 (제안)

1. ✅ 엔티티 + 마이그레이션: `place`, `place_curation`, `place_i18n`, `festival_event`, `place_sync_run`, `place_listing` 뷰 (2026-11-02)
2. ✅ 관광공사 국문 적재 명령(대구) + 반려동물 동기화 + 현황 명령 (2026-11-02, 실제 적재는 개발 계정으로 2일)
3. ✅ 상가정보 적재 명령(대구 중구·남구·수성구 데이트 업종) (2026-11-02)
4. 큐레이션 CSV 가져오기 명령(미리보기 → 반영)
5. ✅ 조회 API: `GET /api/places`(검색·근처·필터·커서), `GET /api/places/{id}` + 중복 병합 (2026-11-02), 축제 `GET /api/events`·`/{id}` + 축제 동기화 (2026-11-03)
6. 일·주·분기 동기화 + 폐업 대조

## 11. 조회 API (구현됨)

비로그인으로 쓴다(둘러보기·검색 비로그인 허용 합의). 노출 규칙은 `place_listing` 뷰가 정하고 API 는 읽기만 한다.

| 엔드포인트 | 내용 |
| --- | --- |
| `GET /api/places` | `q`(이름) · `lat`+`lng`+`radius`(기본 1,500m, 100~20,000) · `category`(쉼표 구분) · `pet` · `indoor` · `cursor` · `limit`. 좌표가 있으면 거리순, 없으면 이름순. 키셋 커서(정렬값+id). 응답 `{items, pageInfo}` 에 `total` 포함 |
| `GET /api/places/{id}` | 상세 — 영업시간(원문·해석 상태·출처), 반려동물(크기·조건), 이용 안내(요금·주차 등), 추천 이유(추천+확인한 곳만), 출처 표기. 병합된 id 면 대상 장소, 숨김·폐업 추정이면 RES_001 |

- 목록 항목의 `openNow` 는 한국 시간 기준 영업 중 여부다. 알 수 없으면 null → 화면은 "영업시간 미확인 · 방문 전 확인".
- 사후면세점 브랜드 매장은 이름 검색일 때만 나온다(반려동물 필터 결과가 더현대 입점 매장으로 덮이던 문제).
- 실패 코드: 검색 조건·커서·id 형식 오류 VAL_001(400), 없음 RES_001(404). 새 코드는 만들지 않았다.
- 계약 테스트: `backend/test/place.e2e-spec.ts` — 시작할 때 마이그레이션을 적용하고 동해 좌표에 테스트 장소를 만들어 검증한다(16개).
- 아직 없는 것: 영어 등 다국어 응답(`place_i18n`), 지도 화면용 사각형(bbox) 조회.

## 12. 축제·공연·행사 (구현됨)

**동기화** `place:sync -- event [--regions=27,47] [--days=90]` (매일)

- **범위는 대구(27) + 경북(47)**: 2026-11-03 진단(`tools/data-check/festival_region_check.py`) 결과 앞으로 90일 관광공사 행사가
  전국 106 · 대구 1 · 경북 7건이었다. 조회 조건 문제는 없었다(지역 코드 빈 행사 0건). 관광공사는 행사가 가까워져야
  등록하는 경우가 많고 겨울은 행사 자체가 적다. 근교 행사를 거리와 함께 보여 주려고 경북까지 받는다.

- `searchFestival2` 를 오늘~N일 기간으로 부른다. 서버는 기간이 겹치는 행사를 준다(종료일 ≥ 요청 시작일).
- 지역 조건(`lDongRegnCd`)을 보내고, 응답에서도 다른 지역 행사는 한 번 더 거른다(서버가 조건을 무시해도 섞이지 않게).
- 종류: lclsSystm2 EV01 축제 → `festival`, EV02 공연 → `performance`, EV03 행사 → `event`(분류가 비면 행사).
- 상세(`detailCommon2` 소개 + `detailIntro2` 관광타입 15)는 새로 생기거나 수정일이 바뀐 행사만 받는다(`detail_synced_at`).
  요금은 이름과 달리 `usetimefestival`, 공연 시간 `playtime`, 장소 `eventplace`, 홈페이지는 `eventhomepage` 우선.
- 좌표가 없는 행사도 저장한다(근처 조회에서만 빠진다). 받은 기간 안에서 목록에 없는 행사는 숨긴다(원본 장애 판단은 §4.1).
- 2026-11-03 임시 DB + 가짜 API 로 확인: 다른 지역·날짜 없는 행사 건너뜀 → 재실행 시 상세 재조회 없음 → 수정 1건만 상세 재조회, 취소 1건 숨김 → 빈 응답이면 숨기지 않음.

**API**

| 엔드포인트 | 내용 |
| --- | --- |
| `GET /api/events` | `from`·`to`(YYYY-MM-DD, 기본 오늘~30일, 최대 92일) · `lat`+`lng`+`radius`(기본 5km, 최대 150km — 근교 경북까지) · `kind` · `cursor` · `limit`. 기간과 겹치는 행사를, 좌표가 있으면 거리순·없으면 시작일순으로. **60일 넘는 상시 프로그램과 숨김 행사는 뺀다.** 항목에 `ongoing`(오늘 진행 중) |
| `GET /api/events/{id}` | 소개·공연 시간·요금·장소·홈페이지·전화·출처. 숨김이면 RES_001 |

- **화면 규칙**(2026-11-03 합의):
  - 홈 '이번 주말 축제·행사' = `from`=토 · `to`=일 · 동네 중심 좌표 · `radius`=120000 → 대구 행사가 먼저, 다음 경북(거리 표시 "대구에서 85km").
  - **비면** 같은 반경으로 `from`=오늘 · `to`=오늘+30일을 불러 제목을 '다가오는 축제·행사'로 바꿔 보여 준다(빈 칸을 두지 않는다).
  - 장소 상세 '근처 축제·행사' = 장소 좌표 + 기본 반경(5km), 없으면 칸을 숨긴다.
- 계약 테스트: `backend/test/festival.e2e-spec.ts` — 2030년 날짜·동해 좌표 픽스처라 실행 날짜와 무관하다.

### 12.1 KOPIS 공연 (구현됨)

**동기화** `place:sync -- kopis [--regions=27,47] [--days=90]` (매일, `KOPIS_SERVICE_KEY` 필요)

대구는 공연이 많은데 관광공사에는 거의 없다. 그래서 KOPIS 공연예술통합전산망을 공연 출처로 쓴다.
조사: `docs/research/pre-dev-check/culture_event_sources.md`. 2026-11-03 사용자 확인: KOPIS 데이터 저장·포스터 재사용 가능.

- **진단**(2026-11-03, `tools/data-check/culture_api_check.py`)
  - 90일을 한 번에 조회할 수 있다(31일 제한 없음). https 동작.
  - 앞으로 90일 공연: 대구 153건(클래식 62 · 대중음악 30 · 뮤지컬 25 · 연극 16 …), 경북 91건.
  - 목록에는 공연시설 id·좌표·수정일이 없다. 그래서 상세와 시설 상세를 따로 부른다.
  - 공연시설 좌표는 5곳 중 5곳에 있었다. 다만 1곳(대구 중구 주소)이 경주 좌표였다 → 아래 좌표 검사를 만든 이유.
- 순서(`sync/kopis.sync.ts`)
  1. **목록** `pblprfr`(signgucode, stdate=오늘, eddate=오늘+N일, rows=100). 끝난 공연(`공연완료`)·다른 시·도·중복은 건너뛴다.
     목록을 끝까지 받았으면 받은 기간 안에서 목록에 없는 공연을 숨긴다(원본 장애 판단은 §4.1).
  2. **상세** `pblprfr/{mt20id}` — 새 공연, 어제 이후 등록·수정된 공연(목록 `afterdate`), 상세를 받은 지 7일 지난 공연만.
     요금 `pcseguidance` → `fee_text`, 공연 시간 `dtguidance` → `playtime_text`, 예매처 첫 링크 → `booking_url`,
     소개 = 줄거리 `sty` + 출연·관람 시간·관람 연령 줄. 장소 이름은 상세가 홀까지 주므로("대구콘서트하우스 (그랜드홀 …)") 상세 값을 쓴다.
  3. **공연시설** `prfplc/{mt10id}` — 진행 중·예정 공연이 쓰는 시설 중 새 시설과 30일 지난 시설만 → `event_venue`.
     **좌표는 주소의 시·도 영역 안일 때만 쓴다**(`geo.ts` `isInSido`). 아니면 비우고 경고를 남긴다(그 공연은 근처 조회에서만 빠진다).
  4. 시설의 좌표·주소·전화를 공연에 복사한다. 조회 API 가 공연 좌표로 거리를 계산하기 때문이다. 시설 좌표를 고치면 다음 실행에 공연도 바뀐다.
- 순회 공연 제목 끝의 지역 꼬리표("굿프렌즈 [대구]", "[대구 북구]", "[안동] (11월)")를 떼어 저장한다. 2026-11-03 244건 중 203건에 붙어 있었다.
  꼬리표 안이 지역 이름과 괄호 메모로만 되어 있을 때만 떼고, "(앵콜)"·"(11.10)" 같은 메모는 남긴다(`kopis-mapper.ts` `stripRegionTag`).
- 포스터는 `http://www.kopis.or.kr/…` 로 온다. 앱이 http 이미지를 막으므로 `https://kopis.or.kr/…` 로 바꿔 저장한다(목록·상세 사진 모두 포스터).
- 호출: 0.6초 간격(KOPIS 는 초당 10회에서 차단). 오퍼레이션별(`pblprfr`·`pblprfr-detail`·`prfplc-detail`) 하루 상한 980.
  공식 한도는 밝혀져 있지 않다. 이후 하루 호출은 목록 4회 + 상세 수십 회로 예상한다.
- 출처 표기: 조회 API 상세의 `attribution.provider` = "(재)예술경영지원센터 공연예술통합전산망(www.kopis.or.kr)".
- 검증: `backend/test/kopis-sync.e2e-spec.ts`. 가짜 KOPIS 응답과 실제 DB 로 다음을 확인한다.
  첫 적재와 시설 좌표 복사, 틀린 좌표 비우기 → 재실행 시 상세·시설 재조회 없음 → 바뀐 공연만 상세 재조회, 없어진 공연 숨김.
- 알려진 한계
  - 관광공사 공연(EV02)과 같은 공연이 둘 다 나올 수 있다. 출처 간 같은 행사 병합은 아직 없다(조사 문서 3-3 의 규칙으로 나중에).
  - '이번 주말'은 기간이 겹치는지만 본다. 평일만 하는 공연도 섞인다(`dtguidance` 요일 해석은 나중에).
  - 기간이 60일 넘는 공연(대구 8건)은 상시 프로그램 규칙으로 목록에서 빠진다.

### 12.2 한국문화정보원 전시 (구현됨)

**동기화** `place:sync -- kcisa [--regions=27,47] [--days=90]` (매일, 공공데이터포털 키 — 15138937 활용신청 필요)

- 진단(2026-11-03): 앞으로 90일 대구 42건(전시 13 · 음악/콘서트 17 …), 경북 17건(전시 1). 좌표 채움 대구 38/42.
- 순서(`sync/kcisa.sync.ts`)
  1. **목록** `area2`(sido=대구·경북, from·to). **분야가 '전시'인 것만** 넣는다 — 공연은 KOPIS 와 겹친다.
     관광공사·KOPIS 에 이름 비교 키(`event-name.ts`, 괄호·문장부호·공백 제거)가 같고 기간이 겹치는 행사가 있으면 넣지 않는다.
     목록을 끝까지 받았으면 받은 기간 안에서 이번에 넣지 않은 전시를 숨긴다(원본 장애 판단은 §4.1).
  2. **상세** `detail2` — 새 전시와 상세를 받은 지 7일 지난 전시만(원본에 수정일이 없다). 요금 `price`, 소개 `contents1`, 전화, 주소 `placeAddr`, 안내 링크 `url`.
- 좌표는 목록에 있다(`gpsY` 위도 · `gpsX` 경도). 지역의 시·도 영역 밖이면 버린다.
- 제목에 `&amp;lsquo;` 처럼 한 번 더 인코딩된 문자가 온다 → `htmlToText` 가 따옴표·가운뎃점·번호 엔티티까지 푼다.
- **이미지는 저장하지 않는다.** 문화공공데이터광장 저작권정책상 공공누리 1유형이 아니면 사전 협의가 필요한데 아직 확인하지 않았다
  (조사 문서 4장 4번). 확인되면 `kcisa-mapper.ts` 에서 `thumbnail`·`imgUrl` 을 넣고 다시 실행한다.
- 전시는 몇 달씩 하므로 상시 프로그램 상한이 183일이다(§2.4). 1년짜리 상설 전시는 목록에서 빠진다.
- 출처 표기: "한국문화정보원 문화포털". 호출: 대구·경북 하루 20회 안팎(개발 계정 10,000/일).
- 검증: `backend/test/kcisa-sync.e2e-spec.ts` — 전시만 넣기 · 다른 출처 중복 건너뛰기 · 상세 · 빈 목록이면 숨기지 않기 · 없어진 전시 숨기기.