feat(api): Phase 1.9.1 API 서버 부트스트랩

- Express 5 서버 세팅 (app.ts 팩토리 분리)
- Zod 기반 환경변수 스키마 검증 (config/env.ts) — 누락 시 즉시 종료
- CORS 미들웨어 (개발 환경만 활성화)
- GET /health 엔드포인트
- 글로벌 에러 핸들러 (dev 환경에서 message 노출)
- esModuleInterop 활성화 (Express/cors default import 지원)
- Phase 1.9.2에서 모듈 라우트 마운트 예정 TODO 주석 추가

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: SOIV

apps/api/package.json

@@ -13,10 +13,15 @@
     "lint": "eslint src --ext .ts"
   },
   "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^5.0.3",
     "tsx": "^4.21.0",
     "vitest": "^2.1.9"
   },
   "dependencies": {
-    "dotenv": "^17.3.1"
+    "cors": "^2.8.5",
+    "dotenv": "^17.3.1",
+    "express": "^5.1.0",
+    "zod": "^3.25.28"
   }
 }

apps/api/src/app.ts

@@ -0,0 +1,30 @@
+import express from 'express';
+import cors from 'cors';
+
+import { healthRouter } from './routes/health';
+import { errorHandler } from './middleware/error';
+
+export function createApp() {
+  const app = express();
+
+  // ── Middleware ────────────────────────────────────────────────
+  // 개발: 모든 origin 허용 / 프로덕션: 단일 포트 통합 서빙이므로 CORS 불필요
+  if (process.env['NODE_ENV'] !== 'production') {
+    app.use(cors());
+  }
+
+  app.use(express.json());
+  app.use(express.urlencoded({ extended: true }));
+
+  // ── Core routes ───────────────────────────────────────────────
+  app.use('/health', healthRouter);
+
+  // TODO(Phase 1.9.2): DB 초기화 후 모듈 라우트 마운트
+  // const registrations = buildBackendRouteRegistrations(manifests);
+  // registrations.forEach(({ apiBasePath, router }) => app.use(apiBasePath, router));
+
+  // ── Error handler (반드시 마지막) ─────────────────────────────
+  app.use(errorHandler);
+
+  return app;
+}

apps/api/src/config/env.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+const EnvSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().int().positive().default(3000),
+  INSTALL_MODE: z.enum(['normal', 'bypass']).optional(),
+});
+
+export type Env = z.infer<typeof EnvSchema>;
+
+export function validateEnv(raw: NodeJS.ProcessEnv): Env {
+  const result = EnvSchema.safeParse(raw);
+
+  if (!result.success) {
+    console.error('[fieldstack][api] Invalid environment variables:');
+    for (const [field, issue] of Object.entries(result.error.flatten().fieldErrors)) {
+      console.error(`  ${field}: ${(issue as string[]).join(', ')}`);
+    }
+    process.exit(1);
+  }
+
+  return result.data;
+}

apps/api/src/index.ts

@@ -1,29 +1,25 @@
-import "dotenv/config";
+import 'dotenv/config';
 
-type InstallMode = "normal" | "bypass";
+import { validateEnv } from './config/env';
+import { createApp } from './app';
 
-const BOOTSTRAP_MESSAGE = "Fieldstack API bootstrap initialized";
+// ── 환경변수 검증 (누락·오류 시 즉시 종료) ────────────────────
+const env = validateEnv(process.env);
 
-function resolveInstallMode(env: NodeJS.ProcessEnv): InstallMode {
-  const requestedMode = env.INSTALL_MODE;
-  const isDevelopment = env.NODE_ENV === "development";
+// ── Install mode ──────────────────────────────────────────────
+const BOOTSTRAP_MESSAGE = 'Fieldstack API bootstrap initialized';
 
-  if (requestedMode === "bypass") {
-    if (isDevelopment) {
-      return "bypass";
-    }
-
-    console.warn("[fieldstack][api] INSTALL_MODE=bypass ignored outside development");
-  }
+console.log(BOOTSTRAP_MESSAGE);
+console.log(`[fieldstack][api] env: ${env.NODE_ENV}`);
+console.log(`[fieldstack][api] install mode: ${env.INSTALL_MODE ?? 'normal'}`);
 
-  return "normal";
+if (env.INSTALL_MODE === 'bypass') {
+  console.warn('[fieldstack][api] DEV INSTALL BYPASS ACTIVE');
 }
 
-const installMode = resolveInstallMode(process.env);
+// ── 서버 시작 ─────────────────────────────────────────────────
+const app = createApp();
 
-console.log(BOOTSTRAP_MESSAGE);
-console.log(`[fieldstack][api] install mode: ${installMode}`);
-
-if (installMode === "bypass") {
-  console.warn("[fieldstack][api] DEV INSTALL BYPASS ACTIVE");
-}
+app.listen(env.PORT, () => {
+  console.log(`[fieldstack][api] server listening on http://localhost:${env.PORT}`);
+});

apps/api/src/middleware/error.ts

@@ -0,0 +1,12 @@
+import type { ErrorRequestHandler } from 'express';
+
+export const errorHandler: ErrorRequestHandler = (err, _req, res, _next) => {
+  const isDev = process.env['NODE_ENV'] === 'development';
+
+  console.error('[fieldstack][api] unhandled error:', err);
+
+  res.status(500).json({
+    error: 'Internal server error',
+    ...(isDev && { message: (err as Error).message }),
+  });
+};

apps/api/src/routes/health.ts

@@ -0,0 +1,11 @@
+import { Router } from 'express';
+
+export const healthRouter = Router();
+
+healthRouter.get('/', (_req, res) => {
+  res.json({
+    status: 'ok',
+    version: process.env['npm_package_version'] ?? '0.0.0',
+    timestamp: new Date().toISOString(),
+  });
+});

apps/api/tsconfig.json

@@ -5,7 +5,8 @@
     "rootDir": "src",
     "noEmit": false,
     "moduleResolution": "Node",
-    "module": "CommonJS"
+    "module": "CommonJS",
+    "esModuleInterop": true
   },
   "include": ["src/**/*.ts"]
 }