feat(setup): Phase 1.95.1~1.95.2 Setup 모드 전환 및 백엔드 API 구현

**1.95.1 모드 전환 시스템**
- setup/mode.ts: installed.lock / fieldstack.config.json 유틸, applyConfigToEnv(), scheduleRestart()
- index.ts: isInstalled() 기반 Setup/앱 모드 분기, config 파일 → process.env 자동 반영
- app.ts: createSetupApp() 팩토리 추가, 앱 모드에서 GET /setup/status → installed:true 반환
- config/env.ts: postgres DATABASE_URL refine 제거 (DB 검증을 initDb() 시점으로 이동)

**1.95.2 Setup 백엔드 API**
- routes/setup.ts: GET /setup/status, GET /setup/db/detect, POST /setup/db/provision (SSE),
  POST /setup/db/test, POST /setup/complete (SSE — DB→마이그레이션→관리자→config→lock→재시작)
- setup/docker.ts: Docker 감지, postgres:16-alpine pull·컨테이너 프로비저닝, 연결 폴링
- setup/runtime.ts: Docker/systemd/native 런타임 병렬 감지 및 provisioner 추상화
  - Docker: fieldstack-postgres 컨테이너 자동 생성 (--restart unless-stopped)
  - systemd: systemctl start + peer/sudo 폴백으로 fieldstack 유저·DB 생성
  - native: 실행 중인 pg에서 fieldstack 유저·DB 생성 시도

**SQLite 제공자 구현 (개발/테스트 전용)**
- db/providers/sqlite.ts: better-sqlite3 기반 실제 구현
  - 데이터 디렉터리 자동 생성, gen_random_uuid()/now() 유저 함수 등록
  - $N → ? 파라미터 변환, RETURNING 절 지원, BEGIN/COMMIT 수동 트랜잭션
- db/migrations/index.ts: {{SERIAL_PK}} 토큰 추가, _migrations 테이블에 applyDialect() 적용

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

Author: SOIV

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Status
 
-Phase 1.5 진행 중 (2026-04-14 기준). Phase 1.9 (API 서버·DB·인증 백엔드·공유 링크) 완료. Phase 1.5.3 로그인 UX 완료 (실패/잠금/세션 만료, 비밀번호 복구 UI, mock 계정 시스템). `packages/controls` P0/P0.5 컴포넌트 구현 완료 (`ready: true`). Storybook 세팅 완료 (port 6007). `@fieldstack/core/browser` 브라우저 전용 엔트리 분리 완료 — 웹 앱은 반드시 이 경로로 import.
+Phase 1.95 진행 중 (2026-04-16 기준). Phase 1.9 (API 서버·DB·인증 백엔드·공유 링크) 완료. Phase 1.5 전 항목 완료. Phase 1.95.1 모드 전환 시스템 완료 (`installed.lock` / `fieldstack.config.json` 기반). Phase 1.95.2 Setup 백엔드 API 완료 (Docker/systemd/native 런타임 자동 감지·프로비저닝, SSE 스트리밍). SQLite 제공자 실제 구현 완료(`better-sqlite3`). `@fieldstack/core/browser` 브라우저 전용 엔트리 분리 완료 — 웹 앱은 반드시 이 경로로 import.
 
 ---
 

apps/api/src/app.ts

@@ -23,6 +23,7 @@ import type { BackendRouteRegistration } from './loader';
 import { createAuthRouter } from './routes/auth';
 import { healthRouter } from './routes/health';
 import { createPublicRouter } from './routes/public';
+import { createSetupRouter } from './routes/setup';
 import { createShareRouter } from './routes/share';
 
 // ── App 팩토리 ────────────────────────────────────────────────
