Merge branch 'main' of http://114.203.209.83:3000/SamProject/sam-docs

dev/changes/20260316_stock_production_order.md

@@ -0,0 +1,173 @@
+# 재고생산관리 기능 추가
+
+**날짜:** 2026-03-16
+**작업자:** Claude Code
+
+---
+
+## 변경 개요
+
+수주 없이 재고 목적으로 생산하는 경우를 관리하는 **재고생산관리** 기능을 추가했다.
+기존 `orders` 테이블을 공유하며, `order_type_code = 'STOCK'`으로 일반 수주와 구분한다.
+
+### 설계 원칙
+
+- **내부 오더(Internal Order)** 패턴 — 재고생산도 수주로 취급
+- 기존 테이블/API 재사용 — 별도 테이블/엔드포인트 없음
+- 하류 시스템(작업지시, 생산, 출하, 품질검사) 변경 없이 동작
+
+---
+
+## 수정된 파일
+
+### 커밋 1: `feat: [order] 재고생산관리(STOCK) 타입 추가`
+
+| 파일 | 변경 내용 |
+|------|----------|
+| `app/Models/Orders/Order.php` | `TYPE_STOCK = 'STOCK'` 상수 추가 |
+| `app/Http/Requests/Order/StoreOrderRequest.php` | STOCK validation 허용, `production_reason`/`target_stock_qty` 옵션 추가 |
+| `app/Http/Requests/Order/UpdateOrderRequest.php` | 동일 |
+| `app/Services/OrderService.php` | STK 채번, stats `order_type` 필터, 매출 생성 스킵 |
+| `app/Http/Controllers/Api/V1/OrderController.php` | stats에 `order_type` 파라미터 전달 |
+
+### 커밋 2: `feat: [order] 재고생산 생산지시 자동 처리`
+
+| 파일 | 변경 내용 |
+|------|----------|
+| `app/Services/OrderService.php` | `store()`: STOCK → `site_name='재고생산'` 자동 설정 |
+| `app/Services/OrderService.php` | `createProductionOrder()`: STOCK 분기 추가 (절곡 자동, project_name, scheduled_date) |
+| `lang/ko/error.php` | `bending_process_not_found` 에러 메시지 추가 |
+| `lang/en/error.php` | 동일 (영문) |
+
+---
+
+## 상세 변경 사항
+
+### 1. Order 모델 — 타입 상수
+
+```php
+public const TYPE_ORDER = 'ORDER';       // 수주
+public const TYPE_PURCHASE = 'PURCHASE'; // 발주
+public const TYPE_STOCK = 'STOCK';       // 재고생산 (신규)
+```
+
+### 2. 채번 규칙
+
+| 타입 | 접두사 | 형식 | 예시 |
+|------|--------|------|------|
+| ORDER | `ORD` | `ORD{YYYYMMDD}{NNNN}` | `ORD202603160001` |
+| STOCK | `STK` | `STK{YYYYMMDD}{NNNN}` | `STK202603160001` |
+
+### 3. store() — STOCK 자동 처리
+
+```php
+if ($isStock) {
+    $data['site_name'] = '재고생산';
+}
+```
+
+### 4. createProductionOrder() — STOCK 분기
+
+| 항목 | ORDER (기존) | STOCK (신규) |
+|------|-------------|-------------|
+| 공정 매칭 | BOM item_id → process_items 매핑 | **절곡 공정 직접 할당** (BOM 스킵) |
+| project_name | `order.site_name ?? client_name` | `'재고생산'` 고정 |
+| scheduled_date | `order.delivery_date` | `now()` |
+| 매출 생성 | `sales_recognition` 정책 적용 | **생성 안 함** |
+
+절곡 공정 조회:
+```php
+$bendingProcess = Process::where('tenant_id', $tenantId)
+    ->where('process_name', '절곡')
+    ->where('is_active', true)
+    ->first();
+```
+
+### 5. stats() — order_type 필터
+
+```php
+public function stats(?string $orderType = null): array
+```
+
+`GET /api/v1/orders/stats?order_type=STOCK` 으로 재고생산 전용 통계 조회 가능.
+
+### 6. 매출 생성 스킵
+
+```php
+if ($status === Order::STATUS_CONFIRMED
+    && $order->order_type_code !== Order::TYPE_STOCK  // STOCK 제외
+    && $order->shouldCreateSaleOnConfirm()) {
+```
+
+---
+
+## 영향범위 분석
+
+| 영역 | 영향 | 이유 |
+|------|------|------|
+| 기존 수주(ORDER) | ❌ 없음 | `$isStock` 조건 분기, else 블록에서 기존 코드 그대로 실행 |
+| 기존 발주(PURCHASE) | ❌ 없음 | 동일 |
+| 작업지시(WorkOrder) | ✅ 정상 동작 | `sales_order_id` FK로 연결, 절곡 공정 할당됨 |
+| 생산/품질검사 | ❌ 없음 | WorkOrder 기반 하류 시스템, Order 타입 무관 |
+| 출하(Shipment) | ❌ 없음 | WorkOrder 참조, Order.site_name 미사용 |
+| 캘린더 | ✅ 표시됨 | `project_name='재고생산'`, `scheduled_date=now()` |
+| 생산지시 목록 | ✅ 표시됨 | `site_name='재고생산'`으로 현장명 표시 |
+
+---
+
+## 버그 수정 (2026-03-17)
+
+### 커밋 3: `fix: [production] 생산지시 생성 시 $isStock 미정의 오류 및 수량 정수 변환`
+
+| 파일 | 변경 내용 |
+|------|----------|
+| `app/Services/OrderService.php` | `DB::transaction` 클로저 `use`절에 `$isStock` 변수 추가 |
+| `app/Services/OrderService.php` | `work_order_items.quantity`를 `(int)` 캐스팅하여 정수로 저장 |
+
+**원인**: `$isStock`가 line 1242에서 정의되지만, `DB::transaction` 클로저의 `use`절에 포함되지 않아 클로저 내부에서 참조 불가 → 500 에러 발생
+
+### 커밋 4: `fix: [production] 생산지시 생성 시 $process 미정의 오류 수정`
+
+| 파일 | 변경 내용 |
+|------|----------|
+| `app/Services/OrderService.php` | `$process = null;` 초기화 추가 (if 블록 밖에서도 참조 가능하도록) |
+
+**원인**: `$process`가 `if ($processId)` 블록 안에서만 정의되지만, 블록 밖 line 1420에서 team_id 결정 시 참조 → 공정 없는 품목 처리 시 500 에러 발생
+
+### 커밋 5 (React): `fix: [stocks] 재고생산 수량을 정수로 표시`
+
+| 파일 | 변경 내용 |
+|------|----------|
+| `src/components/stocks/actions.ts` | `transformItemApiToFrontend`에서 `Math.floor(Number())` 적용 |
+| `src/components/stocks/actions.ts` | 금액 필드도 `Number()`로 안전한 형변환 적용 |
+
+**원인**: API의 Eloquent `decimal:4` 캐스트가 수량을 `"1.0000"` 문자열로 반환하여 프론트엔드에서 소수점 그대로 표시
+
+---
+
+## 테스트 체크리스트
+
+- [x] STOCK 수주 생성 → `order_no` STK 접두사 확인
+- [x] STOCK 수주 생성 → `site_name='재고생산'` 자동 설정 확인
+- [ ] STOCK 수주 확정 → 매출 자동 생성 안 됨 확인
+- [x] STOCK 생산지시 생성 → 절곡 공정 자동 선택 확인
+- [x] STOCK 생산지시 생성 → `project_name='재고생산'` 확인
+- [x] STOCK 생산지시 생성 → `scheduled_date=today` 확인
+- [ ] 기존 ORDER 수주 생산지시 → 기존 BOM 매칭 정상 동작 확인
+- [ ] 생산지시 목록에서 STOCK 건 표시 확인
+- [x] 생산지시 생성 시 `$isStock` 미정의 오류 수정 확인
+- [x] 생산지시 생성 시 `$process` 미정의 오류 수정 확인
+- [x] `work_order_items.quantity` 정수 저장 확인
+- [x] 프론트엔드 수량 정수 표시 확인
+
+---
+
+## 관련 문서
+
+- [재고생산관리 기능 설명](../../features/sales/stock-production.md)
+- [재고생산관리 API 명세](../../frontend/api-specs/stock-production-api.md)
+- [프론트엔드 구현 요청서](../../frontend/requests/stock-production-react-request.md)
+
+---
+
+**최종 업데이트**: 2026-03-17

