Web4ai/o2o-site-AEO
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
99 Commits 13 Branches 0 Tags 104 MiB
HTML 36.4%
Python 23.4%
TypeScript 22.7%
CSS 10.5%
SCSS 4.3%
Other 2.6%
e0d45eda97
Go to file
Mina Choi e0d45eda97 [fix] postgres-init,solution/backend,docs: 스키마 재편이 안 닿은 자리를 전부 잡는다 — init.sql · ORM 인덱스 · 테스트 
0005 가 도메인 스키마를 걷어내고 표 이름을 옮겼는데, 문자열로 표 이름을 들고 있던 자리들이
따라오지 않았다. import 도 타입검사도 pyflakes 도 못 잡는 종류라 전부 **실행되는 순간에만**
터졌고, 그동안 pytest 는 569건이 통째로 죽어 있어 아무것도 못 잡고 있었다.

**init.sql 이 새 DB 를 옛 구조로 세우고 있었다**
64ce467 이 이 파일에 94줄을 더하기만 하고 삭제를 0줄 했다. 그래서 이 파일 한 벌로 세운 DB 는
`place.place_links`·`job.jobs` 를 갖고 ORM 은 `public.place_channels`·`public.jobs` 를 찾는다 —
기동은 정상이고 첫 쿼리에서 죽는다. "init.sql 은 새 DB 를 세우는 전체 DDL 이고 계속 최신을
유지한다"(migrations/README.md)는 계약이 깨져 있었다.
- public 한 벌 · 표 14개로 다시 썼다. 옛 스키마가 있는 DB 에서 다시 돌면 RAISE EXCEPTION 으로
  멈춘다 — 그대로 두면 public 에 빈 표가 생기고 0005 가 "relation already exists" 로 실패해
  데이터가 옛 스키마에 갇힌다
- 말미에 **마이그레이션 기준선**을 심는다. 없으면 새 DB 에서 migrate.py 가 0001 부터 다시 돌다가
  `schema "local" does not exist` 로 죽는다

**운영 버그 둘** — 두 DB(새로 세운 것 · 마이그레이션으로 따라온 것)를 pg_dump 로 찍어 비교해 찾았다
- `upsert_weather` 의 ON CONFLICT 술어에 `kind IS NULL` 이 빠져 **날씨 캐시 저장이 계속 실패**하고
  있었다(0007 이 인덱스에 그 조건을 더했다). 캐시라 화면이 안 죽고 로그에만 남았다.
  포스트그레스는 술어가 인덱스 술어를 함의하는지 보고 아니면 "no unique or exclusion constraint
  matching" 으로 거절한다 — 컬럼도 표도 멀쩡해서 눈으로는 원인이 안 보인다
- ORM 의 `area_contents` 인덱스 정의가 0004·0007·0008 을 하나도 안 따라왔다. 테스트 DB 는 이
  모델로 세워지므로 **테스트가 운영과 다른 제약 아래에서 돌고 있었다**

**0009** — 두 DB 비교에서 나온 어긋남 셋(데이터는 안 건드린다)
- `idx_site_contents_site` 가 기존 DB 에만 없었다(0003 이 유니크만 걸었다) — 섹션 조회가 시퀀셜 스캔
- `places.external_place_id` VARCHAR(32) → (64). ORM 은 64 다 — 긴 id 가 잘리면 동일 업소 판정이 틀린다
- RENAME 이 안 따라간 PK 제약 이름 9개(`facts_pkey` → `place_facts_pkey` …)

**테스트를 살린다**
- conftest 의 TRUNCATE 가 표 이름을 **손으로 나열**하고 있었다. 0005 가 이름을 옮기자 전 테스트가
  `relation "place_aliases" does not exist` 로 죽었다 — 이제 ORM 메타데이터에서 뽑아 다시 어긋날 수 없다
- `test_schema_ddl` 이 모델 표를 `"None.users"` 로 조회해 **한 표도 비교하지 않고 통과**하고 있었다.
  init.sql 이 조용히 어긋난 동안 이 테스트는 초록이었다. 비교한 표 수를 세는 단언을 더한다
- 테스트 SQL 15곳의 옛 표 이름, `_run_worker` 1틱 문제(수집 뒤 따라오는 LOCAL_SYNC 를 집어 가
  정작 기다리던 잡이 PENDING 으로 남았다), 지역 캐시 픽스처(읽는 코드가 옳게 거르는데 테스트가 빨개졌다)

**문서**
- `docs/DATA_MODEL.md` 신설 — 표 14개가 무엇을 담고 누가 쓰는지, 값 하나가 DB 에서 페이지까지
  가는 길, 두 번 도는 게이트, **DB 에 없는 것**
