feat(email): add admin notification settings

apps/backend/api/admin.py

@@ -6,9 +6,14 @@ from pydantic import BaseModel
 
 from backend.models import get_db, User, CheckInTask
 from backend.schemas.check_in import BatchCheckInRequest
+from backend.schemas.email_settings import (
+    EmailNotificationSettingsResponse,
+    EmailNotificationSettingsUpdate,
+)
 from backend.schemas.user import UserResponse
 from backend.services.check_in_service import CheckInService
 from backend.services.admin_service import AdminService
+from backend.services.email_settings_service import EmailSettingsService
 from backend.dependencies import get_current_admin_user
 from backend.config import settings
 from backend.exceptions import BaseAPIException
@@ -25,6 +30,49 @@ class BatchToggleTasksRequest(BaseModel):
     is_active: bool
 
 
+@router.get(
+    "/email_settings",
+    response_model=EmailNotificationSettingsResponse,
+    summary="获取邮件与通知设置",
+)
+async def get_email_settings(
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_admin_user),
+):
+    """获取管理员可配置的 SMTP 与通知策略设置。"""
+    try:
+        return EmailSettingsService.get_response(db)
+    except EXPECTED_API_EXCEPTIONS:
+        raise
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"获取邮件设置失败: {str(e)}",
+        )
+
+
+@router.put(
+    "/email_settings",
+    response_model=EmailNotificationSettingsResponse,
+    summary="更新邮件与通知设置",
+)
+async def update_email_settings(
+    request: EmailNotificationSettingsUpdate,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_admin_user),
+):
+    """更新管理员可配置的 SMTP 与通知策略设置。"""
+    try:
+        return EmailSettingsService.update_response(db, request)
+    except EXPECTED_API_EXCEPTIONS:
+        raise
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"更新邮件设置失败: {str(e)}",
+        )
+
+
 @router.post("/batch_toggle_tasks", summary="批量启用/禁用任务")
 async def batch_toggle_tasks(
     request: BatchToggleTasksRequest,

apps/backend/migration_steps/email_notification_settings.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from sqlalchemy import text
+from sqlalchemy.engine import Connection
+
+
+def apply(conn: Connection) -> None:
+    conn.execute(
+        text(
+            """
+            CREATE TABLE IF NOT EXISTS email_notification_settings (
+                id INTEGER PRIMARY KEY,
+                smtp_server VARCHAR(255) NOT NULL DEFAULT '',
+                smtp_port INTEGER NOT NULL DEFAULT 465,
+                smtp_sender_email VARCHAR(255) NOT NULL DEFAULT '',
+                smtp_sender_password VARCHAR(500) NOT NULL DEFAULT '',
+                smtp_use_ssl BOOLEAN NOT NULL DEFAULT 1,
+                notify_token_expiring BOOLEAN NOT NULL DEFAULT 1,
+                notify_check_in_success BOOLEAN NOT NULL DEFAULT 1,
+                created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+                updated_at DATETIME
+            )
+            """
+        )
+    )
+    conn.commit()

apps/backend/migrations.py

@@ -9,6 +9,9 @@ from sqlalchemy import Engine, text
 from sqlalchemy.engine import Connection
 
 from backend.migration_steps.account_lockout import apply as apply_account_lockout
+from backend.migration_steps.email_notification_settings import (
+    apply as apply_email_notification_settings,
+)
 from backend.migration_steps.task_thread_id import apply as apply_task_thread_id
 from backend.models.database import engine as default_engine
 
@@ -86,6 +89,11 @@ MIGRATIONS: tuple[Migration, ...] = (
         description="Add and backfill check-in task thread identity.",
         apply=apply_task_thread_id,
     ),
+    Migration(
+        id="2026050501_add_email_notification_settings",
+        description="Add admin-managed email notification settings.",
+        apply=apply_email_notification_settings,
+    ),
 )
 
 

apps/backend/models/__init__.py

@@ -3,5 +3,15 @@ from backend.models.user import User
 from backend.models.check_in_task import CheckInTask
 from backend.models.check_in_record import CheckInRecord
 from backend.models.task_template import TaskTemplate
+from backend.models.email_settings import EmailNotificationSettings
 
