"""Notification template management API (通知模板管理). Global / shared templates for admin-authored notification messages. Every endpoint (including reads) requires ``system_role == "admin"``. Routes (prefix ``/api/notification-templates``): GET "" list (keyword / enabled / tag / page / page_size) POST "" create GET "/{id}" read one PUT "/{id}" update (optimistic lock via expected_version) DELETE "/{id}" delete POST "/{id}/duplicate" duplicate POST "/preview" render title/content with variables """ from __future__ import annotations from datetime import datetime from fastapi import APIRouter, HTTPException, Query, Request, Response from pydantic import BaseModel, Field from app.gateway.deps import get_current_user, get_optional_user_from_request from deerflow.persistence.notification_templates import ( DuplicateNotificationTemplateNameError, NotificationTemplateStore, TemplateVariableError, VersionConflictError, preview_templates, validate_templates, ) router = APIRouter(prefix="/api/notification-templates", tags=["notification-templates"]) # ── schemas ────────────────────────────────────────────────────────────── class NotificationTemplateResponse(BaseModel): id: str name: str title_template: str content_template: str tags: list[str] = Field(default_factory=list) enabled: bool = True version: int = 1 created_by: str | None = None created_at: datetime | str | None = None updated_at: datetime | str | None = None class NotificationTemplateListResponse(BaseModel): items: list[NotificationTemplateResponse] total: int page: int page_size: int class NotificationTemplateCreateRequest(BaseModel): name: str = Field(..., min_length=1, max_length=80) title_template: str = Field(..., min_length=1, max_length=120) content_template: str = Field(..., min_length=1, max_length=5000) tags: list[str] = Field(default_factory=list) enabled: bool = True class NotificationTemplateUpdateRequest(BaseModel): name: str = Field(..., min_length=1, max_length=80) title_template: str = Field(..., min_length=1, max_length=120) content_template: str = Field(..., min_length=1, max_length=5000) tags: list[str] = Field(default_factory=list) enabled: bool = True expected_version: int = Field(..., ge=1) class PreviewRequest(BaseModel): title_template: str = Field(..., min_length=0, max_length=120) content_template: str = Field(..., min_length=0, max_length=5000) variables: dict[str, str] = Field(default_factory=dict) class PreviewResponse(BaseModel): title: str content: str missing_variables: list[str] = Field(default_factory=list) # ── helpers ────────────────────────────────────────────────────────────── def _get_store(request: Request) -> NotificationTemplateStore: store = getattr(request.app.state, "notification_template_store", None) if store is None: raise HTTPException(status_code=503, detail="Notification template store not available") return store async def _require_admin(request: Request) -> None: """Reject non-admins. Lets the call through when auth is disabled.""" user = await get_optional_user_from_request(request) if user is None: return if getattr(user, "system_role", None) != "admin": raise HTTPException(status_code=403, detail="通知模板管理仅限管理员") def _normalize_name(name: str) -> str: cleaned = (name or "").strip() if not (2 <= len(cleaned) <= 50): raise HTTPException(status_code=422, detail="名称去除首尾空格后长度须为 2~50") return cleaned def _normalize_tags(tags: list[str] | None) -> list[str]: seen: set[str] = set() out: list[str] = [] for raw in tags or []: tag = (raw or "").strip() if not tag: continue if not (1 <= len(tag) <= 20): raise HTTPException(status_code=422, detail="单个标签长度须为 1~20") if tag in seen: continue seen.add(tag) out.append(tag) if len(out) > 5: raise HTTPException(status_code=422, detail="标签最多 5 个") return out def _validate_lengths(title: str, content: str) -> None: if not (1 <= len(title) <= 120): raise HTTPException(status_code=422, detail="标题模板长度须为 1~120") if not (1 <= len(content) <= 5000): raise HTTPException(status_code=422, detail="正文模板长度须为 1~5000") def _validate_variables(title: str, content: str) -> None: try: validate_templates(title, content) except TemplateVariableError as exc: raise HTTPException(status_code=422, detail=exc.message) from exc def _to_response(row: dict) -> NotificationTemplateResponse: return NotificationTemplateResponse(**row) async def _unique_duplicate_name(store: NotificationTemplateStore, original: str) -> str: base = f"{original} - 副本" if not await store.name_exists(base): return base n = 2 while True: candidate = f"{original} - 副本 {n}" if not await store.name_exists(candidate): return candidate n += 1 # ── routes ─────────────────────────────────────────────────────────────── @router.get("", response_model=NotificationTemplateListResponse) async def list_notification_templates( request: Request, keyword: str | None = Query(default=None), enabled: bool | None = Query(default=None), tag: str | None = Query(default=None), page: int = Query(default=1, ge=1), page_size: int = Query(default=20, ge=1, le=100), ) -> NotificationTemplateListResponse: await _require_admin(request) store = _get_store(request) items, total = await store.list_templates( keyword=keyword, enabled=enabled, tag=tag, page=page, page_size=page_size, ) return NotificationTemplateListResponse( items=[_to_response(r) for r in items], total=total, page=page, page_size=page_size, ) @router.post("/preview", response_model=PreviewResponse) async def preview_notification_template(request: Request, body: PreviewRequest) -> PreviewResponse: await _require_admin(request) result = preview_templates(body.title_template, body.content_template, body.variables) return PreviewResponse(**result) # type: ignore[arg-type] @router.post("", response_model=NotificationTemplateResponse, status_code=201) async def create_notification_template( request: Request, body: NotificationTemplateCreateRequest, ) -> NotificationTemplateResponse: await _require_admin(request) name = _normalize_name(body.name) tags = _normalize_tags(body.tags) _validate_lengths(body.title_template, body.content_template) _validate_variables(body.title_template, body.content_template) store = _get_store(request) user_id = await get_current_user(request) try: row = await store.create_template( { "name": name, "title_template": body.title_template, "content_template": body.content_template, "tags": tags, "enabled": body.enabled, "created_by": user_id, } ) except DuplicateNotificationTemplateNameError: raise HTTPException(status_code=409, detail="模板名称已存在") return _to_response(row) @router.get("/{template_id}", response_model=NotificationTemplateResponse) async def get_notification_template(request: Request, template_id: str) -> NotificationTemplateResponse: await _require_admin(request) store = _get_store(request) row = await store.get_template(template_id) if row is None: raise HTTPException(status_code=404, detail="模板不存在") return _to_response(row) @router.put("/{template_id}", response_model=NotificationTemplateResponse) async def update_notification_template( request: Request, template_id: str, body: NotificationTemplateUpdateRequest, ) -> NotificationTemplateResponse: await _require_admin(request) name = _normalize_name(body.name) tags = _normalize_tags(body.tags) _validate_lengths(body.title_template, body.content_template) _validate_variables(body.title_template, body.content_template) store = _get_store(request) try: row = await store.update_template( template_id, { "name": name, "title_template": body.title_template, "content_template": body.content_template, "tags": tags, "enabled": body.enabled, }, expected_version=body.expected_version, ) except VersionConflictError as exc: raise HTTPException( status_code=409, detail={"message": "版本冲突,请重新加载或覆盖保存", "server": exc.server}, ) from exc except DuplicateNotificationTemplateNameError: raise HTTPException(status_code=409, detail="模板名称已存在") if row is None: raise HTTPException(status_code=404, detail="模板不存在") return _to_response(row) @router.delete("/{template_id}", status_code=204) async def delete_notification_template(request: Request, template_id: str) -> Response: await _require_admin(request) store = _get_store(request) deleted = await store.delete_template(template_id) if not deleted: raise HTTPException(status_code=404, detail="模板不存在") return Response(status_code=204) @router.post("/{template_id}/duplicate", response_model=NotificationTemplateResponse, status_code=201) async def duplicate_notification_template( request: Request, template_id: str, ) -> NotificationTemplateResponse: await _require_admin(request) store = _get_store(request) source = await store.get_template(template_id) if source is None: raise HTTPException(status_code=404, detail="模板不存在") new_name = await _unique_duplicate_name(store, source["name"]) user_id = await get_current_user(request) try: row = await store.create_template( { "name": new_name, "title_template": source["title_template"], "content_template": source["content_template"], "tags": list(source.get("tags") or []), "enabled": source.get("enabled", True), "created_by": user_id, } ) except DuplicateNotificationTemplateNameError: raise HTTPException(status_code=409, detail="模板名称已存在") return _to_response(row)