sam-docs/dev/dev_plans/archive/mng-item-formula-integration-plan.md

MNG 품목관리 - 견적수식 엔진(FormulaEvaluatorService) 연동 계획

작성일: 2026-02-19 목적: 가변사이즈 완제품(FG) 선택 시 오픈사이즈(W,H) 입력 → FormulaEvaluatorService로 동적 자재 산출 → 중앙 패널에 트리 표시 기준 문서: docs/dev_plans/mng-item-management-plan.md, api/app/Services/Quote/FormulaEvaluatorService.php 선행 작업: 3-Panel 품목관리 페이지 구현 완료 (Phase 1~2 of mng-item-management-plan.md) 상태: 🔄 진행중

---

📍 현재 진행 상태

항목	내용
마지막 완료 작업	Phase 2.5: 로딩/에러 상태 처리 (전체 구현 완료)
다음 작업	검증 (브라우저 테스트)
진행률	8/8 (100%)
마지막 업데이트	2026-02-19

---

1. 개요

1.1 배경

MNG 품목관리 페이지(mng.sam.kr/item-management)에서 완제품(FG) FG-KQTS01-벽면형-SUS를 선택하면 items.bom JSON에 등록된 정적 BOM(PT 2개: 가이드레일, 하단마감재)만 표시된다. 그러나 견적관리(dev.sam.kr/sales/quote-management/46)에서는 FormulaEvaluatorService가 W=3000, H=3000 입력으로 17종 51개의 자재를 동적 산출한다.

핵심 문제: items.bom(정적)과 FormulaEvaluatorService(동적) 두 시스템이 분리되어 있어, 품목관리 페이지에서 실제 필요 자재를 볼 수 없다.

해결: 가변사이즈 품목(item_details.is_variable_size = true) 선택 시 오픈사이즈(W, H) 입력 UI를 제공하고, API의 기존 엔드포인트(POST /api/v1/quotes/calculate/bom)를 MNG에서 HTTP로 호출하여 산출 결과를 중앙 패널에 표시한다.

1.2 기준 원칙

┌─────────────────────────────────────────────────────────────────┐
│  🎯 핵심 원칙                                                    │
├─────────────────────────────────────────────────────────────────┤
│  - MNG에서 마이그레이션 파일 생성 금지 (API에서만)               │
│  - MNG ↔ API 통신은 HTTP API 호출 (코드 공유/직접 서비스 호출 X) │
│  - 기존 API 엔드포인트 재사용 (POST /api/v1/quotes/calculate/bom)│
│  - Docker nginx 내부 라우팅 + SSL 우회 패턴 사용                 │
│  - Blade + HTMX + Tailwind + Vanilla JS (Alpine.js 미사용)      │
│  - 정적 BOM과 수식 산출 결과를 탭으로 전환 가능하게              │
│  - Controller에서 직접 DB 쿼리 금지 (Service-First)              │
│  - Controller에서 직접 validate() 금지 (FormRequest 필수)        │
└─────────────────────────────────────────────────────────────────┘

1.3 변경 승인 정책

분류	예시	승인
✅ 즉시 가능	서비스 생성, 컨트롤러 메서드 추가, Blade 수정, JS 추가	불필요
⚠️ 컨펌 필요	API 라우트 추가, 기존 Blade 구조 변경	필수
🔴 금지	mng에서 마이그레이션 생성, API 소스 수정	별도 협의

1.4 MNG 절대 금지 규칙

❌ mng/database/migrations/ 에 파일 생성 금지
❌ docker exec sam-mng-1 php artisan migrate 실행 금지
❌ php artisan db:seed --class=*MenuSeeder 실행 금지
❌ Controller에서 직접 DB 쿼리 금지 (Service-First)
❌ Controller에서 직접 validate() 금지 (FormRequest 필수)
❌ api/ 프로젝트 소스 코드 수정 금지

---

2. 대상 범위

2.1 Phase 1: MNG 백엔드 (HTTP API 호출 서비스)

#	작업 항목	상태	비고
1.1	FormulaApiService 생성 (MNG→API HTTP 호출 래퍼)	✅	신규 파일
1.2	ItemManagementApiController에 calculateFormula 메서드 추가	✅	기존 파일 수정
1.3	API 라우트 추가 (POST /api/admin/items/{id}/calculate-formula)	✅	기존 파일 수정

2.2 Phase 2: MNG 프론트엔드 (UI 연동)

