feat: 활동증명서 렌더링(PDF) + 운영진 초안 생성

Author: youngunghan

.env.example

@@ -34,3 +34,9 @@ OCI_PUBLIC_BASE_URL=
 # AWS Secrets Manager (for dev/prod environments)
 # AWS_SECRET_NAME=waffice-db-credentials
 # AWS_REGION=ap-northeast-2
+
+# Certificate of activities (활동증명서)
+# Base URL used to build the 원본 확인(verification) link embedded in issued PDFs:
+# "{CERT_VERIFY_BASE_URL}/verify/{issue_number}". The /verify endpoint itself is
+# out of scope for this PR; only the link is rendered.
+CERT_VERIFY_BASE_URL=https://waffice.wafflestudio.com

.github/workflows/ci.yml

@@ -19,6 +19,18 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v4
 
+      - name: Install WeasyPrint system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libpango-1.0-0 \
+            libpangoft2-1.0-0 \
+            libcairo2 \
+            libgdk-pixbuf-2.0-0 \
+            libffi8 \
+            shared-mime-info \
+            fonts-noto-cjk
+
       - name: Install dependencies
         run: uv sync --dev
 

Dockerfile

@@ -21,6 +21,19 @@ FROM python:3.11-slim
 # Set working directory
 WORKDIR /app
 