- `SERVERS.md` DB 절을 마이그레이션 체계로. 배포에 `migrate.py` 를 넣는다 — 코드만 갈면 컨테이너는
  정상으로 뜨고 가게 등록·수집·발행만 죽는다
- ARCHITECTURE 2절의 프리렌더 컨테이너가 `solution-frontend` 로 적혀 있었다. 굽는 건
  `solution-prerender` 고 전자는 운영에서 뜨지도 않는다 — AGENTS.md 가 함정으로 적어 둔 그 혼동을
  문서가 만들고 있었다
- 옛 표 이름 잔재(`place_links`·`local_contents`·`job.jobs`·`company.users`·`fact.facts`·`ai_check_results`)

검증: 빈 컨테이너에 init.sql 로 세운 DB ↔ 마이그레이션으로 따라온 DB 를 `pg_dump --schema-only`
로 비교 — 표·인덱스·제약·컬럼 전부 동일. pytest 583건 중 581 통과(남은 2건은 `.env` 누수·
레이트리밋 카운터로 환경 문제다). 구글 로그인 21건 포함.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-10 11:39:43 +09:00
admin [refactor] postgres-init,solution: DB 구조 재편 — 스키마 해체 · 공용 콘텐츠 한 벌 · 마이그레이션 체계 2026-09-09 17:08:02 +09:00
docs [fix] postgres-init,solution/backend,docs: 스키마 재편이 안 닿은 자리를 전부 잡는다 — init.sql · ORM 인덱스 · 테스트 2026-09-10 11:39:43 +09:00
nginx [refactor] solution,nginx: 에디터와 발행본을 한 렌더러로 — 보는 그대로 나간다 2026-09-09 17:09:28 +09:00
postgres-init [fix] postgres-init,solution/backend,docs: 스키마 재편이 안 닿은 자리를 전부 잡는다 — init.sql · ORM 인덱스 · 테스트 2026-09-10 11:39:43 +09:00
solution [fix] postgres-init,solution/backend,docs: 스키마 재편이 안 닿은 자리를 전부 잡는다 — init.sql · ORM 인덱스 · 테스트 2026-09-10 11:39:43 +09:00
.dockerignore 업종 4번째를 관광체험 → 피부과·성형외과 로 바꾸고, 로그인 관문을 에디터 진입으로 되돌린다 2026-09-02 15:42:34 +09:00
.env.example [fix] deploy: 앱이 부르는 API 주소를 한 오리진으로 — :9800 기본값이 로그인을 막았다 2026-09-07 16:19:34 +09:00
.gitignore [feat] solution/frontend,nginx: 랜딩·요금·사례를 프리렌더 — 크롤러가 빈 종이를 받던 것 2026-09-07 11:30:27 +09:00
AGENTS.md [fix] postgres-init,solution/backend,docs: 스키마 재편이 안 닿은 자리를 전부 잡는다 — init.sql · ORM 인덱스 · 테스트 2026-09-10 11:39:43 +09:00
CLAUDE.md .gitignore: CLAUDE.md 심볼릭 링크를 전역 무시에서 되살린다 2026-08-31 13:58:34 +09:00
deploy.sh [feat] deploy,solution/frontend: 운영에서 dev 서버를 걷어낸다 — 정적 번들을 nginx 가 서빙 2026-09-01 11:46:32 +09:00
docker-compose.yml [refactor] postgres-init,solution: DB 구조 재편 — 스키마 해체 · 공용 콘텐츠 한 벌 · 마이그레이션 체계 2026-09-09 17:08:02 +09:00
log.sh [feat] deploy,backend,site: 킹서버 배포 + 설정을 최상위 .env 하나로 통합 2026-09-01 10:04:36 +09:00
package-lock.json [feat] solution/frontend,nginx: 랜딩·요금·사례를 프리렌더 — 크롤러가 빈 종이를 받던 것 2026-09-07 11:30:27 +09:00
package.json [feat] solution,postgres-init: 지역 이야기를 서버가 채운다 · 공용과 개인화를 이름으로 가른다 2026-09-09 17:08:31 +09:00
README.md [feat] deploy,backend,site: 킹서버 배포 + 설정을 최상위 .env 하나로 통합 2026-09-01 10:04:36 +09:00
tsconfig.base.json 구조: 사장님(solution)과 내부 운영(admin)을 두 앱으로 가른다 2026-08-31 15:12:09 +09:00

README.md

o2o-web4ai

상호명 하나로 소상공인 홈페이지를 만들어 발행하는 서비스.

