From fb06975d972f4493061d0f7a5df1d1d9b317cc83 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EA=B6=8C=ED=98=81=EC=84=B1?= <shine1324@gmail.com>
Date: Sat, 31 Jan 2026 09:39:55 +0900
Subject: [PATCH] =?UTF-8?q?feat:=EB=AC=B8=EC=84=9C=EA=B4=80=EB=A6=AC=20Pha?=
 =?UTF-8?q?se=204.1=20-=20DocumentTemplate=20API=20+=20=EA=B2=B0=EC=9E=AC?=
 =?UTF-8?q?=20=EC=9B=8C=ED=81=AC=ED=94=8C=EB=A1=9C=EC=9A=B0=20=ED=99=9C?=
 =?UTF-8?q?=EC=84=B1=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- DocumentTemplate 모델 6개 생성 (Template, ApprovalLine, BasicField, Section, SectionItem, Column)
- DocumentTemplateService (list/show) + DocumentTemplateController (index/show)
- GET /v1/document-templates, GET /v1/document-templates/{id} 라우트
- DocumentTemplateApi.php Swagger (7개 스키마, 2개 엔드포인트)
- Document 결재 워크플로우 4개 엔드포인트 활성화 (submit/approve/reject/cancel)
- ApproveRequest, RejectRequest FormRequest 생성
- DocumentApi.php Swagger에 결재 엔드포인트 4개 추가
- Document.template() 참조 경로 수정 (DocumentTemplate → Documents 네임스페이스)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .../Api/V1/Documents/DocumentController.php   |  52 ++++-
 .../Documents/DocumentTemplateController.php  |  36 ++++
 app/Http/Requests/Document/ApproveRequest.php |  20 ++
 app/Http/Requests/Document/RejectRequest.php  |  20 ++
 .../DocumentTemplate/IndexRequest.php         |  26 +++
 app/Models/Documents/Document.php             |   2 +-
 app/Models/Documents/DocumentTemplate.php     | 113 ++++++++++
 .../DocumentTemplateApprovalLine.php          |  38 ++++
 .../Documents/DocumentTemplateBasicField.php  |  38 ++++
 .../Documents/DocumentTemplateColumn.php      |  43 ++++
 .../Documents/DocumentTemplateSection.php     |  43 ++++
 .../Documents/DocumentTemplateSectionItem.php |  44 ++++
 app/Services/DocumentTemplateService.php      |  67 ++++++
 app/Swagger/v1/DocumentApi.php                | 147 +++++++++++++
 app/Swagger/v1/DocumentTemplateApi.php        | 194 ++++++++++++++++++
 routes/api/v1/documents.php                   |  23 ++-
 16 files changed, 893 insertions(+), 13 deletions(-)
 create mode 100644 app/Http/Controllers/Api/V1/Documents/DocumentTemplateController.php
 create mode 100644 app/Http/Requests/Document/ApproveRequest.php
 create mode 100644 app/Http/Requests/Document/RejectRequest.php
 create mode 100644 app/Http/Requests/DocumentTemplate/IndexRequest.php
 create mode 100644 app/Models/Documents/DocumentTemplate.php
 create mode 100644 app/Models/Documents/DocumentTemplateApprovalLine.php
 create mode 100644 app/Models/Documents/DocumentTemplateBasicField.php
 create mode 100644 app/Models/Documents/DocumentTemplateColumn.php
 create mode 100644 app/Models/Documents/DocumentTemplateSection.php
 create mode 100644 app/Models/Documents/DocumentTemplateSectionItem.php
 create mode 100644 app/Services/DocumentTemplateService.php
 create mode 100644 app/Swagger/v1/DocumentTemplateApi.php

diff --git a/app/Http/Controllers/Api/V1/Documents/DocumentController.php b/app/Http/Controllers/Api/V1/Documents/DocumentController.php
index 639031f..9cbc832 100644
--- a/app/Http/Controllers/Api/V1/Documents/DocumentController.php
+++ b/app/Http/Controllers/Api/V1/Documents/DocumentController.php
@@ -4,7 +4,9 @@
 
 use App\Helpers\ApiResponse;
 use App\Http\Controllers\Controller;
+use App\Http\Requests\Document\ApproveRequest;
 use App\Http\Requests\Document\IndexRequest;
+use App\Http\Requests\Document\RejectRequest;
 use App\Http\Requests\Document\StoreRequest;
 use App\Http\Requests\Document\UpdateRequest;
 use App\Services\DocumentService;
