From 8d2d467bd86c811badd60d74cf72c4d58af54a6b Mon Sep 17 00:00:00 2001
From: zhi <zhi@dev.hangman-lab.top>
Date: Mon, 30 Mar 2026 06:45:21 +0000
Subject: [PATCH] BE-PR-005: Add Essential schema definitions
 (create/update/response) and ProposalDetailResponse with nested essentials

---
 app/schemas/schemas.py | 51 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/app/schemas/schemas.py b/app/schemas/schemas.py
index 6d84533..40ccd97 100644
--- a/app/schemas/schemas.py
+++ b/app/schemas/schemas.py
@@ -302,6 +302,57 @@ class ProposalResponse(ProposalBase):
         from_attributes = True
 
 
+# ---------------------------------------------------------------------------
+# Essential schemas (under Proposal)
+# ---------------------------------------------------------------------------
+
+class EssentialTypeEnum(str, Enum):
+    FEATURE = "feature"
+    IMPROVEMENT = "improvement"
+    REFACTOR = "refactor"
+
+
+class EssentialBase(BaseModel):
+    title: str
+    type: EssentialTypeEnum
+    description: Optional[str] = None
+
+
+class EssentialCreate(EssentialBase):
+    """Create a new Essential under a Proposal.
+
+    ``proposal_id`` is inferred from the URL path, not the body.
+    """
+    pass
+
+
+class EssentialUpdate(BaseModel):
+    title: Optional[str] = None
+    type: Optional[EssentialTypeEnum] = None
+    description: Optional[str] = None
+
+
+class EssentialResponse(EssentialBase):
+    id: int
+    essential_code: str
+    proposal_id: int
+    created_by_id: Optional[int] = None
+    created_at: datetime
+    updated_at: Optional[datetime] = None
+
+    class Config:
+        from_attributes = True
+
+
+class ProposalDetailResponse(ProposalResponse):
+    """Extended Proposal response that embeds its Essential list."""
+
+    essentials: List[EssentialResponse] = []
+
+    class Config:
+        from_attributes = True
+
+
 # Backward-compatible aliases
 ProposeStatusEnum = ProposalStatusEnum
 ProposeBase = ProposalBase