한끗 — 트렌드 번역소
AZ와 MZ는 한 끗 차이 | 요즘 유행(밈·신조어·음식·디저트·핫플)을 1분에 번역하고, SNS 맛집이 광고인지 실후기인지 분석해주는 의존성 0·빌드 0·외부 폰트 CDN 0 정적 모바일 웹. 로그인·개인 저장·방문자 후기 없이 공개 콘텐츠 읽기와 공유를 제공합니다.
구조 한눈에
| 파일·경로 | 역할 |
|---|
frontend/ | ★ 배포 대상(Vercel outputDirectory). 브라우저가 받는 정적 파일 전부 |
frontend/index.html | 홈 — 오늘의 한끗·광고일까 진짜일까 미리보기(상위 6개)·요즘 트렌드 미리보기(상위 8개) + 더보기 → 전체 목록 |
frontend/list.html?type=ad|trend | 전체 목록 — 광고분석(10/페이지) 또는 트렌드(12/페이지) + 페이지네이션. cat=음식→맛집, cat=핫플→카페·핫플 별칭 매핑 |
frontend/trend.html?id= | 상세 — 점수(광고의심도/신뢰도)·만족도·판단·추천·출처·공유·같은 카테고리 우선 관련 콘텐츠 |
frontend/dictionary.html | MZ 사전 — 신조어 카드(뜻·예문·예쁜 우리말·출처) 검색 + 최신 신조어/지난 유행어 분리 |
기존 /login.html·/signup.html·/me.html | 파일 삭제. Vercel에서 홈(/)으로 영구 리다이렉트 |
frontend/pulse.html | 트렌드 펄스 — 이번 주 트렌드 / 트렌드 레이더 — 아이디어 펼침·공개 검색 제공, 개인 저장 기능 없음 |
frontend/assets/styles.css·app.js·pulse.js | 로컬 Pretendard 기반 에디토리얼 디자인 시스템 / 화면 설정과 공통 헬퍼(H.*) / 펄스 |
frontend/data/trends.js·pulse.js | 브라우저가 로드하는 생성물 — 직접 편집 금지 |
backend/ | 비공개(배포 안 됨) — 데이터 원본 + 빌드 스크립트 |
backend/data/trends.json·pulse.json | ★ canonical 데이터 원본 (사람·스크립트가 수정) |
youtube-summaries/ | 생성물 — AI Engineer(@aiDotEngineer) 채널 새 영상 한국어 상세 요약 모음(영상별 .md + 인덱스). 배포 대상 아님(frontend/만 Vercel 배포) |
backend/scripts/auto-build.mjs | 자동 게시 엔진 — 출처 자동검증(404/410/관련성) · 근거 대조(서술의 수치·매체·확산 표현이 출처 본문에 없으면 보류) · 중복 제거 · 통과분만 trends.json 반영 · images 필드 자동 주입(og:image) · shops 배열 URL 생존성 검증(죽은 링크 제거) · git push · 실행마다 backend/out/pipeline/runs.jsonl 1줄 + SUMMARY {json} 출력 · 보류 후보는 .pipeline/review-queue.json에 적재 · --none(후보 0건 기록) · --approved(사람 승인분 게시) |
backend/scripts/pipeline-review.mjs | 보류 후보 사람 검수 + 수집 수치 — --list · --approve=<id>(→ auto-build --approved) · --reject=<id> · --stats [--days=14] · --selftest. 결정은 backend/out/pipeline/reviews.jsonl에 기록. 디스코드 "검수"에서 Hermes hangeut-approve가 호출 |
backend/scripts/restage.mjs | 게시된 트렌드의 유행 단계 재판정 — --pick=5 [--json](분석일 오래된 트렌드형, 최근 14일 재판정분 제외) · --apply=<판정.json> [--no-git|--dry](정규 stage만, 근거는 열리는 비SNS URL 1개 이상 · stage·stageMsg·analyzedAt 갱신 · 근거를 src에 추가 · 하락·끝물이면 label/buzz 조정 · 본문은 안 고치고 어긋나면 conflict 보고 → 검증·refresh·git push) · --selftest. 기록 backend/out/pipeline/restage.jsonl. Hermes hangeut-restage(매일 21:05)가 판단하고 이 스크립트가 쓴다 |
backend/scripts/recheck-ad.mjs | 광고/진짜 일일 재확인 — 가장 오래된 신뢰분석 1건의 출처 재검증(ddgs) → 살아있으면 analyzedAt=오늘 갱신(→ 홈 featured 회전). 근거 대조 실패 항목은 회전 없이 '사람 확인 필요' 보고 후 다음 오래된 항목(최대 3건) 시도 · ddgs 차단으로 본문을 못 읽은 출처는 삭제하지 않고 '유지' |
backend/scripts/lib/websearch.mjs | ddgs 래퍼(공용 extract) — 차단(HTTP 430/432/500 등)되면 ddgs가 DDGSException을 stdout에 찍고 0으로 끝나는데, 이를 빈 본문으로 돌려줘 '무관'이 아니라 '차단(못 읽음)'으로 처리. auto-build·recheck-ad·check-source가 이 함수를 같이 쓴다 |
backend/scripts/lib/grounding.mjs | 근거 대조 게이트(결정적·LLM 없음) — 항목 서술(excerpt·pull·verdict·satTxt·article·shops·reasons)의 수치·매체명·확산 표현이 검증 통과 출처 본문에 있는지 문자열 대조. 유래·인물 바꿔치기·의미 오류는 못 잡음. 셀프테스트: node backend/scripts/lib/grounding.mjs |
backend/scripts/youtube-summarize.mjs | AI Engineer 채널 새 영상 → Gemini 한국어 상세 요약 (URL 직수신 — 자막 스크래핑·yt-dlp 불필요) → youtube-summaries/<날짜>-<id>.md 저장. RSS로 신규 감지, 파일 존재로 중복 스킵. --limit·--lowres·--channel 등 옵션 지원 |
backend/scripts/refresh.mjs 등 | 정적 데이터 생성·출처검증·이미지 스크립트 |
tools/hermes-admin/ | 🔧 Hermes 로컬 관리 콘솔 — 크론·설정·실행기록 관리(비배포, 127.0.0.1 전용) |
docs/ | 기획·아키텍처·메뉴별 문서 |
로컬 실행
정적 서버 띄우기
의존성 0, 빌드 0. 사이트 루트는 frontend/:
# 방법 1: 동봉 미니 서버 — 레포 루트에서 실행 → frontend/를 서빙 (포트 8123)
node .claude/static-server.cjs
# 방법 2: Python — frontend/ 안에서 실행
cd frontend && python -m http.server 8000
데이터 갱신 (선택사항)
node backend/scripts/validate-trends.mjs # backend/data/trends.json 스키마 점검(권장)
node backend/scripts/refresh.mjs # backend/data/trends.json → frontend/data/trends.js 재생성 (레포 루트에서)
trends.json을 직접 편집한 후, 이 스크립트를 실행하면 trends.js가 자동 생성됩니다.
trends.js는 직접 편집하지 마세요 — refresh.mjs의 생성물입니다.
Hermes(고구미봇) 로컬 관리 콘솔 (선택사항)
# Windows
tools\hermes-admin\start.bat # 브라우저 자동 오픈 (포트 7766, 토큰 기반 보호)
# 또는
node tools/hermes-admin/server.mjs # 수동 시작
크론 작업·설정·실행 기록을 웹 UI에서 관리. 로컬 전용(127.0.0.1, 비배포). → 콘솔 가이드
데이터 흐름
.pipeline/curate.json (Hermes가 생성한 후보 항목들)
↓
backend/scripts/auto-build.mjs (자동검증 + 썸네일 주입)
· 중복 제거 · 출처 404/410 제거 · 본문 관련성 검증 · 근거 대조(서술의 수치·매체·확산 표현 ↔ 출처 본문, `lib/grounding.mjs`)
· images 필드 빈 항목 → 출처의 og:image 자동 추출·주입 (추가 fetch 없음)
↓
검증 통과분만 → backend/data/trends.json (canonical 원본)
↓
backend/scripts/validate-trends.mjs (스키마 점검; auto-build 내부 또는 수동)
↓
backend/scripts/refresh.mjs (generatedAt 갱신 + 생성)
↓
frontend/data/trends.js (브라우저가 로드 → H.TRENDS)
↓
사이트 frontend/*.html (마스트헤드·피처·리스트 렌더링)
↓
Vercel 자동 배포 (git push 시)
핵심:
- trends.json만 수정. trends.js는 건드리지 말 것.
- auto-build.mjs가 출처 자동검증(게이트) — 죽음·무관·못읽음 출처만 있으면 자동 보류 · 출처가 통과해도 서술이 출처 밖 수치·매체·확산 표현이면 보류(근거 대조)
- 보류 후보는
.pipeline/review-queue.json에 쌓이며, 사람이 디스코드에서 "검수"로 게시 또는 버리기를 정한다(pipeline-review.mjs). 게시도 살아 있는 출처 1개 이상은 필수. 게시·버리기 뒤에는 이유를 버튼(프리셋 또는 직접 입력)으로 남길 수 있고, 그 코멘트는 reviews.jsonl과 learnings.md에 기록된다(--note)
- 게시된 트렌드의 유행 단계(stage)는
restage.mjs가 매일 21:05 5건씩 재판정한다(분석일 오래된 순). 본문은 고치지 않고, 근거 URL 1개 이상이 있을 때만 단계·분석일을 바꾼다
auto-build.mjs는 trends.json을 쓰기 직전에 다시 읽어, 검증하는 사이 restage.mjs·recheck-ad.mjs가 쓴 변경을 덮어쓰지 않는다- 자동 게시 항목의 썸네일은 auto-build.mjs가 출처 og:image로 자동 주입을 시도하며, 공통 카드에서 대표 이미지가 없거나 로드에 실패하면
frontend/assets/defaults/의 카테고리별 기본 일러스트 SVG로 대체하고 기본 이미지임을 표시한다
- 로그인·계정·개인 저장·방문자 후기·보관함·개인 아이디어 저장 구현을 제거했다. localStorage는 테마와 메뉴 접기 설정에만 사용하며, 과거 저장 데이터의 삭제 명령은 실행하지 않는다
H.*는 정적 데이터 조회·화면 렌더링·공유·화면 설정을 위한 공통 헬퍼이며, 인증/개인 저장소 API는 제공하지 않는다- 디자인 톤은
frontend/assets/styles.css와 DESIGN.md의 에디토리얼 원칙을 따른다. 1025px 이상은 하단 접기 버튼이 있는 사이드바, 1024px 이하는 상단 오른쪽 메뉴 버튼과 슬라이드 메뉴를 사용한다
배포
GitHub GO9ME/aztomz(public) → Vercel 정적 배포. vercel.json의 outputDirectory: "frontend"로 frontend/만 서빙.
backend/·youtube-summaries/ 등 생성물은 git 추적되지만 배포되지 않습니다.
자동: 각 push마다 Vercel이 재배포 (약 1~2분).
git add backend/data/trends.json frontend/data/trends.js
git commit -m "..."
git push origin main # → Vercel 자동 재배포
YouTube 요약 자동화:
- 매일 08:00 KST(23:00 UTC 전날) GitHub Actions에서
youtube-summarize.mjs 실행
- RSS로 AI Engineer 채널 새 영상 감지 → 미요약 항목만 Gemini 한국어 요약
- 변경시 자동 커밋·푸시 (리포에만 저장, 배포되지 않음)
블로그 티스토리·네이버 일일 발행:
- 09:00 집필: Windows 스케줄작업
AZ2MZ_Blog_Daily → claude -p /blog-daily 스킬이 4편(티스토리 2+네이버 2, 서로 다른 글 — 2026-10-07 토큰 절약으로 5+5에서 축소) 집필·검증. 로그: backend/out/blog/blog-daily.log
- 12:00·15:00·18:00 발행: Windows 스케줄작업
AZ2MZ_Blog_Queue → node backend/scripts/blog-queue.mjs가 플랫폼별 순차 발행(T→N→T→N…, 글 사이 20~40분 랜덤, 각 플랫폼 하루 5편 한도). 로그: backend/out/blog/blog-queue.log
- 로그인 자동화 없음(기존 철칙) — 전용 프로필(티스토리
backend/.tistory-profile, 네이버 backend/.naver-profile)에 1회 로그인 후 재사용
- 네이버 본문은 붙여넣기 전
naverize()로 가독성 양식(왼쪽 정렬·문장 2개씩 짧은 문단(16px·줄간격 1.8)·문단 사이 빈 줄·밑줄형 인용구 소제목·기울임 없음)으로 바꾼다. 발행 창 위치는 backend/scripts/lib/window.mjs에서 정하며 BLOG_OFFSCREEN=1이면 화면 밖이다. 세부·주의사항은 docs/architecture.md
문서 인덱스
철칙 (신뢰가 제품의 본질)
| 항목 | 규칙 |
|---|
| 신선도 | analyzedAt은 실제로 재분석한 항목만 오늘 날짜로 갱신. 안 한 항목은 그대로 둠 → "갱신 필요" 노출 |
| 출처 | 검색 결과에 실제로 나온 URL만 사용. 추측·단축·조립 금지. auto-build.mjs가 404/410 제거 + 본문 관련성 검증 |
| 점수 | 모든 점수는 추정치이며 확정 판정이 아님. 단정 표현 금지 |
| 신뢰도 ≠ 만족도 | 신뢰도(믿을 만한가) ≠ 만족도(좋은가) — 별개 축으로 표기. 신뢰도 높아도 내용이 '별로'면 neg |
| 신조어 | 출처에 "2024 신조어" 류 표시면 2026.6 기준으로 한물 의심. 재검증 필수. 한물간 신조어는 fresh:false 또는 stage에 '끝물'·'한물' 표시 → 사전 '최신'에서 빠지고 '지난 유행어'로 보관 |
| 게시 정책 | auto-build.mjs가 출처 검증(관련성·생존성) + 근거 대조 후 통과분만 자동 게시. 거짓·무관·404 출처만 있으면 자동 보류, 서술이 출처 밖이면(근거 대조 실패) 보류 |
데이터 스키마
각 trend 항목:
id (string) — 고유 키type (string) — "신뢰분석" | "트렌드"cat (string) — 정규 7분류 중 하나: 디저트 · 맛집 · 카페·핫플 · 신조어 · 노래·챌린지 · 패션 · AI 프롬프트title (string) — 트렌드명collectedAt (YYYY-MM-DD) — 첫 수집일(불변). 사이트 "수집일별" 누적/필터 기준(index.html?date=). 재분석해도 안 바뀜analyzedAt (YYYY-MM-DD) — 분석 날짜(재분석 시 갱신)ad (0~100) — 광고 의심도trust (0~100) — 실제 후기 신뢰도sat (pos|neg|mix|none) — 만족도 (긍정·부정·혼재, none=맛 후기 0건 → 화면 '판단 불가', 혼재 아님)label (string) — 한끗 판정 (예: "SNS 기대치 조절 필요")verdict (string) — 장문 분석src (array) — 출처 [제목, URL] 쌍recs (array) — 추천 목록 [항목, 평가, 점수]reasons (object) — 점수별 근거 {ad, trust, sat} (각 점수를 그렇게 본 이유, 상세페이지에 "왜 이 점수?"로 노출)tags (array) — 해시태그 (분야·지역·키워드, '#' 없이). 상세페이지에서 클릭 → index.html?tag=값으로 같은 태그 필터. 예: ["베이커리","성수","에그타르트"]- 선택:
def (신조어, 한 줄 뜻 — 사전 카드·상세 요약) / example (신조어, 사용 예문 — 상세 '💬 이렇게 써요') / fresh (신조어, false면 한물간 처리 — 사전 '최신'에서 제외, '지난 유행어'로 보관) / pureKorean (신조어, 예쁜 우리말) / prompt (AI 명령어, 길고 디테일하게) / stage (트렌드·신조어의 유행 단계. 신조어의 경우 '끝물'·'한물'·'지남' 등으로 표시하면 신선도 게이트 제외) / article (블로그형 본문 블록) / video (유튜브 임베드, oembed 200(임베드 가능)만) / images (대표 이미지 — 비어있으면 auto-build.mjs가 출처의 og:image 자동 추출·주입) / shops (선택사항, 소문난 맛집 위주 목록 — [{name, rep?, area?, url?, note?}] 배열. rep은 맛집 평판 한 줄(예:"성수 젤라또 맛집", 상세페이지 초록 배지). 디저트·음식 트렌드일 때만 채움. auto-build.mjs가 각 url 생존성 검증(404/410/ERR 제거, 이름·평판·지역·메모는 유지). 최대 6곳. 단순 유통(편의점·마트)은 제외, verdict나 본문에서만 언급.)
개발 환경
- OS: Windows 11 / 셸: PowerShell (Bash 도구도 사용 가능)
- 배포: GitHub
GO9ME/aztomz → Vercel 정적 배포, push 자동 재배포
- Hermes(고구미봇): 트렌드 수집·분석·검증을 돌리는 AI 에이전트(별도
E:\workspace\side_project\hermes). 검증 게이트(최신성·출처·본문 관련성)를 통과한 항목만 자동 게시·배포하고, 미통과 항목은 보류. → 작동 방식 문서
- Hermes 수동 시작:
tools/start-hermes.bat 더블클릭 — 게이트웨이가 떠 있으면 알려주고, 꺼져 있으면 켜서 cron이 자동으로 돌게 한다(로그인 시 자동 시작도 등록돼 있어 평소엔 불필요). 같은 파일이 hermes\start-hermes.bat에도 복사돼 있다.
