o2o-site-AEO/AGENTS.md

AGENTS.md — 이 레포에서 작업하기 전에

2026-09-15 발행 버전 전환: docs/PUBLISH_VERSION.md가 아래의 상시 프리렌더·재굽기·자산 주소 교체 절차를 대체한다. 목업은 변경하지 않는다.

에이전트와 신규 합류자가 먼저 읽는 파일이다. 여기에는 밟기 쉬운 함정과 규약만 둔다. 설명은 각 문서가 단일 출처다 — 여기로 복사하지 말고 링크한다.

궁금한 것	문서
이 제품이 뭘 푸나 · 안 하기로 한 것	docs/PRODUCT.md
어떻게 도나 · 앱 경계	docs/ARCHITECTURE.md
어느 표 어느 칸에 담기나 · 값이 페이지까지 가는 길	docs/DATA_MODEL.md
다음에 뭘 만드나 (우선순위 P0~P4)	docs/DEVELOPMENT_DIRECTION.md
미결 사항 · 코드가 그걸 어떻게 격리했나	docs/DECISIONS.md
최근에 뭘 왜 바꿨나	docs/DEVLOG.md
서버에 올릴 때	docs/DEPLOY.md
어느 서버에 올리나 (킹서버)	docs/SERVERS.md
장애가 나면 누가·어떻게 아나	docs/ALERTS.md
미니 블로그(AI 자동 포스트) 기획	docs/MINI_BLOG.md
사장님 에이전트(카톡으로 관리) · 신원 연결	docs/AGENT.md

---

이 레포의 한 가지 규칙

백엔드는 HTML 을 만들지 않는다. payload JSON 을 파일로 떨어뜨리고, Node 프리렌더가 그걸 읽어 정적 사이트를 굽는다. 두 쪽은 서로를 모르고 디렉토리 하나로만 만난다. 이 경계를 넘는 변경은 하기 전에 ARCHITECTURE.md 1절을 읽는다.

반드시 알아야 할 함정

밟으면 조용히 틀린다 — 빌드는 성공하고 화면도 뜨는데 결과가 잘못된 종류다.