dev/dev_plans/barobill-service-launch-plan.md

@@ -0,0 +1,242 @@
+# 바로빌 서비스 출시 단계별 준비 계획
+
+> **작성일**: 2026-03-17
+> **상태**: 계획 수립
+> **담당**: R&D실
+
+---
+
+## 1. 개요
+
+### 1.1 목적
+
+MNG에서 운영 중인 바로빌 연동 시스템을 서비스(API+React)로 이관하여, 멀티테넌트 고객이 직접 사용할 수 있는 SaaS 형태로 출시한다.
+
+### 1.2 현재 상태
+
+- **MNG (백오피스)**: 바로빌 SOAP 연동 완료, tenant_id=1 (코드브릿지엑스)에서 실무 운영 중
+- **API**: DB 모델 15개 + REST API 42개 엔드포인트 구현 완료 (데이터 조회/분개용)
+- **React**: 바로빌 설정 페이지 기본 구현
+
+### 1.3 목표
+
+고객(테넌트)이 SAM 서비스에서 바로빌 기능을 직접 설정하고 사용할 수 있도록 한다:
+- 계좌조회, 카드내역, 홈택스 세금계산서 자동 수집
+- 전자세금계산서 발행
+- 카카오톡/SMS 알림
+
+---
+
+## 2. 단계별 로드맵
+
+```
+Phase 1          Phase 2          Phase 3          Phase 4
+SOAP 이관        UI 구현          베타테스트        정식 출시
+(API 개발)       (React 개발)     (내부→외부)       (온보딩 가동)
+───────────── → ───────────── → ───────────── → ─────────────
+```
+
+---
+
+## 3. Phase 1: SOAP 연동 이관 (API 개발)
+
+> **핵심**: MNG의 BarobillService를 API로 이관하여 멀티테넌트 지원
+
+### 3.1 작업 목록
+
+| # | 작업 | 상세 | 난이도 |
+|---|------|------|--------|
+| 1-1 | BarobillService 이관 | MNG 1,761줄 → API로 이동, 멀티테넌트 리팩토링 | 상 |
+| 1-2 | 회원사 관리 API | 등록/수정/조회/상태확인 엔드포인트 | 중 |
+| 1-3 | 인증서 관리 API | 등록URL/유효성/만료일 조회 엔드포인트 | 중 |
+| 1-4 | 계좌 관리 API | 등록/목록/입출금 조회 엔드포인트 | 중 |
+| 1-5 | 카드 관리 API | 등록/수정/해지/사용내역 조회 엔드포인트 | 중 |
+| 1-6 | 세금계산서 발행 API | 작성/발행/조회 엔드포인트 | 상 |
+| 1-7 | 동기화 스케줄러 | 은행/카드/홈택스 자동 수집 (Queue Job) | 중 |
+| 1-8 | 테스트/운영 모드 전환 API | 회원사별 server_mode 전환 | 하 |
+
+### 3.2 기술 과제
+
+| 과제 | 설명 | 대응 방안 |
+|------|------|----------|
+| CERTKEY 관리 | 현재 전역 1개 → 멀티테넌트 대응 필요 | 바로빌 파트너 계약 구조 확인 후 결정 |
+| PHP SOAP 확장 | API 서버에 `php-soap` 설치 필요 | Docker/서버 환경 확인 |
+| 암호화 키 공유 | MNG/API 간 `APP_KEY` 동일해야 복호화 가능 | 현재 동일 키 사용 중 (확인 필요) |
+| 동기화 부하 | 테넌트 수 증가 시 SOAP 호출량 증가 | Queue 분산, 호출 간격 조절 |
+
+### 3.3 환경 준비
+
+```bash
+# API 서버에 PHP SOAP 확장 확인
+php -m | grep soap
+
+# 없으면 설치 (개발 서버 Level 2)
+sudo apt install php8.4-soap
+sudo systemctl restart php8.4-fpm
+
+# .env 설정 추가
+BAROBILL_CERT_KEY_TEST=<테스트 인증키>
+BAROBILL_CERT_KEY_PROD=<운영 인증키>
+BAROBILL_CORP_NUM=<파트너 사업자번호>
+BAROBILL_TEST_MODE=true
+```
+
+---
+
+## 4. Phase 2: UI 구현 (React 개발)
+
+> **핵심**: 고객이 직접 바로빌을 설정하고 데이터를 조회할 수 있는 화면
+
+### 4.1 작업 목록
+
+| # | 작업 | 상세 | 난이도 |
+|---|------|------|--------|
+| 2-1 | 바로빌 설정 페이지 | 회원사 등록/수정, 서버 모드 표시 | 중 |
+| 2-2 | 인증서 관리 화면 | 등록 URL 안내, 유효기간 표시, 갱신 알림 | 중 |
+| 2-3 | 계좌 관리 화면 | 등록 계좌 목록, 등록 URL 안내 | 중 |
+| 2-4 | 카드 관리 화면 | 등록 카드 목록, 추가/해지 | 중 |
+| 2-5 | 카드 거래내역 조회 | 기간별 조회, 분개 연동, 숨김/분할 | 상 |
+| 2-6 | 은행 거래내역 조회 | 기간별 조회, 분개 연동, 오버라이드/분할 | 상 |
+| 2-7 | 홈택스 세금계산서 | 매출/매입 조회, 분개 연동 | 중 |
+| 2-8 | 세금계산서 발행 화면 | 작성/발행 폼, 미리보기 | 상 |
+
+### 4.2 화면 구성 (메뉴 구조)
+
+```
+재무관리
+├─ 계좌관리
+│  ├─ 보유계좌 관리 (바로빌 계좌 등록 포함)
+│  └─ 계좌 입출금 내역
+├─ 카드관리
+│  ├─ 법인카드 관리 (바로빌 카드 등록 포함)
+│  └─ 카드 사용내역
+├─ 세금계산서
+│  ├─ 매출 세금계산서
+│  ├─ 매입 세금계산서
+│  └─ 세금계산서 발행
+└─ 설정
+   └─ 바로빌 연동 설정 (인증서, 모드, 충전잔액)
+```
+
+---
+
+## 5. Phase 3: 베타테스트
+
+> **핵심**: 내부 → 외부 순서로 검증, 테스트 모드 사용
+
+### 5.1 내부 베타테스트
+
+| 항목 | 내용 |
+|------|------|
+| **대상** | tenant_id=1 (코드브릿지엑스 본사) |
+| **기간** | 2주 |
+| **모드** | 테스트 모드 |
+| **검증 항목** | 전체 기능 동작, UI/UX, 데이터 정합성 |
+| **비교 기준** | MNG 운영 데이터와 서비스 데이터 일치 확인 |
+
+**내부 베타 체크리스트**:
+
+- [ ] 회원사 등록/수정 정상 동작
+- [ ] 인증서 등록 URL 정상 접근
+- [ ] 계좌 등록 및 입출금 내역 조회
+- [ ] 카드 등록 및 사용내역 조회
+- [ ] 홈택스 매출/매입 세금계산서 수집
+- [ ] 세금계산서 발행 (테스트 서버)
+- [ ] 분개 연동 정상 동작
+- [ ] 동기화 스케줄러 자동 수집 확인
+- [ ] MNG 데이터와 서비스 데이터 일치
+
+### 5.2 외부 베타테스트
+
+| 항목 | 내용 |
+|------|------|
+| **대상** | 선별 고객사 2~3곳 |
+| **기간** | 2~4주 |
+| **모드** | 테스트 모드 |
+| **검증 항목** | 실사용 시나리오, 다양한 사업자 유형, 피드백 수집 |
+
+**외부 베타 체크리스트**:
+
+- [ ] 다양한 사업자번호로 회원 등록
+- [ ] 다양한 은행/카드사 연동 확인
+- [ ] 고객 직접 인증서/계좌/카드 등록 가능 확인
+- [ ] 고객 피드백 수집 및 반영
+- [ ] 성능 (다수 테넌트 동시 동기화)
+
+---
+
+## 6. Phase 4: 정식 출시
+
+> **핵심**: 운영 모드 전환, 과금 시작, 온보딩 프로세스 가동
+
+### 6.1 출시 준비 체크리스트
+
+**인프라**:
+- [ ] API 서버 `php-soap` 확장 설치 확인
+- [ ] 운영 `.env`에 `BAROBILL_CERT_KEY_PROD`, `BAROBILL_CORP_NUM` 설정
+- [ ] `BAROBILL_TEST_MODE=false` 설정
+- [ ] 동기화 스케줄러 Supervisor 등록
+- [ ] 바로빌 운영 CERTKEY 충전잔액 확보
+
+**과금**:
+- [ ] `barobill_pricing_policies` 요금 정책 데이터 입력
+- [ ] 월정액 구독 자동 과금 배치 등록 (매월 1일)
+- [ ] 과금 내역 고객 조회 화면 (선택)
+
+**운영**:
+- [ ] 인증서 만료 알림 (이메일/카카오톡)
+- [ ] 충전잔액 부족 알림
+- [ ] 동기화 실패 알림 및 재시도 로직
+- [ ] 바로빌 장애 시 대응 매뉴얼
+
+### 6.2 온보딩 프로세스 정립
+
+정식 출시 후 신규 고객 가입 시:
+
+```
+계약 → 테넌트 생성 → 회원등록(테스트) → 인증서/계좌/카드 → 검증 → 운영전환 → 실무사용
+```
+
+> 상세 프로세스: `features/barobill/tenant-onboarding.md` 참조
+
+---
+
+## 7. 바로빌 파트너 정책 확인 필요 사항
+
+> **경고: 개발 착수 전 바로빌 측에 확인해야 할 사항**
+
+| # | 확인 사항 | 이유 | 현재 상태 |
+|---|----------|------|----------|
+| 1 | 멀티테넌트 CERTKEY 구조 | 파트너 1개 키로 다수 회원사 관리 가능한지 | 미확인 |
+| 2 | 테스트 서버 제한 | 테스트 API 호출 횟수/기간 제한 | 미확인 |
+| 3 | 과금 구조 | 파트너 단가표 (건당/월정액) | 미확인 |
+| 4 | SLA | 바로빌 API 가용성 보장 수준 | 미확인 |
+| 5 | 회원사 대량 등록 | 일괄 등록 API 또는 제한 | 미확인 |
+| 6 | 인증서 대리 등록 | 고객 대신 등록 가능 여부 | 미확인 |
+
+---
+
+## 8. 리스크 및 대응
+
+| 리스크 | 영향 | 대응 |
+|--------|------|------|
+| 바로빌 API 장애 | 거래 데이터 수집 중단 | 재시도 로직 + 장애 알림 |
+| 인증서 만료 | 계좌/세금계산서 조회 불가 | 만료 30일 전 알림 |
+| SOAP 호출 지연 | 페이지 응답 지연 | 비동기 Queue 처리 |
+| 테넌트 급증 | 동기화 부하 | 호출 간격 분산, 우선순위 큐 |
+| 충전잔액 부족 | API 호출 실패 | 잔액 모니터링 + 자동 알림 |
+
+---
+
+## 관련 문서
+
+| 문서 | 설명 |
+|------|------|
+| [바로빌 연동 시스템](../../features/barobill/README.md) | 전체 구조, 모드, 과금 |
+| [테넌트 온보딩](../../features/barobill/tenant-onboarding.md) | 온보딩 6단계 프로세스 |
+| [바로빌 API 명세](../../frontend/api-specs/barobill-api.md) | REST API 42개 엔드포인트 |
+| [이관 현황](../../system/migration-status.md) | MNG→API+React 전체 이관 현황 |
+
+---
+
+**최종 업데이트**: 2026-03-17