#	작업 항목	상태	비고
2.1	중앙 패널 헤더에 탭 UI 추가 (정적 BOM / 수식 산출)	✅	index.blade.php 수정
2.2	오픈사이즈 입력 폼 (W, H, 수량) + 산출 버튼	✅	index.blade.php 수정
2.3	수식 산출 결과 트리 렌더링 (카테고리 그룹별)	✅	JS 추가
2.4	가변사이즈 품목 감지 → 자동 탭 전환	✅	item-detail.blade.php + JS 수정
2.5	로딩/에러 상태 처리	✅	JS 추가

---

3. 이미 구현된 코드 (선행 작업 - 수정 대상)

새 세션에서 현재 코드 상태를 파악할 수 있도록 이미 존재하는 파일 전체 목록과 핵심 구조를 기록.

3.1 파일 구조 (이미 존재)

mng/
├── app/
│   ├── Http/Controllers/
│   │   ├── ItemManagementController.php              # Web (HX-Redirect 패턴)
│   │   └── Api/Admin/
│   │       └── ItemManagementApiController.php       # API (index, bomTree, detail)
│   ├── Models/
│   │   ├── Items/
│   │   │   ├── Item.php                              # BelongsToTenant, 관계, 스코프, 상수
│   │   │   └── ItemDetail.php                        # 1:1 확장 (is_variable_size 필드 포함)
│   │   └── Commons/
│   │       └── File.php                              # 파일 모델
│   ├── Services/
│   │   └── ItemManagementService.php                 # getItemList, getBomTree, getItemDetail
│   └── Traits/
│       └── BelongsToTenant.php                       # 테넌트 격리 Trait
├── resources/views/item-management/
│   ├── index.blade.php                               # 3-Panel 메인 (★ 수정 대상)
│   └── partials/
│       ├── item-list.blade.php                       # 좌측 패널 (변경 없음)
│       ├── bom-tree.blade.php                        # 중앙 패널 초기 상태 (변경 없음)
│       └── item-detail.blade.php                     # 우측 패널 (★ 수정 대상)
├── routes/
│   ├── web.php                                       # Route: GET /item-management (변경 없음)
│   └── api.php                                       # Route: items group (★ 수정 대상 - 라우트 추가)
└── config/
    └── api-explorer.php                              # FLOW_TESTER_API_KEY 설정 참조

3.2 현재 ItemManagementApiController 전체 (수정 대상)

<?php
namespace App\Http\Controllers\Api\Admin;

use App\Http\Controllers\Controller;
use App\Services\ItemManagementService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;

class ItemManagementApiController extends Controller
{
    public function __construct(
        private readonly ItemManagementService $service
    ) {}

    public function index(Request $request): View
    {
        $items = $this->service->getItemList([
            'search' => $request->input('search'),
            'item_type' => $request->input('item_type'),
            'per_page' => $request->input('per_page', 50),
        ]);
        return view('item-management.partials.item-list', compact('items'));
    }

    public function bomTree(int $id, Request $request): JsonResponse
    {
        $maxDepth = $request->input('max_depth', 10);
        $tree = $this->service->getBomTree($id, $maxDepth);
        return response()->json($tree);
    }

    public function detail(int $id): View
    {
        $data = $this->service->getItemDetail($id);
        return view('item-management.partials.item-detail', [
            'item' => $data['item'],
            'bomChildren' => $data['bom_children'],
        ]);
    }
}

3.3 현재 API 라우트 (items 그룹, mng/routes/api.php:866~)

Route::middleware(['web', 'auth', 'hq.member'])->prefix('admin/items')->name('api.admin.items.')->group(function () {
    Route::get('/search', [ItemApiController::class, 'search'])->name('search');

    // 품목관리 페이지 API
    Route::get('/', [ItemManagementApiController::class, 'index'])->name('index');
    Route::get('/{id}/bom-tree', [ItemManagementApiController::class, 'bomTree'])->name('bom-tree');
    Route::get('/{id}/detail', [ItemManagementApiController::class, 'detail'])->name('detail');
    // ★ 여기에 calculate-formula 라우트 추가 예정
});

3.4 현재 index.blade.php 중앙 패널 (수정 대상 부분)

<!-- 현재 중앙 패널 -->
<div class="flex-1 bg-white rounded-lg shadow-sm flex flex-col overflow-hidden">
    <div class="px-4 py-3 border-b border-gray-200">
        <h2 class="text-sm font-semibold text-gray-700">BOM 구성 (재귀 트리)</h2>
    </div>
    <div id="bom-tree-container" class="flex-1 overflow-y-auto p-4">
        <p class="text-gray-400 text-center py-10">좌측에서 품목을 선택하세요.</p>
    </div>
