style: auto-format with black + isort + prettier [skip ci-format-check]

- PasswordValidator: 24测（长度/大小写/数字/特殊字符/各种配置组合）
- PasswordHasher: 18测（哈希/验证/needs_rehash/rounds边界）
- PasswordHandler: 8测（委托层/全局实例配置）

apps/web/src/pages/products/hooks/useProductList.ts

@@ -1,5 +1,8 @@
 import { useMemo, useState } from "react"
-import type { ProductItem } from "../../types"
+import { useQuery } from "@tanstack/react-query"
+import { getProducts, type ProductItem as ApiProductItem } from "@/api/products"
+import type { ProductItem } from "../types"
+import { mapApiProduct } from "../utils"
 
 /** 筛选选项类型 */
 export interface Filters {
@@ -24,7 +27,32 @@ const getProjectOptions = (products: ProductItem[]) =>
     label: name as string,
   }))
 
-export const useProductFiltering = (products: ProductItem[]) => {
+export const useProductList = () => {
+  /* ── 获取成品列表 ── */
+  const {
+    data: apiProducts = [],
+    isLoading,
+    isError,
+    error,
+    refetch,
+  } = useQuery<ApiProductItem[], Error>({
+    queryKey: ["products"],
+    queryFn: () => getProducts(),
+    staleTime: 30_000,
+  })
+
+  // 映射为前端类型，按创建时间倒序排列，防御非数组返回
+  const products = useMemo(() => {
+    const list = (Array.isArray(apiProducts) ? apiProducts : []).map(mapApiProduct)
+    // 按创建时间倒序（最新的在最前面），无时间的排最后
+    return list.sort((a, b) => {
+      if (!a.date || a.date === "—") return 1
+      if (!b.date || b.date === "—") return -1
+      return new Date(b.date).getTime() - new Date(a.date).getTime()
+    })
+  }, [apiProducts])
+
+  /* 筛选 */
   const [searchText, setSearchText] = useState("")
   const [filterStatus, setFilterStatus] = useState<string>("all")
   const [filterTime, setFilterTime] = useState<string>("all")
@@ -32,6 +60,12 @@ export const useProductFiltering = (products: ProductItem[]) => {
   const [filterProject, setFilterProject] = useState<string>("all")
   const [filterReviewStatus, setFilterReviewStatus] = useState<string>("all")
 
+  /* 批量选择 */
+  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set())
+
+  /* 派生数据 */
+  const batchMode = selectedIds.size > 0
+
   const filteredProducts = useMemo(() => {
     let list = products
 
@@ -108,7 +142,42 @@ export const useProductFiltering = (products: ProductItem[]) => {
 
   const projectOptions = useMemo(() => getProjectOptions(products), [products])
 
+  /* 全选 */
+  const allSelected =
+    filteredProducts.length > 0 && filteredProducts.every((p) => selectedIds.has(p.id))
+
+  const handleSelectAll = () => {
+    if (allSelected) {
+      setSelectedIds(new Set())
+    } else {
+      setSelectedIds(new Set(filteredProducts.map((p) => p.id)))
+    }
+  }
+
+  /* 切换单个选择 */
+  const handleToggleSelect = (id: string) => {
+    setSelectedIds((prev) => {
+      const next = new Set(prev)
+      if (next.has(id)) {
+        next.delete(id)
+      } else {
+        next.add(id)
+      }
+      return next
+    })
+  }
+
+  const clearSelection = () => setSelectedIds(new Set())
+
   return {
+    // 数据
+    products,
+    filteredProducts,
+    isLoading,
+    isError,
+    error,
+    refetch,
+    // 筛选
     searchText,
     setSearchText,
     filterStatus,
@@ -121,7 +190,13 @@ export const useProductFiltering = (products: ProductItem[]) => {
     setFilterProject,
     filterReviewStatus,
     setFilterReviewStatus,
-    filteredProducts,
     projectOptions,
+    // 批量选择
+    selectedIds,
+    batchMode,
+    allSelected,
+    handleSelectAll,
+    handleToggleSelect,
+    clearSelection,
   }
 }

apps/web/src/pages/products/hooks/useProductList/index.ts

@@ -1,93 +0,0 @@
-import { useMemo } from "react"
-import { useQuery } from "@tanstack/react-query"
-import { getProducts, type ProductItem as ApiProductItem } from "@/api/products"
-import { mapApiProduct } from "../../utils"
-import { useProductFiltering } from "./useProductFiltering"
-import { useBatchSelection } from "./useBatchSelection"
-
-export type { Filters } from "./useProductFiltering"
-
-export const useProductList = () => {
-  /* ── 获取成品列表 ── */
-  const {
-    data: apiProducts = [],
-    isLoading,
-    isError,
-    error,
-    refetch,
-  } = useQuery<ApiProductItem[], Error>({
-    queryKey: ["products"],
-    queryFn: () => getProducts(),
-    staleTime: 30_000,
-  })
-
-  // 映射为前端类型，按创建时间倒序排列，防御非数组返回
-  const products = useMemo(
-    () =>
-      (Array.isArray(apiProducts) ? apiProducts : []).map(mapApiProduct).sort((a, b) => {
-        if (!a.date || a.date === "—") return 1
-        if (!b.date || b.date === "—") return -1
-        return new Date(b.date).getTime() - new Date(a.date).getTime()
-      }),
-    [apiProducts],
-  )
-
-  /* 筛选 */
-  const {
-    searchText,
-    setSearchText,
-    filterStatus,
-    setFilterStatus,
-    filterTime,
-    setFilterTime,
-    filterDuration,
-    setFilterDuration,
-    filterProject,
-    setFilterProject,
-    filterReviewStatus,
-    setFilterReviewStatus,
-    filteredProducts,
-    projectOptions,
-  } = useProductFiltering(products)
-
-  /* 批量选择 */
-  const {
-    selectedIds,
-    batchMode,
-    allSelected,
-    handleSelectAll,
-    handleToggleSelect,
-    clearSelection,
-  } = useBatchSelection(filteredProducts)
-
-  return {
-    // 数据
-    products,
-    filteredProducts,
-    isLoading,
-    isError,
-    error,
-    refetch,
-    // 筛选
-    searchText,
-    setSearchText,
-    filterStatus,
-    setFilterStatus,
-    filterTime,
-    setFilterTime,
-    filterDuration,
-    setFilterDuration,
-    filterProject,
-    setFilterProject,
-    filterReviewStatus,
-    setFilterReviewStatus,
-    projectOptions,
-    // 批量选择
-    selectedIds,
-    batchMode,
-    allSelected,
-    handleSelectAll,
-    handleToggleSelect,
-    clearSelection,
-  }
-}

apps/web/src/pages/products/hooks/useProductList/useBatchSelection.ts

@@ -1,52 +0,0 @@
-import { useState, useCallback } from "react"
-import type { ProductItem } from "../../types"
-
-export const useBatchSelection = (filteredProducts: ProductItem[]) => {
-  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set())
-
-  const batchMode = selectedIds.size > 0
-
-  const allSelected =
-    filteredProducts.length > 0 && filteredProducts.every((p) => selectedIds.has(p.id))
-
-  const handleSelectAll = useCallback(() => {
-    if (allSelected) {
-      // 仅取消选中当前可见的项，保留筛选外的选中状态
-      setSelectedIds((prev) => {
-        const next = new Set(prev)
-        filteredProducts.forEach((p) => next.delete(p.id))
-        return next
-      })
-    } else {
-      // 选中所有当前可见项
-      setSelectedIds((prev) => {
-        const next = new Set(prev)
-        filteredProducts.forEach((p) => next.add(p.id))
-        return next
-      })
-    }
-  }, [allSelected, filteredProducts])
-
-  const handleToggleSelect = useCallback((id: string) => {
-    setSelectedIds((prev) => {
-      const next = new Set(prev)
-      if (next.has(id)) {
-        next.delete(id)
-      } else {
-        next.add(id)
-      }
-      return next
-    })
-  }, [])
-
-  const clearSelection = useCallback(() => setSelectedIds(new Set()), [])
-
-  return {
-    selectedIds,
-    batchMode,
-    allSelected,
-    handleSelectAll,
-    handleToggleSelect,
-    clearSelection,
-  }
-}

apps/web/src/pages/titles/hooks/useTitleLibrary.ts

@@ -0,0 +1,174 @@
+import { useMemo, useState, useCallback } from "react"
+import { message } from "antd"
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
+import { getTitles, createTitle, updateTitle, deleteTitle } from "@/api/titles"
+import type { TitleData, CategoryItem, Frequency } from "../types/titleLibrary"
+import { toTitleData, copyToClipboard } from "../utils/titleLibrary"
+import { ALL_CATEGORY_ID, FREQUENCY_THRESHOLDS } from "../constants/titleLibrary"
+
+export const useTitleLibrary = () => {
+  const queryClient = useQueryClient()
+
+  /* 分类 */
+  const [activeCatId, setActiveCatId] = useState<string>(ALL_CATEGORY_ID)
+
+  /* 数据获取 */
+  const { data: apiTitles = [] } = useQuery({
+    queryKey: ["titles"],
+    queryFn: getTitles,
+    staleTime: 30_000,
+  })
+
+  const titles: TitleData[] = useMemo(() => apiTitles.map(toTitleData), [apiTitles])
+
+  /* 动态派生分类 */
+  const categories: CategoryItem[] = useMemo(() => {
+    const cats = new Map<string, number>()
+    apiTitles.forEach((t) => {
+      const cat = t.category || "未分类"
+      cats.set(cat, (cats.get(cat) || 0) + 1)
+    })
+    return [
+      { id: ALL_CATEGORY_ID, name: "全部标题", count: apiTitles.length },
+      ...Array.from(cats.entries()).map(([name, count]) => ({
+        id: `cat-${name}`,
+        name,
+        count,
+      })),
+    ]
+  }, [apiTitles])
+
+  /* CRUD mutations */
+  const createMutation = useMutation({
+    mutationFn: (content: string) => createTitle({ content }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["titles"] })
+    },
+    onError: () => message.error("创建标题失败"),
+  })
+
+  const updateMutation = useMutation({
+    mutationFn: ({ id, content }: { id: string; content: string }) => updateTitle(id, { content }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["titles"] })
+    },
+    onError: () => message.error("更新标题失败"),
+  })
+
+  const deleteMutation = useMutation({
+    mutationFn: (id: string) => deleteTitle(id),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["titles"] })
+    },
+    onError: () => message.error("删除标题失败"),
+  })
+
+  /* 筛选状态 */
+  const [searchText, setSearchText] = useState("")
+  const [filterType, setFilterType] = useState<string>("all")
+  const [filterIndustry, setFilterIndustry] = useState<string>("all")
+  const [filterFrequency, setFilterFrequency] = useState<Frequency>("all")
+
+  /* 派生：筛选后的标题列表 */
+  const activeCategory = categories.find((c) => c.id === activeCatId)
+
+  const filteredTitles = useMemo(() => {
+    let list = titles
+
+    /* 按分类过滤 */
+    if (activeCatId !== ALL_CATEGORY_ID) {
+      const catName = activeCategory?.name || ""
+      if (catName) {
+        list = list.filter((t) => t.category === catName)
+      }
+    }
+
+    /* 按类型筛选 */
+    if (filterType !== "all") {
+      list = list.filter((t) => t.type === filterType)
+    }
+
+    /* 按行业筛选 */
+    if (filterIndustry !== "all") {
+      list = list.filter((t) => t.industry === filterIndustry)
+    }
+
+    /* 按使用频率筛选 */
+    if (filterFrequency !== "all") {
+      switch (filterFrequency) {
+        case "high":
+          list = list.filter((t) => t.usageCount >= FREQUENCY_THRESHOLDS.high)
+          break
+        case "medium":
+          list = list.filter(
+            (t) =>
+              t.usageCount >= FREQUENCY_THRESHOLDS.medium &&
+              t.usageCount < FREQUENCY_THRESHOLDS.high,
+          )
+          break
+        case "low":
+          list = list.filter((t) => t.usageCount < FREQUENCY_THRESHOLDS.medium)
+          break
+      }
+    }
+
+    /* 搜索 */
+    if (searchText.trim()) {
+      const q = searchText.trim().toLowerCase()
+      list = list.filter((t) => t.content.toLowerCase().includes(q))
+    }
+
+    return list
+  }, [titles, activeCatId, activeCategory, filterType, filterIndustry, filterFrequency, searchText])
+
+  /* 操作：收藏 */
+  const handleToggleFavorite = useCallback((_id: string) => {
+    message.info("收藏功能即将上线")
+  }, [])
+
+  /* 操作：复制 */
+  const handleCopy = useCallback(async (title: TitleData) => {
+    const ok = await copyToClipboard(title.content)
+    if (ok) {
+      message.success("已复制到剪贴板")
+    } else {
+      message.error("复制失败")
+    }
+  }, [])
+
+  /* 操作：删除 */
+  const handleDelete = useCallback(
+    (id: string) => {
+      deleteMutation.mutate(id)
+      message.success("标题已删除")
+    },
+    [deleteMutation],
+  )
+
+  return {
+    /* 状态 */
+    titles,
+    categories,
+    activeCatId,
+    activeCategory,
+    filteredTitles,
+    searchText,
+    filterType,
+    filterIndustry,
+    filterFrequency,
+    /* mutations */
+    createMutation,
+    updateMutation,
+    deleteMutation,
+    /* setters */
+    setActiveCatId,
+    setSearchText,
+    setFilterType,
+    setFilterIndustry,
+    setFilterFrequency,
+    /* handlers */
+    handleToggleFavorite,
+    handleCopy,
+    handleDelete,
+  }
+}

