From 185664497258997d08c6b77359b5478d18ea2602 Mon Sep 17 00:00:00 2001 From: Mina Choi Date: Mon, 31 Aug 2026 16:32:41 +0900 Subject: [PATCH] =?UTF-8?q?=EB=AC=B8=EC=84=9C:=20README=20=EB=A5=BC=20?= =?UTF-8?q?=EC=A7=80=EA=B8=88=20=EA=B5=AC=EC=A1=B0=EB=A1=9C=20=EB=A7=9E?= =?UTF-8?q?=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 주소표를 갈랐다. 내부 화면(:3002)·내부 API(:9801)가 127.0.0.1 에만 열린다는 걸 적었다. - 클론 직후 `cp nginx/site.conf.example` 을 넣었다 — 빼먹으면 Docker 가 그 자리에 디렉토리를 만들어 nginx 가 설정 없이 뜬다. - npm 워크스페이스 루트가 레포 루트라는 것, 스키마가 init.sql 한 벌이라는 것. - 레포 구조를 admin/{backend,frontend} 까지 반영. - 문서 지도에 DEVELOPMENT_DIRECTION 이 두 줄 있었다. "한 사실은 한 곳에"를 이 표가 스스로 어기고 있었다. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_019uYhHQdssRubirPirrdJJC --- README.md | 55 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 33 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 27de4d8..306190d 100644 --- a/README.md +++ b/README.md @@ -13,49 +13,60 @@ ## 실행 ```bash -cp .env.example .env # DB_*, JWT_*, 외부 API 키 -docker compose up -d # API :9800 · 워커 · web :3000 +cp .env.example .env # DB_*, JWT_*, 외부 API 키 +cp nginx/site.conf.example nginx/site.conf # 빼먹으면 nginx 가 설정 없이 뜬다 +docker compose up -d docker compose logs -f worker ``` -| | 주소 | -|---|---| -| 빌더/운영 화면 | http://localhost:3000 | -| 발행된 사이트 | http://localhost:3000/s/`` | -| API 문서 | http://localhost:9800/docs | +| | 주소 | 공개 | +|---|---|---| +| 사장님 앱 (빌더) | http://localhost:3000 | 외부 | +| 발행된 사이트 | http://localhost:3000/s/`` · 운영은 :80 | 외부 | +| 사장님 API 문서 | http://localhost:9800/docs | 외부 | +| **내부 운영 화면** | http://localhost:3002 | **127.0.0.1 만** | +| **내부 API 문서** | http://localhost:9801/docs | **127.0.0.1 만** | -DB 는 compose 밖이다 (호스트 PostgreSQL, `host.docker.internal`). -백엔드 스크립트는 `solution/backend/` 에서 `.venv/bin/python scripts/.py`. +내부 두 개를 `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/.py` +- 테스트는 `solution/backend/` 에서 `.venv/bin/pytest` ## 레포 구조 ``` -solution/ 사장님 — 사이트 만들기·관리 - backend/ FastAPI + 워커. 진입점 둘 — web_main(:9800 사장님) / admin_main(:9801 내부) - frontend/ 빌더(위저드 + 에디터 + 발행 게이트) - site/ 발행 사이트. SSR 엔트리 + 프리렌더 + 정적 서버 - shared/ front·site·백엔드 계약이 만나는 타입·규칙 (SitePayload, slug) -admin/ 우리 — 전체 사이트 운영 - backend/ 내부 API 진입점(:9801). 도메인 코드는 solution/backend 를 PYTHONPATH 로 쓴다 - frontend/ 내부 운영 화면 -docs/ 아래 표 -nginx/ 발행 사이트 정적 서빙 (site.conf 는 .example 만 커밋한다) -postgres-init/ 스키마 DDL (init.sql 한 벌) +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/ARCHITECTURE.md). + ## 문서 지도 | 문서 | 언제 읽나 | |---|---| | [docs/PRODUCT.md](docs/PRODUCT.md) | 이 제품이 뭘 푸는지 · **안 하기로 한 것**이 뭔지 | -| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 발행 파이프라인 전체 · 앱을 어떻게 나눌지 | +| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 발행 파이프라인 전체 · 두 앱과 한 백엔드의 경계 | | [docs/DEVELOPMENT_DIRECTION.md](docs/DEVELOPMENT_DIRECTION.md) | v19 설계서 대비 격차 · **개발 우선순위(P0~P4)** | | [docs/DECISIONS.md](docs/DECISIONS.md) | 미결 사항과, 코드가 그걸 어떻게 격리해 뒀는지 | | [docs/DEPLOY.md](docs/DEPLOY.md) | 서버에 올릴 때 · 배포 후 재발행 절차 | | [docs/DATA_SOURCE_RESEARCH.md](docs/DATA_SOURCE_RESEARCH.md) | 어디서 콘텐츠를 가져올 수 있나 (실측 근거) | | [docs/COLLECTION_SEO_AEO_FLOW.md](docs/COLLECTION_SEO_AEO_FLOW.md) | 수집→LLM→SEO/AEO 현재 구현 | | [docs/API_USAGE.md](docs/API_USAGE.md) | API 비용 — 제품 원가와 개발비 구분 | -| [docs/DEVELOPMENT_DIRECTION.md](docs/DEVELOPMENT_DIRECTION.md) | Web4AI v19 설계서와 현재 구현의 차이 · 추가 개발 우선순위 | ## 문서 규칙