</div>

3.5 현재 JS 구조 (index.blade.php @push('scripts'))

핵심 함수:

• loadItemList() - 좌측 품목 리스트 HTMX 로드
• selectItem(itemId, updateTree) - 품목 선택 (좌측 하이라이트 + 중앙 트리 fetch + 우측 상세 HTMX)
• selectTreeNode(itemId) - 중앙 트리 노드 클릭 (우측만 갱신, 트리 유지)
• renderBomTree(node, container) - BOM 트리 재귀 렌더링
• getTypeBadgeClass(type) - 유형별 뱃지 CSS 클래스

3.6 테넌트 필터링 패턴 (중요)

MNG의 HQ 관리자는 헤더에서 테넌트를 선택하며, session('selected_tenant_id')에 저장된다. 그러나 BelongsToTenant의 TenantScope는 request->attributes, X-TENANT-ID 헤더, auth user에서 tenant_id를 읽으므로 세션 값과 불일치할 수 있다.

따라서 Service에서는 Item::withoutGlobalScopes()->where('tenant_id', session('selected_tenant_id')) 패턴을 사용한다.

// ✅ 올바른 패턴 (현재 ItemManagementService에서 사용 중)
Item::withoutGlobalScopes()
    ->where('tenant_id', session('selected_tenant_id'))
    ->findOrFail($id);

// ❌ 잘못된 패턴 (HQ 관리자 세션과 불일치)
Item::findOrFail($id);  // TenantScope가 auth user의 tenant_id 사용

---

4. 상세 작업 내용

4.1 Phase 1: MNG 백엔드

1.1 FormulaApiService 생성

파일 경로: mng/app/Services/FormulaApiService.php (신규 생성)

역할: MNG에서 API 프로젝트의 POST /api/v1/quotes/calculate/bom 엔드포인트를 HTTP로 호출하는 래퍼

호출 대상 API 엔드포인트 상세:

POST /api/v1/quotes/calculate/bom
라우트 정의: api/routes/api/v1/sales.php:64
미들웨어: 글로벌(ApiKeyMiddleware, CorsMiddleware, ApiRateLimiter)
FormRequest: QuoteBomCalculateRequest (authorize = true, 제한 없음)

API 인증 요구사항 (확인 완료):

헤더	필수	설명
X-API-KEY	✅ 필수	api_keys 테이블에 is_active=true로 등록된 키
Authorization: Bearer {token}	❌ 선택	Sanctum 토큰, 있으면 tenant_id 자동 설정
X-TENANT-ID	❌ 선택	테넌트 식별 (Bearer 없을 때 대안)

API Key 취득 방법: env('FLOW_TESTER_API_KEY') (mng/.env에 설정됨, config/api-explorer.php:26에서 참조)

요청 페이로드:

{
    "finished_goods_code": "FG-KQTS01",
    "variables": {
        "W0": 3000,
        "H0": 3000,
        "QTY": 1
    },
    "tenant_id": 287
}

응답 구조 (FormulaEvaluatorService::calculateBomWithDebug 반환값):

{
    "success": true,
    "finished_goods": { "code": "FG-KQTS01", "name": "벽면형-SUS", "id": 123 },
    "variables": { "W0": 3000, "H0": 3000, "QTY": 1 },
    "items": [
        {
            "item_code": "PT-강재-C형강",
            "item_name": "C형강 65×32×10t",
            "specification": "65×32×10t",
            "unit": "mm",
            "quantity": 6038,
            "unit_price": 1.0,
            "total_price": 6038,
            "category_group": "steel"
        }
    ],
    "grouped_items": {
        "steel": [ ... ],
        "part": [ ... ],
        "motor": [ ... ]
    },
    "subtotals": { "steel": 123456, "part": 78900, "motor": 50000 },
    "grand_total": 252356,
    "debug_steps": [ ... ]
}

구현 코드:

<?php
namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class FormulaApiService
{
    /**
     * API 서버의 FormulaEvaluatorService를 HTTP로 호출하여 BOM 산출
     *
     * Docker 내부 통신 패턴:
     * - URL: https://nginx/api/v1/quotes/calculate/bom (Docker nginx 컨테이너)
     * - Host 헤더: api.sam.kr (nginx가 올바른 서버 블록으로 라우팅)
     * - SSL 우회: withoutVerifying() (내부 자체 서명 인증서)
     * - 인증: X-API-KEY 헤더 (FLOW_TESTER_API_KEY 환경변수)
     */
    public function calculateBom(string $finishedGoodsCode, array $variables, int $tenantId): array
    {
        try {
            $apiKey = config('api-explorer.default_environments.0.api_key')
                   ?: env('FLOW_TESTER_API_KEY', '');

            $response = Http::timeout(30)
                ->withoutVerifying()
                ->withHeaders([
                    'Host' => 'api.sam.kr',
                    'Accept' => 'application/json',
                    'Content-Type' => 'application/json',
                    'X-API-KEY' => $apiKey,
                    'X-TENANT-ID' => (string) $tenantId,
                ])
                ->post('https://nginx/api/v1/quotes/calculate/bom', [
                    'finished_goods_code' => $finishedGoodsCode,
                    'variables' => $variables,
                    'tenant_id' => $tenantId,
                ]);

            if ($response->successful()) {
                $json = $response->json();
                // ApiResponse::handle()는 {success, message, data} 구조로 래핑
                return $json['data'] ?? $json;
            }

            Log::warning('FormulaApiService: API 호출 실패', [
                'status' => $response->status(),
                'body' => $response->body(),
                'code' => $finishedGoodsCode,
            ]);

            return [
                'success' => false,
                'error' => 'API 응답 오류: HTTP ' . $response->status(),
            ];
        } catch (\Exception $e) {
            Log::error('FormulaApiService: 예외 발생', [
                'message' => $e->getMessage(),
                'code' => $finishedGoodsCode,
            ]);

            return [
                'success' => false,
                'error' => '수식 계산 서버 연결 실패: ' . $e->getMessage(),
            ];
        }
    }
}

트러블슈팅 가이드:

• 401 Unauthorized → API Key 확인: docker exec sam-mng-1 php artisan tinker --execute="echo env('FLOW_TESTER_API_KEY');"
• Connection refused → nginx 컨테이너 확인: docker ps | grep nginx
• SSL certificate problem → withoutVerifying() 누락 확인
• 422 Validation → finished_goods_code가 items 테이블에 존재하는지 확인

1.2 ItemManagementApiController::calculateFormula 추가

파일: mng/app/Http/Controllers/Api/Admin/ItemManagementApiController.php

변경: 기존 컨트롤러에 메서드 1개 추가 + use 문 추가

// 파일 상단 use 추가
use App\Services\FormulaApiService;

// 기존 메서드 아래에 추가
/**
 * 수식 기반 BOM 산출 (API 서버의 FormulaEvaluatorService HTTP 호출)
 */
public function calculateFormula(Request $request, int $id): JsonResponse
{
    $item = \App\Models\Items\Item::withoutGlobalScopes()
        ->where('tenant_id', session('selected_tenant_id'))
        ->findOrFail($id);

    $width = (int) $request->input('width', 1000);
    $height = (int) $request->input('height', 1000);
    $qty = (int) $request->input('qty', 1);

    $variables = [
        'W0' => $width,
        'H0' => $height,
        'QTY' => $qty,
    ];

    $formulaService = new FormulaApiService();
    $result = $formulaService->calculateBom(
        $item->code,
        $variables,
        (int) session('selected_tenant_id')
    );

    return response()->json($result);
}

1.3 API 라우트 추가

파일: mng/routes/api.php (라인 866~ 기존 items 그룹 내)

추가 위치: 기존 detail 라우트 아래

// 기존 라우트 아래에 추가
Route::post('/{id}/calculate-formula', [ItemManagementApiController::class, 'calculateFormula'])->name('calculate-formula');

---

4.2 Phase 2: MNG 프론트엔드

2.1 중앙 패널 탭 UI

수정 파일: mng/resources/views/item-management/index.blade.php

변경 대상 (현재 HTML):

<div class="px-4 py-3 border-b border-gray-200">
    <h2 class="text-sm font-semibold text-gray-700">BOM 구성 (재귀 트리)</h2>
</div>
<div id="bom-tree-container" class="flex-1 overflow-y-auto p-4">

변경 후:

<div class="px-4 py-3 border-b border-gray-200">
    <div class="flex items-center gap-1">
        <button type="button" id="tab-static-bom"
                class="bom-tab px-3 py-1.5 text-xs font-medium rounded-md bg-blue-100 text-blue-800"
                onclick="switchBomTab('static')">
            정적 BOM
        </button>
        <button type="button" id="tab-formula-bom"
                class="bom-tab px-3 py-1.5 text-xs font-medium rounded-md bg-gray-100 text-gray-600 hover:bg-gray-200"
                onclick="switchBomTab('formula')"
                style="display:none;">
            수식 산출
        </button>
    </div>