@@ -70,10 +72,50 @@ public function destroy(int $id): JsonResponse
     }
 
     // =========================================================================
-    // 결재 관련 메서드 (보류 - 기존 시스템 연동 필요)
+    // 결재 워크플로우
     // =========================================================================
-    // public function submit(int $id): JsonResponse
-    // public function approve(int $id, ApproveRequest $request): JsonResponse
-    // public function reject(int $id, RejectRequest $request): JsonResponse
-    // public function cancel(int $id): JsonResponse
+
+    /**
+     * 결재 제출 (DRAFT → PENDING)
+     * POST /v1/documents/{id}/submit
+     */
+    public function submit(int $id): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id) {
+            return $this->service->submit($id);
+        }, __('message.updated'));
+    }
+
+    /**
+     * 결재 승인
+     * POST /v1/documents/{id}/approve
+     */
+    public function approve(int $id, ApproveRequest $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id, $request) {
+            return $this->service->approve($id, $request->validated()['comment'] ?? null);
+        }, __('message.updated'));
+    }
+
+    /**
+     * 결재 반려
+     * POST /v1/documents/{id}/reject
+     */
+    public function reject(int $id, RejectRequest $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id, $request) {
+            return $this->service->reject($id, $request->validated()['comment']);
+        }, __('message.updated'));
+    }
+
+    /**
+     * 결재 취소/회수
+     * POST /v1/documents/{id}/cancel
+     */
+    public function cancel(int $id): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id) {
+            return $this->service->cancel($id);
+        }, __('message.updated'));
+    }
 }
