Mina Choi
fc47946d3f
세팅할 때마다 "이 값이 어디 가는 거지" 를 코드에서 되짚고 있었다. AGENTS.md 에 설정 파일 지도를 넣고, 흩어져 있던 cp 명령을 거기 한 곳으로 모았다. 두는 곳 — 템플릿이 전부 짝을 갖는다(7개 확인). 루트 .env ← 백엔드가 읽는 유일한 .env solution/backend/config/ config.local.toml DB·JWT·포트·CORS solution/backend/config/ config.test.toml 없으면 pytest 가 import 단계에서 죽는다 solution/frontend/ .env VITE_* (API :9800) admin/frontend/ .env VITE_* (API :9801) nginx/ site.conf 없으면 Docker 가 디렉토리를 만든다 두지 않는 곳과 그 이유도 같이 적었다 — solution/backend(dotenv 가 루트를 본다), admin/backend(PYTHONPATH 로 solution 것을 쓴다), solution/site, solution/shared. solution/site/.env.example 을 지웠다. "여기엔 아무것도 없다" 는 걸 알리려고 둔 파일인데, .env.example 은 이 레포에서 "복사해서 채워라" 라는 뜻이라 정반대 신호를 준다. 그 설명은 지도의 '두지 않는 곳' 으로 옮겼다. 그 밖에 - config.test.toml.example 의 server_name 이 O2oSiteServerTest 로 남아 있었다. - config.local.toml.example 에 생략 가능한 [ExternalApiConfig] 필드 셋을 주석으로 적었다. - .gitignore 의 *.toml 이 레포 전체를 덮는다는 것과, 그래서 pyproject.toml 같은 걸 추가하면 조용히 무시된다는 것을 규칙 옆에 적었다.
165 lines
11 KiB
Markdown
165 lines
11 KiB
Markdown
# AGENTS.md — 이 레포에서 작업하기 전에
|
|
|
|
에이전트와 신규 합류자가 **먼저 읽는 파일**이다. 여기에는 *밟기 쉬운 함정*과 *규약*만 둔다.
|
|
설명은 각 문서가 단일 출처다 — 여기로 복사하지 말고 링크한다.
|
|
|
|
| 궁금한 것 | 문서 |
|
|
|---|---|
|
|
| 이 제품이 뭘 푸나 · **안 하기로 한 것** | [docs/PRODUCT.md](docs/PRODUCT.md) |
|
|
| 어떻게 도나 · 앱 경계 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
|
|
| **다음에 뭘 만드나** (우선순위 P0~P4) | [docs/DEVELOPMENT_DIRECTION.md](docs/DEVELOPMENT_DIRECTION.md) |
|
|
| 미결 사항 · 코드가 그걸 어떻게 격리했나 | [docs/DECISIONS.md](docs/DECISIONS.md) |
|
|
| 서버에 올릴 때 | [docs/DEPLOY.md](docs/DEPLOY.md) |
|
|
|
|
---
|
|
|
|
## 이 레포의 한 가지 규칙
|
|
|
|
**백엔드는 HTML 을 만들지 않는다.** payload JSON 을 파일로 떨어뜨리고, Node 프리렌더가 그걸 읽어
|
|
정적 사이트를 굽는다. 두 쪽은 서로를 모르고 **디렉토리 하나로만 만난다.**
|
|
이 경계를 넘는 변경은 하기 전에 [ARCHITECTURE.md 1절](docs/ARCHITECTURE.md)을 읽는다.
|
|
|
|
## 반드시 알아야 할 함정
|
|
|
|
밟으면 **조용히 틀린다** — 빌드는 성공하고 화면도 뜨는데 결과가 잘못된 종류다.
|
|
|
|
- **번들 파일명은 콘텐츠 해시다.** HTML 은 `/assets/index-DvNTmLhy.css` 를 **루트 절대경로**로
|
|
가리킨다. 경로는 프리렌더가 `dist/client/.vite/manifest.json` 에서 읽어 박는다
|
|
(`prerender.ts:160`). 렌더러 CSS 를 고치면 이름이 바뀐다.
|
|
- **로컬 `out/assets` 는 빌드마다 통째로 갈린다** (`prerender.ts:573` `rmSync`). 옛 해시 파일이
|
|
사라지므로 새 번들로 일부 사이트만 구우면 나머지는 CSS 가 404 다.
|
|
→ 프리렌더 기동 시 전체 재굽기가 이 구멍을 메운다.
|
|
- **★ 프론트(`solution/site`)를 배포하면 반드시 전체 재굽기 + 전체 재업로드.**
|
|
`azure_static.publish(slug)` 는 공용 자산 + `s/<slug>` 만 올린다 —
|
|
**렌더러를 고쳐도 다른 사이트에는 반영되지 않는다.**
|
|
→ `docker compose restart web` 후 `python scripts/republish_all.py`
|
|
- **발행 호스트는 두 곳에 있고 같아야 한다.** 백엔드 `SITE_PUBLIC_HOST`(기본 `w4ai.o2o.kr`,
|
|
`site_payload.py`) ↔ 프론트 `VITE_PUBLISH_HOST`. canonical·og:url·sitemap·IndexNow 가 전부
|
|
이 값을 쓴다. 그리고 **`origin` 은 payload JSON 에 구워진다** — 호스트를 바꾸면 프리렌더
|
|
재실행만으로는 안 되고 **백엔드에서 재발행**해 payload 를 다시 만들어야 한다.
|
|
- **`AZURE_STORAGE_PREFIX` 와 루트 절대경로는 충돌한다.** HTML 이 `/assets/…` 를 가리키는데
|
|
블롭은 `ai-for-web/assets/…` 에 놓인다. 접두사를 쓰려면 오리진 경로를 `/ai-for-web` 로 잡는
|
|
CDN 을 앞에 세워야 한다. 아니면 비워라.
|
|
(프리렌더는 서브패스 마운트를 지원한다 — `basePath` 가 `/sites/s/joy` 면 자산은 `/sites/assets`.)
|
|
- **`AZURE_STORAGE_CONTAINER=$web`** — 셸에서 export 할 땐 반드시 작은따옴표(`'$web'`).
|
|
- **슬러그 규칙은 두 곳에 있고 같아야 한다**: `site_payload.publish_slug()` ↔
|
|
`solution/shared/src/lib/slug.ts publishUrl`. 어긋나면 발행은 성공하고 주소만 404 다.
|
|
- **디렉토리 요청 → `index.html`.** `/s/<slug>` 가 **끝 슬래시 없이** 열려야 한다.
|
|
정적 서버를 바꾸든 nginx 설정을 만지든 이 규칙부터 확인한다.
|
|
|
|
## 코드 규약
|
|
|
|
- **미결 사항은 코드로 풀지 않는다.** [DECISIONS.md](docs/DECISIONS.md) 1절이 보류한 것은
|
|
플래그·어댑터로 격리해 두고, 결론이 나면 **날짜와 함께 결론을 적고 격리를 제거한다.**
|
|
- **수집 어댑터를 추가하기 전에** [DECISIONS.md](docs/DECISIONS.md) 1-1 과
|
|
[DATA_SOURCE_RESEARCH.md](docs/DATA_SOURCE_RESEARCH.md)를 읽는다.
|
|
봇 탐지 우회는 **결론과 무관하게 영구 금지**다.
|
|
- **주석은 "왜"를 적는다.** 이 레포의 기존 주석이 그 톤이다 — 실측값, 밟았던 함정, 안 한 이유.
|
|
코드를 읽으면 알 수 있는 "무엇"은 쓰지 않는다.
|
|
- 문서는 코드와 **같은 커밋**에서 고친다. 동작을 바꿨는데 문서를 안 고쳤으면 미완이다.
|
|
|
|
## 레포 구조
|
|
|
|
```
|
|
solution/ 사장님 — backend · frontend(빌더) · site(발행물) · shared(계약)
|
|
admin/ 우리 — backend(진입점만, :9801) · frontend(운영 화면)
|
|
```
|
|
|
|
최상단은 **프로젝트 단위**다(`o2o-negosium` 과 같은 규약). `frontend/` `backend/` 를 최상단
|
|
묶음 폴더로 쓰지 않는다. 근거와 경계는 [ARCHITECTURE.md 4절](docs/ARCHITECTURE.md).
|
|
|
|
★ **의존 방향은 `admin` → `solution` 한 쪽뿐이다.** admin 의 `@` 별칭이 `solution/frontend/src` 를
|
|
가리키고, API 도 solution 백엔드를 본다. 반대 방향이 생기면 가른 의미가 사라진다.
|
|
|
|
★ **백엔드는 코드 한 벌, 진입점 둘이다.**
|
|
|
|
| | 포트 | 진입점 | 권한 |
|
|
|---|---|---|---|
|
|
| 사장님 API | 9800 | `solution/backend/web_main.py` | 엔드포인트별 |
|
|
| 내부 API | 9801 | `admin/backend/main.py` → `app.py` | **앱 전체 role >= DEVELOPER** |
|
|
|
|
`services`·`crud`·`models` 은 그대로 공유한다. admin 화면이 부르는 게 사장님 빌더와 거의
|
|
같아서(place·fact, admin 전용은 `local-content` 하나) 도메인을 복제하지 않고 **같은 router
|
|
객체를 다시 마운트하면서 앱 단위로 권한만 덧건다.**
|
|
경로 접두어(`/v1/admin/...`)가 아니라 **포트**를 가른 이유: 접두어는 같은 프로세스라
|
|
사장님이 닿는 서버에 내부 엔드포인트가 존재한다. 포트를 가르면 아예 없다.
|
|
`ADMIN_API_BIND` 기본값이 `127.0.0.1` 인 것도 같은 이유다 — 0.0.0.0 으로 열면 무의미하다.
|
|
⚠️ 단 `/v1/admin/local-content` 는 아직 :9800 에도 마운트돼 있다 — 남은 구멍이다
|
|
([ARCHITECTURE.md 4절](docs/ARCHITECTURE.md)).
|
|
|
|
## 실행
|
|
|
|
```bash
|
|
docker compose up -d # api :9800 · api-admin :9801 · 워커 · web :3000 · admin :3002 · nginx :80
|
|
docker compose logs -f worker
|
|
```
|
|
|
|
- 사장님 앱 `:3000`(API :9800) · 내부 운영 `:3002`(API :9801, 로컬호스트에만 열림)
|
|
- 발행 사이트: `http://localhost:3000/s/<slug>` (빌더 Vite 가 :3001 정적서버로 프록시)
|
|
- **클론 직후 1회**: 설정 파일 복사 — 아래 "설정 파일은 어느 폴더에 두나"
|
|
- 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`. **`APP_ENV=test` 면 `.env` 를 읽지 않는다** —
|
|
실키가 테스트로 새어 외부 API 요금이 나가는 경로를 막아 뒀다
|
|
|
|
## 설정 파일은 어느 폴더에 두나
|
|
|
|
**실제 값은 하나도 커밋되지 않는다.** 커밋되는 건 `*.example` 뿐이고, 클론 직후 그걸 복사해
|
|
값을 채우는 게 세팅의 전부다.
|
|
|
|
| 폴더 | 파일 | 담는 것 | 템플릿 |
|
|
|---|---|---|---|
|
|
| **레포 루트** | `.env` | DB · JWT · 외부 API 키 · 수집 어댑터 · 발행/색인 · 포트 바인딩 | `.env.example` |
|
|
| `solution/backend/config/` | `config.local.toml` | DB 접속 · JWT · 포트 · CORS(`client_url`) | `config.local.toml.example` |
|
|
| `solution/backend/config/` | `config.test.toml` | 테스트 DB(`web4ai_test_db`) | `config.test.toml.example` |
|
|
| `solution/frontend/` | `.env` | 이 앱의 `VITE_*` (API :9800 · 발행 호스트 · 개발 자동로그인) | `.env.example` |
|
|
| `admin/frontend/` | `.env` | 이 앱의 `VITE_*` (API **:9801**) | `.env.example` |
|
|
| `nginx/` | `site.conf` | 발행 사이트 정적 서빙 규칙 | `site.conf.example` |
|
|
|
|
**두지 않는 곳** — 두면 조용히 무시된다.
|
|
|
|
| 폴더 | 왜 없나 |
|
|
|---|---|
|
|
| `solution/backend/` | `.env` 를 여기 두면 아무도 안 읽는다. dotenv 가 **레포 루트**를 본다 (`config/server_configs.py`) |
|
|
| `admin/backend/` | 진입점 두 파일뿐이다. `config/` 는 `PYTHONPATH` 로 `solution/backend` 것을 그대로 쓴다 |
|
|
| `solution/site/` | 렌더러는 런타임 env 를 안 쓴다 — 사이트별 값은 전부 `SitePayload` 로 들어온다. 그래야 payload 하나로 같은 HTML 이 재현된다. 프리렌더 옵션은 CLI 인자(`--payload` `--out`)이고, `INDEXNOW_KEY`·`PORT` 는 compose 가 프로세스에 넣는다 |
|
|
| `solution/shared/` | 코드만 있다 |
|
|
|
|
### 클론 직후 한 번
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
cp nginx/site.conf.example nginx/site.conf
|
|
cp solution/backend/config/config.local.toml.example solution/backend/config/config.local.toml
|
|
cp solution/backend/config/config.test.toml.example solution/backend/config/config.test.toml
|
|
cp solution/frontend/.env.example solution/frontend/.env # compose 로만 쓰면 생략 가능
|
|
cp admin/frontend/.env.example admin/frontend/.env # 〃
|
|
```
|
|
|
|
`site.conf` 를 빼먹으면 Docker 가 그 자리에 **디렉토리**를 만들어 nginx 가 설정 없이 뜬다.
|
|
`config.test.toml` 이 없으면 `pytest` 가 conftest import 단계에서 죽는다.
|
|
|
|
### 누가 무엇을 읽나 — 우선순위
|
|
|
|
**실제 환경변수(compose) > 루트 `.env` > `config.{APP_ENV}.toml`**
|
|
|
|
- compose 는 루트 `.env` 를 `env_file` 로 통째로 넣고 `${...}` 치환에도 쓴다.
|
|
- 백엔드는 **compose 밖에서 띄울 때** 루트 `.env` 를 python-dotenv 로 직접 읽는다.
|
|
- Vite 앱만 구조상 **자기 디렉토리의 `.env`** 를 읽는다 — 그래서 나뉜 것이지 취향이 아니다.
|
|
- 도커 이미지는 시크릿을 굽지 않는다. `config.local.toml` 을 **example 사본(플레이스홀더)으로
|
|
덮어** 넣으므로(`Dockerfile:24`), 컨테이너로 띄울 땐 `JWT_*` 를 env 로 반드시 주입해야 한다.
|
|
안 하면 공개된 플레이스홀더가 서명 키가 된다.
|
|
- **`APP_ENV=test` 면 `.env` 를 읽지 않는다.** 실키가 테스트로 새어 외부 API 요금이 나가는
|
|
경로를 막아 뒀다 — 그래서 `config.test.toml` 의 키는 전부 빈 값이어야 한다.
|
|
|
|
★ **두 곳에 같은 값을 적지 않는다.** 발행 호스트는 compose 가 루트의 `SITE_PUBLIC_HOST` 를
|
|
`VITE_PUBLISH_HOST` 로 흘려보낸다. 각자 적으면 canonical 과 화면 주소가 조용히 갈라진다.
|
|
|
|
## 커밋
|
|
|
|
- 한 커밋 = 한 가지 변경. 문서와 그 문서가 설명하는 코드는 같은 커밋에 둔다.
|
|
- 커밋 메시지는 한국어로, **무엇을 왜 바꿨는지**. 파일 목록은 `git` 이 이미 안다.
|