</div>

<!-- 수식 산출 입력 폼 (가변사이즈 품목 선택 시에만 표시) -->
<div id="formula-input-panel" style="display:none;" class="p-4 bg-gray-50 border-b border-gray-200">
    <div class="flex items-end gap-3">
        <div>
            <label class="block text-xs text-gray-500 mb-1">폭 W (mm)</label>
            <input type="number" id="input-width" value="1000" min="100" max="10000" step="1"
                   class="w-24 px-2 py-1.5 text-sm border border-gray-300 rounded focus:ring-2 focus:ring-blue-500 focus:outline-none">
        </div>
        <div>
            <label class="block text-xs text-gray-500 mb-1">높이 H (mm)</label>
            <input type="number" id="input-height" value="1000" min="100" max="10000" step="1"
                   class="w-24 px-2 py-1.5 text-sm border border-gray-300 rounded focus:ring-2 focus:ring-blue-500 focus:outline-none">
        </div>
        <div>
            <label class="block text-xs text-gray-500 mb-1">수량</label>
            <input type="number" id="input-qty" value="1" min="1" max="100" step="1"
                   class="w-16 px-2 py-1.5 text-sm border border-gray-300 rounded focus:ring-2 focus:ring-blue-500 focus:outline-none">
        </div>
        <button type="button" id="btn-calculate" onclick="calculateFormula()"
                class="px-4 py-1.5 text-sm font-medium text-white bg-blue-600 rounded hover:bg-blue-700 transition-colors">
            산출
        </button>
    </div>
</div>

<!-- 정적 BOM 영역 -->
<div id="bom-tree-container" class="flex-1 overflow-y-auto p-4">
    <p class="text-gray-400 text-center py-10">좌측에서 품목을 선택하세요.</p>
</div>

<!-- 수식 산출 결과 영역 (초기 숨김) -->
<div id="formula-result-container" class="flex-1 overflow-y-auto p-4" style="display:none;">
    <p class="text-gray-400 text-center py-10">오픈사이즈를 입력하고 산출 버튼을 클릭하세요.</p>
</div>

2.2 item-detail.blade.php에 메타 데이터 추가

수정 파일: mng/resources/views/item-management/partials/item-detail.blade.php

파일 맨 위에 추가 (기존 <div class="space-y-4"> 앞):

<!-- 품목 메타 데이터 (JS에서 가변사이즈 감지용) -->
<div id="item-meta-data"
     data-item-id="{{ $item->id }}"
     data-item-code="{{ $item->code }}"
     data-is-variable-size="{{ $item->details?->is_variable_size ? 'true' : 'false' }}"
     style="display:none;"></div>

2.3 JS 추가 (index.blade.php @push('scripts'))

기존 IIFE 내부에 추가할 변수와 함수:

// ── 추가 변수 ──
let currentBomTab = 'static';  // 'static' | 'formula'
let currentItemId = null;
let currentItemCode = null;

// ── 탭 전환 ──
window.switchBomTab = function(tab) {
    currentBomTab = tab;

    // 탭 버튼 스타일
    document.querySelectorAll('.bom-tab').forEach(btn => {
        btn.classList.remove('bg-blue-100', 'text-blue-800');
        btn.classList.add('bg-gray-100', 'text-gray-600');
    });
    const activeBtn = document.getElementById(tab === 'static' ? 'tab-static-bom' : 'tab-formula-bom');
    if (activeBtn) {
        activeBtn.classList.remove('bg-gray-100', 'text-gray-600');
        activeBtn.classList.add('bg-blue-100', 'text-blue-800');
    }

    // 콘텐츠 영역 전환
    document.getElementById('bom-tree-container').style.display = (tab === 'static') ? '' : 'none';
    document.getElementById('formula-input-panel').style.display = (tab === 'formula') ? '' : 'none';
    document.getElementById('formula-result-container').style.display = (tab === 'formula') ? '' : 'none';
};

// ── 가변사이즈 탭 표시/숨김 ──
function showFormulaTab() {
    document.getElementById('tab-formula-bom').style.display = '';
    switchBomTab('formula');  // 자동으로 수식 산출 탭으로 전환
}

function hideFormulaTab() {
    document.getElementById('tab-formula-bom').style.display = 'none';
    document.getElementById('formula-input-panel').style.display = 'none';
    document.getElementById('formula-result-container').style.display = 'none';
    switchBomTab('static');
}

