Go to file

hbyang a7fcc14e7d [feat] solution: 인물 사진은 위키미디어에서 · 사진 없는 엽서는 싣지 않는다 시안과 나란히 놓으니 세 가지가 달랐다(2026-09-10 실측). ① 엽서 네 장이 같은 사진이었다 ② 그 네 장이 전부 같은 박물관의 관람안내(주소·휴관일· 운영시간)였다 ③ 인물 열전은 사진이 한 장도 없었다. ★ 인물 사진 — 위키미디어 공식 API (services/external/wikimedia.py) 공공데이터는 관광지 사진을 주지 사람 얼굴을 주지 않는다. 인물 사진이 공개돼 있으면서 재게시 권리를 기계가 읽을 수 있게 알려주는 곳은 사실상 위키백과·위키공용뿐이다. - 크롤링이 아니라 MediaWiki API 다. 페이지를 긁어 파싱하지 않는다 - 권리 판정을 여기서 끝낸다: 위키에는 자유 저작물만 있지 않다 — 인물에는 특히 '공정 이용' (비자유) 파일이 섞이고, 그걸 발행본에 실으면 상업적 이용이라 바로 침해다. PD·CC0·CC BY·CC BY-SA 만 통과시키고, NC·ND·fair use·판정 불가는 버린다 - 통과한 사진에는 출처 표시가 따라붙는다(CC BY 계열의 조건). imageCredit 이 그 값이고 화면에 찍는다 — 표시하지 않을 거면 애초에 쓰지 않는다 - 실측: 10명 중 2명(전봉준·신석정류)만 자유 저작물이 있다. 나머지는 없는 것이 정답이고 그 자리는 렌더러가 이니셜로 세운다. 비슷한 이름의 다른 사람 사진을 붙이는 게 더 나쁘다 ★ 사진이 본체인 종류는 사진 없는 항목을 버린다 (_IMAGE_REQUIRED_KINDS = postcard) 엽서는 앞면 사진이 본체다. 없으면 뒷면만 남아 빈 카드로 보인다. 연표는 다르다 — 활자만으로도 레일에 서므로 버리면 오히려 구멍이 난다. 실측: 12건 중 6건이 빠졌다 ★ 같은 사진을 두 번 쓰지 않는다 네 항목이 같은 시설을 말하면 검색이 같은 사진을 네 번 준다. 두 번째부터는 없는 것으로 친다 ★ 프롬프트(shared 한 벌, export 포함) - postcard: "같은 대상을 두 번 쓰지 않는다" · "운영시간·휴관일·주소·요금은 엽서에 적지 않는다 — 그건 이용 정보지 엽서 문장이 아니다" · place 가 사진을 찾는 열쇠임을 명시 - shared/section-data: PeopleItem·ChronicleItem·PostcardItem 에 imageCredit 추가 - site: SourceLine 이 사진 출처를 함께 찍는다(글 출처가 없어도 사진 출처만으로 한 줄 선다). 엽서는 사진 바로 아래에 따로 찍는다 — 앞면이 사진이라 거기 붙는 게 맞다 실측(전북 군산시) 발행본: 인물 2장 · 엽서 6장(전부 고유) · 연표 3장(전부 고유), 사진 11장 모두 출처 표시. site vitest 51 passed · story·snapshot 23 passed.		2026-09-10 15:19:23 +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	[feat] solution: 인물 사진은 위키미디어에서 · 사진 없는 엽서는 싣지 않는다	2026-09-10 15:19:23 +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 상한을 어디서 강제하나

문서 규칙

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