Mina Choi
139d460839
alters/*.sql 은 **기존 DB 를 보정**하는 파일이다. 그런데 이 프로젝트는 아직 git 에도 서버에도 올라가지 않아 보정할 기존 DB 가 없다. 파일마다 주석이 "신규 DB 는 init-data/init.sql 에 반영돼 있어 이 파일이 필요 없다"고 이미 적고 있었다. 지우기 전에 init.sql 이 여섯 개를 전부 담고 있는지 확인했다 — local_contents 발행 컬럼 4개, site template_id·theme, external_place_id/external_source, 그리고 allow-duplicate-places 가 지우는 두 인덱스가 애초에 없다는 것까지. 운영 DB 가 생기는 순간 이 디렉토리는 다시 필요해진다. 그때 되살린다. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019uYhHQdssRubirPirrdJJC |
||
|---|---|---|
| backend | ||
| docs | ||
| frontend | ||
| nginx | ||
| postgres-init/init-data | ||
| .env.example | ||
| .gitignore | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| docker-compose.yml | ||
| README.md | ||
o2o-web4ai
상호명 하나로 소상공인 홈페이지를 만들어 발행하는 서비스.
목표는 예쁜 사이트가 아니다 — AI 검색과 검색엔진이 이 가게를 "공식 홈페이지 기준"으로 설명하게 만드는 것이다. 그래서 산출물은 SPA 가 아니라 크롤러가 그대로 읽는 정적 HTML 이고, 발행 게이트가 통과시키지 않은 값은 사이트에 나가지 않는다.
- 무엇을 · 누구를 위해 · 무엇을 안 하는가 → docs/PRODUCT.md
- 어떻게 도는가 (파이프라인·앱 경계) → docs/ARCHITECTURE.md
- 에이전트·신규 합류자가 먼저 읽을 규약 → AGENTS.md
실행
cp .env.example .env # DB_*, JWT_*, 외부 API 키
docker compose up -d # API :9800 · 워커 · web :3000
docker compose logs -f worker
| 주소 | |
|---|---|
| 빌더/운영 화면 | http://localhost:3000 |
| 발행된 사이트 | http://localhost:3000/s/<slug> |
| API 문서 | http://localhost:9800/docs |
DB 는 compose 밖이다 (호스트 PostgreSQL, host.docker.internal).
백엔드 스크립트는 backend/ 에서 .venv/bin/python scripts/<name>.py.
레포 구조
backend/ FastAPI + 워커. HTML 을 만들지 않는다 — payload JSON 만 떨어뜨린다
frontend/
admin/ 빌더(사장님) + 내부 운영 화면 — ★ 분리 예정, ARCHITECTURE.md 4절
site/ 발행 사이트. SSR 엔트리 + 프리렌더 + 정적 서버
shared/ 두 앱과 백엔드 계약이 만나는 타입·규칙 (SitePayload, slug)
docs/ 아래 표
postgres-init/ 스키마 DDL
문서 지도
| 문서 | 언제 읽나 |
|---|---|
| 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 비용 — 제품 원가와 개발비 구분 |
| docs/DEVELOPMENT_DIRECTION.md | Web4AI v19 설계서와 현재 구현의 차이 · 추가 개발 우선순위 |
문서 규칙
- 한 사실은 한 곳에. 중복된 문서는 썩고, 썩은 문서는 사람과 에이전트를 적극적으로 오도한다. 다른 문서의 내용은 복사하지 말고 링크한다.
- 코드가 말해주는 건 쓰지 않는다. 문서에 적을 값어치가 있는 건 왜 이렇게 했는지, 왜 저건 안 했는지, 그리고 실측값(날짜와 함께)이다.
- 결론이 나면
DECISIONS.md에 날짜와 함께 적고, 격리해 둔 플래그를 제거한다. - 문서는 코드와 같은 커밋·같은 리뷰에서 고친다. 동작을 바꾸는 PR 이 문서를 안 고쳤으면 미완이다.