74 changed files with 154 additions and 12115 deletions
--- a/ai-assistant/.env.example
+++ b/ai-assistant/.env.example
@ -1,25 +0,0 @@
 # AI Assistant API (VEXPLOR 내장) - 환경 변수
 # 이 파일을 .env 로 복사한 뒤 값 설정
 NODE_ENV=development
 PORT=3100
 # PostgreSQL (AI 어시스턴트 전용 DB)
 DB_HOST=localhost
 DB_PORT=5432
 DB_USER=ai_assistant
 DB_PASSWORD=ai_assistant_password
 DB_NAME=ai_assistant_db
 # JWT
 JWT_SECRET=your-super-secret-jwt-key-change-in-production
 JWT_EXPIRES_IN=7d
 JWT_REFRESH_SECRET=your-refresh-secret-key-change-in-production
 JWT_REFRESH_EXPIRES_IN=30d
 # LLM (구글 키 등)
 GEMINI_API_KEY=your-gemini-api-key
 GEMINI_MODEL=gemini-2.0-flash
 RATE_LIMIT_WINDOW_MS=60000
 RATE_LIMIT_MAX_REQUESTS=100
--- a/ai-assistant/Dockerfile.win
+++ b/ai-assistant/Dockerfile.win
@ -1,17 +0,0 @@
 # AI 어시스턴트 API - Docker (Windows 개발용)
 FROM node:20-bookworm-slim
 RUN apt-get update && apt-get install -y --no-install-recommends wget ca-certificates \
    && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY package*.json ./
 RUN npm ci --omit=dev
 COPY . .
 ENV NODE_ENV=development
 EXPOSE 3100
 CMD ["node", "src/app.js"]
--- a/ai-assistant/README.md
+++ b/ai-assistant/README.md
@ -1,43 +0,0 @@
 # AI 어시스턴트 API (VEXPLOR 내장)
 VEXPLOR와 **같은 서비스**로 동작하도록 이 API는 포트 3100에서 구동되고, backend-node가 `/api/ai/v1` 요청을 여기로 프록시합니다.
 ## 동작 방식
 - **프론트(9771)** → `/api/ai/v1/*` 호출
 - **Next.js** → `8080/api/ai/v1/*` 로 rewrite
 - **backend-node(8080)** → `3100/api/v1/*` 로 프록시 → **이 서비스**
 따라서 사용자는 **다른 포트를 쓰지 않고** VEXPLOR만 켜도 AI 기능을 사용할 수 있습니다.
 ## 서비스 올리는 순서 (한 번에 동작하게)
 1. **AI 어시스턴트 API (이 폴더, 포트 3100)**  
   ```bash
   cd ai-assistant
   npm install
   cp .env.example .env   # 필요 시 DB, JWT, GEMINI_API_KEY 등 수정
   npm start
   ```
 2. **backend-node (포트 8080)**  
   ```bash
   cd backend-node
   npm run dev
   ```
 3. **프론트 (포트 9771)**  
   ```bash
   cd frontend
   npm run dev
   ```
 브라우저에서는 `http://localhost:9771` 만 사용하면 되고, AI API는 같은 오리진의 `/api/ai/v1` 로 호출됩니다.
 ## 환경 변수
 - `.env.example` 을 `.env` 로 복사 후 수정
 - `PORT=3100` (기본값)
 - PostgreSQL: `DB_*`
 - JWT: `JWT_SECRET`, `JWT_REFRESH_SECRET`
 - LLM: `GEMINI_API_KEY` 등
--- a/ai-assistant/package-lock.json
+++ b/ai-assistant/package-lock.json
--- a/ai-assistant/package.json
+++ b/ai-assistant/package.json
@ -1,38 +0,0 @@
 {
  "name": "ai-assistant-api",
  "version": "1.0.0",
  "description": "AI Assistant API (VEXPLOR 내장) - 포트 3100에서 구동, backend-node가 /api/ai/v1 로 프록시",
  "private": true,
  "main": "src/app.js",
  "scripts": {
    "start": "node src/app.js",
    "dev": "nodemon src/app.js"
  },
  "dependencies": {
    "@google/genai": "^1.0.0",
    "axios": "^1.6.0",
    "bcryptjs": "^2.4.3",
    "compression": "^1.7.4",
    "cors": "^2.8.5",
    "dotenv": "^16.4.1",
    "express": "^4.18.2",
    "express-rate-limit": "^7.1.5",
    "express-validator": "^7.0.1",
    "helmet": "^7.1.0",
    "jsonwebtoken": "^9.0.2",
    "pg": "^8.11.3",
    "pg-hstore": "^2.3.4",
    "sequelize": "^6.35.2",
    "swagger-jsdoc": "^6.2.8",
    "swagger-ui-express": "^5.0.1",
    "uuid": "^9.0.1",
    "winston": "^3.11.0",
    "zod": "^3.22.4"
  },
  "devDependencies": {
    "nodemon": "^3.0.3"
  },
  "engines": {
    "node": ">=18.0.0"
  }
 }
--- a/ai-assistant/src/app.js
+++ b/ai-assistant/src/app.js
@ -1,186 +0,0 @@
 // src/app.js
 // AI Assistant API 서버 메인 엔트리포인트
 require('dotenv').config();
 const express = require('express');
 const cors = require('cors');
 const helmet = require('helmet');
 const compression = require('compression');
 const rateLimit = require('express-rate-limit');
 const swaggerUi = require('swagger-ui-express');
 const swaggerSpec = require('./config/swagger.config');
 const logger = require('./config/logger.config');
 const { sequelize } = require('./models');
 const routes = require('./routes');
 const errorHandler = require('./middlewares/error-handler.middleware');
 const app = express();
 // VEXPLOR 내장 시 backend-node가 이 포트로 프록시하므로 기본 3100 사용
 const PORT = process.env.PORT || 3100;
 // ===========================================
 // 미들웨어 설정
 // ===========================================
 // Trust proxy (Docker/Nginx 환경)
 app.set('trust proxy', 1);
 // CORS 설정 (helmet보다 먼저 설정)
 app.use(cors({
  origin: true, // 모든 origin 허용
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
 }));
 // Preflight 요청 처리
 app.options('*', cors());
 // 보안 헤더 (CORS 이후에 설정)
 app.use(helmet({
  crossOriginResourcePolicy: { policy: 'cross-origin' },
  crossOriginOpenerPolicy: { policy: 'unsafe-none' },
 }));
 // 요청 본문 파싱
 app.use(express.json({ limit: '10mb' }));
 app.use(express.urlencoded({ extended: true }));
 // 압축
 app.use(compression());
 // Rate Limiting (전역)
 const limiter = rateLimit({
  windowMs: parseInt(process.env.RATE_LIMIT_WINDOW_MS, 10) || 60000,
  max: parseInt(process.env.RATE_LIMIT_MAX_REQUESTS, 10) || 100,
  message: {
    success: false,
    error: {
      code: 'RATE_LIMIT_EXCEEDED',
      message: '요청 한도를 초과했습니다. 잠시 후 다시 시도해주세요.',
    },
  },
  standardHeaders: true,
  legacyHeaders: false,
 });
 app.use(limiter);
 // 요청 로깅
 app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    const duration = Date.now() - start;
    logger.info(`${req.method} ${req.originalUrl} ${res.statusCode} ${duration}ms`);
  });
  next();
 });
 // ===========================================
 // 헬스 체크
 // ===========================================
 app.get('/health', (req, res) => {
  res.json({
    success: true,
    data: {
      status: 'healthy',
      timestamp: new Date().toISOString(),
      uptime: process.uptime(),
    },
  });
 });
 // ===========================================
 // Swagger API 문서
 // ===========================================
 app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec, {
  explorer: true,
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: 'AI Assistant API 문서',
  swaggerOptions: {
    persistAuthorization: true,
    displayRequestDuration: true,
  },
 }));
 // Swagger JSON
 app.get('/api-docs.json', (req, res) => {
  res.setHeader('Content-Type', 'application/json');
  res.send(swaggerSpec);
 });
 // ===========================================
 // API 라우트
 // ===========================================
 app.use('/api/v1', routes);
 // ===========================================
 // 404 처리
 // ===========================================
 app.use((req, res) => {
  res.status(404).json({
    success: false,
    error: {
      code: 'NOT_FOUND',
      message: `요청한 리소스를 찾을 수 없습니다: ${req.method} ${req.originalUrl}`,
    },
  });
 });
 // ===========================================
 // 에러 핸들러
 // ===========================================
 app.use(errorHandler);
 // ===========================================
 // 서버 시작
 // ===========================================
 async function startServer() {
  try {
    // 데이터베이스 연결
    await sequelize.authenticate();
    logger.info('✅ 데이터베이스 연결 성공');
    // 테이블 동기화 (테이블이 없으면 생성)
    await sequelize.sync();
    logger.info('✅ 데이터베이스 스키마 동기화 완료');
    // 초기 데이터 설정 (관리자 계정, LLM 프로바이더)
    const initService = require('./services/init.service');
    await initService.initialize();
    // 서버 시작
    app.listen(PORT, () => {
      logger.info(`🚀 AI Assistant API 서버가 포트 ${PORT}에서 실행 중입니다`);
      logger.info(`📚 API 문서 (Swagger): http://localhost:${PORT}/api-docs`);
      logger.info(`📚 API 엔드포인트: http://localhost:${PORT}/api/v1`);
    });
  } catch (error) {
    logger.error('❌ 서버 시작 실패:', error);
    process.exit(1);
  }
 }
 // 프로세스 종료 처리
 process.on('SIGTERM', async () => {
  logger.info('SIGTERM 신호 수신, 서버 종료 중...');
  await sequelize.close();
  process.exit(0);
 });
 process.on('SIGINT', async () => {
  logger.info('SIGINT 신호 수신, 서버 종료 중...');
  await sequelize.close();
  process.exit(0);
 });
 startServer();
 module.exports = app;