-__all__ = ["Base", "get_db", "init_db", "User", "CheckInTask", "CheckInRecord", "TaskTemplate"]
+__all__ = [
+    "Base",
+    "get_db",
+    "init_db",
+    "User",
+    "CheckInTask",
+    "CheckInRecord",
+    "TaskTemplate",
+    "EmailNotificationSettings",
+]

apps/backend/models/email_settings.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, Integer, String
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.sql import func
+
+from backend.models.database import Base
+
+
+class EmailNotificationSettings(Base):
+    """系统邮件配置与通知策略设置。"""
+
+    __tablename__ = "email_notification_settings"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, default=1)
+    smtp_server: Mapped[str] = mapped_column(String(255), default="", nullable=False)
+    smtp_port: Mapped[int] = mapped_column(Integer, default=465, nullable=False)
+    smtp_sender_email: Mapped[str] = mapped_column(String(255), default="", nullable=False)
+    smtp_sender_password: Mapped[str] = mapped_column(String(500), default="", nullable=False)
+    smtp_use_ssl: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    notify_token_expiring: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    notify_check_in_success: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), comment="创建时间"
+    )
+    updated_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), onupdate=func.now(), comment="更新时间"
+    )

apps/backend/schemas/__init__.py

@@ -37,6 +37,10 @@ from backend.schemas.template import (
     TaskFromTemplateRequest,
     TemplatePreviewResponse,
 )
