Files

hskwon a1af11871d docs: BP-MES Phase 1 통합 테스트 가이드 및 작업 이력 업데이트

- BP-MES_PHASE1_INTEGRATION_TEST.md 작성
  - 17개 API 엔드포인트 검증 가이드
  - 4개 통합 시나리오 (CRUD, BOM, File, 전체)
  - 에러 처리 검증 케이스
  - 성능 검증 기준
  - Swagger UI 테스트 체크리스트

- CURRENT_WORKS.md 업데이트
  - Items BOM API 구현 내용 (Day 6-9)
  - Items File Upload API 구현 내용 (Day 10-12)
  - 통합 테스트 완료 (Day 13-14)
  - API 엔드포인트 요약 (총 17개)
  - Phase 1 완료 및 Phase 2 제안

2025-11-17 14:08:42 +09:00

15 KiB

Raw Blame History

BP-MES Phase 1 통합 테스트 가이드

개요

BP-MES Phase 1에서 구현된 Items API의 통합 테스트 가이드입니다.

구현 완료 항목:

✅ Phase 1 Day 1-2: products/product_components 테이블 확장 (33개 필드)
✅ Phase 1 Day 3-5: ItemsController CRUD API (통합 품목 조회/생성/수정/삭제)
✅ Phase 1 Day 6-9: ItemsBomController API (BOM 관리 10개 엔드포인트)
✅ Phase 1 Day 10-12: ItemsFileController API (파일 업로드/삭제)

테스트 환경:

API Base URL: http://api.sam.kr/api/v1
Swagger UI: http://api.sam.kr/api-docs/index.html
인증: API Key (X-API-KEY) + Bearer Token (Authorization)

1. API 엔드포인트 검증

1.1 Items CRUD API (5개 엔드포인트)

Method	Endpoint	Description	Controller
GET	`/items`	품목 목록 조회 (통합)	ItemsController@index
POST	`/items`	품목 생성	ItemsController@store
GET	`/items/code/{code}`	코드 기반 조회	ItemsController@showByCode
PUT	`/items/{code}`	품목 수정	ItemsController@update
DELETE	`/items/{code}`	품목 삭제	ItemsController@destroy

1.2 Items BOM API (10개 엔드포인트)

Method	Endpoint	Description	Controller
GET	`/items/{code}/bom`	BOM 목록 (flat)	ItemsBomController@index
GET	`/items/{code}/bom/tree`	BOM 트리 (계층)	ItemsBomController@tree
POST	`/items/{code}/bom`	BOM 추가 (bulk)	ItemsBomController@store
PUT	`/items/{code}/bom/{lineId}`	BOM 수정	ItemsBomController@update
DELETE	`/items/{code}/bom/{lineId}`	BOM 삭제	ItemsBomController@destroy
GET	`/items/{code}/bom/summary`	BOM 요약	ItemsBomController@summary
GET	`/items/{code}/bom/validate`	BOM 검증	ItemsBomController@validate
POST	`/items/{code}/bom/replace`	BOM 전체 교체	ItemsBomController@replace
POST	`/items/{code}/bom/reorder`	BOM 정렬	ItemsBomController@reorder
GET	`/items/{code}/bom/categories`	카테고리 목록	ItemsBomController@listCategories

1.3 Items File API (2개 엔드포인트)

Method	Endpoint	Description	Controller
POST	`/items/{code}/files`	파일 업로드	ItemsFileController@upload
DELETE	`/items/{code}/files/{type}`	파일 삭제	ItemsFileController@delete

지원 파일 타입:

bending_diagram: 절곡도 (jpg, png, gif, svg - 10MB)
specification: 시방서 (pdf, doc, docx, xls, xlsx, hwp - 20MB)
certification: 인정서 (pdf, doc, docx, xls, xlsx, hwp - 20MB)

2. 데이터베이스 검증

2.1 Migration 상태

php artisan migrate:status

확인 사항:

✅ 2025_11_14_000001_add_hybrid_fields_to_products_table (batch 27)
✅ 2025_11_14_000002_add_attributes_to_product_components_table (batch 27)
✅ 2025_11_17_125437_add_file_fields_to_products_table (batch 28)

2.2 products 테이블 필드 확인

파일 관련 필드 (9개):

SELECT
    bending_diagram,
    bending_details,
    specification_file,
    specification_file_name,
    certification_file,
    certification_file_name,
    certification_number,
    certification_start_date,
    certification_end_date
FROM products
LIMIT 1;

2.3 Model 검증

# Product 모델 fillable 확인
php artisan tinker
>>> (new \App\Models\Products\Product)->getFillable();

# Product 모델 casts 확인
>>> (new \App\Models\Products\Product)->getCasts();