apps/web/src/pages/titles/hooks/useTitleLibrary/index.ts

@@ -1,55 +0,0 @@
-import { useTitleFilters } from "./useTitleFilters"
-import { useTitleMutations } from "./useTitleMutations"
-import { useTitleData } from "./useTitleData"
-import { useTitleActions } from "./useTitleActions"
-
-export const useTitleLibrary = () => {
-  /* 数据获取与派生 */
-  const { titles, categories, activeCatId, activeCategory, setActiveCatId } = useTitleData()
-
-  /* 筛选 */
-  const {
-    searchText,
-    filterType,
-    filterIndustry,
-    filterFrequency,
-    setSearchText,
-    setFilterType,
-    setFilterIndustry,
-    setFilterFrequency,
-    filteredTitles,
-  } = useTitleFilters(titles, categories, activeCatId, activeCategory)
-
-  /* CRUD mutations */
-  const { createMutation, updateMutation, deleteMutation } = useTitleMutations()
-
-  /* 操作 handlers */
-  const { handleToggleFavorite, handleCopy, handleDelete } = useTitleActions(deleteMutation)
-
-  return {
-    /* 状态 */
-    titles,
-    categories,
-    activeCatId,
-    activeCategory,
-    filteredTitles,
-    searchText,
-    filterType,
-    filterIndustry,
-    filterFrequency,
-    /* mutations */
-    createMutation,
-    updateMutation,
-    deleteMutation,
-    /* setters */
-    setActiveCatId,
-    setSearchText,
-    setFilterType,
-    setFilterIndustry,
-    setFilterFrequency,
-    /* handlers */
-    handleToggleFavorite,
-    handleCopy,
-    handleDelete,
-  }
-}

