initial commit

Change-Id: I80f911b3ee68264927839ebee517d37bc3b71c9b

CLAUDE.md

@@ -0,0 +1,45 @@
+# CLAUDE.md — 이 프로젝트에서 Claude Code가 따라야 할 규약
+
+너는 사내 개발 워크스페이스에서 동작하는 코딩 에이전트다. 이 프로젝트는 **Node(ESM) 앱**이고,
+**로컬 개발/테스트는 워크스페이스에서 직접 `node` 실행**, **배포는 Kubero(Gitea push → buildpack 자동빌드)** 로 한다.
+
+## 절대 규칙
+- **비밀값을 코드/커밋에 넣지 마라.** DB·MinIO 자격증명은 항상 환경변수에서만 읽는다.
+  값은 프로젝트의 `.project-env` 에 있고(프로젝트 폴더 cd 시 셸이 자동 export), 이 파일은 **절대 커밋 금지**(`.gitignore`에 있음). 참고용 예시는 `.project-env.example`.
+- 운영 배포를 직접 하지 마라. 배포는 **git push → Kubero**가 담당한다. 너는 코드만 책임진다.
+- **진입점은 루트의 `index.js` 다(Kubero buildpack 의 run = `node index.js`).** 서버 구현은 `src/server.js`,
+  `index.js` 는 그것을 로드하기만 한다. 진입 파일 구조를 바꾸지 마라(바꾸면 Kubero 배포가 안 뜬다).
+
+## 외부 연결 (프로젝트 `.project-env` 에서 env로 주입됨)
+- **Postgres**: `DATABASE_URL` (직원 전용 schema로 격리, `search_path` 고정). 코드는 `src/db.js`를 통해 접근.
+  DB는 클러스터 내부 OpenEverest(`postgresql-6ox`)의 `appdb` 다.
+- **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` 명령으로 입력. (프로젝트 설정 아님)
+
+## 로컬 개발 워크플로 (컨테이너 빌드 불필요)
+```bash
+# 이 폴더는 new-project 로 만들어졌고 .project-env(DB/S3)가 이미 채워져 있다.
+# 폴더에 들어와 있으면 셸이 .project-env 를 자동 export 한 상태다($DATABASE_URL 등 사용 가능).
+npm install
+npm run dev                 # node --watch 로 핫리로드, http://localhost:3000
+
+# 배포(Kubero)와 "동일한 방식"으로 한 번 돌려보기 — 이게 가장 정확한 사전 검증이다.
+npm start                   # = node index.js (Kubero 의 run 커맨드와 동일)
+```
+- Kubero buildpack 은 Dockerfile 을 쓰지 않는다. 로컬에서 **컨테이너 이미지를 빌드할 필요가 없다.**
+  Kubero 가 결국 `npm install` → `node index.js` 만 하므로, 위 `npm start` 가 통과하면 배포도 거의 그대로 된다.
+
+연결 확인: `npm run db:check`, `npm run minio:check`, 또는 `/db` `/s3` 엔드포인트.
+
+## 배포 워크플로 (Kubero)
+1. Gitea repo에 push (`main` 등 배포 브랜치).
+2. Kubero(https://kubero.bokdev.in)가 이 repo를 받아 **NodeJS buildpack**으로 자동 빌드/배포한다
+   (build=`npm install`, run=`node index.js`, Node 22). Dockerfile 은 쓰지 않는다.
+3. Kubero 앱의 **Environment Variables** 에 `DATABASE_URL`, `S3_*`, `PORT` 를 채운다(로컬 `.project-env`와 같은 키).
+4. 포트는 `3000`(`PORT`). 앱 주소는 `https://<앱이름>.apps.bokdev.in`.
+
+## 코드 규약
+- ESM(`import`/`export`), Node 22+. 외부 연결정보는 반드시 `src/config.js` 한 곳을 거친다.
+- 새 외부 의존성을 추가하면 `package.json`에 반영하고 `npm install`로 lock 갱신.
+- 변경 후에는 `npm run db:check` / `npm run minio:check`로 연결이 살아있는지 스스로 확인하라.