feat: prepare ACS deployment

docs/ACS작업일지.md

@@ -0,0 +1,195 @@
+# ACS 작업일지
+
+## 2026-07-10
+
+### 작업 범위 합의
+- Codex는 `C:\ai-dev\workspace\acs`의 ACS 개선 및 배포 준비를 담당하기로 함.
+- RTGS 프로젝트는 별도 담당자가 작업하므로, 사용자가 명시적으로 요청하지 않는 한 `C:\ai-dev\workspace\rtgs`는 읽기/수정/빌드/배포하지 않기로 함.
+- ACS 관련 설치, 구성, 변경, 배포, 검증 내용은 이 파일에 계속 갱신하기로 함.
+- 서버/저장소 계정 정보와 비밀번호는 일지에 기록하지 않기로 함.
+
+### 로컬 프로젝트 확인
+- ACS 구조 확인:
+  - 백엔드: Spring Boot 3.4.5, Java 21, Maven, JPA, Flyway, PostgreSQL 운영 구성
+  - 프론트엔드: React 19, Vite 6, TypeScript
+  - 배포 구성: `infra/docker-compose.yml`, `infra/docker-compose.tls.yml`, nginx reverse proxy
+- Git 원격 저장소는 아직 등록되어 있지 않음을 확인함.
+- `.git/index.lock` 파일이 남아 있어, 추후 `git add/commit/push` 전 정리가 필요함.
+
+### 배포 전 빌드/테스트 검증
+- 프론트엔드 `npm run build` 성공.
+- 백엔드 최초 테스트에서 운영 Flyway 스키마와 엔티티 불일치 발견:
+  - `visit_requests` 테이블에 `work_name`, `control_*`, `watcher*_ *` 계열 컬럼 누락.
+- 신규 Flyway 마이그레이션 추가:
+  - `backend/src/main/resources/db/migration/V4__visit_request_contact_fields.sql`
+  - 기존 DB에도 적용 가능하도록 `ALTER TABLE ... ADD COLUMN` 방식 사용.
+- 테스트용 H2 호환성을 위해 컬럼 추가 구문을 개별 `ALTER TABLE` 문으로 분리함.
+- `DataSeeder`의 로컬 계정과 테스트 코드 기대 계정 불일치 수정:
+  - 기존 단축 계정 `a/s/h` 유지
+  - 테스트 및 CSV seed와 맞는 `admin/security/host`도 함께 생성하도록 보정
+- 백엔드 `mvn -B -ntp test` 성공:
+  - 9 tests, 0 failures, 0 errors
+- 백엔드 `mvn -B -ntp -DskipTests package` 성공:
+  - `backend/target/acs-0.0.1-SNAPSHOT.jar` 생성 확인
+
+### Docker/Compose 확인
+- 로컬 Docker 설치 확인:
+  - `docker --version` 성공
+  - `docker compose` 플러그인은 없음
+  - `docker-compose --version`은 사용 가능
+- Compose 설정 문법 확인:
+  - `docker-compose --env-file infra/.env.example -f infra/docker-compose.yml config` 성공
+  - `docker-compose --env-file infra/.env.example -f infra/docker-compose.yml -f infra/docker-compose.tls.yml config` 성공
+- 운영 배포 URL을 환경변수로 넣은 HTTPS 구성 확인:
+  - `ACS_PUBLIC_BASE_URL=https://acs.apps.bokdev.in`
+  - `ACS_COOKIE_SECURE=true`
+  - Compose config 정상
+- Docker 이미지 빌드는 로컬 Docker 빌더 문제로 실패:
+  - buildx 플러그인 없음
+  - Docker legacy builder가 Docker API v1.54 build 요청에서 `500 Internal Server Error` 반환
+  - 코드/Compose 문법 문제보다는 로컬 Docker Desktop/빌더 환경 문제로 판단
+
+### 서버/URL 접근성 확인
+- `https://portal.bokdev.in/`:
+  - HTTPS 접근 가능
+  - HTTP 200 OK 확인
+- `https://acs.apps.bokdev.in`:
+  - DNS 해석 가능
+  - 현재 HTTP 503 Service Unavailable 확인
+  - 아직 앱이 정상 배포/기동되지 않은 상태로 판단
+- `https://acs.bokdev.in/0420301/repo`:
+  - 현재 PC 네트워크에서 `acs.bokdev.in` DNS 해석 실패
+  - 저장소 원격 등록/푸시 전 네트워크 또는 도메인 확인 필요
+
+### 저장소 URL/DNS 추가 확인
+- 저장소 후보 URL `https://acs.bokdev.in/0420301/repo` 확인.
+- 로컬 ACS Git remote 확인 결과, 등록된 원격 저장소 없음.
+- `git ls-remote https://acs.bokdev.in/0420301/repo` 실행 결과:
+  - `Could not resolve host: acs.bokdev.in`
+- 현재 PC DNS 서버:
+  - `210.104.132.1`, `210.104.132.2`
+  - `10.168.198.34`, `10.168.198.35`
+- 기본 DNS 및 공개 DNS 확인 결과:
+  - `portal.bokdev.in`은 `27.96.158.129`로 해석됨.
+  - `acs.apps.bokdev.in`은 `27.96.158.129`로 해석됨.
+  - `acs.bokdev.in`은 해석 실패.
+- `bokdev.in` 권한 DNS 서버 확인:
+  - `salvador.ns.porkbun.com`
+  - `fortaleza.ns.porkbun.com`
+  - `curitiba.ns.porkbun.com`
+  - `maceio.ns.porkbun.com`
+- 권한 DNS 서버 `curitiba.ns.porkbun.com`에 직접 질의한 결과:
+  - `portal.bokdev.in` A 레코드 존재: `27.96.158.129`
+  - `acs.apps.bokdev.in` A 레코드 존재: `27.96.158.129`
+  - `acs.bokdev.in` A/CNAME 레코드 없음
+  - `nslookup acs.bokdev.in curitiba.ns.porkbun.com` 결과: `Non-existent domain`
+- 결론:
+  - 현재 저장소 URL의 호스트명 `acs.bokdev.in`은 DNS에 등록되어 있지 않은 것으로 판단.
+  - 저장소 URL이 잘못 전달되었거나, DNS 레코드 생성이 아직 완료되지 않았을 가능성이 큼.
+  - 원격 저장소 등록/푸시 전에 정확한 저장소 URL 재확인이 필요.
+
+### AI DEV 매뉴얼 확인
+- 참조 파일: `docs/AIdev.md`
+- 매뉴얼 기준 주요 서비스:
+  - 포털: `https://portal.bokdev.in`
+  - Coder: `https://coder.bokdev.in`
+  - Gitea: `https://gitea.bokdev.in`
+  - Kubero: `https://kubero.bokdev.in`
+  - Coolify: `https://coolify.bokdev.in`
+- Gitea 저장소 생성/Push 기준:
+  - Gitea의 `playground` 조직에 저장소를 생성.
+  - 저장소 URL 형식은 `https://gitea.bokdev.in/playground/<repo>.git`.
+  - 예: ACS 저장소명이 `acs`라면 `https://gitea.bokdev.in/playground/acs.git`.
+- 배포 기준:
+  - Gitea 저장소 1개가 배포 앱 1개에 대응.
+  - Kubero 또는 Coolify 중 하나를 사용.
+  - Coolify는 Public Repository 방식으로 Gitea 저장소 URL 전체를 입력하고 Dockerfile 빌드를 사용.
+  - Coolify에서 도메인 생성 시 `https://<repo>.apps.bokdev.in` 형식으로 지정되는 것으로 매뉴얼에 기재되어 있음.
+- ACS에 대한 적용 판단:
+  - 기존 후보 `https://acs.bokdev.in/0420301/repo`는 매뉴얼 기준 저장소 URL 형식이 아님.
+  - ACS 저장소 URL은 우선 `https://gitea.bokdev.in/playground/acs.git`로 보는 것이 타당.
+  - 저장소가 아직 없다면 Gitea `playground` 조직에 `acs` repository를 생성해야 함.
+  - 배포 URL `https://acs.apps.bokdev.in`은 Coolify 도메인 형식과 일치.
+
+### 프로젝트 설정 URL 오류 확인
+- 사용자가 포털 프로젝트 수정 화면에서 저장소 URL을 `https://acs.bokdev.in/0420301/repo`로 임의 입력한 사실 확인.
+- 해당 값은 Gitea 저장소 URL이 아니므로 수정 필요.
+- 후보 저장소 페이지 확인:
+  - `https://gitea.bokdev.in/playground/acs`: Not found
+  - `https://gitea.bokdev.in/playground/ACS`: Not found
+  - `https://gitea.bokdev.in/0420301/acs`: Not found
+  - `https://gitea.bokdev.in/0420301/ACS`: Not found
+- 결론:
+  - 현재 ACS Gitea 저장소는 아직 생성되지 않았거나, 비공개/다른 이름으로 생성된 상태일 수 있음.
+  - 매뉴얼 기준으로는 `playground` 조직에 `acs` 저장소를 새로 만들고, 프로젝트 저장소 URL을 `https://gitea.bokdev.in/playground/acs.git`로 설정하는 것이 우선 추천.
+  - 배포 URL `https://acs.apps.bokdev.in`은 유지 가능.
+
+### Gitea Credential Helper 및 저장소 재확인
+- Git 접근 중 Windows `CredentialHelperSelector` 팝업 발생.
+- 권장값인 `manager` 선택 완료.
+- 이후 `git ls-remote https://gitea.bokdev.in/playground/acs.git` 재시도 시 인증 대기 상태로 타임아웃됨.
+- 비대화식 확인:
+  - `GIT_TERMINAL_PROMPT=0`
+  - `git -c credential.helper= ls-remote https://gitea.bokdev.in/playground/acs.git`
+  - 결과: `could not read Username for 'https://gitea.bokdev.in': terminal prompts disabled`
+- Gitea API 비교 확인:
+  - `https://gitea.bokdev.in/api/v1/repos/playground/MANUAL`: 200 OK
+  - `https://gitea.bokdev.in/api/v1/repos/playground/acs`: `The target couldn't be found`
+- 판단:
+  - Gitea 서버와 API는 정상 접근 가능.
+  - `playground/acs` 저장소는 비로그인/API 기준으로 존재하지 않거나 private/권한 미승인 상태.
+  - 포털 프로젝트의 저장소 URL 수정만으로 Gitea 저장소가 자동 생성되는 것은 아니므로, Gitea에서 `playground/acs` repository 생성 여부를 별도로 확인해야 함.
+
+### Gitea ACS 저장소 생성 및 원격 등록
+- 사용자가 Gitea에서 ACS 저장소 생성 완료.
+- 생성된 저장소 확인:
+  - 웹 URL: `https://gitea.bokdev.in/0420301/acs`
+  - Git URL: `https://gitea.bokdev.in/0420301/acs.git`
+  - `playground/acs`가 아니라 개인 네임스페이스 `0420301/acs`로 생성됨.
+- 빈 저장소 상태 확인:
+  - `git ls-remote https://gitea.bokdev.in/0420301/acs.git` 결과가 비어 있으나 exit code 0으로 정상.
+- 이전 타임아웃된 Gitea 확인용 Git 프로세스와 stale lock 파일 정리:
+  - `.git/config.lock`
+  - `.git/index.lock`
+- 로컬 ACS Git remote 등록 완료:
+  - `origin https://gitea.bokdev.in/0420301/acs.git`
+- 남은 사항:
+  - push 전 커밋 대상 정리 필요.
+  - 로그 파일(`backend/backend-run.log`, `frontend/frontend-dev.log`)과 백업 파일(`docs/ACS작업일지.md.bak`)은 커밋 제외 권장.
+  - 작업트리 변경분 검토 후 최초 commit/push 진행 필요.
+
+### 인증서 확인
+- `infra/certs/fullchain.pem`, `infra/certs/privkey.pem` 존재 확인.
+- 현재 인증서는 `CN=localhost`, SAN도 `localhost`, `127.0.0.1`용임.
+- 운영 도메인 `acs.apps.bokdev.in`용 인증서가 아니므로 실제 HTTPS 운영 배포에는 부적합.
+- 운영 배포 전 포털/플랫폼 인증서 자동 제공 여부 또는 도메인 인증서 교체 필요.
+
+### 배포 정책 추천
+- 권장 흐름:
+  - 로컬 개발
+  - Git commit/push
+  - 서버 개발환경 배포
+  - 서버 개발환경 검증
+  - 운영 배포 승인
+  - 서버 운영환경 배포
+- 서버에서 직접 코드를 수정하며 개발하는 방식은 비추천.
+- 서버 개발환경도 Git으로 받은 검증 대상 환경으로 운영하고, 운영환경에는 검증된 커밋/태그만 배포하는 정책을 권장.
+- 권장 브랜치/환경:
+  - `dev` 또는 `develop`: 서버 개발환경 배포
+  - `main`: 운영 배포 가능 브랜치
+  - 운영 배포 시 태그 사용 예: `acs-v0.1.0`
+- DB 변경은 Flyway migration으로만 반영하는 정책 유지.
+
+### 남은 작업
+- `.git/index.lock` 정리 후 Git 작업 가능 상태 확인.
+- ACS 원격 저장소 URL/DNS 문제 확인.
+- 원격 저장소 등록 및 최초 push 여부 결정.
+- 서버 개발환경과 운영환경을 포털에서 분리 구성할 수 있는지 확인.
+- 운영 도메인 인증서 처리 방식 확인.
+- 로컬 Docker buildx 또는 Docker Desktop 빌더 문제 해결.
+- 실제 배포 전 운영 `.env` 값 확정:
+  - `POSTGRES_PASSWORD`
+  - `ACS_PUBLIC_BASE_URL`
+  - `ACS_COOKIE_SECURE`
+  - `ACS_SMS_PROVIDER`
+  - SMTP 또는 사내 메시지 API 설정