확인 사항:

✅ fillable에 9개 파일 필드 포함
✅ casts: bending_details (array), certification_start_date (date), certification_end_date (date)

3. 통합 테스트 시나리오

시나리오 1: 기본 CRUD 흐름

Step 1: 품목 생성

POST /api/v1/items
Content-Type: application/json
X-API-KEY: {api_key}
Authorization: Bearer {token}

{
  "item_type": "PRODUCT",
  "code": "TEST-001",
  "name": "테스트 제품",
  "unit": "EA",
  "category_id": 1,
  "product_type": "FG",
  "is_sellable": true,
  "is_purchasable": false,
  "is_producible": true
}

예상 결과:

HTTP 200 OK
{"success": true, "message": "품목이 등록되었습니다.", "data": {...}}

Step 2: 품목 조회

GET /api/v1/items/code/TEST-001
X-API-KEY: {api_key}
Authorization: Bearer {token}

예상 결과:

HTTP 200 OK
Product 데이터 반환

Step 3: 품목 수정

PUT /api/v1/items/TEST-001
Content-Type: application/json
X-API-KEY: {api_key}
Authorization: Bearer {token}

{
  "name": "테스트 제품 (수정)",
  "margin_rate": 15.5,
  "safety_stock": 100
}

예상 결과:

HTTP 200 OK
{"success": true, "message": "품목이 수정되었습니다.", "data": {...}}

시나리오 2: BOM 관리 흐름

전제 조건:

부모 품목: TEST-001 (생성 완료)
자재 1: M-001 (기존 자재)
자재 2: M-002 (기존 자재)

Step 1: BOM 추가 (Bulk)

POST /api/v1/items/TEST-001/bom
Content-Type: application/json
X-API-KEY: {api_key}
Authorization: Bearer {token}

{
  "items": [
    {
      "ref_type": "MATERIAL",
      "ref_id": 1,
      "quantity": 2.5,
      "sort_order": 1,
      "quantity_formula": "W * 2"
    },
    {
      "ref_type": "MATERIAL",
      "ref_id": 2,
      "quantity": 1.0,
      "sort_order": 2,
      "condition": "MOTOR='Y'"
    }
  ]
}

예상 결과:

HTTP 200 OK
BOM 항목 2개 생성

Step 2: BOM 트리 조회

GET /api/v1/items/TEST-001/bom/tree
X-API-KEY: {api_key}
Authorization: Bearer {token}

예상 결과:

HTTP 200 OK
계층 구조로 BOM 반환 (depth, children 포함)

Step 3: BOM 요약 조회

GET /api/v1/items/TEST-001/bom/summary
X-API-KEY: {api_key}
Authorization: Bearer {token}

예상 결과:

HTTP 200 OK
total_count, material_count, product_count 반환

Step 4: BOM 검증

GET /api/v1/items/TEST-001/bom/validate
X-API-KEY: {api_key}
Authorization: Bearer {token}

예상 결과:

HTTP 200 OK
is_valid, errors, warnings 반환

Step 5: BOM 라인 수정

PUT /api/v1/items/TEST-001/bom/1
Content-Type: application/json
X-API-KEY: {api_key}
Authorization: Bearer {token}

{
  "quantity": 3.0,
  "quantity_formula": "W * 3"
}

예상 결과:

HTTP 200 OK
BOM 항목 업데이트 완료

Step 6: BOM 정렬 변경

POST /api/v1/items/TEST-001/bom/reorder
Content-Type: application/json
X-API-KEY: {api_key}
Authorization: Bearer {token}

{
  "items": [
    {"id": 2, "sort_order": 1},
    {"id": 1, "sort_order": 2}
  ]
}

예상 결과:

HTTP 200 OK
BOM 정렬 순서 변경 완료

시나리오 3: 파일 업로드 흐름

전제 조건:

품목: TEST-001 (생성 완료)
테스트 파일: bending.jpg (절곡도), spec.pdf (시방서), cert.pdf (인정서)

Step 1: 절곡도 업로드

POST /api/v1/items/TEST-001/files
Content-Type: multipart/form-data
X-API-KEY: {api_key}
Authorization: Bearer {token}

type: bending_diagram
file: bending.jpg
bending_details: [
  {"angle": 90, "length": 100.5, "type": "V형"},
  {"angle": 45, "length": 50.0, "type": "Z형"}
]

예상 결과:

HTTP 200 OK
file_url, file_path, file_name 반환
product.bending_diagram 필드에 파일 경로 저장
product.bending_details 필드에 배열 저장

Step 2: 시방서 업로드

POST /api/v1/items/TEST-001/files
Content-Type: multipart/form-data
X-API-KEY: {api_key}
Authorization: Bearer {token}