// ── 상세 로드 완료 후 가변사이즈 감지 ──
document.body.addEventListener('htmx:afterSwap', function(event) {
    if (event.detail.target.id === 'item-detail') {
        const meta = document.getElementById('item-meta-data');
        if (meta) {
            currentItemId = meta.dataset.itemId;
            currentItemCode = meta.dataset.itemCode;
            if (meta.dataset.isVariableSize === 'true') {
                showFormulaTab();
            } else {
                hideFormulaTab();
            }
        }
    }
});

// ── 수식 산출 API 호출 ──
window.calculateFormula = function() {
    if (!currentItemId) return;

    const width = parseInt(document.getElementById('input-width').value) || 1000;
    const height = parseInt(document.getElementById('input-height').value) || 1000;
    const qty = parseInt(document.getElementById('input-qty').value) || 1;

    // 입력값 범위 검증
    if (width < 100 || width > 10000 || height < 100 || height > 10000) {
        alert('폭과 높이는 100~10000 범위로 입력하세요.');
        return;
    }

    const container = document.getElementById('formula-result-container');
    container.innerHTML = '<div class="flex justify-center py-10"><div class="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600"></div></div>';

    fetch(`/api/admin/items/${currentItemId}/calculate-formula`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-CSRF-TOKEN': csrfToken,
        },
        body: JSON.stringify({ width, height, qty }),
    })
    .then(res => res.json())
    .then(data => {
        if (data.success === false) {
            container.innerHTML = `
                <div class="text-center py-10">
                    <p class="text-red-500 text-sm mb-2">${data.error || '산출 실패'}</p>
                    <button onclick="calculateFormula()" class="text-blue-600 text-sm hover:underline">다시 시도</button>
                </div>`;
            return;
        }
        renderFormulaTree(data, container);
    })
    .catch(err => {
        container.innerHTML = `
            <div class="text-center py-10">
                <p class="text-red-500 text-sm mb-2">서버 연결 실패</p>
                <button onclick="calculateFormula()" class="text-blue-600 text-sm hover:underline">다시 시도</button>
            </div>`;
    });
};

// ── 수식 산출 결과 트리 렌더링 ──
function renderFormulaTree(data, container) {
    container.innerHTML = '';

    // 카테고리 그룹 한글 매핑
    const groupLabels = { steel: '강재', part: '부품', motor: '모터/컨트롤러' };
    const groupIcons = { steel: '🏗️', part: '🔧', motor: '⚡' };
    const groupedItems = data.grouped_items || {};

    // 합계 영역
    if (data.grand_total) {
        const totalDiv = document.createElement('div');
        totalDiv.className = 'mb-4 p-3 bg-blue-50 rounded-lg flex justify-between items-center';
        totalDiv.innerHTML = `
            <span class="text-sm font-medium text-blue-800">
                ${data.finished_goods?.name || ''} (${data.finished_goods?.code || ''})
                <span class="text-xs text-blue-600 ml-2">W:${data.variables?.W0} H:${data.variables?.H0}</span>
            </span>
            <span class="text-sm font-bold text-blue-900">합계: ${Number(data.grand_total).toLocaleString()}원</span>
        `;
        container.appendChild(totalDiv);
    }

    // 카테고리 그룹별 렌더링
    Object.entries(groupedItems).forEach(([group, items]) => {
        if (!items || items.length === 0) return;

        const groupDiv = document.createElement('div');
        groupDiv.className = 'mb-3';

        const subtotal = data.subtotals?.[group] || 0;

        // 그룹 헤더
        const header = document.createElement('div');
        header.className = 'flex items-center gap-2 py-2 px-3 bg-gray-50 rounded-t-lg cursor-pointer';
        header.innerHTML = `
            <span class="text-xs text-gray-400">▼</span>
            <span>${groupIcons[group] || '📦'}</span>
            <span class="text-sm font-semibold text-gray-700">${groupLabels[group] || group}</span>
            <span class="text-xs text-gray-500">(${items.length}건)</span>
            <span class="ml-auto text-xs font-medium text-gray-600">소계: ${Number(subtotal).toLocaleString()}원</span>
        `;

        const listDiv = document.createElement('div');
        listDiv.className = 'border border-gray-100 rounded-b-lg divide-y divide-gray-50';

        // 그룹 접기/펼치기
        header.onclick = function() {
            const toggle = header.querySelector('.text-gray-400');
            if (listDiv.style.display === 'none') {
                listDiv.style.display = '';
                toggle.textContent = '▼';
            } else {
                listDiv.style.display = 'none';
                toggle.textContent = '▶';
            }
        };

        // 아이템 목록
        items.forEach(item => {
            const row = document.createElement('div');
            row.className = 'flex items-center gap-2 py-1.5 px-3 hover:bg-gray-50 cursor-pointer text-sm';
            row.innerHTML = `
                <span class="inline-flex items-center px-1.5 py-0.5 rounded text-xs font-medium bg-green-100 text-green-800">PT</span>
                <span class="font-mono text-xs text-gray-500 w-32 truncate">${item.item_code || ''}</span>
                <span class="text-gray-700 flex-1 truncate">${item.item_name || ''}</span>
                <span class="text-xs text-gray-500 w-16 text-right">${item.quantity || 0} ${item.unit || ''}</span>
                <span class="text-xs text-blue-600 font-medium w-20 text-right">${Number(item.total_price || 0).toLocaleString()}원</span>
            `;
            // 아이템 클릭 시 items 테이블에서 해당 코드로 검색하여 상세 표시
            row.onclick = function() {
                // item_code로 좌측 검색 → 해당 품목 상세 로드
                const searchInput = document.getElementById('item-search');
                searchInput.value = item.item_code;
                loadItemList();
            };
            listDiv.appendChild(row);
        });

        groupDiv.appendChild(header);
        groupDiv.appendChild(listDiv);
        container.appendChild(groupDiv);
    });

    if (Object.keys(groupedItems).length === 0) {
        container.innerHTML = '<p class="text-gray-400 text-center py-10">산출된 자재가 없습니다.</p>';
    }
}