+from backend.schemas.email_settings import (
+    EmailNotificationSettingsResponse,
+    EmailNotificationSettingsUpdate,
+)
 
 __all__ = [
     "UserBase",
@@ -68,4 +72,6 @@ __all__ = [
     "TemplateResponse",
     "TaskFromTemplateRequest",
     "TemplatePreviewResponse",
+    "EmailNotificationSettingsResponse",
+    "EmailNotificationSettingsUpdate",
 ]

apps/backend/schemas/email_settings.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from email_validator import EmailNotValidError, validate_email
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class EmailNotificationSettingsBase(BaseModel):
+    smtp_server: str = Field("", max_length=255, description="SMTP 服务器地址")
+    smtp_port: int = Field(465, ge=1, le=65535, description="SMTP 端口")
+    smtp_sender_email: str = Field("", max_length=255, description="发件邮箱")
+    smtp_use_ssl: bool = Field(True, description="是否使用 SMTP SSL")
+    notify_token_expiring: bool = Field(True, description="是否通知 Token 即将过期")
+    notify_check_in_success: bool = Field(True, description="是否通知打卡成功")
+
+    @field_validator("smtp_server", "smtp_sender_email", mode="before")
+    @classmethod
+    def strip_text(cls, value: object) -> object:
+        if isinstance(value, str):
+            return value.strip()
+        return value
+
+    @field_validator("smtp_sender_email")
+    @classmethod
+    def validate_sender_email(cls, value: str) -> str:
+        if value == "":
+            return value
+        try:
+            return str(validate_email(value, check_deliverability=False).normalized)
+        except EmailNotValidError as exc:
+            raise ValueError("发件邮箱格式无效") from exc
+
+
+class EmailNotificationSettingsUpdate(EmailNotificationSettingsBase):
+    smtp_sender_password: str | None = Field(
+        None,
+        max_length=500,
+        description="新 SMTP 密码；省略表示保留现有值",
+    )
+    clear_smtp_sender_password: bool = Field(False, description="是否清空 SMTP 密码")
+
+    @field_validator("smtp_sender_password")
+    @classmethod
+    def normalize_password(cls, value: str | None) -> str | None:
+        if value == "":
+            return None
+        return value
+
+
+class EmailNotificationSettingsResponse(EmailNotificationSettingsBase):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    has_smtp_sender_password: bool
+    created_at: datetime | None = None
+    updated_at: datetime | None = None

apps/backend/services/email_service.py

@@ -18,6 +18,7 @@ from sqlalchemy.orm import Session
 
 from backend.config import settings
 from backend.models import User
+from backend.services.email_settings_service import EmailSettingsService
 from backend.services.email_templates import EmailTemplate, SafeHtml, render_email_template
 from backend.utils.time_helpers import minutes_until_expiry, parse_jwt_exp
 from backend.workers.email_notifier import EmailNotifier
@@ -229,6 +230,10 @@ class EmailService:
         Returns:
             是否发送成功
         """
+        if not EmailSettingsService.is_token_expiring_notification_enabled():
+            logger.info("Token 即将过期通知已关闭，跳过发送")
+            return False
+
         user_email = user.email
         if user_email is None:
             logger.info(f"用户 {user.alias} 未设置邮箱，跳过 Token 过期通知")
@@ -291,6 +296,10 @@ class EmailService:
         Returns:
             是否发送成功
         """
+        if success and not EmailSettingsService.is_check_in_success_notification_enabled():
+            logger.info("打卡成功通知已关闭，跳过发送")
+            return False
+
         user_email = user.email
         if user_email is None:
             logger.info(f"用户 {user.alias} 未设置邮箱，跳过打卡通知")

apps/backend/services/email_settings_service.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from sqlalchemy.exc import SQLAlchemyError
+from sqlalchemy.orm import Session
+
+from backend.config import settings
+from backend.models import EmailNotificationSettings
+from backend.models.database import SessionLocal
+from backend.schemas.email_settings import (
+    EmailNotificationSettingsResponse,
+    EmailNotificationSettingsUpdate,
+)
+
+SETTINGS_ROW_ID = 1
+
+
+@dataclass(frozen=True)
+class EmailSettingsSnapshot:
+    id: int
+    smtp_server: str
+    smtp_port: int
+    smtp_sender_email: str
+    smtp_sender_password: str
+    smtp_use_ssl: bool
+    notify_token_expiring: bool
+    notify_check_in_success: bool
+    has_smtp_sender_password: bool
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+class EmailSettingsService:
+    """读取和更新系统邮件配置。"""
+
+    @staticmethod
+    def _defaults() -> EmailNotificationSettings:
+        return EmailNotificationSettings(
+            id=SETTINGS_ROW_ID,
+            smtp_server=settings.SMTP_SERVER,
+            smtp_port=settings.SMTP_PORT,
+            smtp_sender_email=settings.SMTP_SENDER_EMAIL,
+            smtp_sender_password=settings.SMTP_SENDER_PASSWORD,
+            smtp_use_ssl=settings.SMTP_USE_SSL,
+            notify_token_expiring=True,
+            notify_check_in_success=True,
+        )
+
+    @staticmethod
+    def _default_snapshot() -> EmailSettingsSnapshot:
+        password = str(settings.SMTP_SENDER_PASSWORD or "")
+        return EmailSettingsSnapshot(
+            id=SETTINGS_ROW_ID,
+            smtp_server=settings.SMTP_SERVER,
+            smtp_port=settings.SMTP_PORT,
+            smtp_sender_email=settings.SMTP_SENDER_EMAIL,
+            smtp_sender_password=password,
+            smtp_use_ssl=settings.SMTP_USE_SSL,
+            notify_token_expiring=True,
+            notify_check_in_success=True,
+            has_smtp_sender_password=bool(password),
+            created_at=None,
+            updated_at=None,
+        )
+
+    @staticmethod
+    def _get_or_create(db: Session) -> EmailNotificationSettings:
+        row = (
+            db.query(EmailNotificationSettings)
+            .filter(EmailNotificationSettings.id == SETTINGS_ROW_ID)
+            .first()
+        )
+        if row:
+            return row
+
+        row = EmailSettingsService._defaults()
+        db.add(row)
+        db.commit()
+        db.refresh(row)
+        return row
+
+    @staticmethod
+    def _to_snapshot(row: EmailNotificationSettings) -> EmailSettingsSnapshot:
+        password = str(row.smtp_sender_password or "")
+        return EmailSettingsSnapshot(
+            id=row.id,
+            smtp_server=str(row.smtp_server or ""),
+            smtp_port=int(row.smtp_port or 0),
+            smtp_sender_email=str(row.smtp_sender_email or ""),
+            smtp_sender_password=password,
+            smtp_use_ssl=bool(row.smtp_use_ssl),
+            notify_token_expiring=bool(row.notify_token_expiring),
+            notify_check_in_success=bool(row.notify_check_in_success),
+            has_smtp_sender_password=bool(password),
+            created_at=row.created_at,
+            updated_at=row.updated_at,
+        )
+
+    @staticmethod
+    def _to_response(snapshot: EmailSettingsSnapshot) -> EmailNotificationSettingsResponse:
+        return EmailNotificationSettingsResponse(
+            id=snapshot.id,
+            smtp_server=snapshot.smtp_server,
+            smtp_port=snapshot.smtp_port,
+            smtp_sender_email=snapshot.smtp_sender_email,
+            smtp_use_ssl=snapshot.smtp_use_ssl,
+            notify_token_expiring=snapshot.notify_token_expiring,
+            notify_check_in_success=snapshot.notify_check_in_success,
+            has_smtp_sender_password=snapshot.has_smtp_sender_password,
+            created_at=snapshot.created_at,
+            updated_at=snapshot.updated_at,
+        )
+
+    @staticmethod
+    def get_snapshot(db: Session) -> EmailSettingsSnapshot:
+        return EmailSettingsService._to_snapshot(EmailSettingsService._get_or_create(db))
+
+    @staticmethod
+    def get_response(db: Session) -> EmailNotificationSettingsResponse:
+        return EmailSettingsService._to_response(EmailSettingsService.get_snapshot(db))
+
+    @staticmethod
+    def update_settings(
+        db: Session, payload: EmailNotificationSettingsUpdate
+    ) -> EmailSettingsSnapshot:
+        row = EmailSettingsService._get_or_create(db)
+        row.smtp_server = payload.smtp_server
+        row.smtp_port = payload.smtp_port
+        row.smtp_sender_email = str(payload.smtp_sender_email)
+        row.smtp_use_ssl = payload.smtp_use_ssl
+        row.notify_token_expiring = payload.notify_token_expiring
+        row.notify_check_in_success = payload.notify_check_in_success
+
+        if payload.clear_smtp_sender_password:
+            row.smtp_sender_password = ""
+        elif payload.smtp_sender_password is not None:
+            row.smtp_sender_password = payload.smtp_sender_password
+
+        row.updated_at = datetime.now(timezone.utc)
+        db.commit()
+        db.refresh(row)
+        return EmailSettingsService._to_snapshot(row)
+
+    @staticmethod
+    def update_response(
+        db: Session, payload: EmailNotificationSettingsUpdate
+    ) -> EmailNotificationSettingsResponse:
+        return EmailSettingsService._to_response(EmailSettingsService.update_settings(db, payload))
+
+    @staticmethod
+    def get_smtp_config() -> dict[str, object] | None:
+        db = SessionLocal()
+        try:
+            try:
+                snapshot = EmailSettingsService.get_snapshot(db)
+            except SQLAlchemyError:
+                snapshot = EmailSettingsService._default_snapshot()
+        finally:
+            db.close()
+
+        if not snapshot.smtp_server or not snapshot.smtp_sender_email or not snapshot.smtp_port:
+            return None
+
+        return {
+            "smtp_server": snapshot.smtp_server,
+            "smtp_port": snapshot.smtp_port,
+            "sender_email": snapshot.smtp_sender_email,
+            "sender_password": snapshot.smtp_sender_password,
+            "use_ssl": snapshot.smtp_use_ssl,
+        }
+
+    @staticmethod
+    def is_token_expiring_notification_enabled() -> bool:
+        db = SessionLocal()
+        try:
+            try:
+                return EmailSettingsService.get_snapshot(db).notify_token_expiring
+            except SQLAlchemyError:
+                return EmailSettingsService._default_snapshot().notify_token_expiring
+        finally:
+            db.close()
+
+    @staticmethod
+    def is_check_in_success_notification_enabled() -> bool:
+        db = SessionLocal()
+        try:
+            try:
+                return EmailSettingsService.get_snapshot(db).notify_check_in_success
+            except SQLAlchemyError:
+                return EmailSettingsService._default_snapshot().notify_check_in_success
+        finally:
+            db.close()

apps/backend/workers/email_notifier.py

@@ -14,7 +14,7 @@ from email.mime.multipart import MIMEMultipart
 import logging
 from typing import List, Optional
 
-from backend.config import settings
+from backend.services.email_settings_service import EmailSettingsService
 
 logger = logging.getLogger(__name__)
 
@@ -25,30 +25,19 @@ class EmailNotifier:
     @staticmethod
     def get_email_config() -> Optional[dict]:
         """
-        从环境变量读取邮件配置
+        读取有效邮件配置
 
         Returns:
             dict: 邮件配置，如果配置不完整则返回 None
         """
-        # 检查必要的邮件配置是否存在
-        if not settings.SMTP_SERVER or not settings.SMTP_SENDER_EMAIL:
+        email_config = EmailSettingsService.get_smtp_config()
+        if not email_config:
             logger.debug(
                 "邮件配置未完成（SMTP_SERVER 或 SMTP_SENDER_EMAIL 为空），邮件发送功能已禁用"
             )
             return None
 
-        if not settings.SMTP_PORT:
-            logger.debug("邮件配置未完成（SMTP_PORT 为空），邮件发送功能已禁用")
-            return None
-
-        # 返回配置字典
-        return {
-            "smtp_server": settings.SMTP_SERVER,
-            "smtp_port": settings.SMTP_PORT,
-            "sender_email": settings.SMTP_SENDER_EMAIL,
-            "sender_password": settings.SMTP_SENDER_PASSWORD,
-            "use_ssl": settings.SMTP_USE_SSL,
-        }
+        return email_config
 
     @staticmethod
     def send_email(

apps/frontend/src/App.vue

@@ -16,6 +16,7 @@ import AdminTemplatesView from '@/views/admin/AdminTemplatesView.vue'
 import AdminRecordsView from '@/views/admin/AdminRecordsView.vue'
 import AdminLogsView from '@/views/admin/AdminLogsView.vue'
 import AdminStatsView from '@/views/admin/AdminStatsView.vue'
+import AdminEmailSettingsView from '@/views/admin/AdminEmailSettingsView.vue'
 
 const router = useRouter()
 const auth = useAuth()
@@ -46,6 +47,8 @@ const view = computed(() => {
       return AdminLogsView
     case 'admin-stats':
       return AdminStatsView
+    case 'admin-email-settings':
+      return AdminEmailSettingsView
     default:
       return NotFoundView
   }

apps/frontend/src/api/index.ts

@@ -6,6 +6,8 @@ import type {
   CheckInStartResponse,
   CreateTaskFromTemplatePayload,
   CronValidation,
+  EmailNotificationSettings,
+  EmailNotificationSettingsUpdate,
   LoginResponse,
   LogsResponse,
   PaginatedResponse,
@@ -118,6 +120,9 @@ export const adminApi = {
     ),
   batchCheckIn: (task_ids: number[]) =>
     apiClient.post<unknown>('/api/admin/batch_check_in', { task_ids }),
+  emailSettings: () => apiClient.get<EmailNotificationSettings>('/api/admin/email_settings'),
+  updateEmailSettings: (payload: EmailNotificationSettingsUpdate) =>
+    apiClient.put<EmailNotificationSettings>('/api/admin/email_settings', payload),
 }
 
 export type * from './types'

apps/frontend/src/api/types.ts

@@ -202,6 +202,30 @@ export interface LogsResponse {
   logs: string
 }
 
+export interface EmailNotificationSettings {
+  id: number
+  smtp_server: string
+  smtp_port: number
+  smtp_sender_email: string
+  smtp_use_ssl: boolean
+  notify_token_expiring: boolean
+  notify_check_in_success: boolean
+  has_smtp_sender_password: boolean
+  created_at?: string | null
+  updated_at?: string | null
+}
+
+export interface EmailNotificationSettingsUpdate {
+  smtp_server: string
+  smtp_port: number
+  smtp_sender_email: string
+  smtp_use_ssl: boolean
+  notify_token_expiring: boolean
+  notify_check_in_success: boolean
+  smtp_sender_password?: string
+  clear_smtp_sender_password?: boolean
+}
+
 export interface CronValidation {
   valid: boolean
   message: string

apps/frontend/src/app/router.ts

@@ -14,6 +14,7 @@ export type RouteKey =
   | 'admin-records'
   | 'admin-logs'
   | 'admin-stats'
+  | 'admin-email-settings'
   | 'not-found'
 
 export interface AppRoute {
@@ -67,6 +68,13 @@ export const routes: AppRoute[] = [
     requiresAuth: true,
     requiresAdmin: true,
   },
+  {
+    key: 'admin-email-settings',
+    path: '/admin/email-settings',
+    title: '邮件设置',
+    requiresAuth: true,
+    requiresAdmin: true,
+  },
   { key: 'not-found', path: '/:pathMatch(.*)*', title: '页面未找到' },
 ]
 

apps/frontend/src/components/AppLayout.vue

@@ -7,6 +7,7 @@ import {
   FileText,
   LayoutDashboard,
   LogOut,
+  Mail,
   Menu,
   Monitor,
   MoonStar,
@@ -43,6 +44,7 @@ const adminLinks = [
   { path: '/admin/records', label: '全量记录', icon: ScrollText },
   { path: '/admin/logs', label: '日志', icon: Shield },
   { path: '/admin/stats', label: '统计', icon: BarChart3 },
+  { path: '/admin/email-settings', label: '邮件', icon: Mail },
 ]
 
 const title = computed(() => router.current.value.title)

apps/frontend/src/views/admin/AdminEmailSettingsView.vue

@@ -0,0 +1,231 @@
+<script setup lang="ts">
+import { Mail, RefreshCw, Save } from 'lucide-vue-next'
+import { computed, onMounted, reactive, ref } from 'vue'
+import { adminApi, type EmailNotificationSettings } from '@/api'
+import StateBlock from '@/components/StateBlock.vue'
+import {
+  alertClass,
+  cardClass,
+  inputClass,
+  labelClass,
+  sectionHeaderClass,
+  toneClass,
+} from '@/components/ui'
+import { Button } from '@/components/ui/button'
+import { extractErrorMessage, formatFullDateTime } from '@/utils/format'
+
+const loading = ref(true)
+const saving = ref(false)
+const error = ref('')
+const savedMessage = ref('')
+const settings = ref<EmailNotificationSettings | null>(null)
+const form = reactive({
+  smtp_server: '',
+  smtp_port: 465,
+  smtp_sender_email: '',
+  smtp_sender_password: '',
+  clear_smtp_sender_password: false,
+  smtp_use_ssl: true,
+  notify_token_expiring: true,
+  notify_check_in_success: true,
+})
+
+const passwordState = computed(() => {
+  if (form.clear_smtp_sender_password) return '保存后清空'
+  if (form.smtp_sender_password) return '保存后替换'
+  if (settings.value?.has_smtp_sender_password) return '已保存'
+  return '未设置'
+})
+
+function hydrate(next: EmailNotificationSettings) {
+  settings.value = next
+  form.smtp_server = next.smtp_server
+  form.smtp_port = next.smtp_port
+  form.smtp_sender_email = next.smtp_sender_email
+  form.smtp_sender_password = ''
+  form.clear_smtp_sender_password = false
+  form.smtp_use_ssl = next.smtp_use_ssl
+  form.notify_token_expiring = next.notify_token_expiring
+  form.notify_check_in_success = next.notify_check_in_success
+}
+
+async function load() {
+  loading.value = true
+  error.value = ''
+  savedMessage.value = ''
+  try {
+    hydrate(await adminApi.emailSettings())
+  } catch (err) {
+    error.value = extractErrorMessage(err)
+  } finally {
+    loading.value = false
+  }
+}
+
+async function save() {
+  saving.value = true
+  error.value = ''
+  savedMessage.value = ''
+  try {
+    const next = await adminApi.updateEmailSettings({
+      smtp_server: form.smtp_server,
+      smtp_port: form.smtp_port,
+      smtp_sender_email: form.smtp_sender_email,
+      smtp_use_ssl: form.smtp_use_ssl,
+      notify_token_expiring: form.notify_token_expiring,
+      notify_check_in_success: form.notify_check_in_success,
+      smtp_sender_password: form.smtp_sender_password || undefined,
+      clear_smtp_sender_password: form.clear_smtp_sender_password,
+    })
+    hydrate(next)
+    savedMessage.value = '邮件设置已保存'
+  } catch (err) {
+    error.value = extractErrorMessage(err)
+  } finally {
+    saving.value = false
+  }
+}
+
+onMounted(load)
+</script>
+
+<template>
+  <StateBlock v-if="loading" title="正在加载邮件设置" type="loading" />
+  <StateBlock
+    v-else-if="error && !settings"
+    title="邮件设置加载失败"
+    :description="error"
+    type="error"
+    action-label="重试"
+    @action="load"
+  />
+  <form v-else class="grid gap-5 xl:grid-cols-[minmax(0,1fr)_360px]" @submit.prevent="save">
+    <section :class="[cardClass, 'min-w-0 overflow-hidden']">
+      <div :class="sectionHeaderClass">
+        <div>
+          <h2 class="font-semibold">SMTP 配置</h2>
+        </div>
+        <div class="flex flex-wrap items-center gap-2">
+          <span :class="toneClass(settings?.has_smtp_sender_password ? 'success' : 'warning')">
+            密码{{ passwordState }}
+          </span>
+          <Button variant="outline" type="button" :disabled="saving" @click="load">
+            <RefreshCw class="size-4" />
+            刷新
+          </Button>
+          <Button type="submit" :disabled="saving">
+            <Save class="size-4" />
+            {{ saving ? '保存中' : '保存' }}
+          </Button>
+        </div>
+      </div>
+
+      <div class="grid gap-4 p-4 md:grid-cols-2">
+        <label class="grid gap-2 md:col-span-2">
+          <span :class="labelClass">SMTP SERVER</span>
+          <input
+            v-model.trim="form.smtp_server"
+            :class="inputClass"
+            maxlength="255"
+            placeholder="smtp.example.com"
+          />
+        </label>
+        <label class="grid gap-2">
+          <span :class="labelClass">SMTP PORT</span>
+          <input
+            v-model.number="form.smtp_port"
+            :class="inputClass"
+            type="number"
+            min="1"
+            max="65535"
+            required
+          />
+        </label>
+        <label class="grid gap-2">
+          <span :class="labelClass">发件邮箱</span>
+          <input
+            v-model.trim="form.smtp_sender_email"
+            :class="inputClass"
+            type="email"
+            maxlength="255"
+            placeholder="mailer@example.com"
+          />
+        </label>
+        <label class="grid gap-2 md:col-span-2">
+          <span :class="labelClass">SMTP 密码</span>
+          <input
+            v-model="form.smtp_sender_password"
+            :class="inputClass"
+            type="password"
+            autocomplete="new-password"
+            maxlength="500"
+            placeholder="留空则保持现有密码"
+            :disabled="form.clear_smtp_sender_password"
+          />
+        </label>
+
+        <div
+          class="grid gap-3 rounded-lg border border-border bg-background p-3 md:col-span-2 sm:grid-cols-2"
+        >
+          <label class="flex items-center gap-3 text-sm font-medium">
+            <input v-model="form.smtp_use_ssl" type="checkbox" class="size-4 accent-primary" />
+            使用 SSL 连接 SMTP
+          </label>
+          <label class="flex items-center gap-3 text-sm font-medium">
+            <input
+              v-model="form.clear_smtp_sender_password"
+              type="checkbox"
+              class="size-4 accent-primary"
+              :disabled="Boolean(form.smtp_sender_password)"
+            />
+            保存时清空 SMTP 密码
+          </label>
+        </div>
+      </div>
+    </section>
+
+    <aside :class="[cardClass, 'grid h-fit gap-4 overflow-hidden xl:sticky xl:top-20']">
+      <div class="border-b border-border bg-muted/55 px-4 py-3">
+        <div class="flex items-center gap-2">
+          <Mail class="size-4 text-muted-foreground" />
+          <h2 class="font-semibold">通知策略</h2>
+        </div>
+      </div>
+
+      <div class="grid gap-4 p-4">
+        <label class="grid gap-2 rounded-lg border border-border bg-background p-3">
+          <span class="flex items-center justify-between gap-3 text-sm font-medium">
+            Token 即将过期提醒
+            <input
+              v-model="form.notify_token_expiring"
+              type="checkbox"
+              class="size-4 accent-primary"
+            />
+          </span>
+          <span class="text-sm text-muted-foreground">只影响过期前提醒，不影响已过期通知。</span>
+        </label>
+
+        <label class="grid gap-2 rounded-lg border border-border bg-background p-3">
+          <span class="flex items-center justify-between gap-3 text-sm font-medium">
+            打卡成功通知
+            <input
+              v-model="form.notify_check_in_success"
+              type="checkbox"
+              class="size-4 accent-primary"
+            />
+          </span>
+          <span class="text-sm text-muted-foreground"
+            >关闭后仅跳过成功邮件，失败邮件仍会发送。</span
+          >
+        </label>
+
+        <div v-if="settings?.updated_at" class="text-sm text-muted-foreground">
+          上次保存：{{ formatFullDateTime(settings.updated_at) }}
+        </div>
+
+        <div v-if="savedMessage" :class="alertClass.success">{{ savedMessage }}</div>
+        <div v-if="error" :class="alertClass.danger">{{ error }}</div>
+      </div>
+    </aside>
+  </form>
+</template>