AI용 분할본 · 지도 7단계(운영·개정 — 필요할 때만) — 어느 단계에서든 막히면 이 페이지를 연다 · 이 페이지 전에 읽을 페이지: PART 0 사용법·AI 시작 지침 · 코드 파일은 여기 없다 — 코드 자리의 줄을 따른다(폴더에 책 파일이 하나도 없는 처음이면 부록 A-2 의 curl 한 줄부터)
핵심 규칙 — AI 는 어느 페이지에서든 이것을 지킨다
사용자가 제작 결정서를 명시적으로 승인하기 전에는 코드를 한 줄도 쓰지 않는다. 승인 뒤에는 결정서에 없는 질문·기능을 더하지 않고, 결정서 범위를 끝까지 완주한다.
책 코드 파일은 손으로 옮겨 쓰거나 다시 쓰지 않는다 — node scripts/get-book-code.mjs 가 책 그대로 만든다(첫 실행은 부록 A-2 의 curl 한 줄). AI용 분할본의 코드 자리는 " 경로" 한 줄이다 — 그 파일을 cat 으로 읽는다. 고쳐도 되는 파일은 PART 0 [AI 시작 지침] 5-b 의 목록뿐이다.
매 push 와 완료 보고 전에 node scripts/verify-book-code.mjs 를 실행해 "불일치 0개" 출력을 그대로 보인다.
API 키·비밀번호 값을 채팅·코드·로그·PROGRESS.md 에 적지 않는다. 환경변수는 "이름 + 설정 완료 여부"만 보고받는다.
확인은 AI 가 직접 명령을 실행해 출력으로 증명한다. push ≠ 배포 — 실서버 /api/health 의 commit 이 내 마지막 커밋과 같아지기 전에는 "배포됐다"고 말하지 않는다.
AI 는 지도(https://console.hrum.ai/sajuEbook/ — 같은 지도가 sajuEbook/ai.html 에도 있다)의 단계 순서대로 그 단계의 페이지만 읽는다. 진행 상황은 PROGRESS.md 에 적고, 이어서 할 때는 지도의 다음 단계로 간다 — 승인된 결정서를 다시 묻지 않는다. 전체본 sajuEbook.html 은 사람용이다(링크를 못 여는 도구에 첨부할 때만 AI 가 전체를 읽는다).
로컬에서 화면·상담이 "요청을 처리하지 못했어요"로 실패하고 스모크가 401/502 를 찍음: 먼저 .env.local 에 HRUM_API_KEY 를 넣었는지 확인합니다(1-2). 키가 없으면 로그인과 무관하게 이 증상이 납니다. 키를 넣었는데도 그렇다면 1-3 의 확인 명령을 돌려 봅니다 — 401 이면 대시보드에 보이던 가입 자동 키(값을 받은 적 없는 키)를 쓴 경우가 많으니 새 키를 만듭니다
401 Unauthorized (HRUM): 키 오타·폐기된 키, 또는 값을 받은 적 없는 가입 자동 키(대시보드에 「키 발급됨」만 보이는 경우 — 새 키를 만듭니다, 1-3). 콘솔에서 키 상태를 확인하고 RIDM Apps 앱 상세 → 환경변수에서 HRUM_API_KEY를 다시 저장(저장하면 앱이 자동으로 재시작됩니다 — 재배포 불필요)
401 (우리 앱): 로그인 세션이 없는 것 — 정상 동작입니다. 로그인했는데도 401이면 쿠키 이름을 __Host-session으로 직접 지은 것 — 앱은 평범한 session으로 굽고 읽어야 합니다(부록 A 보안 규칙 6)
CORS 에러: 브라우저에서 api.hrum.ai를 직접 부르는 중 — 프록시(/api/float/...) 경유로 수정
응답이 undefined: data 래핑을 안 깠음. res.data.data가 아니라 json.data (한 겹). 서버의 afterFloat 도 같다 — 답은 call.result.data.interpretation(부록 E-1)
chat만 이상함: chat/completions는 raw OpenAI 형식 — data 래핑 없음
429: 우리 프록시의 회원별 제한(1분 10회) 또는 로그인 실패 제한 — 정상. 한도는 route.ts의 dedup.allow 숫자
409 OUTCOME_UNKNOWN: HRUM 응답이 늦거나 끊겨 과금 여부를 모르는 상태 — 자동 재시도하지 말고 같은 requestId로 다시 조회(7-5). 새 requestId로 다시 부르면 이중 과금이 될 수 있습니다
기억 안 됨: ① 5번째 질문 전인지 확인 — 요약이 5턴마다 만들어져서 1~4번째는 memory.used가 false가 정상 ② endUserId가 세션 회원 id가 아닌 다른 값으로 가고 있는지 프록시 확인
주소에 들어가면 503 "앱이 대기 중입니다": 무료 플랜 앱이 잠든 상태에서 HEAD나 curl 기본 User-Agent로 확인한 것 — 브라우저로 열거나 브라우저 User-Agent를 붙이면 깨어납니다(8-3). 브라우저인데도 계속 503이면 앱 카드 상태(시작 실패·정지)를 확인
배포 기록이 "실패": 그 줄의 빌드 로그 끝부분을 봅니다. 루트에 Dockerfile 없음·package-lock.json 미커밋·next build 타입 에러가 대부분(8-2 표)
빌드 실패 secrets found in the repository: 배포 기록에 나온 파일·줄을 봅니다. .env.example에 예시 비밀번호가 든 DB 주소를 적은 경우가 대부분 — 값을 비우고 push(8-2 표)
push 했는데 실서버가 그대로: push 는 배포가 아닙니다. /api/health 의 commit 이 옛 커밋이면 새 빌드가 실패했거나 아직 "자동 승인 중" — 콘솔 → 내 앱 → 배포 기록에서 그 커밋 줄의 상태·사유를 봅니다(8-2 표)
상담 말투가 결정과 다름(반말로 했는데 존댓말 등): lib/persona-list.ts 의 tone 을 확인(casual=반말). 화면이 책의 components/Chat.tsx 를 안 쓰고 자작 상담 화면을 붙였으면 캐릭터 key 가 안 가서 기본값으로 답합니다 — node scripts/verify-book-code.mjs 가 "화면이 책 컴포넌트를 안 씀"으로 알려 줍니다
"시작 실패": 10초 안에 /가 응답 안 함, 읽기 전용 파일시스템에 쓰기 시도(/tmp만 가능), 메모리 초과. 로컬에서 docker run --read-only --tmpfs /tmp -p 3000:3000 이미지로 재현
API 500 + DATABASE_URL is not set: 로컬 실행에서 .env.local에 로컬 Postgres 주소를 안 넣은 것. RIDM Apps에서는 플랫폼이 자동으로 넣어 주니 직접 넣지 마세요(예약 이름이라 저장도 거부됩니다)
DB 에러 too many clients: 앱 DB 연결은 3개까지 — lib/db.ts의 Pool max: 2를 늘리지 말고, 요청마다 새 Pool을 만들고 있지 않은지 확인
DB 쓰기가 갑자기 전부 실패: 플랜 DB 용량을 넘긴 채 24시간이 지나(150% 초과면 즉시) 읽기 전용이 된 것 — 필요 없는 행을 지우거나 플랜을 올립니다(부록 E-3)
상담 호출만 400 "property timezone should not exist": 만세력용 body를 상담에 재사용한 것 — lib/api.ts의 readingBody()로 다시 만들면 해결(5-1·6-2)
만세력 화면이 시간 미상에서 하얗게 죽거나 undefined가 보임: 응답 필드를 직접 읽은 것 — 5-1의 normalizeManseryeok을 거치지 않았거나 ManseryeokDetail 밖에서 data.strength 같은 값을 읽음. tests/manseryeok.test.tsx의 unknownHour·broken 픽스처로 재현
프록시가 404 "지원하지 않는 요청이에요": 이 앱의 주제(lib/app-topics.ts)에 없는 경로나 AI(only)를 부른 것 — 화면이 다른 주제의 경로를 부르지 않는지 확인합니다. lib/app-topics.ts 는 책이 판마다 정한 값이라 고치지 않습니다
상담이 400 ONLY_REQUIRES_INPUT · ONLY_DOMAIN_UNAVAILABLE: 주제 상담에 그 주제의 입력이 빠졌거나(자미두수 = 시각 있는 원국, 타로 = tarot, 꿈해몽 = dream) 계정에서 그 기능이 꺼진 것 — HRUM 은 사주 풀이로 대신 답하지 않습니다. 콘솔 요금표에서 그 기능이 열려 있는지 확인합니다
자미두수 명반 대신 "태어난 시각을 넣어 주세요"만 보임: 정상입니다 — 원국에 시각이 없으면 명반을 세울 수 없어 부르지 않습니다(부르면 400 birth_time_required). 생년월일 수정에서 시각을 넣으면 바로 뜹니다
상승궁이 안 나옴: 시각과 태어난 도시가 둘 다 있어야 합니다 — 시각 모름이면 정오 기준이라 상승궁 null 이 정상입니다
타로 카드 이미지가 안 보임: imageUrl 이 https 가 아니면 화면이 버립니다(lib/tarot.ts). 이미지는 console.hrum.ai 에서 오므로 next.config.ts 에 이미지 주소 제한을 따로 걸지 않습니다
꿈해몽 결과가 비어 있음: 꿈에서 상징 낱말을 못 찾은 것 — 오류가 아니고 요금도 0원입니다. 장면(무엇이·어디서·어떻게)을 더 구체적으로 적으면 찾습니다
한자가 □로 나옴: 폰트 문제 — 한자는 시스템 폰트가 커버하니 font-family에 serif 폴백 추가
말풍선에 **굵게**·1.·- 기호가 그대로 보임: 답변을 plain text로 넣은 것 — 6-2의 components/AssistantMessage.tsx(react-markdown+remark-gfm)로 교체하고 tests/assistant-message.test.tsx 통과 확인. 정규식으로 별표만 지우는 땜질은 목록·문단이 깨지므로 금지
git에 키가 이미 커밋됨: 즉시 콘솔에서 키 폐기→재발급하고 RIDM Apps 환경변수를 새 키로 교체. 저장소는 새로 파는 게 빠름(새 저장소를 앱에 다시 연결)
AI용 분할본 · 지도 7단계(운영·개정 — 필요할 때만) — 어느 단계에서든 막히면 이 페이지를 연다 · 이 페이지 전에 읽을 페이지: PART 0 사용법·AI 시작 지침 · 코드 파일은 여기 없다 — 코드 자리의 줄을 따른다(폴더에 책 파일이 하나도 없는 처음이면 부록 A-2 의 curl 한 줄부터)