type: specification
file: spec.pdf

예상 결과:

HTTP 200 OK
product.specification_file, specification_file_name 업데이트

Step 3: 인정서 업로드

POST /api/v1/items/TEST-001/files
Content-Type: multipart/form-data
X-API-KEY: {api_key}
Authorization: Bearer {token}

type: certification
file: cert.pdf
certification_number: CERT-2025-001
certification_start_date: 2025-01-01
certification_end_date: 2026-12-31

예상 결과:

HTTP 200 OK
product.certification_file, certification_file_name, certification_number, certification_start_date, certification_end_date 업데이트

Step 4: 파일 조회 (품목 정보에 포함)

GET /api/v1/items/code/TEST-001
X-API-KEY: {api_key}
Authorization: Bearer {token}

예상 결과:

HTTP 200 OK
Product 데이터에 파일 URL 포함

Step 5: 파일 삭제

DELETE /api/v1/items/TEST-001/files/bending_diagram
X-API-KEY: {api_key}
Authorization: Bearer {token}

예상 결과:

HTTP 200 OK
물리적 파일 삭제
product.bending_diagram, bending_details NULL 처리

시나리오 4: 전체 통합 시나리오

목표: 품목 생성 → BOM 구성 → 파일 업로드 → 검증

1. 품목 생성

POST /api/v1/items
{
  "item_type": "PRODUCT",
  "code": "INT-TEST-001",
  "name": "통합 테스트 제품",
  "unit": "EA",
  "category_id": 1,
  "product_type": "FG",
  "product_category": "SCREEN",
  "is_sellable": true,
  "is_purchasable": false,
  "is_producible": true,
  "margin_rate": 20.0,
  "safety_stock": 50,
  "lead_time": 7,
  "is_variable_size": true
}

2. BOM 구성

POST /api/v1/items/INT-TEST-001/bom
{
  "items": [
    {"ref_type": "MATERIAL", "ref_id": 1, "quantity": 2.0, "sort_order": 1, "quantity_formula": "W * 2"},
    {"ref_type": "MATERIAL", "ref_id": 2, "quantity": 1.0, "sort_order": 2, "condition": "MOTOR='Y'"},
    {"ref_type": "PRODUCT", "ref_id": 5, "quantity": 1.0, "sort_order": 3}
  ]
}

3. BOM 트리 및 요약 확인

GET /api/v1/items/INT-TEST-001/bom/tree
GET /api/v1/items/INT-TEST-001/bom/summary
GET /api/v1/items/INT-TEST-001/bom/validate

4. 절곡도 업로드

POST /api/v1/items/INT-TEST-001/files
type: bending_diagram
file: test_bending.jpg
bending_details: [{"angle": 90, "length": 100, "type": "V형"}]

5. 시방서 업로드

POST /api/v1/items/INT-TEST-001/files
type: specification
file: test_spec.pdf

6. 인정서 업로드

POST /api/v1/items/INT-TEST-001/files
type: certification
file: test_cert.pdf
certification_number: TEST-CERT-001
certification_start_date: 2025-01-01
certification_end_date: 2026-12-31

7. 최종 검증

GET /api/v1/items/code/INT-TEST-001

확인 사항:

✅ 품목 정보 정상 반환
✅ BOM 데이터 포함 (componentLines 관계)
✅ 파일 URL 3개 포함 (bending_diagram, specification_file, certification_file)
✅ 인증 정보 포함 (certification_number, start_date, end_date)
✅ 절곡 상세 정보 포함 (bending_details 배열)

8. 삭제 테스트

DELETE /api/v1/items/INT-TEST-001/bom/1
DELETE /api/v1/items/INT-TEST-001/files/bending_diagram
DELETE /api/v1/items/INT-TEST-001

4. 에러 처리 검증

4.1 파일 업로드 에러

케이스 1: 잘못된 파일 타입

POST /api/v1/items/TEST-001/files
type: bending_diagram
file: test.txt (텍스트 파일)

예상: HTTP 422, "허용되지 않는 파일 형식입니다."

케이스 2: 파일 크기 초과

POST /api/v1/items/TEST-001/files
type: bending_diagram
file: huge_image.jpg (15MB)

예상: HTTP 422, "파일 크기가 너무 큽니다."

케이스 3: 인증 기간 검증 실패

POST /api/v1/items/TEST-001/files
type: certification
file: cert.pdf
certification_start_date: 2025-12-31
certification_end_date: 2025-01-01

예상: HTTP 422, "인증 종료일은 시작일 이후여야 합니다."

4.2 BOM 에러

케이스 1: 존재하지 않는 품목

POST /api/v1/items/INVALID-CODE/bom