---

5. 컨펌 대기 목록

#	항목	변경 내용	영향 범위	상태
1	API 인증 방식	X-API-KEY 필수 (FLOW_TESTER_API_KEY)	MNG→API 통신	✅ 확인 완료
2	API 라우트 추가	POST /api/admin/items/{id}/calculate-formula	mng/routes/api.php	✅ 즉시 가능

---

6. 변경 이력

날짜	항목	변경 내용	파일	승인
2026-02-19	-	계획 문서 초안 작성	-	-
2026-02-19	-	자기완결성 보강 (기존 코드 현황, API 인증 분석, 트러블슈팅)	-	-
2026-02-19	1.1~1.3	Phase 1 백엔드 구현 완료 (FormulaApiService, Controller, Route)	FormulaApiService.php, ItemManagementApiController.php, api.php	✅
2026-02-19	2.1~2.5	Phase 2 프론트엔드 구현 완료 (탭 UI, 입력 폼, 트리 렌더링, 감지, 에러)	index.blade.php, item-detail.blade.php	✅

---

7. 참고 문서

• 기존 품목관리 계획: docs/dev_plans/mng-item-management-plan.md
• FormulaEvaluatorService: api/app/Services/Quote/FormulaEvaluatorService.php
  • 메서드: calculateBomWithDebug(string $finishedGoodsCode, array $inputVariables, ?int $tenantId): array
  • tenant_id=287 자동 감지 → KyungdongFormulaHandler 라우팅
• KyungdongFormulaHandler: api/app/Services/Quote/Handlers/KyungdongFormulaHandler.php
  • calculateDynamicItems(array $inputs) → steel(10종), part(3종), motor/controller 산출
• API 라우트: api/routes/api/v1/sales.php:64 → QuoteController::calculateBom
• QuoteBomCalculateRequest: api/app/Http/Requests/V1/QuoteBomCalculateRequest.php
  • finished_goods_code (required|string)
  • variables (required|array), variables.W0 (required|numeric), variables.H0 (required|numeric)
  • tenant_id (nullable|integer)
• MNG-API HTTP 패턴: mng/app/Services/FlowTester/HttpClient.php
• API Key 설정: mng/config/api-explorer.php:26 → env('FLOW_TESTER_API_KEY')
• 현재 품목관리 뷰: mng/resources/views/item-management/index.blade.php
• MNG 프로젝트 규칙: mng/CLAUDE.md

---

8. 세션 및 메모리 관리 정책

8.1 세션 시작 시 (Load Strategy)

1. 이 문서 읽기 (docs/dev_plans/mng-item-formula-integration-plan.md)
2. 📍 현재 진행 상태 확인 → 다음 작업 파악
3. 섹션 3 "이미 구현된 코드" 확인 → 수정 대상 파일 파악
4. 필요시 Serena 메모리 로드:
   read_memory("item-formula-state")
   read_memory("item-formula-snapshot")
   read_memory("item-formula-active-symbols")