diff --git a/app/Http/Controllers/Api/V1/Documents/DocumentTemplateController.php b/app/Http/Controllers/Api/V1/Documents/DocumentTemplateController.php
new file mode 100644
index 0000000..3173881
--- /dev/null
+++ b/app/Http/Controllers/Api/V1/Documents/DocumentTemplateController.php
@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\Documents;
+
+use App\Helpers\ApiResponse;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\DocumentTemplate\IndexRequest;
+use App\Services\DocumentTemplateService;
+use Illuminate\Http\JsonResponse;
+
+class DocumentTemplateController extends Controller
+{
+    public function __construct(private DocumentTemplateService $service) {}
+
+    /**
+     * 양식 목록 조회
+     * GET /v1/document-templates
+     */
+    public function index(IndexRequest $request): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($request) {
+            return $this->service->list($request->validated());
+        }, __('message.fetched'));
+    }
+
+    /**
+     * 양식 상세 조회
+     * GET /v1/document-templates/{id}
+     */
+    public function show(int $id): JsonResponse
+    {
+        return ApiResponse::handle(function () use ($id) {
+            return $this->service->show($id);
+        }, __('message.fetched'));
+    }
+}
diff --git a/app/Http/Requests/Document/ApproveRequest.php b/app/Http/Requests/Document/ApproveRequest.php
new file mode 100644
index 0000000..83da347
--- /dev/null
+++ b/app/Http/Requests/Document/ApproveRequest.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace App\Http\Requests\Document;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class ApproveRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'comment' => 'nullable|string|max:500',
+        ];
+    }
+}
diff --git a/app/Http/Requests/Document/RejectRequest.php b/app/Http/Requests/Document/RejectRequest.php
new file mode 100644
index 0000000..e2946ff
--- /dev/null
+++ b/app/Http/Requests/Document/RejectRequest.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace App\Http\Requests\Document;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class RejectRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'comment' => 'required|string|max:500',
+        ];
+    }
+}
diff --git a/app/Http/Requests/DocumentTemplate/IndexRequest.php b/app/Http/Requests/DocumentTemplate/IndexRequest.php
new file mode 100644
index 0000000..260c6cd
--- /dev/null
+++ b/app/Http/Requests/DocumentTemplate/IndexRequest.php
@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Http\Requests\DocumentTemplate;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class IndexRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'is_active' => 'nullable|boolean',
+            'category' => 'nullable|string|max:50',
+            'search' => 'nullable|string|max:100',
+            'sort_by' => 'nullable|string|in:created_at,name,category',
+            'sort_dir' => 'nullable|string|in:asc,desc',
+            'per_page' => 'nullable|integer|min:1|max:100',
+            'page' => 'nullable|integer|min:1',
+        ];
+    }
+}
diff --git a/app/Models/Documents/Document.php b/app/Models/Documents/Document.php
index 6f3b2c2..1f5b4ed 100644
--- a/app/Models/Documents/Document.php
+++ b/app/Models/Documents/Document.php
@@ -96,7 +96,7 @@ class Document extends Model
      */
     public function template(): BelongsTo
     {
-        return $this->belongsTo(\App\Models\DocumentTemplate::class, 'template_id');
+        return $this->belongsTo(DocumentTemplate::class, 'template_id');
     }
 
     /**
diff --git a/app/Models/Documents/DocumentTemplate.php b/app/Models/Documents/DocumentTemplate.php
new file mode 100644
index 0000000..a1dd054
--- /dev/null
+++ b/app/Models/Documents/DocumentTemplate.php
@@ -0,0 +1,113 @@
+<?php
+
+namespace App\Models\Documents;
+
+use App\Traits\BelongsToTenant;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+/**
+ * 문서 양식(템플릿) 모델
+ *
+ * @property int $id
+ * @property int $tenant_id
+ * @property string $name 양식명
+ * @property string $category 분류 (품질, 생산 등)
+ * @property string|null $title 문서 제목
+ * @property string|null $company_name 회사명
+ * @property string|null $company_address 회사 주소
+ * @property string|null $company_contact 연락처
+ * @property string $footer_remark_label 하단 비고 라벨
+ * @property string $footer_judgement_label 하단 판정 라벨
+ * @property array|null $footer_judgement_options 판정 옵션 (JSON)
+ * @property bool $is_active 활성 여부
+ * @property \Carbon\Carbon|null $created_at
+ * @property \Carbon\Carbon|null $updated_at
+ * @property \Carbon\Carbon|null $deleted_at
+ */
+class DocumentTemplate extends Model
+{
+    use BelongsToTenant, SoftDeletes;
+
+    protected $table = 'document_templates';
+
+    protected $fillable = [
+        'tenant_id',
+        'name',
+        'category',
+        'title',
+        'company_name',
+        'company_address',
+        'company_contact',
+        'footer_remark_label',
+        'footer_judgement_label',
+        'footer_judgement_options',
+        'is_active',
+    ];
+
+    protected $casts = [
+        'footer_judgement_options' => 'array',
+        'is_active' => 'boolean',
+    ];
+
+    // =========================================================================
+    // Relationships
+    // =========================================================================
+
+    /**
+     * 결재라인
+     */
+    public function approvalLines(): HasMany
+    {
+        return $this->hasMany(DocumentTemplateApprovalLine::class, 'template_id')
+            ->orderBy('sort_order');
+    }
+
+    /**
+     * 기본 필드
+     */
+    public function basicFields(): HasMany
+    {
+        return $this->hasMany(DocumentTemplateBasicField::class, 'template_id')
+            ->orderBy('sort_order');
+    }
+
+    /**
+     * 검사 기준서 섹션
+     */
+    public function sections(): HasMany
+    {
+        return $this->hasMany(DocumentTemplateSection::class, 'template_id')
+            ->orderBy('sort_order');
+    }
+
+    /**
+     * 테이블 컬럼
+     */
+    public function columns(): HasMany
+    {
+        return $this->hasMany(DocumentTemplateColumn::class, 'template_id')
+            ->orderBy('sort_order');
+    }
+
+    // =========================================================================
+    // Scopes
+    // =========================================================================
+
+    /**
+     * 활성 양식만
+     */
+    public function scopeActive($query)
+    {
+        return $query->where('is_active', true);
+    }
+
+    /**
+     * 카테고리 필터
+     */
+    public function scopeCategory($query, string $category)
+    {
+        return $query->where('category', $category);
+    }
+}
diff --git a/app/Models/Documents/DocumentTemplateApprovalLine.php b/app/Models/Documents/DocumentTemplateApprovalLine.php
new file mode 100644
index 0000000..b6b274b
--- /dev/null
+++ b/app/Models/Documents/DocumentTemplateApprovalLine.php
@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Models\Documents;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * 문서 양식 결재라인 모델
+ *
+ * @property int $id
+ * @property int $template_id
+ * @property string $name 결재자 이름/직책
+ * @property string|null $dept 부서
+ * @property string $role 역할 (작성/검토/승인)
+ * @property int $sort_order 정렬 순서
+ */
+class DocumentTemplateApprovalLine extends Model
+{
+    protected $table = 'document_template_approval_lines';
+
+    protected $fillable = [
+        'template_id',
+        'name',
+        'dept',
+        'role',
+        'sort_order',
+    ];
+
+    protected $casts = [
+        'sort_order' => 'integer',
+    ];
+
+    public function template(): BelongsTo
+    {
+        return $this->belongsTo(DocumentTemplate::class, 'template_id');
+    }
+}
diff --git a/app/Models/Documents/DocumentTemplateBasicField.php b/app/Models/Documents/DocumentTemplateBasicField.php
new file mode 100644
index 0000000..c2e22c6
--- /dev/null
+++ b/app/Models/Documents/DocumentTemplateBasicField.php
@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Models\Documents;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * 문서 양식 기본필드 모델
+ *
+ * @property int $id
+ * @property int $template_id
+ * @property string $label 필드 라벨
+ * @property string $field_type 필드 타입 (text/date/select 등)
+ * @property string|null $default_value 기본값
+ * @property int $sort_order 정렬 순서
+ */
+class DocumentTemplateBasicField extends Model
+{
+    protected $table = 'document_template_basic_fields';
+
+    protected $fillable = [
+        'template_id',
+        'label',
+        'field_type',
+        'default_value',
+        'sort_order',
+    ];
+
+    protected $casts = [
+        'sort_order' => 'integer',
+    ];
+
+    public function template(): BelongsTo
+    {
+        return $this->belongsTo(DocumentTemplate::class, 'template_id');
+    }
+}
diff --git a/app/Models/Documents/DocumentTemplateColumn.php b/app/Models/Documents/DocumentTemplateColumn.php
new file mode 100644
index 0000000..af39ef2
--- /dev/null
+++ b/app/Models/Documents/DocumentTemplateColumn.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Models\Documents;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * 문서 양식 테이블 컬럼 모델
+ *
+ * @property int $id
+ * @property int $template_id
+ * @property string $label 컬럼 라벨
+ * @property string|null $width 컬럼 너비
+ * @property string $column_type 컬럼 타입 (text/check/complex/select/measurement)
+ * @property string|null $group_name 그룹명
+ * @property array|null $sub_labels 하위 라벨 (complex 타입)
+ * @property int $sort_order 정렬 순서
+ */
+class DocumentTemplateColumn extends Model
+{
+    protected $table = 'document_template_columns';
+
+    protected $fillable = [
+        'template_id',
+        'label',
+        'width',
+        'column_type',
+        'group_name',
+        'sub_labels',
+        'sort_order',
+    ];
+
+    protected $casts = [
+        'sub_labels' => 'array',
+        'sort_order' => 'integer',
+    ];
+
+    public function template(): BelongsTo
+    {
+        return $this->belongsTo(DocumentTemplate::class, 'template_id');
+    }
+}
diff --git a/app/Models/Documents/DocumentTemplateSection.php b/app/Models/Documents/DocumentTemplateSection.php
new file mode 100644
index 0000000..1346f35
--- /dev/null
+++ b/app/Models/Documents/DocumentTemplateSection.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Models\Documents;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+/**
+ * 문서 양식 섹션 모델
+ *
+ * @property int $id
+ * @property int $template_id
+ * @property string $title 섹션 제목
+ * @property string|null $image_path 검사 기준 이미지 경로
+ * @property int $sort_order 정렬 순서
+ */
+class DocumentTemplateSection extends Model
+{
+    protected $table = 'document_template_sections';
+
+    protected $fillable = [
+        'template_id',
+        'title',
+        'image_path',
+        'sort_order',
+    ];
+
+    protected $casts = [
+        'sort_order' => 'integer',
+    ];
+
+    public function template(): BelongsTo
+    {
+        return $this->belongsTo(DocumentTemplate::class, 'template_id');
+    }
+
+    public function items(): HasMany
+    {
+        return $this->hasMany(DocumentTemplateSectionItem::class, 'section_id')
+            ->orderBy('sort_order');
+    }
+}
diff --git a/app/Models/Documents/DocumentTemplateSectionItem.php b/app/Models/Documents/DocumentTemplateSectionItem.php
new file mode 100644
index 0000000..b61fd5e
--- /dev/null
+++ b/app/Models/Documents/DocumentTemplateSectionItem.php
@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Models\Documents;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * 문서 양식 섹션 검사항목 모델
+ *
+ * @property int $id
+ * @property int $section_id
+ * @property string|null $category 항목 분류
+ * @property string $item 검사항목
+ * @property string|null $standard 검사기준
+ * @property string|null $method 검사방식
+ * @property string|null $frequency 검사주기
+ * @property string|null $regulation 관련 규격
+ * @property int $sort_order 정렬 순서
+ */
+class DocumentTemplateSectionItem extends Model
+{
+    protected $table = 'document_template_section_items';
+
+    protected $fillable = [
+        'section_id',
+        'category',
+        'item',
+        'standard',
+        'method',
+        'frequency',
+        'regulation',
+        'sort_order',
+    ];
+
+    protected $casts = [
+        'sort_order' => 'integer',
+    ];
+
+    public function section(): BelongsTo
+    {
+        return $this->belongsTo(DocumentTemplateSection::class, 'section_id');
+    }
+}
diff --git a/app/Services/DocumentTemplateService.php b/app/Services/DocumentTemplateService.php
new file mode 100644
index 0000000..bbce2c5
--- /dev/null
+++ b/app/Services/DocumentTemplateService.php
@@ -0,0 +1,67 @@
+<?php
+
+namespace App\Services;
+
+use App\Models\Documents\DocumentTemplate;
+use Illuminate\Contracts\Pagination\LengthAwarePaginator;
+
+class DocumentTemplateService extends Service
+{
+    /**
+     * 양식 목록 조회
+     */
+    public function list(array $params): LengthAwarePaginator
+    {
+        $tenantId = $this->tenantId();
+
+        $query = DocumentTemplate::query()
+            ->where('tenant_id', $tenantId)
+            ->with(['approvalLines', 'basicFields']);
+
+        // 활성 상태 필터
+        if (isset($params['is_active'])) {
+            $query->where('is_active', filter_var($params['is_active'], FILTER_VALIDATE_BOOLEAN));
+        }
+
+        // 카테고리 필터
+        if (! empty($params['category'])) {
+            $query->where('category', $params['category']);
+        }
+
+        // 검색 (양식명)
+        if (! empty($params['search'])) {
+            $search = $params['search'];
+            $query->where(function ($q) use ($search) {
+                $q->where('name', 'like', "%{$search}%")
+                    ->orWhere('title', 'like', "%{$search}%");
+            });
+        }
+
+        // 정렬
+        $sortBy = $params['sort_by'] ?? 'created_at';
+        $sortDir = $params['sort_dir'] ?? 'desc';
+        $query->orderBy($sortBy, $sortDir);
+
+        $perPage = $params['per_page'] ?? 20;
+
+        return $query->paginate($perPage);
+    }
+
+    /**
+     * 양식 상세 조회 (전체 관계 포함)
+     */
+    public function show(int $id): DocumentTemplate
+    {
+        $tenantId = $this->tenantId();
+
+        return DocumentTemplate::query()
+            ->where('tenant_id', $tenantId)
+            ->with([
+                'approvalLines',
+                'basicFields',
+                'sections.items',
+                'columns',
+            ])
+            ->findOrFail($id);
+    }
+}
diff --git a/app/Swagger/v1/DocumentApi.php b/app/Swagger/v1/DocumentApi.php
index fa6383c..5c47d30 100644
--- a/app/Swagger/v1/DocumentApi.php
+++ b/app/Swagger/v1/DocumentApi.php
@@ -334,4 +334,151 @@ public function update() {}
      * )
      */
     public function destroy() {}