--- a/ai-assistant/src/controllers/admin.controller.js
+++ b/ai-assistant/src/controllers/admin.controller.js
@ -1,474 +0,0 @@
 // src/controllers/admin.controller.js
 // 관리자 컨트롤러
 const { LLMProvider, User, UsageLog, ApiKey } = require('../models');
 const { Op } = require('sequelize');
 const logger = require('../config/logger.config');
 // ===== LLM 프로바이더 관리 =====
 /**
 * LLM 프로바이더 목록 조회
 */
 exports.getProviders = async (req, res, next) => {
  try {
    const providers = await LLMProvider.findAll({
      order: [['priority', 'ASC']],
      attributes: [
        'id',
        'name',
        'displayName',
        'endpoint',
        'modelName',
        'priority',
        'maxTokens',
        'temperature',
        'timeoutMs',
        'costPer1kInputTokens',
        'costPer1kOutputTokens',
        'isActive',
        'isHealthy',
        'lastHealthCheck',
        'createdAt',
        'updatedAt',
        // API 키는 마스킹해서 반환
        'apiKey',
      ],
    });
    // API 키 마스킹
    const maskedProviders = providers.map((p) => {
      const data = p.toJSON();
      if (data.apiKey) {
        // 앞 8자만 보여주고 나머지는 마스킹
        data.apiKey = data.apiKey.substring(0, 8) + '****' + data.apiKey.slice(-4);
        data.hasApiKey = true;
      } else {
        data.hasApiKey = false;
      }
      return data;
    });
    return res.json({
      success: true,
      data: maskedProviders,
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * LLM 프로바이더 추가
 */
 exports.createProvider = async (req, res, next) => {
  try {
    const {
      name,
      displayName,
      endpoint,
      apiKey,
      modelName,
      priority = 50,
      maxTokens = 4096,
      temperature = 0.7,
      timeoutMs = 60000,
      costPer1kInputTokens = 0,
      costPer1kOutputTokens = 0,
    } = req.body;
    // 중복 이름 확인
    const existing = await LLMProvider.findOne({ where: { name } });
    if (existing) {
      return res.status(409).json({
        success: false,
        error: {
          code: 'PROVIDER_EXISTS',
          message: '이미 존재하는 프로바이더 이름입니다.',
        },
      });
    }
    const provider = await LLMProvider.create({
      name,
      displayName,
      endpoint,
      apiKey,
      modelName,
      priority,
      maxTokens,
      temperature,
      timeoutMs,
      costPer1kInputTokens,
      costPer1kOutputTokens,
      isActive: true,
      isHealthy: true,
    });
    logger.info(`LLM 프로바이더 추가: ${name} (${modelName})`);
    return res.status(201).json({
      success: true,
      data: {
        id: provider.id,
        name: provider.name,
        displayName: provider.displayName,
        modelName: provider.modelName,
        priority: provider.priority,
        isActive: provider.isActive,
        message: 'LLM 프로바이더가 추가되었습니다.',
      },
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * LLM 프로바이더 수정
 */
 exports.updateProvider = async (req, res, next) => {
  try {
    const { id } = req.params;
    const updates = req.body;
    const provider = await LLMProvider.findByPk(id);
    if (!provider) {
      return res.status(404).json({
        success: false,
        error: {
          code: 'PROVIDER_NOT_FOUND',
          message: 'LLM 프로바이더를 찾을 수 없습니다.',
        },
      });
    }
    // 허용된 필드만 업데이트
    const allowedFields = [
      'displayName',
      'endpoint',
      'apiKey',
      'modelName',
      'priority',
      'maxTokens',
      'temperature',
      'timeoutMs',
      'costPer1kInputTokens',
      'costPer1kOutputTokens',
      'isActive',
      'isHealthy',
    ];
    allowedFields.forEach((field) => {
      if (updates[field] !== undefined) {
        provider[field] = updates[field];
      }
    });
    await provider.save();
    logger.info(`LLM 프로바이더 수정: ${provider.name}`);
    return res.json({
      success: true,
      data: {
        id: provider.id,
        name: provider.name,
        displayName: provider.displayName,
        modelName: provider.modelName,
        isActive: provider.isActive,
        message: 'LLM 프로바이더가 수정되었습니다.',
      },
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * LLM 프로바이더 삭제
 */
 exports.deleteProvider = async (req, res, next) => {
  try {
    const { id } = req.params;
    const provider = await LLMProvider.findByPk(id);
    if (!provider) {
      return res.status(404).json({
        success: false,
        error: {
          code: 'PROVIDER_NOT_FOUND',
          message: 'LLM 프로바이더를 찾을 수 없습니다.',
        },
      });
    }
    const providerName = provider.name;
    await provider.destroy();
    logger.info(`LLM 프로바이더 삭제: ${providerName}`);
    return res.json({
      success: true,
      data: {
        message: 'LLM 프로바이더가 삭제되었습니다.',
      },
    });
  } catch (error) {
    return next(error);
  }
 };
 // ===== 사용자 관리 =====
 /**
 * 사용자 목록 조회
 */
 exports.getUsers = async (req, res, next) => {
  try {
    const page = parseInt(req.query.page, 10) || 1;
    const limit = parseInt(req.query.limit, 10) || 100;
    const offset = (page - 1) * limit;
    const { count, rows: users } = await User.findAndCountAll({
      attributes: [
        'id',
        'email',
        'name',
        'role',
        'status',
        'plan',
        'monthlyTokenLimit',
        'lastLoginAt',
        'createdAt',
      ],
      order: [['createdAt', 'DESC']],
      limit,
      offset,
    });
    // 페이지네이션 없이 간단한 배열로 반환 (프론트엔드 호환)
    return res.json({
      success: true,
      data: users,
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * 사용자 정보 수정
 */
 exports.updateUser = async (req, res, next) => {
  try {
    const { id } = req.params;
    const { role, status, plan, monthlyTokenLimit } = req.body;
    const user = await User.findByPk(id);
    if (!user) {
      return res.status(404).json({
        success: false,
        error: {
          code: 'USER_NOT_FOUND',
          message: '사용자를 찾을 수 없습니다.',
        },
      });
    }
    if (role) user.role = role;
    if (status) user.status = status;
    if (plan) user.plan = plan;
    if (monthlyTokenLimit !== undefined) user.monthlyTokenLimit = monthlyTokenLimit;
    await user.save();
    logger.info(`사용자 정보 수정: ${user.email} (role: ${user.role}, status: ${user.status})`);
    return res.json({
      success: true,
      data: user.toSafeJSON(),
    });
  } catch (error) {
    return next(error);
  }
 };
 // ===== 시스템 통계 =====
 /**
 * 사용자별 사용량 통계
 */
 exports.getUsageByUser = async (req, res, next) => {
  try {
    const days = parseInt(req.query.days, 10) || 7;
    const startDate = new Date();
    startDate.setDate(startDate.getDate() - days);
    startDate.setHours(0, 0, 0, 0);
    // 사용자별 집계 (raw SQL 사용)
    const userStats = await UsageLog.sequelize.query(`
      SELECT 
        u.id as "userId",
        u.email,
        u.name,
        COALESCE(SUM(ul.total_tokens), 0) as "totalTokens",
        COALESCE(SUM(ul.cost_usd), 0) as "totalCost",
        COUNT(ul.id) as "requestCount"
      FROM users u
      LEFT JOIN usage_logs ul ON u.id = ul.user_id AND ul.created_at >= :startDate
      GROUP BY u.id, u.email, u.name
      HAVING COUNT(ul.id) > 0
      ORDER BY SUM(ul.total_tokens) DESC NULLS LAST
    `, {
      replacements: { startDate },
      type: UsageLog.sequelize.QueryTypes.SELECT,
    });
    // 데이터 정리
    const result = userStats.map((stat) => ({
      userId: stat.userId,
      email: stat.email || 'Unknown',
      name: stat.name || '',
      totalTokens: parseInt(stat.totalTokens, 10) || 0,
      totalCost: parseFloat(stat.totalCost) || 0,
      requestCount: parseInt(stat.requestCount, 10) || 0,
    }));
    return res.json({
      success: true,
      data: result,
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * 프로바이더별 사용량 통계
 */
 exports.getUsageByProvider = async (req, res, next) => {
  try {
    const days = parseInt(req.query.days, 10) || 7;
    const startDate = new Date();
    startDate.setDate(startDate.getDate() - days);
    startDate.setHours(0, 0, 0, 0);
    // 프로바이더별 집계 (컬럼명 수정: providerName, modelName)
    const providerStats = await UsageLog.findAll({
      where: {
        createdAt: { [Op.gte]: startDate },
      },
      attributes: [
        'providerName',
        'modelName',
        [UsageLog.sequelize.fn('SUM', UsageLog.sequelize.col('total_tokens')), 'totalTokens'],
        [UsageLog.sequelize.fn('SUM', UsageLog.sequelize.col('prompt_tokens')), 'promptTokens'],
        [UsageLog.sequelize.fn('SUM', UsageLog.sequelize.col('completion_tokens')), 'completionTokens'],
        [UsageLog.sequelize.fn('SUM', UsageLog.sequelize.col('cost_usd')), 'totalCost'],
        [UsageLog.sequelize.fn('COUNT', UsageLog.sequelize.col('id')), 'requestCount'],
        [UsageLog.sequelize.fn('AVG', UsageLog.sequelize.col('response_time_ms')), 'avgResponseTime'],
      ],
      group: ['providerName', 'modelName'],
      order: [[UsageLog.sequelize.literal('"totalTokens"'), 'DESC']],
      raw: true,
    });
    // 데이터 정리
    const result = providerStats.map((stat) => ({
      provider: stat.providerName || 'Unknown',
      model: stat.modelName || 'Unknown',
      totalTokens: parseInt(stat.totalTokens, 10) || 0,
      promptTokens: parseInt(stat.promptTokens, 10) || 0,
      completionTokens: parseInt(stat.completionTokens, 10) || 0,
      totalCost: parseFloat(stat.totalCost) || 0,
      requestCount: parseInt(stat.requestCount, 10) || 0,
      avgResponseTime: Math.round(parseFloat(stat.avgResponseTime) || 0),
    }));
    return res.json({
      success: true,
      data: result,
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * 시스템 통계 조회
 */
 exports.getStats = async (req, res, next) => {
  try {
    // 전체 사용자 수
    const totalUsers = await User.count();
    const activeUsers = await User.count({ where: { status: 'active' } });
    // 전체 API 키 수
    const totalApiKeys = await ApiKey.count();
    const activeApiKeys = await ApiKey.count({ where: { status: 'active' } });
    // 오늘 사용량
    const today = new Date();
    today.setHours(0, 0, 0, 0);
    const todayUsage = await UsageLog.findOne({
      where: {
        createdAt: { [Op.gte]: today },
      },
      attributes: [
        [UsageLog.sequelize.fn('SUM', UsageLog.sequelize.col('total_tokens')), 'totalTokens'],
        [UsageLog.sequelize.fn('SUM', UsageLog.sequelize.col('cost_usd')), 'totalCost'],
        [UsageLog.sequelize.fn('COUNT', UsageLog.sequelize.col('id')), 'requestCount'],
      ],
      raw: true,
    });
    // 이번 달 사용량
    const monthStart = new Date(today.getFullYear(), today.getMonth(), 1);
    const monthlyUsage = await UsageLog.findOne({
      where: {
        createdAt: { [Op.gte]: monthStart },
      },
      attributes: [
        [UsageLog.sequelize.fn('SUM', UsageLog.sequelize.col('total_tokens')), 'totalTokens'],
        [UsageLog.sequelize.fn('SUM', UsageLog.sequelize.col('cost_usd')), 'totalCost'],
        [UsageLog.sequelize.fn('COUNT', UsageLog.sequelize.col('id')), 'requestCount'],
      ],
      raw: true,
    });
    // 활성 프로바이더 수
    const activeProviders = await LLMProvider.count({ where: { isActive: true, isHealthy: true } });
    return res.json({
      success: true,
      data: {
        users: {
          total: totalUsers,
          active: activeUsers,
        },
        apiKeys: {
          total: totalApiKeys,
          active: activeApiKeys,
        },
        providers: {
          active: activeProviders,
        },
        usage: {
          today: {
            tokens: parseInt(todayUsage?.totalTokens, 10) || 0,
            cost: parseFloat(todayUsage?.totalCost) || 0,
            requests: parseInt(todayUsage?.requestCount, 10) || 0,
          },
          monthly: {
            tokens: parseInt(monthlyUsage?.totalTokens, 10) || 0,
            cost: parseFloat(monthlyUsage?.totalCost) || 0,
            requests: parseInt(monthlyUsage?.requestCount, 10) || 0,
          },
        },
      },
    });
  } catch (error) {
    return next(error);
  }
 };
--- a/ai-assistant/src/controllers/api-key.controller.js
+++ b/ai-assistant/src/controllers/api-key.controller.js
@ -1,215 +0,0 @@
 // src/controllers/api-key.controller.js
 // API 키 컨트롤러
 const { ApiKey } = require('../models');
 const logger = require('../config/logger.config');
 /**
 * API 키 발급
 */
 exports.create = async (req, res, next) => {
  try {
    const { name, expiresInDays, permissions } = req.body;
    const userId = req.user.userId;
    // API 키 생성
    const rawKey = ApiKey.generateKey();
    const keyHash = ApiKey.hashKey(rawKey);
    const keyPrefix = rawKey.substring(0, 12);
    // 만료 일시 계산
    let expiresAt = null;
    if (expiresInDays) {
      expiresAt = new Date();
      expiresAt.setDate(expiresAt.getDate() + expiresInDays);
    }
    const apiKey = await ApiKey.create({
      userId,
      name,
      keyPrefix,
      keyHash,
      permissions: permissions || ['chat:read', 'chat:write'],
      expiresAt,
    });
    logger.info(`API 키 발급: ${name} (user: ${userId})`);
    // 주의: 원본 키는 이 응답에서만 반환됨 (다시 조회 불가)
    return res.status(201).json({
      success: true,
      data: {
        id: apiKey.id,
        name: apiKey.name,
        key: rawKey, // 원본 키 (한 번만 표시)
        keyPrefix: apiKey.keyPrefix,
        permissions: apiKey.permissions,
        expiresAt: apiKey.expiresAt,
        createdAt: apiKey.createdAt,
        message: '⚠️ API 키는 이 응답에서만 확인할 수 있습니다. 안전한 곳에 저장하세요.',
      },
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * API 키 목록 조회
 */
 exports.list = async (req, res, next) => {
  try {
    const userId = req.user.userId;
    const apiKeys = await ApiKey.findAll({
      where: { userId },
      attributes: [
        'id',
        'name',
        'keyPrefix',
        'permissions',
        'rateLimit',
        'status',
        'expiresAt',
        'lastUsedAt',
        'totalRequests',
        'createdAt',
      ],
      order: [['createdAt', 'DESC']],
    });
    return res.json({
      success: true,
      data: apiKeys,
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * API 키 상세 조회
 */
 exports.get = async (req, res, next) => {
  try {
    const { id } = req.params;
    const userId = req.user.userId;
    const apiKey = await ApiKey.findOne({
      where: { id, userId },
      attributes: [
        'id',
        'name',
        'keyPrefix',
        'permissions',
        'rateLimit',
        'status',
        'expiresAt',
        'lastUsedAt',
        'totalRequests',
        'createdAt',
        'updatedAt',
      ],
    });
    if (!apiKey) {
      return res.status(404).json({
        success: false,
        error: {
          code: 'API_KEY_NOT_FOUND',
          message: 'API 키를 찾을 수 없습니다.',
        },
      });
    }
    return res.json({
      success: true,
      data: apiKey,
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * API 키 수정
 */
 exports.update = async (req, res, next) => {
  try {
    const { id } = req.params;
    const { name, status } = req.body;
    const userId = req.user.userId;
    const apiKey = await ApiKey.findOne({
      where: { id, userId },
    });
    if (!apiKey) {
      return res.status(404).json({
        success: false,
        error: {
          code: 'API_KEY_NOT_FOUND',
          message: 'API 키를 찾을 수 없습니다.',
        },
      });
    }
    if (name) apiKey.name = name;
    if (status) apiKey.status = status;
    await apiKey.save();
    logger.info(`API 키 수정: ${apiKey.name} (id: ${id})`);
    return res.json({
      success: true,
      data: {
        id: apiKey.id,
        name: apiKey.name,
        keyPrefix: apiKey.keyPrefix,
        status: apiKey.status,
        updatedAt: apiKey.updatedAt,
      },
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * API 키 폐기
 */
 exports.revoke = async (req, res, next) => {
  try {
    const { id } = req.params;
    const userId = req.user.userId;
    const apiKey = await ApiKey.findOne({
      where: { id, userId },
    });
    if (!apiKey) {
      return res.status(404).json({
        success: false,
        error: {
          code: 'API_KEY_NOT_FOUND',
          message: 'API 키를 찾을 수 없습니다.',
        },
      });
    }
    apiKey.status = 'revoked';
    await apiKey.save();
    logger.info(`API 키 폐기: ${apiKey.name} (id: ${id})`);
    return res.json({
      success: true,
      data: {
        message: 'API 키가 폐기되었습니다.',
      },
    });
  } catch (error) {
    return next(error);
  }
 };
--- a/ai-assistant/src/controllers/auth.controller.js
+++ b/ai-assistant/src/controllers/auth.controller.js
@ -1,195 +0,0 @@
 // src/controllers/auth.controller.js
 // 인증 컨트롤러
 const jwt = require('jsonwebtoken');
 const { User } = require('../models');
 const logger = require('../config/logger.config');
 const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key';
 const JWT_EXPIRES_IN = process.env.JWT_EXPIRES_IN || '7d';
 const JWT_REFRESH_SECRET = process.env.JWT_REFRESH_SECRET || 'your-refresh-secret';
 const JWT_REFRESH_EXPIRES_IN = process.env.JWT_REFRESH_EXPIRES_IN || '30d';
 /**
 * JWT 토큰 생성
 */
 function generateTokens(user) {
  const accessToken = jwt.sign(
    { userId: user.id, email: user.email, role: user.role },
    JWT_SECRET,
    { expiresIn: JWT_EXPIRES_IN }
  );
  const refreshToken = jwt.sign(
    { userId: user.id },
    JWT_REFRESH_SECRET,
    { expiresIn: JWT_REFRESH_EXPIRES_IN }
  );
  return { accessToken, refreshToken };
 }
 /**
 * 회원가입
 */
 exports.register = async (req, res, next) => {
  try {
    const { email, password, name } = req.body;
    // 이메일 중복 확인
    const existingUser = await User.findOne({ where: { email } });
    if (existingUser) {
      return res.status(409).json({
        success: false,
        error: {
          code: 'EMAIL_ALREADY_EXISTS',
          message: '이미 등록된 이메일입니다.',
        },
      });
    }
    // 사용자 생성
    const user = await User.create({
      email,
      password,
      name,
    });
    // 토큰 생성
    const tokens = generateTokens(user);
    logger.info(`새 사용자 가입: ${email}`);
    return res.status(201).json({
      success: true,
      data: {
        user: user.toSafeJSON(),
        ...tokens,
      },
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * 로그인
 */
 exports.login = async (req, res, next) => {
  try {
    const { email, password } = req.body;
    // 사용자 조회
    const user = await User.findOne({ where: { email } });
    if (!user) {
      return res.status(401).json({
        success: false,
        error: {
          code: 'INVALID_CREDENTIALS',
          message: '이메일 또는 비밀번호가 올바르지 않습니다.',
        },
      });
    }
    // 비밀번호 검증
    const isValidPassword = await user.validatePassword(password);
    if (!isValidPassword) {
      return res.status(401).json({
        success: false,
        error: {
          code: 'INVALID_CREDENTIALS',
          message: '이메일 또는 비밀번호가 올바르지 않습니다.',
        },
      });
    }
    // 계정 상태 확인
    if (user.status !== 'active') {
      return res.status(403).json({
        success: false,
        error: {
          code: 'ACCOUNT_INACTIVE',
          message: '계정이 비활성화되었습니다. 관리자에게 문의하세요.',
        },
      });
    }
    // 마지막 로그인 시간 업데이트
    user.lastLoginAt = new Date();
    await user.save();
    // 토큰 생성
    const tokens = generateTokens(user);
    logger.info(`사용자 로그인: ${email}`);
    return res.json({
      success: true,
      data: {
        user: user.toSafeJSON(),
        ...tokens,
      },
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * 토큰 갱신
 */
 exports.refresh = async (req, res, next) => {
  try {
    const { refreshToken } = req.body;
    // 리프레시 토큰 검증
    let decoded;
    try {
      decoded = jwt.verify(refreshToken, JWT_REFRESH_SECRET);
    } catch (error) {
      return res.status(401).json({
        success: false,
        error: {
          code: 'INVALID_REFRESH_TOKEN',
          message: '유효하지 않은 리프레시 토큰입니다.',
        },
      });
    }
    // 사용자 조회
    const user = await User.findByPk(decoded.userId);
    if (!user || user.status !== 'active') {
      return res.status(401).json({
        success: false,
        error: {
          code: 'USER_NOT_FOUND',
          message: '사용자를 찾을 수 없습니다.',
        },
      });
    }
    // 새 토큰 생성
    const tokens = generateTokens(user);
    return res.json({
      success: true,
      data: tokens,
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * 로그아웃
 */
 exports.logout = async (req, res) => {
  // 클라이언트에서 토큰 삭제 처리
  // 서버에서는 특별한 처리 없음 (필요시 블랙리스트 구현)
  return res.json({
    success: true,
    data: {
      message: '로그아웃되었습니다.',
    },
  });
 };
--- a/ai-assistant/src/controllers/chat.controller.js
+++ b/ai-assistant/src/controllers/chat.controller.js
@ -1,152 +0,0 @@
 // src/controllers/chat.controller.js
 // 채팅 컨트롤러 (OpenAI 호환 API)
 const llmService = require('../services/llm.service');
 const logger = require('../config/logger.config');
 /**
 * 채팅 완성 API (OpenAI 호환)
 * POST /api/v1/chat/completions
 */
 exports.completions = async (req, res, next) => {
  try {
    const {
      model = 'gemini-2.0-flash',
      messages,
      temperature = 0.7,
      max_tokens = 4096,
      stream = false,
    } = req.body;
    const startTime = Date.now();
    // 스트리밍 응답 처리
    if (stream) {
      return handleStreamingResponse(req, res, {
        model,
        messages,
        temperature,
        maxTokens: max_tokens,
      });
    }
    // 일반 응답 처리
    const result = await llmService.chat({
      model,
      messages,
      temperature,
      maxTokens: max_tokens,
      userId: req.user.id,
      apiKeyId: req.apiKey?.id,
    });
    const responseTime = Date.now() - startTime;
    // 사용량 정보 저장 (미들웨어에서 처리)
    req.usageData = {
      providerId: result.providerId,
      providerName: result.provider,
      modelName: result.model,
      promptTokens: result.usage.promptTokens,
      completionTokens: result.usage.completionTokens,
      totalTokens: result.usage.totalTokens,
      costUsd: result.cost,
      responseTimeMs: responseTime,
      success: true,
    };
    // OpenAI 호환 응답 형식
    return res.json({
      id: `chatcmpl-${Date.now()}`,
      object: 'chat.completion',
      created: Math.floor(Date.now() / 1000),
      model: result.model,
      choices: [
        {
          index: 0,
          message: {
            role: 'assistant',
            content: result.text,
          },
          finish_reason: 'stop',
        },
      ],
      usage: {
        prompt_tokens: result.usage.promptTokens,
        completion_tokens: result.usage.completionTokens,
        total_tokens: result.usage.totalTokens,
      },
    });
  } catch (error) {
    logger.error('채팅 완성 오류:', error);
    // 사용량 정보 저장 (실패)
    req.usageData = {
      success: false,
      errorMessage: error.message,
    };
    return next(error);
  }
 };
 /**
 * 스트리밍 응답 처리
 */
 async function handleStreamingResponse(req, res, params) {
  const { model, messages, temperature, maxTokens } = params;
  // SSE 헤더 설정
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  try {
    // 스트리밍 응답 생성
    const stream = await llmService.chatStream({
      model,
      messages,
      temperature,
      maxTokens,
      userId: req.user.id,
      apiKeyId: req.apiKey?.id,
    });
    // 스트림 이벤트 처리
    for await (const chunk of stream) {
      const data = {
        id: `chatcmpl-${Date.now()}`,
        object: 'chat.completion.chunk',
        created: Math.floor(Date.now() / 1000),
        model,
        choices: [
          {
            index: 0,
            delta: {
              content: chunk.text,
            },
            finish_reason: chunk.done ? 'stop' : null,
          },
        ],
      };
      res.write(`data: ${JSON.stringify(data)}\n\n`);
    }
    // 스트림 종료
    res.write('data: [DONE]\n\n');
    res.end();
  } catch (error) {
    logger.error('스트리밍 오류:', error);
    const errorData = {
      error: {
        message: error.message,
        type: 'server_error',
      },
    };
    res.write(`data: ${JSON.stringify(errorData)}\n\n`);
    res.end();
  }
 }
--- a/ai-assistant/src/controllers/model.controller.js
+++ b/ai-assistant/src/controllers/model.controller.js
@ -1,67 +0,0 @@
 // src/controllers/model.controller.js
 // 모델 컨트롤러
 const { LLMProvider } = require('../models');
 /**
 * 사용 가능한 모델 목록 조회
 */
 exports.list = async (req, res, next) => {
  try {
    const providers = await LLMProvider.getActiveProviders();
    // OpenAI 호환 형식으로 변환
    const models = providers.map((provider) => ({
      id: provider.modelName,
      object: 'model',
      created: Math.floor(new Date(provider.createdAt).getTime() / 1000),
      owned_by: provider.name,
      permission: [],
      root: provider.modelName,
      parent: null,
    }));
    return res.json({
      object: 'list',
      data: models,
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * 모델 상세 정보 조회
 */
 exports.get = async (req, res, next) => {
  try {
    const { id } = req.params;
    const provider = await LLMProvider.findOne({
      where: { modelName: id, isActive: true },
    });
    if (!provider) {
      return res.status(404).json({
        error: {
          message: `모델 '${id}'을(를) 찾을 수 없습니다.`,
          type: 'invalid_request_error',
          param: 'model',
          code: 'model_not_found',
        },
      });
    }
    return res.json({
      id: provider.modelName,
      object: 'model',
      created: Math.floor(new Date(provider.createdAt).getTime() / 1000),
      owned_by: provider.name,
      permission: [],
      root: provider.modelName,
      parent: null,
    });
  } catch (error) {
    return next(error);
  }
 };
--- a/ai-assistant/src/controllers/usage.controller.js
+++ b/ai-assistant/src/controllers/usage.controller.js
@ -1,177 +0,0 @@
 // src/controllers/usage.controller.js
 // 사용량 컨트롤러
 const { UsageLog, User } = require('../models');
 const { Op } = require('sequelize');
 /**
 * 사용량 요약 조회
 */
 exports.getSummary = async (req, res, next) => {
  try {
    const userId = req.user.userId;
    // 사용자 정보 조회
    const user = await User.findByPk(userId);
    if (!user) {
      return res.status(404).json({
        success: false,
        error: {
          code: 'USER_NOT_FOUND',
          message: '사용자를 찾을 수 없습니다.',
        },
      });
    }
    // 이번 달 사용량
    const now = new Date();
    const monthlyUsage = await UsageLog.getMonthlyTotalByUser(
      userId,
      now.getFullYear(),
      now.getMonth() + 1
    );
    // 오늘 사용량
    const todayStart = new Date(now.getFullYear(), now.getMonth(), now.getDate());
    const todayEnd = new Date(todayStart);
    todayEnd.setDate(todayEnd.getDate() + 1);
    const todayUsage = await UsageLog.findOne({
      where: {
        userId,
        createdAt: {
          [Op.between]: [todayStart, todayEnd],
        },
      },
      attributes: [
        [UsageLog.sequelize.fn('SUM', UsageLog.sequelize.col('total_tokens')), 'totalTokens'],
        [UsageLog.sequelize.fn('SUM', UsageLog.sequelize.col('cost_usd')), 'totalCost'],
        [UsageLog.sequelize.fn('COUNT', UsageLog.sequelize.col('id')), 'requestCount'],
      ],
      raw: true,
    });
    return res.json({
      success: true,
      data: {
        plan: user.plan,
        limit: {
          monthly: user.monthlyTokenLimit,
          remaining: Math.max(0, user.monthlyTokenLimit - monthlyUsage.totalTokens),
        },
        usage: {
          today: {
            tokens: parseInt(todayUsage?.totalTokens, 10) || 0,
            cost: parseFloat(todayUsage?.totalCost) || 0,
            requests: parseInt(todayUsage?.requestCount, 10) || 0,
          },
          monthly: monthlyUsage,
        },
      },
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * 일별 사용량 조회
 */
 exports.getDailyUsage = async (req, res, next) => {
  try {
    const userId = req.user.userId;
    const { startDate, endDate } = req.query;
    // 기본값: 최근 30일
    const end = endDate ? new Date(endDate) : new Date();
    const start = startDate ? new Date(startDate) : new Date(end);
    if (!startDate) {
      start.setDate(start.getDate() - 30);
    }
    const dailyUsage = await UsageLog.getDailyUsageByUser(userId, start, end);
    return res.json({
      success: true,
      data: {
        startDate: start.toISOString().split('T')[0],
        endDate: end.toISOString().split('T')[0],
        usage: dailyUsage,
      },
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * 월별 사용량 조회
 */
 exports.getMonthlyUsage = async (req, res, next) => {
  try {
    const userId = req.user.userId;
    const now = new Date();
    const year = parseInt(req.query.year, 10) || now.getFullYear();
    const month = parseInt(req.query.month, 10) || (now.getMonth() + 1);
    const monthlyUsage = await UsageLog.getMonthlyTotalByUser(userId, year, month);
    return res.json({
      success: true,
      data: {
        year,
        month,
        usage: monthlyUsage,
      },
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * 사용량 로그 목록 조회
 */
 exports.getLogs = async (req, res, next) => {
  try {
    const userId = req.user.userId;
    const page = parseInt(req.query.page, 10) || 1;
    const limit = parseInt(req.query.limit, 10) || 20;
    const offset = (page - 1) * limit;
    const { count, rows: logs } = await UsageLog.findAndCountAll({
      where: { userId },
      attributes: [
        'id',
        'providerName',
        'modelName',
        'promptTokens',
        'completionTokens',
        'totalTokens',
        'costUsd',
        'responseTimeMs',
        'success',
        'errorMessage',
        'createdAt',
      ],
      order: [['createdAt', 'DESC']],
      limit,
      offset,
    });
    return res.json({
      success: true,
      data: {
        logs,
        pagination: {
          total: count,
          page,
          limit,
          totalPages: Math.ceil(count / limit),
        },
      },
    });
  } catch (error) {
    return next(error);
  }
 };
--- a/ai-assistant/src/controllers/user.controller.js
+++ b/ai-assistant/src/controllers/user.controller.js
@ -1,113 +0,0 @@
 // src/controllers/user.controller.js
 // 사용자 컨트롤러
 const { User, UsageLog } = require('../models');
 const logger = require('../config/logger.config');
 /**
 * 내 정보 조회
 */
 exports.getMe = async (req, res, next) => {
  try {
    const user = await User.findByPk(req.user.userId);
    if (!user) {
      return res.status(404).json({
        success: false,
        error: {
          code: 'USER_NOT_FOUND',
          message: '사용자를 찾을 수 없습니다.',
        },
      });
    }
    // 이번 달 사용량 조회
    const now = new Date();
    const monthlyUsage = await UsageLog.getMonthlyTotalByUser(
      user.id,
      now.getFullYear(),
      now.getMonth() + 1
    );
    return res.json({
      success: true,
      data: {
        ...user.toSafeJSON(),
        usage: {
          monthly: monthlyUsage,
          limit: user.monthlyTokenLimit,
          remaining: Math.max(0, user.monthlyTokenLimit - monthlyUsage.totalTokens),
        },
      },
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * 내 정보 수정
 */
 exports.updateMe = async (req, res, next) => {
  try {
    const { name, password } = req.body;
    const user = await User.findByPk(req.user.userId);
    if (!user) {
      return res.status(404).json({
        success: false,
        error: {
          code: 'USER_NOT_FOUND',
          message: '사용자를 찾을 수 없습니다.',
        },
      });
    }
    // 업데이트할 필드만 설정
    if (name) user.name = name;
    if (password) user.password = password;
    await user.save();
    logger.info(`사용자 정보 수정: ${user.email}`);
    return res.json({
      success: true,
      data: user.toSafeJSON(),
    });
  } catch (error) {
    return next(error);
  }
 };
 /**
 * 계정 삭제
 */
 exports.deleteMe = async (req, res, next) => {
  try {
    const user = await User.findByPk(req.user.userId);
    if (!user) {
      return res.status(404).json({
        success: false,
        error: {
          code: 'USER_NOT_FOUND',
          message: '사용자를 찾을 수 없습니다.',
        },
      });
    }
    // 소프트 삭제 (상태 변경)
    user.status = 'inactive';
    await user.save();
    logger.info(`사용자 계정 삭제: ${user.email}`);
    return res.json({
      success: true,
      data: {
        message: '계정이 삭제되었습니다.',
      },
    });
  } catch (error) {
    return next(error);
  }
 };
--- a/ai-assistant/src/middlewares/auth.middleware.js
+++ b/ai-assistant/src/middlewares/auth.middleware.js
@ -1,257 +0,0 @@
 // src/middlewares/auth.middleware.js
 // 인증 미들웨어
 const jwt = require('jsonwebtoken');
 const { ApiKey, User } = require('../models');
 const logger = require('../config/logger.config');
 const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key';
 /**
 * JWT 토큰 인증 미들웨어
 * Authorization: Bearer <JWT_TOKEN>
 */
 exports.authenticateJWT = async (req, res, next) => {
  try {
    const authHeader = req.headers.authorization;
    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      return res.status(401).json({
        success: false,
        error: {
          code: 'UNAUTHORIZED',
          message: '인증 토큰이 필요합니다.',
        },
      });
    }
    const token = authHeader.substring(7);
    try {
      const decoded = jwt.verify(token, JWT_SECRET);
      req.user = decoded;
      return next();
    } catch (error) {
      if (error.name === 'TokenExpiredError') {
        return res.status(401).json({
          success: false,
          error: {
            code: 'TOKEN_EXPIRED',
            message: '토큰이 만료되었습니다.',
          },
        });
      }
      return res.status(401).json({
        success: false,
        error: {
          code: 'INVALID_TOKEN',
          message: '유효하지 않은 토큰입니다.',
        },
      });
    }
  } catch (error) {
    return next(error);
  }
 };
 /**
 * API 키 인증 미들웨어
 * Authorization: Bearer <API_KEY>
 */
 exports.authenticateApiKey = async (req, res, next) => {
  try {
    const authHeader = req.headers.authorization;
    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      return res.status(401).json({
        error: {
          message: 'API 키가 필요합니다.',
          type: 'invalid_request_error',
          code: 'missing_api_key',
        },
      });
    }
    const apiKeyValue = authHeader.substring(7);
    // API 키 접두사 확인
    const prefix = process.env.API_KEY_PREFIX || 'sk-';
    if (!apiKeyValue.startsWith(prefix)) {
      return res.status(401).json({
        error: {
          message: '유효하지 않은 API 키 형식입니다.',
          type: 'invalid_request_error',
          code: 'invalid_api_key',
        },
      });
    }
    // API 키 조회
    const apiKey = await ApiKey.findByKey(apiKeyValue);
    if (!apiKey) {
      return res.status(401).json({
        error: {
          message: '유효하지 않은 API 키입니다.',
          type: 'invalid_request_error',
          code: 'invalid_api_key',
        },
      });
    }
    // 만료 확인
    if (apiKey.isExpired()) {
      return res.status(401).json({
        error: {
          message: 'API 키가 만료되었습니다.',
          type: 'invalid_request_error',
          code: 'expired_api_key',
        },
      });
    }
    // 사용자 상태 확인
    if (apiKey.user.status !== 'active') {
      return res.status(403).json({
        error: {
          message: '계정이 비활성화되었습니다.',
          type: 'invalid_request_error',
          code: 'account_inactive',
        },
      });
    }
    // 사용 기록 업데이트
    await apiKey.recordUsage();
    // 요청 객체에 사용자 및 API 키 정보 추가
    req.user = {
      id: apiKey.user.id,
      userId: apiKey.user.id,
      email: apiKey.user.email,
      role: apiKey.user.role,
      plan: apiKey.user.plan,
    };
    req.apiKey = apiKey;
    return next();
  } catch (error) {
    logger.error('API 키 인증 오류:', error);
    return next(error);
  }
 };
 /**
 * 관리자 권한 확인 미들웨어
 */
 exports.requireAdmin = (req, res, next) => {
  if (req.user.role !== 'admin') {
    return res.status(403).json({
      success: false,
      error: {
        code: 'FORBIDDEN',
        message: '관리자 권한이 필요합니다.',
      },
    });
  }
  return next();
 };
 /**
 * JWT 또는 API 키 인증 미들웨어
 * JWT 토큰과 API 키 모두 허용
 */
 exports.authenticateAny = async (req, res, next) => {
  try {
    const authHeader = req.headers.authorization;
    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      return res.status(401).json({
        success: false,
        error: {
          code: 'UNAUTHORIZED',
          message: '인증이 필요합니다.',
        },
      });
    }
    const token = authHeader.substring(7);
    const prefix = process.env.API_KEY_PREFIX || 'sk-';
    // API 키인 경우
    if (token.startsWith(prefix)) {
      const apiKey = await ApiKey.findByKey(token);
      if (!apiKey) {
        return res.status(401).json({
          error: {
            message: '유효하지 않은 API 키입니다.',
            type: 'invalid_request_error',
            code: 'invalid_api_key',
          },
        });
      }
      if (apiKey.isExpired()) {
        return res.status(401).json({
          error: {
            message: 'API 키가 만료되었습니다.',
            type: 'invalid_request_error',
            code: 'expired_api_key',
          },
        });
      }
      if (apiKey.user.status !== 'active') {
        return res.status(403).json({
          error: {
            message: '계정이 비활성화되었습니다.',
            type: 'invalid_request_error',
            code: 'account_inactive',
          },
        });
      }
      await apiKey.recordUsage();
      req.user = {
        id: apiKey.user.id,
        userId: apiKey.user.id,
        email: apiKey.user.email,
        role: apiKey.user.role,
        plan: apiKey.user.plan,
      };
      req.apiKey = apiKey;
      return next();
    }
    // JWT 토큰인 경우
    try {
      const decoded = jwt.verify(token, JWT_SECRET);
      req.user = decoded;
      return next();
    } catch (error) {
      if (error.name === 'TokenExpiredError') {
        return res.status(401).json({
          success: false,
          error: {
            code: 'TOKEN_EXPIRED',
            message: '토큰이 만료되었습니다.',
          },
        });
      }
      return res.status(401).json({
        success: false,
        error: {
          code: 'INVALID_TOKEN',
          message: '유효하지 않은 토큰입니다.',
        },
      });
    }
  } catch (error) {
    return next(error);
  }
 };
--- a/ai-assistant/src/middlewares/error-handler.middleware.js
+++ b/ai-assistant/src/middlewares/error-handler.middleware.js
@ -1,80 +0,0 @@
 // src/middlewares/error-handler.middleware.js
 // 에러 핸들러 미들웨어
 const logger = require('../config/logger.config');
 /**
 * 전역 에러 핸들러
 */
 module.exports = (err, req, res, _next) => {
  // 에러 로깅
  logger.error('에러 발생:', {
    message: err.message,
    stack: err.stack,
    path: req.path,
    method: req.method,
  });
  // Sequelize 유효성 검사 에러
  if (err.name === 'SequelizeValidationError') {
    return res.status(400).json({
      success: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: '데이터 유효성 검사 실패',
        details: err.errors.map((e) => ({
          field: e.path,
          message: e.message,
        })),
      },
    });
  }
  // Sequelize 고유 제약 조건 에러
  if (err.name === 'SequelizeUniqueConstraintError') {
    return res.status(409).json({
      success: false,
      error: {
        code: 'DUPLICATE_ENTRY',
        message: '중복된 데이터가 존재합니다.',
        details: err.errors.map((e) => ({
          field: e.path,
          message: e.message,
        })),
      },
    });
  }
  // JWT 에러
  if (err.name === 'JsonWebTokenError') {
    return res.status(401).json({
      success: false,
      error: {
        code: 'INVALID_TOKEN',
        message: '유효하지 않은 토큰입니다.',
      },
    });
  }
  // 기본 에러 응답
  const statusCode = err.statusCode || 500;
  const message = err.message || '서버 오류가 발생했습니다.';
  // 프로덕션 환경에서는 상세 에러 숨김
  const response = {
    success: false,
    error: {
      code: err.code || 'INTERNAL_ERROR',
      message: process.env.NODE_ENV === 'production' && statusCode === 500
        ? '서버 오류가 발생했습니다.'
        : message,
    },
  };
  // 개발 환경에서는 스택 트레이스 포함
  if (process.env.NODE_ENV === 'development') {
    response.error.stack = err.stack;
  }
  return res.status(statusCode).json(response);
 };
--- a/ai-assistant/src/middlewares/usage-logger.middleware.js
+++ b/ai-assistant/src/middlewares/usage-logger.middleware.js
@ -1,50 +0,0 @@
 // src/middlewares/usage-logger.middleware.js
 // 사용량 로깅 미들웨어
 const { UsageLog } = require('../models');
 const logger = require('../config/logger.config');
 /**
 * 사용량 로깅 미들웨어
 * 응답 완료 후 사용량 정보를 데이터베이스에 저장
 */
 exports.usageLogger = (req, res, next) => {
  // 응답 완료 후 처리
  res.on('finish', async () => {
    try {
      // 사용량 데이터가 없으면 스킵
      if (!req.usageData) {
        return;
      }
      const usageData = {
        userId: req.user?.id || req.user?.userId,
        apiKeyId: req.apiKey?.id || null,
        providerId: req.usageData.providerId || null,
        providerName: req.usageData.providerName || null,
        modelName: req.usageData.modelName || null,
        promptTokens: req.usageData.promptTokens || 0,
        completionTokens: req.usageData.completionTokens || 0,
        totalTokens: req.usageData.totalTokens || 0,
        costUsd: req.usageData.costUsd || 0,
        responseTimeMs: req.usageData.responseTimeMs || null,
        success: req.usageData.success !== false,
        errorMessage: req.usageData.errorMessage || null,
        requestIp: req.ip || req.connection?.remoteAddress,
        userAgent: req.headers['user-agent'] || null,
      };
      await UsageLog.create(usageData);
      logger.debug('사용량 로그 저장:', {
        userId: usageData.userId,
        tokens: usageData.totalTokens,
        cost: usageData.costUsd,
      });
    } catch (error) {
      logger.error('사용량 로그 저장 실패:', error);
    }
  });
  next();
 };
--- a/ai-assistant/src/middlewares/validation.middleware.js
+++ b/ai-assistant/src/middlewares/validation.middleware.js
@ -1,30 +0,0 @@
 // src/middlewares/validation.middleware.js
 // 유효성 검사 미들웨어
 const { validationResult } = require('express-validator');
 /**
 * 요청 유효성 검사 결과 처리
 */
 exports.validateRequest = (req, res, next) => {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    const formattedErrors = errors.array().map((error) => ({
      field: error.path,
      message: error.msg,
      value: error.value,
    }));
    return res.status(400).json({
      success: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: '입력값이 올바르지 않습니다.',
        details: formattedErrors,
      },
    });
  }
  return next();
 };
--- a/ai-assistant/src/models/api-key.model.js
+++ b/ai-assistant/src/models/api-key.model.js
@ -1,130 +0,0 @@
 // src/models/api-key.model.js
 // API 키 모델
 const { DataTypes } = require('sequelize');
 const crypto = require('crypto');
 module.exports = (sequelize) => {
  const ApiKey = sequelize.define('ApiKey', {
    id: {
      type: DataTypes.UUID,
      defaultValue: DataTypes.UUIDV4,
      primaryKey: true,
    },
    userId: {
      type: DataTypes.UUID,
      allowNull: false,
      references: {
        model: 'users',
        key: 'id',
      },
      comment: '소유자 사용자 ID',
    },
    name: {
      type: DataTypes.STRING(100),
      allowNull: false,
      comment: 'API 키 이름 (사용자 지정)',
    },
    keyPrefix: {
      type: DataTypes.STRING(12),
      allowNull: false,
      comment: 'API 키 접두사 (표시용)',
    },
    keyHash: {
      type: DataTypes.STRING(64),
      allowNull: false,
      unique: true,
      comment: 'API 키 해시 (SHA-256)',
    },
    permissions: {
      type: DataTypes.JSONB,
      defaultValue: ['chat:read', 'chat:write'],
      comment: '권한 목록',
    },
    rateLimit: {
      type: DataTypes.INTEGER,
      defaultValue: 60, // 분당 60회
      comment: '분당 요청 제한',
    },
    status: {
      type: DataTypes.ENUM('active', 'revoked', 'expired'),
      defaultValue: 'active',
      comment: 'API 키 상태',
    },
    expiresAt: {
      type: DataTypes.DATE,
      allowNull: true,
      comment: '만료 일시 (null이면 무기한)',
    },
    lastUsedAt: {
      type: DataTypes.DATE,
      allowNull: true,
      comment: '마지막 사용 시간',
    },
    totalRequests: {
      type: DataTypes.INTEGER,
      defaultValue: 0,
      comment: '총 요청 수',
    },
  }, {
    tableName: 'api_keys',
    timestamps: true,
    underscored: true,
    indexes: [
      {
        fields: ['key_hash'],
        unique: true,
      },
      {
        fields: ['user_id'],
      },
      {
        fields: ['status'],
      },
    ],
  });
  // 클래스 메서드: API 키 생성
  ApiKey.generateKey = function() {
    const prefix = process.env.API_KEY_PREFIX || 'sk-';
    const length = parseInt(process.env.API_KEY_LENGTH, 10) || 48;
    const randomPart = crypto.randomBytes(length).toString('base64url').slice(0, length);
    return `${prefix}${randomPart}`;
  };
  // 클래스 메서드: API 키 해시 생성
  ApiKey.hashKey = function(key) {
    return crypto.createHash('sha256').update(key).digest('hex');
  };
  // 클래스 메서드: API 키로 조회
  ApiKey.findByKey = async function(key) {
    const keyHash = this.hashKey(key);
    const apiKey = await this.findOne({
      where: { keyHash, status: 'active' },
    });
    if (apiKey) {
      // 사용자 정보 별도 조회
      const { User } = require('./index');
      apiKey.user = await User.findByPk(apiKey.userId);
    }
    return apiKey;
  };
  // 인스턴스 메서드: 사용 기록 업데이트
  ApiKey.prototype.recordUsage = async function() {
    this.lastUsedAt = new Date();
    this.totalRequests += 1;
    await this.save();
  };
  // 인스턴스 메서드: 만료 여부 확인
  ApiKey.prototype.isExpired = function() {
    if (!this.expiresAt) return false;
    return new Date() > this.expiresAt;
  };
  return ApiKey;
 };
--- a/ai-assistant/src/models/index.js
+++ b/ai-assistant/src/models/index.js
@ -1,55 +0,0 @@
 // src/models/index.js
 // Sequelize 모델 인덱스
 const { Sequelize } = require('sequelize');
 const config = require('../config/database.config');
 const env = process.env.NODE_ENV || 'development';
 const dbConfig = config[env];
 // Sequelize 인스턴스 생성
 const sequelize = new Sequelize(
  dbConfig.database,
  dbConfig.username,
  dbConfig.password,
  {
    host: dbConfig.host,
    port: dbConfig.port,
    dialect: dbConfig.dialect,
    logging: dbConfig.logging,
    pool: dbConfig.pool,
    dialectOptions: dbConfig.dialectOptions,
  }
 );
 // 모델 임포트
 const User = require('./user.model')(sequelize);
 const ApiKey = require('./api-key.model')(sequelize);
 const UsageLog = require('./usage-log.model')(sequelize);
 const LLMProvider = require('./llm-provider.model')(sequelize);
 // 관계 설정
 // User - ApiKey (1:N)
 User.hasMany(ApiKey, { foreignKey: 'userId', as: 'apiKeys' });
 ApiKey.belongsTo(User, { foreignKey: 'userId', as: 'user' });
 // User - UsageLog (1:N)
 User.hasMany(UsageLog, { foreignKey: 'userId', as: 'usageLogs' });
 UsageLog.belongsTo(User, { foreignKey: 'userId', as: 'user' });
 // ApiKey - UsageLog (1:N)
 ApiKey.hasMany(UsageLog, { foreignKey: 'apiKeyId', as: 'usageLogs' });
 UsageLog.belongsTo(ApiKey, { foreignKey: 'apiKeyId', as: 'apiKey' });
 // LLMProvider - UsageLog (1:N)
 LLMProvider.hasMany(UsageLog, { foreignKey: 'providerId', as: 'usageLogs' });
 UsageLog.belongsTo(LLMProvider, { foreignKey: 'providerId', as: 'provider' });
 module.exports = {
  sequelize,
  Sequelize,
  User,
  ApiKey,
  UsageLog,
  LLMProvider,
 };
--- a/ai-assistant/src/models/llm-provider.model.js
+++ b/ai-assistant/src/models/llm-provider.model.js
@ -1,143 +0,0 @@
 // src/models/llm-provider.model.js
 // LLM 프로바이더 모델
 const { DataTypes } = require('sequelize');
 module.exports = (sequelize) => {
  const LLMProvider = sequelize.define('LLMProvider', {
    id: {
      type: DataTypes.UUID,
      defaultValue: DataTypes.UUIDV4,
      primaryKey: true,
    },
    name: {
      type: DataTypes.STRING(50),
      allowNull: false,
      unique: true,
      comment: '프로바이더 이름 (gemini, openai, claude 등)',
    },
    displayName: {
      type: DataTypes.STRING(100),
      allowNull: false,
      comment: '표시 이름',
    },
    endpoint: {
      type: DataTypes.STRING(500),
      allowNull: true,
      comment: 'API 엔드포인트 URL',
    },
    apiKey: {
      type: DataTypes.TEXT,
      allowNull: true,
      comment: 'API 키 (암호화 저장 권장)',
    },
    modelName: {
      type: DataTypes.STRING(100),
      allowNull: false,
      comment: '기본 모델 이름',
    },
    priority: {
      type: DataTypes.INTEGER,
      defaultValue: 100,
      comment: '우선순위 (낮을수록 우선)',
    },
    maxTokens: {
      type: DataTypes.INTEGER,
      defaultValue: 4096,
      comment: '최대 토큰 수',
    },
    temperature: {
      type: DataTypes.FLOAT,
      defaultValue: 0.7,
      comment: '기본 온도',
    },
    timeoutMs: {
      type: DataTypes.INTEGER,
      defaultValue: 60000,
      comment: '타임아웃 (밀리초)',
    },
    costPer1kInputTokens: {
      type: DataTypes.DECIMAL(10, 6),
      defaultValue: 0,
      comment: '입력 토큰 1K당 비용 (USD)',
    },
    costPer1kOutputTokens: {
      type: DataTypes.DECIMAL(10, 6),
      defaultValue: 0,
      comment: '출력 토큰 1K당 비용 (USD)',
    },
    isActive: {
      type: DataTypes.BOOLEAN,
      defaultValue: true,
      comment: '활성화 여부',
    },
    isHealthy: {
      type: DataTypes.BOOLEAN,
      defaultValue: true,
      comment: '건강 상태',
    },
    lastHealthCheck: {
      type: DataTypes.DATE,
      allowNull: true,
      comment: '마지막 헬스 체크 시간',
    },
    healthCheckUrl: {
      type: DataTypes.STRING(500),
      allowNull: true,
      comment: '헬스 체크 URL',
    },
    config: {
      type: DataTypes.JSONB,
      defaultValue: {},
      comment: '추가 설정',
    },
  }, {
    tableName: 'llm_providers',
    timestamps: true,
    underscored: true,
    indexes: [
      {
        fields: ['name'],
        unique: true,
      },
      {
        fields: ['priority'],
      },
      {
        fields: ['is_active', 'is_healthy'],
      },
    ],
  });
  // 클래스 메서드: 활성 프로바이더 목록 조회 (우선순위 순)
  LLMProvider.getActiveProviders = async function() {
    return this.findAll({
      where: { isActive: true },
      order: [['priority', 'ASC']],
    });
  };
  // 클래스 메서드: 건강한 프로바이더 목록 조회
  LLMProvider.getHealthyProviders = async function() {
    return this.findAll({
      where: { isActive: true, isHealthy: true },
      order: [['priority', 'ASC']],
    });
  };
  // 인스턴스 메서드: 헬스 상태 업데이트
  LLMProvider.prototype.updateHealth = async function(isHealthy) {
    this.isHealthy = isHealthy;
    this.lastHealthCheck = new Date();
    await this.save();
  };
  // 인스턴스 메서드: 비용 계산
  LLMProvider.prototype.calculateCost = function(promptTokens, completionTokens) {
    const inputCost = (promptTokens / 1000) * parseFloat(this.costPer1kInputTokens || 0);
    const outputCost = (completionTokens / 1000) * parseFloat(this.costPer1kOutputTokens || 0);
    return inputCost + outputCost;
  };
  return LLMProvider;
 };
--- a/ai-assistant/src/models/usage-log.model.js
+++ b/ai-assistant/src/models/usage-log.model.js
@ -1,164 +0,0 @@
 // src/models/usage-log.model.js
 // 사용량 로그 모델
 const { DataTypes, Op } = require('sequelize');
 module.exports = (sequelize) => {
  const UsageLog = sequelize.define('UsageLog', {
    id: {
      type: DataTypes.UUID,
      defaultValue: DataTypes.UUIDV4,
      primaryKey: true,
    },
    userId: {
      type: DataTypes.UUID,
      allowNull: false,
      references: {
        model: 'users',
        key: 'id',
      },
      comment: '사용자 ID',
    },
    apiKeyId: {
      type: DataTypes.UUID,
      allowNull: true,
      references: {
        model: 'api_keys',
        key: 'id',
      },
      comment: 'API 키 ID',
    },
    providerId: {
      type: DataTypes.UUID,
      allowNull: true,
      references: {
        model: 'llm_providers',
        key: 'id',
      },
      comment: 'LLM 프로바이더 ID',
    },
    providerName: {
      type: DataTypes.STRING(50),
      allowNull: true,
      comment: 'LLM 프로바이더 이름',
    },
    modelName: {
      type: DataTypes.STRING(100),
      allowNull: true,
      comment: '사용된 모델 이름',
    },
    promptTokens: {
      type: DataTypes.INTEGER,
      defaultValue: 0,
      comment: '프롬프트 토큰 수',
    },
    completionTokens: {
      type: DataTypes.INTEGER,
      defaultValue: 0,
      comment: '완성 토큰 수',
    },
    totalTokens: {
      type: DataTypes.INTEGER,
      defaultValue: 0,
      comment: '총 토큰 수',
    },
    costUsd: {
      type: DataTypes.DECIMAL(10, 6),
      defaultValue: 0,
      comment: '비용 (USD)',
    },
    responseTimeMs: {
      type: DataTypes.INTEGER,
      allowNull: true,
      comment: '응답 시간 (밀리초)',
    },
    success: {
      type: DataTypes.BOOLEAN,
      defaultValue: true,
      comment: '성공 여부',
    },
    errorMessage: {
      type: DataTypes.TEXT,
      allowNull: true,
      comment: '에러 메시지',
    },
    requestIp: {
      type: DataTypes.STRING(45),
      allowNull: true,
      comment: '요청 IP 주소',
    },
    userAgent: {
      type: DataTypes.STRING(500),
      allowNull: true,
      comment: 'User-Agent',
    },
  }, {
    tableName: 'usage_logs',
    timestamps: true,
    underscored: true,
    indexes: [
      {
        fields: ['user_id'],
      },
      {
        fields: ['api_key_id'],
      },
      {
        fields: ['created_at'],
      },
      {
        fields: ['provider_name'],
      },
    ],
  });
  // 클래스 메서드: 사용자별 일별 사용량 조회
  UsageLog.getDailyUsageByUser = async function(userId, startDate, endDate) {
    return this.findAll({
      where: {
        userId,
        createdAt: {
          [Op.between]: [startDate, endDate],
        },
      },
      attributes: [
        [sequelize.fn('DATE', sequelize.col('created_at')), 'date'],
        [sequelize.fn('SUM', sequelize.col('total_tokens')), 'totalTokens'],
        [sequelize.fn('SUM', sequelize.col('cost_usd')), 'totalCost'],
        [sequelize.fn('COUNT', sequelize.col('id')), 'requestCount'],
      ],
      group: [sequelize.fn('DATE', sequelize.col('created_at'))],
      order: [[sequelize.fn('DATE', sequelize.col('created_at')), 'ASC']],
      raw: true,
    });
  };
  // 클래스 메서드: 사용자별 월간 총 사용량 조회
  UsageLog.getMonthlyTotalByUser = async function(userId, year, month) {
    const startDate = new Date(year, month - 1, 1);
    const endDate = new Date(year, month, 0, 23, 59, 59);
    const result = await this.findOne({
      where: {
        userId,
        createdAt: {
          [Op.between]: [startDate, endDate],
        },
      },
      attributes: [
        [sequelize.fn('SUM', sequelize.col('total_tokens')), 'totalTokens'],
        [sequelize.fn('SUM', sequelize.col('cost_usd')), 'totalCost'],
        [sequelize.fn('COUNT', sequelize.col('id')), 'requestCount'],
      ],
      raw: true,
    });
    return {
      totalTokens: parseInt(result.totalTokens, 10) || 0,
      totalCost: parseFloat(result.totalCost) || 0,
      requestCount: parseInt(result.requestCount, 10) || 0,
    };
  };
  return UsageLog;
 };
--- a/ai-assistant/src/models/user.model.js
+++ b/ai-assistant/src/models/user.model.js
@ -1,92 +0,0 @@
 // src/models/user.model.js
 // 사용자 모델
 const { DataTypes } = require('sequelize');
 const bcrypt = require('bcryptjs');
 module.exports = (sequelize) => {
  const User = sequelize.define('User', {
    id: {
      type: DataTypes.UUID,
      defaultValue: DataTypes.UUIDV4,
      primaryKey: true,
    },
    email: {
      type: DataTypes.STRING(255),
      allowNull: false,
      unique: true,
      validate: {
        isEmail: true,
      },
      comment: '이메일 (로그인 ID)',
    },
    password: {
      type: DataTypes.STRING(255),
      allowNull: false,
      comment: '비밀번호 (해시)',
    },
    name: {
      type: DataTypes.STRING(100),
      allowNull: false,
      comment: '사용자 이름',
    },
    role: {
      type: DataTypes.ENUM('user', 'admin'),
      defaultValue: 'user',
      comment: '역할 (user: 일반 사용자, admin: 관리자)',
    },
    status: {
      type: DataTypes.ENUM('active', 'inactive', 'suspended'),
      defaultValue: 'active',
      comment: '계정 상태',
    },
    plan: {
      type: DataTypes.ENUM('free', 'basic', 'pro', 'enterprise'),
      defaultValue: 'free',
      comment: '요금제 플랜',
    },
    monthlyTokenLimit: {
      type: DataTypes.INTEGER,
      defaultValue: 100000, // 무료 플랜 기본 10만 토큰
      comment: '월간 토큰 한도',
    },
    lastLoginAt: {
      type: DataTypes.DATE,
      allowNull: true,
      comment: '마지막 로그인 시간',
    },
  }, {
    tableName: 'users',
    timestamps: true,
    underscored: true,
    hooks: {
      // 비밀번호 해싱
      beforeCreate: async (user) => {
        if (user.password) {
          const salt = await bcrypt.genSalt(10);
          user.password = await bcrypt.hash(user.password, salt);
        }
      },
      beforeUpdate: async (user) => {
        if (user.changed('password')) {
          const salt = await bcrypt.genSalt(10);
          user.password = await bcrypt.hash(user.password, salt);
        }
      },
    },
  });
  // 인스턴스 메서드: 비밀번호 검증
  User.prototype.validatePassword = async function(password) {
    return bcrypt.compare(password, this.password);
  };
  // 인스턴스 메서드: 안전한 JSON 변환 (비밀번호 제외)
  User.prototype.toSafeJSON = function() {
    const values = { ...this.get() };
    delete values.password;
    return values;
  };
  return User;
 };
--- a/ai-assistant/src/routes/admin.routes.js
+++ b/ai-assistant/src/routes/admin.routes.js
@ -1,151 +0,0 @@
 // src/routes/admin.routes.js
 // 관리자 라우트
 const express = require('express');
 const { body, param } = require('express-validator');
 const adminController = require('../controllers/admin.controller');
 const { authenticateJWT, requireAdmin } = require('../middlewares/auth.middleware');
 const { validateRequest } = require('../middlewares/validation.middleware');
 const router = express.Router();
 // 모든 라우트에 JWT 인증 + 관리자 권한 필요
 router.use(authenticateJWT);
 router.use(requireAdmin);
 // ===== LLM 프로바이더 관리 =====
 /**
 * GET /api/v1/admin/providers
 * LLM 프로바이더 목록 조회
 */
 router.get('/providers', adminController.getProviders);
 /**
 * POST /api/v1/admin/providers
 * LLM 프로바이더 추가
 */
 router.post(
  '/providers',
  [
    body('name')
      .trim()
      .isLength({ min: 1, max: 50 })
      .withMessage('프로바이더 이름은 1-50자 사이여야 합니다'),
    body('displayName')
      .trim()
      .isLength({ min: 1, max: 100 })
      .withMessage('표시 이름은 1-100자 사이여야 합니다'),
    body('modelName')
      .trim()
      .isLength({ min: 1, max: 100 })
      .withMessage('모델 이름은 1-100자 사이여야 합니다'),
    body('apiKey')
      .optional()
      .isString(),
    body('priority')
      .optional()
      .isInt({ min: 1, max: 100 }),
    validateRequest,
  ],
  adminController.createProvider
 );
 /**
 * PATCH /api/v1/admin/providers/:id
 * LLM 프로바이더 수정 (API 키 설정 포함)
 */
 router.patch(
  '/providers/:id',
  [
    param('id')
      .isUUID()
      .withMessage('유효한 프로바이더 ID가 아닙니다'),
    body('apiKey')
      .optional()
      .isString(),
    body('modelName')
      .optional()
      .isString(),
    body('isActive')
      .optional()
      .isBoolean(),
    body('priority')
      .optional()
      .isInt({ min: 1, max: 100 }),
    validateRequest,
  ],
  adminController.updateProvider
 );
 /**
 * DELETE /api/v1/admin/providers/:id
 * LLM 프로바이더 삭제
 */
 router.delete(
  '/providers/:id',
  [
    param('id')
      .isUUID()
      .withMessage('유효한 프로바이더 ID가 아닙니다'),
    validateRequest,
  ],
  adminController.deleteProvider
 );
 // ===== 사용자 관리 =====
 /**
 * GET /api/v1/admin/users
 * 사용자 목록 조회
 */
 router.get('/users', adminController.getUsers);
 /**
 * PATCH /api/v1/admin/users/:id
 * 사용자 정보 수정 (역할, 상태, 플랜 등)
 */
 router.patch(
  '/users/:id',
  [
    param('id')
      .isUUID()
      .withMessage('유효한 사용자 ID가 아닙니다'),
    body('role')
      .optional()
      .isIn(['user', 'admin']),
    body('status')
      .optional()
      .isIn(['active', 'inactive', 'suspended']),
    body('plan')
      .optional()
      .isIn(['free', 'basic', 'pro', 'enterprise']),
    body('monthlyTokenLimit')
      .optional()
      .isInt({ min: 0 }),
    validateRequest,
  ],
  adminController.updateUser
 );
 // ===== 시스템 통계 =====
 /**
 * GET /api/v1/admin/stats
 * 시스템 통계 조회
 */
 router.get('/stats', adminController.getStats);
 /**
 * GET /api/v1/admin/usage/by-user
 * 사용자별 사용량 통계
 */
 router.get('/usage/by-user', adminController.getUsageByUser);
 /**
 * GET /api/v1/admin/usage/by-provider
 * 프로바이더별 사용량 통계
 */
 router.get('/usage/by-provider', adminController.getUsageByProvider);
 module.exports = router;
--- a/ai-assistant/src/routes/api-key.routes.js
+++ b/ai-assistant/src/routes/api-key.routes.js
@ -1,99 +0,0 @@
 // src/routes/api-key.routes.js
 // API 키 라우트
 const express = require('express');
 const { body, param } = require('express-validator');
 const apiKeyController = require('../controllers/api-key.controller');
 const { authenticateJWT } = require('../middlewares/auth.middleware');
 const { validateRequest } = require('../middlewares/validation.middleware');
 const router = express.Router();
 // 모든 라우트에 JWT 인증 적용
 router.use(authenticateJWT);
 /**
 * POST /api/v1/api-keys
 * API 키 발급
 */
 router.post(
  '/',
  [
    body('name')
      .trim()
      .isLength({ min: 1, max: 100 })
      .withMessage('API 키 이름은 1-100자 사이여야 합니다'),
    body('expiresInDays')
      .optional()
      .isInt({ min: 1, max: 365 })
      .withMessage('만료 기간은 1-365일 사이여야 합니다'),
    body('permissions')
      .optional()
      .isArray()
      .withMessage('권한은 배열이어야 합니다'),
    validateRequest,
  ],
  apiKeyController.create
 );
 /**
 * GET /api/v1/api-keys
 * API 키 목록 조회
 */
 router.get('/', apiKeyController.list);
 /**
 * GET /api/v1/api-keys/:id
 * API 키 상세 조회
 */
 router.get(
  '/:id',
  [
    param('id')
      .isUUID()
      .withMessage('유효한 API 키 ID가 아닙니다'),
    validateRequest,
  ],
  apiKeyController.get
 );
 /**
 * PATCH /api/v1/api-keys/:id
 * API 키 수정
 */
 router.patch(
  '/:id',
  [
    param('id')
      .isUUID()
      .withMessage('유효한 API 키 ID가 아닙니다'),
    body('name')
      .optional()
      .trim()
      .isLength({ min: 1, max: 100 })
      .withMessage('API 키 이름은 1-100자 사이여야 합니다'),
    body('status')
      .optional()
      .isIn(['active', 'revoked'])
      .withMessage('상태는 active 또는 revoked여야 합니다'),
    validateRequest,
  ],
  apiKeyController.update
 );
 /**
 * DELETE /api/v1/api-keys/:id
 * API 키 폐기
 */
 router.delete(
  '/:id',
  [
    param('id')
      .isUUID()
      .withMessage('유효한 API 키 ID가 아닙니다'),
    validateRequest,
  ],
  apiKeyController.revoke
 );
 module.exports = router;
--- a/ai-assistant/src/routes/auth.routes.js
+++ b/ai-assistant/src/routes/auth.routes.js
@ -1,76 +0,0 @@
 // src/routes/auth.routes.js
 // 인증 라우트
 const express = require('express');
 const { body } = require('express-validator');
 const authController = require('../controllers/auth.controller');
 const { validateRequest } = require('../middlewares/validation.middleware');
 const router = express.Router();
 /**
 * POST /api/v1/auth/register
 * 회원가입
 */
 router.post(
  '/register',
  [
    body('email')
      .isEmail()
      .normalizeEmail()
      .withMessage('유효한 이메일 주소를 입력해주세요'),
    body('password')
      .isLength({ min: 8 })
      .withMessage('비밀번호는 최소 8자 이상이어야 합니다')
      .matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/)
      .withMessage('비밀번호는 대문자, 소문자, 숫자를 포함해야 합니다'),
    body('name')
      .trim()
      .isLength({ min: 2, max: 100 })
      .withMessage('이름은 2-100자 사이여야 합니다'),
    validateRequest,
  ],
  authController.register
 );
 /**
 * POST /api/v1/auth/login
 * 로그인
 */
 router.post(
  '/login',
  [
    body('email')
      .isEmail()
      .normalizeEmail()
      .withMessage('유효한 이메일 주소를 입력해주세요'),
    body('password')
      .notEmpty()
      .withMessage('비밀번호를 입력해주세요'),
    validateRequest,
  ],
  authController.login
 );
 /**
 * POST /api/v1/auth/refresh
 * 토큰 갱신
 */
 router.post(
  '/refresh',
  [
    body('refreshToken')
      .notEmpty()
      .withMessage('리프레시 토큰을 입력해주세요'),
    validateRequest,
  ],
  authController.refresh
 );
 /**
 * POST /api/v1/auth/logout
 * 로그아웃
 */
 router.post('/logout', authController.logout);
 module.exports = router;
--- a/ai-assistant/src/routes/chat.routes.js
+++ b/ai-assistant/src/routes/chat.routes.js
@ -1,55 +0,0 @@
 // src/routes/chat.routes.js
 // 채팅 API 라우트 (OpenAI 호환)
 const express = require('express');
 const { body } = require('express-validator');
 const chatController = require('../controllers/chat.controller');
 const { authenticateAny } = require('../middlewares/auth.middleware');
 const { validateRequest } = require('../middlewares/validation.middleware');
 const { usageLogger } = require('../middlewares/usage-logger.middleware');
 const router = express.Router();
 /**
 * POST /api/v1/chat/completions
 * 채팅 완성 API (OpenAI 호환)
 * 
 * 인증: Bearer API_KEY 또는 JWT 토큰
 */
 router.post(
  '/completions',
  authenticateAny,
  [
    body('model')
      .optional()
      .isString()
      .withMessage('모델은 문자열이어야 합니다'),
    body('messages')
      .isArray({ min: 1 })
      .withMessage('메시지 배열이 필요합니다'),
    body('messages.*.role')
      .isIn(['system', 'user', 'assistant'])
      .withMessage('메시지 역할은 system, user, assistant 중 하나여야 합니다'),
    body('messages.*.content')
      .isString()
      .notEmpty()
      .withMessage('메시지 내용이 필요합니다'),
    body('temperature')
      .optional()
      .isFloat({ min: 0, max: 2 })
      .withMessage('온도는 0-2 사이여야 합니다'),
    body('max_tokens')
      .optional()
      .isInt({ min: 1, max: 128000 })
      .withMessage('최대 토큰은 1-128000 사이여야 합니다'),
    body('stream')
      .optional()
      .isBoolean()
      .withMessage('스트림은 불리언이어야 합니다'),
    validateRequest,
  ],
  usageLogger,
  chatController.completions
 );
 module.exports = router;
--- a/ai-assistant/src/routes/index.js
+++ b/ai-assistant/src/routes/index.js
@ -1,45 +0,0 @@
 // src/routes/index.js
 // API 라우트 인덱스
 const express = require('express');
 const authRoutes = require('./auth.routes');
 const userRoutes = require('./user.routes');
 const apiKeyRoutes = require('./api-key.routes');
 const chatRoutes = require('./chat.routes');
 const usageRoutes = require('./usage.routes');
 const modelRoutes = require('./model.routes');
 const adminRoutes = require('./admin.routes');
 const router = express.Router();
 // API 정보
 router.get('/', (req, res) => {
  res.json({
    success: true,
    data: {
      name: 'AI Assistant API',
      version: '1.0.0',
      description: 'LLM API Platform - OpenAI 호환 API',
      endpoints: {
        auth: '/api/v1/auth',
        users: '/api/v1/users',
        apiKeys: '/api/v1/api-keys',
        chat: '/api/v1/chat',
        models: '/api/v1/models',
        usage: '/api/v1/usage',
      },
      documentation: 'https://docs.example.com',
    },
  });
 });
 // 라우트 등록
 router.use('/auth', authRoutes);
 router.use('/users', userRoutes);
 router.use('/api-keys', apiKeyRoutes);
 router.use('/chat', chatRoutes);
 router.use('/models', modelRoutes);
 router.use('/usage', usageRoutes);
 router.use('/admin', adminRoutes);
 module.exports = router;
--- a/ai-assistant/src/routes/model.routes.js
+++ b/ai-assistant/src/routes/model.routes.js
@ -1,24 +0,0 @@
 // src/routes/model.routes.js
 // 모델 라우트
 const express = require('express');
 const modelController = require('../controllers/model.controller');
 const { authenticateAny } = require('../middlewares/auth.middleware');
 const router = express.Router();
 /**
 * GET /api/v1/models
 * 사용 가능한 모델 목록 조회
 * JWT 토큰 또는 API 키로 인증
 */
 router.get('/', authenticateAny, modelController.list);
 /**
 * GET /api/v1/models/:id
 * 모델 상세 정보 조회
 * JWT 토큰 또는 API 키로 인증
 */
 router.get('/:id', authenticateAny, modelController.get);
 module.exports = router;
--- a/ai-assistant/src/routes/usage.routes.js
+++ b/ai-assistant/src/routes/usage.routes.js
@ -1,81 +0,0 @@
 // src/routes/usage.routes.js
 // 사용량 라우트
 const express = require('express');
 const { query } = require('express-validator');
 const usageController = require('../controllers/usage.controller');
 const { authenticateJWT } = require('../middlewares/auth.middleware');
 const { validateRequest } = require('../middlewares/validation.middleware');
 const router = express.Router();
 // 모든 라우트에 JWT 인증 적용
 router.use(authenticateJWT);
 /**
 * GET /api/v1/usage
 * 사용량 요약 조회
 */
 router.get('/', usageController.getSummary);
 /**
 * GET /api/v1/usage/daily
 * 일별 사용량 조회
 */
 router.get(
  '/daily',
  [
    query('startDate')
      .optional()
      .isISO8601()
      .withMessage('시작 날짜는 ISO 8601 형식이어야 합니다'),
    query('endDate')
      .optional()
      .isISO8601()
      .withMessage('종료 날짜는 ISO 8601 형식이어야 합니다'),
    validateRequest,
  ],
  usageController.getDailyUsage
 );
 /**
 * GET /api/v1/usage/monthly
 * 월별 사용량 조회
 */
 router.get(
  '/monthly',
  [
    query('year')
      .optional()
      .isInt({ min: 2020, max: 2100 })
      .withMessage('연도는 2020-2100 사이여야 합니다'),
    query('month')
      .optional()
      .isInt({ min: 1, max: 12 })
      .withMessage('월은 1-12 사이여야 합니다'),
    validateRequest,
  ],
  usageController.getMonthlyUsage
 );
 /**
 * GET /api/v1/usage/logs
 * 사용량 로그 목록 조회
 */
 router.get(
  '/logs',
  [
    query('page')
      .optional()
      .isInt({ min: 1 })
      .withMessage('페이지는 1 이상이어야 합니다'),
    query('limit')
      .optional()
      .isInt({ min: 1, max: 100 })
      .withMessage('한도는 1-100 사이여야 합니다'),
    validateRequest,
  ],
  usageController.getLogs
 );
 module.exports = router;
--- a/ai-assistant/src/routes/user.routes.js
+++ b/ai-assistant/src/routes/user.routes.js
@ -1,50 +0,0 @@
 // src/routes/user.routes.js
 // 사용자 라우트
 const express = require('express');
 const { body } = require('express-validator');
 const userController = require('../controllers/user.controller');
 const { authenticateJWT } = require('../middlewares/auth.middleware');
 const { validateRequest } = require('../middlewares/validation.middleware');
 const router = express.Router();
 // 모든 라우트에 JWT 인증 적용
 router.use(authenticateJWT);
 /**
 * GET /api/v1/users/me
 * 내 정보 조회
 */
 router.get('/me', userController.getMe);
 /**
 * PATCH /api/v1/users/me
 * 내 정보 수정
 */
 router.patch(
  '/me',
  [
    body('name')
      .optional()
      .trim()
      .isLength({ min: 2, max: 100 })
      .withMessage('이름은 2-100자 사이여야 합니다'),
    body('password')
      .optional()
      .isLength({ min: 8 })
      .withMessage('비밀번호는 최소 8자 이상이어야 합니다')
      .matches(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/)
      .withMessage('비밀번호는 대문자, 소문자, 숫자를 포함해야 합니다'),
    validateRequest,
  ],
  userController.updateMe
 );
 /**
 * DELETE /api/v1/users/me
 * 계정 삭제
 */
 router.delete('/me', userController.deleteMe);
 module.exports = router;
--- a/ai-assistant/src/seeders/001-llm-providers.js
+++ b/ai-assistant/src/seeders/001-llm-providers.js
@ -1,74 +0,0 @@
 // src/seeders/001-llm-providers.js
 // LLM 프로바이더 시드 데이터
 const { v4: uuidv4 } = require('uuid');
 module.exports = {
  up: async (queryInterface, Sequelize) => {
    const now = new Date();
    await queryInterface.bulkInsert('llm_providers', [
      {
        id: uuidv4(),
        name: 'gemini',
        display_name: 'Google Gemini',
        endpoint: null, // SDK 사용
        api_key: process.env.GEMINI_API_KEY || '',
        model_name: 'gemini-2.0-flash',
        priority: 1,
        max_tokens: 8192,
        temperature: 0.7,
        timeout_ms: 60000,
        cost_per_1k_input_tokens: 0.00025,
        cost_per_1k_output_tokens: 0.001,
        is_active: true,
        is_healthy: true,
        config: JSON.stringify({}),
        created_at: now,
        updated_at: now,
      },
      {
        id: uuidv4(),
        name: 'openai',
        display_name: 'OpenAI GPT',
        endpoint: 'https://api.openai.com/v1/chat/completions',
        api_key: process.env.OPENAI_API_KEY || '',
        model_name: 'gpt-4o-mini',
        priority: 2,
        max_tokens: 4096,
        temperature: 0.7,
        timeout_ms: 60000,
        cost_per_1k_input_tokens: 0.00015,
        cost_per_1k_output_tokens: 0.0006,
        is_active: true,
        is_healthy: true,
        config: JSON.stringify({}),
        created_at: now,
        updated_at: now,
      },
      {
        id: uuidv4(),
        name: 'claude',
        display_name: 'Anthropic Claude',
        endpoint: 'https://api.anthropic.com/v1/messages',
        api_key: process.env.CLAUDE_API_KEY || '',
        model_name: 'claude-3-haiku-20240307',
        priority: 3,
        max_tokens: 4096,
        temperature: 0.7,
        timeout_ms: 60000,
        cost_per_1k_input_tokens: 0.00025,
        cost_per_1k_output_tokens: 0.00125,
        is_active: true,
        is_healthy: true,
        config: JSON.stringify({}),
        created_at: now,
        updated_at: now,
      },
    ]);
  },
  down: async (queryInterface, Sequelize) => {
    await queryInterface.bulkDelete('llm_providers', null, {});
  },
 };
--- a/ai-assistant/src/services/init.service.js
+++ b/ai-assistant/src/services/init.service.js
@ -1,128 +0,0 @@
 // src/services/init.service.js
 // 초기 데이터 설정 서비스
 const { User, LLMProvider } = require('../models');
 const logger = require('../config/logger.config');
 /**
 * 초기 관리자 계정 생성
 */
 async function createDefaultAdmin() {
  try {
    const adminEmail = process.env.ADMIN_EMAIL || 'admin@admin.com';
    const adminPassword = process.env.ADMIN_PASSWORD || 'Admin123!';
    const existing = await User.findOne({ where: { email: adminEmail } });
    if (existing) {
      logger.info(`관리자 계정 이미 존재: ${adminEmail}`);
      return existing;
    }
    const admin = await User.create({
      email: adminEmail,
      password: adminPassword,
      name: '관리자',
      role: 'admin',
      status: 'active',
      plan: 'enterprise',
      monthlyTokenLimit: 10000000, // 1000만 토큰
    });
    logger.info(`✅ 기본 관리자 계정 생성: ${adminEmail}`);
    return admin;
  } catch (error) {
    logger.error('관리자 계정 생성 실패:', error);
    throw error;
  }
 }
 /**
 * 기본 LLM 프로바이더 생성
 */
 async function createDefaultProviders() {
  try {
    const providers = [
      {
        name: 'gemini',
        displayName: 'Google Gemini',
        endpoint: null,
        apiKey: process.env.GEMINI_API_KEY || '',
        modelName: process.env.GEMINI_MODEL || 'gemini-2.0-flash',
        priority: 1,
        maxTokens: 8192,
        temperature: 0.7,
        timeoutMs: 60000,
        costPer1kInputTokens: 0.00025,
        costPer1kOutputTokens: 0.001,
      },
      {
        name: 'openai',
        displayName: 'OpenAI GPT',
        endpoint: 'https://api.openai.com/v1/chat/completions',
        apiKey: process.env.OPENAI_API_KEY || '',
        modelName: process.env.OPENAI_MODEL || 'gpt-4o-mini',
        priority: 2,
        maxTokens: 4096,
        temperature: 0.7,
        timeoutMs: 60000,
        costPer1kInputTokens: 0.00015,
        costPer1kOutputTokens: 0.0006,
      },
      {
        name: 'claude',
        displayName: 'Anthropic Claude',
        endpoint: 'https://api.anthropic.com/v1/messages',
        apiKey: process.env.CLAUDE_API_KEY || '',
        modelName: process.env.CLAUDE_MODEL || 'claude-3-haiku-20240307',
        priority: 3,
        maxTokens: 4096,
        temperature: 0.7,
        timeoutMs: 60000,
        costPer1kInputTokens: 0.00025,
        costPer1kOutputTokens: 0.00125,
      },
    ];
    for (const providerData of providers) {
      const existing = await LLMProvider.findOne({ where: { name: providerData.name } });
      if (existing) {
        // API 키가 환경변수에 설정되어 있고 DB에는 없으면 업데이트
        if (providerData.apiKey && !existing.apiKey) {
          existing.apiKey = providerData.apiKey;
          existing.modelName = providerData.modelName;
          await existing.save();
          logger.info(`LLM 프로바이더 API 키 업데이트: ${providerData.name}`);
        }
        continue;
      }
      await LLMProvider.create({
        ...providerData,
        isActive: true,
        isHealthy: !!providerData.apiKey, // API 키가 있으면 healthy
      });
      logger.info(`✅ LLM 프로바이더 생성: ${providerData.name} (${providerData.modelName})`);
    }
  } catch (error) {
    logger.error('LLM 프로바이더 생성 실패:', error);
    throw error;
  }
 }
 /**
 * 초기화 실행
 */
 async function initialize() {
  logger.info('🔧 초기 데이터 설정 시작...');
  await createDefaultAdmin();
  await createDefaultProviders();
  logger.info('✅ 초기 데이터 설정 완료');
 }
 module.exports = {
  initialize,
  createDefaultAdmin,
  createDefaultProviders,
 };
--- a/ai-assistant/src/services/llm.service.js
+++ b/ai-assistant/src/services/llm.service.js
@ -1,385 +0,0 @@
 // src/services/llm.service.js
 // LLM 서비스 - 멀티 프로바이더 지원
 const axios = require('axios');
 const { LLMProvider } = require('../models');
 const logger = require('../config/logger.config');
 class LLMService {
  constructor() {
    this.providers = [];
    this.initialized = false;
  }
  /**
   * 서비스 초기화
   */
  async initialize() {
    if (this.initialized) return;
    try {
      await this.loadProviders();
      this.initialized = true;
      logger.info('✅ LLM 서비스 초기화 완료');
    } catch (error) {
      logger.error('❌ LLM 서비스 초기화 실패:', error);
      // 초기화 실패 시 기본 프로바이더 사용
      this.providers = this.getDefaultProviders();
      this.initialized = true;
    }
  }
  /**
   * 데이터베이스에서 프로바이더 로드
   */
  async loadProviders() {
    try {
      const providers = await LLMProvider.getHealthyProviders();
      if (providers.length === 0) {
        logger.warn('⚠️ 활성 프로바이더가 없습니다. 기본 프로바이더 사용');
        this.providers = this.getDefaultProviders();
      } else {
        this.providers = providers.map((p) => ({
          id: p.id,
          name: p.name,
          endpoint: p.endpoint,
          apiKey: p.apiKey,
          modelName: p.modelName,
          priority: p.priority,
          maxTokens: p.maxTokens,
          temperature: p.temperature,
          timeoutMs: p.timeoutMs,
          costPer1kInputTokens: parseFloat(p.costPer1kInputTokens) || 0,
          costPer1kOutputTokens: parseFloat(p.costPer1kOutputTokens) || 0,
          isHealthy: p.isHealthy,
          config: p.config,
        }));
      }
      logger.info(`📥 ${this.providers.length}개 프로바이더 로드됨`);
    } catch (error) {
      logger.error('프로바이더 로드 실패:', error);
      throw error;
    }
  }
  /**
   * 기본 프로바이더 설정 (환경 변수 기반)
   */
  getDefaultProviders() {
    const providers = [];
    // Gemini
    if (process.env.GEMINI_API_KEY) {
      providers.push({
        id: 'default-gemini',
        name: 'gemini',
        apiKey: process.env.GEMINI_API_KEY,
        modelName: process.env.GEMINI_MODEL || 'gemini-2.0-flash',
        priority: 1,
        maxTokens: 8192,
        temperature: 0.7,
        timeoutMs: 60000,
        costPer1kInputTokens: 0.00025,
        costPer1kOutputTokens: 0.001,
        isHealthy: true,
      });
    }
    // OpenAI
    if (process.env.OPENAI_API_KEY) {
      providers.push({
        id: 'default-openai',
        name: 'openai',
        endpoint: 'https://api.openai.com/v1/chat/completions',
        apiKey: process.env.OPENAI_API_KEY,
        modelName: process.env.OPENAI_MODEL || 'gpt-4o-mini',
        priority: 2,
        maxTokens: 4096,
        temperature: 0.7,
        timeoutMs: 60000,
        costPer1kInputTokens: 0.00015,
        costPer1kOutputTokens: 0.0006,
        isHealthy: true,
      });
    }
    // Claude
    if (process.env.CLAUDE_API_KEY) {
      providers.push({
        id: 'default-claude',
        name: 'claude',
        endpoint: 'https://api.anthropic.com/v1/messages',
        apiKey: process.env.CLAUDE_API_KEY,
        modelName: process.env.CLAUDE_MODEL || 'claude-3-haiku-20240307',
        priority: 3,
        maxTokens: 4096,
        temperature: 0.7,
        timeoutMs: 60000,
        costPer1kInputTokens: 0.00025,
        costPer1kOutputTokens: 0.00125,
        isHealthy: true,
      });
    }
    return providers;
  }
  /**
   * 채팅 API 호출 (자동 fallback)
   */
  async chat(params) {
    const {
      model,
      messages,
      temperature = 0.7,
      maxTokens = 4096,
      userId,
      apiKeyId,
    } = params;
    // 초기화 확인
    if (!this.initialized) {
      await this.initialize();
    }
    const startTime = Date.now();
    let lastError = null;
    // 요청된 모델에 맞는 프로바이더 찾기
    const requestedProvider = this.providers.find(
      (p) => p.modelName === model || p.name === model
    );
    // 우선순위 순으로 프로바이더 정렬
    const sortedProviders = requestedProvider
      ? [requestedProvider, ...this.providers.filter((p) => p !== requestedProvider)]
      : this.providers;
    // 프로바이더 순회 (fallback)
    for (const provider of sortedProviders) {
      if (!provider.isHealthy) {
        logger.warn(`⚠️ ${provider.name} 건강하지 않음, 건너뜀`);
        continue;
      }
      try {
        logger.info(`🚀 ${provider.name} (${provider.modelName}) 시도 중...`);
        const result = await this.callProvider(provider, {
          messages,
          maxTokens: maxTokens || provider.maxTokens,
          temperature: temperature || provider.temperature,
        });
        const responseTime = Date.now() - startTime;
        // 비용 계산
        const cost = this.calculateCost(
          result.usage.promptTokens,
          result.usage.completionTokens,
          provider.costPer1kInputTokens,
          provider.costPer1kOutputTokens
        );
        logger.info(
          `✅ ${provider.name} 성공 (${responseTime}ms, ${result.usage.totalTokens} tokens)`
        );
        return {
          text: result.text,
          provider: provider.name,
          providerId: provider.id,
          model: provider.modelName,
          usage: result.usage,
          responseTime,
          cost,
        };
      } catch (error) {
        logger.error(`❌ ${provider.name} 실패:`, error.message);
        lastError = error;
        // 다음 프로바이더로 fallback
        continue;
      }
    }
    // 모든 프로바이더 실패
    throw new Error(
      `모든 LLM 프로바이더가 실패했습니다: ${lastError?.message || '알 수 없는 오류'}`
    );
  }
  /**
   * 개별 프로바이더 호출
   */
  async callProvider(provider, { messages, maxTokens, temperature }) {
    const timeout = provider.timeoutMs || 60000;
    switch (provider.name) {
      case 'gemini':
        return this.callGemini(provider, { messages, maxTokens, temperature });
      case 'openai':
        return this.callOpenAI(provider, { messages, maxTokens, temperature, timeout });
      case 'claude':
        return this.callClaude(provider, { messages, maxTokens, temperature, timeout });
      default:
        throw new Error(`지원하지 않는 프로바이더: ${provider.name}`);
    }
  }
  /**
   * Gemini API 호출
   */
  async callGemini(provider, { messages, maxTokens, temperature }) {
    const { GoogleGenAI } = require('@google/genai');
    const ai = new GoogleGenAI({ apiKey: provider.apiKey });
    // 메시지 변환 (OpenAI 형식 -> Gemini 형식)
    const contents = messages.map((msg) => ({
      role: msg.role === 'assistant' ? 'model' : 'user',
      parts: [{ text: msg.content }],
    }));
    // system 메시지 처리
    const systemMessage = messages.find((m) => m.role === 'system');
    const systemInstruction = systemMessage ? systemMessage.content : undefined;
    const config = {
      maxOutputTokens: maxTokens,
      temperature,
    };
    const result = await ai.models.generateContent({
      model: provider.modelName,
      contents: contents.filter((c) => c.role !== 'system'),
      systemInstruction,
      config,
    });
    // 응답 텍스트 추출
    let text = '';
    if (result.candidates?.[0]?.content?.parts) {
      text = result.candidates[0].content.parts
        .filter((p) => p.text)
        .map((p) => p.text)
        .join('\n');
    }
    const usage = result.usageMetadata || {};
    const promptTokens = usage.promptTokenCount ?? 0;
    const completionTokens = usage.candidatesTokenCount ?? 0;
    return {
      text,
      usage: {
        promptTokens,
        completionTokens,
        totalTokens: promptTokens + completionTokens,
      },
    };
  }
  /**
   * OpenAI API 호출
   */
  async callOpenAI(provider, { messages, maxTokens, temperature, timeout }) {
    const response = await axios.post(
      provider.endpoint,
      {
        model: provider.modelName,
        messages,
        max_tokens: maxTokens,
        temperature,
      },
      {
        timeout,
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${provider.apiKey}`,
        },
      }
    );
    return {
      text: response.data.choices[0].message.content,
      usage: {
        promptTokens: response.data.usage.prompt_tokens,
        completionTokens: response.data.usage.completion_tokens,
        totalTokens: response.data.usage.total_tokens,
      },
    };
  }
  /**
   * Claude API 호출
   */
  async callClaude(provider, { messages, maxTokens, temperature, timeout }) {
    // system 메시지 분리
    const systemMessage = messages.find((m) => m.role === 'system');
    const otherMessages = messages.filter((m) => m.role !== 'system');
    const response = await axios.post(
      provider.endpoint,
      {
        model: provider.modelName,
        messages: otherMessages,
        system: systemMessage?.content,
        max_tokens: maxTokens,
        temperature,
      },
      {
        timeout,
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': provider.apiKey,
          'anthropic-version': '2023-06-01',
        },
      }
    );
    return {
      text: response.data.content[0].text,
      usage: {
        promptTokens: response.data.usage.input_tokens,
        completionTokens: response.data.usage.output_tokens,
        totalTokens:
          response.data.usage.input_tokens + response.data.usage.output_tokens,
      },
    };
  }
  /**
   * 스트리밍 채팅 (제너레이터)
   */
  async *chatStream(params) {
    // 현재는 간단한 구현 (전체 응답 후 청크로 분할)
    // 실제 스트리밍은 각 프로바이더의 스트리밍 API 사용 필요
    const result = await this.chat(params);
    // 텍스트를 청크로 분할하여 전송
    const chunkSize = 10;
    for (let i = 0; i < result.text.length; i += chunkSize) {
      yield {
        text: result.text.slice(i, i + chunkSize),
        done: i + chunkSize >= result.text.length,
      };
    }
  }
  /**
   * 비용 계산
   */
  calculateCost(promptTokens, completionTokens, inputCost, outputCost) {
    const inputTotal = (promptTokens / 1000) * inputCost;
    const outputTotal = (completionTokens / 1000) * outputCost;
    return parseFloat((inputTotal + outputTotal).toFixed(6));
  }
 }
 // 싱글톤 인스턴스
 const llmService = new LLMService();
 module.exports = llmService;
--- a/ai-assistant/src/swagger/api-docs.js
+++ b/ai-assistant/src/swagger/api-docs.js
@ -1,359 +0,0 @@
 // src/swagger/api-docs.js
 // Swagger API 문서 정의
 /**
 * @swagger
 * /auth/register:
 *   post:
 *     tags: [Auth]
 *     summary: 회원가입
 *     description: 새 계정을 생성합니다.
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required: [email, password, name]
 *             properties:
 *               email:
 *                 type: string
 *                 format: email
 *                 example: user@example.com
 *               password:
 *                 type: string
 *                 minLength: 8
 *                 example: Password123!
 *                 description: 8자 이상, 영문/숫자/특수문자 포함
 *               name:
 *                 type: string
 *                 example: 홍길동
 *     responses:
 *       201:
 *         description: 회원가입 성공
 *       400:
 *         description: 유효성 검사 실패
 *       409:
 *         description: 이미 존재하는 이메일
 */
 /**
 * @swagger
 * /auth/login:
 *   post:
 *     tags: [Auth]
 *     summary: 로그인
 *     description: 이메일과 비밀번호로 로그인합니다.
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required: [email, password]
 *             properties:
 *               email:
 *                 type: string
 *                 format: email
 *                 example: admin@admin.com
 *               password:
 *                 type: string
 *                 example: Admin123!
 *     responses:
 *       200:
 *         description: 로그인 성공
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 data:
 *                   type: object
 *                   properties:
 *                     user:
 *                       type: object
 *                     accessToken:
 *                       type: string
 *                       description: JWT 액세스 토큰
 *                     refreshToken:
 *                       type: string
 *                       description: JWT 리프레시 토큰
 *       401:
 *         description: 인증 실패
 */
 /**
 * @swagger
 * /chat/completions:
 *   post:
 *     tags: [Chat]
 *     summary: 채팅 완성 (OpenAI 호환)
 *     description: |
 *       AI 모델에 메시지를 보내고 응답을 받습니다.
 *       OpenAI API와 호환되는 형식입니다.
 *       
 *       **인증**: JWT 토큰 또는 API 키 (sk-xxx)
 *     security:
 *       - BearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/ChatCompletionRequest'
 *           examples:
 *             simple:
 *               summary: 간단한 질문
 *               value:
 *                 model: gemini-2.0-flash
 *                 messages:
 *                   - role: user
 *                     content: 안녕하세요!
 *             with_system:
 *               summary: 시스템 프롬프트 포함
 *               value:
 *                 model: gemini-2.0-flash
 *                 messages:
 *                   - role: system
 *                     content: 당신은 친절한 AI 어시스턴트입니다.
 *                   - role: user
 *                     content: 파이썬으로 Hello World 출력하는 코드 알려줘
 *                 temperature: 0.7
 *                 max_tokens: 1000
 *     responses:
 *       200:
 *         description: 성공
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ChatCompletionResponse'
 *       401:
 *         description: 인증 실패
 *       429:
 *         description: 요청 한도 초과
 */
 /**
 * @swagger
 * /models:
 *   get:
 *     tags: [Models]
 *     summary: 모델 목록 조회
 *     description: 사용 가능한 AI 모델 목록을 조회합니다.
 *     security:
 *       - BearerAuth: []
 *     responses:
 *       200:
 *         description: 성공
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 object:
 *                   type: string
 *                   example: list
 *                 data:
 *                   type: array
 *                   items:
 *                     type: object
 *                     properties:
 *                       id:
 *                         type: string
 *                         example: gemini-2.0-flash
 *                       object:
 *                         type: string
 *                         example: model
 *                       owned_by:
 *                         type: string
 *                         example: google
 */
 /**
 * @swagger
 * /api-keys:
 *   get:
 *     tags: [API Keys]
 *     summary: API 키 목록 조회
 *     description: 발급받은 API 키 목록을 조회합니다.
 *     security:
 *       - BearerAuth: []
 *     responses:
 *       200:
 *         description: 성공
 *   post:
 *     tags: [API Keys]
 *     summary: API 키 발급
 *     description: 새 API 키를 발급받습니다. 키는 한 번만 표시됩니다.
 *     security:
 *       - BearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required: [name]
 *             properties:
 *               name:
 *                 type: string
 *                 example: My API Key
 *                 description: API 키 이름
 *     responses:
 *       201:
 *         description: 발급 성공
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 data:
 *                   type: object
 *                   properties:
 *                     key:
 *                       type: string
 *                       description: 발급된 API 키 (한 번만 표시)
 *                       example: sk-abc123def456...
 */
 /**
 * @swagger
 * /api-keys/{id}:
 *   delete:
 *     tags: [API Keys]
 *     summary: API 키 폐기
 *     description: API 키를 폐기합니다.
 *     security:
 *       - BearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *         description: API 키 ID
 *     responses:
 *       200:
 *         description: 폐기 성공
 *       404:
 *         description: API 키를 찾을 수 없음
 */
 /**
 * @swagger
 * /usage:
 *   get:
 *     tags: [Usage]
 *     summary: 사용량 요약 조회
 *     description: 오늘/이번 달 사용량 요약을 조회합니다.
 *     security:
 *       - BearerAuth: []
 *     responses:
 *       200:
 *         description: 성공
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 data:
 *                   type: object
 *                   properties:
 *                     plan:
 *                       type: string
 *                       example: free
 *                     limit:
 *                       type: object
 *                       properties:
 *                         monthly:
 *                           type: integer
 *                         remaining:
 *                           type: integer
 *                     usage:
 *                       type: object
 *                       properties:
 *                         today:
 *                           type: object
 *                         monthly:
 *                           type: object
 */
 /**
 * @swagger
 * /usage/logs:
 *   get:
 *     tags: [Usage]
 *     summary: 사용 로그 조회
 *     description: API 호출 로그를 조회합니다.
 *     security:
 *       - BearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 20
 *     responses:
 *       200:
 *         description: 성공
 */
 /**
 * @swagger
 * /admin/users:
 *   get:
 *     tags: [Admin]
 *     summary: 사용자 목록 조회 (관리자)
 *     description: 모든 사용자 목록을 조회합니다. 관리자 권한 필요.
 *     security:
 *       - BearerAuth: []
 *     responses:
 *       200:
 *         description: 성공
 *       403:
 *         description: 권한 없음
 */
 /**
 * @swagger
 * /admin/providers:
 *   get:
 *     tags: [Admin]
 *     summary: LLM 프로바이더 목록 (관리자)
 *     description: LLM 프로바이더 설정을 조회합니다. 관리자 권한 필요.
 *     security:
 *       - BearerAuth: []
 *     responses:
 *       200:
 *         description: 성공
 *       403:
 *         description: 권한 없음
 */
 /**
 * @swagger
 * /admin/stats:
 *   get:
 *     tags: [Admin]
 *     summary: 시스템 통계 (관리자)
 *     description: 시스템 전체 통계를 조회합니다. 관리자 권한 필요.
 *     security:
 *       - BearerAuth: []
 *     responses:
 *       200:
 *         description: 성공
 *       403:
 *         description: 권한 없음
 */
--- a/backend-node/package-lock.json
+++ b/backend-node/package-lock.json
@ -22,7 +22,6 @@
        "express-rate-limit": "^7.1.5",
        "helmet": "^7.1.0",
        "html-to-docx": "^1.8.0",
        "http-proxy-middleware": "^3.0.5",
        "iconv-lite": "^0.7.0",
        "imap": "^0.8.19",
        "joi": "^17.11.0",
@ -3319,15 +3318,6 @@
      "dev": true,
      "license": "MIT"
    },
    "node_modules/@types/http-proxy": {
      "version": "1.17.17",
      "resolved": "https://registry.npmjs.org/@types/http-proxy/-/http-proxy-1.17.17.tgz",
      "integrity": "sha512-ED6LB+Z1AVylNTu7hdzuBqOgMnvG/ld6wGCG8wFnAzKX5uyW2K3WD52v0gnLCTK/VLpXtKckgWuyScYK6cSPaw==",
      "license": "MIT",
      "dependencies": {
        "@types/node": "*"
      }
    },
    "node_modules/@types/imap": {
      "version": "0.8.42",
      "resolved": "https://registry.npmjs.org/@types/imap/-/imap-0.8.42.tgz",
@ -4429,6 +4419,7 @@
      "version": "3.0.3",
      "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
      "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "fill-range": "^7.1.1"
@ -6163,6 +6154,7 @@
      "version": "7.1.1",
      "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",
      "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "to-regex-range": "^5.0.1"
@ -6895,20 +6887,6 @@
        "node": ">= 0.8"
      }
    },
    "node_modules/http-proxy": {
      "version": "1.18.1",
      "resolved": "https://registry.npmjs.org/http-proxy/-/http-proxy-1.18.1.tgz",
      "integrity": "sha512-7mz/721AbnJwIVbnaSv1Cz3Am0ZLT/UBwkC92VlxhXv/k/BBQfM2fXElQNC27BVGr0uwUpplYPQM9LnaBMR5NQ==",
      "license": "MIT",
      "dependencies": {
        "eventemitter3": "^4.0.0",
        "follow-redirects": "^1.0.0",
        "requires-port": "^1.0.0"
      },
      "engines": {
        "node": ">=8.0.0"
      }
    },
    "node_modules/http-proxy-agent": {
      "version": "7.0.2",
      "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz",
@ -6922,29 +6900,6 @@
        "node": ">= 14"
      }
    },
    "node_modules/http-proxy-middleware": {
      "version": "3.0.5",
      "resolved": "https://registry.npmjs.org/http-proxy-middleware/-/http-proxy-middleware-3.0.5.tgz",
      "integrity": "sha512-GLZZm1X38BPY4lkXA01jhwxvDoOkkXqjgVyUzVxiEK4iuRu03PZoYHhHRwxnfhQMDuaxi3vVri0YgSro/1oWqg==",
      "license": "MIT",
      "dependencies": {
        "@types/http-proxy": "^1.17.15",
        "debug": "^4.3.6",
        "http-proxy": "^1.18.1",
        "is-glob": "^4.0.3",
        "is-plain-object": "^5.0.0",
        "micromatch": "^4.0.8"
      },
      "engines": {
        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
      }
    },
    "node_modules/http-proxy/node_modules/eventemitter3": {
      "version": "4.0.7",
      "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-4.0.7.tgz",
      "integrity": "sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw==",
      "license": "MIT"
    },
    "node_modules/https-proxy-agent": {
      "version": "7.0.6",
      "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
@ -7253,6 +7208,7 @@
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
      "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==",
      "dev": true,
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
@ -7282,6 +7238,7 @@
      "version": "4.0.3",
      "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
      "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "is-extglob": "^2.1.1"
@ -7312,6 +7269,7 @@
      "version": "7.0.0",
      "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz",
      "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==",
      "dev": true,
      "license": "MIT",
      "engines": {
        "node": ">=0.12.0"
@ -7336,15 +7294,6 @@
        "node": ">=8"
      }
    },
    "node_modules/is-plain-object": {
      "version": "5.0.0",
      "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz",
      "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/is-property": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/is-property/-/is-property-1.0.2.tgz",
@ -8617,6 +8566,7 @@
      "version": "4.0.8",
      "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz",
      "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "braces": "^3.0.3",
@ -9438,6 +9388,7 @@
      "version": "2.3.1",
      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz",
      "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==",
      "dev": true,
      "license": "MIT",
      "engines": {
        "node": ">=8.6"
@ -9995,12 +9946,6 @@
        "node": ">=0.10.0"
      }
    },
    "node_modules/requires-port": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/requires-port/-/requires-port-1.0.0.tgz",
      "integrity": "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ==",
      "license": "MIT"
    },
    "node_modules/resolve": {
      "version": "1.22.10",
      "resolved": "https://registry.npmjs.org/resolve/-/resolve-1.22.10.tgz",
@ -10879,6 +10824,7 @@
      "version": "5.0.1",
      "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
      "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "is-number": "^7.0.0"
--- a/backend-node/package.json
+++ b/backend-node/package.json
@ -36,7 +36,6 @@
    "express-rate-limit": "^7.1.5",
    "helmet": "^7.1.0",
    "html-to-docx": "^1.8.0",
    "http-proxy-middleware": "^3.0.5",
    "iconv-lite": "^0.7.0",
    "imap": "^0.8.19",
    "joi": "^17.11.0",
--- a/backend-node/src/app.ts
+++ b/backend-node/src/app.ts
@ -16,17 +16,14 @@ import { refreshTokenIfNeeded } from "./middleware/authMiddleware";
 // ============================================
 // 처리되지 않은 Promise 거부 핸들러
-process.on(
+process.on("unhandledRejection", (reason: Error | any, promise: Promise<any>) => {
-  "unhandledRejection",
+  logger.error("⚠️ Unhandled Promise Rejection:", {
-  (reason: Error | any, promise: Promise<any>) => {
+    reason: reason?.message || reason,
-    logger.error("⚠️ Unhandled Promise Rejection:", {
+    stack: reason?.stack,
-      reason: reason?.message || reason,
+  });
-      stack: reason?.stack,
+  // 프로세스를 종료하지 않고 로깅만 수행
-    });
+  // 심각한 에러의 경우 graceful shutdown 고려
-    // 프로세스를 종료하지 않고 로깅만 수행
+});
    // 심각한 에러의 경우 graceful shutdown 고려
  },
 );
 // 처리되지 않은 예외 핸들러
 process.on("uncaughtException", (error: Error) => {
@ -41,16 +38,13 @@ process.on("uncaughtException", (error: Error) => {
 // SIGTERM 시그널 처리 (Docker/Kubernetes 환경)
 process.on("SIGTERM", () => {
  logger.info("📴 SIGTERM 시그널 수신, graceful shutdown 시작...");
-  const { stopAiAssistant } = require("./utils/startAiAssistant");
+  // 여기서 연결 풀 정리 등 cleanup 로직 추가 가능
  stopAiAssistant();
  process.exit(0);
 });
 // SIGINT 시그널 처리 (Ctrl+C)
 process.on("SIGINT", () => {
  logger.info("📴 SIGINT 시그널 수신, graceful shutdown 시작...");
  const { stopAiAssistant } = require("./utils/startAiAssistant");
  stopAiAssistant();
  process.exit(0);
 });
@ -118,9 +112,7 @@ import departmentRoutes from "./routes/departmentRoutes"; // 부서 관리
 import tableCategoryValueRoutes from "./routes/tableCategoryValueRoutes"; // 카테고리 값 관리
 import codeMergeRoutes from "./routes/codeMergeRoutes"; // 코드 병합
 import numberingRuleRoutes from "./routes/numberingRuleRoutes"; // 채번 규칙 관리
-import entitySearchRoutes, {
+import entitySearchRoutes, { entityOptionsRouter } from "./routes/entitySearchRoutes"; // 엔티티 검색 및 옵션
  entityOptionsRouter,
 } from "./routes/entitySearchRoutes"; // 엔티티 검색 및 옵션
 import screenEmbeddingRoutes from "./routes/screenEmbeddingRoutes"; // 화면 임베딩 및 데이터 전달
 import screenGroupRoutes from "./routes/screenGroupRoutes"; // 화면 그룹 관리
 import popActionRoutes from "./routes/popActionRoutes"; // POP 액션 실행
@ -136,7 +128,6 @@ import cascadingHierarchyRoutes from "./routes/cascadingHierarchyRoutes"; // 다
 import categoryValueCascadingRoutes from "./routes/categoryValueCascadingRoutes"; // 카테고리 값 연쇄관계
 import categoryTreeRoutes from "./routes/categoryTreeRoutes"; // 카테고리 트리 (테스트)
 import processWorkStandardRoutes from "./routes/processWorkStandardRoutes"; // 공정 작업기준
 import aiAssistantProxy from "./routes/aiAssistantProxy"; // AI 어시스턴트 API 프록시 (같은 포트로 서비스)
 import auditLogRoutes from "./routes/auditLogRoutes"; // 통합 변경 이력
 import { BatchSchedulerService } from "./services/batchSchedulerService";
 // import collectionRoutes from "./routes/collectionRoutes"; // 임시 주석
@ -161,7 +152,7 @@ app.use(
        ], // 프론트엔드 도메인 허용
      },
    },
-  }),
+  })
 );
 app.use(compression());
 app.use(express.json({ limit: "10mb" }));
@ -184,13 +175,13 @@ app.use(
    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
    res.setHeader(
      "Access-Control-Allow-Headers",
-      "Content-Type, Authorization",
+      "Content-Type, Authorization"
    );
    res.setHeader("Cross-Origin-Resource-Policy", "cross-origin");
    res.setHeader("Cache-Control", "public, max-age=3600");
    next();
  },
-  express.static(path.join(process.cwd(), "uploads")),
+  express.static(path.join(process.cwd(), "uploads"))
 );
 // CORS 설정 - environment.ts에서 이미 올바른 형태로 처리됨
@ -210,7 +201,7 @@ app.use(
    ],
    preflightContinue: false,
    optionsSuccessStatus: 200,
-  }),
+  })
 );
 // Rate Limiting (개발 환경에서는 완화)
@ -327,7 +318,6 @@ app.use("/api/category-tree", categoryTreeRoutes); // 카테고리 트리 (테
 app.use("/api/process-work-standard", processWorkStandardRoutes); // 공정 작업기준
 app.use("/api/audit-log", auditLogRoutes); // 통합 변경 이력
 app.use("/api", screenEmbeddingRoutes); // 화면 임베딩 및 데이터 전달
 app.use("/api/ai/v1", aiAssistantProxy); // AI 어시스턴트 (동일 서비스 내 프록시 → AI 서비스 포트)
 app.use("/api/vehicle", vehicleTripRoutes); // 차량 운행 이력 관리
 app.use("/api/approval", approvalRoutes); // 결재 시스템
 // app.use("/api/collections", collectionRoutes); // 임시 주석
@ -416,14 +406,6 @@ app.listen(PORT, HOST, async () => {
  } catch (error) {
    logger.error(`❌ 메일 자동 삭제 스케줄러 시작 실패:`, error);
  }
  // AI 어시스턴트 서비스 함께 기동 (한 번에 킬 가능)
  try {
    const { startAiAssistant } = await import("./utils/startAiAssistant");
    startAiAssistant();
  } catch (error) {
    logger.warn("⚠️ AI 어시스턴트 기동 스킵:", error);
  }
 });
 export default app;
--- a/backend-node/src/routes/aiAssistantProxy.ts
+++ b/backend-node/src/routes/aiAssistantProxy.ts
@ -1,31 +0,0 @@
 /**
 * AI 어시스턴트 API 프록시
 * - /api/ai/v1/* 요청을 AI 서비스(기본 3100 포트)로 전달
 * - VEXPLOR와 같은 서비스로 쓰려면: 프론트(9771) → 백엔드(8080) → 여기서 3100으로 프록시
 */
 import { createProxyMiddleware } from "http-proxy-middleware";
 import type { RequestHandler } from "express";
 const AI_SERVICE_URL =
  process.env.AI_ASSISTANT_SERVICE_URL || "http://127.0.0.1:3100";
 const aiAssistantProxy: RequestHandler = createProxyMiddleware({
  target: AI_SERVICE_URL,
  changeOrigin: true,
  pathRewrite: { "^/api/ai/v1": "/api/v1" },
  // 대상 서비스 미기동 시 502 등 에러 처리 (v3 타입에 없을 수 있음)
  onError: (_err, _req, res) => {
    if (!res.headersSent) {
      res.status(502).json({
        success: false,
        error: {
          code: "AI_SERVICE_UNAVAILABLE",
          message:
            "AI 어시스턴트 서비스를 사용할 수 없습니다. AI 서비스(기본 3100 포트)를 기동한 뒤 다시 시도하세요.",
        },
      });
    }
  },
 } as Parameters<typeof createProxyMiddleware>[0]);
 export default aiAssistantProxy;
--- a/backend-node/src/routes/dataRoutes.ts
+++ b/backend-node/src/routes/dataRoutes.ts
@ -1,7 +1,6 @@
 import express from "express";
 import { dataService } from "../services/dataService";
 import { masterDetailExcelService } from "../services/masterDetailExcelService";
 import { multiTableExcelService, TableChainConfig } from "../services/multiTableExcelService";
 import { authenticateToken } from "../middleware/authMiddleware";
 import { AuthenticatedRequest } from "../types/auth";
 import { auditLogService } from "../services/auditLogService";
@ -261,117 +260,6 @@ router.post(
  }
 );
 // ================================
 // 다중 테이블 엑셀 업로드 API
 // ================================
 /**
 * 다중 테이블 자동 감지
 * GET /api/data/multi-table/auto-detect?rootTable=customer_mng
 *
 * 루트 테이블명만 넘기면 FK 관계를 자동 탐색하여
 * 완성된 TableChainConfig를 반환한다.
 */
 router.get(
  "/multi-table/auto-detect",
  authenticateToken,
  async (req: AuthenticatedRequest, res) => {
    try {
      const rootTable = req.query.rootTable as string;
      const screenId = req.query.screenId ? Number(req.query.screenId) : undefined;
      const companyCode = req.user?.companyCode || "*";
      if (!rootTable) {
        return res.status(400).json({
          success: false,
          message: "rootTable 파라미터가 필요합니다.",
        });
      }
      const config = await multiTableExcelService.autoDetectTableChain(
        rootTable,
        companyCode,
        screenId
      );
      return res.json({ success: true, data: config });
    } catch (error: any) {
      console.error("다중 테이블 자동 감지 오류:", error);
      return res.status(500).json({
        success: false,
        message: error.message || "자동 감지 중 오류가 발생했습니다.",
      });
    }
  }
 );
 /**
 * 다중 테이블 엑셀 업로드
 * POST /api/data/multi-table/upload
 *
 * Body: { config: TableChainConfig, modeId: string, rows: Record<string, any>[] }
 */
 router.post(
  "/multi-table/upload",
  authenticateToken,
  async (req: AuthenticatedRequest, res) => {
    try {
      const { config, modeId, rows } = req.body;
      const companyCode = req.user?.companyCode || "*";
      const userId = req.user?.userId || "system";
      if (!config || !modeId || !rows || !Array.isArray(rows)) {
        return res.status(400).json({
          success: false,
          message: "config, modeId, rows 배열이 필요합니다.",
        });
      }
      if (rows.length === 0) {
        return res.status(400).json({
          success: false,
          message: "업로드할 데이터가 없습니다.",
        });
      }
      console.log(`다중 테이블 엑셀 업로드:`, {
        configId: config.id,
        modeId,
        rowCount: rows.length,
        companyCode,
        userId,
      });
      const result = await multiTableExcelService.uploadMultiTable(
        config as TableChainConfig,
        modeId,
        rows,
        companyCode,
        userId
      );
      const summaryParts = result.results.map(
        (r) => `${r.tableName}: 신규 ${r.inserted}건, 수정 ${r.updated}건`
      );
      return res.json({
        success: result.success,
        data: result,
        message: result.success
          ? summaryParts.join(" / ")
          : "업로드 중 오류가 발생했습니다.",
      });
    } catch (error: any) {
      console.error("다중 테이블 업로드 오류:", error);
      return res.status(500).json({
        success: false,
        message: "다중 테이블 업로드 중 오류가 발생했습니다.",
        error: error.message,
      });
    }
  }
 );
 // ================================
 // 기존 데이터 API
 // ================================
--- a/backend-node/src/services/multiTableExcelService.ts
+++ b/backend-node/src/services/multiTableExcelService.ts
--- a/backend-node/src/services/tableManagementService.ts
+++ b/backend-node/src/services/tableManagementService.ts
@ -3783,15 +3783,15 @@ export class TableManagementService {
                    );
                  }
                } else if (operator === "equals") {
-                  // 🔧 equals 연산자: 메인 테이블의 FK 컬럼에서 직접 매칭 (연결 필터용)
+                  // 🔧 equals 연산자: 정확히 일치
                  whereConditions.push(
-                    `main.${joinConfig.sourceColumn}::text = '${safeValue}'`
+                    `${alias}.${joinConfig.displayColumn}::text = '${safeValue}'`
                  );
                  entitySearchColumns.push(
-                    `${key} (main.${joinConfig.sourceColumn})`
+                    `${key} (${joinConfig.referenceTable}.${joinConfig.displayColumn})`
                  );
                  logger.info(
-                    `🎯 Entity 조인 직접 FK 매칭: ${key} → main.${joinConfig.sourceColumn} = '${safeValue}'`
+                    `🎯 Entity 조인 정확히 일치 검색: ${key} → ${joinConfig.referenceTable}.${joinConfig.displayColumn} = '${safeValue}' (별칭: ${alias})`
                  );
                } else {
                  // 기본: 부분 일치 (ILIKE)
--- a/backend-node/src/utils/startAiAssistant.ts
+++ b/backend-node/src/utils/startAiAssistant.ts
@ -1,65 +0,0 @@
 /**
 * AI 어시스턴트 서비스를 자식 프로세스로 기동
 * - backend-node 서버 기동 시 함께 띄우고, 종료 시 함께 종료 (한 번에 킬)
 */
 import path from "path";
 import { spawn, ChildProcess } from "child_process";
 import { logger } from "./logger";
 const AI_PORT = process.env.AI_ASSISTANT_SERVICE_PORT || "3100";
 let aiAssistantProcess: ChildProcess | null = null;
 /** ERP-node/ai-assistant 경로 (backend-node 기준 상대) */
 function getAiAssistantDir(): string {
  return path.resolve(process.cwd(), "..", "ai-assistant");
 }
 /**
 * AI 어시스턴트 서비스 기동 (있으면 띄움, 실패해도 backend는 계속 동작)
 */
 export function startAiAssistant(): void {
  const aiDir = getAiAssistantDir();
  const appPath = path.join(aiDir, "src", "app.js");
  try {
    const fs = require("fs");
    if (!fs.existsSync(appPath)) {
      logger.info(`⏭️ AI 어시스턴트 스킵 (경로 없음: ${appPath})`);
      return;
    }
  } catch {
    return;
  }
  aiAssistantProcess = spawn("node", ["src/app.js"], {
    cwd: aiDir,
    stdio: "inherit",
    env: { ...process.env, PORT: AI_PORT },
    shell: true, // Windows에서 node 경로 인식
  });
  aiAssistantProcess.on("error", (err) => {
    logger.warn(`⚠️ AI 어시스턴트 프로세스 에러: ${err.message}`);
  });
  aiAssistantProcess.on("exit", (code, signal) => {
    aiAssistantProcess = null;
    if (code != null && code !== 0) {
      logger.warn(`⚠️ AI 어시스턴트 종료 (code=${code}, signal=${signal})`);
    }
  });
  logger.info(`🤖 AI 어시스턴트 서비스 기동 (포트 ${AI_PORT}, cwd: ${aiDir})`);
 }
 /**
 * AI 어시스턴트 프로세스 종료 (SIGTERM/SIGINT 시 호출)
 */
 export function stopAiAssistant(): void {
  if (aiAssistantProcess && aiAssistantProcess.kill) {
    aiAssistantProcess.kill("SIGTERM");
    aiAssistantProcess = null;
    logger.info("🤖 AI 어시스턴트 프로세스 종료");
  }
 }
--- a/docs/plan-multi-table-excel-upload.md
+++ b/docs/plan-multi-table-excel-upload.md
@ -1,194 +0,0 @@
 # 다중 테이블 엑셀 업로드 범용 시스템
 ## 개요
 하나의 플랫 엑셀 파일로 계층적 다중 테이블(2~N개)에 데이터를 일괄 등록하는 범용 시스템.
 거래처 관리(customer_mng → customer_item_mapping → customer_item_prices)를 첫 번째 적용 대상으로 하되,
 공급업체, BOM 등 다른 화면에서도 재사용 가능하도록 설계한다.
 ## 핵심 기능
 1. 모드 선택: 어느 레벨까지 등록할지 사용자가 선택
 2. 템플릿 다운로드: 모드에 맞는 엑셀 양식 자동 생성
 3. 파일 업로드: 플랫 엑셀 → 계층 그룹핑 → 트랜잭션 UPSERT
 4. 컬럼 매핑: 엑셀 헤더 ↔ DB 컬럼 자동/수동 매핑
 ## DB 테이블 관계 (거래처 관리)
 ```
 customer_mng (Level 1 - 루트)
  PK: id (SERIAL)
  UNIQUE: customer_code
  └─ customer_item_mapping (Level 2)
       PK: id (UUID)
       FK: customer_id → customer_mng.id
       UPSERT키: customer_id + customer_item_code
       └─ customer_item_prices (Level 3)
            PK: id (UUID)
            FK: mapping_id → customer_item_mapping.id
            항상 INSERT (기간별 단가 이력)
 ```
 ## 범용 설정 구조 (TableChainConfig)
 ```typescript
 interface TableLevel {
  tableName: string;
  label: string;
  // 부모와의 관계
  parentFkColumn?: string;       // 이 테이블에서 부모를 참조하는 FK 컬럼
  parentRefColumn?: string;      // 부모 테이블에서 참조되는 컬럼 (PK 또는 UNIQUE)
  // UPSERT 설정
  upsertMode: 'upsert' | 'insert';  // upsert: 기존 데이터 있으면 UPDATE, insert: 항상 신규
  upsertKeyColumns?: string[];   // UPSERT 매칭 키 (예: ['customer_code'])
  // 엑셀 매핑 컬럼
  columns: Array<{
    dbColumn: string;
    excelHeader: string;
    required: boolean;
    defaultValue?: any;
  }>;
 }
 interface TableChainConfig {
  id: string;
  name: string;
  description: string;
  levels: TableLevel[];         // 0 = 루트, 1 = 자식, 2 = 손자...
  uploadModes: Array<{
    id: string;
    label: string;
    description: string;
    activeLevels: number[];     // 이 모드에서 활성화되는 레벨 인덱스
  }>;
 }
 ```
 ## 거래처 관리 설정 예시
 ```typescript
 const customerChainConfig: TableChainConfig = {
  id: 'customer_management',
  name: '거래처 관리',
  description: '거래처, 품목매핑, 단가 일괄 등록',
  levels: [
    {
      tableName: 'customer_mng',
      label: '거래처',
      upsertMode: 'upsert',
      upsertKeyColumns: ['customer_code'],
      columns: [
        { dbColumn: 'customer_code', excelHeader: '거래처코드', required: true },
        { dbColumn: 'customer_name', excelHeader: '거래처명', required: true },
        { dbColumn: 'division', excelHeader: '구분', required: false },
        { dbColumn: 'contact_person', excelHeader: '담당자', required: false },
        { dbColumn: 'contact_phone', excelHeader: '연락처', required: false },
        { dbColumn: 'email', excelHeader: '이메일', required: false },
        { dbColumn: 'business_number', excelHeader: '사업자번호', required: false },
        { dbColumn: 'address', excelHeader: '주소', required: false },
      ],
    },
    {
      tableName: 'customer_item_mapping',
      label: '품목매핑',
      parentFkColumn: 'customer_id',
      parentRefColumn: 'id',
      upsertMode: 'upsert',
      upsertKeyColumns: ['customer_id', 'customer_item_code'],
      columns: [
        { dbColumn: 'customer_item_code', excelHeader: '거래처품번', required: true },
        { dbColumn: 'customer_item_name', excelHeader: '거래처품명', required: true },
        { dbColumn: 'item_id', excelHeader: '품목ID', required: false },
      ],
    },
    {
      tableName: 'customer_item_prices',
      label: '단가',
      parentFkColumn: 'mapping_id',
      parentRefColumn: 'id',
      upsertMode: 'insert',
      columns: [
        { dbColumn: 'base_price', excelHeader: '기준단가', required: true },
        { dbColumn: 'discount_type', excelHeader: '할인유형', required: false },
        { dbColumn: 'discount_value', excelHeader: '할인값', required: false },
        { dbColumn: 'start_date', excelHeader: '적용시작일', required: false },
        { dbColumn: 'end_date', excelHeader: '적용종료일', required: false },
        { dbColumn: 'currency_code', excelHeader: '통화', required: false },
      ],
    },
  ],
  uploadModes: [
    { id: 'customer_only', label: '거래처만 등록', description: '거래처 기본정보만', activeLevels: [0] },
    { id: 'customer_item', label: '거래처 + 품목정보', description: '거래처와 품목매핑', activeLevels: [0, 1] },
    { id: 'customer_item_price', label: '거래처 + 품목 + 단가', description: '전체 등록', activeLevels: [0, 1, 2] },
  ],
 };
 ```
 ## 처리 로직 (백엔드)
 ### 1단계: 그룹핑
 엑셀의 플랫 행을 계층별 그룹으로 변환:
 - Level 0 (거래처): customer_code 기준 그룹핑
 - Level 1 (품목매핑): customer_code + customer_item_code 기준 그룹핑
 - Level 2 (단가): 매 행마다 INSERT
 ### 2단계: 계단식 UPSERT (트랜잭션)
 ```
 BEGIN TRANSACTION
 FOR EACH unique customer_code:
  1. customer_mng UPSERT → 결과에서 id 획득 (returnedId)
  FOR EACH unique customer_item_code (해당 거래처):
    2. customer_item_mapping의 customer_id = returnedId 주입
       UPSERT → 결과에서 id 획득 (mappingId)
    FOR EACH price row (해당 품목매핑):
      3. customer_item_prices의 mapping_id = mappingId 주입
         INSERT
 COMMIT (전체 성공) or ROLLBACK (하나라도 실패)
 ```
 ### 3단계: 결과 반환
 ```json
 {
  "success": true,
  "results": {
    "customer_mng": { "inserted": 2, "updated": 1 },
    "customer_item_mapping": { "inserted": 5, "updated": 2 },
    "customer_item_prices": { "inserted": 12 }
  },
  "errors": []
 }
 ```
 ## 테스트 계획
 ### 1단계: 백엔드 서비스
 - [x] plan.md 작성
 - [ ] multiTableExcelService.ts 기본 구조 작성
 - [ ] 그룹핑 로직 구현
 - [ ] 계단식 UPSERT 로직 구현
 - [ ] 트랜잭션 처리
 - [ ] 에러 핸들링
 ### 2단계: API 엔드포인트
 - [ ] POST /api/data/multi-table/upload 추가
 - [ ] POST /api/data/multi-table/template 추가 (템플릿 다운로드)
 - [ ] 입력값 검증
 ### 3단계: 프론트엔드
 - [ ] MultiTableExcelUploadModal.tsx 컴포넌트 작성
 - [ ] 모드 선택 UI
 - [ ] 템플릿 다운로드 버튼
 - [ ] 파일 업로드 + 미리보기
 - [ ] 컬럼 매핑 UI
 - [ ] 업로드 결과 표시
 ### 4단계: 통합
 - [ ] 거래처 관리 화면에 연결
 - [ ] 실제 데이터로 테스트
 ## 진행 상태
 - 완료된 테스트는 [x]로 표시
 - 현재 진행 중인 테스트는 [진행중]으로 표시
--- a/frontend/app/(main)/admin/aiAssistant/api-keys/page.tsx
+++ b/frontend/app/(main)/admin/aiAssistant/api-keys/page.tsx
@ -1,299 +0,0 @@
 "use client";
 import { useState, useEffect } from "react";
 import { aiAssistantApi } from "@/lib/api/aiAssistant";
 import type { ApiKeyItem } from "@/lib/api/aiAssistant";
 import {
  Key,
  Plus,
  Copy,
  Trash2,
  Loader2,
  Check,
  Eye,
  EyeOff,
 } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Badge } from "@/components/ui/badge";
 import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
 } from "@/components/ui/dialog";
 import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
 } from "@/components/ui/table";
 import { toast } from "sonner";
 export default function AiAssistantApiKeysPage() {
  const [loading, setLoading] = useState(true);
  const [apiKeys, setApiKeys] = useState<ApiKeyItem[]>([]);
  const [createDialogOpen, setCreateDialogOpen] = useState(false);
  const [newKeyDialogOpen, setNewKeyDialogOpen] = useState(false);
  const [newKeyName, setNewKeyName] = useState("");
  const [newKey, setNewKey] = useState("");
  const [creating, setCreating] = useState(false);
  const [showKey, setShowKey] = useState(false);
  const [copied, setCopied] = useState(false);
  useEffect(() => {
    loadApiKeys();
  }, []);
  const loadApiKeys = async () => {
    setLoading(true);
    try {
      const res = await aiAssistantApi.get("/api-keys");
      setApiKeys(res.data?.data ?? []);
    } catch {
      toast.error("API 키 목록을 불러오는데 실패했습니다.");
    } finally {
      setLoading(false);
    }
  };
  const createApiKey = async () => {
    if (!newKeyName.trim()) {
      toast.error("키 이름을 입력해주세요.");
      return;
    }
    setCreating(true);
    try {
      const res = await aiAssistantApi.post("/api-keys", { name: newKeyName });
      setNewKey((res.data?.data as { key?: string })?.key ?? "");
      setCreateDialogOpen(false);
      setNewKeyDialogOpen(true);
      setNewKeyName("");
      loadApiKeys();
      toast.success("API 키가 생성되었습니다.");
    } catch (err: unknown) {
      const msg =
        err && typeof err === "object" && "response" in err
          ? (err as { response?: { data?: { error?: { message?: string } } } }).response?.data
              ?.error?.message
          : null;
      toast.error(msg ?? "API 키 생성에 실패했습니다.");
    } finally {
      setCreating(false);
    }
  };
  const revokeApiKey = async (id: number) => {
    if (!confirm("이 API 키를 폐기하시겠습니까?")) return;
    try {
      await aiAssistantApi.delete(`/api-keys/${id}`);
      loadApiKeys();
      toast.success("API 키가 폐기되었습니다.");
    } catch {
      toast.error("API 키 폐기에 실패했습니다.");
    }
  };
  const copyToClipboard = async (text: string) => {
    try {
      await navigator.clipboard.writeText(text);
      setCopied(true);
      toast.success("클립보드에 복사되었습니다.");
      setTimeout(() => setCopied(false), 2000);
    } catch {
      toast.error("복사에 실패했습니다.");
    }
  };
  const baseUrl =
    typeof window !== "undefined"
      ? process.env.NEXT_PUBLIC_AI_ASSISTANT_API_URL || "http://localhost:3100/api/v1"
      : "";
  if (loading) {
    return (
      <div className="flex h-64 items-center justify-center">
        <Loader2 className="text-primary h-8 w-8 animate-spin" />
      </div>
    );
  }
  return (
    <div className="space-y-6">
      <div className="flex items-center justify-between">
        <div>
          <h1 className="text-3xl font-bold tracking-tight">API 키 관리</h1>
          <p className="text-muted-foreground mt-1">
            외부 시스템에서 AI Assistant API를 사용하기 위한 키를 관리합니다.
          </p>
        </div>
        <Dialog open={createDialogOpen} onOpenChange={setCreateDialogOpen}>
          <DialogTrigger asChild>
            <Button>
              <Plus className="mr-2 h-4 w-4" />
              새 API 키
            </Button>
          </DialogTrigger>
          <DialogContent>
            <DialogHeader>
              <DialogTitle>새 API 키 생성</DialogTitle>
              <DialogDescription>
                새로운 API 키를 생성합니다. 키는 한 번만 표시되므로 안전하게 보관하세요.
              </DialogDescription>
            </DialogHeader>
            <div className="space-y-4 py-4">
              <div className="space-y-2">
                <Label htmlFor="keyName">키 이름</Label>
                <Input
                  id="keyName"
                  placeholder="예: Production Server"
                  value={newKeyName}
                  onChange={(e) => setNewKeyName(e.target.value)}
                />
              </div>
            </div>
            <DialogFooter>
              <Button variant="outline" onClick={() => setCreateDialogOpen(false)}>
                취소
              </Button>
              <Button onClick={createApiKey} disabled={creating}>
                {creating && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
                생성
              </Button>
            </DialogFooter>
          </DialogContent>
        </Dialog>
      </div>
      <Dialog open={newKeyDialogOpen} onOpenChange={setNewKeyDialogOpen}>
        <DialogContent>
          <DialogHeader>
            <DialogTitle>API 키가 생성되었습니다</DialogTitle>
            <DialogDescription>
              이 키는 다시 표시되지 않습니다. 안전한 곳에 복사하여 보관하세요.
            </DialogDescription>
          </DialogHeader>
          <div className="space-y-4 py-4">
            <div className="flex items-center gap-2">
              <Input
                type={showKey ? "text" : "password"}
                value={newKey}
                readOnly
                className="font-mono"
              />
              <Button variant="outline" size="icon" onClick={() => setShowKey(!showKey)}>
                {showKey ? <EyeOff className="h-4 w-4" /> : <Eye className="h-4 w-4" />}
              </Button>
              <Button variant="outline" size="icon" onClick={() => copyToClipboard(newKey)}>
                {copied ? <Check className="h-4 w-4" /> : <Copy className="h-4 w-4" />}
              </Button>
            </div>
          </div>
          <DialogFooter>
            <Button onClick={() => setNewKeyDialogOpen(false)}>확인</Button>
          </DialogFooter>
        </DialogContent>
      </Dialog>
      <Card>
        <CardHeader>
          <CardTitle>API 키 목록</CardTitle>
          <CardDescription>발급된 모든 API 키를 확인하고 관리합니다.</CardDescription>
        </CardHeader>
        <CardContent>
          {apiKeys.length === 0 ? (
            <div className="flex flex-col items-center justify-center py-12 text-center">
              <Key className="text-muted-foreground mb-4 h-12 w-12" />
              <h3 className="text-lg font-medium">API 키가 없습니다</h3>
              <p className="text-muted-foreground mt-1 text-sm">새 API 키를 생성하여 시작하세요.</p>
            </div>
          ) : (
            <Table>
              <TableHeader>
                <TableRow>
                  <TableHead>이름</TableHead>
                  <TableHead>키</TableHead>
                  <TableHead>상태</TableHead>
                  <TableHead>사용량</TableHead>
                  <TableHead>마지막 사용</TableHead>
                  <TableHead>생성일</TableHead>
                  <TableHead className="text-right">작업</TableHead>
                </TableRow>
              </TableHeader>
              <TableBody>
                {apiKeys.map((key) => (
                  <TableRow key={key.id}>
                    <TableCell className="font-medium">{key.name}</TableCell>
                    <TableCell>
                      <div className="flex items-center gap-2">
                        <code className="bg-muted rounded px-2 py-1 text-sm">
                          {key.keyPrefix}...
                        </code>
                        <Button
                          variant="ghost"
                          size="icon"
                          className="h-8 w-8"
                          onClick={() => copyToClipboard(key.keyPrefix + "...")}
                        >
                          <Copy className="h-3 w-3" />
                        </Button>
                      </div>
                    </TableCell>
                    <TableCell>
                      <Badge variant={key.status === "active" ? "success" : "secondary"}>
                        {key.status === "active" ? "활성" : "폐기됨"}
                      </Badge>
                    </TableCell>
                    <TableCell>{(key.usageCount ?? 0).toLocaleString()} 토큰</TableCell>
                    <TableCell>
                      {key.lastUsedAt
                        ? new Date(key.lastUsedAt).toLocaleDateString("ko-KR")
                        : "-"}
                    </TableCell>
                    <TableCell>{new Date(key.createdAt).toLocaleDateString("ko-KR")}</TableCell>
                    <TableCell className="text-right">
                      {key.status === "active" && (
                        <Button
                          variant="ghost"
                          size="icon"
                          className="text-destructive hover:text-destructive h-8 w-8"
                          onClick={() => revokeApiKey(key.id)}
                        >
                          <Trash2 className="h-4 w-4" />
                        </Button>
                      )}
                    </TableCell>
                  </TableRow>
                ))}
              </TableBody>
            </Table>
          )}
        </CardContent>
      </Card>
      <Card>
        <CardHeader>
          <CardTitle>API 사용 방법</CardTitle>
          <CardDescription>
            발급받은 API 키를 Authorization 헤더에 포함하여 요청하세요.
          </CardDescription>
        </CardHeader>
        <CardContent>
          <pre className="bg-muted overflow-x-auto rounded-lg p-4 text-sm">
            {`curl -X POST ${baseUrl}/chat/completions \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -d '{"model": "gemini-2.0-flash", "messages": [{"role": "user", "content": "Hello!"}]}'`}
          </pre>
        </CardContent>
      </Card>
    </div>
  );
 }
--- a/frontend/app/(main)/admin/aiAssistant/api-test/page.tsx
+++ b/frontend/app/(main)/admin/aiAssistant/api-test/page.tsx
@ -1,180 +0,0 @@
 "use client";
 import { useState } from "react";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { Textarea } from "@/components/ui/textarea";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Badge } from "@/components/ui/badge";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { toast } from "sonner";
 const DEFAULT_BASE = "http://localhost:3100/api/v1";
 const PRESETS = [
  { name: "채팅 완성", method: "POST", endpoint: "/chat/completions", body: '{"model":"gemini-2.0-flash","messages":[{"role":"user","content":"안녕하세요!"}],"temperature":0.7}' },
  { name: "모델 목록", method: "GET", endpoint: "/models", body: "" },
  { name: "사용량", method: "GET", endpoint: "/usage", body: "" },
  { name: "API 키 목록", method: "GET", endpoint: "/api-keys", body: "" },
 ];
 export default function AiAssistantApiTestPage() {
  const [baseUrl, setBaseUrl] = useState(
    typeof window !== "undefined" ? (process.env.NEXT_PUBLIC_AI_ASSISTANT_API_URL || DEFAULT_BASE) : DEFAULT_BASE
  );
  const [apiKey, setApiKey] = useState("");
  const [method, setMethod] = useState("POST");
  const [endpoint, setEndpoint] = useState("/chat/completions");
  const [body, setBody] = useState(PRESETS[0].body);
  const [loading, setLoading] = useState(false);
  const [response, setResponse] = useState<{ status: number; statusText: string; data: unknown } | null>(null);
  const [responseTime, setResponseTime] = useState<number | null>(null);
  const [copied, setCopied] = useState(false);
  const apply = (p: (typeof PRESETS)[0]) => {
    setMethod(p.method);
    setEndpoint(p.endpoint);
    setBody(p.body);
  };
  const send = async () => {
    setLoading(true);
    setResponse(null);
    setResponseTime(null);
    const start = Date.now();
    try {
      const headers: Record<string, string> = { "Content-Type": "application/json" };
      if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
      const opt: RequestInit = { method, headers };
      if (method !== "GET" && body.trim()) {
        try {
          JSON.parse(body);
          opt.body = body;
        } catch {
          toast.error("JSON 형식 오류");
          setLoading(false);
          return;
        }
      }
      const res = await fetch(`${baseUrl}${endpoint}`, opt);
      const elapsed = Date.now() - start;
      setResponseTime(elapsed);
      const ct = res.headers.get("content-type");
      const data = ct?.includes("json") ? await res.json() : await res.text();
      setResponse({ status: res.status, statusText: res.statusText, data });
      toast.success(res.ok ? `성공 ${res.status}` : `실패 ${res.status}`);
    } catch (e) {
      setResponseTime(Date.now() - start);
      setResponse({ status: 0, statusText: "Network Error", data: { error: String(e) } });
      toast.error("네트워크 오류");
    } finally {
      setLoading(false);
    }
  };
  const copyRes = () => {
    navigator.clipboard.writeText(JSON.stringify(response?.data, null, 2));
    setCopied(true);
    toast.success("복사됨");
    setTimeout(() => setCopied(false), 2000);
  };
  const statusV = (s: number) => (s >= 200 && s < 300 ? "success" : s >= 400 ? "destructive" : "secondary");
  return (
    <div className="space-y-6">
      <div>
        <h1 className="text-3xl font-bold tracking-tight">API 테스트</h1>
        <p className="text-muted-foreground mt-1">API를 직접 호출하여 테스트합니다.</p>
      </div>
      <div className="grid gap-6 lg:grid-cols-2">
        <div className="space-y-4">
          <Card>
            <CardHeader className="pb-3">
              <CardTitle className="text-base">API 설정</CardTitle>
            </CardHeader>
            <CardContent className="space-y-4">
              <div className="space-y-2">
                <Label>Base URL</Label>
                <Input value={baseUrl} onChange={(e) => setBaseUrl(e.target.value)} />
              </div>
              <div className="space-y-2">
                <Label>API 키 또는 JWT</Label>
                <Input type="password" value={apiKey} onChange={(e) => setApiKey(e.target.value)} placeholder="sk-xxx" />
              </div>
            </CardContent>
          </Card>
          <Card>
            <CardHeader className="pb-3">
              <CardTitle className="text-base">빠른 선택</CardTitle>
            </CardHeader>
            <CardContent>
              <div className="flex flex-wrap gap-2">
                {PRESETS.map((p, i) => (
                  <Button key={i} variant="outline" size="sm" onClick={() => apply(p)}>
                    <Badge variant="secondary" className="mr-2 text-xs">{p.method}</Badge>
                    {p.name}
                  </Button>
                ))}
              </div>
            </CardContent>
          </Card>
          <Card>
            <CardHeader className="pb-3">
              <CardTitle className="text-base">요청</CardTitle>
            </CardHeader>
            <CardContent className="space-y-4">
              <div className="flex gap-2">
                <Select value={method} onValueChange={setMethod}>
                  <SelectTrigger className="w-[100px]"><SelectValue /></SelectTrigger>
                  <SelectContent>
                    <SelectItem value="GET">GET</SelectItem>
                    <SelectItem value="POST">POST</SelectItem>
                    <SelectItem value="PUT">PUT</SelectItem>
                    <SelectItem value="DELETE">DELETE</SelectItem>
                  </SelectContent>
                </Select>
                <Input value={endpoint} onChange={(e) => setEndpoint(e.target.value)} className="flex-1" />
              </div>
              {method !== "GET" && (
                <div className="space-y-2">
                  <Label>Body (JSON)</Label>
                  <Textarea value={body} onChange={(e) => setBody(e.target.value)} className="font-mono text-sm min-h-[180px]" />
                </div>
              )}
              <Button className="w-full" onClick={send} disabled={loading}>
                {loading ? "요청 중..." : "요청 보내기"}
              </Button>
            </CardContent>
          </Card>
        </div>
        <Card className="h-full">
          <CardHeader className="pb-3">
            <div className="flex items-center justify-between">
              <CardTitle className="text-base">응답</CardTitle>
              {response && (
                <div className="flex items-center gap-2">
                  <Badge variant={statusV(response.status)}>{response.status} {response.statusText}</Badge>
                  {responseTime != null && <Badge variant="outline">{responseTime}ms</Badge>}
                  <Button variant="ghost" size="icon" className="h-8 w-8" onClick={copyRes}>
                    {copied ? "✓" : "복사"}
                  </Button>
                </div>
              )}
            </div>
          </CardHeader>
          <CardContent>
            {!response ? (
              <p className="text-muted-foreground py-12 text-center">요청을 보내면 응답이 표시됩니다.</p>
            ) : (
              <pre className="bg-muted max-h-[500px] overflow-auto rounded-lg p-4 text-sm font-mono whitespace-pre-wrap">
                {typeof response.data === "string" ? response.data : JSON.stringify(response.data, null, 2)}
              </pre>
            )}
          </CardContent>
        </Card>
      </div>
    </div>
  );
 }
--- a/frontend/app/(main)/admin/aiAssistant/chat/page.tsx
+++ b/frontend/app/(main)/admin/aiAssistant/chat/page.tsx
@ -1,142 +0,0 @@
 "use client";
 import { useState, useRef, useEffect } from "react";
 import { aiAssistantApi } from "@/lib/api/aiAssistant";
 import { Send, Loader2, Bot, User, Trash2, Settings2 } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { Textarea } from "@/components/ui/textarea";
 import { Card, CardContent } from "@/components/ui/card";
 import { ScrollArea } from "@/components/ui/scroll-area";
 import { Avatar, AvatarFallback } from "@/components/ui/avatar";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
 import { cn } from "@/lib/utils";
 import { toast } from "sonner";
 type ChatMessage = { role: "user" | "assistant"; content: string };
 type ModelItem = { id: string };
 export default function AiAssistantChatPage() {
  const [messages, setMessages] = useState<ChatMessage[]>([]);
  const [input, setInput] = useState("");
  const [loading, setLoading] = useState(false);
  const [models, setModels] = useState<ModelItem[]>([]);
  const [selectedModel, setSelectedModel] = useState("gemini-2.0-flash");
  const messagesEndRef = useRef<HTMLDivElement>(null);
  useEffect(() => {
    aiAssistantApi.get("/models").then((res) => {
      const list = (res.data?.data as ModelItem[]) ?? [];
      setModels(list);
      if (list.length && !list.some((m) => m.id === selectedModel)) setSelectedModel(list[0].id);
    }).catch(() => {});
  }, []);
  useEffect(() => {
    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
  }, [messages]);
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!input.trim() || loading) return;
    const userMsg: ChatMessage = { role: "user", content: input.trim() };
    setMessages((prev) => [...prev, userMsg]);
    setInput("");
    setLoading(true);
    try {
      const res = await aiAssistantApi.post("/chat/completions", {
        model: selectedModel,
        messages: [...messages, userMsg].map((m) => ({ role: m.role, content: m.content })),
      });
      const content = (res.data as { choices?: Array<{ message?: { content?: string } }> })?.choices?.[0]?.message?.content ?? "";
      setMessages((prev) => [...prev, { role: "assistant", content }]);
    } catch (err: unknown) {
      const msg = err && typeof err === "object" && "response" in err
        ? (err as { response?: { data?: { error?: { message?: string } } } }).response?.data?.error?.message
        : null;
      toast.error(msg ?? "AI 응답 실패");
      setMessages((prev) => prev.slice(0, -1));
    } finally {
      setLoading(false);
    }
  };
  return (
    <div className="flex h-[calc(100vh-8rem)] flex-col">
      <div className="mb-4 flex items-center justify-between">
        <div>
          <h1 className="text-3xl font-bold tracking-tight">AI 채팅</h1>
          <p className="text-muted-foreground mt-1">AI Assistant와 대화하세요.</p>
        </div>
        <div className="flex items-center gap-2">
          <Select value={selectedModel} onValueChange={setSelectedModel}>
            <SelectTrigger className="w-[200px]">
              <Settings2 className="mr-2 h-4 w-4" />
              <SelectValue placeholder="모델 선택" />
            </SelectTrigger>
            <SelectContent>
              {models.map((m) => (
                <SelectItem key={m.id} value={m.id}>{m.id}</SelectItem>
              ))}
              {models.length === 0 && <SelectItem value="gemini-2.0-flash">gemini-2.0-flash</SelectItem>}
            </SelectContent>
          </Select>
          <Button variant="outline" size="icon" onClick={() => setMessages([])}>
            <Trash2 className="h-4 w-4" />
          </Button>
        </div>
      </div>
      <Card className="flex flex-1 flex-col overflow-hidden">
        <ScrollArea className="flex-1 p-4">
          {messages.length === 0 ? (
            <div className="flex h-full flex-col items-center justify-center text-center">
              <div className="bg-primary/10 mb-4 flex h-16 w-16 items-center justify-center rounded-full">
                <Bot className="text-primary h-8 w-8" />
              </div>
              <h3 className="text-lg font-medium">AI Assistant</h3>
              <p className="text-muted-foreground mt-1 max-w-sm">무엇이든 물어보세요.</p>
            </div>
          ) : (
            <div className="space-y-4">
              {messages.map((msg, i) => (
                <div key={i} className={cn("flex gap-3", msg.role === "user" && "flex-row-reverse")}>
                  <Avatar className="h-8 w-8 shrink-0">
                    <AvatarFallback className={cn(msg.role === "user" ? "bg-primary text-primary-foreground" : "bg-muted")}>
                      {msg.role === "user" ? <User className="h-4 w-4" /> : <Bot className="h-4 w-4" />}
                    </AvatarFallback>
                  </Avatar>
                  <div className={cn("max-w-[80%] rounded-lg px-4 py-2", msg.role === "user" ? "bg-primary text-primary-foreground" : "bg-muted")}>
                    <p className="whitespace-pre-wrap text-sm">{msg.content}</p>
                  </div>
                </div>
              ))}
              {loading && (
                <div className="flex gap-3">
                  <Avatar className="h-8 w-8 shrink-0">
                    <AvatarFallback className="bg-muted"><Bot className="h-4 w-4" /></AvatarFallback>
                  </Avatar>
                  <div className="rounded-lg bg-muted px-4 py-2"><Loader2 className="h-4 w-4 animate-spin" /></div>
                </div>
              )}
              <div ref={messagesEndRef} />
            </div>
          )}
        </ScrollArea>
        <CardContent className="border-t p-4">
          <form onSubmit={handleSubmit} className="flex gap-2">
            <Textarea
              value={input}
              onChange={(e) => setInput(e.target.value)}
              onKeyDown={(e) => e.key === "Enter" && !e.shiftKey && (e.preventDefault(), handleSubmit(e as unknown as React.FormEvent))}
              placeholder="메시지 입력 (Shift+Enter 줄바꿈)"
              className="max-h-[200px] min-h-[60px] resize-none"
              disabled={loading}
            />
            <Button type="submit" size="icon" className="h-[60px] w-[60px]" disabled={loading || !input.trim()}>
              {loading ? <Loader2 className="h-5 w-5 animate-spin" /> : <Send className="h-5 w-5" />}
            </Button>
          </form>
        </CardContent>
      </Card>
    </div>
  );
 }
--- a/frontend/app/(main)/admin/aiAssistant/dashboard/page.tsx
+++ b/frontend/app/(main)/admin/aiAssistant/dashboard/page.tsx
@ -1,190 +0,0 @@
 "use client";
 import { useState, useEffect } from "react";
 import { getAiAssistantAuth, aiAssistantApi } from "@/lib/api/aiAssistant";
 import type { UsageSummary, ApiKeyItem, AdminStats } from "@/lib/api/aiAssistant";
 import { BarChart3, Key, Zap, TrendingUp, Loader2, AlertCircle, Users, Cpu } from "lucide-react";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Badge } from "@/components/ui/badge";
 import { Progress } from "@/components/ui/progress";
 import { toast } from "sonner";
 export default function AiAssistantDashboardPage() {
  const auth = getAiAssistantAuth();
  const user = auth?.user;
  const isAdmin = user?.role === "admin";
  const [loading, setLoading] = useState(true);
  const [usage, setUsage] = useState<UsageSummary | null>(null);
  const [apiKeys, setApiKeys] = useState<ApiKeyItem[]>([]);
  const [stats, setStats] = useState<AdminStats | null>(null);
  useEffect(() => {
    loadData();
  }, []);
  const loadData = async () => {
    setLoading(true);
    try {
      const usageRes = await aiAssistantApi.get("/usage");
      setUsage(usageRes.data?.data ?? null);
      const keysRes = await aiAssistantApi.get("/api-keys");
      setApiKeys(keysRes.data?.data ?? []);
      if (isAdmin) {
        const statsRes = await aiAssistantApi.get("/admin/stats");
        setStats(statsRes.data?.data ?? null);
      }
    } catch {
      toast.error("데이터를 불러오는데 실패했습니다.");
    } finally {
      setLoading(false);
    }
  };
  if (loading) {
    return (
      <div className="flex h-64 items-center justify-center">
        <Loader2 className="text-primary h-8 w-8 animate-spin" />
      </div>
    );
  }
  const monthlyTokens = usage?.usage?.monthly?.totalTokens ?? 0;
  const monthlyLimit = usage?.limit?.monthly ?? 0;
  const usagePercent = monthlyLimit > 0 ? Math.round((monthlyTokens / monthlyLimit) * 100) : 0;
  return (
    <div className="space-y-6">
      <div>
        <h1 className="text-3xl font-bold tracking-tight">대시보드</h1>
        <p className="text-muted-foreground mt-1">안녕하세요, {user?.name || user?.email}님!</p>
      </div>
      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">오늘 사용량</CardTitle>
            <Zap className="text-muted-foreground h-4 w-4" />
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">
              {(usage?.usage?.today?.tokens ?? 0).toLocaleString()}
            </div>
            <p className="text-muted-foreground text-xs">토큰</p>
          </CardContent>
        </Card>
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">이번 달 사용량</CardTitle>
            <BarChart3 className="text-muted-foreground h-4 w-4" />
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">{monthlyTokens.toLocaleString()}</div>
            <p className="text-muted-foreground mb-2 text-xs">
              / {monthlyLimit.toLocaleString()} 토큰
            </p>
            <Progress value={usagePercent} className="h-2" />
            <p className="text-muted-foreground mt-1 text-right text-xs">{usagePercent}% 사용</p>
          </CardContent>
        </Card>
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">오늘 요청 수</CardTitle>
            <TrendingUp className="text-muted-foreground h-4 w-4" />
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">
              {(usage?.usage?.today?.requests ?? 0).toLocaleString()}
            </div>
            <p className="text-muted-foreground text-xs">회</p>
          </CardContent>
        </Card>
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">활성 API 키</CardTitle>
            <Key className="text-muted-foreground h-4 w-4" />
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">
              {apiKeys.filter((k) => k.status === "active").length}
            </div>
            <p className="text-muted-foreground text-xs">개</p>
          </CardContent>
        </Card>
      </div>
      {isAdmin && stats && (
        <Card className="bg-gradient-to-r from-primary to-primary/80 text-primary-foreground">
          <CardHeader>
            <CardTitle>시스템 현황</CardTitle>
            <CardDescription className="text-primary-foreground/70">전체 시스템 통계</CardDescription>
          </CardHeader>
          <CardContent>
            <div className="grid grid-cols-2 gap-4 md:grid-cols-4">
              <div className="space-y-1">
                <div className="flex items-center gap-2">
                  <Users className="h-4 w-4" />
                  <span className="text-sm opacity-80">전체 사용자</span>
                </div>
                <p className="text-2xl font-bold">{stats.users?.total ?? 0}</p>
              </div>
              <div className="space-y-1">
                <div className="flex items-center gap-2">
                  <Users className="h-4 w-4" />
                  <span className="text-sm opacity-80">활성 사용자</span>
                </div>
                <p className="text-2xl font-bold">{stats.users?.active ?? 0}</p>
              </div>
              <div className="space-y-1">
                <div className="flex items-center gap-2">
                  <Key className="h-4 w-4" />
                  <span className="text-sm opacity-80">전체 API 키</span>
                </div>
                <p className="text-2xl font-bold">{stats.apiKeys?.total ?? 0}</p>
              </div>
              <div className="space-y-1">
                <div className="flex items-center gap-2">
                  <Cpu className="h-4 w-4" />
                  <span className="text-sm opacity-80">활성 프로바이더</span>
                </div>
                <p className="text-2xl font-bold">{stats.providers?.active ?? 0}</p>
              </div>
            </div>
          </CardContent>
        </Card>
      )}
      <Card>
        <CardHeader>
          <CardTitle>내 API 키</CardTitle>
          <CardDescription>발급받은 API 키 목록</CardDescription>
        </CardHeader>
        <CardContent>
          {apiKeys.length === 0 ? (
            <div className="flex flex-col items-center justify-center py-8 text-center">
              <AlertCircle className="text-muted-foreground mb-3 h-10 w-10" />
              <p className="text-muted-foreground">API 키가 없습니다.</p>
              <p className="text-muted-foreground text-sm">새 키를 발급받으세요.</p>
            </div>
          ) : (
            <div className="space-y-3">
              {apiKeys.slice(0, 5).map((key) => (
                <div
                  key={key.id}
                  className="bg-card flex items-center justify-between rounded-lg border p-3"
                >
                  <div>
                    <p className="font-medium">{key.name}</p>
                    <p className="text-muted-foreground font-mono text-sm">{key.keyPrefix}...</p>
                  </div>
                  <Badge variant={key.status === "active" ? "success" : "secondary"}>
                    {key.status === "active" ? "활성" : "비활성"}
                  </Badge>
                </div>
              ))}
            </div>
          )}
        </CardContent>
      </Card>
    </div>
  );
 }
--- a/frontend/app/(main)/admin/aiAssistant/history/page.tsx
+++ b/frontend/app/(main)/admin/aiAssistant/history/page.tsx
@ -1,157 +0,0 @@
 "use client";
 import { useState, useEffect } from "react";
 import { aiAssistantApi } from "@/lib/api/aiAssistant";
 import type { UsageLogItem } from "@/lib/api/aiAssistant";
 import { History, Loader2, MessageSquare, Clock, Zap, CheckCircle, XCircle } from "lucide-react";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Badge } from "@/components/ui/badge";
 import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
 } from "@/components/ui/table";
 import { Button } from "@/components/ui/button";
 import { toast } from "sonner";
 export default function AiAssistantHistoryPage() {
  const [loading, setLoading] = useState(true);
  const [logs, setLogs] = useState<UsageLogItem[]>([]);
  const [page, setPage] = useState(1);
  const [totalPages, setTotalPages] = useState(1);
  useEffect(() => {
    loadLogs();
  }, [page]);
  const loadLogs = async () => {
    setLoading(true);
    try {
      const res = await aiAssistantApi.get(`/usage/logs?page=${page}&limit=20`);
      const data = res.data?.data as { logs?: UsageLogItem[]; pagination?: { totalPages?: number } };
      setLogs(data?.logs ?? []);
      setTotalPages(data?.pagination?.totalPages ?? 1);
    } catch {
      toast.error("대화 이력을 불러오는데 실패했습니다.");
    } finally {
      setLoading(false);
    }
  };
  if (loading && logs.length === 0) {
    return (
      <div className="flex h-64 items-center justify-center">
        <Loader2 className="text-primary h-8 w-8 animate-spin" />
      </div>
    );
  }
  return (
    <div className="space-y-6">
      <div>
        <h1 className="text-3xl font-bold tracking-tight">대화 이력</h1>
        <p className="text-muted-foreground mt-1">AI Assistant와의 대화 기록을 확인합니다.</p>
      </div>
      <Card>
        <CardHeader>
          <CardTitle>API 호출 로그</CardTitle>
          <CardDescription>최근 API 호출 기록</CardDescription>
        </CardHeader>
        <CardContent>
          {logs.length === 0 ? (
            <div className="flex flex-col items-center justify-center py-12 text-center">
              <History className="text-muted-foreground mb-4 h-12 w-12" />
              <h3 className="text-lg font-medium">대화 이력이 없습니다</h3>
              <p className="text-muted-foreground mt-1 text-sm">AI 채팅을 시작하면 이력이 표시됩니다.</p>
            </div>
          ) : (
            <>
              <Table>
                <TableHeader>
                  <TableRow>
                    <TableHead>상태</TableHead>
                    <TableHead>프로바이더</TableHead>
                    <TableHead>모델</TableHead>
                    <TableHead>토큰</TableHead>
                    <TableHead>비용</TableHead>
                    <TableHead>응답시간</TableHead>
                    <TableHead>일시</TableHead>
                  </TableRow>
                </TableHeader>
                <TableBody>
                  {logs.map((log) => (
                    <TableRow key={log.id}>
                      <TableCell>
                        {log.success ? (
                          <Badge variant="success" className="gap-1">
                            <CheckCircle className="h-3 w-3" />
                            성공
                          </Badge>
                        ) : (
                          <Badge variant="destructive" className="gap-1">
                            <XCircle className="h-3 w-3" />
                            실패
                          </Badge>
                        )}
                      </TableCell>
                      <TableCell>
                        <Badge variant="outline">{log.providerName}</Badge>
                      </TableCell>
                      <TableCell className="font-mono text-sm">{log.modelName}</TableCell>
                      <TableCell>
                        <div className="flex items-center gap-1">
                          <Zap className="text-muted-foreground h-3 w-3" />
                          <span>{(log.totalTokens ?? 0).toLocaleString()}</span>
                        </div>
                        <div className="text-muted-foreground text-xs">
                          입력: {log.promptTokens ?? 0} / 출력: {log.completionTokens ?? 0}
                        </div>
                      </TableCell>
                      <TableCell>${(log.costUsd ?? 0).toFixed(6)}</TableCell>
                      <TableCell>
                        <div className="flex items-center gap-1">
                          <Clock className="text-muted-foreground h-3 w-3" />
                          <span>{log.responseTimeMs ?? 0}ms</span>
                        </div>
                      </TableCell>
                      <TableCell className="text-muted-foreground">
                        {new Date(log.createdAt).toLocaleString("ko-KR")}
                      </TableCell>
                    </TableRow>
                  ))}
                </TableBody>
              </Table>
              {totalPages > 1 && (
                <div className="mt-4 flex items-center justify-center gap-2">
                  <Button
                    variant="outline"
                    size="sm"
                    onClick={() => setPage((p) => Math.max(1, p - 1))}
                    disabled={page === 1}
                  >
                    이전
                  </Button>
                  <span className="text-muted-foreground text-sm">
                    {page} / {totalPages}
                  </span>
                  <Button
                    variant="outline"
                    size="sm"
                    onClick={() => setPage((p) => Math.min(totalPages, p + 1))}
                    disabled={page === totalPages}
                  >
                    다음
                  </Button>
                </div>
              )}
            </>
          )}
        </CardContent>
      </Card>
    </div>
  );
 }
--- a/frontend/app/(main)/admin/aiAssistant/layout.tsx
+++ b/frontend/app/(main)/admin/aiAssistant/layout.tsx
@ -1,128 +0,0 @@
 "use client";
 import { useState, useEffect } from "react";
 import Link from "next/link";
 import {
  getAiAssistantAuth,
  setAiAssistantAuth,
  loginAiAssistant,
 } from "@/lib/api/aiAssistant";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 export default function AIAssistantLayout({
  children,
 }: {
  children: React.ReactNode;
 }) {
  const [mounted, setMounted] = useState(false);
  const [auth, setAuth] = useState<ReturnType<typeof getAiAssistantAuth>>(null);
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState("");
  useEffect(() => {
    setAuth(getAiAssistantAuth());
    setMounted(true);
  }, []);
  const handleLogin = async (e: React.FormEvent) => {
    e.preventDefault();
    setError("");
    setLoading(true);
    try {
      await loginAiAssistant(email, password);
      setAuth(getAiAssistantAuth());
    } catch (err: unknown) {
      const msg =
        err && typeof err === "object" && "response" in err
          ? (err as { response?: { data?: { error?: { message?: string } } } }).response?.data
              ?.error?.message
          : null;
      setError(msg || "로그인에 실패했습니다.");
    } finally {
      setLoading(false);
    }
  };
  const handleLogout = () => {
    setAiAssistantAuth(null);
    setAuth(null);
  };
  if (!mounted) {
    return (
      <div className="flex min-h-[40vh] items-center justify-center">
        <p className="text-muted-foreground text-sm">로딩 중...</p>
      </div>
    );
  }
  if (!auth) {
    return (
      <div className="mx-auto flex min-h-[60vh] max-w-sm flex-col justify-center p-6">
        <Card>
          <CardHeader>
            <CardTitle>AI 어시스턴트 로그인</CardTitle>
            <CardDescription>
              AI 서비스(API 키, 사용량, 채팅 등)를 사용하려면 로그인하세요.
            </CardDescription>
          </CardHeader>
          <CardContent>
            <form onSubmit={handleLogin} className="space-y-4">
              <div className="space-y-2">
                <Label htmlFor="email">이메일</Label>
                <Input
                  id="email"
                  type="email"
                  value={email}
                  onChange={(e) => setEmail(e.target.value)}
                  placeholder="admin@admin.com"
                  required
                />
              </div>
              <div className="space-y-2">
                <Label htmlFor="password">비밀번호</Label>
                <Input
                  id="password"
                  type="password"
                  value={password}
                  onChange={(e) => setPassword(e.target.value)}
                  required
                />
              </div>
              {error && (
                <p className="text-destructive text-sm">{error}</p>
              )}
              <div className="flex gap-2">
                <Button type="submit" className="flex-1" disabled={loading}>
                  {loading ? "로그인 중..." : "로그인"}
                </Button>
                <Button asChild variant="outline">
                  <Link href="/admin">취소</Link>
                </Button>
              </div>
            </form>
          </CardContent>
        </Card>
      </div>
    );
  }
  return (
    <div className="space-y-4">
      <div className="flex items-center justify-end gap-2 border-b pb-2 text-sm">
        <span className="text-muted-foreground">
          {auth.user?.name || auth.user?.email} (AI 서비스)
        </span>
        <Button variant="ghost" size="sm" onClick={handleLogout}>
          로그아웃
        </Button>
      </div>
      {children}
    </div>
  );
 }
--- a/frontend/app/(main)/admin/aiAssistant/page.tsx
+++ b/frontend/app/(main)/admin/aiAssistant/page.tsx
@ -1,6 +0,0 @@
 import { redirect } from "next/navigation";
 /** AI 어시스턴트 진입 시 대시보드로 이동 */
 export default function AIAssistantPage() {
  redirect("/admin/aiAssistant/dashboard");
 }
--- a/frontend/app/(main)/admin/aiAssistant/usage/page.tsx
+++ b/frontend/app/(main)/admin/aiAssistant/usage/page.tsx
@ -1,195 +0,0 @@
 "use client";
 import { useState, useEffect } from "react";
 import { aiAssistantApi } from "@/lib/api/aiAssistant";
 import type { UsageSummary } from "@/lib/api/aiAssistant";
 import { BarChart3, Calendar, Loader2, TrendingUp, Zap, DollarSign } from "lucide-react";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import { Progress } from "@/components/ui/progress";
 import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
 } from "@/components/ui/select";
 import { toast } from "sonner";
 interface DailyUsageItem {
  date?: string;
  totalTokens?: number;
  requestCount?: number;
 }
 export default function AiAssistantUsagePage() {
  const [loading, setLoading] = useState(true);
  const [usage, setUsage] = useState<UsageSummary | null>(null);
  const [dailyUsage, setDailyUsage] = useState<DailyUsageItem[]>([]);
  const [period, setPeriod] = useState("7");
  useEffect(() => {
    loadUsage();
  }, [period]);
  const loadUsage = async () => {
    setLoading(true);
    try {
      const [usageRes, dailyRes] = await Promise.all([
        aiAssistantApi.get("/usage"),
        aiAssistantApi.get(`/usage/daily?days=${period}`),
      ]);
      setUsage(usageRes.data?.data ?? null);
      setDailyUsage((dailyRes.data?.data as { usage?: DailyUsageItem[] })?.usage ?? []);
    } catch {
      toast.error("사용량 데이터를 불러오는데 실패했습니다.");
    } finally {
      setLoading(false);
    }
  };
  if (loading) {
    return (
      <div className="flex h-64 items-center justify-center">
        <Loader2 className="text-primary h-8 w-8 animate-spin" />
      </div>
    );
  }
  const todayTokens = usage?.usage?.today?.tokens ?? 0;
  const todayRequests = usage?.usage?.today?.requests ?? 0;
  const monthlyTokens = usage?.usage?.monthly?.totalTokens ?? 0;
  const monthlyCost = usage?.usage?.monthly?.totalCost ?? 0;
  const monthlyLimit = usage?.limit?.monthly ?? 0;
  const usagePercent = monthlyLimit > 0 ? Math.round((monthlyTokens / monthlyLimit) * 100) : 0;
  const maxTokens = Math.max(...dailyUsage.map((d) => d.totalTokens ?? 0), 1);
  return (
    <div className="space-y-6">
      <div>
        <h1 className="text-3xl font-bold tracking-tight">사용량</h1>
        <p className="text-muted-foreground mt-1">API 사용량 및 비용을 확인합니다.</p>
      </div>
      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">오늘 토큰</CardTitle>
            <Zap className="text-muted-foreground h-4 w-4" />
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">{todayTokens.toLocaleString()}</div>
          </CardContent>
        </Card>
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">오늘 요청</CardTitle>
            <TrendingUp className="text-muted-foreground h-4 w-4" />
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">{todayRequests.toLocaleString()}</div>
          </CardContent>
        </Card>
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">이번 달 토큰</CardTitle>
            <BarChart3 className="text-muted-foreground h-4 w-4" />
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">{monthlyTokens.toLocaleString()}</div>
          </CardContent>
        </Card>
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">이번 달 비용</CardTitle>
            <DollarSign className="text-muted-foreground h-4 w-4" />
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">${monthlyCost.toFixed(4)}</div>
          </CardContent>
        </Card>
      </div>
      <Card>
        <CardHeader className="flex flex-row items-center justify-between">
          <div>
            <CardTitle>일별 사용량</CardTitle>
            <CardDescription>기간별 토큰 사용량 추이</CardDescription>
          </div>
          <Select value={period} onValueChange={setPeriod}>
            <SelectTrigger className="w-[140px]">
              <Calendar className="mr-2 h-4 w-4" />
              <SelectValue />
            </SelectTrigger>
            <SelectContent>
              <SelectItem value="7">최근 7일</SelectItem>
              <SelectItem value="14">최근 14일</SelectItem>
              <SelectItem value="30">최근 30일</SelectItem>
            </SelectContent>
          </Select>
        </CardHeader>
        <CardContent>
          {dailyUsage.length === 0 ? (
            <div className="flex flex-col items-center justify-center py-12 text-center">
              <BarChart3 className="text-muted-foreground mb-4 h-12 w-12" />
              <p className="text-muted-foreground">사용 기록이 없습니다.</p>
            </div>
          ) : (
            <div className="space-y-3">
              {dailyUsage.map((day, idx) => (
                <div key={day.date ?? idx} className="flex items-center gap-4">
                  <div className="text-muted-foreground w-20 text-sm">
                    {day.date
                      ? new Date(day.date).toLocaleDateString("ko-KR", {
                          month: "short",
                          day: "numeric",
                        })
                      : "-"}
                  </div>
                  <div className="flex-1">
                    <div className="bg-muted h-8 overflow-hidden rounded-lg">
                      <div
                        className="bg-primary h-full rounded-lg transition-all duration-500"
                        style={{
                          width: `${((day.totalTokens ?? 0) / maxTokens) * 100}%`,
                        }}
                      />
                    </div>
                  </div>
                  <div className="w-28 text-right">
                    <span className="text-sm font-medium">
                      {(day.totalTokens ?? 0).toLocaleString()}
                    </span>
                    <span className="text-muted-foreground ml-1 text-xs">토큰</span>
                  </div>
                  <div className="text-muted-foreground w-16 text-right text-sm">
                    {day.requestCount ?? 0}회
                  </div>
                </div>
              ))}
            </div>
          )}
        </CardContent>
      </Card>
      <Card className="bg-gradient-to-r from-primary to-primary/80 text-primary-foreground">
        <CardContent className="pt-6">
          <div className="mb-4 flex items-center justify-between">
            <div>
              <h3 className="text-lg font-semibold">
                현재 플랜: {(usage?.plan ?? "FREE").toUpperCase()}
              </h3>
              <p className="text-primary-foreground/70">
                월간 한도: {monthlyLimit > 0 ? monthlyLimit.toLocaleString() : "무제한"} 토큰
              </p>
            </div>
            <div className="text-right">
              <p className="text-3xl font-bold">{usagePercent}%</p>
              <p className="text-primary-foreground/70 text-sm">사용률</p>
            </div>
          </div>
          <Progress value={usagePercent} className="bg-primary-foreground/20 h-3" />
        </CardContent>
      </Card>
    </div>
  );
 }
--- a/frontend/app/(main)/admin/page.tsx
+++ b/frontend/app/(main)/admin/page.tsx
@ -1,4 +1,4 @@
-import { Users, Shield, Settings, BarChart3, Palette, Layout, Database, Package, Building2, Bot } from "lucide-react";
+import { Users, Shield, Settings, BarChart3, Palette, Layout, Database, Package, Building2 } from "lucide-react";
 import Link from "next/link";
 import { GlobalFileViewer } from "@/components/GlobalFileViewer";
@ -80,20 +80,6 @@ export default function AdminPage() {
                </div>
              </div>
            </Link>
            <Link href="/admin/aiAssistant" className="block">
              <div className="bg-card hover:bg-muted rounded-lg border p-6 shadow-sm transition-colors">
                <div className="flex items-center gap-4">
                  <div className="bg-primary/10 flex h-12 w-12 items-center justify-center rounded-lg">
                    <Bot className="text-primary h-6 w-6" />
                  </div>
                  <div>
                    <h3 className="text-foreground font-semibold">AI 어시스턴트</h3>
                    <p className="text-muted-foreground text-sm">AI 채팅 및 LLM 연동 관리</p>
                  </div>
                </div>
              </div>
            </Link>
          </div>
        </div>
--- a/frontend/app/(main)/admin/screenMng/barcodeList/page.tsx
+++ b/frontend/app/(main)/admin/screenMng/barcodeList/page.tsx
@ -6,15 +6,12 @@ import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { BarcodeListTable } from "@/components/barcode/BarcodeListTable";
-import { BarcodeScanModal } from "@/components/common/BarcodeScanModal";
+import { Plus, Search, RotateCcw } from "lucide-react";
 import { Plus, Search, RotateCcw, Scan } from "lucide-react";
 import { useBarcodeList } from "@/hooks/useBarcodeList";
 export default function BarcodeLabelManagementPage() {
  const router = useRouter();
  const [searchText, setSearchText] = useState("");
  const [scanModalOpen, setScanModalOpen] = useState(false);
  const [scannedBarcode, setScannedBarcode] = useState<string | null>(null);
  const { labels, total, page, limit, isLoading, refetch, setPage, handleSearch } = useBarcodeList();
@ -77,33 +74,6 @@ export default function BarcodeLabelManagementPage() {
          </CardContent>
        </Card>
        {/* 카메라 스캔: 바코드 값을 텍스트로 추출해 표시 */}
        <Card className="shadow-sm">
          <CardHeader className="bg-gray-50/50">
            <CardTitle className="flex items-center gap-2">
              <Scan className="h-5 w-5" />
              바코드 스캔
            </CardTitle>
            <p className="text-muted-foreground text-sm">
              카메라로 바코드를 스캔하면 추출된 값을 아래에 텍스트로 표시합니다.
            </p>
          </CardHeader>
          <CardContent className="space-y-4">
            <Button onClick={() => setScanModalOpen(true)} variant="outline" className="gap-2">
              <Scan className="h-4 w-4" />
              카메라로 바코드 스캔
            </Button>
            {scannedBarcode ? (
              <div className="rounded-lg border bg-muted/30 p-4">
                <p className="text-muted-foreground mb-1 text-sm">추출된 바코드 값</p>
                <p className="font-mono text-lg font-semibold break-all">{scannedBarcode}</p>
              </div>
            ) : (
              <p className="text-muted-foreground text-sm">아직 스캔한 바코드가 없습니다. 위 버튼으로 스캔해 보세요.</p>
            )}
          </CardContent>
        </Card>
        <Card className="shadow-sm">
          <CardHeader className="bg-gray-50/50">
            <CardTitle className="flex items-center justify-between">
@ -125,18 +95,6 @@ export default function BarcodeLabelManagementPage() {
            />
          </CardContent>
        </Card>
        <BarcodeScanModal
          open={scanModalOpen}
          onOpenChange={setScanModalOpen}
          targetField="바코드 값"
          barcodeFormat="all"
          autoSubmit={false}
          onScanSuccess={(barcode) => {
            setScannedBarcode(barcode);
            setScanModalOpen(false);
          }}
        />
      </div>
    </div>
  );
--- a/frontend/components/barcode/designer/BarcodeComponentPalette.tsx
+++ b/frontend/components/barcode/designer/BarcodeComponentPalette.tsx
@ -6,10 +6,9 @@ import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { BarcodeLabelComponent } from "@/types/barcode";
 import { v4 as uuidv4 } from "uuid";
-const ITEMS: { type: BarcodeLabelComponent["type"]; label: string; icon: React.ReactNode; barcodeType?: string }[] = [
+const ITEMS: { type: BarcodeLabelComponent["type"]; label: string; icon: React.ReactNode }[] = [
  { type: "text", label: "텍스트", icon: <Type className="h-4 w-4" /> },
  { type: "barcode", label: "바코드", icon: <Barcode className="h-4 w-4" /> },
  { type: "barcode", label: "QR 코드", icon: <Barcode className="h-4 w-4" />, barcodeType: "QR" },
  { type: "image", label: "이미지", icon: <Image className="h-4 w-4" /> },
  { type: "line", label: "선", icon: <Minus className="h-4 w-4" /> },
  { type: "rectangle", label: "사각형", icon: <Square className="h-4 w-4" /> },
@ -17,24 +16,22 @@ const ITEMS: { type: BarcodeLabelComponent["type"]; label: string; icon: React.R
 const MM_TO_PX = 4;
-function defaultComponent(type: BarcodeLabelComponent["type"], barcodeType?: string): BarcodeLabelComponent {
+function defaultComponent(type: BarcodeLabelComponent["type"]): BarcodeLabelComponent {
  const id = `comp_${uuidv4()}`;
  const base = { id, type, x: 10 * MM_TO_PX, y: 10 * MM_TO_PX, width: 80, height: 24, zIndex: 0 };
  switch (type) {
    case "text":
      return { ...base, content: "텍스트", fontSize: 10, fontColor: "#000000" };
-    case "barcode": {
+    case "barcode":
      const isQR = barcodeType === "QR";
      return {
        ...base,
-        width: isQR ? 100 : 120,
+        width: 120,
-        height: isQR ? 100 : 40,
+        height: 40,
-        barcodeType: barcodeType || "CODE128",
+        barcodeType: "CODE128",
-        barcodeValue: isQR ? "" : "123456789",
+        barcodeValue: "123456789",
-        showBarcodeText: !isQR,
+        showBarcodeText: true,
      };
    }
    case "image":
      return { ...base, width: 60, height: 60, imageUrl: "", objectFit: "contain" };
    case "line":
@ -50,16 +47,14 @@ function DraggableItem({
  type,
  label,
  icon,
  barcodeType,
 }: {
  type: BarcodeLabelComponent["type"];
  label: string;
  icon: React.ReactNode;
  barcodeType?: string;
 }) {
  const [{ isDragging }, drag] = useDrag(() => ({
    type: "barcode-component",
-    item: { component: defaultComponent(type, barcodeType) },
+    item: { component: defaultComponent(type) },
    collect: (m) => ({ isDragging: m.isDragging() }),
  }));
@ -83,14 +78,8 @@ export function BarcodeComponentPalette() {
        <CardTitle className="text-sm">요소 추가</CardTitle>
      </CardHeader>
      <CardContent className="space-y-2">
-        {ITEMS.map((item, idx) => (
+        {ITEMS.map((item) => (
-          <DraggableItem
+          <DraggableItem key={item.type} type={item.type} label={item.label} icon={item.icon} />
            key={item.barcodeType ? `${item.type}_${item.barcodeType}` : `${item.type}_${idx}`}
            type={item.type}
            label={item.label}
            icon={item.icon}
            barcodeType={item.barcodeType}
          />
        ))}
      </CardContent>
    </Card>
--- a/frontend/components/barcode/designer/BarcodeDesignerCanvas.tsx
+++ b/frontend/components/barcode/designer/BarcodeDesignerCanvas.tsx
@ -1,20 +1,14 @@
 "use client";
-import { useRef, useState, useEffect } from "react";
+import { useRef } from "react";
 import { useDrop } from "react-dnd";
 import { useBarcodeDesigner, MM_TO_PX } from "@/contexts/BarcodeDesignerContext";
 import { BarcodeLabelCanvasComponent } from "./BarcodeLabelCanvasComponent";
 import { BarcodeLabelComponent } from "@/types/barcode";
 import { v4 as uuidv4 } from "uuid";
 /** 작업 영역에 라벨이 들어가도록 스케일 (최소 0.5=작게 맞춤, 최대 3) */
 const MIN_SCALE = 0.5;
 const MAX_SCALE = 3;
 export function BarcodeDesignerCanvas() {
  const containerRef = useRef<HTMLDivElement>(null);
  const canvasRef = useRef<HTMLDivElement>(null);
  const [scale, setScale] = useState(1);
  const {
    widthMm,
    heightMm,
@ -28,45 +22,17 @@ export function BarcodeDesignerCanvas() {
  const widthPx = widthMm * MM_TO_PX;
  const heightPx = heightMm * MM_TO_PX;
  // 컨테이너 크기에 맞춰 캔버스 스케일 계산 (라벨이 너무 작게 보이지 않도록)
  useEffect(() => {
    const el = containerRef.current;
    if (!el || widthPx <= 0 || heightPx <= 0) return;
    const observer = new ResizeObserver(() => {
      const w = el.clientWidth - 48;
      const h = el.clientHeight - 48;
      if (w <= 0 || h <= 0) return;
      const scaleX = w / widthPx;
      const scaleY = h / heightPx;
      const fitScale = Math.min(scaleX, scaleY);
      const s = Math.max(MIN_SCALE, Math.min(MAX_SCALE, fitScale));
      setScale(s);
    });
    observer.observe(el);
    const w = el.clientWidth - 48;
    const h = el.clientHeight - 48;
    if (w > 0 && h > 0) {
      const scaleX = w / widthPx;
      const scaleY = h / heightPx;
      const fitScale = Math.min(scaleX, scaleY);
      const s = Math.max(MIN_SCALE, Math.min(MAX_SCALE, fitScale));
      setScale(s);
    }
    return () => observer.disconnect();
  }, [widthPx, heightPx]);
  const [{ isOver }, drop] = useDrop(() => ({
    accept: "barcode-component",
    drop: (item: { component: BarcodeLabelComponent }, monitor) => {
-      const canvasEl = canvasRef.current;
+      if (!canvasRef.current) return;
      if (!canvasEl) return;
      const offset = monitor.getClientOffset();
-      const rect = canvasEl.getBoundingClientRect();
+      const rect = canvasRef.current.getBoundingClientRect();
      if (!offset) return;
-      // 스케일 적용된 좌표 → 실제 캔버스 좌표
+
-      const s = scale;
+      let x = offset.x - rect.left;
-      let x = (offset.x - rect.left) / s;
+      let y = offset.y - rect.top;
-      let y = (offset.y - rect.top) / s;
+      // 드롭 시 요소 중앙이 커서에 오도록 보정
      x -= item.component.width / 2;
      y -= item.component.height / 2;
      x = Math.max(0, Math.min(x, widthPx - item.component.width));
@ -82,56 +48,36 @@ export function BarcodeDesignerCanvas() {
      addComponent(newComp);
    },
    collect: (m) => ({ isOver: m.isOver() }),
-  }), [widthPx, heightPx, scale, components.length, addComponent, snapValueToGrid]);
+  }), [widthPx, heightPx, components.length, addComponent, snapValueToGrid]);
  // 스케일된 캔버스가 컨테이너 안에 들어가도록 fit (하단 잘림 방지)
  const scaledW = widthPx * scale;
  const scaledH = heightPx * scale;
  return (
-    <div
+    <div className="flex flex-1 items-center justify-center overflow-auto bg-gray-100 p-6">
      ref={containerRef}
      className="flex min-h-0 flex-1 items-center justify-center overflow-auto bg-gray-100 p-6"
    >
      {/* 래퍼: 스케일된 크기만큼 차지해서 flex로 정확히 가운데 + 하단 잘림 방지 */}
      <div
-        className="flex shrink-0 items-center justify-center"
+        key={`canvas-${widthMm}-${heightMm}`}
-        style={{ width: scaledW, height: scaledH }}
+        ref={(r) => {
          (canvasRef as any).current = r;
          drop(r);
        }}
        className="relative bg-white shadow-lg"
        style={{
          width: widthPx,
          height: heightPx,
          minWidth: widthPx,
          minHeight: heightPx,
          backgroundImage: showGrid
            ? `linear-gradient(to right, #e5e7eb 1px, transparent 1px),
               linear-gradient(to bottom, #e5e7eb 1px, transparent 1px)`
            : undefined,
          backgroundSize: showGrid ? `${MM_TO_PX * 5}px ${MM_TO_PX * 5}px` : undefined,
          outline: isOver ? "2px dashed #2563eb" : "1px solid #d1d5db",
        }}
        onClick={(e) => {
          if (e.target === e.currentTarget) selectComponent(null);
        }}
      >
-        <div
+        {components.map((c) => (
-          style={{
+          <BarcodeLabelCanvasComponent key={c.id} component={c} />
-            transform: `scale(${scale})`,
+        ))}
            transformOrigin: "0 0",
          }}
        >
          <div
            key={`canvas-${widthMm}-${heightMm}`}
            ref={(r) => {
              (canvasRef as { current: HTMLDivElement | null }).current = r;
              drop(r);
            }}
            className="relative bg-white shadow-lg"
            style={{
              width: widthPx,
              height: heightPx,
              minWidth: widthPx,
              minHeight: heightPx,
              backgroundImage: showGrid
                ? `linear-gradient(to right, #e5e7eb 1px, transparent 1px),
                   linear-gradient(to bottom, #e5e7eb 1px, transparent 1px)`
                : undefined,
              backgroundSize: showGrid ? `${MM_TO_PX * 5}px ${MM_TO_PX * 5}px` : undefined,
              outline: isOver ? "2px dashed #2563eb" : "1px solid #d1d5db",
            }}
            onClick={(e) => {
              if (e.target === e.currentTarget) selectComponent(null);
            }}
          >
            {components.map((c) => (
              <BarcodeLabelCanvasComponent key={c.id} component={c} />
            ))}
          </div>
        </div>
      </div>
    </div>
  );
--- a/frontend/components/barcode/designer/BarcodeDesignerLeftPanel.tsx
+++ b/frontend/components/barcode/designer/BarcodeDesignerLeftPanel.tsx
@ -6,7 +6,7 @@ import { BarcodeComponentPalette } from "./BarcodeComponentPalette";
 export function BarcodeDesignerLeftPanel() {
  return (
-    <div className="flex min-h-0 w-72 shrink-0 flex-col overflow-hidden border-r bg-white">
+    <div className="flex min-h-0 w-64 shrink-0 flex-col overflow-hidden border-r bg-white">
      <div className="min-h-0 flex-1 overflow-hidden">
        <ScrollArea className="h-full">
          <div className="space-y-4 p-4">
--- a/frontend/components/barcode/designer/BarcodeDesignerRightPanel.tsx
+++ b/frontend/components/barcode/designer/BarcodeDesignerRightPanel.tsx
@ -1,125 +1,14 @@
 "use client";
 import { useState, useEffect } from "react";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 import { Button } from "@/components/ui/button";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
 import { Switch } from "@/components/ui/switch";
-import { Trash2, Plus } from "lucide-react";
+import { Trash2 } from "lucide-react";
 import { ScrollArea } from "@/components/ui/scroll-area";
 import { useBarcodeDesigner } from "@/contexts/BarcodeDesignerContext";
 import { BarcodeLabelComponent } from "@/types/barcode";
 // QR 기본 키: 품번, 품명, 규격
 const DEFAULT_QR_JSON_KEYS = ["part_no", "part_name", "spec"];
 function parseQRJsonValue(str: string): Record<string, string> {
  const trimmed = (str || "").trim();
  if (!trimmed) return {};
  try {
    const o = JSON.parse(trimmed);
    if (o && typeof o === "object" && !Array.isArray(o)) {
      return Object.fromEntries(
        Object.entries(o).map(([k, v]) => [String(k), v != null ? String(v) : ""])
      );
    }
  } catch {
    // ignore
  }
  return {};
 }
 function QRJsonFields({
  selected,
  update,
 }: {
  selected: BarcodeLabelComponent;
  update: (u: Partial<BarcodeLabelComponent>) => void;
 }) {
  const [pairs, setPairs] = useState<{ key: string; value: string }[]>(() => {
    const parsed = parseQRJsonValue(selected.barcodeValue || "");
    if (Object.keys(parsed).length > 0) {
      return Object.entries(parsed).map(([key, value]) => ({ key, value }));
    }
    return DEFAULT_QR_JSON_KEYS.map((key) => ({ key, value: "" }));
  });
  // 바코드 값이 바깥에서 바뀌면 파싱해서 동기화
  useEffect(() => {
    const parsed = parseQRJsonValue(selected.barcodeValue || "");
    if (Object.keys(parsed).length > 0) {
      setPairs(Object.entries(parsed).map(([key, value]) => ({ key, value: String(value ?? "") })));
    }
  }, [selected.barcodeValue]);
  const applyJson = () => {
    const obj: Record<string, string> = {};
    pairs.forEach(({ key, value }) => {
      const k = key.trim();
      if (k) obj[k] = value.trim();
    });
    update({ barcodeValue: JSON.stringify(obj) });
  };
  const setPair = (index: number, field: "key" | "value", val: string) => {
    setPairs((prev) => {
      const next = [...prev];
      if (!next[index]) next[index] = { key: "", value: "" };
      next[index] = { ...next[index], [field]: val };
      return next;
    });
  };
  const addRow = () => setPairs((prev) => [...prev, { key: "", value: "" }]);
  const removeRow = (index: number) =>
    setPairs((prev) => (prev.length <= 1 ? prev : prev.filter((_, i) => i !== index)));
  return (
    <div className="rounded-md border border-primary/30 bg-muted/20 p-3">
      <Label className="text-xs font-medium">여러 값 입력 → JSON으로 QR 생성</Label>
      <p className="text-muted-foreground mt-0.5 text-[10px]">키는 자유 입력, 값 입력 후 적용 버튼을 누르면 QR에 반영됩니다.</p>
      <div className="mt-2 space-y-2">
        {pairs.map((p, i) => (
          <div key={i} className="flex gap-1 items-center">
            <Input
              className="h-8 flex-1 min-w-0 text-xs"
              placeholder="키 (예: part_no)"
              value={p.key}
              onChange={(e) => setPair(i, "key", e.target.value)}
            />
            <Input
              className="h-8 flex-1 min-w-0 text-xs"
              placeholder="값"
              value={p.value}
              onChange={(e) => setPair(i, "value", e.target.value)}
            />
            <Button
              type="button"
              variant="ghost"
              size="icon"
              className="h-8 w-8 shrink-0 text-destructive"
              onClick={() => removeRow(i)}
              disabled={pairs.length <= 1}
            >
              <Trash2 className="h-3.5 w-3.5" />
            </Button>
          </div>
        ))}
      </div>
      <div className="mt-2 flex gap-1">
        <Button type="button" size="sm" variant="outline" className="flex-1 gap-1" onClick={addRow}>
          <Plus className="h-3.5 w-3.5" />
          필드 추가
        </Button>
        <Button type="button" size="sm" className="flex-1" onClick={applyJson}>
          JSON으로 QR 적용
        </Button>
      </div>
    </div>
  );
 }
 export function BarcodeDesignerRightPanel() {
  const {
    components,
@ -167,8 +56,8 @@ export function BarcodeDesignerRightPanel() {
    updateComponent(selected.id, updates);
  return (
-    <div className="flex w-72 flex-col border-l bg-white overflow-hidden">
+    <div className="w-72 border-l bg-white">
-      <div className="shrink-0 border-b p-2 flex items-center justify-between">
+      <div className="border-b p-2 flex items-center justify-between">
        <span className="text-sm font-medium">속성</span>
        <Button
          variant="ghost"
@ -182,7 +71,6 @@ export function BarcodeDesignerRightPanel() {
          <Trash2 className="h-4 w-4" />
        </Button>
      </div>
      <ScrollArea className="flex-1 min-h-0">
      <div className="space-y-4 p-4">
        <div className="grid grid-cols-2 gap-2">
          <div>
@ -273,15 +161,12 @@ export function BarcodeDesignerRightPanel() {
                </SelectContent>
              </Select>
            </div>
            {selected.barcodeType === "QR" && (
              <QRJsonFields selected={selected} update={update} />
            )}
            <div>
-              <Label className="text-xs">{selected.barcodeType === "QR" ? "값 (직접 JSON 입력)" : "값"}</Label>
+              <Label className="text-xs">값</Label>
              <Input
                value={selected.barcodeValue || ""}
                onChange={(e) => update({ barcodeValue: e.target.value })}
-                placeholder={selected.barcodeType === "QR" ? '{"part_no":"","part_name":"","spec":""}' : "123456789"}
+                placeholder="123456789"
              />
            </div>
            <div className="flex items-center gap-2">
@ -361,7 +246,6 @@ export function BarcodeDesignerRightPanel() {
          </div>
        )}
      </div>
      </ScrollArea>
    </div>
  );
 }
--- a/frontend/components/barcode/designer/BarcodeTemplatePalette.tsx
+++ b/frontend/components/barcode/designer/BarcodeTemplatePalette.tsx
@ -114,13 +114,11 @@ export function BarcodeTemplatePalette() {
                  key={t.template_id}
                  variant="outline"
                  size="sm"
-                  className="h-auto w-full justify-start px-2 py-1.5 text-left"
+                  className="h-auto w-full justify-start py-1.5 text-left"
                  onClick={() => applyTemplate(t.template_id)}
                >
-                  <span className="block break-words text-left text-xs leading-tight">
+                  <span className="truncate">{t.template_name_kor}</span>
-                    {t.template_name_kor}
+                  <span className="text-muted-foreground ml-1 shrink-0 text-xs">
                  </span>
                  <span className="text-muted-foreground mt-0.5 block text-[10px]">
                    {t.width_mm}×{t.height_mm}
                  </span>
                </Button>
--- a/frontend/components/common/BarcodeScanModal.tsx
+++ b/frontend/components/common/BarcodeScanModal.tsx
@ -46,6 +46,7 @@ export const BarcodeScanModal: React.FC<BarcodeScanModalProps> = ({
  useEffect(() => {
    if (open) {
      codeReaderRef.current = new BrowserMultiFormatReader();
      // 자동 권한 요청 제거 - 사용자가 버튼을 클릭해야 권한 요청
    }
    return () => {
@ -183,7 +184,7 @@ export const BarcodeScanModal: React.FC<BarcodeScanModalProps> = ({
        <DialogHeader>
          <DialogTitle className="text-base sm:text-lg">바코드 스캔</DialogTitle>
          <DialogDescription className="text-xs sm:text-sm">
-            카메라로 바코드를 스캔합니다.
+            카메라로 바코드를 스캔하세요.
            {targetField && ` (대상 필드: ${targetField})`}
          </DialogDescription>
        </DialogHeader>
--- a/frontend/components/common/MultiTableExcelUploadModal.tsx
+++ b/frontend/components/common/MultiTableExcelUploadModal.tsx
@ -1,786 +0,0 @@
 "use client";
 import React, { useState, useRef, useEffect } from "react";
 import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogFooter,
 } from "@/components/ui/dialog";
 import { Button } from "@/components/ui/button";
 import { Label } from "@/components/ui/label";
 import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
 } from "@/components/ui/select";
 import { toast } from "sonner";
 import {
  Upload,
  FileSpreadsheet,
  AlertCircle,
  CheckCircle2,
  ArrowRight,
  Zap,
  Download,
  Loader2,
 } from "lucide-react";
 import { importFromExcel, getExcelSheetNames, exportToExcel } from "@/lib/utils/excelExport";
 import { cn } from "@/lib/utils";
 import { EditableSpreadsheet } from "./EditableSpreadsheet";
 import {
  TableChainConfig,
  uploadMultiTableExcel,
 } from "@/lib/api/multiTableExcel";
 export interface MultiTableExcelUploadModalProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  config: TableChainConfig;
  onSuccess?: () => void;
 }
 interface ColumnMapping {
  excelColumn: string;
  targetColumn: string | null;
 }
 export const MultiTableExcelUploadModal: React.FC<MultiTableExcelUploadModalProps> = ({
  open,
  onOpenChange,
  config,
  onSuccess,
 }) => {
  // 스텝: 1=모드선택+파일, 2=컬럼매핑, 3=확인
  const [currentStep, setCurrentStep] = useState(1);
  // 모드 선택
  const [selectedModeId, setSelectedModeId] = useState<string>(
    config.uploadModes[0]?.id || ""
  );
  // 파일
  const [file, setFile] = useState<File | null>(null);
  const [sheetNames, setSheetNames] = useState<string[]>([]);
  const [selectedSheet, setSelectedSheet] = useState("");
  const [isDragOver, setIsDragOver] = useState(false);
  const fileInputRef = useRef<HTMLInputElement>(null);
  const [allData, setAllData] = useState<Record<string, any>[]>([]);
  const [displayData, setDisplayData] = useState<Record<string, any>[]>([]);
  const [excelColumns, setExcelColumns] = useState<string[]>([]);
  // 매핑
  const [columnMappings, setColumnMappings] = useState<ColumnMapping[]>([]);
  // 업로드
  const [isUploading, setIsUploading] = useState(false);
  const selectedMode = config.uploadModes.find((m) => m.id === selectedModeId);
  // 선택된 모드에서 활성화되는 컬럼 목록
  const activeColumns = React.useMemo(() => {
    if (!selectedMode) return [];
    const cols: Array<{ dbColumn: string; excelHeader: string; required: boolean; levelLabel: string }> = [];
    for (const levelIdx of selectedMode.activeLevels) {
      const level = config.levels[levelIdx];
      if (!level) continue;
      for (const col of level.columns) {
        cols.push({
          ...col,
          levelLabel: level.label,
        });
      }
    }
    return cols;
  }, [selectedMode, config.levels]);
  // 템플릿 다운로드
  const handleDownloadTemplate = () => {
    if (!selectedMode) return;
    const headers: string[] = [];
    const sampleRow: Record<string, string> = {};
    const sampleRow2: Record<string, string> = {};
    for (const levelIdx of selectedMode.activeLevels) {
      const level = config.levels[levelIdx];
      if (!level) continue;
      for (const col of level.columns) {
        headers.push(col.excelHeader);
        sampleRow[col.excelHeader] = col.required ? "(필수)" : "";
        sampleRow2[col.excelHeader] = "";
      }
    }
    // 예시 데이터 생성 (config에 맞춰)
    exportToExcel(
      [sampleRow, sampleRow2],
      `${config.name}_${selectedMode.label}_템플릿.xlsx`,
      "Sheet1"
    );
    toast.success("템플릿 파일이 다운로드되었습니다.");
  };
  // 파일 처리
  const processFile = async (selectedFile: File) => {
    const ext = selectedFile.name.split(".").pop()?.toLowerCase();
    if (!["xlsx", "xls", "csv"].includes(ext || "")) {
      toast.error("엑셀 파일만 업로드 가능합니다. (.xlsx, .xls, .csv)");
      return;
    }
    setFile(selectedFile);
    try {
      const sheets = await getExcelSheetNames(selectedFile);
      setSheetNames(sheets);
      setSelectedSheet(sheets[0] || "");
      const data = await importFromExcel(selectedFile, sheets[0]);
      setAllData(data);
      setDisplayData(data);
      if (data.length > 0) {
        setExcelColumns(Object.keys(data[0]));
      }
      toast.success(`파일 선택 완료: ${selectedFile.name}`);
    } catch (error) {
      console.error("파일 읽기 오류:", error);
      toast.error("파일을 읽는 중 오류가 발생했습니다.");
      setFile(null);
    }
  };
  const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const selectedFile = e.target.files?.[0];
    if (selectedFile) await processFile(selectedFile);
  };
  const handleDragOver = (e: React.DragEvent) => {
    e.preventDefault();
    e.stopPropagation();
    setIsDragOver(true);
  };
  const handleDragLeave = (e: React.DragEvent) => {
    e.preventDefault();
    e.stopPropagation();
    setIsDragOver(false);
  };
  const handleDrop = async (e: React.DragEvent) => {
    e.preventDefault();
    e.stopPropagation();
    setIsDragOver(false);
    const droppedFile = e.dataTransfer.files?.[0];
    if (droppedFile) await processFile(droppedFile);
  };
  const handleSheetChange = async (sheetName: string) => {
    setSelectedSheet(sheetName);
    if (!file) return;
    try {
      const data = await importFromExcel(file, sheetName);
      setAllData(data);
      setDisplayData(data);
      if (data.length > 0) {
        setExcelColumns(Object.keys(data[0]));
      }
    } catch (error) {
      console.error("시트 읽기 오류:", error);
      toast.error("시트를 읽는 중 오류가 발생했습니다.");
    }
  };
  // 2단계 진입 시 자동 매핑 시도
  useEffect(() => {
    if (currentStep === 2 && excelColumns.length > 0) {
      performAutoMapping();
    }
  }, [currentStep]);
  const performAutoMapping = () => {
    const newMappings: ColumnMapping[] = excelColumns.map((excelCol) => {
      const normalizedExcel = excelCol.toLowerCase().trim();
      const matched = activeColumns.find((ac) => {
        return (
          ac.excelHeader.toLowerCase().trim() === normalizedExcel ||
          ac.dbColumn.toLowerCase().trim() === normalizedExcel
        );
      });
      return {
        excelColumn: excelCol,
        targetColumn: matched ? matched.excelHeader : null,
      };
    });
    setColumnMappings(newMappings);
    const matchedCount = newMappings.filter((m) => m.targetColumn).length;
    if (matchedCount > 0) {
      toast.success(`${matchedCount}개 컬럼이 자동 매핑되었습니다.`);
    }
  };
  const handleMappingChange = (excelColumn: string, targetColumn: string | null) => {
    setColumnMappings((prev) =>
      prev.map((m) =>
        m.excelColumn === excelColumn ? { ...m, targetColumn } : m
      )
    );
  };
  // 업로드 실행
  const handleUpload = async () => {
    if (!file || !selectedMode) return;
    setIsUploading(true);
    try {
      // 엑셀 데이터를 excelHeader 기준으로 변환
      const mappedRows = allData.map((row) => {
        const mappedRow: Record<string, any> = {};
        columnMappings.forEach((mapping) => {
          if (mapping.targetColumn) {
            mappedRow[mapping.targetColumn] = row[mapping.excelColumn];
          }
        });
        return mappedRow;
      });
      // 빈 행 필터링
      const filteredRows = mappedRows.filter((row) =>
        Object.values(row).some(
          (v) => v !== undefined && v !== null && (typeof v !== "string" || v.trim() !== "")
        )
      );
      console.log(`다중 테이블 업로드: ${filteredRows.length}행`);
      const result = await uploadMultiTableExcel({
        config,
        modeId: selectedModeId,
        rows: filteredRows,
      });
      if (result.success && result.data) {
        const { results, errors } = result.data;
        const summaryParts = results
          .filter((r) => r.inserted + r.updated > 0)
          .map((r) => {
            const parts: string[] = [];
            if (r.inserted > 0) parts.push(`신규 ${r.inserted}건`);
            if (r.updated > 0) parts.push(`수정 ${r.updated}건`);
            return `${r.tableName}: ${parts.join(", ")}`;
          });
        const msg = summaryParts.join(" / ");
        const errorMsg = errors.length > 0 ? ` (오류: ${errors.length}건)` : "";
        toast.success(`업로드 완료: ${msg}${errorMsg}`);
        if (errors.length > 0) {
          console.warn("업로드 오류 목록:", errors);
        }
        onSuccess?.();
        onOpenChange(false);
      } else {
        toast.error(result.message || "업로드에 실패했습니다.");
      }
    } catch (error) {
      console.error("다중 테이블 업로드 실패:", error);
      toast.error("업로드 중 오류가 발생했습니다.");
    } finally {
      setIsUploading(false);
    }
  };
  // 다음/이전 단계
  const handleNext = () => {
    if (currentStep === 1) {
      if (!file) {
        toast.error("파일을 선택해주세요.");
        return;
      }
      if (displayData.length === 0) {
        toast.error("데이터가 없습니다.");
        return;
      }
    }
    if (currentStep === 2) {
      // 필수 컬럼 매핑 확인
      const mappedTargets = new Set(
        columnMappings.filter((m) => m.targetColumn).map((m) => m.targetColumn)
      );
      const unmappedRequired = activeColumns
        .filter((ac) => ac.required && !mappedTargets.has(ac.excelHeader))
        .map((ac) => `${ac.excelHeader}`);
      if (unmappedRequired.length > 0) {
        toast.error(`필수 컬럼이 매핑되지 않았습니다: ${unmappedRequired.join(", ")}`);
        return;
      }
    }
    setCurrentStep((prev) => Math.min(prev + 1, 3));
  };
  const handlePrevious = () => {
    setCurrentStep((prev) => Math.max(prev - 1, 1));
  };
  // 모달 닫기 시 초기화
  useEffect(() => {
    if (!open) {
      setCurrentStep(1);
      setSelectedModeId(config.uploadModes[0]?.id || "");
      setFile(null);
      setSheetNames([]);
      setSelectedSheet("");
      setAllData([]);
      setDisplayData([]);
      setExcelColumns([]);
      setColumnMappings([]);
    }
  }, [open, config.uploadModes]);
  return (
    <Dialog open={open} onOpenChange={onOpenChange}>
      <DialogContent
        className="max-h-[95vh] max-w-[95vw] sm:max-w-[1200px]"
        style={{ width: "1000px", height: "700px", minWidth: "700px", minHeight: "500px", maxWidth: "1400px", maxHeight: "900px" }}
      >
        <DialogHeader>
          <DialogTitle className="flex items-center gap-2 text-base sm:text-lg">
            <FileSpreadsheet className="h-5 w-5" />
            {config.name} - 엑셀 업로드
            <span className="ml-2 rounded bg-indigo-100 px-2 py-0.5 text-xs font-normal text-indigo-700">
              다중 테이블
            </span>
          </DialogTitle>
          <DialogDescription className="text-xs sm:text-sm">
            {config.description}
          </DialogDescription>
        </DialogHeader>
        {/* 스텝 인디케이터 */}
        <div className="flex items-center justify-between">
          {[
            { num: 1, label: "모드 선택 / 파일" },
            { num: 2, label: "컬럼 매핑" },
            { num: 3, label: "확인" },
          ].map((step, index) => (
            <React.Fragment key={step.num}>
              <div className="flex flex-col items-center gap-1">
                <div
                  className={cn(
                    "flex h-8 w-8 items-center justify-center rounded-full text-sm font-medium transition-colors sm:h-10 sm:w-10",
                    currentStep === step.num
                      ? "bg-primary text-primary-foreground"
                      : currentStep > step.num
                        ? "bg-success text-white"
                        : "bg-muted text-muted-foreground"
                  )}
                >
                  {currentStep > step.num ? (
                    <CheckCircle2 className="h-4 w-4 sm:h-5 sm:w-5" />
                  ) : (
                    step.num
                  )}
                </div>
                <span
                  className={cn(
                    "text-[10px] font-medium sm:text-xs",
                    currentStep === step.num ? "text-primary" : "text-muted-foreground"
                  )}
                >
                  {step.label}
                </span>
              </div>
              {index < 2 && (
                <div
                  className={cn(
                    "h-0.5 flex-1 transition-colors",
                    currentStep > step.num ? "bg-success" : "bg-muted"
                  )}
                />
              )}
            </React.Fragment>
          ))}
        </div>
        {/* 스텝별 컨텐츠 */}
        <div className="max-h-[calc(95vh-200px)] space-y-4 overflow-y-auto">
          {/* 1단계: 모드 선택 + 파일 선택 */}
          {currentStep === 1 && (
            <div className="space-y-4">
              {/* 업로드 모드 선택 */}
              <div>
                <Label className="text-xs font-medium sm:text-sm">업로드 모드 *</Label>
                <div className="mt-2 grid gap-2 sm:grid-cols-3">
                  {config.uploadModes.map((mode) => (
                    <button
                      key={mode.id}
                      type="button"
                      onClick={() => {
                        setSelectedModeId(mode.id);
                        setFile(null);
                        setAllData([]);
                        setDisplayData([]);
                        setExcelColumns([]);
                      }}
                      className={cn(
                        "rounded-lg border p-3 text-left transition-all",
                        selectedModeId === mode.id
                          ? "border-primary bg-primary/5 ring-2 ring-primary/20"
                          : "border-border hover:border-primary/50 hover:bg-muted/50"
                      )}
                    >
                      <p className="text-xs font-semibold sm:text-sm">{mode.label}</p>
                      <p className="mt-1 text-[10px] text-muted-foreground sm:text-xs">
                        {mode.description}
                      </p>
                    </button>
                  ))}
                </div>
              </div>
              {/* 템플릿 다운로드 */}
              <div className="flex items-center justify-between rounded-md border border-muted bg-muted/30 p-3">
                <div className="flex items-center gap-2 text-xs text-muted-foreground sm:text-sm">
                  <Download className="h-4 w-4" />
                  <span>선택한 모드에 맞는 엑셀 양식을 다운로드하세요</span>
                </div>
                <Button
                  variant="outline"
                  size="sm"
                  onClick={handleDownloadTemplate}
                  className="h-8 text-xs sm:text-sm"
                >
                  <Download className="mr-1 h-3 w-3" />
                  템플릿 다운로드
                </Button>
              </div>
              {/* 파일 선택 */}
              <div>
                <Label htmlFor="multi-file-upload" className="text-xs sm:text-sm">
                  파일 선택 *
                </Label>
                <div
                  onDragOver={handleDragOver}
                  onDragLeave={handleDragLeave}
                  onDrop={handleDrop}
                  onClick={() => fileInputRef.current?.click()}
                  className={cn(
                    "mt-2 flex cursor-pointer flex-col items-center justify-center rounded-lg border-2 border-dashed p-4 transition-colors",
                    isDragOver
                      ? "border-primary bg-primary/5"
                      : file
                        ? "border-green-500 bg-green-50"
                        : "border-muted-foreground/25 hover:border-primary hover:bg-muted/50"
                  )}
                >
                  {file ? (
                    <div className="flex items-center gap-3">
                      <FileSpreadsheet className="h-8 w-8 text-green-600" />
                      <div>
                        <p className="text-sm font-medium text-green-700">{file.name}</p>
                        <p className="text-xs text-muted-foreground">
                          클릭하여 다른 파일 선택
                        </p>
                      </div>
                    </div>
                  ) : (
                    <>
                      <Upload
                        className={cn(
                          "mb-2 h-8 w-8",
                          isDragOver ? "text-primary" : "text-muted-foreground"
                        )}
                      />
                      <p
                        className={cn(
                          "text-sm font-medium",
                          isDragOver ? "text-primary" : "text-muted-foreground"
                        )}
                      >
                        {isDragOver ? "파일을 놓으세요" : "파일을 드래그하거나 클릭하여 선택"}
                      </p>
                      <p className="mt-1 text-xs text-muted-foreground">
                        지원 형식: .xlsx, .xls, .csv
                      </p>
                    </>
                  )}
                  <input
                    ref={fileInputRef}
                    id="multi-file-upload"
                    type="file"
                    accept=".xlsx,.xls,.csv"
                    onChange={handleFileChange}
                    className="hidden"
                  />
                </div>
              </div>
              {/* 미리보기 */}
              {file && displayData.length > 0 && (
                <>
                  <div className="flex items-center gap-3">
                    <div className="flex items-center gap-2">
                      <Label className="text-xs text-muted-foreground sm:text-sm">시트:</Label>
                      <Select value={selectedSheet} onValueChange={handleSheetChange}>
                        <SelectTrigger className="h-8 w-[140px] text-xs sm:h-9 sm:w-[180px] sm:text-sm">
                          <SelectValue placeholder="Sheet1" />
                        </SelectTrigger>
                        <SelectContent>
                          {sheetNames.map((name) => (
                            <SelectItem key={name} value={name} className="text-xs sm:text-sm">
                              {name}
                            </SelectItem>
                          ))}
                        </SelectContent>
                      </Select>
                    </div>
                    <span className="text-xs text-muted-foreground">
                      {displayData.length}개 행
                    </span>
                  </div>
                  <EditableSpreadsheet
                    columns={excelColumns}
                    data={displayData}
                    onColumnsChange={setExcelColumns}
                    onDataChange={(newData) => {
                      setDisplayData(newData);
                      setAllData(newData);
                    }}
                    maxHeight="250px"
                  />
                </>
              )}
            </div>
          )}
          {/* 2단계: 컬럼 매핑 */}
          {currentStep === 2 && (
            <div className="space-y-4">
              <div className="flex items-center justify-between">
                <h3 className="text-sm font-semibold sm:text-base">컬럼 매핑 설정</h3>
                <Button
                  type="button"
                  variant="default"
                  size="sm"
                  onClick={performAutoMapping}
                  className="h-8 text-xs sm:h-9 sm:text-sm"
                >
                  <Zap className="mr-2 h-4 w-4" />
                  자동 매핑
                </Button>
              </div>
              <div className="space-y-2">
                <div className="grid grid-cols-[1fr_auto_1fr] gap-2 text-[10px] font-medium text-muted-foreground sm:text-xs">
                  <div>엑셀 컬럼</div>
                  <div></div>
                  <div>시스템 컬럼</div>
                </div>
                <div className="max-h-[300px] space-y-2 overflow-y-auto">
                  {columnMappings.map((mapping, index) => (
                    <div
                      key={index}
                      className="grid grid-cols-[1fr_auto_1fr] items-center gap-2"
                    >
                      <div className="rounded-md border border-border bg-muted px-3 py-2 text-xs font-medium sm:text-sm">
                        {mapping.excelColumn}
                      </div>
                      <ArrowRight className="h-4 w-4 text-muted-foreground" />
                      <Select
                        value={mapping.targetColumn || "none"}
                        onValueChange={(value) =>
                          handleMappingChange(
                            mapping.excelColumn,
                            value === "none" ? null : value
                          )
                        }
                      >
                        <SelectTrigger className="h-8 text-xs sm:h-10 sm:text-sm">
                          <SelectValue placeholder="매핑 안함">
                            {mapping.targetColumn || "매핑 안함"}
                          </SelectValue>
                        </SelectTrigger>
                        <SelectContent>
                          <SelectItem value="none" className="text-xs sm:text-sm">
                            매핑 안함
                          </SelectItem>
                          {activeColumns.map((ac) => (
                            <SelectItem
                              key={`${ac.levelLabel}-${ac.dbColumn}`}
                              value={ac.excelHeader}
                              className="text-xs sm:text-sm"
                            >
                              {ac.required && (
                                <span className="mr-1 text-destructive">*</span>
                              )}
                              [{ac.levelLabel}] {ac.excelHeader} ({ac.dbColumn})
                            </SelectItem>
                          ))}
                        </SelectContent>
                      </Select>
                    </div>
                  ))}
                </div>
              </div>
              {/* 미매핑 필수 컬럼 경고 */}
              {(() => {
                const mappedTargets = new Set(
                  columnMappings.filter((m) => m.targetColumn).map((m) => m.targetColumn)
                );
                const missing = activeColumns.filter(
                  (ac) => ac.required && !mappedTargets.has(ac.excelHeader)
                );
                if (missing.length === 0) return null;
                return (
                  <div className="rounded-md border border-destructive/50 bg-destructive/10 p-3">
                    <div className="flex items-start gap-2">
                      <AlertCircle className="mt-0.5 h-4 w-4 text-destructive" />
                      <div className="text-[10px] text-destructive sm:text-xs">
                        <p className="font-medium">필수 컬럼이 매핑되지 않았습니다:</p>
                        <p className="mt-1">
                          {missing.map((m) => `[${m.levelLabel}] ${m.excelHeader}`).join(", ")}
                        </p>
                      </div>
                    </div>
                  </div>
                );
              })()}
              {/* 모드 정보 */}
              {selectedMode && (
                <div className="rounded-md border border-muted bg-muted/30 p-3">
                  <div className="flex items-start gap-2">
                    <Zap className="mt-0.5 h-4 w-4 text-muted-foreground" />
                    <div className="text-[10px] text-muted-foreground sm:text-xs">
                      <p className="font-medium">모드: {selectedMode.label}</p>
                      <p className="mt-1">
                        대상 테이블:{" "}
                        {selectedMode.activeLevels
                          .map((i) => config.levels[i]?.label)
                          .filter(Boolean)
                          .join(" → ")}
                      </p>
                    </div>
                  </div>
                </div>
              )}
            </div>
          )}
          {/* 3단계: 확인 */}
          {currentStep === 3 && (
            <div className="space-y-4">
              <div className="rounded-md border border-border bg-muted/50 p-4">
                <h3 className="text-sm font-medium sm:text-base">업로드 요약</h3>
                <div className="mt-2 space-y-1 text-[10px] text-muted-foreground sm:text-xs">
                  <p><span className="font-medium">파일:</span> {file?.name}</p>
                  <p><span className="font-medium">시트:</span> {selectedSheet}</p>
                  <p><span className="font-medium">데이터 행:</span> {allData.length}개</p>
                  <p><span className="font-medium">모드:</span> {selectedMode?.label}</p>
                  <p>
                    <span className="font-medium">대상 테이블:</span>{" "}
                    {selectedMode?.activeLevels
                      .map((i) => {
                        const level = config.levels[i];
                        return level
                          ? `${level.label}(${level.tableName})`
                          : "";
                      })
                      .filter(Boolean)
                      .join(" → ")}
                  </p>
                </div>
              </div>
              <div className="rounded-md border border-border bg-muted/50 p-4">
                <h3 className="text-sm font-medium sm:text-base">컬럼 매핑</h3>
                <div className="mt-2 space-y-1 text-[10px] text-muted-foreground sm:text-xs">
                  {columnMappings
                    .filter((m) => m.targetColumn)
                    .map((mapping, idx) => {
                      const ac = activeColumns.find(
                        (c) => c.excelHeader === mapping.targetColumn
                      );
                      return (
                        <p key={idx}>
                          <span className="font-medium">{mapping.excelColumn}</span>{" "}
                          → [{ac?.levelLabel}] {mapping.targetColumn}
                        </p>
                      );
                    })}
                </div>
              </div>
              <div className="rounded-md border border-warning bg-warning/10 p-3">
                <div className="flex items-start gap-2">
                  <AlertCircle className="mt-0.5 h-4 w-4 text-warning" />
                  <div className="text-[10px] text-warning sm:text-xs">
                    <p className="font-medium">주의사항</p>
                    <p className="mt-1">
                      업로드를 진행하면 데이터가 데이터베이스에 저장됩니다.
                      같은 키 값의 기존 데이터는 업데이트됩니다.
                    </p>
                  </div>
                </div>
              </div>
            </div>
          )}
        </div>
        <DialogFooter className="gap-2 sm:gap-0">
          <Button
            variant="outline"
            onClick={currentStep === 1 ? () => onOpenChange(false) : handlePrevious}
            disabled={isUploading}
            className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm"
          >
            {currentStep === 1 ? "취소" : "이전"}
          </Button>
          {currentStep < 3 ? (
            <Button
              onClick={handleNext}
              disabled={isUploading || (currentStep === 1 && !file)}
              className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm"
            >
              다음
            </Button>
          ) : (
            <Button
              onClick={handleUpload}
              disabled={isUploading || columnMappings.filter((m) => m.targetColumn).length === 0}
              className="h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm"
            >
              {isUploading ? (
                <>
                  <Loader2 className="mr-2 h-4 w-4 animate-spin" />
                  업로드 중...
                </>
              ) : (
                "업로드"
              )}
            </Button>
          )}
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
 };
--- a/frontend/components/layout/MainSidebar.tsx
+++ b/frontend/components/layout/MainSidebar.tsx
@ -1,4 +1,4 @@
-import { ChevronDown, ChevronRight, Home, FileText, Users, BarChart3, Cog, GitBranch, Bot } from "lucide-react";
+import { ChevronDown, ChevronRight, Home, FileText, Users, BarChart3, Cog, GitBranch } from "lucide-react";
 import { cn } from "@/lib/utils";
 import { MenuItem } from "@/types/menu";
 import { MENU_ICONS, MESSAGES } from "@/constants/layout";
@ -38,9 +38,6 @@ const getMenuIcon = (menuName: string, dbIconName?: string | null) => {
  if (MENU_ICONS.DATAFLOW.some((keyword) => menuName.includes(keyword))) {
    return <GitBranch className="h-4 w-4" />;
  }
  if (MENU_ICONS.AI.some((keyword) => menuName.includes(keyword))) {
    return <Bot className="h-4 w-4" />;
  }
  return <FileText className="h-4 w-4" />;
 };
--- a/frontend/components/screen/config-panels/ButtonConfigPanel.tsx
+++ b/frontend/components/screen/config-panels/ButtonConfigPanel.tsx
@ -851,7 +851,6 @@ export const ButtonConfigPanel: React.FC<ButtonConfigPanelProps> = ({
            {/* 엑셀 관련 */}
            <SelectItem value="excel_download">엑셀 다운로드</SelectItem>
            <SelectItem value="excel_upload">엑셀 업로드</SelectItem>
            <SelectItem value="multi_table_excel_upload">다중 테이블 엑셀 업로드</SelectItem>
            {/* 고급 기능 */}
            <SelectItem value="quickInsert">즉시 저장</SelectItem>
@ -2431,8 +2430,6 @@ export const ButtonConfigPanel: React.FC<ButtonConfigPanelProps> = ({
        />
      )}
      {/* 다중 테이블 엑셀 업로드: 설정 불필요 (버튼 클릭 시 화면 테이블에서 자동 감지) */}
      {/* 바코드 스캔 액션 설정 */}
      {localInputs.actionType === "barcode_scan" && (
        <div className="bg-muted/50 mt-4 space-y-4 rounded-lg border p-4">
@ -4000,8 +3997,8 @@ export const ButtonConfigPanel: React.FC<ButtonConfigPanelProps> = ({
        )}
      </div>
-      {/* 제어 기능 섹션 - 엑셀 업로드 계열이 아닐 때만 표시 */}
+      {/* 제어 기능 섹션 - 엑셀 업로드가 아닐 때만 표시 */}
-      {localInputs.actionType !== "excel_upload" && localInputs.actionType !== "multi_table_excel_upload" && (
+      {localInputs.actionType !== "excel_upload" && (
        <div className="border-border mt-8 border-t pt-6">
          <ImprovedButtonControlConfigPanel component={component} onUpdateProperty={onUpdateProperty} />
        </div>
@ -4690,4 +4687,3 @@ const ExcelUploadConfigSection: React.FC<{
    </div>
  );
 };
--- a/frontend/components/ui/badge.tsx
+++ b/frontend/components/ui/badge.tsx
@ -12,8 +12,6 @@ const badgeVariants = cva(
        secondary: "border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80",
        destructive: "border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80",
        outline: "text-foreground",
        success: "border-transparent bg-green-500 text-white hover:bg-green-600",
        warning: "border-transparent bg-yellow-500 text-white hover:bg-yellow-600",
      },
    },
    defaultVariants: {
--- a/frontend/components/v2/config-panels/V2RepeaterConfigPanel.tsx
+++ b/frontend/components/v2/config-panels/V2RepeaterConfigPanel.tsx
@ -365,14 +365,6 @@ export const V2RepeaterConfigPanel: React.FC<V2RepeaterConfigPanelProps> = ({
    fetchEntityJoinColumns();
  }, [entityJoinTargetTable]);
  // 설정 업데이트 헬퍼
  const updateConfig = useCallback(
    (updates: Partial<V2RepeaterConfig>) => {
      onChange({ ...config, ...updates });
    },
    [config, onChange],
  );
  // Entity 조인 컬럼 토글 (추가/제거)
  const toggleEntityJoinColumn = useCallback(
    (joinTableName: string, sourceColumn: string, refColumnName: string, refColumnLabel: string, displayField: string) => {
@ -431,6 +423,14 @@ export const V2RepeaterConfigPanel: React.FC<V2RepeaterConfigPanelProps> = ({
    [config.entityJoins],
  );
  // 설정 업데이트 헬퍼
  const updateConfig = useCallback(
    (updates: Partial<V2RepeaterConfig>) => {
      onChange({ ...config, ...updates });
    },
    [config, onChange],
  );
  const updateDataSource = useCallback(
    (field: string, value: any) => {
      updateConfig({
--- a/frontend/constants/layout.ts
+++ b/frontend/constants/layout.ts
@ -41,5 +41,4 @@ export const MENU_ICONS = {
  STATISTICS: ["통계", "분석", "리포트", "차트"],
  SETTINGS: ["설정", "관리", "시스템"],
  DATAFLOW: ["데이터", "흐름", "관계", "연결"],
  AI: ["AI", "어시스턴트", "챗봇", "LLM"],
 } as const;
--- a/frontend/docs/AI_어시스턴트_메뉴_등록_가이드.md
+++ b/frontend/docs/AI_어시스턴트_메뉴_등록_가이드.md
@ -1,50 +0,0 @@
 # AI 어시스턴트 메뉴 등록 가이드 (VEXPLOR)
 AI 어시스턴트는 **VEXPLOR와 같은 서비스/같은 포트**로 동작합니다.  
 프론트는 `/api/ai/v1` 로 호출하고, backend-node가 AI 서비스(기본 3100 포트)로 프록시합니다.
 ## 서비스 기동
 - **AI API**: `ERP-node/ai-assistant` 에서 `npm install` 후 `npm start` (포트 3100)
 - **backend-node**: `npm run dev` (8080)
 - **frontend**: `npm run dev` (9771)
 별도 포트/도메인 설정 없이 브라우저에서는 **localhost:9771** 만 사용하면 됩니다.
 ---
 ## VEXPLOR 메뉴 URL 목록 (전체 탑재)
 대메뉴 예: **AI 서비스** / **AI**  
 소메뉴는 아래 표의 **메뉴명**과 **URL**로 등록하면 됩니다. (메뉴명에 "AI", "어시스턴트", "챗봇", "LLM" 포함 시 사이드바에 Bot 아이콘 표시)
 ### 일반 메뉴
 | 메뉴명       | URL (메뉴 관리에 입력할 값)   |
 |-------------|-------------------------------|
 | AI 채팅     | /admin/aiAssistant/chat       |
 | 대시보드    | /admin/aiAssistant/dashboard  |
 | API 키 관리 | /admin/aiAssistant/api-keys   |
 | API 테스트  | /admin/aiAssistant/api-test   |
 | 내 사용량   | /admin/aiAssistant/usage       |
 | 대화 이력   | /admin/aiAssistant/history    |
 | 설정        | /admin/aiAssistant/settings    |
 ### 관리자 메뉴
 | 메뉴명           | URL (메뉴 관리에 입력할 값)        |
 |------------------|------------------------------------|
 | 사용자 관리      | /admin/aiAssistant/admin/users     |
 | LLM 관리         | /admin/aiAssistant/admin/providers  |
 | LLM 사용량 통계  | /admin/aiAssistant/admin/usage-stats |
 ---
 ## 등록 순서 예시
 1. **대메뉴**: 메뉴명 `AI 서비스`, URL은 비우거나 `#` (자식만 사용할 경우)
 2. **소메뉴**: 위 표에서 필요한 것만 추가
   - 예: 메뉴명 `대시보드`, URL `/admin/aiAssistant/dashboard`
   - 예: 메뉴명 `API 키 관리`, URL `/admin/aiAssistant/api-keys`
 이렇게 등록하면 VEXPLOR 사이드바에서 각 메뉴 클릭 시 해당 AI 어시스턴트 화면이 열립니다.
--- a/frontend/lib/api/aiAssistant/client.ts
+++ b/frontend/lib/api/aiAssistant/client.ts
@ -1,127 +0,0 @@
 /**
 * AI 어시스턴트 전용 API 클라이언트
 * - VEXPLOR와 같은 서비스/같은 포트: /api/ai/v1 로 호출 (Next → backend-node → AI 서비스 프록시)
 * - 인증 토큰은 sessionStorage 'ai-assistant-auth' 사용 (VEXPLOR 인증과 분리)
 */
 import axios, { AxiosError } from "axios";
 import type { AiAssistantAuthState } from "./types";
 const STORAGE_KEY = "ai-assistant-auth";
 /** 같은 오리진 기준 AI API prefix (backend-node가 /api/ai/v1 을 AI 서비스로 프록시) */
 function getBaseUrl(): string {
  if (typeof window === "undefined") return "";
  return "/api/ai/v1";
 }
 export function getAiAssistantAuth(): AiAssistantAuthState | null {
  if (typeof window === "undefined") return null;
  try {
    const raw = sessionStorage.getItem(STORAGE_KEY);
    return raw ? (JSON.parse(raw) as AiAssistantAuthState) : null;
  } catch {
    return null;
  }
 }
 export function setAiAssistantAuth(state: AiAssistantAuthState | null): void {
  if (typeof window === "undefined") return;
  if (state) sessionStorage.setItem(STORAGE_KEY, JSON.stringify(state));
  else sessionStorage.removeItem(STORAGE_KEY);
 }
 export function getAiAssistantAccessToken(): string | null {
  return getAiAssistantAuth()?.accessToken ?? null;
 }
 let refreshing = false;
 const queue: Array<{ resolve: (t: string) => void; reject: (e: unknown) => void }> = [];
 function processQueue(error: unknown, token: string | null) {
  queue.forEach((p) => (error ? p.reject(error) : p.resolve(token!)));
  queue.length = 0;
 }
 const client = axios.create({
  baseURL: "",
  headers: { "Content-Type": "application/json" },
 });
 client.interceptors.request.use((config) => {
  const base = getBaseUrl();
  if (base) config.baseURL = base;
  const token = getAiAssistantAccessToken();
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
 });
 client.interceptors.response.use(
  (res) => res,
  async (err: AxiosError) => {
    const original = err.config as typeof err.config & { _retry?: boolean };
    const isAuth = original?.url?.includes("/auth/");
    if (isAuth || err.response?.status !== 401 || original?._retry) {
      return Promise.reject(err);
    }
    if (refreshing) {
      return new Promise<string>((resolve, reject) => {
        queue.push({ resolve, reject });
      })
        .then((token) => {
          if (original.headers) original.headers.Authorization = `Bearer ${token}`;
          return client(original);
        })
        .catch((e) => Promise.reject(e));
    }
    original._retry = true;
    refreshing = true;
    const auth = getAiAssistantAuth();
    try {
      if (!auth?.refreshToken) throw new Error("No refresh token");
      const base = getBaseUrl();
      const { data } = await axios.post<{ data: { accessToken: string } }>(
        `${base}/auth/refresh`,
        { refreshToken: auth.refreshToken },
        { headers: { "Content-Type": "application/json" } },
      );
      const newToken = data?.data?.accessToken;
      if (!newToken) throw new Error("No access token");
      const newState: AiAssistantAuthState = {
        ...auth,
        accessToken: newToken,
      };
      setAiAssistantAuth(newState);
      processQueue(null, newToken);
      if (original.headers) original.headers.Authorization = `Bearer ${newToken}`;
      return client(original);
    } catch (e) {
      processQueue(e, null);
      setAiAssistantAuth(null);
      return Promise.reject(err);
    } finally {
      refreshing = false;
    }
  },
 );
 /** AI 어시스턴트 로그인 (이메일/비밀번호) */
 export async function loginAiAssistant(
  email: string,
  password: string,
 ): Promise<AiAssistantAuthState> {
  const base = getBaseUrl();
  const { data } = await axios.post<{
    data: { user: AiAssistantAuthState["user"]; accessToken: string; refreshToken: string };
  }>(`${base}/auth/login`, { email, password }, { headers: { "Content-Type": "application/json" }, withCredentials: true });
  const state: AiAssistantAuthState = {
    user: data.data.user,
    accessToken: data.data.accessToken,
    refreshToken: data.data.refreshToken,
  };
  setAiAssistantAuth(state);
  return state;
 }
 export default client;
--- a/frontend/lib/api/aiAssistant/index.ts
+++ b/frontend/lib/api/aiAssistant/index.ts
@ -1,8 +0,0 @@
 export { default as aiAssistantApi } from "./client";
 export {
  getAiAssistantAuth,
  setAiAssistantAuth,
  getAiAssistantAccessToken,
  loginAiAssistant,
 } from "./client";
 export * from "./types";
--- a/frontend/lib/api/aiAssistant/types.ts
+++ b/frontend/lib/api/aiAssistant/types.ts
@ -1,70 +0,0 @@
 /**
 * AI 어시스턴트 API 응답/요청 타입 (workspace_assistant 백엔드 연동)
 */
 export interface AiAssistantUser {
  id: number;
  email: string;
  name: string;
  role: "user" | "admin";
  status?: string;
  plan?: string;
  monthlyTokenLimit?: number;
  createdAt?: string;
 }
 export interface AiAssistantAuthState {
  user: AiAssistantUser;
  accessToken: string;
  refreshToken: string;
 }
 export interface UsageSummary {
  usage?: {
    today?: { tokens?: number; requests?: number };
    monthly?: { totalTokens?: number; totalCost?: number };
  };
  limit?: { monthly?: number };
  plan?: string;
 }
 export interface ApiKeyItem {
  id: number;
  name: string;
  keyPrefix: string;
  status: string;
  usageCount?: number;
  lastUsedAt?: string | null;
  createdAt: string;
 }
 export interface UsageLogItem {
  id: number;
  success: boolean;
  providerName?: string;
  modelName?: string;
  promptTokens?: number;
  completionTokens?: number;
  totalTokens?: number;
  costUsd?: number;
  responseTimeMs?: number;
  createdAt: string;
 }
 export interface AdminStats {
  users?: { total?: number; active?: number };
  apiKeys?: { total?: number };
  providers?: { active?: number };
 }
 export interface LlmProvider {
  id: number;
  displayName: string;
  modelName: string;
  apiKey?: string;
  priority: number;
  maxTokens?: number;
  temperature?: number;
  isActive: boolean;
  costPer1kInputTokens?: number;
 }
--- a/frontend/lib/api/multiTableExcel.ts
+++ b/frontend/lib/api/multiTableExcel.ts
@ -1,98 +0,0 @@
 /**
 * 다중 테이블 엑셀 업로드 API 클라이언트
 */
 import { apiClient } from "./client";
 /** 테이블 계층 레벨 설정 */
 export interface TableLevel {
  tableName: string;
  label: string;
  parentFkColumn?: string;
  parentRefColumn?: string;
  upsertMode: "upsert" | "insert";
  upsertKeyColumns?: string[];
  columns: ColumnDef[];
 }
 /** 컬럼 정의 */
 export interface ColumnDef {
  dbColumn: string;
  excelHeader: string;
  required: boolean;
  defaultValue?: any;
 }
 /** 업로드 모드 정의 */
 export interface UploadMode {
  id: string;
  label: string;
  description: string;
  activeLevels: number[];
 }
 /** 테이블 체인 설정 */
 export interface TableChainConfig {
  id: string;
  name: string;
  description: string;
  levels: TableLevel[];
  uploadModes: UploadMode[];
 }
 /** 레벨별 결과 */
 export interface LevelResult {
  tableName: string;
  inserted: number;
  updated: number;
 }
 /** 업로드 결과 */
 export interface MultiTableUploadResult {
  success: boolean;
  results: LevelResult[];
  totalRows: number;
  errors: string[];
 }
 /**
 * 루트 테이블명으로 TableChainConfig를 자동 감지
 * DB FK 관계 + 컬럼 메타데이터를 분석하여 실시간 생성
 */
 export async function autoDetectMultiTableConfig(
  rootTable: string,
  screenId?: number
 ): Promise<{ success: boolean; data?: TableChainConfig; message?: string }> {
  try {
    const params: Record<string, any> = { rootTable };
    if (screenId) params.screenId = screenId;
    const response = await apiClient.get("/data/multi-table/auto-detect", {
      params,
    });
    return response.data;
  } catch (error: any) {
    return {
      success: false,
      message: error.response?.data?.message || error.message,
    };
  }
 }
 /**
 * 다중 테이블 엑셀 업로드 실행
 */
 export async function uploadMultiTableExcel(params: {
  config: TableChainConfig;
  modeId: string;
  rows: Record<string, any>[];
 }): Promise<{ success: boolean; data?: MultiTableUploadResult; message?: string }> {
  try {
    const response = await apiClient.post("/data/multi-table/upload", params);
    return response.data;
  } catch (error: any) {
    return {
      success: false,
      message: error.response?.data?.message || error.message,
    };
  }
 }
--- a/frontend/lib/registry/components/v2-split-panel-layout/SplitPanelLayoutComponent.tsx
+++ b/frontend/lib/registry/components/v2-split-panel-layout/SplitPanelLayoutComponent.tsx
@ -1235,7 +1235,6 @@ export const SplitPanelLayoutComponent: React.FC<SplitPanelLayoutComponentProps>
      if (!leftItem) return;
      setIsLoadingRight(true);
      setRightData([]);
      try {
        // detail / join 모두 동일한 필터링 로직 사용
        // (차이점: 초기 로드 여부만 다름 - detail은 초기 로드 안 함)
@ -1344,12 +1343,34 @@ export const SplitPanelLayoutComponent: React.FC<SplitPanelLayoutComponentProps>
              enableEntityJoin: true,
              size: 1000,
              companyCodeOverride: companyCode,
-              additionalJoinColumns: rightJoinColumns,
+              additionalJoinColumns: rightJoinColumns, // 🆕 Entity 조인 컬럼 전달
            });
            console.log("🔗 [분할패널] 복합키 조회 결과:", result);
-            setRightData(result.data || []);
+            // 추가 dataFilter 적용
            let filteredData = result.data || [];
            const dataFilter = componentConfig.rightPanel?.dataFilter;
            if (dataFilter?.enabled && dataFilter.conditions?.length > 0) {
              filteredData = filteredData.filter((item: any) => {
                return dataFilter.conditions.every((cond: any) => {
                  const value = item[cond.column];
                  const condValue = cond.value;
                  switch (cond.operator) {
                    case "equals":
                      return value === condValue;
                    case "notEquals":
                      return value !== condValue;
                    case "contains":
                      return String(value).includes(String(condValue));
                    default:
                      return true;
                  }
                });
              });
            }
            setRightData(filteredData);
          } else {
            // 단일키 (하위 호환성) → entityJoinApi 사용으로 전환 (entity 조인 컬럼 지원)
            const leftColumn = componentConfig.rightPanel?.relation?.leftColumn;
@ -1359,11 +1380,9 @@ export const SplitPanelLayoutComponent: React.FC<SplitPanelLayoutComponentProps>
              const leftValue = leftItem[leftColumn];
              const { entityJoinApi } = await import("@/lib/api/entityJoin");
-              console.log("🔗 [분할패널] 단일키 조건:", { leftColumn, rightColumn, leftValue, rightTableName });
+              // 단일키를 복합키 형식으로 변환
              // 단일키를 복합키 형식으로 변환 (entity 컬럼이므로 equals 연산자 필수)
              const searchConditions: Record<string, any> = {};
-              searchConditions[rightColumn] = { value: leftValue, operator: "equals" };
+              searchConditions[rightColumn] = leftValue;
              // Entity 조인 컬럼 추출
              const rightJoinColumnsLegacy = extractAdditionalJoinColumns(
@ -1382,13 +1401,35 @@ export const SplitPanelLayoutComponent: React.FC<SplitPanelLayoutComponentProps>
                additionalJoinColumns: rightJoinColumnsLegacy,
              });
-              setRightData(result.data || []);
+              let filteredDataLegacy = result.data || [];
              // 데이터 필터 적용
              const dataFilterLegacy = componentConfig.rightPanel?.dataFilter;
              if (dataFilterLegacy?.enabled && dataFilterLegacy.conditions?.length > 0) {
                filteredDataLegacy = filteredDataLegacy.filter((item: any) => {
                  return dataFilterLegacy.conditions.every((cond: any) => {
                    const value = item[cond.column];
                    const condValue = cond.value;
                    switch (cond.operator) {
                      case "equals":
                        return value === condValue;
                      case "notEquals":
                        return value !== condValue;
                      case "contains":
                        return String(value).includes(String(condValue));
                      default:
                        return true;
                    }
                  });
                });
              }
              setRightData(filteredDataLegacy || []);
            }
          }
        }
      } catch (error) {
        console.error("우측 데이터 로드 실패:", error);
        setRightData([]);
        toast({
          title: "데이터 로드 실패",
          description: "우측 패널 데이터를 불러올 수 없습니다.",
--- a/frontend/lib/utils/buttonActions.ts
+++ b/frontend/lib/utils/buttonActions.ts
@ -49,7 +49,6 @@ export type ButtonActionType =
  | "view_table_history" // 테이블 이력 보기
  | "excel_download" // 엑셀 다운로드
  | "excel_upload" // 엑셀 업로드
  | "multi_table_excel_upload" // 다중 테이블 엑셀 업로드
  | "barcode_scan" // 바코드 스캔
  | "code_merge" // 코드 병합
  // | "empty_vehicle" // 공차등록 (위치 수집 + 상태 변경) - 운행알림으로 통합
@ -429,9 +428,6 @@ export class ButtonActionExecutor {
        case "excel_upload":
          return await this.handleExcelUpload(config, context);
        case "multi_table_excel_upload":
          return await this.handleMultiTableExcelUpload(config, context);
        case "barcode_scan":
          return await this.handleBarcodeScan(config, context);
@ -5608,69 +5604,6 @@ export class ButtonActionExecutor {
    }
  }
  /**
   * 다중 테이블 엑셀 업로드 액션 처리
   */
  private static async handleMultiTableExcelUpload(config: ButtonActionConfig, context: ButtonActionContext): Promise<boolean> {
    try {
      const rootTable = context.tableName;
      if (!rootTable) {
        toast.error("화면에 테이블이 설정되지 않았습니다. 화면 설정을 확인하세요.");
        return false;
      }
      toast.loading("테이블 구조를 분석하고 있습니다...", { id: "multi-table-detect" });
      const { autoDetectMultiTableConfig } = await import("@/lib/api/multiTableExcel");
      const result = await autoDetectMultiTableConfig(rootTable, context.screenId);
      toast.dismiss("multi-table-detect");
      if (!result.success || !result.data) {
        toast.error(result.message || `테이블 구조를 분석할 수 없습니다: ${rootTable}`);
        return false;
      }
      const chainConfig = result.data;
      const { MultiTableExcelUploadModal } = await import("@/components/common/MultiTableExcelUploadModal");
      const { createRoot } = await import("react-dom/client");
      const modalContainer = document.createElement("div");
      document.body.appendChild(modalContainer);
      const root = createRoot(modalContainer);
      const closeModal = () => {
        root.unmount();
        document.body.removeChild(modalContainer);
      };
      root.render(
        React.createElement(MultiTableExcelUploadModal, {
          open: true,
          onOpenChange: (open: boolean) => {
            if (!open) closeModal();
          },
          config: chainConfig,
          onSuccess: () => {
            context.onRefresh?.();
          },
        }),
      );
      return true;
    } catch (error) {
      toast.dismiss("multi-table-detect");
      console.error("다중 테이블 엑셀 업로드 모달 열기 실패:", error);
      showErrorToast(config.errorMessage || "다중 테이블 엑셀 업로드 화면을 열 수 없습니다", error, {
        guidance: "잠시 후 다시 시도해 주세요.",
      });
      return false;
    }
  }
  /**
   * 바코드 스캔 액션 처리
   */
@ -7767,11 +7700,6 @@ export const DEFAULT_BUTTON_ACTIONS: Record<ButtonActionType, Partial<ButtonActi
    successMessage: "엑셀 파일이 업로드되었습니다.",
    errorMessage: "엑셀 업로드 중 오류가 발생했습니다.",
  },
  multi_table_excel_upload: {
    type: "multi_table_excel_upload",
    successMessage: "다중 테이블 엑셀 업로드가 완료되었습니다.",
    errorMessage: "다중 테이블 엑셀 업로드 중 오류가 발생했습니다.",
  },
  barcode_scan: {
    type: "barcode_scan",
    barcodeFormat: "all",
--- a/frontend/lib/utils/excelExport.ts
+++ b/frontend/lib/utils/excelExport.ts
@ -104,8 +104,8 @@ export async function importFromExcel(
          return;
        }
-        // 워크북 읽기 (cellDates: 엑셀 시리얼 날짜를 JS Date 객체로 변환)
+        // 워크북 읽기
-        const workbook = XLSX.read(data, { type: "binary", cellDates: true });
+        const workbook = XLSX.read(data, { type: "binary" });
        // 시트 선택 (지정된 시트 또는 첫 번째 시트)
        const targetSheetName = sheetName || workbook.SheetNames[0];
@ -118,31 +118,15 @@ export async function importFromExcel(
        // JSON으로 변환 (빈 셀도 포함하여 모든 컬럼 키 유지)
        const jsonData = XLSX.utils.sheet_to_json(worksheet, {
-          defval: "",
+          defval: "", // 빈 셀에 빈 문자열 할당
        });
        // Date 객체를 yyyy-mm-dd 문자열로 변환
        const processedData = (jsonData as Record<string, any>[]).map((row) => {
          const newRow: Record<string, any> = {};
          for (const [key, value] of Object.entries(row)) {
            if (value instanceof Date && !isNaN(value.getTime())) {
              const y = value.getUTCFullYear();
              const m = String(value.getUTCMonth() + 1).padStart(2, "0");
              const d = String(value.getUTCDate()).padStart(2, "0");
              newRow[key] = `${y}-${m}-${d}`;
            } else {
              newRow[key] = value;
            }
          }
          return newRow;
        });
        console.log("✅ 엑셀 가져오기 완료:", {
          sheetName: targetSheetName,
-          rowCount: processedData.length,
+          rowCount: jsonData.length,
        });
-        resolve(processedData);
+        resolve(jsonData as Record<string, any>[]);
      } catch (error) {
        console.error("❌ 엑셀 가져오기 실패:", error);
        reject(error);
--- a/frontend/next.config.mjs
+++ b/frontend/next.config.mjs
@ -20,9 +20,11 @@ const nextConfig = {
  },
  // API 프록시 설정 - 백엔드로 요청 전달
-  // Docker: SERVER_API_URL 사용. 로컬: 127.0.0.1 사용 (localhost는 IPv6 ::1 로 해석되어 ECONNREFUSED 나는 경우 있음)
+  // Docker 환경: 컨테이너 이름(pms-backend-mac) 또는 SERVER_API_URL 사용
  // 로컬 개발: http://127.0.0.1:8080 사용
  async rewrites() {
-    const backendUrl = process.env.SERVER_API_URL || "http://127.0.0.1:8080";
+    // Docker 컨테이너 내부에서는 컨테이너 이름으로 통신
    const backendUrl = process.env.SERVER_API_URL || "http://localhost:8080";
    return [
      {
        source: "/api/:path*",