예상: HTTP 404, "존재하지 않는 URI 또는 데이터입니다."

케이스 2: 순환 참조

POST /api/v1/items/TEST-001/bom
{
  "items": [
    {"ref_type": "PRODUCT", "ref_id": 1, "quantity": 1.0}
  ]
}

(TEST-001의 ID가 1인 경우) 예상: BOM 검증 시 순환 참조 경고

4.3 CRUD 에러

케이스 1: 중복 코드

POST /api/v1/items
{
  "code": "TEST-001"  (이미 존재)
}

예상: HTTP 422, "중복된 데이터가 존재합니다."

케이스 2: 필수 필드 누락

POST /api/v1/items
{
  "code": "TEST-002"
  // name 누락
}

예상: HTTP 422, 검증 실패

5. 성능 검증

5.1 BOM 트리 조회 성능

# 10개 계층, 각 계층 5개 자식 = 약 50개 노드
GET /api/v1/items/{code}/bom/tree

# 목표: < 1초
# 실제: {측정 필요}

5.2 파일 업로드 성능

# 10MB 이미지 업로드
POST /api/v1/items/{code}/files

# 목표: < 5초
# 실제: {측정 필요}

5.3 목록 조회 성능

# 1000개 품목 페이징 조회
GET /api/v1/items?page=1&size=20

# 목표: < 500ms
# 실제: {측정 필요}

6. Swagger UI 테스트

6.1 접속 확인

URL: http://api.sam.kr/api-docs/index.html

확인 사항:

✅ Items Files 태그 표시
✅ POST /api/v1/items/{code}/files 엔드포인트 표시
✅ DELETE /api/v1/items/{code}/files/{type} 엔드포인트 표시
✅ ItemFileUploadResponse 스키마 표시
✅ ItemFileDeleteResponse 스키마 표시
✅ Try it out 기능 동작

6.2 API 문서 완성도

Items CRUD:

✅ 5개 엔드포인트 모두 문서화
✅ Request/Response 스키마 정의
✅ 예시 데이터 포함

Items BOM:

✅ 10개 엔드포인트 모두 문서화
✅ BOMLine, BOMTree 스키마 정의
✅ 예시 데이터 포함

Items Files:

✅ 2개 엔드포인트 모두 문서화
✅ multipart/form-data 정의
✅ 파일 타입별 검증 규칙 설명

7. 체크리스트

Phase 1 완료 항목

products 테이블 확장 (33개 필드)
product_components 테이블 확장 (5개 필드)
products 파일 필드 추가 (9개 필드)
ItemsController CRUD API (5개 엔드포인트)
ItemsBomController API (10개 엔드포인트)
ItemsFileController API (2개 엔드포인트)
FormRequest 검증 (ItemsFileUploadRequest)
Swagger 문서 작성 (ItemsFileApi)
Migration 실행 및 검증
Pint 코드 포맷팅
Git 커밋

테스트 권장 순서

Swagger UI 접속 및 문서 확인
Database 스키마 검증
Model fillable/casts 확인
Items CRUD API 테스트
Items BOM API 테스트
Items File API 테스트
통합 시나리오 테스트
에러 처리 검증
성능 측정
최종 검증

8. 다음 단계

Phase 2 계획 (제안):

Frontend 연동 (React/Vue)
파일 미리보기 기능
BOM 계산 로직 (수식 평가)
조건부 BOM 처리
대량 데이터 Import/Export
품목 복제 기능
변경 이력 추적
통합 검색 개선

작성일: 2025-11-17 작성자: Claude Code 버전: 1.0

15 KiB Raw Blame History

BP-MES Phase 1 통합 테스트 가이드

개요

1. API 엔드포인트 검증

1.1 Items CRUD API (5개 엔드포인트)

1.2 Items BOM API (10개 엔드포인트)

1.3 Items File API (2개 엔드포인트)

2. 데이터베이스 검증

2.1 Migration 상태

2.2 products 테이블 필드 확인

2.3 Model 검증

3. 통합 테스트 시나리오

시나리오 1: 기본 CRUD 흐름

시나리오 2: BOM 관리 흐름

시나리오 3: 파일 업로드 흐름

시나리오 4: 전체 통합 시나리오

4. 에러 처리 검증

4.1 파일 업로드 에러

4.2 BOM 에러

4.3 CRUD 에러

5. 성능 검증

5.1 BOM 트리 조회 성능

5.2 파일 업로드 성능

5.3 목록 조회 성능

6. Swagger UI 테스트

6.1 접속 확인

6.2 API 문서 완성도

7. 체크리스트

Phase 1 완료 항목

테스트 권장 순서

8. 다음 단계

15 KiB

Raw Blame History