refactor(contract): 完善请求和响应注释，以及可用性

alien_contract/api/router.py

@@ -1,4 +1,4 @@
-from typing import Union
+from typing import Union, Literal
 
 from fastapi import APIRouter, Depends, Query
 
@@ -34,7 +34,7 @@ async def create_bundle(
 
 @router.get("/bundles", response_model=PaginatedBundleResponse)
 async def list_bundles(
-    subject_type: str = Query(...),
+    subject_type: Literal["store", "lawyer"] = Query(...),
     subject_id: int = Query(..., gt=0),
     page: int = Query(1, ge=1),
     page_size: int = Query(10, ge=1, le=100),

alien_contract/repositories/contract_repo.py

@@ -120,11 +120,11 @@ class ContractRepository:
         result = await self.db.execute(stmt)
         statuses = [row[0] for row in result.fetchall()]
         if not statuses:
-            status = "pending"
+            status = "pending"  # 所有合同都未签成功
         elif all(s == 1 for s in statuses):
-            status = "all_signed"
+            status = "all_signed"  # 所有合同都已签成功
         elif any(s == 1 for s in statuses):
-            status = "partially_signed"
+            status = "partially_signed"  # 有合同已签成功
         else:
             status = "pending"
         update_stmt = ContractBundle.__table__.update().where(ContractBundle.id == bundle_id).values(status=status)

alien_contract/schemas/request/contract.py

@@ -3,6 +3,8 @@ from typing import Literal
 
 from pydantic import BaseModel, Field, field_validator
 
+BundleType = Literal["STORE_STANDARD", "LAWYER_STANDARD"]
+
 
 class BundleCreateRequest(BaseModel):
     subject_type: Literal["store", "lawyer"] = Field(description="主体类型")
@@ -12,7 +14,7 @@ class BundleCreateRequest(BaseModel):
     contact_name: str = Field(description="联系人姓名")
     contact_phone: str = Field(description="联系电话")
     ord_id: str = Field(description="统一社会信用代码")
-    bundle_type: str | None = Field(default=None, description="合同包类型")  # LAWYER_STANDARD/STORE_STANDARD
+    bundle_type: BundleType | None = Field(default=None, description="合同包类型，支持 STORE_STANDARD 或 LAWYER_STANDARD")
 
     @field_validator("contact_phone")
     @classmethod

alien_contract/schemas/response/contract.py

@@ -1,67 +1,67 @@
 from datetime import datetime
 from typing import Optional, List, Any
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class ContractDocumentResponse(BaseModel):
-    id: int
-    contract_type: str
-    contract_name: str
-    is_primary: int
-    status: int
-    sign_flow_id: str
-    file_id: str
-    template_url: str
-    sign_url: str
-    download_url: str
-    signing_time: Optional[datetime] = None
-    effective_time: Optional[datetime] = None
-    expiry_time: Optional[datetime] = None
+    id: int = Field(description="合同文档ID")
+    contract_type: str = Field(description="合同类型编码")
+    contract_name: str = Field(description="合同名称")
+    is_primary: int = Field(description="是否主合同，1是0否")
+    status: int = Field(description="签署状态，0未签1已签")
+    sign_flow_id: str = Field(description="e签宝签署流程ID")
+    file_id: str = Field(description="e签宝文件ID")
+    template_url: str = Field(description="合同模板文件链接")
+    sign_url: str = Field(description="签署链接")
+    download_url: str = Field(description="已签文件下载链接")
+    signing_time: Optional[datetime] = Field(default=None, description="签署时间")
+    effective_time: Optional[datetime] = Field(default=None, description="生效时间")
+    expiry_time: Optional[datetime] = Field(default=None, description="到期时间")
 
 
 class ContractBundleResponse(BaseModel):
-    id: int
-    subject_type: str
-    subject_id: int
-    subject_name: str
-    business_segment: str
-    contact_name: str
-    contact_phone: str
-    ord_id: str
-    bundle_type: str
-    status: str
-    primary_document_id: Optional[int] = None
-    documents: List[ContractDocumentResponse]
+    id: int = Field(description="合同包ID")
+    subject_type: str = Field(description="主体类型，store或lawyer")
+    subject_id: int = Field(description="主体ID")
+    subject_name: str = Field(description="主体名称")
+    business_segment: str = Field(description="业务板块")
+    contact_name: str = Field(description="联系人姓名")
+    contact_phone: str = Field(description="联系人手机号")
+    ord_id: str = Field(description="统一社会信用代码")
+    bundle_type: str = Field(description="合同包类型")
+    status: str = Field(description="合同包状态")
+    primary_document_id: Optional[int] = Field(default=None, description="主合同文档ID")
+    documents: List[ContractDocumentResponse] = Field(description="合同文档列表")
 
 
 class BundleCreateResponse(BaseModel):
-    success: bool
-    message: str
-    bundle_id: Optional[int] = None
-    primary_sign_flow_id: Optional[str] = None
-    created_contracts: Optional[List[dict]] = None
+    success: bool = Field(description="是否成功")
+    message: str = Field(description="响应消息")
+    bundle_id: Optional[int] = Field(default=None, description="合同包ID")
+    primary_sign_flow_id: Optional[str] = Field(default=None, description="主合同签署流程ID")
+    created_contracts: Optional[List[dict]] = Field(default=None, description="本次创建的合同列表")
 
 
 class ErrorResponse(BaseModel):
-    success: bool = False
-    message: str
-    raw: Optional[Any] = None
+    success: bool = Field(default=False, description="是否成功")
+    message: str = Field(description="错误消息")
+    raw: Optional[Any] = Field(default=None, description="原始错误数据")
 
 
 class SuccessResponse(BaseModel):
-    code: str
-    msg: str
+    code: str = Field(description="响应代码")
+    msg: str = Field(description="响应消息")
 
 
 class PaginatedBundleResponse(BaseModel):
-    items: List[ContractBundleResponse]
-    total: int
-    page: int
-    page_size: int
-    total_pages: int
+    items: List[ContractBundleResponse] = Field(description="合同包列表")
+    total: int = Field(description="总记录数")
+    page: int = Field(description="当前页码")
+    page_size: int = Field(description="每页条数")
+    total_pages: int = Field(description="总页数")
 
 
 class ModuleStatusResponse(BaseModel):
-    module: str
-    status: str
+    module: str = Field(description="模块名称")
+    status: str = Field(description="模块状态")