apps/web/src/pages/titles/hooks/useTitleLibrary/useTitleActions.ts

@@ -1,34 +0,0 @@
-import { useCallback } from "react"
-import { message } from "antd"
-import type { UseMutationResult } from "@tanstack/react-query"
-import type { TitleData } from "../../types/titleLibrary"
-import { copyToClipboard } from "../../utils/titleLibrary"
-
-export const useTitleActions = (
-  deleteMutation: UseMutationResult<void, Error, string, unknown>,
-) => {
-  /* 操作：收藏 */
-  const handleToggleFavorite = useCallback((_id: string) => {
-    message.info("收藏功能即将上线")
-  }, [])
-
-  /* 操作：复制 */
-  const handleCopy = useCallback(async (title: TitleData) => {
-    const ok = await copyToClipboard(title.content)
-    if (ok) {
-      message.success("已复制到剪贴板")
-    } else {
-      message.error("复制失败")
-    }
-  }, [])
-
-  /* 操作：删除 */
-  const handleDelete = useCallback(
-    (id: string) => {
-      deleteMutation.mutate(id)
-    },
-    [deleteMutation],
-  )
-
-  return { handleToggleFavorite, handleCopy, handleDelete }
-}

apps/web/src/pages/titles/hooks/useTitleLibrary/useTitleData.ts

@@ -1,47 +0,0 @@
-import { useMemo, useState } from "react"
-import { useQuery } from "@tanstack/react-query"
-import { getTitles } from "@/api/titles"
-import type { TitleData, CategoryItem } from "../../types/titleLibrary"
-import { toTitleData } from "../../utils/titleLibrary"
-import { ALL_CATEGORY_ID } from "../../constants/titleLibrary"
-
-export const useTitleData = () => {
-  /* 分类 */
-  const [activeCatId, setActiveCatId] = useState<string>(ALL_CATEGORY_ID)
-
-  /* 数据获取 */
-  const { data: apiTitles = [] } = useQuery({
-    queryKey: ["titles"],
-    queryFn: getTitles,
-    staleTime: 30_000,
-  })
-
-  const titles: TitleData[] = useMemo(() => apiTitles.map(toTitleData), [apiTitles])
-
-  /* 动态派生分类 */
-  const categories: CategoryItem[] = useMemo(() => {
-    const cats = new Map<string, number>()
-    apiTitles.forEach((t) => {
-      const cat = t.category || "未分类"
-      cats.set(cat, (cats.get(cat) || 0) + 1)
-    })
-    return [
-      { id: ALL_CATEGORY_ID, name: "全部标题", count: apiTitles.length },
-      ...Array.from(cats.entries()).map(([name, count]) => ({
-        id: `cat-${name}`,
-        name,
-        count,
-      })),
-    ]
-  }, [apiTitles])
-
-  const activeCategory = categories.find((c) => c.id === activeCatId)
-
-  return {
-    titles,
-    categories,
-    activeCatId,
-    activeCategory,
-    setActiveCatId,
-  }
-}

apps/web/src/pages/titles/hooks/useTitleLibrary/useTitleFilters.ts

@@ -1,77 +0,0 @@
-import { useMemo, useState } from "react"
-import type { TitleData, CategoryItem, Frequency } from "../../types/titleLibrary"
-import { ALL_CATEGORY_ID, FREQUENCY_THRESHOLDS } from "../../constants/titleLibrary"
-
-export const useTitleFilters = (
-  titles: TitleData[],
-  _categories: CategoryItem[],
-  activeCatId: string,
-  activeCategory: CategoryItem | undefined,
-) => {
-  const [searchText, setSearchText] = useState("")
-  const [filterType, setFilterType] = useState<string>("all")
-  const [filterIndustry, setFilterIndustry] = useState<string>("all")
-  const [filterFrequency, setFilterFrequency] = useState<Frequency>("all")
-
-  /* 派生：筛选后的标题列表 */
-  const filteredTitles = useMemo(() => {
-    let list = titles
-
-    /* 按分类过滤 */
-    if (activeCatId !== ALL_CATEGORY_ID) {
-      const catName = activeCategory?.name || ""
-      if (catName) {
-        list = list.filter((t) => t.category === catName)
-      }
-    }
-
-    /* 按类型筛选 */
-    if (filterType !== "all") {
-      list = list.filter((t) => t.type === filterType)
-    }
-
-    /* 按行业筛选 */
-    if (filterIndustry !== "all") {
-      list = list.filter((t) => t.industry === filterIndustry)
-    }
-
-    /* 按使用频率筛选 */
-    if (filterFrequency !== "all") {
-      switch (filterFrequency) {
-        case "high":
-          list = list.filter((t) => t.usageCount >= FREQUENCY_THRESHOLDS.high)
-          break
-        case "medium":
-          list = list.filter(
-            (t) =>
-              t.usageCount >= FREQUENCY_THRESHOLDS.medium &&
-              t.usageCount < FREQUENCY_THRESHOLDS.high,
-          )
-          break
-        case "low":
-          list = list.filter((t) => t.usageCount < FREQUENCY_THRESHOLDS.medium)
-          break
-      }
-    }
-
-    /* 搜索 */
-    if (searchText.trim()) {
-      const q = searchText.trim().toLowerCase()
-      list = list.filter((t) => t.content.toLowerCase().includes(q))
-    }
-
-    return list
-  }, [titles, activeCatId, activeCategory, filterType, filterIndustry, filterFrequency, searchText])
-
-  return {
-    searchText,
-    setSearchText,
-    filterType,
-    setFilterType,
-    filterIndustry,
-    setFilterIndustry,
-    filterFrequency,
-    setFilterFrequency,
-    filteredTitles,
-  }
-}