목표는 예쁜 사이트가 아니다 — AI 검색과 검색엔진이 이 가게를 "공식 홈페이지 기준"으로 설명하게 만드는 것이다. 그래서 산출물은 SPA 가 아니라 크롤러가 그대로 읽는 정적 HTML 이고, 발행 게이트가 통과시키지 않은 값은 사이트에 나가지 않는다.

  • 무엇을 · 누구를 위해 · 무엇을 안 하는가 → docs/PRODUCT.md
  • 어떻게 도는가 (파이프라인·앱 경계) → docs/ARCHITECTURE.md
  • 에이전트·신규 합류자가 먼저 읽을 규약 → AGENTS.md

실행

cp .env.example .env                              # DB_*, JWT_*, 외부 API 키
cp nginx/site.conf.example nginx/site.conf        # 빼먹으면 nginx 가 설정 없이 뜬다
docker compose up -d
docker compose logs -f solution-worker
주소 공개
사장님 앱 (빌더) http://localhost:3000 외부
발행된 사이트 http://localhost:3000/s/<slug> · 운영은 :80 외부
솔루션 API 문서 http://localhost:9800/docs 외부
내부 운영 화면 http://localhost:3002 127.0.0.1 만
어드민 API 문서 http://localhost:9801/docs 127.0.0.1 만

내부 두 개를 0.0.0.0 으로 열면 앱을 가른 의미가 없다 (ADMIN_BIND · ADMIN_API_BIND).

  • DB 는 compose 밖이다 (호스트 PostgreSQL, host.docker.internal). 스키마는 postgres-init/init-data/init.sql 한 벌 — 누적 ALTER 파일은 없다.
  • npm 워크스페이스 루트는 레포 루트다. npm install 은 여기서 한 번. npm run dev:frontend / dev:admin / dev:site
  • 백엔드 스크립트는 solution/backend/ 에서 .venv/bin/python scripts/<name>.py
  • 테스트는 solution/backend/ 에서 .venv/bin/pytest

레포 구조

solution/          사장님 — 사이트 만들기·관리
  backend/         FastAPI(:9800) + 워커. HTML 은 만들지 않는다 — payload JSON 만 떨어뜨린다
  frontend/        빌더 (위저드 + 에디터 + 발행 게이트)
  site/            발행 사이트. SSR 엔트리 + 프리렌더 + 정적 서버
  shared/          frontend·site·백엔드 계약 (SitePayload · slug · 디자인 토큰)
admin/             우리 — 전체 사이트 운영
  backend/         진입점만(:9801). 도메인 코드는 solution/backend 를 PYTHONPATH 로 쓴다
  frontend/        운영 화면. `@` 별칭이 solution/frontend/src 를 가리킨다
docs/              아래 표
nginx/             발행 사이트 정적 서빙 (site.conf 는 .example 만 커밋)
postgres-init/     스키마 DDL

의존 방향은 admin → solution 한 쪽뿐이다. 반대가 생기면 번들을 가른 의미가 사라진다. 근거는 ARCHITECTURE.md 4절.

문서 지도

문서 언제 읽나
docs/PRODUCT.md 이 제품이 뭘 푸는지 · 안 하기로 한 것이 뭔지
docs/ARCHITECTURE.md 발행 파이프라인 전체 · 두 앱과 한 백엔드의 경계
docs/DEVELOPMENT_DIRECTION.md v19 설계서 대비 격차 · 개발 우선순위(P0~P4)
docs/DECISIONS.md 미결 사항과, 코드가 그걸 어떻게 격리해 뒀는지
docs/DEPLOY.md 서버에 올릴 때 · 배포 후 재발행 절차
docs/DATA_SOURCE_RESEARCH.md 어디서 콘텐츠를 가져올 수 있나 (실측 근거)
docs/COLLECTION_SEO_AEO_FLOW.md 수집→LLM→SEO/AEO 현재 구현
docs/API_USAGE.md 외부 API 원가 — 사이트 1건당 $1 상한을 어디서 강제하나

문서 규칙

  1. 한 사실은 한 곳에. 중복된 문서는 썩고, 썩은 문서는 사람과 에이전트를 적극적으로 오도한다. 다른 문서의 내용은 복사하지 말고 링크한다.
  2. 코드가 말해주는 건 쓰지 않는다. 문서에 적을 값어치가 있는 건 왜 이렇게 했는지, 왜 저건 안 했는지, 그리고 실측값(날짜와 함께)이다.
  3. 결론이 나면 DECISIONS.md 에 날짜와 함께 적고, 격리해 둔 플래그를 제거한다.
  4. 문서는 코드와 같은 커밋·같은 리뷰에서 고친다. 동작을 바꾸는 PR 이 문서를 안 고쳤으면 미완이다.