[docs] deploy: 킹서버 DB 절을 마이그레이션 체계로 — 코드만 갈면 스키마가 안 따라온다

이 절은 아직 "`init.sql` 한 벌이 스키마 전부" 이고 "이미 있는 DB 에는 파일 하단의
ALTER 절만 손으로 돌려라" 라고 적혀 있었다. 그 방식은 이번 재편에서 없어졌다 —
`postgres-init/migrations/` + `scripts/migrate.py` 가 대신한다.

- 스키마 파일이 두 벌이라는 것과 둘 다 최신을 유지해야 하는 이유
- 배포 절차에 `migrate.py --dry-run` → `migrate.py` 를 넣는다. `postgres-init/` 은
  이미지에 굽지 않고 마운트하므로 코드 배포와 따로 돌릴 수 있다
- ★ 이번 배포(0005~0008)는 스키마를 통째로 편다. 안 돌리면 컨테이너는 정상으로 뜨고
  가게 등록·수집·발행만 죽는다 — 없는 표를 부르는 코드는 기동을 통과한다

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/SERVERS.md

@@ -119,14 +119,41 @@ cd ~/data2/o2o-site-AEO
 
 호스트에 PostgreSQL 15(pgvecto)가 `king_postgres_container` 로 떠 있고 `5432` 가 호스트에 열려 있다.
 컴포즈가 `DB_HOST` 기본값을 `host.docker.internal` 로 두고 `extra_hosts: host-gateway` 를
-붙여 두었으므로 **컴포즈를 고치지 않고 그대로 닿는다.** DB 는 만들어야 한다 —
-`postgres-init/init-data/init.sql` 한 벌이 스키마 전부다.
+붙여 두었으므로 **컴포즈를 고치지 않고 그대로 닿는다.**
 
-★ **`init.sql` 은 DB 를 처음 만들 때만 돈다.** 이미 있는 DB 에는 파일 하단의 "기존 DB 보정(ALTER)"
-절만 손으로 돌려야 새 컬럼이 들어간다. 빠뜨리면 **HTTP 는 200 인데 기능만 죽는다** —
+스키마 파일은 **두 벌**이고 둘 다 최신을 유지한다 —
+`postgres-init/init-data/init.sql` 은 **새 DB 를 세우는 전체 DDL**,
+`postgres-init/migrations/NNNN_*.sql` 은 **이미 데이터가 든 DB** 를 거기까지 끌어올린다.
+한쪽만 고치면 새로 세운 DB 와 서버 DB 가 조용히 갈라진다.
+
+★ **`init.sql` 은 DB 를 처음 만들 때만 돈다**(postgres 이미지의 초기화 훅). 파일에 컬럼을
+더해도 서버 DB 에는 들어가지 않는다. 빠뜨리면 **HTTP 는 200 인데 기능만 죽는다** —
 실측(2026-09-03): `users.provider` 없음 → 로그인 전부 실패, `sites.thumbnail_url` 없음 →
-쇼케이스 전부 실패. 로그를 봐야 보인다. 컬럼을 `CREATE TABLE` 에만 추가하고 ALTER 절에
-안 적으면 **새 DB 는 되고 기존 DB 만 조용히 깨진다.**
+쇼케이스 전부 실패. 실측(2026-09-09): `local.place_contents` 없음 → TourAPI 가 주변 정보를
+받아 와도 저장할 곳이 없어 축제·맛집 0건. 셋 다 화면이 아니라 로그를 봐야 보인다.
+
+### 배포할 때 — 코드만 갈면 스키마는 안 따라온다
+
+`postgres-init/` 은 이미지에 굽지 않고 백엔드 컨테이너에 마운트한다(`docker-compose.yml`).
+코드 배포와 별개로 돌릴 수 있어야 하기 때문이다.
+
+```bash
+cd ~/data2/o2o-site-AEO
+./deploy.sh api
+docker compose exec solution-backend python scripts/migrate.py --dry-run   # 뭐가 돌지 먼저 본다
+docker compose exec solution-backend python scripts/migrate.py
+```
+
+적용 기록은 `public.schema_migrations` 에 남고 이미 있는 번호는 건너뛴다. 파일은 재실행
+안전하게(`IF NOT EXISTS`) 쓰므로 손으로 한 번 더 돌려도 된다.
+규칙은 [postgres-init/migrations/README.md](../postgres-init/migrations/README.md).
+
+★ **2026-09-10 배포는 스키마가 통째로 바뀐다**(`0005`~`0008`). 도메인별 스키마
+(`company` · `place` · `fact` · `local` · `site` · `job`)를 걷어내 `public` 한 벌로 폈고
+표 이름도 옮겼다 — `place_links` → `place_channels`, `job.jobs` → `jobs`, 공용 콘텐츠는
+`area_contents` 한 벌, 개인화는 `site_sections` 로 모았다.
+**마이그레이션을 안 돌리면 컨테이너는 정상으로 뜨고 가게 등록 · 수집 · 발행만 죽는다** —
+없는 표를 부르는 코드는 import 도 기동도 통과하고 그 줄이 실행되는 순간에만 터진다.
 
 ## 공개 주소 — `https://web4ai.o2osolution.ai` (2026-09-03 기준)