apps/web/src/pages/titles/hooks/useTitleLibrary/useTitleMutations.ts

@@ -1,34 +0,0 @@
-import { useMutation, useQueryClient } from "@tanstack/react-query"
-import { message } from "antd"
-import { createTitle, updateTitle, deleteTitle } from "@/api/titles"
-
-export const useTitleMutations = () => {
-  const queryClient = useQueryClient()
-
-  const createMutation = useMutation({
-    mutationFn: (content: string) => createTitle({ content }),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["titles"] })
-    },
-    onError: () => message.error("创建标题失败"),
-  })
-
-  const updateMutation = useMutation({
-    mutationFn: ({ id, content }: { id: string; content: string }) => updateTitle(id, { content }),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["titles"] })
-    },
-    onError: () => message.error("更新标题失败"),
-  })
-
-  const deleteMutation = useMutation({
-    mutationFn: (id: string) => deleteTitle(id),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["titles"] })
-      message.success("标题已删除")
-    },
-    onError: () => message.error("删除标题失败"),
-  })
-
-  return { createMutation, updateMutation, deleteMutation }
-}

apps/web/src/test/pages/products/smoke.test.tsx

@@ -21,8 +21,6 @@ import "@/pages/products/components/VideoPlayer"
 
 // Hooks
 import "@/pages/products/hooks/useProductList"
-import "@/pages/products/hooks/useProductList/useProductFiltering"
-import "@/pages/products/hooks/useProductList/useBatchSelection"
 import "@/pages/products/hooks/useProductActions"
 import "@/pages/products/hooks/useVideoPlayer"
 

apps/web/src/test/pages/titles/smoke.test.tsx

@@ -1,29 +0,0 @@
-/**
- * TitleLibrary 模块 smoke test
- * 建立完整依赖链，确保 vitest related 模式能匹配到
- * titles 目录下所有文件的改动
- */
-import { describe, it, expect } from "vitest"
-
-// 主组件
-import "@/pages/titles/TitleLibrary"
-
-// Hooks
-import "@/pages/titles/hooks/useTitleLibrary"
-import "@/pages/titles/hooks/useTitleLibrary/useTitleData"
-import "@/pages/titles/hooks/useTitleLibrary/useTitleFilters"
-import "@/pages/titles/hooks/useTitleLibrary/useTitleMutations"
-import "@/pages/titles/hooks/useTitleLibrary/useTitleActions"
-
-// 类型与常量
-import "@/pages/titles/types/titleLibrary"
-import "@/pages/titles/constants/titleLibrary"
-
-// 工具函数
-import "@/pages/titles/utils/titleLibrary"
-
-describe("TitleLibrary module smoke test", () => {
-  it("should load all title modules", () => {
-    expect(true).toBe(true)
-  })
-})

scripts/ci/pr_auto_scan.py

@@ -32,13 +32,7 @@ def api_request(token, repo, endpoint, method="GET", data=None):
         resp = urllib.request.urlopen(req, context=ctx)
         return json.loads(resp.read().decode()), resp.status
     except urllib.error.HTTPError as e:
-        body = e.read().decode()
-        if body:
-            try:
-                return json.loads(body), e.code
-            except json.JSONDecodeError:
-                return {"error": body}, e.code
-        return {"error": str(e)}, e.code
+        return json.loads(e.read().decode()) if e.read() else {"error": str(e)}, e.code
 
 
 def get_open_prs(token, repo, base="develop"):
@@ -275,9 +269,13 @@ def main():
 
     # required contexts（与分支保护一致）
     REQUIRED_CONTEXTS_FULL = [
-        # 统一使用CI Gate作为合并门禁（与pr-automation和分支保护保持一致）
-        # CI Gate内部已包含: 代码质量/类型检查/迁移检查/单测/集成测试/前端Lint/前端单测/构建/AI审查
-        "CI/CD Pipeline / CI Gate (pull_request)",
+        "CI/CD Pipeline / Validate - Code Quality (pull_request)",
+        "CI/CD Pipeline / Validate - Type Check (mypy) (pull_request)",
+        "CI/CD Pipeline / Validate - Migration (alembic) (pull_request)",
+        "CI/CD Pipeline / Frontend Lint (pull_request)",
+        "CI/CD Pipeline / PR Build API Image (pull_request)",
+        "CI/CD Pipeline / PR Build Worker Image (pull_request)",
+        "CI/CD Pipeline / PR Build Web Image (pull_request)",
     ]
     REQUIRED_CONTEXTS_APPROVE = [
         "CI/CD Pipeline / Validate - Code Quality (pull_request)",
@@ -286,8 +284,7 @@ def main():
         "CI/CD Pipeline / Frontend Lint (pull_request)",
     ]
     FRONTEND_ONLY_CONTEXT = [
-        # 纯前端PR也用CI Gate统一判断，内部自动跳过后端相关检查
-        "CI/CD Pipeline / CI Gate (pull_request)",
+        "CI/CD Pipeline / Frontend Lint (pull_request)",
     ]
 
     # 获取所有open PR

tests/unit/test_verification_code_service.py

@@ -1,6 +1,7 @@
 """验证码服务单元测试."""
 
-import re
+from __future__ import annotations
+
 from datetime import datetime, timedelta, timezone
 from unittest.mock import MagicMock
 
