# 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
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~)
```php
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 중앙 패널 (수정 대상 부분)
```html
BOM 구성 (재귀 트리)
좌측에서 품목을 선택하세요.
```
### 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'))` 패턴을 사용한다.**
```php
// ✅ 올바른 패턴 (현재 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`에서 참조)
**요청 페이로드**:
```json
{
"finished_goods_code": "FG-KQTS01",
"variables": {
"W0": 3000,
"H0": 3000,
"QTY": 1
},
"tenant_id": 287
}
```
**응답 구조** (FormulaEvaluatorService::calculateBomWithDebug 반환값):
```json
{
"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
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 문 추가
```php
// 파일 상단 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 라우트 아래
```php
// 기존 라우트 아래에 추가
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)**:
```html
BOM 구성 (재귀 트리)
```
**변경 후**:
```html
좌측에서 품목을 선택하세요.
오픈사이즈를 입력하고 산출 버튼을 클릭하세요.
```
#### 2.2 item-detail.blade.php에 메타 데이터 추가
**수정 파일**: `mng/resources/views/item-management/partials/item-detail.blade.php`
**파일 맨 위에 추가** (기존 `
` 앞):
```html
```
#### 2.3 JS 추가 (index.blade.php @push('scripts'))
**기존 IIFE 내부에 추가할 변수와 함수**:
```javascript
// ── 추가 변수 ──
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 = '