Add AI DEV Node deployment foundation

2026-07-13 10:33:21 +09:00
parent 6abcee3727
commit b90bfe35ca
23 changed files with 3978 additions and 0 deletions
--- a/docs/ACS작업일지.md
+++ b/docs/ACS작업일지.md
@@ -322,3 +322,64 @@
  - `ACS_COOKIE_SECURE`
  - `ACS_SMS_PROVIDER`
  - SMTP 또는 사내 메시지 API 설정
+
+## 2026-07-13
+
+### Node.js 전환 착수
+- 사용자가 `C:\ai-dev\workspace\acs - 복사본`에 기존 소스 백업이 있으므로, 원본 `C:\ai-dev\workspace\acs`를 AI DEV 표준 배포 구조로 전환하기로 결정.
+- 목표:
+  - Spring Boot 백엔드 배포 방식에서 Node.js 앱 배포 방식으로 전환.
+  - DB는 자체 PostgreSQL 컨테이너가 아니라 AI DEV `.project-env`의 `DATABASE_URL` 사용.
+  - 기존 React 프론트와 `/api` 계약은 최대한 유지.
+- 추가 문서:
+  - `docs/node-migration-plan.md`
+- 추가된 Node 골격:
+  - 루트 `package.json`, `tsconfig.json`
+  - `server/index.ts`
+  - `server/config/env.ts`
+  - `server/db/pool.ts`
+  - `server/db/migrate.ts`
+  - `server/http/apiResponse.ts`
+  - `server/http/errors.ts`
+  - `server/routes/health.ts`
+  - `server/routes/index.ts`
+- Flyway SQL을 Node migration 구조로 1차 이관:
+  - `migrations/001_init.sql`
+  - `migrations/002_audit_log.sql`
+  - `migrations/003_pass_delivery.sql`
+  - `migrations/004_visit_request_contact_fields.sql`
+- 검증:
+  - `npm install` 완료.
+  - `npm run typecheck` 성공.
+  - `npm audit --omit=dev` 결과 운영 의존성 취약점 0건.
+  - `npm run build` 성공. 단, 로컬 PC 권한 정책상 프론트 `esbuild`는 승인 권한으로 실행 필요.
+  - `node dist/server/index.js` 기동 후 `GET /api/health` 응답 확인.
+  - 정적 React build(`/`) 응답 200 확인.
+- 다음 작업:
+  - Auth/session/role middleware 구현.
+  - PostgreSQL session store 연결.
+  - 사용자 seed 전략 확정.
+  - `/api/auth/login`, `/api/auth/logout`, `/api/auth/me`, `/api/auth/change-password`부터 Spring 기능 parity 구현.
+
+### AIdev.md 배포 가이드 준수 보완
+- `docs/AIdev.md` 기준 ACS 배포 필수 항목을 재점검.
+- 보완 사항:
+  - 루트 `Dockerfile` 추가. AI DEV Coolify/Kubero Dockerfile build pack 기준으로 빌드.
+  - 루트 `.dockerignore` 추가.
+  - Node engine 기준을 `>=22`로 조정.
+  - `/healthz` 추가: `{"ok": true}` 응답.
+  - `/db` 추가: `DATABASE_URL`로 PostgreSQL `SELECT now()` 점검.
+  - `/s3` 추가: ACS는 S3/MinIO 미사용이므로 skip 응답.
+  - `npm run db:check` 추가: `.project-env`/`.env` 로드 후 DB 점검.
+  - `npm run minio:check` 추가: ACS S3 미사용 skip 출력.
+  - `npm run start:deploy` 추가: migration 적용 후 Node 서버 기동.
+  - `CLAUDE.md` 추가: AI DEV 배포 제약과 ACS 전환 규칙 명시.
+- 검증:
+  - `npm run typecheck` 성공.
+  - `npm audit --omit=dev` 운영 의존성 취약점 0건.
+  - `npm run build` 성공. 이 PC에서는 esbuild 실행 정책 때문에 승인 권한 필요.
+  - `GET /healthz` 정상.
+  - `GET /api/health` 정상.
+  - `GET /s3` skip 응답 정상.
+  - `GET /db`는 현재 Windows 로컬에 `DATABASE_URL`이 없어 500과 명확한 오류 메시지를 반환. AI DEV/Coder에서 `.project-env` 로드 후 재검증 필요.
+  - `docker build -t acs-node-guide-check .`는 Docker daemon 미기동(`dockerDesktopLinuxEngine` pipe 없음)으로 실행 전 실패. Docker Desktop 또는 AI DEV/Coder 배포 환경에서 재검증 필요.
--- a/docs/node-migration-plan.md
+++ b/docs/node-migration-plan.md
@@ -0,0 +1,176 @@
+# ACS Node.js Migration Plan
+
+## Goal
+
+Convert ACS from the current Spring Boot backend deployment model to an AI DEV compliant Node.js application.
+
+The target deployment must:
+
+- Run as a Node.js app.
+- Run on port `3000`.
+- Use `process.env.DATABASE_URL` supplied by `.project-env` / AI DEV.
+- Avoid self-managed PostgreSQL containers in the deployment path.
+- Build through the root `Dockerfile`.
+- Preserve the existing React frontend where possible.
+- Preserve the current `/api` contract and response envelope:
+
+```json
+{ "code": 200, "message": "OK", "data": {} }
+```
+
+## Target Architecture
+
+```text
+Node.js app
+├─ /api/*                  Express API
+├─ /assets, /index.html    Static React build from frontend/dist
+├─ PostgreSQL              process.env.DATABASE_URL
+└─ migrations              SQL files adapted from existing Flyway migrations
+```
+
+Recommended stack:
+
+- Runtime: Node.js + TypeScript
+- HTTP: Express
+- Database: `pg`
+- Session: `express-session` with PostgreSQL-backed store
+- Password hashing: `bcrypt`
+- QR generation: `qrcode`
+- Excel import/export: `multer` + `exceljs`
+- Frontend: existing React/Vite app
+
+## Migration Principles
+
+1. Keep the frontend API surface stable.
+2. Reuse the current PostgreSQL schema as much as possible.
+3. Convert by feature slice, not by framework layer.
+4. Keep Spring Boot code available as the behavior reference until parity is verified.
+5. Make AI DEV deployment simple: `npm install`, `npm run build`, `npm start`.
+
+## Feature Migration Order
+
+### Phase 1. Node Foundation
+
+- Add root Node package and TypeScript config.
+- Add `server/` source tree.
+- Add env loader for local `.project-env` compatibility.
+- Add PostgreSQL connection pool using `DATABASE_URL`.
+- Add migration runner using SQL files in `migrations/`.
+- Add health check endpoint: `GET /api/health`.
+- Add AI DEV health check endpoint: `GET /healthz`.
+- Add AI DEV DB check endpoint: `GET /db`.
+- Add S3 status endpoint: `GET /s3` with an explicit skip response because ACS does not use S3/MinIO.
+- Serve `frontend/dist` for non-API routes.
+
+### Phase 2. Auth and Common Infrastructure
+
+- Implement API response helper.
+- Implement error handler.
+- Implement session middleware.
+- Implement role guard middleware.
+- Implement:
+  - `POST /api/auth/login`
+  - `POST /api/auth/logout`
+  - `GET /api/auth/me`
+  - `POST /api/auth/change-password`
+
+### Phase 3. Read-First Business APIs
+
+- `GET /api/zones`
+- `GET /api/visit-requests`
+- `GET /api/visit-requests/pending`
+- `GET /api/visit-requests/:id`
+- `GET /api/stats/summary`
+
+### Phase 4. Visit Request and Approval Workflow
+
+- `POST /api/visit-requests`
+- `POST /api/visit-requests/:id/cancel`
+- `POST /api/approvals/:id/approve`
+- `POST /api/approvals/:id/reject`
+- Generate `qr_token` on approval.
+- Insert approval and audit log records.
+- Preserve "notification failure must not rollback approval" behavior.
+
+### Phase 5. Pass, QR, and Access Control
+
+- `GET /api/passes/:id`
+- `GET /api/passes/:id/qr.png`
+- `GET /api/public/passes/:token`
+- `GET /api/public/passes/:token/qr.png`
+- `POST /api/access/check-in`
+- `POST /api/access/check-out`
+- `GET /api/access/inside`
+- `GET /api/access/today`
+- Public kiosk check-in/out endpoints.
+
+### Phase 6. Admin Features
+
+- Blacklist CRUD.
+- Audit log list.
+- Delivery outbox list and retry.
+- Excel upload for visit requests.
+- XLSX visit report download.
+
+### Phase 7. Deployment Cleanup
+
+- Update README and AI DEV run instructions.
+- Mark Spring Boot backend and Docker Compose deployment as legacy.
+- Keep or remove legacy files after user confirmation.
+- Verify deployment in AI DEV with real `.project-env`.
+
+## API Compatibility Rules
+
+- Keep `/api` prefix.
+- Keep frontend DTO field names in camelCase.
+- Keep HTTP status behavior close to the Spring implementation:
+  - 400 validation error
+  - 401 unauthenticated
+  - 403 forbidden
+  - 404 missing resource
+  - 409 business conflict
+- State-changing APIs must require an authenticated session unless they are public token endpoints.
+- Public pass endpoints must not require login.
+
+## Database Migration Strategy
+
+Existing files:
+
+- `V1__init.sql`
+- `V2__audit_log.sql`
+- `V3__pass_delivery.sql`
+- `V4__visit_request_contact_fields.sql`
+
+Node target:
+
+- Copy SQL into `migrations/001_init.sql` etc.
+- Create a `schema_migrations` table.
+- Apply migrations in filename order.
+- Do not create or manage a PostgreSQL container.
+- Use only `DATABASE_URL`.
+
+## Verification Checklist
+
+- `npm run typecheck`
+- `npm run build`
+- `npm run db:check` in AI DEV/Coder with `.project-env` loaded
+- `npm run minio:check` returns a documented skip because ACS does not use S3
+- `npm start`
+- `GET /healthz`
+- `GET /db`
+- `GET /api/health`
+- Login with seeded admin user.
+- Create visit request.
+- Approve request and confirm QR token.
+- Open public pass page.
+- Check in and check out.
+- Confirm inside/today access views.
+- Confirm blacklist blocks check-in.
+- Download report XLSX.
+
+## Open Decisions
+
+- Exact AI DEV Node version.
+- Whether AI DEV automatically runs `npm run build` or only `npm start`.
+- Whether `.project-env` exists in the repository root or must be sourced by the shell before startup.
+- Whether the production app should seed initial users automatically or require an explicit seed command.