fc / apps /documents /services /template /template_service.py
jun2024's picture
Upload 2241 files
b4f2238 verified
Raw History Blame Contribute Delete
13.2 kB
"""Business logic services."""
from __future__ import annotations
import logging
from typing import Any, cast
from django.core.files.uploadedfile import UploadedFile
from django.utils.translation import gettext_lazy as _
from apps.core.exceptions import NotFoundError
from apps.core.utils.path import Path
from apps.documents.models import DocumentTemplate, Placeholder
from apps.documents.services.document_template.placeholder_extractor import (
extract_placeholders as extract_placeholders_from_file,
)
from apps.documents.services.document_template.repo import DocumentTemplateRepo
from apps.documents.services.document_template.validation_service import DocumentTemplateValidationService
from apps.documents.services.document_template.workflow import DocumentTemplateWorkflow
logger = logging.getLogger(__name__)
class DocumentTemplateService:
"""
文书模板服务
负责文书模板的创建、更新、查询、版本管理和占位符提取.
"""
def __init__(
self,
repo: DocumentTemplateRepo | None = None,
validator: DocumentTemplateValidationService | None = None,
workflow: DocumentTemplateWorkflow | None = None,
) -> None:
self._repo = repo
self._validator = validator
self._workflow = workflow
@property
def repo(self) -> DocumentTemplateRepo:
if self._repo is None:
self._repo = DocumentTemplateRepo()
return self._repo
@property
def validator(self) -> DocumentTemplateValidationService:
if self._validator is None:
self._validator = DocumentTemplateValidationService()
return self._validator
@property
def workflow(self) -> DocumentTemplateWorkflow:
if self._workflow is None:
self._workflow = DocumentTemplateWorkflow(repo=self.repo, validator=self.validator)
return self._workflow
def create_template(
self,
name: str,
template_type: str,
file: UploadedFile | None = None,
file_path: str | None = None,
description: str = "",
case_types: list[str] | None = None,
case_stages: list[str] | None = None,
contract_types: list[str] | None = None,
contract_sub_type: str | None = None,
is_active: bool = True,
) -> DocumentTemplate:
"""
创建文书模板
支持两种模式:
1. 上传模式:通过 file 参数上传文件
2. 路径引用模式:通过 file_path 指定已存在的文件路径
Args:
name: 模板名称
template_type: 模板类型
file: 上传的文件(上传模式)
file_path: 文件路径(路径引用模式)
description: 描述
case_types: 适用案件类型列表
case_stages: 适用案件阶段列表
contract_types: 适用合同类型列表
contract_sub_type: 合同子类型(仅合同模板)
is_active: 是否启用
Returns:
创建的 DocumentTemplate 实例
Raises:
ValidationException: 验证失败
Requirements: 2.1, 2.2, 2.3, 2.5
"""
template = self.workflow.create_template(
name=name,
template_type=template_type,
contract_sub_type=contract_sub_type,
file=file,
file_path=file_path,
description=description,
case_types=case_types or [],
case_stages=case_stages or [],
contract_types=contract_types or [],
is_active=is_active,
)
logger.info("创建文书模板: %s (ID: %s)", template.name, cast(int, template.pk))
return template
def update_template(
self,
template_id: int,
name: str | None = None,
template_type: str | None = None,
contract_sub_type: str | None = None,
file: UploadedFile | None = None,
file_path: str | None = None,
description: str | None = None,
case_types: list[str] | None = None,
case_stages: list[str] | None = None,
contract_types: list[str] | None = None,
is_active: bool | None = None,
created_by: Any | None = None,
) -> DocumentTemplate:
"""
更新文书模板
如果更新了文件(file 或 file_path),会自动创建版本记录.
Args:
template_id: 模板 ID
name: 新名称
template_type: 新模板类型
contract_sub_type: 新合同子类型
file: 新上传文件
file_path: 新文件路径
description: 新描述
case_types: 新适用案件类型
case_stages: 新适用案件阶段
contract_types: 新适用合同类型
is_active: 新启用状态
created_by: 版本创建人(Lawyer 实例)
Returns:
更新后的 DocumentTemplate 实例
Raises:
NotFoundError: 模板不存在
ValidationException: 验证失败
Requirements: 2.6, 2.7
"""
try:
template = self.repo.get_by_id(template_id)
except DocumentTemplate.DoesNotExist:
raise NotFoundError(
message=_("文书模板不存在"),
code="TEMPLATE_NOT_FOUND",
errors={"template_id": f"ID 为 {template_id} 的模板不存在"},
) from None
template = self.workflow.update_template(
template,
name=name,
template_type=template_type,
contract_sub_type=contract_sub_type,
file=file,
file_path=file_path,
description=description,
case_types=case_types,
case_stages=case_stages,
contract_types=contract_types,
is_active=is_active,
created_by=created_by,
)
logger.info("更新文书模板: %s (ID: %s)", template.name, cast(int, template.pk))
return template
def validate_file_path(self, file_path: str) -> Any:
"""
验证文件路径是否存在
Args:
file_path: 文件路径
Returns:
文件是否存在
Requirements: 2.5
"""
if not file_path:
return False
return self.validator.validate_file_path(file_path)
def get_full_file_path(self, template: DocumentTemplate) -> str | None:
"""
获取模板文件的完整路径
Args:
template: 文书模板实例
Returns:
完整文件路径,如果文件不存在返回 None
"""
try:
file_path = template.get_file_location()
if file_path and Path(file_path).exists():
logger.debug("模板 %s (ID: %s) 文件路径: %s", template.name, cast(int, template.pk), file_path)
return file_path
else:
logger.warning("模板 %s (ID: %s) 文件不存在: %s", template.name, cast(int, template.pk), file_path)
return None
except Exception:
logger.exception(
"get_full_file_path_failed",
extra={"template_id": cast(int, template.pk), "template_name": template.name},
)
raise
def extract_placeholders(self, template: DocumentTemplate) -> list[str]:
"""
从 docx 模板中提取所有占位符
使用 docxtpl 解析模板,提取所有 {{ xxx }} 格式的占位符.
Args:
template: 文书模板实例
Returns:
占位符键列表
Requirements: 2.9, 2.10
"""
file_path = self.get_full_file_path(template)
if not file_path:
logger.warning("模板文件不存在: %s (ID: %s)", template.name, cast(int, template.pk))
return []
try:
result = extract_placeholders_from_file(file_path)
logger.info(
"模板 %s (ID: %s) 提取到 %s 个占位符: %s", template.name, cast(int, template.pk), len(result), result
)
return result
except Exception:
logger.exception(
"extract_placeholders_failed",
extra={"template_id": cast(int, template.pk), "template_name": template.name, "file_path": file_path},
)
raise
def get_undefined_placeholders(self, template: DocumentTemplate) -> list[str]:
"""
获取模板中未定义的占位符
对比模板中的占位符和系统已注册的占位符,返回未定义的.
Args:
template: 文书模板实例
Returns:
未定义的占位符键列表
Requirements: 2.10
"""
template_placeholders = set(self.extract_placeholders(template))
if not template_placeholders:
return []
registered_keys = set(Placeholder.objects.filter(is_active=True).values_list("key", flat=True))
undefined = template_placeholders - registered_keys
return sorted(list(undefined))
def get_template_by_id(self, template_id: int) -> DocumentTemplate:
"""
根据 ID 获取模板
Args:
template_id: 模板 ID
Returns:
DocumentTemplate 实例
Raises:
NotFoundError: 模板不存在
"""
try:
return self.repo.get_by_id(template_id)
except DocumentTemplate.DoesNotExist:
raise NotFoundError(
message=_("文书模板不存在"),
code="TEMPLATE_NOT_FOUND",
errors={"template_id": f"ID 为 {template_id} 的模板不存在"},
) from None
def list_templates(
self, template_type: str | None = None, case_type: str | None = None, is_active: bool | None = None
) -> list[DocumentTemplate]:
"""
列出文书模板
Args:
template_type: 按模板类型过滤 (contract/case)
case_type: 按适用案件类型过滤
is_active: 按启用状态过滤
Returns:
DocumentTemplate 列表
"""
queryset = self.repo.all()
if template_type is not None:
queryset = queryset.filter(template_type=template_type)
if case_type is not None:
queryset = queryset.filter(case_types__contains=[case_type])
if is_active is not None:
queryset = queryset.filter(is_active=is_active)
return list(queryset)
def delete_template(self, template_id: int) -> bool:
"""
删除模板(软删除)
Args:
template_id: 模板 ID
Returns:
是否成功
Raises:
NotFoundError: 模板不存在
"""
try:
template = self.repo.get_by_id(template_id)
except DocumentTemplate.DoesNotExist:
raise NotFoundError(
message=_("文书模板不存在"),
code="TEMPLATE_NOT_FOUND",
errors={"template_id": f"ID 为 {template_id} 的模板不存在"},
) from None
template.is_active = False
template.save(update_fields=["is_active", "updated_at"])
logger.info("软删除文书模板: %s (ID: %s)", template.name, cast(int, template.pk))
return True
def create_template_from_dict(self, data: dict[str, Any]) -> DocumentTemplate:
"""
从字典数据创建文书模板
用于 API 层调用,接收 Schema 转换后的字典数据.
Args:
data: 包含模板字段的字典
Returns:
创建的 DocumentTemplate 实例
Raises:
ValidationException: 验证失败
Requirements: 1.1
"""
template = self.workflow.create_from_dict(data)
logger.info("创建文书模板: %s (ID: %s)", template.name, cast(int, template.pk))
return template
def update_template_from_dict(self, template_id: int, data: dict[str, Any]) -> DocumentTemplate:
"""
从字典数据更新文书模板
用于 API 层调用,接收 Schema 转换后的字典数据.
Args:
template_id: 模板 ID
data: 包含更新字段的字典
Returns:
更新后的 DocumentTemplate 实例
Raises:
NotFoundError: 模板不存在
ValidationException: 验证失败
Requirements: 1.1
"""
try:
template = self.repo.get_by_id(template_id)
except DocumentTemplate.DoesNotExist:
raise NotFoundError(
message=_("文书模板不存在"),
code="TEMPLATE_NOT_FOUND",
errors={"template_id": f"ID 为 {template_id} 的模板不存在"},
) from None
template = self.workflow.update_from_dict(template, data)
logger.info("更新文书模板: %s (ID: %s)", template.name, cast(int, template.pk))
return template