+
+    // =========================================================================
+    // 결재 워크플로우
+    // =========================================================================
+
+    /**
+     * @OA\Post(
+     *     path="/api/v1/documents/{id}/submit",
+     *     tags={"Documents"},
+     *     summary="결재 제출",
+     *     description="DRAFT 또는 REJECTED 상태의 문서를 결재 요청합니다 (PENDING 상태로 변경).",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @OA\Schema(type="integer")),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="결재 제출 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Document"))
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=400, description="잘못된 요청 (제출 불가 상태 또는 결재선 미설정)", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="문서를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function submit() {}
+
+    /**
+     * @OA\Post(
+     *     path="/api/v1/documents/{id}/approve",
+     *     tags={"Documents"},
+     *     summary="결재 승인",
+     *     description="현재 사용자의 결재 단계를 승인합니다. 모든 단계 완료 시 문서가 APPROVED 상태로 변경됩니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @OA\Schema(type="integer")),
+     *
+     *     @OA\RequestBody(
+     *         required=false,
+     *
+     *         @OA\JsonContent(
+     *
+     *             @OA\Property(property="comment", type="string", example="승인합니다.", nullable=true, description="결재 의견")
+     *         )
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="승인 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Document"))
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=400, description="잘못된 요청 (승인 불가 상태 또는 차례 아님)", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="문서를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function approve() {}
+
+    /**
+     * @OA\Post(
+     *     path="/api/v1/documents/{id}/reject",
+     *     tags={"Documents"},
+     *     summary="결재 반려",
+     *     description="현재 사용자의 결재 단계를 반려합니다. 문서가 REJECTED 상태로 변경됩니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @OA\Schema(type="integer")),
+     *
+     *     @OA\RequestBody(
+     *         required=true,
+     *
+     *         @OA\JsonContent(
+     *             required={"comment"},
+     *
+     *             @OA\Property(property="comment", type="string", example="검사 기준 미달로 반려합니다.", description="반려 사유 (필수)")
+     *         )
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="반려 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Document"))
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=400, description="잘못된 요청 (반려 불가 상태 또는 차례 아님)", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="문서를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function reject() {}
+
+    /**
+     * @OA\Post(
+     *     path="/api/v1/documents/{id}/cancel",
+     *     tags={"Documents"},
+     *     summary="결재 취소/회수",
+     *     description="작성자만 DRAFT 또는 PENDING 상태의 문서를 취소할 수 있습니다. CANCELLED 상태로 변경됩니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="id", in="path", required=true, description="문서 ID", @OA\Schema(type="integer")),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="취소 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Document"))
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=400, description="잘못된 요청 (취소 불가 상태 또는 작성자 아님)", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="문서를 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function cancel() {}
 }
diff --git a/app/Swagger/v1/DocumentTemplateApi.php b/app/Swagger/v1/DocumentTemplateApi.php
new file mode 100644
index 0000000..2471ab0
--- /dev/null
+++ b/app/Swagger/v1/DocumentTemplateApi.php
@@ -0,0 +1,194 @@
+<?php
+
+namespace App\Swagger\v1;
+
+/**
+ * @OA\Tag(name="DocumentTemplates", description="문서 양식(템플릿) 관리")
+ *
+ * @OA\Schema(
+ *     schema="DocumentTemplate",
+ *     type="object",
+ *     description="문서 양식 정보",
+ *
+ *     @OA\Property(property="id", type="integer", example=1, description="양식 ID"),
+ *     @OA\Property(property="tenant_id", type="integer", example=1, description="테넌트 ID"),
+ *     @OA\Property(property="name", type="string", example="수입검사 성적서 (EGI)", description="양식명"),
+ *     @OA\Property(property="category", type="string", example="품질", description="분류"),
+ *     @OA\Property(property="title", type="string", example="수입검사 성적서", nullable=true, description="문서 제목"),
+ *     @OA\Property(property="company_name", type="string", example="(주)SAM", nullable=true, description="회사명"),
+ *     @OA\Property(property="company_address", type="string", nullable=true, description="회사 주소"),
+ *     @OA\Property(property="company_contact", type="string", nullable=true, description="연락처"),
+ *     @OA\Property(property="footer_remark_label", type="string", example="부적합 내용", description="하단 비고 라벨"),
+ *     @OA\Property(property="footer_judgement_label", type="string", example="종합판정", description="하단 판정 라벨"),
+ *     @OA\Property(property="footer_judgement_options", type="array", nullable=true, description="판정 옵션",
+ *         @OA\Items(type="string", example="적합")
+ *     ),
+ *     @OA\Property(property="is_active", type="boolean", example=true, description="활성 여부"),
+ *     @OA\Property(property="approval_lines", type="array", description="결재라인",
+ *         @OA\Items(ref="#/components/schemas/DocumentTemplateApprovalLine")
+ *     ),
+ *     @OA\Property(property="basic_fields", type="array", description="기본 필드",
+ *         @OA\Items(ref="#/components/schemas/DocumentTemplateBasicField")
+ *     ),
+ *     @OA\Property(property="sections", type="array", description="검사 기준서 섹션",
+ *         @OA\Items(ref="#/components/schemas/DocumentTemplateSection")
+ *     ),
+ *     @OA\Property(property="columns", type="array", description="테이블 컬럼",
+ *         @OA\Items(ref="#/components/schemas/DocumentTemplateColumn")
+ *     ),
+ *     @OA\Property(property="created_at", type="string", format="date-time", example="2026-01-28T09:00:00Z"),
+ *     @OA\Property(property="updated_at", type="string", format="date-time", example="2026-01-28T09:00:00Z")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="DocumentTemplateApprovalLine",
+ *     type="object",
+ *     description="양식 결재라인",
+ *
+ *     @OA\Property(property="id", type="integer", example=1),
+ *     @OA\Property(property="template_id", type="integer", example=1),
+ *     @OA\Property(property="name", type="string", example="작성", description="결재자 이름/직책"),
+ *     @OA\Property(property="dept", type="string", example="품질", nullable=true, description="부서"),
+ *     @OA\Property(property="role", type="string", example="작성", description="역할"),
+ *     @OA\Property(property="sort_order", type="integer", example=1, description="정렬 순서")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="DocumentTemplateBasicField",
+ *     type="object",
+ *     description="양식 기본 필드",
+ *
+ *     @OA\Property(property="id", type="integer", example=1),
+ *     @OA\Property(property="template_id", type="integer", example=1),
+ *     @OA\Property(property="label", type="string", example="품명", description="필드 라벨"),
+ *     @OA\Property(property="field_type", type="string", example="text", description="필드 타입"),
+ *     @OA\Property(property="default_value", type="string", example="", nullable=true, description="기본값"),
+ *     @OA\Property(property="sort_order", type="integer", example=1, description="정렬 순서")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="DocumentTemplateSection",
+ *     type="object",
+ *     description="양식 검사 기준서 섹션",
+ *
+ *     @OA\Property(property="id", type="integer", example=1),
+ *     @OA\Property(property="template_id", type="integer", example=1),
+ *     @OA\Property(property="title", type="string", example="검사항목", description="섹션 제목"),
+ *     @OA\Property(property="image_path", type="string", example="/img/inspection/screen_inspection.jpg", nullable=true, description="검사 기준 이미지"),
+ *     @OA\Property(property="sort_order", type="integer", example=1, description="정렬 순서"),
+ *     @OA\Property(property="items", type="array", description="검사항목",
+ *         @OA\Items(ref="#/components/schemas/DocumentTemplateSectionItem")
+ *     )
+ * )
+ *
+ * @OA\Schema(
+ *     schema="DocumentTemplateSectionItem",
+ *     type="object",
+ *     description="양식 검사항목",
+ *
+ *     @OA\Property(property="id", type="integer", example=1),
+ *     @OA\Property(property="section_id", type="integer", example=1),
+ *     @OA\Property(property="category", type="string", example="외관", nullable=true, description="항목 분류"),
+ *     @OA\Property(property="item", type="string", example="표면 스크래치", description="검사항목"),
+ *     @OA\Property(property="standard", type="string", example="스크래치 없을 것", nullable=true, description="검사기준"),
+ *     @OA\Property(property="method", type="string", example="육안검사", nullable=true, description="검사방식"),
+ *     @OA\Property(property="frequency", type="string", example="전수", nullable=true, description="검사주기"),
+ *     @OA\Property(property="regulation", type="string", nullable=true, description="관련 규격"),
+ *     @OA\Property(property="sort_order", type="integer", example=1, description="정렬 순서")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="DocumentTemplateColumn",
+ *     type="object",
+ *     description="양식 테이블 컬럼",
+ *
+ *     @OA\Property(property="id", type="integer", example=1),
+ *     @OA\Property(property="template_id", type="integer", example=1),
+ *     @OA\Property(property="label", type="string", example="1차", description="컬럼 라벨"),
+ *     @OA\Property(property="width", type="string", example="80px", nullable=true, description="컬럼 너비"),
+ *     @OA\Property(property="column_type", type="string", example="check", enum={"text","check","complex","select","measurement"}, description="컬럼 타입"),
+ *     @OA\Property(property="group_name", type="string", example="측정치", nullable=true, description="그룹명"),
+ *     @OA\Property(property="sub_labels", type="array", nullable=true, description="하위 라벨 (complex 타입)",
+ *         @OA\Items(type="string", example="n1")
+ *     ),
+ *     @OA\Property(property="sort_order", type="integer", example=1, description="정렬 순서")
+ * )
+ */
+class DocumentTemplateApi
+{
+    /**
+     * @OA\Get(
+     *     path="/api/v1/document-templates",
+     *     tags={"DocumentTemplates"},
+     *     summary="양식 목록 조회",
+     *     description="문서 양식(템플릿) 목록을 조회합니다. 결재라인과 기본필드를 포함합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="is_active", in="query", description="활성 상태 필터", @OA\Schema(type="boolean")),
+     *     @OA\Parameter(name="category", in="query", description="카테고리 필터", @OA\Schema(type="string", example="품질")),
+     *     @OA\Parameter(name="search", in="query", description="검색어 (양식명, 제목)", @OA\Schema(type="string")),
+     *     @OA\Parameter(name="sort_by", in="query", description="정렬 기준", @OA\Schema(type="string", enum={"created_at","name","category"}, default="created_at")),
+     *     @OA\Parameter(name="sort_dir", in="query", description="정렬 방향", @OA\Schema(type="string", enum={"asc","desc"}, default="desc")),
+     *     @OA\Parameter(ref="#/components/parameters/Page"),
+     *     @OA\Parameter(ref="#/components/parameters/Size"),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="조회 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(
+     *                         property="data",
+     *                         type="object",
+     *                         @OA\Property(property="current_page", type="integer", example=1),
+     *                         @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/DocumentTemplate")),
+     *                         @OA\Property(property="per_page", type="integer", example=20),
+     *                         @OA\Property(property="total", type="integer", example=10)
+     *                     )
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=400, description="잘못된 요청", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function index() {}
+
+    /**
+     * @OA\Get(
+     *     path="/api/v1/document-templates/{id}",
+     *     tags={"DocumentTemplates"},
+     *     summary="양식 상세 조회",
+     *     description="ID 기준 양식 상세 정보를 조회합니다. 결재라인, 기본필드, 섹션(검사항목 포함), 컬럼 전체를 반환합니다.",
+     *     security={{"ApiKeyAuth":{}},{"BearerAuth":{}}},
+     *
+     *     @OA\Parameter(name="id", in="path", required=true, description="양식 ID", @OA\Schema(type="integer", example=7)),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="조회 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/DocumentTemplate"))
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=404, description="양식을 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function show() {}
+}
\ No newline at end of file
diff --git a/routes/api/v1/documents.php b/routes/api/v1/documents.php
index ff1de56..f28f438 100644
--- a/routes/api/v1/documents.php
+++ b/routes/api/v1/documents.php
@@ -3,13 +3,22 @@
 /**
  * 문서 관리 API 라우트 (v1)
  *
+ * - 문서 양식(템플릿) 조회
  * - 문서 CRUD
- * - 결재 워크플로우 (보류 - 기존 시스템 연동 필요)
+ * - 결재 워크플로우
  */
 
 use App\Http\Controllers\Api\V1\Documents\DocumentController;
+use App\Http\Controllers\Api\V1\Documents\DocumentTemplateController;
 use Illuminate\Support\Facades\Route;
 
+// 문서 양식(템플릿) - 읽기 전용
+Route::prefix('document-templates')->group(function () {
+    Route::get('/', [DocumentTemplateController::class, 'index'])->name('v1.document-templates.index');
+    Route::get('/{id}', [DocumentTemplateController::class, 'show'])->whereNumber('id')->name('v1.document-templates.show');
+});
+
+// 문서 CRUD + 결재
 Route::prefix('documents')->group(function () {
     // 문서 CRUD
     Route::get('/', [DocumentController::class, 'index'])->name('v1.documents.index');
@@ -18,9 +27,9 @@
     Route::patch('/{id}', [DocumentController::class, 'update'])->whereNumber('id')->name('v1.documents.update');
     Route::delete('/{id}', [DocumentController::class, 'destroy'])->whereNumber('id')->name('v1.documents.destroy');
 
-    // 결재 워크플로우 (보류 - 기존 시스템 연동 필요)
-    // Route::post('/{id}/submit', [DocumentController::class, 'submit'])->name('v1.documents.submit');
-    // Route::post('/{id}/approve', [DocumentController::class, 'approve'])->name('v1.documents.approve');
-    // Route::post('/{id}/reject', [DocumentController::class, 'reject'])->name('v1.documents.reject');
-    // Route::post('/{id}/cancel', [DocumentController::class, 'cancel'])->name('v1.documents.cancel');
-});
+    // 결재 워크플로우
+    Route::post('/{id}/submit', [DocumentController::class, 'submit'])->whereNumber('id')->name('v1.documents.submit');
+    Route::post('/{id}/approve', [DocumentController::class, 'approve'])->whereNumber('id')->name('v1.documents.approve');
+    Route::post('/{id}/reject', [DocumentController::class, 'reject'])->whereNumber('id')->name('v1.documents.reject');
+    Route::post('/{id}/cancel', [DocumentController::class, 'cancel'])->whereNumber('id')->name('v1.documents.cancel');
+});
\ No newline at end of file