docs/AIdev.md

@@ -0,0 +1,349 @@
+# AI DEV 개발·배포 매뉴얼 (개발자용)
+
+행번 계정 하나로 **Coder에서 개발**하고, **Gitea에 push**, **Kubero 또는 Coolify로 배포**합니다.
+(배포 도구는 Kubero·Coolify 중 검토 중입니다. [9번](#9-배포-gitea--kubero--coolify)에 두 방법을 모두 정리해 두었습니다.)
+DB(PostgreSQL)·파일저장소(MinIO)·AI(LiteLLM - key 제외)는 워크스페이스에 미리 연결되어 있습니다.
+
+<!-- 이미지: `![설명](images/파일명.png)` 자리에 맞춰 캡처 후 images/ 에 추가 -->
+
+## 목차
+
+**최초 1회**
+[1. 로그인](#1-로그인) → [2. 워크스페이스 만들기](#2-워크스페이스-만들기-최초-1회) → [3. VS Code 열기](#3-vs-code-열기) → [5. AI 키 등록](#5-ai-키-등록-최초-1회)
+
+**앱마다**
+[6. 새 프로젝트 시작](#6-새-프로젝트-시작) → [7. 개발](#7-개발) → [8. 로컬 실행·확인](#8-로컬-실행확인) → [9. 배포](#9-배포-gitea--kubero--coolify)
+
+```
+[최초 1회] 로그인(1) → 워크스페이스 생성(2) → VS Code(3) → AI 키 등록(5)
+[앱마다]   new-project + git init(6) → 개발·커밋(7) → 로컬 확인(8) → 레포 생성·push·배포(Kubero/Coolify)(9)
+```
+
+## 0. 서비스 주소
+
+| 용도 | 주소 |
+|---|---|
+| AI DEV 포털 (시작점) | https://portal.bokdev.in |
+| Coder (개발 워크스페이스) | https://coder.bokdev.in |
+| Gitea (코드 저장소) | https://gitea.bokdev.in |
+| Kubero (배포 · 후보) | https://kubero.bokdev.in |
+| Coolify (배포 · 후보) | https://coolify.bokdev.in |
+| 개발 중 미리보기 | `https://<자동생성>.coder.bokdev.in` |
+| 배포된 앱 | `https://<레포명>.playground.bokdev.in` |
+
+모든 서비스는 **행번 계정(SSO)** 으로 로그인합니다.
+
+코드에서 쓰는 접속정보(DB·S3)는 `.project-env` 파일로 자동 제공됩니다. 직접 입력할 값이 없습니다.
+
+## 1. 로그인
+
+1. https://portal.bokdev.in 접속
+   <!-- TODO: 포털 주소 portal.bokdev.in / backstage.bokdev.in 중 확정 -->
+2. 행번 계정으로 로그인
+   - 아이디: 본인 행번 (예: `2620227`)
+   - 비밀번호: 본인 비밀번호 (초기 비밀번호: `bok1234!!` + `행번 7자리`)
+   ![포털 로그인 화면](images/01-login.png)
+
+3. 이후 Coder·Gitea·Kubero는 추가 로그인 없이 같은 계정으로 열립니다.
+   - Kubero의 경우 `OAuth로 로그인하기`를 눌러 SSO 로그인이 가능합니다.
+   ![포털 로그인 화면](images/portal.bokdev.in_.png)
+
+## 2. Coder 워크스페이스 만들기 (최초 1회)
+
+Coder 워크스페이스 = 본인 전용 개발 컨테이너(VS Code + 개발 도구 일체).
+
+> ⚠️**주의**: 같은 브라우저에 다른 계정으로 Gitea 로그인이 남아 있으면 그 계정으로 연동됩니다.  
+> 승인 전에 Gitea에서 로그아웃했는지 확인하거나, **시크릿 모드**에서 진행합니다.   
+> Coder와 Gitea의 로그인 계정이 일치하지 않는 경우 Workspace 생성 후 계정 불일치로 Push가 되지 않을 수 있습니다.
+
+1. https://coder.bokdev.in → **Workspaces** → **Create Workspace** (템플릿: `aidev`)
+2. 설정값 입력
+   - **Name**: 워크스페이스 이름 (예: `ws-aidev-<행번>`)
+   - **External Authentication**: Gitea — **애플리케이션 승인** 클릭
+   - **CPU / Memory / Disk**: 기본값(2 Core / 4 GiB / 10 GiB) 사용. 추후 변경 가능.
+
+   ![Gitea 계정 연동](images/02-coder-gitea.png)
+
+3. **Create Workspace** 클릭
+4. 최초 빌드는 2~5분 소요. 상태가 **Running**이 되면 완료.
+
+> **주의**: 워크스페이스는 한 번 만들면 계속 사용합니다.
+
+## 3. VS Code 열기
+
+1. 워크스페이스 화면에서 **VS Code Web** 아이콘 클릭
+2. `/home/coder/projects` 폴더가 자동으로 열립니다. ("Yes, I trust the authors" 클릭)
+3. 안에 **`sample`** 폴더가 있습니다. DB·S3 연결이 확인된 참조용 예제이며 **직접 수정하지 않습니다**. [6번](#6-새-프로젝트-시작)에서 복사해 사용합니다.
+   <!-- TODO: 예제 폴더명 sample → connection-validation 변경 반영 여부 확인 (new-project 스크립트 포함) -->
+
+> 작업 파일은 반드시 `/home/coder/projects` 아래에 둡니다. 이 폴더만 워크스페이스 재시작 후에도 보존됩니다.
+
+## 4. 기본 제공 환경
+
+새 워크스페이스에 아래가 설치·연결되어 있습니다.
+
+| 항목 | 내용 |
+|---|---|
+| 개발 도구 | Java(JDK)/Maven, Node 22, Python 3.12, git, psql |
+| 컨테이너 | podman (`docker` 명령도 동일 동작) |
+| DB | 본인 전용 PostgreSQL 스키마 (`$DATABASE_URL`) |
+| VS Code 확장 | Claude Code, Codex |
+| AI CLI | `claude`, `codex` — [5번](#5-ai-키-등록-최초-1회)에서 키 등록 필요 |
+
+## 5. AI 키 등록 (최초 1회)
+
+Claude Code / Codex 는 사내 AI 게이트웨이(LiteLLM)를 사용합니다. 발급받은 본인 virtual key를 한 번만 등록하면 CLI·확장이 모두 공유합니다.
+
+1. 터미널 열기: VS Code 메뉴(좌상단 ☰) → **Terminal → New Terminal**
+2. 아래 명령 실행 후 본인 키(`sk-...`) 입력:
+   ```bash
+   update-litellm-key
+   ```
+   ```
+   LiteLLM virtual key 입력 (sk-...): sk-본인-키
+   키 갱신 완료 (len=25). 현재 터미널에 즉시 적용됨.
+   ```
+3. 확인:
+   ```bash
+   echo $ANTHROPIC_BASE_URL   # https://litellm.bok.or.kr 이면 정상
+   claude
+   ```
+   ```bash
+   echo $OPENAI_BASE_URL      # https://litellm.bok.or.kr/v1 이면 정상
+   codex
+   ```
+
+> **키 등록·변경 후 VS Code(웹)가 응답하지 않을 수 있습니다.**
+> 워크스페이스 화면에서 VS Code 서버를 **Stop → Start** 하여 재시작합니다.
+
+키는 워크스페이스의 `~/.env`에만 저장됩니다. 키를 바꿀 때도 같은 명령을 다시 실행합니다.
+
+기본 모델은 게이트웨이에 맞춰 설정되어 있습니다.
+
+| 도구 | 기본 모델 | 설정 파일 |
+|---|---|---|
+| Claude Code | `claude-opus-4-8` | `~/.claude/settings.json` |
+| Codex | `gpt-5.5` | `~/.codex/config.toml` |
+
+## 6. 새 프로젝트 시작
+
+`sample` 예제를 복사해 시작합니다.
+
+**(1) 터미널에서 프로젝트 생성** — 반드시 `~/projects` 에서 실행:
+```bash
+cd ~/projects
+cd sample && git pull && cd ..   # 예제 최신화
+new-project myapp                # 예제를 ~/projects/myapp 으로 복사 + .project-env 자동 생성
+```
+`myapp`은 예시입니다. 이 이름은 Gitea 레포명으로 설정할 이름과 동일하게 맞추시면 되고, 소문자·숫자·하이픈만 사용합니다.
+
+**(2) git 초기화** — 개발 시작 시점에 합니다. 커밋 이력을 처음부터 관리하기 위함이며, 원격(Gitea) 연결은 배포 단계([9번](#9-배포-gitea--kubero--coolify))에서 합니다:
+```bash
+cd ~/projects/myapp
+git init -b main
+git add .
+git commit -m "init project"
+```
+
+**(3) VS Code로 폴더 열기**: **File → Open Folder…** → `/home/coder/projects/myapp` → OK
+왼쪽에 `myapp` 파일 목록이 보이면 완료. 새 터미널은 이 폴더에서 시작됩니다.
+
+**(4) 라이브러리 설치**:
+```bash
+npm install
+```
+
+> **`.project-env`** 는 이 프로젝트의 설정 파일(DB·S3 접속정보)입니다. 폴더에 들어가면(cd) 자동으로 환경변수에 로드됩니다.
+> <!-- TODO: 예제 .gitignore 에서 .project-env 제외할지 확인 필요 -->
+> LiteLLM 키만 예외로 워크스페이스 공용 `~/.env`([5번](#5-ai-키-등록-최초-1회))에서 관리합니다.
+
+## 7. 개발
+
+- **편집**: 왼쪽 파일 목록에서 파일 선택 → 수정 → Ctrl+S 저장
+- **AI 도구**: 프로젝트 폴더 안 터미널에서 `claude` 또는 `codex` 실행. 폴더 밖에서 실행하면 프로젝트 파일을 읽지 못합니다.
+- **커밋**: 기능 단위로 수시로 커밋합니다. push는 배포 단계에서.
+  ```bash
+  git add . && git commit -m "메시지"
+  ```
+- **DB 접속**:
+  ```bash
+  psql "$DATABASE_URL"        # 프로젝트 폴더에서 실행 (.project-env 로드 필요)
+  ```
+- 코드에서는 `process.env.DATABASE_URL`, `process.env.S3_*` 를 사용합니다.
+- **`CLAUDE.md`**: 프로젝트 규칙·주의사항을 적어두면 Claude Code가 자동으로 읽고 따릅니다. 예제에 기본 파일이 포함되어 있습니다.
+- AI에게는 구체적으로 지시합니다. 예: "로그인 API 만들어줘" 대신 "`src/`에 POST /login 추가, 검증 실패 시 401 반환". 생성된 코드는 [8번](#8-로컬-실행확인)으로 직접 확인 후 커밋합니다.
+
+### 7-1. bkit 플러그인 (선택)
+
+Claude Code에 계획→설계→구현→검증 절차를 더하는 플러그인. 터미널의 `claude` CLI에서만 동작합니다(VS Code 확장 미지원).
+
+설치(최초 1회, `claude` 실행 후 프롬프트에 입력):
+```
+/plugin marketplace add popup-studio-ai/bkit-claude-code
+/plugin install bkit
+```
+
+사용: `/pdca pm <기능이름>` — 기능 하나를 계획부터 검증까지 진행. 세분화 명령은 `/pdca plan` `/pdca design` `/pdca do` `/pdca analyze`.
+
+## 8. 로컬 실행·확인
+
+**(1) 실행**
+```bash
+cd ~/projects/myapp
+npm run dev             # 저장 시 자동 재시작
+```
+`listening on :3000` 이 에러 없이 출력되면 기동 성공.
+실패 시 순서대로 확인: ① `npm install` 했는지 ② 코드 문법 오류 ③ 프로젝트 폴더 밖에서 실행(`.project-env` 미로딩).
+
+**(2) 연결 점검** — 앱을 띄우지 않고 DB·S3 연결만 확인:
+```bash
+npm run db:check        # "DB OK: ..." 이면 정상
+npm run minio:check     # "S3 OK: ..." 이면 정상
+```
+FAIL이면 `.project-env` 값을 확인합니다. 여기서 통과하면 배포 환경에서도 동일하게 동작합니다.
+
+**(3) 브라우저 미리보기** — 워크스페이스는 클러스터 내부라 `localhost:3000`이 PC 브라우저에서 열리지 않습니다. 포트 포워딩을 사용합니다:
+1. VS Code 하단 **PORTS** 탭 → **Forward a Port** → `3000` 입력
+2. 포워딩된 포트의 **Open in Browser** 클릭 → `https://<자동생성>.coder.bokdev.in`
+
+![브라우저 미리보기](images/coder-ports-preview.png)
+
+**(4) 엔드포인트 확인**
+```bash
+curl 127.0.0.1:3000/healthz   # {"ok":true}            앱 기동
+curl 127.0.0.1:3000/db        # {"ok":true,"now":...}   DB 연결
+curl 127.0.0.1:3000/s3        # {"ok":true,"bucket":...} S3 연결
+```
+`"ok": false` 이면 함께 출력되는 `error` 메시지가 원인입니다.
+
+미리보기 URL은 본인 전용이며 워크스페이스를 끄면 사라집니다. 정식 배포는 [9번](#9-배포-gitea--kubero--coolify).
+
+## 9. 배포 (Gitea → Kubero / Coolify)
+
+배포 단위: Gitea `playground` 조직의 레포 1개 = 배포 앱 1개.
+배포 주소: `https://<레포명>.playground.bokdev.in`
+
+배포 도구는 **Kubero**와 **Coolify** 중 하나를 사용합니다.  
+**Gitea 레포 생성([9-1](#9-1-gitea-원격-레포-생성-앱당-1회))과 push([9-2](#9-2-push))는 두 도구 공통**이며, 이후 사용하는 도구에 따라 [9-3A(Kubero)](#9-3a-kubero에-앱-추가-앱당-1회) 또는 [9-3B(Coolify)](#9-3b-coolify에-앱-추가-앱당-1회)를 따릅니다.
+
+| 항목 | Kubero | Coolify |
+|---|---|---|
+| 배포 위치 | `playground` 파이프라인에 앱 추가 | `ai-dev` 팀 → `ai-dev` 프로젝트에 앱 추가 |
+| 코드 수정 반영 | push 후 **수동 재빌드** (자동 빌드 미연동) | push 시 **자동 재빌드·배포** (webhook 설정 시, [9-3B](#9-3b-coolify에-앱-추가-앱당-1회)) |
+| 환경변수 입력 | `.project-env` 업로드 → 자동 파싱 | `.project-env` 값을 붙여넣기 (Developer view) |
+| 빌드 방식 | Dockerfile | Dockerfile |
+
+### 9-1. Gitea 원격 레포 생성 (앱당 1회)
+
+1. https://gitea.bokdev.in/playground → 우측 상단 **`+` → New Repository**  
+   ![새 저장소 만들기](images/make-new-repository.png)
+2. **Owner: `playground`** 로 변경, Repository Name 입력 (예: `myapp`), public 설정
+   ![새 저장소 옵션 설정](images/make-new-repository-2.png)
+3. README / .gitignore / License 는 체크하지 않음(빈 저장소여야 함) → **Create Repository**
+
+### 9-2. push
+
+```bash
+cd ~/projects/myapp
+git remote add origin https://gitea.bokdev.in/playground/myapp.git
+git push -u origin main
+```
+- 최초 push 시 Gitea 승인 화면이 뜨면 **Authorize** 클릭([2번](#2-워크스페이스-만들기-최초-1회)에서 승인했다면 생략됨).
+- 이후 수정 반영: `git add . && git commit -m "..." && git push`
+
+### 9-3A. Kubero에 앱 추가 (앱당 1회)
+
+`playground` pipeline을 사용하시면 되며, 사용자는 그 안에 본인 앱만 추가합니다.
+
+1. https://kubero.bokdev.in 접속
+2. **`playground`** 파이프라인 선택
+3. **Production** 아래의 `+` 버튼을 클릭해 앱을 추가
+4. App Name과 환경 ENVIRONMENT VARIABLES 추가
+   ![Kubero 배포 앱 추가](images/kubero-pipeline.png)  
+   - `.project-env` 파일을 업로드 하면 자동으로 파싱되어 등록됩니다.
+
+> 자동 빌드는 현재 미연동입니다. **코드 수정 후에는 push 하고 Kubero에서 해당 앱의 빌드를 다시 실행합니다.**
+
+### 9-3B. Coolify에 앱 추가 (앱당 1회)
+
+Coolify는 "**push → Dockerfile로 자동 빌드·배포**" 방식입니다. 사용자는 `ai-dev` 프로젝트에 본인 앱만 추가합니다.
+
+1. https://coolify.bokdev.in 접속 → 우측 상단에서 **`aidev`** 팀 선택
+2. 좌측 **`Projects` → `aidev`** (서버·DB가 연결된 프로젝트) → **`+ Add Resource`**  
+   ![Coolify 팀 선택](images/coolify-team.png)
+3. 리소스 종류에서 **`Public Repository`** 선택
+   ![Coolify 리소스 종류 선택](images/coolify-new-resource.png)
+4. **Repository URL**에 **전체 주소**를 입력 후 **`Check Repository`**:
+   `https://gitea.bokdev.in/playground/myapp.git`
+   (`playground/myapp` 처럼 줄여 쓰면 실패합니다.)
+   > **비공개(private) 레포일 때** — `Public Repository` 로도 받을 수 있습니다. URL에 Gitea 토큰을 끼워 넣습니다:
+   > `https://<토큰>@gitea.bokdev.in/playground/myapp.git`
+   > - 토큰 발급: Gitea → 우측 상단 프로필 → **Settings → Applications → Generate New Token**. 이름 지정 후 **`repository` 읽기 권한(Read)** 만 체크 → 생성. 표시되는 토큰은 **이때 한 번만** 보이므로 복사해 둡니다.
+   > - 발급한 토큰을 위 URL의 `<토큰>` 자리에 넣고 **`Check Repository`**. (토큰이 URL·Coolify 설정에 저장되므로 읽기 전용 권한만 부여합니다.)
+5. **Build Pack: `Dockerfile`**, Branch `main`, Port `3000`.
+   ![Coolify 저장소 연결](images/coolify-repo.png)
+6. **Configuration → Domains** 에서 **`Generate Domain`** 클릭 → `https://<레포명>.apps.bokdev.in` 형태로 지정.
+7. **Environment Variables** 에 `.project-env` 값 등록:
+   - **Developer view** 에서 `.project-env` 내용을 그대로 붙여넣으면 일괄 등록됩니다. (`cat ~/projects/myapp/.project-env`)
+   - `DATABASE_URL` 은 `%20`·`%3D` 인코딩까지 **그대로** 넣습니다(빼면 DB 연결이 깨집니다).
+8. **Deploy** 클릭 → **Deployments** 탭에서 빌드 로그 확인. `New container started` / `Deployment finished` 가 보이면 성공.
+
+#### 자동 배포(auto deploy) 설정 (앱당 1회)
+
+Public Repository 방식은 webhook을 걸어야 push가 자동 배포로 이어집니다(Coolify가 push를 스스로 감지하지 못함). Coolify에 별도의 "Auto Deploy" 켜기 단계는 없고, **Webhooks 탭의 URL·Secret을 Gitea에 등록하는 것이 곧 자동 배포 설정**입니다. 앱마다 한 번만 하면 됩니다.
+
+1. **Coolify 앱** → **Configuration → Webhooks** 탭에서, **Gitea** 항목의 **Webhook URL** 과 **Secret** 을 복사합니다. (Secret 칸이 비어 있으면 값을 입력/생성 후 저장)
+   ![Coolify Webhook URL·Secret](images/coolify-webhook.png)
+2. **Gitea 레포** → `https://gitea.bokdev.in/playground/myapp` → **Settings → Webhooks → Add Webhook → Gitea** 에 등록:
+   - **Target URL**: 1번의 Webhook URL
+   - **Secret**: 1번의 Secret
+   - **Content Type**: `application/json`
+   - **Trigger**: Push events, **Active** 체크 → **Add Webhook**
+   ![Gitea Webhook 등록](images/gitea-webhook.png)
+3. Gitea webhook 화면의 **Test Delivery** 를 누르거나 실제로 `git push` → Coolify **Deployments** 에 새 빌드가 자동으로 뜨면 완료.
+
+> push가 배포를 트리거할지는 앱 **Advanced** 탭의 **`Auto Deploy`** 옵션이 결정하며, **기본값이 켜짐**이라 따로 켤 필요는 없습니다(자동 배포를 끄고 싶을 때만 여기서 해제).
+> 설정 후에는 코드를 고쳐 **`git push` 하면 자동으로 다시 빌드·배포**됩니다(Deployments에서 새 빌드 로그 확인). webhook을 걸지 않았다면 앱 화면에서 **Deploy** 를 눌러 수동 배포합니다.
+
+### 9-4. 확인
+
+배포·재시작 직후 약 1~2분은 초기화(코드 다운로드·설치) 시간입니다. 일시적으로 404가 나오는 경우, 잠시 기다린 후 Ctrl + Shift + R로 강력 새로고침 후 확인해주세요.
+
+```bash
+curl https://<레포명>.playground.bokdev.in/healthz   # {"ok":true}
+curl https://<레포명>.playground.bokdev.in/db
+curl https://<레포명>.playground.bokdev.in/s3
+```
+
+![배포된 앱](images/08-deployed-app.png)
+
+문제가 있으면 Kubero에서 해당 앱의 빌드/배포 로그를 확인합니다. 로그에 `listening on :3000` 이 보이면 기동 성공입니다.
+
+
+## FAQ
+
+- Coder Workspace 켜고 끄기
+  - Coder workspace 재기동이 필요한 경우: Coder 워크스페이스 화면에서 **Stop**
+  - 다시 사용: **Start** (VS Code Web 아이콘이 뜰 때까지 대기)
+  - `~/projects` 만 보존됩니다. 그 외 경로의 파일은 사라질 수 있습니다.
+
+- **로그인을 서비스마다 해야 하나요** → 아니요. 행번 계정 SSO 하나로 전부 로그인됩니다.
+- **Coder에서 파일이 사라졌어요** → `~/projects` 밖에 저장한 경우 파일이 유실될 수 있습니다([3번](#3-vs-code-열기)).
+- **AI 도구 401 오류** → `update-litellm-key` 재실행([5번](#5-ai-키-등록-최초-1회)). 키가 `sk-`로 시작하는지 확인.
+- **AI 도구 400 (Invalid model)** → [5번](#5-ai-키-등록-최초-1회) 표의 기본 모델명 사용.
+- **키 등록 후 VS Code가 먹통** → VS Code 서버 Stop → Start([5번](#5-ai-키-등록-최초-1회)).
+- **`$DATABASE_URL` 이 비어 있음** → 프로젝트 폴더 안에서 실행해야 `.project-env` 가 로드됩니다([6번](#6-새-프로젝트-시작)).
+- **`npm run dev` 가 `Cannot find package ...`** → `npm install` 미실행([6번](#6-새-프로젝트-시작)).
+- **push 인증을 물어봄** → Gitea 승인을 아직 안 한 경우. 승인 화면에서 Authorize([9-2](#9-2-push)).
+- **다른 계정으로 push/연동됨** → 브라우저에 남아 있던 Gitea 로그인 세션 때문입니다. Gitea 로그아웃 후 재승인하거나 시크릿 창 사용([2번](#2-워크스페이스-만들기-최초-1회)).
+- **배포 주소가 404** → ① 배포 직후 1~2분 대기 ② `/healthz` 확인 ③ Kubero/Coolify 배포 로그 확인([9-4](#9-4-확인)).
+- **`/healthz` 는 되는데 `/db`·`/s3` 가 500** → 먼저 로컬에서 `npm run db:check` / `minio:check` 통과 확인([8번](#8-로컬-실행확인)). 로컬에서 되면 배포 로그의 에러 메시지 확인. Coolify는 `.project-env` 값(특히 `DATABASE_URL` 의 `%20`/`%3D`)이 그대로인지도 확인.
+- **배포가 옛날 코드** → push 됐는지 먼저 확인. Kubero는 빌드 재실행([9-3A](#9-3a-kubero에-앱-추가-앱당-1회)), Coolify는 push 시 자동 재배포([9-3B](#9-3b-coolify에-앱-추가-앱당-1회)).
+- **DB가 비어 있음** → 정상입니다. 빈 전용 스키마가 제공되며 테이블은 직접 생성합니다.
+- **K8s에 직접 접근하고 싶어요** → 직원은 K8s에 직접 접근하지 않습니다. Coder·Gitea·Kubero로 개발·배포가 완결됩니다.
+
+
+## 문의
+- IT 전략국 클라우드팀 김창록 팀장
+- IT 전략국 정보시스템개발팀 박성록 과장
+- IT 전략국 클라우드팀 이혜민 조사역

docs/issues-and-guidelines.md

@@ -1,7 +1,7 @@
 # ACS 개발 이슈 정리 및 유의사항(규칙)
 
 > 문서 작성일: 2026-07-03
-> 대상: IT센터 출입자관리시스템 (`C:\ai-dev\workspace\access-control-system`)
+> 대상: IT센터 출입자관리시스템 (`C:\ai-dev\workspace\acs`)
 > 목적: 기획·개발·테스트·수정 단계에서 실제로 겪은 이슈를 정리하고, 재발 방지를 위한 **규칙**으로 제안한다.
 > 표기: 각 항목은 **[이슈] → [규칙]** 형태. 규칙 요약은 문서 끝 §6 체크리스트 참조.
 

docs/workflow.md

@@ -1,7 +1,7 @@
 # IT센터 출입자관리시스템(ACS) 워크플로우
 
 > 문서 작성일: 2026-07-03
-> 대상: `C:\ai-dev\workspace\access-control-system` (Spring Boot 3.4.5 / Java 21 · React 19 · Vite 6)
+> 대상: `C:\ai-dev\workspace\acs` (Spring Boot 3.4.5 / Java 21 · React 19 · Vite 6)
 > 목적: 방문자 사전신청 → 승인 → 출입증 발송 → 입·출입 체크 → 재실현황/리포트까지의 전체 업무 흐름 정리
 
 ---

docs/회사의 이메일 API 사용법.txt

@@ -0,0 +1,6 @@
+회사의 이메일 API 사용법
+
+https://helpdesk.dooray.com/share/pages/9wWo-xwiR66BO5LGshgVTg/2937064454837487755
+
+
+https://helpdesk.dooray.com/share/pages/9wWo-xwiR66BO5LGshgVTg/2939991731086319521