@@ -59,6 +60,11 @@ export function createApp(services?: AppServices) {
   // ── Core routes ───────────────────────────────────────────────
   app.use('/health', healthRouter);
 
+  // 앱 모드에서 /setup/status는 installed:true를 반환 (프론트엔드 모드 감지용)
+  app.get('/setup/status', (_req, res) => {
+    res.json({ success: true, data: { installed: true } });
+  });
+
   if (services) {
     app.use('/auth', createAuthRouter(services));
     app.use('/core/share', createShareRouter(services));
@@ -83,13 +89,43 @@ export function createAppWithPublicRouter(
   app.use(express.urlencoded({ extended: true }));
 
   app.use('/health', healthRouter);
+
+  // 앱 모드에서 /setup/status는 installed:true를 반환 (프론트엔드 모드 감지용)
+  app.get('/setup/status', (_req, res) => {
+    res.json({ success: true, data: { installed: true } });
+  });
+
   app.use('/auth', createAuthRouter(services));
   app.use('/core/share', createShareRouter(services));
   app.use('/s', createPublicRouter(services.sharedLink, getRenderer));
 
   return app;
 }
 
+// ── Setup 전용 앱 팩토리 (installed.lock 없을 때) ─────────────
+
+export function createSetupApp(): express.Application {
+  const app = express();
+
+  app.use(cors());
+  app.use(express.json());
+  app.use(express.urlencoded({ extended: true }));
+
+  app.use('/health', healthRouter);
+  app.use('/setup', createSetupRouter());
+
+  // 프로덕션: 빌드된 프론트엔드 정적 파일 서빙
+  const publicDir = path.join(__dirname, '..', 'public');
+  if (fs.existsSync(publicDir)) {
+    app.use(express.static(publicDir));
+    app.get('*', (_req, res) => {
+      res.sendFile(path.join(publicDir, 'index.html'));
+    });
+  }
+
+  return app;
+}
+
 // ── 모듈 라우터 마운트 ────────────────────────────────────────
 
 export async function mountModuleRouters(

apps/api/src/config/env.ts

@@ -14,10 +14,9 @@ const EnvSchema = z.object({
   TOTP_ISSUER: z.string().default('Fieldstack'),
   // Shared Link
   PUBLIC_URL: z.string().url().optional(),
-}).refine(
-  (env) => env.DB_PROVIDER !== 'postgres' || Boolean(env.DATABASE_URL),
-  { message: 'DATABASE_URL is required when DB_PROVIDER=postgres', path: ['DATABASE_URL'] },
-);
+});
+// DATABASE_URL 존재 여부는 initDb() 호출 시 검증한다.
+// Setup 모드에서는 DB 설정이 아직 없으므로 여기서 강제 검증하지 않는다.
 
 export type Env = z.infer<typeof EnvSchema>;
 

apps/api/src/index.ts

@@ -6,6 +6,7 @@ import { validateEnv } from './config/env';
 import {
   createApp,
   createAppWithPublicRouter,
+  createSetupApp,
   finalizeApp,
   initDb,
   initServices,
@@ -18,6 +19,10 @@ import {
   scanBackendModules,
   validateModuleDependencies,
 } from './loader';
+import { applyConfigToEnv, isInstalled } from './setup/mode';
+
+// ── fieldstack.config.json → process.env 반영 (env vars 우선) ─
+applyConfigToEnv();
 
 // ── 환경변수 검증 (누락·오류 시 즉시 종료) ────────────────────
 const env = validateEnv(process.env);
@@ -35,23 +40,40 @@ if (env.INSTALL_MODE === 'bypass') {
 // modules/ 디렉터리는 프로젝트 루트 기준 (apps/api/src → ../../../modules)
 const MODULES_DIR = path.join(__dirname, '..', '..', '..', 'modules');
 
-// ── DB 초기화 → 마이그레이션 → 서비스 초기화 → 모듈 로드 → 서버 시작 ──
-async function start() {
+// ── Setup 모드 ─────────────────────────────────────────────────
+// installed.lock 없고 bypass 아닐 때 → Setup 마법사만 서빙
+async function startSetup() {
+  console.log('[fieldstack][api] *** SETUP MODE — installation wizard active ***');
+  const app = createSetupApp();
+  finalizeApp(app);
+  app.listen(env.PORT, () => {
+    console.log(`[fieldstack][api] setup server listening on http://localhost:${env.PORT}`);
+  });
+}
+
+// ── 앱 모드 ────────────────────────────────────────────────────
+// DB 초기화 → 마이그레이션 → 서비스 초기화 → 모듈 로드 → 서버 시작
+async function startApp() {
   let services;
 
   if (env.DB_PROVIDER === 'postgres' && env.DATABASE_URL) {
     const db = await initDb();
     await runMigrations(db);
     services = await initServices(db);
     console.log('[fieldstack][api] DB initialized and migrations applied');
+  } else if (env.DB_PROVIDER === 'sqlite') {
+    const db = await initDb();
+    await runMigrations(db);
+    services = await initServices(db);
+    console.log('[fieldstack][api] SQLite DB initialized and migrations applied');
   }
 
   let app;
   if (services) {
     const { getSharedLinkRenderer } = await import('@fieldstack/core');
     app = createAppWithPublicRouter(services, getSharedLinkRenderer);
   } else {
-    // DB 없이 시작 (INSTALL_MODE=bypass 등) — 헬스체크만 동작
+    // DB 없이 시작 (INSTALL_MODE=bypass, DB 미설정) — 헬스체크만 동작
     app = createApp();
   }
 
@@ -82,7 +104,12 @@ async function start() {
   });
 }
 
-start().catch((err) => {
+// ── 진입점 ──────────────────────────────────────────────────────
+const shouldSetup = !isInstalled() && env.INSTALL_MODE !== 'bypass';
+
+const boot = shouldSetup ? startSetup : startApp;
+
+boot().catch((err) => {
   console.error('[fieldstack][api] startup failed:', err);
   process.exit(1);
 });