+# System libraries required by WeasyPrint (활동증명서 PDF 렌더링) at runtime,
+# plus a Korean-capable font so Korean text in the PDF doesn't render as tofu.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        libpango-1.0-0 \
+        libpangoft2-1.0-0 \
+        libcairo2 \
+        libgdk-pixbuf-2.0-0 \
+        libffi8 \
+        shared-mime-info \
+        fonts-noto-cjk \
+    && rm -rf /var/lib/apt/lists/*
+
 # Install uv in runtime (needed to run the app)
 RUN pip install --no-cache-dir uv
 

alembic/versions/e2f3a4b5c6d7_add_certificates_and_events.py

@@ -0,0 +1,141 @@
+"""add certificates and events
+
+Adds the certificates (the issuance/draft records) and certificate_events
+(append-only processing history) tables. This builds on top of the
+president_terms/certificate_signatures tables added by
+d1e2f3a4b5c6_add_president_terms_and_signatures.py.
+
+Revision ID: e2f3a4b5c6d7
+Revises: d1e2f3a4b5c6
+Create Date: 2026-07-19 00:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import mysql
+
+from alembic import op
+
+revision: str = "e2f3a4b5c6d7"
+down_revision: Union[str, None] = "d1e2f3a4b5c6"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "certificates",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("requested_by_id", sa.Integer(), nullable=True),
+        sa.Column(
+            "kind",
+            sa.Enum("SELF", "DRAFT", name="certificatekind"),
+            nullable=False,
+        ),
+        sa.Column(
+            "status",
+            sa.Enum("ISSUED", "ORIGINAL_PENDING", name="certificatestatus"),
+            nullable=False,
+        ),
+        # 운영진용 발급 이력(list_history) 정렬 우선순위 생성 컬럼(ORIGINAL_
+        # PENDING -> 1, 아니면 0). president_terms.is_current와 같은 패턴.
+        sa.Column(
+            "pending_priority",
+            mysql.TINYINT(),
+            sa.Computed("IF(status = 'ORIGINAL_PENDING', 1, 0)", persisted=False),
+            nullable=False,
+        ),
+        sa.Column("issue_number", sa.CHAR(length=36), nullable=True),
+        sa.Column("verification_token_hash", sa.String(length=64), nullable=True),
+        sa.Column("options", sa.JSON(), nullable=False),
+        sa.Column("snapshot", sa.JSON(), nullable=True),
+        sa.Column("pdf_object_key", sa.String(length=500), nullable=True),
+        sa.Column("issued_at", sa.BigInteger(), nullable=True),
+        sa.Column("expires_at", sa.BigInteger(), nullable=True),
+        sa.Column("created_at", sa.BigInteger(), nullable=False),
+        sa.Column("updated_at", sa.BigInteger(), nullable=False),
+        sa.Column("deleted_at", sa.BigInteger(), nullable=True),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["requested_by_id"], ["users.id"], ondelete="SET NULL"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("issue_number", name="uq_certificates_issue_number"),
+    )
+    # list_own의 WHERE user_id = ? ORDER BY created_at DESC, id DESC (+ 동일
+    # 형태의 커서 술어)를 그대로 커버한다. user_id가 최좌측 컬럼이므로
+    # user_id FK가 요구하는 커버 인덱스 역할도 대신한다.
+    op.create_index(
+        "idx_certificates_user_created_id",
+        "certificates",
+        ["user_id", "created_at", "id"],
+        unique=False,
+    )
+    # list_history의 ORDER BY pending_priority DESC, created_at DESC, id DESC
+    # (+ 동일 형태의 커서 술어)를 그대로 커버한다.
+    op.create_index(
+        "idx_certificates_history_priority",
+        "certificates",
+        ["pending_priority", "created_at", "id"],
+        unique=False,
+    )
+    op.create_index(
+        "idx_certificates_created_at", "certificates", ["created_at"], unique=False
+    )
+
+    op.create_table(
+        "certificate_events",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("certificate_id", sa.Integer(), nullable=False),
+        sa.Column(
+            "action",
+            sa.Enum(
+                "APPLIED",
+                "ISSUED",
+                "DRAFT_CREATED",
+                "ORIGINAL_REGISTERED",
+                name="certificateeventaction",
+            ),
+            nullable=False,
+        ),
+        sa.Column(
+            "actor_type",
+            sa.Enum(
+                "APPLICANT",
+                "SYSTEM",
+                "PRESIDENT",
+                "ADMIN",
+                name="certificateactortype",
+            ),
+            nullable=False,
+        ),
+        sa.Column("actor_id", sa.Integer(), nullable=True),
+        sa.Column("created_at", sa.BigInteger(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["certificate_id"], ["certificates.id"], ondelete="CASCADE"
+        ),
+        sa.ForeignKeyConstraint(["actor_id"], ["users.id"], ondelete="SET NULL"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "idx_certificate_events_certificate_created",
+        "certificate_events",
+        ["certificate_id", "created_at"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    # NOTE: idx_certificate_events_certificate_created and
+    # idx_certificates_user_created_id (user_id가 최좌측 컬럼이므로 여전히
+    # user_id FK를 커버한다) are each the *only* index covering their table's
+    # FK column, so MySQL rejects an explicit DROP INDEX on them while the FK
+    # constraint is still attached (error 1553). drop_table removes a table's
+    # FKs and indexes together, so those two are intentionally left for
+    # drop_table to clean up rather than dropped explicitly first.
+    op.drop_table("certificate_events")
+
+    op.drop_index("idx_certificates_created_at", table_name="certificates")
+    op.drop_index("idx_certificates_history_priority", table_name="certificates")
+    op.drop_table("certificates")

app/deps/__init__.py

@@ -2,6 +2,7 @@
     get_current_user,
     require_admin,
     require_associate,
+    require_certificate_eligible,
     require_president,
     require_regular,
 )
@@ -12,6 +13,7 @@
     "require_associate",
     "require_regular",
     "require_admin",
+    "require_certificate_eligible",
     "require_president",
     "require_leader_or_admin",
 ]

app/deps/auth.py

@@ -6,7 +6,7 @@
 from app.config.cookies import ACCESS_TOKEN_COOKIE_NAME
 from app.config.database import get_db
 from app.config.secrets import JWT_SECRET_KEY
-from app.exceptions import NotPresidentError
+from app.exceptions import AssociateCannotIssueCertificateError, NotPresidentError
 from app.models import Qualification, User
 from app.services import UserService
 from app.services.certificate import PresidentService
@@ -105,6 +105,23 @@ async def require_admin(user: User = Depends(get_current_user)) -> User:
     return user
 
 
+async def require_certificate_eligible(
+    user: User = Depends(get_current_user),
+) -> User:
+    """
+    활동증명서 발급 대상 자격 확인: 정회원/활동회원만 가능.
+
+    준회원(이하)은 `ASSOCIATE_CANNOT_ISSUE_CERTIFICATE`(403, AppError)로 거부한다.
+    기존 `require_regular`는 영어 HTTPException을 던지지만, 활동증명서 API는
+    명세가 요구하는 전용 에러 코드/한국어 메시지를 응답 바디에 실어야 하므로
+    (`{"ok": false, "error": "ASSOCIATE_CANNOT_ISSUE_CERTIFICATE", ...}`)
+    `app.exceptions.AppError`를 그대로 raise한다.
+    """
+    if user.qualification not in (Qualification.REGULAR, Qualification.ACTIVE):
+        raise AssociateCannotIssueCertificateError()
+    return user
+
+
 async def require_president(
     user: User = Depends(get_current_user), db: Session = Depends(get_db)
 ) -> User:

app/exceptions.py

@@ -225,3 +225,41 @@ class SignatureUploadConflictError(AppError):
 
     def __init__(self, message: str = "다른 서명 등록 요청과 충돌했습니다. 다시 시도해주세요."):
         super().__init__("SIGNATURE_UPLOAD_CONFLICT", message, 409)
+
+
+class AssociateCannotIssueCertificateError(AppError):
+    """403 - Associate-level members cannot issue certificates of activities"""
+
+    def __init__(self, message: str = "준회원은 활동증명서를 발급받을 수 없습니다."):
+        super().__init__("ASSOCIATE_CANNOT_ISSUE_CERTIFICATE", message, 403)
+
+
+class PresidentNotFoundError(AppError):
+    """409 - No current president is registered"""
+
+    def __init__(self, message: str = "현재 등록된 회장이 없습니다. 운영팀에 문의해주세요."):
+        super().__init__("PRESIDENT_NOT_FOUND", message, 409)
+
+
+class PresidentSignatureNotFoundError(AppError):
+    """409 - The current president has no registered signature"""
+
+    def __init__(
+        self,
+        message: str = "회장의 서명을 찾을 수 없습니다. 운영팀에 에러를 신고해주세요!",
+    ):
+        super().__init__("PRESIDENT_SIGNATURE_NOT_FOUND", message, 409)
+
+
+class InvalidCertificateOptionsError(AppError):
+    """400 - Certificate options failed validation (message varies by cause)"""
+
+    def __init__(self, message: str = "발급 옵션이 올바르지 않습니다."):
+        super().__init__("INVALID_CERTIFICATE_OPTIONS", message, 400)
+
+
+class CertificateRenderFailedError(AppError):
+    """502 - PDF rendering failed"""
+
+    def __init__(self, message: str = "활동증명서 생성에 실패했습니다."):
+        super().__init__("CERTIFICATE_RENDER_FAILED", message, 502)

app/models/__init__.py

@@ -1,9 +1,14 @@
 from app.models.audit_log import AuditLog
-from app.models.certificate import CertificateSignature
+from app.models.certificate import Certificate, CertificateEvent, CertificateSignature
 from app.models.enums import (
     ActivityStatus,
     ApprovalStatus,
     AuditAction,
+    CertificateActorType,
+    CertificateEventAction,
+    CertificateKind,
+    CertificateSigner,
+    CertificateStatus,
     GraduationStatus,
     MemberRole,
     ProjectStatus,
@@ -35,4 +40,11 @@
     "RequestReviewer",
     "PresidentTerm",
     "CertificateSignature",
+    "Certificate",
+    "CertificateEvent",
+    "CertificateKind",
+    "CertificateStatus",
+    "CertificateEventAction",
+    "CertificateActorType",
+    "CertificateSigner",
 ]