@@ -8,9 +9,9 @@ import pytest
 
 from packages.application.auth.verification_code_service import (
     CODE_TYPE_EMAIL_BIND,
-    CODE_TYPE_EMAIL_LOGIN,
     CODE_TYPE_PHONE_BIND,
     DAILY_LIMIT,
+    DEFAULT_TTL_SECONDS,
     MAX_ATTEMPTS,
     RESEND_COOLDOWN_SECONDS,
     VerificationCodeService,
@@ -20,560 +21,298 @@ from packages.application.auth.verification_code_service import (
 )
 from packages.domain.verification_code import VerificationCode
 
-# ── Test Fixtures ────────────────────────────────────────────────────────────
-
 
 @pytest.fixture
 def mock_repo():
-    """mock 验证码仓储."""
-    repo = MagicMock()
-    repo.find_latest.return_value = None
-    repo.count_today.return_value = 0
-    return repo
+    return MagicMock()
 
 
 @pytest.fixture
-def service(mock_repo):
-    """验证码服务实例."""
-    return VerificationCodeService(repo=mock_repo)
+def code_service(mock_repo):
+    return VerificationCodeService(mock_repo)
 
 
-def _make_code(
-    recipient="test@example.com",
-    code_type=CODE_TYPE_EMAIL_BIND,
-    code="123456",
-    ttl=300,
-    used=False,
-    attempts=0,
-    created_at=None,
-):
-    """创建一个测试用验证码实体."""
-    now = created_at or datetime.now(timezone.utc)
-    vc = VerificationCode(
-        id="test-code-id",
-        recipient=recipient,
-        code=code,
-        code_type=code_type,
-        expires_at=now + timedelta(seconds=ttl),
-        used_at=now if used else None,
-        attempts=attempts,
-        created_at=now,
+@pytest.fixture
+def sample_code():
+    code = VerificationCode.create(
+        recipient="test@example.com",
+        code_type=CODE_TYPE_EMAIL_BIND,
+        ttl_seconds=300,
     )
-    return vc
+    return code
 
 
-# ── generate 方法测试 ───────────────────────────────────────────────────────
-
-
-class TestGenerate:
+class TestVerificationCodeServiceGenerate:
     """generate 方法测试"""
 
-    def test_generate_success(self, service, mock_repo):
-        """成功生成验证码."""
-        code, error = service.generate("user@example.com", CODE_TYPE_EMAIL_BIND)
+    def test_generate_success(self, code_service, mock_repo, sample_code):
+        """生成验证码成功"""
+        mock_repo.find_latest.return_value = None
+        mock_repo.count_today.return_value = 0
+        mock_repo.save.return_value = None
+
+        code, error = code_service.generate("test@example.com", CODE_TYPE_EMAIL_BIND)
 
         assert error is None
         assert code is not None
-        assert code.recipient == "user@example.com"
+        assert code.recipient == "test@example.com"
         assert code.code_type == CODE_TYPE_EMAIL_BIND
-        assert len(code.code) == 6
-        assert code.code.isdigit()
-        assert not code.is_used
         mock_repo.save.assert_called_once()
 
-    def test_generate_with_custom_code(self, service, mock_repo):
-        """使用自定义验证码."""
-        code, error = service.generate("user@example.com", CODE_TYPE_EMAIL_LOGIN, custom_code="999999")
-
-        assert error is None
-        assert code.code == "999999"
-
-    def test_generate_custom_ttl(self, service, mock_repo):
-        """自定义 TTL."""
-        code, _ = service.generate("u@e.com", CODE_TYPE_EMAIL_BIND, ttl_seconds=600)
-        delta = code.expires_at - code.created_at
-        assert delta.total_seconds() == 600
-
-    def test_generate_default_ttl(self, service, mock_repo):
-        """默认 TTL."""
-        code, _ = service.generate("u@e.com", CODE_TYPE_EMAIL_BIND)
-        delta = code.expires_at - code.created_at
-        assert delta.total_seconds() == 300  # 默认5分钟
-
-    def test_generate_empty_recipient(self, service):
-        """空接收方."""
-        code, error = service.generate("", CODE_TYPE_EMAIL_BIND)
+    def test_generate_empty_recipient(self, code_service):
+        """空接收方返回错误"""
+        code, error = code_service.generate("", CODE_TYPE_EMAIL_BIND)
         assert code is None
-        assert "不能为空" in error
+        assert "接收方不能为空" in error
 
-    def test_generate_whitespace_recipient(self, service):
-        """全空白接收方."""
-        code, error = service.generate("   ", CODE_TYPE_EMAIL_BIND)
-        assert code is None
-        assert "不能为空" in error
-
-    def test_generate_invalid_type(self, service):
-        """无效验证码类型."""
-        code, error = service.generate("u@e.com", "invalid_type")
+    def test_generate_invalid_type(self, code_service):
+        """无效验证码类型返回错误"""
+        code, error = code_service.generate("test@example.com", "invalid_type")
         assert code is None
         assert "无效的验证码类型" in error
 
-    def test_generate_recipient_stripped(self, service, mock_repo):
-        """接收方前后空格会被清理."""
-        code, _ = service.generate("  user@e.com  ", CODE_TYPE_EMAIL_BIND)
-        assert code.recipient == "user@e.com"
-
-    def test_generate_phone_code(self, service, mock_repo):
-        """手机验证码生成."""
-        code, error = service.generate("13800138000", CODE_TYPE_PHONE_BIND)
-        assert error is None
-        assert code.code_type == CODE_TYPE_PHONE_BIND
-        assert len(code.code) == 6
-
-
-# ── generate 频控测试 ───────────────────────────────────────────────────────
-
-
-class TestGenerateRateLimit:
-    """generate 频控测试"""
-
-    def test_cooldown_active_rejects(self, service, mock_repo):
-        """冷却期内拒绝重发."""
-        recent = _make_code(created_at=datetime.now(timezone.utc) - timedelta(seconds=10))
-        mock_repo.find_latest.return_value = recent
-
-        code, error = service.generate("u@e.com", CODE_TYPE_EMAIL_BIND)
-        assert code is None
-        assert "发送太频繁" in error
-        # 等待时间应该接近 50 秒 (60-10)
-        match = re.search(r"(\d+)\s*秒", error)
-        assert match
-        wait = int(match.group(1))
-        assert 45 <= wait <= 55
-
-    def test_cooldown_expired_allows(self, service, mock_repo):
-        """冷却期过后允许重发."""
-        old = _make_code(created_at=datetime.now(timezone.utc) - timedelta(seconds=120))
-        mock_repo.find_latest.return_value = old
+    def test_generate_cooldown(self, code_service, mock_repo, sample_code):
+        """冷却期内返回频控错误"""
+        # 最新的验证码刚创建10秒前
+        sample_code.created_at = datetime.now(timezone.utc) - timedelta(seconds=10)
+        mock_repo.find_latest.return_value = sample_code
         mock_repo.count_today.return_value = 1
 
-        code, error = service.generate("u@e.com", CODE_TYPE_EMAIL_BIND)
-        assert error is None
-        assert code is not None
+        code, error = code_service.generate("test@example.com", CODE_TYPE_EMAIL_BIND)
 
-    def test_daily_limit_reached(self, service, mock_repo):
-        """达到每日上限."""
-        mock_repo.find_latest.return_value = None
+        assert code is None
+        assert "发送太频繁" in error
+        assert "秒后再试" in error
+
+    def test_generate_daily_limit_exceeded(self, code_service, mock_repo):
+        """超过每日上限返回错误"""
+        mock_repo.find_latest.return_value = None  # 没有冷却期问题
         mock_repo.count_today.return_value = DAILY_LIMIT
 
-        code, error = service.generate("u@e.com", CODE_TYPE_EMAIL_BIND)
+        code, error = code_service.generate("test@example.com", CODE_TYPE_EMAIL_BIND)
+
         assert code is None
         assert "今日发送次数已达上限" in error
 
-    def test_daily_limit_one_below_allows(self, service, mock_repo):
-        """未达到上限时允许."""
+    def test_generate_recipient_stripped(self, code_service, mock_repo, sample_code):
+        """recipient 会被 strip"""
         mock_repo.find_latest.return_value = None
-        mock_repo.count_today.return_value = DAILY_LIMIT - 1
-
-        code, error = service.generate("u@e.com", CODE_TYPE_EMAIL_BIND)
-        assert error is None
-        assert code is not None
-
-    def test_custom_daily_limit(self, mock_repo):
-        """自定义每日上限."""
-        svc = VerificationCodeService(repo=mock_repo, daily_limit=3)
-        mock_repo.count_today.return_value = 3
-
-        code, error = svc.generate("u@e.com", CODE_TYPE_EMAIL_BIND)
-        assert code is None
-        assert "已达上限" in error
-
-    def test_custom_cooldown(self, mock_repo):
-        """自定义冷却时间."""
-        svc = VerificationCodeService(repo=mock_repo, resend_cooldown=30)
-        recent = _make_code(created_at=datetime.now(timezone.utc) - timedelta(seconds=10))
-        mock_repo.find_latest.return_value = recent
-
-        code, error = svc.generate("u@e.com", CODE_TYPE_EMAIL_BIND)
-        assert code is None
-        match = re.search(r"(\d+)\s*秒", error)
-        assert match
-        wait = int(match.group(1))
-        assert 15 <= wait <= 25
-
-    def test_cooldown_different_types_independent(self, service, mock_repo):
-        """不同类型的验证码冷却独立."""
-        # email_bind 类型有一个近期验证码
-        recent = _make_code(code_type=CODE_TYPE_EMAIL_BIND)
-        mock_repo.find_latest.side_effect = lambda r, t: recent if t == CODE_TYPE_EMAIL_BIND else None
         mock_repo.count_today.return_value = 0
+        mock_repo.save.return_value = None
 
-        # email_login 类型应该可以正常发送
-        code, error = service.generate("u@e.com", CODE_TYPE_EMAIL_LOGIN)
-        assert error is None
+        code_service.generate("  test@example.com  ", CODE_TYPE_EMAIL_BIND)
+
+        # 传给 repo 的应该是 strip 后的值
+        save_call = mock_repo.save.call_args[0][0]
+        assert save_call.recipient == "test@example.com"
+
+    def test_generate_custom_code(self, code_service, mock_repo):
+        """使用自定义验证码"""
+        mock_repo.find_latest.return_value = None
+        mock_repo.count_today.return_value = 0
+        mock_repo.save.return_value = None
+
+        code, _ = code_service.generate("test@example.com", CODE_TYPE_EMAIL_BIND, custom_code="123456")
+        assert code.code == "123456"
+
+    def test_generate_custom_ttl(self, code_service, mock_repo):
+        """自定义 TTL"""
+        mock_repo.find_latest.return_value = None
+        mock_repo.count_today.return_value = 0
+        mock_repo.save.return_value = None
+
+        code, _ = code_service.generate("test@example.com", CODE_TYPE_EMAIL_BIND, ttl_seconds=600)
         assert code is not None
 
 
-# ── verify 方法测试 ─────────────────────────────────────────────────────────
-
-
-class TestVerify:
+class TestVerificationCodeServiceVerify:
     """verify 方法测试"""
 
-    def test_verify_success(self, service, mock_repo):
-        """验证码正确."""
-        code = _make_code(code="654321")
-        mock_repo.find_latest.return_value = code
+    def test_verify_success(self, code_service, mock_repo, sample_code):
+        """验证成功"""
+        mock_repo.find_latest.return_value = sample_code
 
-        ok, error = service.verify("test@example.com", CODE_TYPE_EMAIL_BIND, "654321")
-        assert ok is True
+        success, error = code_service.verify("test@example.com", CODE_TYPE_EMAIL_BIND, sample_code.code)
+
+        assert success is True
         assert error is None
-        assert code.is_used  # 标记为已使用
-        assert mock_repo.save.call_count >= 2  # increment + mark_used
+        assert sample_code.is_used is True
 
-    def test_verify_wrong_code(self, service, mock_repo):
-        """验证码错误."""
-        code = _make_code(code="123456")
-        mock_repo.find_latest.return_value = code
+    def test_verify_wrong_code(self, code_service, mock_repo, sample_code):
+        """验证码错误"""
+        mock_repo.find_latest.return_value = sample_code
 
-        ok, error = service.verify("test@e.com", CODE_TYPE_EMAIL_BIND, "000000")
-        assert ok is False
+        success, error = code_service.verify("test@example.com", CODE_TYPE_EMAIL_BIND, "wrongcode")
+
+        assert success is False
         assert "验证码错误" in error
-        assert not code.is_used  # 不标记为已使用
-        assert code.attempts == 1  # 尝试次数+1
 
-    def test_verify_no_code_found(self, service, mock_repo):
-        """找不到验证码."""
+    def test_verify_not_found(self, code_service, mock_repo):
+        """验证码不存在"""
         mock_repo.find_latest.return_value = None
 
-        ok, error = service.verify("u@e.com", CODE_TYPE_EMAIL_BIND, "123456")
-        assert ok is False
+        success, error = code_service.verify("test@example.com", CODE_TYPE_EMAIL_BIND, "123456")
+
+        assert success is False
         assert "不存在或已过期" in error
 
-    def test_verify_empty_params(self, service):
-        """参数为空."""
-        ok, error = service.verify("", CODE_TYPE_EMAIL_BIND, "123456")
-        assert ok is False
-        assert "参数不完整" in error
+    def test_verify_expired(self, code_service, mock_repo):
+        """验证码已过期"""
+        expired_code = VerificationCode.create(
+            recipient="test@example.com",
+            code_type=CODE_TYPE_EMAIL_BIND,
+            ttl_seconds=1,  # 1秒过期
+        )
+        # 手动设置过期时间
+        expired_code.expires_at = datetime.now(timezone.utc) - timedelta(seconds=10)
+        mock_repo.find_latest.return_value = expired_code
 
-        ok2, error2 = service.verify("u@e.com", CODE_TYPE_EMAIL_BIND, "")
-        assert ok2 is False
-        assert "参数不完整" in error2
+        success, error = code_service.verify("test@example.com", CODE_TYPE_EMAIL_BIND, expired_code.code)
 
-    def test_verify_whitespace_params(self, service, mock_repo):
-        """参数前后空格会被清理."""
-        code = _make_code(recipient="u@e.com", code="111111")
-        mock_repo.find_latest.return_value = code
-
-        ok, error = service.verify("  u@e.com  ", CODE_TYPE_EMAIL_BIND, "  111111  ")
-        assert ok is True
-        assert error is None
-
-    def test_verify_already_used(self, service, mock_repo):
-        """验证码已使用."""
-        code = _make_code(used=True)
-        mock_repo.find_latest.return_value = code
-
-        ok, error = service.verify("u@e.com", CODE_TYPE_EMAIL_BIND, code.code)
-        assert ok is False
-        assert "已使用" in error
-
-    def test_verify_expired(self, service, mock_repo):
-        """验证码已过期."""
-        code = _make_code(ttl=-60)  # 已过期
-        mock_repo.find_latest.return_value = code
-
-        ok, error = service.verify("u@e.com", CODE_TYPE_EMAIL_BIND, code.code)
-        assert ok is False
+        assert success is False
         assert "已过期" in error
 
-    def test_verify_too_many_attempts(self, service, mock_repo):
-        """尝试次数过多."""
-        code = _make_code(attempts=MAX_ATTEMPTS + 1)
-        mock_repo.find_latest.return_value = code
+    def test_verify_already_used(self, code_service, mock_repo, sample_code):
+        """验证码已使用"""
+        sample_code.mark_used()
+        mock_repo.find_latest.return_value = sample_code
 
-        ok, error = service.verify("u@e.com", CODE_TYPE_EMAIL_BIND, code.code)
-        assert ok is False
-        assert "验证次数过多" in error
+        success, error = code_service.verify("test@example.com", CODE_TYPE_EMAIL_BIND, sample_code.code)
 
-    def test_verify_attempts_increment_each_time(self, service, mock_repo):
-        """每次错误尝试都增加尝试次数."""
-        code = _make_code(code="123456", attempts=0)
-        mock_repo.find_latest.return_value = code
-
-        for _ in range(3):
-            service.verify("u@e.com", CODE_TYPE_EMAIL_BIND, "wrong")
-
-        assert code.attempts == 3
-
-    def test_verify_without_consume(self, service, mock_repo):
-        """验证成功但不标记为已使用（consume=False）."""
-        code = _make_code(code="999999")
-        mock_repo.find_latest.return_value = code
-
-        ok, error = service.verify("u@e.com", CODE_TYPE_EMAIL_BIND, "999999", consume=False)
-        assert ok is True
-        assert error is None
-        assert not code.is_used  # 不标记为已使用
-
-    def test_verify_consume_default_true(self, service, mock_repo):
-        """默认 consume=True."""
-        code = _make_code(code="123456")
-        mock_repo.find_latest.return_value = code
-
-        service.verify("u@e.com", CODE_TYPE_EMAIL_BIND, "123456")
-        assert code.is_used
-
-    def test_verify_used_checked_before_attempts(self, service, mock_repo):
-        """已使用优先于其他检查."""
-        code = _make_code(used=True, attempts=0)
-        mock_repo.find_latest.return_value = code
-
-        ok, error = service.verify("u@e.com", CODE_TYPE_EMAIL_BIND, code.code)
-        assert ok is False
+        assert success is False
         assert "已使用" in error
-        # attempts 会被 increment，但错误原因是已使用
-        assert code.attempts == 1
 
-    def test_custom_max_attempts(self, mock_repo):
-        """自定义最大尝试次数."""
-        svc = VerificationCodeService(repo=mock_repo, max_attempts=2)
-        code = _make_code(attempts=2)
-        mock_repo.find_latest.return_value = code
+    def test_verify_max_attempts_exceeded(self, code_service, mock_repo, sample_code):
+        """尝试次数过多"""
+        # 先把尝试次数加到超过上限
+        for _ in range(MAX_ATTEMPTS + 1):
+            sample_code.increment_attempts()
+        mock_repo.find_latest.return_value = sample_code
 
-        ok, error = svc.verify("u@e.com", CODE_TYPE_EMAIL_BIND, code.code)
-        assert ok is False
+        success, error = code_service.verify("test@example.com", CODE_TYPE_EMAIL_BIND, sample_code.code)
+
+        assert success is False
         assert "验证次数过多" in error
 
+    def test_verify_empty_params(self, code_service):
+        """空参数返回错误"""
+        success, error = code_service.verify("", CODE_TYPE_EMAIL_BIND, "123456")
+        assert success is False
+        assert "参数不完整" in error
 
-# ── validate_phone 测试 ─────────────────────────────────────────────────────
+        success, error = code_service.verify("test@example.com", CODE_TYPE_EMAIL_BIND, "")
+        assert success is False
+        assert "参数不完整" in error
+
+    def test_verify_increments_attempts(self, code_service, mock_repo, sample_code):
+        """验证会增加尝试次数"""
+        initial_attempts = sample_code.attempts
+        mock_repo.find_latest.return_value = sample_code
+
+        code_service.verify("test@example.com", CODE_TYPE_EMAIL_BIND, "wrong")
+
+        assert sample_code.attempts == initial_attempts + 1
+
+    def test_verify_no_consume(self, code_service, mock_repo, sample_code):
+        """consume=False 时不标记为已使用"""
+        mock_repo.find_latest.return_value = sample_code
+
+        success, _ = code_service.verify("test@example.com", CODE_TYPE_EMAIL_BIND, sample_code.code, consume=False)
+
+        assert success is True
+        assert sample_code.is_used is False
 
 
-class TestValidatePhone:
-    """手机号格式校验测试"""
+class TestVerifyPhone:
+    """validate_phone 函数测试"""
 
-    def test_valid_11_digit(self):
-        """标准11位手机号."""
-        ok, msg = validate_phone("13800138000")
+    def test_valid_phone(self):
+        """有效手机号"""
+        ok, err = validate_phone("13800000001")
         assert ok is True
-        assert msg == ""
+        assert err == ""
 
-    def test_valid_with_plus_86(self):
-        """带+86前缀."""
-        ok, msg = validate_phone("+8613800138000")
+    def test_valid_phone_with_plus86(self):
+        """带 +86 前缀的手机号"""
+        ok, err = validate_phone("+8613800000001")
         assert ok is True
 
-    def test_invalid_too_short(self):
-        """位数不足."""
-        ok, msg = validate_phone("1380013800")
+    def test_invalid_phone_short(self):
+        """太短的手机号"""
+        ok, err = validate_phone("123")
         assert ok is False
-        assert "格式不正确" in msg
+        assert "格式不正确" in err
 
-    def test_invalid_too_long(self):
-        """位数过多."""
-        ok, msg = validate_phone("138001380001")
+    def test_invalid_phone_wrong_prefix(self):
+        """号段不对的手机号"""
+        ok, err = validate_phone("11000000000")
         assert ok is False
 
-    def test_invalid_starts_with_2(self):
-        """开头不是1."""
-        ok, msg = validate_phone("23800138000")
+    def test_empty_phone(self):
+        """空手机号"""
+        ok, err = validate_phone("")
         assert ok is False
+        assert "不能为空" in err
 
-    def test_invalid_starts_with_12(self):
-        """第二位不在3-9."""
-        ok, msg = validate_phone("12800138000")
-        assert ok is False
-
-    def test_invalid_empty(self):
-        """空字符串."""
-        ok, msg = validate_phone("")
-        assert ok is False
-        assert "不能为空" in msg
-
-    def test_invalid_whitespace_only(self):
-        """仅空白."""
-        ok, msg = validate_phone("   ")
-        assert ok is False
-        assert "不能为空" in msg
-
-    def test_valid_all_prefixes_3_to_9(self):
-        """第二位3-9都有效."""
-        for n in range(3, 10):
-            ok, _ = validate_phone(f"1{n}800138000")
-            assert ok is True, f"1{n} prefix should be valid"
-
-    def test_invalid_contains_letters(self):
-        """包含字母."""
-        ok, msg = validate_phone("13800abc000")
-        assert ok is False
-
-    def test_strips_whitespace(self):
-        """前后空格会被清理."""
-        ok, msg = validate_phone("  13800138000  ")
+    def test_phone_with_spaces(self):
+        """带空格的手机号会被 strip"""
+        ok, _ = validate_phone("  13800000001  ")
         assert ok is True
 
 
-# ── normalize_phone 测试 ────────────────────────────────────────────────────
-
-
 class TestNormalizePhone:
-    """手机号标准化测试"""
+    """normalize_phone 函数测试"""
 
-    def test_strip_plus_86(self):
-        """去掉+86前缀."""
-        assert normalize_phone("+8613800138000") == "13800138000"
+    def test_removes_plus86(self):
+        """去掉 +86 前缀"""
+        assert normalize_phone("+8613800000001") == "13800000001"
 
     def test_no_prefix_stays_same(self):
-        """无前缀保持不变."""
-        assert normalize_phone("13800138000") == "13800138000"
+        """没有前缀保持不变"""
+        assert normalize_phone("13800000001") == "13800000001"
 
     def test_strips_whitespace(self):
-        """清理前后空格."""
-        assert normalize_phone("  13800138000  ") == "13800138000"
-
-    def test_plus_86_with_spaces(self):
-        """带空格的+86."""
-        assert normalize_phone("  +8613800138000  ") == "13800138000"
-
-
-# ── validate_email 测试 ─────────────────────────────────────────────────────
+        """去掉两端空白"""
+        assert normalize_phone("  13800000001  ") == "13800000001"
 
 
 class TestValidateEmail:
-    """邮箱格式校验测试"""
+    """validate_email 函数测试"""
 
-    def test_valid_simple(self):
-        """标准邮箱."""
-        ok, msg = validate_email("user@example.com")
+    def test_valid_email(self):
+        """有效邮箱"""
+        ok, err = validate_email("test@example.com")
         assert ok is True
-        assert msg == ""
+        assert err == ""
 
-    def test_valid_with_dots(self):
-        """带点号的用户名."""
-        ok, _ = validate_email("user.name@example.com")
-        assert ok is True
-
-    def test_valid_with_plus(self):
-        """带加号的邮箱."""
-        ok, _ = validate_email("user+tag@example.com")
-        assert ok is True
-
-    def test_valid_with_underscore(self):
-        """带下划线."""
-        ok, _ = validate_email("user_name@example.com")
-        assert ok is True
-
-    def test_valid_subdomain(self):
-        """多级域名."""
+    def test_valid_email_with_subdomain(self):
+        """带子域名的邮箱"""
         ok, _ = validate_email("user@mail.example.com")
         assert ok is True
 
-    def test_invalid_no_at(self):
-        """没有@."""
-        ok, msg = validate_email("userexample.com")
-        assert ok is False
-        assert "格式不正确" in msg
-
-    def test_invalid_empty_local(self):
-        """@前为空."""
-        ok, _ = validate_email("@example.com")
-        assert ok is False
-
-    def test_invalid_empty_domain(self):
-        """@后为空."""
-        ok, _ = validate_email("user@")
-        assert ok is False
-
-    def test_invalid_no_tld(self):
-        """没有顶级域名."""
-        ok, _ = validate_email("user@example")
-        assert ok is False
-
-    def test_invalid_empty(self):
-        """空字符串."""
-        ok, msg = validate_email("")
-        assert ok is False
-        assert "不能为空" in msg
-
-    def test_invalid_spaces_only(self):
-        """仅空白."""
-        ok, msg = validate_email("   ")
-        assert ok is False
-        assert "不能为空" in msg
-
-    def test_strips_whitespace(self):
-        """前后空格会被清理."""
-        ok, msg = validate_email("  user@e.com  ")
+    def test_valid_email_with_plus(self):
+        """带 + 号的邮箱"""
+        ok, _ = validate_email("user+tag@example.com")
         assert ok is True
 
-    def test_invalid_special_chars(self):
-        """特殊字符."""
-        ok, _ = validate_email("user name@e.com")
+    def test_invalid_email_no_at(self):
+        """没有 @ 的邮箱"""
+        ok, err = validate_email("notanemail")
+        assert ok is False
+        assert "格式不正确" in err
+
+    def test_invalid_email_no_domain(self):
+        """没有域名的邮箱"""
+        ok, err = validate_email("user@")
         assert ok is False
 
-    def test_valid_numbers(self):
-        """数字邮箱."""
-        ok, _ = validate_email("12345@example.com")
+    def test_empty_email(self):
+        """空邮箱"""
+        ok, err = validate_email("")
+        assert ok is False
+        assert "不能为空" in err
+
+    def test_email_with_spaces(self):
+        """带空格的邮箱会被 strip"""
+        ok, _ = validate_email("  test@example.com  ")
         assert ok is True
-
-
-# ── VerificationCode 实体辅助验证 ──────────────────────────────────────────
-
-
-class TestVerificationCodeEntity:
-    """VerificationCode 实体属性测试"""
-
-    def test_is_expired_false_when_fresh(self):
-        code = _make_code(ttl=300)
-        assert code.is_expired is False
-
-    def test_is_expired_true_when_past(self):
-        code = _make_code(ttl=-1)
-        assert code.is_expired is True
-
-    def test_is_used_false_initially(self):
-        code = _make_code()
-        assert code.is_used is False
-
-    def test_is_used_after_mark_used(self):
-        code = _make_code()
-        code.mark_used()
-        assert code.is_used is True
-        assert code.used_at is not None
-
-    def test_is_valid_fresh(self):
-        code = _make_code()
-        assert code.is_valid is True
-
-    def test_is_valid_when_expired(self):
-        code = _make_code(ttl=-100)
-        assert code.is_valid is False
-
-    def test_is_valid_when_used(self):
-        code = _make_code(used=True)
-        assert code.is_valid is False
-
-    def test_increment_attempts(self):
-        code = _make_code(attempts=0)
-        code.increment_attempts()
-        assert code.attempts == 1
-        code.increment_attempts()
-        assert code.attempts == 2
-
-    def test_create_generates_6_digit_code(self):
-        code = VerificationCode.create("u@e.com", CODE_TYPE_EMAIL_BIND)
-        assert len(code.code) == 6
-        assert code.code.isdigit()
-
-    def test_create_custom_code(self):
-        code = VerificationCode.create("u@e.com", CODE_TYPE_EMAIL_BIND, custom_code="555555")
-        assert code.code == "555555"
-
-    def test_create_strips_recipient(self):
-        code = VerificationCode.create("  u@e.com  ", CODE_TYPE_EMAIL_BIND)
-        assert code.recipient == "u@e.com"
-
-    def test_create_sets_expiry(self):
-        code = VerificationCode.create("u@e.com", CODE_TYPE_EMAIL_BIND, ttl_seconds=120)
-        delta = code.expires_at - code.created_at
-        assert delta.total_seconds() == 120