sam-api/app/Swagger/v1/ProductionOrderApi.php

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="ProductionOrders", description="생산지시 관리")
 *
 * @OA\Schema(
 *     schema="ProductionOrderListItem",
 *     type="object",
 *     description="생산지시 목록 아이템",
 *
 *     @OA\Property(property="id", type="integer", example=1, description="수주 ID"),
 *     @OA\Property(property="order_no", type="string", example="ORD-20260301-0001", description="수주번호 (= 생산지시번호)"),
 *     @OA\Property(property="site_name", type="string", example="서울현장", nullable=true, description="현장명"),
 *     @OA\Property(property="client_name", type="string", example="(주)고객사", nullable=true, description="거래처명"),
 *     @OA\Property(property="quantity", type="number", example=232, description="부품수량 합계"),
 *     @OA\Property(property="node_count", type="integer", example=4, description="개소수 (order_nodes 수)"),
 *     @OA\Property(property="delivery_date", type="string", format="date", example="2026-03-15", nullable=true, description="납기일"),
 *     @OA\Property(property="production_ordered_at", type="string", format="date", example="2026-02-21", nullable=true, description="생산지시일 (첫 WorkOrder 생성일, Y-m-d)"),
 *     @OA\Property(property="production_status", type="string", enum={"waiting","in_production","completed"}, example="waiting", description="생산 상태"),
 *     @OA\Property(property="work_orders_count", type="integer", example=2, description="작업지시 수 (공정별 1건)"),
 *     @OA\Property(property="work_order_progress", type="object",
 *         @OA\Property(property="total", type="integer", example=3),
 *         @OA\Property(property="completed", type="integer", example=1),
 *         @OA\Property(property="in_progress", type="integer", example=1)
 *     ),
 *     @OA\Property(property="client", type="object", nullable=true,
 *         @OA\Property(property="id", type="integer", example=1),
 *         @OA\Property(property="name", type="string", example="(주)고객사")
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="ProductionOrderStats",
 *     type="object",
 *     description="생산지시 통계",
 *
 *     @OA\Property(property="total", type="integer", example=25, description="전체"),
 *     @OA\Property(property="waiting", type="integer", example=10, description="생산대기"),
 *     @OA\Property(property="in_production", type="integer", example=8, description="생산중"),
 *     @OA\Property(property="completed", type="integer", example=7, description="생산완료")
 * )
 *
 * @OA\Schema(
 *     schema="ProductionOrderDetail",
 *     type="object",
 *     description="생산지시 상세",
 *
 *     @OA\Property(property="order", ref="#/components/schemas/ProductionOrderListItem"),
 *     @OA\Property(property="production_ordered_at", type="string", format="date", example="2026-02-21", nullable=true),
 *     @OA\Property(property="production_status", type="string", enum={"waiting","in_production","completed"}),
 *     @OA\Property(property="node_count", type="integer", example=4, description="개소수"),
 *     @OA\Property(property="work_order_progress", type="object",
 *         @OA\Property(property="total", type="integer"),
 *         @OA\Property(property="completed", type="integer"),
 *         @OA\Property(property="in_progress", type="integer")
 *     ),
 *     @OA\Property(property="work_orders", type="array",
 *
 *         @OA\Items(type="object",
 *
 *             @OA\Property(property="id", type="integer"),
 *             @OA\Property(property="work_order_no", type="string"),
 *             @OA\Property(property="process_name", type="string"),
 *             @OA\Property(property="quantity", type="integer"),
 *             @OA\Property(property="status", type="string"),
 *             @OA\Property(property="assignees", type="array", @OA\Items(type="string"))
 *         )
 *     ),
 *     @OA\Property(property="bom_process_groups", type="array",
 *
 *         @OA\Items(type="object",
 *
 *             @OA\Property(property="process_name", type="string"),
 *             @OA\Property(property="size_spec", type="string", nullable=true),
 *             @OA\Property(property="items", type="array",
 *
 *                 @OA\Items(type="object",
 *
 *                     @OA\Property(property="id", type="integer", nullable=true),
 *                     @OA\Property(property="item_code", type="string"),
 *                     @OA\Property(property="item_name", type="string"),
 *                     @OA\Property(property="spec", type="string"),
 *                     @OA\Property(property="lot_no", type="string"),
 *                     @OA\Property(property="required_qty", type="number"),
 *                     @OA\Property(property="qty", type="number")
 *                 )
 *             )
 *         )
 *     )
 * )
 */
class ProductionOrderApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/production-orders",
     *     tags={"ProductionOrders"},
     *     summary="생산지시 목록 조회",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(name="search", in="query", required=false,
     *
     *         @OA\Schema(type="string"), description="검색어 (수주번호, 거래처명, 현장명)"
     *     ),
     *
     *     @OA\Parameter(name="production_status", in="query", required=false,
     *
     *         @OA\Schema(type="string", enum={"waiting","in_production","completed"}), description="생산 상태 필터"
     *     ),
     *
     *     @OA\Parameter(name="sort_by", in="query", required=false,
     *
     *         @OA\Schema(type="string", enum={"created_at","delivery_date","order_no"}), description="정렬 기준"
     *     ),
     *
     *     @OA\Parameter(name="sort_dir", in="query", required=false,
     *
     *         @OA\Schema(type="string", enum={"asc","desc"}), description="정렬 방향"
     *     ),
     *
     *     @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer")),
     *     @OA\Parameter(name="per_page", in="query", required=false, @OA\Schema(type="integer")),
     *
     *     @OA\Response(response=200, description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", type="object",
     *                 @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/ProductionOrderListItem")),
     *                 @OA\Property(property="current_page", type="integer"),
     *                 @OA\Property(property="last_page", type="integer"),
     *                 @OA\Property(property="per_page", type="integer"),
     *                 @OA\Property(property="total", type="integer")
     *             )
     *         )
     *     )
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *     path="/api/v1/production-orders/stats",
     *     tags={"ProductionOrders"},
     *     summary="생산지시 상태별 통계",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Response(response=200, description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", ref="#/components/schemas/ProductionOrderStats")
     *         )
     *     )
     * )
     */
    public function stats() {}

    /**
     * @OA\Get(
     *     path="/api/v1/production-orders/{orderId}",
     *     tags={"ProductionOrders"},
     *     summary="생산지시 상세 조회",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\Parameter(name="orderId", in="path", required=true, @OA\Schema(type="integer"), description="수주 ID"),
     *
     *     @OA\Response(response=200, description="성공",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string"),
     *             @OA\Property(property="data", ref="#/components/schemas/ProductionOrderDetail")
     *         )
     *     ),
     *
     *     @OA\Response(response=404, description="생산지시를 찾을 수 없음")
     * )
     */
    public function show() {}
}