• ★★ out/s/ 에는 payload 가 없는 사이트가 있다 — 목업(stay · stay2 · stay3 · *.old). 프리렌더는 payload 를 받은 사이트만 굽는다. 목업은 손으로 넣은 것이라 재굽기 대상이 아니고, 자산이 한 번 지워지면 영영 복구되지 않는다 — 재굽기를 몇 번 돌려도 안 살아나고 사람이 파일을 되돌려 넣어야 한다. 실측(2026-09-07): 번들 해시가 바뀌자 목업 3개의 CSS·JS· 이미지가 전부 404 가 됐고, 그 파일들은 stay-mockup 워크트리에서 손으로 꺼내 복구했다. → out/assets 에서 파일을 지우는 코드는 out/s/** 의 HTML 이 참조하는 것을 먼저 뺀다 (prerender.ts referencedAssets). 보관 기간으로는 못 막는다 — 기간이 지나면 같은 일이 난다. → 목업을 다루는 작업은 out/s/ 를 먼저 열어 payload 가 없는 디렉토리가 무엇인지 본다. → ★ stay 는 프리렌더가 굽지 않는다 (prerender.ts PROTECTED_SLUGS, 기본 stay · PRERENDER_PROTECTED_SLUGS 로 덮어쓴다). "payload 가 없으면 안 굽는다" 는 보호가 못 된다 — payload 가 생기는 순간 덮인다. 실측(2026-09-15): 누가 빌더에서 슬러그 stay 로 발행해 payloads/stay.json 이 생기자 프리렌더가 /s/stay 를 그 payload 로 구워 목업을 통째로 날렸다(캐치프레이즈 100개·미니 플레이어·날씨 문구·주입분 전부). 그 payload 는 solution/site/payloads-mockup-hold/ 로 옮긴다 — 지우면 재발행 때 또 온다.

• ★ 굽기는 네트워크를 탄다 — 사진을 내려받는다 (prerender.ts mirrorMedia). payload.media[].url 이 남의 도메인이면 out/s/<slug>/img/<주소해시>.<확장자> 로 받아 놓고 payload 의 주소를 우리 오리진 절대주소로 바꾼 뒤에 굽는다. 이유는 캔버스다 — 수집처(*.pstatic.net · tong.visitkorea.or.kr)가 Access-Control-Allow-Origin 을 안 줘서 그 사진을 캔버스에 그리면 오염돼 toBlob 이 막히고, 엽서 쓰기의 저장·공유가 모든 발행 사이트에서 죽어 있었다(실측 2026-09-15). 클라이언트에서는 못 넘는다. → 못 받은 사진은 원래 주소를 그대로 쓴다(사진이 사라지는 것보다 낫다). 로그에 한 줄 남는다. → 주소가 그대로면 파일명도 그대로라 다시 구워도 내려받지 않는다. 처음 한 번만 느리다. → ★ 이미 나가 있는 사이트는 그대로 둔다. 새 기능은 사장님이 다시 발행할 때 들어간다 (아래 항목). 그 사이를 메우는 건 중계다 — /v1/image/relay?url=… (backend/router/v1/media/relay.py). 캔버스가 CORS 로 사진을 못 받으면 같은 오리진의 이 주소로 한 번 더 받아 본다(site/src/lib/postcard-canvas.ts loadImage). 열린 프록시가 아니다 — https · 호스트 allowlist · 이미지 타입 · 8MB · 리다이렉트 후 호스트 재검사. 호스트를 늘릴 때는 "우리가 이미 그 사진을 화면에 싣고 있는가" 를 먼저 본다. → originUrl · sourceType 은 손대지 않는다 — 재게시 권리(DECISIONS 1-2)가 "불가" 로 결론 나면 sourceType = CRAWL 을 빼는 그 대응이 그대로 먹어야 한다.

• ★★ 배포해도 기존 사이트를 다시 굽지 않는다 — 자산 주소만 갈아 끼운다. (2026-09-15 대표 지시: "전체 재굽기 할 필요가 없어, 사장님이 재발행하면 끝인데 / css js만 안 깨지게 하란 말이야") 예전에는 solution-prerender 가 뜰 때마다 payload 를 전부 다시 구웠다. 그러면 렌더러를 한 줄 고칠 때마다 이미 나가 있는 사이트의 HTML 이 통째로 바뀐다 — 사장님은 발행한 적이 없는데 내용이 달라지고, 구글이 다시 읽어 가는 값도 달라진다. 지금 기동이 하는 일은 prerender.js --refresh-assets 하나다 (watch-payloads.mjs refreshAssets → prerender.ts refreshBakedAssets): → 구워진 index.html 안의 assets/index-<해시>.css|js 파일명만 새 번들로 바꾼다. 내용·구조·payload 는 손대지 않는다. 접두사(/assets · /sites/assets)도 그대로 둔다. → 한 번도 안 구워진 payload 만 굽는다(볼륨이 비었거나 감시가 꺼진 새 발행). → ★ payload 가 없는 디렉토리는 건드리지 않는다(목업 stay3 · *.old, 그리고 PROTECTED_SLUGS). 손으로 만든 유일본에 최신 번들을 물렸다가 깨지면 되돌릴 수 없다 — 그쪽 번들 교체는 사람이 한다(mockup/README "번들만 갈아 끼운다"). 대상은 --payload-dir 에 <슬러그>.json 이 있는 사이트뿐이다. ★ 그래서 정적 HTML 은 옛 렌더러의 것이고 스크립트는 새 렌더러다. 어긋나면 리액트가 그 자리에서 다시 그리므로 손님 화면은 새것이지만, 크롤러가 읽는 HTML 은 옛것이다. 둘을 맞추는 방법은 재발행뿐이고 그건 사장님이 누른다. 급하면 republish_all.py 지만 먼저 묻는다 — 전 사이트의 발행일이 한꺼번에 움직이는 일이다.

• 번들 파일명은 콘텐츠 해시다. HTML 은 /assets/index-DvNTmLhy.css 를 루트 절대경로로 가리킨다. 경로는 프리렌더가 dist/client/.vite/manifest.json 에서 읽어 박는다 (prerender.ts:160). 렌더러 CSS 를 고치면 이름이 바뀐다.

• 옛 해시 자산은 30일 남는다 (prerender.ts ASSET_RETENTION_DAYS). 예전에는 빌드마다 out/assets 를 통째로 갈아서, 새 번들로 일부만 구우면 나머지 사이트가 CSS 404 였다. 지금은 남긴다 — 구글은 HTML 을 가져간 뒤 렌더를 나중에 돌리므로, 그 사이 자산이 사라지면 스타일 없는 페이지를 렌더한 것으로 기록된다. 보관 근거는 out/assets/.builds.json 대장이고 파일 mtime 이 아니다. → 재굽기는 여전히 필요하지만 급하지 않다. 디자인이 반영 안 될 뿐, 깨지지는 않는다.

• ★ 대장(out/assets/.builds.json)에 없는 자산은 지우지 않는다 — "지금 처음 본 것" 으로 치고 보관 기간을 새로 준다(pruneAssets). 이 규칙을 깨면 운영 사이트가 즉시 끊긴다. 실제로 그랬다(2026-09-07): 대장은 이 기능과 함께 생겼으므로 배포 직후 첫 실행에는 대장이 없고, 그때 디스크에 있던 기존 자산이 전부 "대장에 없음" 으로 분류돼 한꺼번에 삭제됐다. 옛 자산을 남기려고 만든 코드가 첫 실행에서 정확히 반대로 동작했다. → 자산을 지우는 코드를 손볼 때는 "기록이 없다"와 "만료됐다"를 절대 같이 묶지 않는다. → 이미 끊겼다면 복구는 docker compose restart solution-prerender — 기동이 공용 자산을 다시 깔고 구워진 HTML 의 자산 주소를 맞춘다(전체 재굽기가 아니다, 위 ★★ 항목).

• ★ 사이트를 굽는 컨테이너는 solution-prerender 다. solution-frontend 는 개발용이라 운영에서는 아예 뜨지 않는다(docker-compose.yml profiles: ["dev"]). 이름이 비슷해서 restart solution-frontend 를 치면 아무 일도 안 일어나는데 명령은 성공한다 — 재굽기를 했다고 믿고 넘어가게 된다. 실제로 그렇게 복구가 한 번 헛돌았다(2026-09-07).

• ★ 프론트(solution/site)를 고쳐도 기존 사이트의 내용은 안 바뀐다. 기동은 자산 주소만 맞춘다(위 ★★ 항목) — 새 렌더러로 다시 그려지는 건 그 사장님이 다시 발행할 때다. Azure 를 쓰는 경우엔 한 겹 더 있다: azure_static.publish(slug) 는 공용 자산 + s/<slug> 만 올린다 — 다른 사이트의 블롭은 그대로다. → 전 사이트를 한꺼번에 새 렌더러로 맞춰야 할 일이 생기면 docker compose restart solution-prerender 후 python scripts/republish_all.py 인데, 먼저 묻는다(발행일이 전부 움직인다).

• 발행 호스트는 두 곳에 있고 같아야 한다. 백엔드 SITE_PUBLIC_HOST(기본 web4ai.o2osolution.ai, site_payload.py) ↔ 프론트 VITE_PUBLISH_HOST. canonical·og:url·sitemap·IndexNow 가 전부 이 값을 쓴다. 그리고 origin 은 payload JSON 에 구워진다 — 호스트를 바꾸면 프리렌더 재실행만으로는 안 되고 백엔드에서 재발행해 payload 를 다시 만들어야 한다.

• GOOGLE_CLIENT_ID 도 두 곳에 있고 같아야 한다. 백엔드(GOOGLE_CLIENT_ID) ↔ 프론트 (VITE_GOOGLE_CLIENT_ID, compose 가 루트 값을 흘려보낸다). 백엔드는 이 값으로 구글 토큰의 수신자(aud)를 대조한다 — 이 검사가 유일하게 "남의 앱에 발급된 진짜 구글 토큰"을 막는다. 어긋나면 버튼은 뜨는데 로그인만 계속 거부된다. 비우면 구글 로그인만 꺼진다(서버는 뜬다).

• ★ VITE_AUTO_LOGIN_ID·PW 는 운영 진입점(solution-site, nginx/Dockerfile)에 절대 넘기지 않는다. 예전엔 docker-compose.yml 의 solution-site build args 에 이 값이 실제로 흘러가고 있었다 — .env 에 채운 채로 배포하면 자동 로그인 계정이 사장님이 여는 운영 번들에 그대로 구워졌다(누구나 JS 에서 읽을 수 있다). 지금은 그 build arg 자체가 없다. lib/autoSession.ts 의 import.meta.env.DEV 가드가 둘째 안전판이다 — 실수로 값이 다시 넘어와도 운영 빌드(vite build)에서는 죽은 코드로 접혀 번들에서 빠진다. 자동 로그인이 필요하면 solution-frontend(--profile dev, vite dev)만 쓴다.

• 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 다.

• ★ 발행본 주소는 끝 슬래시가 없다 — 목록 페이지 /s 도 마찬가지다. canonical · 사이트맵 · llms.txt · 서치콘솔 색인 요청이 전부 이 형태여야 한다. 어긋나면 구글이 제출분을 "대체 페이지(적절한 표준 태그가 있음)" 로 분류한다 — 색인은 되는데 제출 URL 은 0건으로 보이는, 눈으로 원인을 못 찾는 종류다. → nginx 는 location = /s 로 목록 index.html 을 직접 주고 /s/ 는 거기로 301 한다. 이 블록을 지우면 /s 가 맨 아래 location / 로 떨어져 빌더 SPA 셸이 200 으로 나간다 — 404 도 목록도 아닌 세 번째 페이지가 크롤러에 잡힌다(실측 2026-09-08). → 리다이렉트는 absolute_redirect off 로 상대 Location 이어야 한다. TLS 를 앞단 Apache 가 끊어서 nginx 의 $scheme 는 늘 http 다 — 절대 URL 로 내면 https→http 다.

• ★ SNS 게재 승인은 GET 으로 처리하지 않는다. 메신저의 링크 미리보기 생성기·백신·브라우저 프리페치가 사람이 누르기 전에 그 URL 을 연다. GET 승인이면 사장님이 안 눌렀는데 글이 올라가고 로그에는 "승인됨" 으로 남는다 — 눈으로 원인을 못 찾는 종류다. 링크는 확인 화면을 열 뿐이고 게시는 그 화면의 POST 다(DECISIONS 8-3).

• ★ SNS 게재는 sites.domain 이 확정된 사이트에만 허용한다. domain 이 비면 발행 슬러그가 상호명에서 파생되고(_publish_target), 상호를 고치면 주소가 통째로 바뀐다. SITE_SLUG_LOCKED 는 domain 변경만 막으므로 여기엔 안 걸린다 — 이미 올라간 글의 링크는 404 가 되고 그 글은 수정할 수 없다.

• ★ ORM 의 server_default=text("'…'") 에 쉼표를 딸려 보내지 않는다. text("'[]',") 는 DEFAULT '[]', NOT NULL 로 나가 CREATE TABLE 이 통째로 실패한다. 운영 DB 는 init.sql 로 만들어져 안 드러나고, ORM 이 스키마를 만드는 테스트 DB 에서만 터진다(실측 2026-09-14).

SNS에서 조용히 틀리는 것 (2026-09-14)

• domain NULL은 임시 주소다. SNS는 PUBLISHED + current_version_id + 확정 domain을 모두 요구한다.
• 승인 GET은 프리페치가 연다. 상태 전이는 POST의 nonce 해시 + PENDING CAS로만 한다.
• Threads는 X의 offline.access/회전 refresh_token 계약을 쓰지 않는다. 장기 access token을 갱신한다.
• 토큰 갱신 저장 실패는 재연결. POSTING 중단·응답 유실은 UNKNOWN이며 자동 재게시 금지.
• 초기 SOCIAL_POSTING_ENABLED=0. SOCIAL.md의 실제 게시·해지 안내 페이지 전제를 확인한 뒤 연다.

에이전트에서 조용히 틀리는 것 (2026-09-21)

• 도구가 crud 를 직접 부르면 게이트가 통째로 뚫린다 — 업종 스키마 검증·출처 필수·정정본 보호가 사라지는데 아무 증상이 없다(값은 들어가고 빌드도 성공한다). 도구는 반드시 services/* 를 통과한다. collect_service.store_facts 가 크롤러에 걸어 둔 그 문이다.
• 카카오 채널 발화자는 우리 user_id 가 아니다 — 채널 단위 익명 키다. owner_kakao_links 매핑 없이 발화자를 믿으면 채널 진입점만 소유자 범위 밖에 놓인다.
• 코드 소비 경로를 웹훅 서명 검증보다 먼저 열지 않는다 — 누구나 6자리를 대입해 남의 계정에 자기 카톡을 붙일 수 있다. 지금 redeem() 이 라우터에 없는 이유다(AGENT.md).

코드 규약

• 미결 사항은 코드로 풀지 않는다. DECISIONS.md 1절이 보류한 것은 플래그·어댑터로 격리해 두고, 결론이 나면 날짜와 함께 결론을 적고 격리를 제거한다.
• 수집 어댑터를 추가하기 전에 DECISIONS.md 1-1 과 DATA_SOURCE_RESEARCH.md를 읽는다. 봇 탐지 우회는 결론과 무관하게 영구 금지다.
• 주석은 "왜"를 적는다. 이 레포의 기존 주석이 그 톤이다 — 실측값, 밟았던 함정, 안 한 이유. 코드를 읽으면 알 수 있는 "무엇"은 쓰지 않는다.
• 문서는 코드와 같은 커밋에서 고친다. 동작을 바꿨는데 문서를 안 고쳤으면 미완이다.

레포 구조

solution/    사장님 — backend · frontend(빌더) · site(발행물) · shared(계약)
admin/       우리 — backend(진입점만, :9801) · frontend(운영 화면)

최상단은 프로젝트 단위다(o2o-negosium 과 같은 규약). frontend/ backend/ 를 최상단 묶음 폴더로 쓰지 않는다. 근거와 경계는 ARCHITECTURE.md 4절.

★ 의존 방향은 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절).

실행

docker compose up -d               # api :9800 · 워커 · 프리렌더 · nginx :80
docker compose --profile dev up -d # + 사장님 앱 HMR :3000 (로컬 전용)
docker compose logs -f solution-worker

★ 운영에는 dev 서버를 띄우지 않는다. docker compose up -d 가 올리는 nginx(:80)가 사장님 앱(구운 번들) · 발행 사이트 · API 를 한 오리진으로 준다. solution-frontend (Vite dev, :3000)는 --profile dev 로만 뜨고 HMR 이 필요할 때만 쓴다.

• 한 오리진: http://localhost/ 앱 · http://localhost/s/<slug> 발행 사이트 · /v1/... API
• 내부 운영 :3002(API :9801, 로컬호스트에만 열림) — --profile admin
• ★ VITE_* 는 번들에 구워진다. 주소를 바꾸면 .env 만 고쳐선 안 되고 ./deploy.sh solution-site 로 다시 구워야 한다
• 클론 직후 1회: cp .env.example .env · cp nginx/site.conf.example nginx/site.conf (후자를 빼먹으면 Docker 가 그 자리에 디렉토리를 만들어 nginx 가 설정 없이 뜬다)
• DB 는 compose 밖이다 (호스트 PostgreSQL, host.docker.internal). 스키마는 postgres-init/init-data/init.sql(새 DB 전체 DDL) + postgres-init/migrations/ (이미 만들어진 DB 보정)다. 둘 다 고친다 — init.sql 만 고치면 서버 DB 에 반영되지 않고, 마이그레이션만 쓰면 새로 세운 DB 에 그 변경이 없다. 적용: scripts/migrate.py
• 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 요금이 나가는 경로를 막아 뒀다

.env 는 어디에 두나

루트 .env 가 단일 출처다. compose 가 이 파일만 읽고(${...} 치환 + env_file), Vite 앱은 구조상 자기 디렉토리의 .env 만 읽는다 — 그래서 나뉘어 있는 것이지 취향이 아니다.

파일	담는 것
.env	DB · JWT · 외부 API 키 · SITE_PUBLIC_HOST · INDEXNOW_KEY
solution/frontend/.env · admin/frontend/.env	그 앱에만 있는 VITE_*. admin 은 API 가 :9801 이다

★ 두 곳에 같은 값을 적지 않는다. 발행 호스트는 compose 가 루트의 SITE_PUBLIC_HOST 를 VITE_PUBLISH_HOST 로 흘려보낸다. 각자 적으면 canonical 과 화면 주소가 조용히 갈라진다.

브랜치 · 커밋

o2o-negosium 과 같은 규약이다.

브랜치는 영문이다. 한국어 브랜치를 올리지 않는다(워크트리 도구가 한글 이름을 자동으로 만드는데 그대로 push 되기 쉽다).

feature/<주제>  feat/<주제>   새 기능
fix/<주제>                    버그
chore/<주제>                  잡일·설정
docs/<주제>                   문서
design/<주제>                 디자인

커밋 제목: [type] scope: 요약 — 부연

[feat] lps/enuri: 오퍼 항목의 판매몰명 식별 — 이미지 CDN 도메인 매핑
[fix] negosium/front: 복기 구멍을 블록 경계에서 끊고 시트 여닫이에 고정
[chore] lps: 구 IQR 이상치 제거 코드 삭제 — 죽은 경로 정리

• type: feat fix chore docs
• scope 는 코드 경로다 — lps/ai · negodata/front · postgres-init. 이 레포라면 solution/backend · site · admin/front · deploy. 여러 곳이면 쉼표(negosium/front,landing)
• 요약은 명사형으로 끝낸다 — "분리" "추가" "갱신". "~한다" 로 쓰지 않는다
• 부연은 — 뒤에 붙인다

본문은 세 덩이다.

[fix] lps: 행(hang)·병목 가드 — 페이지 상호작용 80s 상한 + AI 호출 타임아웃

crash 로 굳은 페이지는 content() 가 CDP 응답을 상한 없이 기다린다 —
실측(gmarket): 무로그 4분 행 → 잡 데드라인 300s 소진 → 사용자 체감 +5분.

- browser.py: goto+렌더대기+content 를 _fetch_page 로 묶어 80s 단일 상한
- ai/keyword: timeout=45s 명시 — SDK 기본(600s)이 잡 데드라인보다 크다

테스트 4건 추가, 전체 270 passed

1. 왜 — 실측값·밟은 함정. 코드를 읽으면 아는 "무엇" 은 쓰지 않는다
2. 변경 항목 — 파일/모듈별 불릿, 항목마다 근거
3. 검증 — tsc·eslint·vite build 통과 · 전체 N passed

한 커밋 = 한 가지 변경. 문서와 그 문서가 설명하는 코드는 같은 커밋에 둔다.

레포 구조

solution/    사장님 — backend · frontend(빌더) · site(발행물) · shared(계약)
admin/       우리 — backend(진입점만, :9801) · frontend(운영 화면)

최상단은 프로젝트 단위다(o2o-negosium 과 같은 규약). frontend/ backend/ 를 최상단 묶음 폴더로 쓰지 않는다. 근거와 경계는 ARCHITECTURE.md 4절.

★ 의존 방향은 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절).

실행

docker compose up -d               # api :9800 · 워커 · 프리렌더 · nginx :80
docker compose --profile dev up -d # + 사장님 앱 HMR :3000 (로컬 전용)
docker compose logs -f solution-worker

★ 운영에는 dev 서버를 띄우지 않는다. docker compose up -d 가 올리는 nginx(:80)가 사장님 앱(구운 번들) · 발행 사이트 · API 를 한 오리진으로 준다. solution-frontend (Vite dev, :3000)는 --profile dev 로만 뜨고 HMR 이 필요할 때만 쓴다.

• 한 오리진: http://localhost/ 앱 · http://localhost/s/<slug> 발행 사이트 · /v1/... API
• 내부 운영 :3002(API :9801, 로컬호스트에만 열림) — --profile admin
• ★ VITE_* 는 번들에 구워진다. 주소를 바꾸면 .env 만 고쳐선 안 되고 ./deploy.sh solution-site 로 다시 구워야 한다
• 클론 직후 1회: cp .env.example .env · cp nginx/site.conf.example nginx/site.conf (후자를 빼먹으면 Docker 가 그 자리에 디렉토리를 만들어 nginx 가 설정 없이 뜬다)
• DB 는 compose 밖이다 (호스트 PostgreSQL, host.docker.internal). 스키마는 postgres-init/init-data/init.sql(새 DB 전체 DDL) + postgres-init/migrations/ (이미 만들어진 DB 보정)다. 둘 다 고친다 — init.sql 만 고치면 서버 DB 에 반영되지 않고, 마이그레이션만 쓰면 새로 세운 DB 에 그 변경이 없다. 적용: scripts/migrate.py
• 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 요금이 나가는 경로를 막아 뒀다

.env 는 어디에 두나

루트 .env 가 단일 출처다. compose 가 이 파일만 읽고(${...} 치환 + env_file), Vite 앱은 구조상 자기 디렉토리의 .env 만 읽는다 — 그래서 나뉘어 있는 것이지 취향이 아니다.

파일	담는 것
.env	DB · JWT · 외부 API 키 · SITE_PUBLIC_HOST · INDEXNOW_KEY
solution/frontend/.env · admin/frontend/.env	그 앱에만 있는 VITE_*. admin 은 API 가 :9801 이다

★ 두 곳에 같은 값을 적지 않는다. 발행 호스트는 compose 가 루트의 SITE_PUBLIC_HOST 를 VITE_PUBLISH_HOST 로 흘려보낸다. 각자 적으면 canonical 과 화면 주소가 조용히 갈라진다.

브랜치 · 커밋

o2o-negosium 과 같은 규약이다.

브랜치는 영문이다. 한국어 브랜치를 올리지 않는다(워크트리 도구가 한글 이름을 자동으로 만들 수 있는데, 그대로 push 하면 안 된다).

feature/<주제>    새 기능        fix/<주제>      버그
chore/<주제>      잡일·설정      docs/<주제>     문서

커밋 메시지는 type(scope): 한국어 설명.

feat(site): 발행 모달에 커스텀 도메인 안내를 붙인다
fix(backend/config): 배포 주소에서 CORS 가 막히던 것
chore(deploy): 포트를 .env 로 뽑는다

• type: feat fix chore docs refactor
• scope: 건드린 자리(backend site admin/front lps postgres-init …). 애매하면 생략한다
• 한 커밋 = 한 가지 변경. 문서와 그 문서가 설명하는 코드는 같은 커밋에 둔다
• 본문에는 왜 를 적는다. 파일 목록은 git 이 이미 안다