8.2 작업 중 관리 (Context Defense)

컨텍스트 잔량	Action	내용
30% 이하	Snapshot	write_memory("item-formula-snapshot", "코드변경+논의요약")
20% 이하	Context Purge	write_memory("item-formula-active-symbols", "주요 수정 파일/함수")
10% 이하	Stop & Save	최종 상태 저장 후 세션 교체 권고

---

9. 검증 결과

9.1 테스트 케이스

#	테스트	입력	예상 결과	실제 결과	상태
1	FG 가변사이즈 품목 선택	FG-KQTS01 클릭	수식 산출 탭 자동 표시, 입력 폼 노출		⏳
2	오픈사이즈 입력 후 산출	W:3000, H:3000, QTY:1	17종 자재 트리 (steel/part/motor 그룹별), 소계/합계 표시		⏳
3	비가변사이즈 품목 선택	PT 품목 클릭	수식 산출 탭 숨김, 정적 BOM만 표시		⏳
4	정적 BOM ↔ 수식 산출 탭 전환	탭 클릭	각 탭 콘텐츠 전환, 입력 폼 표시/숨김		⏳
5	산출 결과에서 품목 클릭	트리 노드 클릭	좌측 검색에 품목코드 입력 → 품목 리스트 필터링		⏳
6	API Key 미설정	FLOW_TESTER_API_KEY 없음	에러 메시지 "API 응답 오류: HTTP 401" + 재시도 버튼		⏳
7	입력값 범위 초과	W:0, H:-1	alert 표시, API 호출 안 함		⏳
8	서버 연결 실패	nginx 중지 상태	에러 메시지 "서버 연결 실패" + 재시도 버튼		⏳

9.2 성공 기준 달성 현황

기준	달성	비고
FG 가변사이즈 품목에서 수식 산출 가능	⏳
산출 결과가 견적관리와 동일한 17종 자재 표시	⏳
정적 BOM과 수식 산출 탭 전환 작동	⏳
비가변사이즈 품목은 기존 정적 BOM만 표시	⏳
에러 처리 및 로딩 상태 표시	⏳

---

10. 자기완결성 점검 결과

10.1 체크리스트 검증

#	검증 항목	상태	비고
1	작업 목적이 명확한가?	✅	가변사이즈 FG 품목의 동적 자재 산출 표시
2	성공 기준이 정의되어 있는가?	✅	9.2 성공 기준 5개 항목
3	작업 범위가 구체적인가?	✅	Phase 1 백엔드 3건, Phase 2 프론트 5건
4	의존성이 명시되어 있는가?	✅	API 엔드포인트 인증 분석 완료, Docker 라우팅 패턴
5	참고 파일 경로가 정확한가?	✅	모든 파일 경로 검증 완료
6	단계별 절차가 실행 가능한가?	✅	전체 구현 코드 포함
7	검증 방법이 명시되어 있는가?	✅	9.1 테스트 케이스 8개
8	모호한 표현이 없는가?	✅	구체적 수치/코드로 기술
9	기존 코드 현황이 명시되어 있는가?	✅	섹션 3에 전체 파일 구조 + 핵심 코드 인라인
10	API 인증 방식이 확정되었는가?	✅	X-API-KEY 필수 (FLOW_TESTER_API_KEY)
11	트러블슈팅 가이드가 있는가?	✅	4.1 FormulaApiService 트러블슈팅 섹션

10.2 새 세션 시뮬레이션 테스트

질문	답변 가능	참조 섹션
Q1. 이 작업의 목적은 무엇인가?	✅	1.1 배경
Q2. 어디서부터 시작해야 하는가?	✅	📍 현재 진행 상태 + 4.1 Phase 1
Q3. 어떤 파일을 수정/생성해야 하는가?	✅	3.1 파일 구조 + 2. 대상 범위
Q4. 현재 코드 상태는 어떤가?	✅	3.2~3.6 기존 코드 현황
Q5. API 인증은 어떻게 하는가?	✅	4.1 FormulaApiService (인증 테이블)
Q6. 테넌트 필터링은 어떻게 동작하는가?	✅	3.6 테넌트 필터링 패턴
Q7. 작업 완료 확인 방법은?	✅	9. 검증 결과
Q8. 막혔을 때 참고 문서는?	✅	7. 참고 문서 + 4.1 트러블슈팅

결과: 8/8 통과 → ✅ 자기완결성 확보

---

이 문서는 /sc:plan 스킬로 생성되었습니다. 자기완결성 보강: 2026-02-19