# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

> 이 프로젝트에서 Claude Code가 따라야 할 규약

너는 사내 개발 워크스페이스에서 동작하는 코딩 에이전트다. 이 프로젝트는 **Node(ESM) 앱**이고,
**로컬 개발/테스트는 podman**, **배포는 Coolify(Gitea push → Dockerfile 자동빌드)** 로 한다.

## 절대 규칙
- **비밀값을 코드/커밋에 넣지 마라.** DB·MinIO 자격증명은 항상 환경변수에서만 읽는다.
  값은 프로젝트의 `.project-env` 에 있고(프로젝트 폴더 cd 시 셸이 자동 export), 이 파일은 **절대 커밋 금지**(`.gitignore`에 있음). 참고용 예시는 `.project-env.example`.
- 컨테이너는 `docker` 명령으로 실행해도 되지만 **실제 런타임은 rootless podman**이다(`docker`는 podman 별칭).
- 운영 배포를 직접 하지 마라. 배포는 **git push → Coolify**가 담당한다. 너는 코드/Dockerfile만 책임진다.

## 하네스 가드 (자동 적용 — `.claude/`)
- `.claude/settings.json` + `.claude/hooks/block-secrets.mjs` 가 **PreToolUse 훅**으로 비밀값 파일 접근을
  하드 차단한다: `.project-env`, `.env`, `.env.*`, `~/.env`. Read/Edit/Write 뿐 아니라 **Bash 우회**
  (`cat`/`less`/`grep` 등 명령 문자열)도 막힌다. 키 구조 참고가 필요하면 `.project-env.example` 만 보면 된다.
- 값을 직접 들여다보려 하지 말고, 항상 런타임 환경변수(`$DATABASE_URL`, `$S3_*`)와 `src/config.js` 를 통해서만 쓴다.
- 자주 쓰는 명령(`npm install`, `npm run dev|start|db:check|minio:check`, `podman build|compose`)은 미리 허용돼 있다.

## 아키텍처 한눈에
- 외부 연결정보는 **`src/config.js` 한 곳**에서만 env를 읽는다 → `src/db.js`(pg Pool, `pingDb`),
  `src/s3.js`(S3Client, `pingS3`)가 이를 소비. `src/server.js`(Express)가 `/healthz` `/db` `/s3` 로 노출.
- `scripts/check-db.js` / `check-minio.js` 는 같은 `pingDb`/`pingS3` 를 CLI로 호출하는 얇은 래퍼다.
- DB는 직원 전용 schema가 `search_path` 에 고정돼 격리된다. S3(MinIO)는 `forcePathStyle: true` 필수.

## 외부 연결 (프로젝트 `.project-env` 에서 env로 주입됨)
- **Postgres**: `DATABASE_URL` (직원 전용 schema로 격리, `search_path` 고정). 코드는 `src/db.js`를 통해 접근.
- **MinIO(S3)**: API endpoint `https://minio.bokdev.in` (콘솔 `minioc`가 아님), 버킷 `coolify-user-data`.
  키는 `.project-env`의 `S3_ACCESS_KEY_ID`/`S3_SECRET_ACCESS_KEY`. 코드는 `src/s3.js`를 통해 접근.
- **LiteLLM**: AI 호출은 사내 gateway(`https://litellm.bok.or.kr`) 경유. virtual key는 워크스페이스 전역인 `~/.env`(`LITELLM_KEY`)에서 관리 — `update-litellm-key` 명령으로 입력. (프로젝트 설정 아님)

## 로컬 개발 워크플로 (podman)
```bash
# 이 폴더는 new-project 로 만들어졌고 .project-env(DB/S3)가 이미 채워져 있다.
# 폴더에 들어와 있으면 셸이 .project-env 를 자동 export 한 상태다($DATABASE_URL 등 사용 가능).
npm install
npm run dev                 # node --watch 로 핫리로드, http://localhost:3000

# 컨테이너로 동일하게 돌려보기
podman build -t sample .
podman run --rm -p 3000:3000 --env-file .project-env sample
# 또는
podman compose up --build
```
연결 확인: `npm run db:check`, `npm run minio:check`, 또는 `/db` `/s3` 엔드포인트.

## 배포 워크플로 (Coolify)
1. Gitea repo에 push (`main` 등 배포 브랜치).
2. Coolify가 이 **Dockerfile**로 자동 빌드/배포한다(로컬 podman 빌드와 동일 Dockerfile).
3. Coolify 쪽 Environment Variables 에 `DATABASE_URL`, `S3_*` 를 채운다(로컬 `.project-env`와 같은 키).
4. 포트는 컨테이너 `3000`. Coolify에서 도메인/포트 매핑.

## 코드 규약
- ESM(`import`/`export`), Node 22+. 외부 연결정보는 반드시 `src/config.js` 한 곳을 거친다.
- 새 외부 의존성을 추가하면 `package.json`에 반영하고 `npm install`로 lock 갱신.
- 변경 후에는 `npm run db:check` / `npm run minio:check`로 연결이 살아있는지 스스로 확인하라.