feat: 문서 관리 시스템 모델 생성 (Phase 1.2)

- Document 모델 (상태 관리, 다형성 연결, 결재 처리) - DocumentApproval 모델 (결재 단계, 상태 처리) - DocumentData 모델 (EAV 패턴 데이터 저장) - DocumentAttachment 모델 (파일 첨부 연결) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-28 19:57:22 +09:00
parent c7b2e97189
commit 2bce30056d
4 changed files with 675 additions and 0 deletions
--- a/app/Models/Documents/Document.php
+++ b/app/Models/Documents/Document.php
@@ -0,0 +1,246 @@
+<?php
+
+namespace App\Models\Documents;
+
+use App\Models\Members\User;
+use App\Traits\BelongsToTenant;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+/**
+ * 문서 모델
+ *
+ * @property int $id
+ * @property int $tenant_id
+ * @property int $template_id
+ * @property string $document_no 문서번호
+ * @property string $title 문서 제목
+ * @property string $status 상태 (DRAFT/PENDING/APPROVED/REJECTED/CANCELLED)
+ * @property string|null $linkable_type 연결 모델 타입
+ * @property int|null $linkable_id 연결 모델 ID
+ * @property \Carbon\Carbon|null $submitted_at 결재 요청일
+ * @property \Carbon\Carbon|null $completed_at 결재 완료일
+ * @property int|null $created_by
+ * @property int|null $updated_by
+ * @property int|null $deleted_by
+ * @property \Carbon\Carbon|null $created_at
+ * @property \Carbon\Carbon|null $updated_at
+ * @property \Carbon\Carbon|null $deleted_at
+ */
+class Document extends Model
+{
+    use BelongsToTenant, SoftDeletes;
+
+    protected $table = 'documents';
+
+    // =========================================================================
+    // 상태 상수
+    // =========================================================================
+
+    public const STATUS_DRAFT = 'DRAFT';
+
+    public const STATUS_PENDING = 'PENDING';
+
+    public const STATUS_APPROVED = 'APPROVED';
+
+    public const STATUS_REJECTED = 'REJECTED';
+
+    public const STATUS_CANCELLED = 'CANCELLED';
+
+    public const STATUSES = [
+        self::STATUS_DRAFT,
+        self::STATUS_PENDING,
+        self::STATUS_APPROVED,
+        self::STATUS_REJECTED,
+        self::STATUS_CANCELLED,
+    ];
+
+    // =========================================================================
+    // Fillable & Casts
+    // =========================================================================
+
+    protected $fillable = [
+        'tenant_id',
+        'template_id',
+        'document_no',
+        'title',
+        'status',
+        'linkable_type',
+        'linkable_id',
+        'submitted_at',
+        'completed_at',
+        'created_by',
+        'updated_by',
+        'deleted_by',
+    ];
+
+    protected $casts = [
+        'submitted_at' => 'datetime',
+        'completed_at' => 'datetime',
+    ];
+
+    protected $attributes = [
+        'status' => self::STATUS_DRAFT,
+    ];
+
+    // =========================================================================
+    // Relationships
+    // =========================================================================
+
+    /**
+     * 템플릿
+     */
+    public function template(): BelongsTo
+    {
+        return $this->belongsTo(\App\Models\DocumentTemplate::class, 'template_id');
+    }
+
+    /**
+     * 결재 목록
+     */
+    public function approvals(): HasMany
+    {
+        return $this->hasMany(DocumentApproval::class)->orderBy('step');
+    }
+
+    /**
+     * 문서 데이터
+     */
+    public function data(): HasMany
+    {
+        return $this->hasMany(DocumentData::class);
+    }
+
+    /**
+     * 첨부파일
+     */
+    public function attachments(): HasMany
+    {
+        return $this->hasMany(DocumentAttachment::class);
+    }
+
+    /**
+     * 연결된 엔티티 (다형성)
+     */
+    public function linkable(): MorphTo
+    {
+        return $this->morphTo();
+    }
+
+    /**
+     * 생성자
+     */
+    public function creator(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'created_by');
+    }
+
+    /**
+     * 수정자
+     */
+    public function updater(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'updated_by');
+    }
+
+    // =========================================================================
+    // Scopes
+    // =========================================================================
+
+    /**
+     * 상태로 필터링
+     */
+    public function scopeStatus($query, string $status)
+    {
+        return $query->where('status', $status);
+    }
+
+    /**
+     * 임시저장 문서
+     */
+    public function scopeDraft($query)
+    {
+        return $query->where('status', self::STATUS_DRAFT);
+    }
+
+    /**
+     * 결재 대기 문서
+     */
+    public function scopePending($query)
+    {
+        return $query->where('status', self::STATUS_PENDING);
+    }
+
+    /**
+     * 승인된 문서
+     */
+    public function scopeApproved($query)
+    {
+        return $query->where('status', self::STATUS_APPROVED);
+    }
+
+    // =========================================================================
+    // Helper Methods
+    // =========================================================================
+
+    /**
+     * 편집 가능 여부
+     */
+    public function canEdit(): bool
+    {
+        return $this->status === self::STATUS_DRAFT
+            || $this->status === self::STATUS_REJECTED;
+    }
+
+    /**
+     * 결재 요청 가능 여부
+     */
+    public function canSubmit(): bool
+    {
+        return $this->status === self::STATUS_DRAFT
+            || $this->status === self::STATUS_REJECTED;
+    }
+
+    /**
+     * 결재 처리 가능 여부
+     */
+    public function canApprove(): bool
+    {
+        return $this->status === self::STATUS_PENDING;
+    }
+
+    /**
+     * 취소 가능 여부
+     */
+    public function canCancel(): bool
+    {
+        return in_array($this->status, [
+            self::STATUS_DRAFT,
+            self::STATUS_PENDING,
+        ]);
+    }
+
+    /**
+     * 현재 결재 단계 가져오기
+     */
+    public function getCurrentApprovalStep(): ?DocumentApproval
+    {
+        return $this->approvals()
+            ->where('status', DocumentApproval::STATUS_PENDING)
+            ->orderBy('step')
+            ->first();
+    }
+
+    /**
+     * 특정 사용자의 결재 차례 확인
+     */
+    public function isUserTurn(int $userId): bool
+    {
+        $currentStep = $this->getCurrentApprovalStep();
+
+        return $currentStep && $currentStep->user_id === $userId;
+    }
+}
--- a/app/Models/Documents/DocumentApproval.php
+++ b/app/Models/Documents/DocumentApproval.php
@@ -0,0 +1,180 @@
+<?php
+
+namespace App\Models\Documents;
+
+use App\Models\Members\User;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * 문서 결재 모델
+ *
+ * @property int $id
+ * @property int $document_id
+ * @property int $user_id
+ * @property int $step 결재 순서
+ * @property string $role 역할 (작성/검토/승인)
+ * @property string $status 상태 (PENDING/APPROVED/REJECTED)
+ * @property string|null $comment 결재 의견
+ * @property \Carbon\Carbon|null $acted_at 결재 처리일
+ * @property int|null $created_by
+ * @property int|null $updated_by
+ * @property \Carbon\Carbon|null $created_at
+ * @property \Carbon\Carbon|null $updated_at
+ */
+class DocumentApproval extends Model
+{
+    protected $table = 'document_approvals';
+
+    // =========================================================================
+    // 상태 상수
+    // =========================================================================
+
+    public const STATUS_PENDING = 'PENDING';
+
+    public const STATUS_APPROVED = 'APPROVED';
+
+    public const STATUS_REJECTED = 'REJECTED';
+
+    public const STATUSES = [
+        self::STATUS_PENDING,
+        self::STATUS_APPROVED,
+        self::STATUS_REJECTED,
+    ];
+
+    // =========================================================================
+    // 역할 상수
+    // =========================================================================
+
+    public const ROLE_WRITER = '작성';
+
+    public const ROLE_REVIEWER = '검토';
+
+    public const ROLE_APPROVER = '승인';
+
+    // =========================================================================
+    // Fillable & Casts
+    // =========================================================================
+
+    protected $fillable = [
+        'document_id',
+        'user_id',
+        'step',
+        'role',
+        'status',
+        'comment',
+        'acted_at',
+        'created_by',
+        'updated_by',
+    ];
+
+    protected $casts = [
+        'step' => 'integer',
+        'acted_at' => 'datetime',
+    ];
+
+    protected $attributes = [
+        'step' => 1,
+        'status' => self::STATUS_PENDING,
+    ];
+
+    // =========================================================================
+    // Relationships
+    // =========================================================================
+
+    /**
+     * 문서
+     */
+    public function document(): BelongsTo
+    {
+        return $this->belongsTo(Document::class);
+    }
+
+    /**
+     * 결재자
+     */
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    /**
+     * 생성자
+     */
+    public function creator(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'created_by');
+    }
+
+    // =========================================================================
+    // Scopes
+    // =========================================================================
+
+    /**
+     * 대기 중인 결재
+     */
+    public function scopePending($query)
+    {
+        return $query->where('status', self::STATUS_PENDING);
+    }
+
+    /**
+     * 승인된 결재
+     */
+    public function scopeApproved($query)
+    {
+        return $query->where('status', self::STATUS_APPROVED);
+    }
+
+    /**
+     * 반려된 결재
+     */
+    public function scopeRejected($query)
+    {
+        return $query->where('status', self::STATUS_REJECTED);
+    }
+
+    /**
+     * 특정 사용자의 결재
+     */
+    public function scopeForUser($query, int $userId)
+    {
+        return $query->where('user_id', $userId);
+    }
+
+    // =========================================================================
+    // Helper Methods
+    // =========================================================================
+
+    /**
+     * 대기 상태 여부
+     */
+    public function isPending(): bool
+    {
+        return $this->status === self::STATUS_PENDING;
+    }
+
+    /**
+     * 승인 상태 여부
+     */
+    public function isApproved(): bool
+    {
+        return $this->status === self::STATUS_APPROVED;
+    }
+
+    /**
+     * 반려 상태 여부
+     */
+    public function isRejected(): bool
+    {
+        return $this->status === self::STATUS_REJECTED;
+    }
+
+    /**
+     * 결재 처리 완료 여부
+     */
+    public function isProcessed(): bool
+    {
+        return ! $this->isPending();
+    }
+}
--- a/app/Models/Documents/DocumentAttachment.php
+++ b/app/Models/Documents/DocumentAttachment.php
@@ -0,0 +1,144 @@
+<?php
+
+namespace App\Models\Documents;
+
+use App\Models\Commons\File;
+use App\Models\Members\User;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * 문서 첨부파일 모델
+ *
+ * @property int $id
+ * @property int $document_id
+ * @property int $file_id
+ * @property string $attachment_type 첨부 유형 (general, signature, image 등)
+ * @property string|null $description 설명
+ * @property int|null $created_by
+ * @property \Carbon\Carbon|null $created_at
+ * @property \Carbon\Carbon|null $updated_at
+ */
+class DocumentAttachment extends Model
+{
+    protected $table = 'document_attachments';
+
+    // =========================================================================
+    // 첨부 유형 상수
+    // =========================================================================
+
+    public const TYPE_GENERAL = 'general';
+
+    public const TYPE_SIGNATURE = 'signature';
+
+    public const TYPE_IMAGE = 'image';
+
+    public const TYPE_REFERENCE = 'reference';
+
+    public const TYPES = [
+        self::TYPE_GENERAL,
+        self::TYPE_SIGNATURE,
+        self::TYPE_IMAGE,
+        self::TYPE_REFERENCE,
+    ];
+
+    // =========================================================================
+    // Fillable & Casts
+    // =========================================================================
+
+    protected $fillable = [
+        'document_id',
+        'file_id',
+        'attachment_type',
+        'description',
+        'created_by',
+    ];
+
+    protected $attributes = [
+        'attachment_type' => self::TYPE_GENERAL,
+    ];
+
+    // =========================================================================
+    // Relationships
+    // =========================================================================
+
+    /**
+     * 문서
+     */
+    public function document(): BelongsTo
+    {
+        return $this->belongsTo(Document::class);
+    }
+
+    /**
+     * 파일
+     */
+    public function file(): BelongsTo
+    {
+        return $this->belongsTo(File::class);
+    }
+
+    /**
+     * 생성자
+     */
+    public function creator(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'created_by');
+    }
+
+    // =========================================================================
+    // Scopes
+    // =========================================================================
+
+    /**
+     * 특정 유형의 첨부파일
+     */
+    public function scopeOfType($query, string $type)
+    {
+        return $query->where('attachment_type', $type);
+    }
+
+    /**
+     * 일반 첨부파일
+     */
+    public function scopeGeneral($query)
+    {
+        return $query->where('attachment_type', self::TYPE_GENERAL);
+    }
+
+    /**
+     * 서명 첨부파일
+     */
+    public function scopeSignatures($query)
+    {
+        return $query->where('attachment_type', self::TYPE_SIGNATURE);
+    }
+
+    /**
+     * 이미지 첨부파일
+     */
+    public function scopeImages($query)
+    {
+        return $query->where('attachment_type', self::TYPE_IMAGE);
+    }
+
+    // =========================================================================
+    // Helper Methods
+    // =========================================================================
+
+    /**
+     * 서명 첨부파일 여부
+     */
+    public function isSignature(): bool
+    {
+        return $this->attachment_type === self::TYPE_SIGNATURE;
+    }
+
+    /**
+     * 이미지 첨부파일 여부
+     */
+    public function isImage(): bool
+    {
+        return $this->attachment_type === self::TYPE_IMAGE;
+    }
+}
--- a/app/Models/Documents/DocumentData.php
+++ b/app/Models/Documents/DocumentData.php
@@ -0,0 +1,105 @@
+<?php
+
+namespace App\Models\Documents;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+/**
+ * 문서 데이터 모델 (EAV 패턴)
+ *
+ * @property int $id
+ * @property int $document_id
+ * @property int|null $section_id 섹션 ID
+ * @property int|null $column_id 컬럼 ID
+ * @property int $row_index 행 인덱스
+ * @property string $field_key 필드 키
+ * @property string|null $field_value 필드 값
+ * @property \Carbon\Carbon|null $created_at
+ * @property \Carbon\Carbon|null $updated_at
+ */
+class DocumentData extends Model
+{
+    protected $table = 'document_data';
+
+    // =========================================================================
+    // Fillable & Casts
+    // =========================================================================
+
+    protected $fillable = [
+        'document_id',
+        'section_id',
+        'column_id',
+        'row_index',
+        'field_key',
+        'field_value',
+    ];
+
+    protected $casts = [
+        'section_id' => 'integer',
+        'column_id' => 'integer',
+        'row_index' => 'integer',
+    ];
+
+    protected $attributes = [
+        'row_index' => 0,
+    ];
+
+    // =========================================================================
+    // Relationships
+    // =========================================================================
+
+    /**
+     * 문서
+     */
+    public function document(): BelongsTo
+    {
+        return $this->belongsTo(Document::class);
+    }
+
+    // =========================================================================
+    // Scopes
+    // =========================================================================
+
+    /**
+     * 특정 섹션의 데이터
+     */
+    public function scopeForSection($query, int $sectionId)
+    {
+        return $query->where('section_id', $sectionId);
+    }
+
+    /**
+     * 특정 필드 키의 데이터
+     */
+    public function scopeForField($query, string $fieldKey)
+    {
+        return $query->where('field_key', $fieldKey);
+    }
+
+    /**
+     * 특정 행의 데이터
+     */
+    public function scopeForRow($query, int $rowIndex)
+    {
+        return $query->where('row_index', $rowIndex);
+    }
+
+    // =========================================================================
+    // Helper Methods
+    // =========================================================================
+
+    /**
+     * 값을 특정 타입으로 캐스팅
+     */
+    public function getTypedValue(string $type = 'string'): mixed
+    {
+        return match ($type) {
+            'integer', 'int' => (int) $this->field_value,
+            'float', 'double' => (float) $this->field_value,
+            'boolean', 'bool' => filter_var($this->field_value, FILTER_VALIDATE_BOOLEAN),
+            'array', 'json' => json_decode($this->field_value, true),
+            default => $this->field_value,
+        };
+    }
+}