# 组件化重构专项实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 拆分 9 个巨型文件、收敛 49 个重复组件到共享底座、补全 ErrorBoundary/StatsGrid/SkeletonCard 底座

**Architecture:** 两阶段 — Phase 1 收敛+补全底座（ErrorBoundary 抽取 + StatsGrid/SkeletonCard 新增），Phase 2 按模块垂直闭环（3 批风险分级：低/中/高）

**Tech Stack:** Next.js 16 / React 19 / TypeScript strict / Tailwind v4 / next-intl / shadcn/ui

**Spec:** `docs/superpowers/specs/2026-07-06-component-refactoring-design.md`

---

## 文件结构总览

### Phase 1 新增/修改文件

| 文件 | 操作 | 职责 |
|------|------|------|
| `src/shared/components/ui/error-boundary.tsx` | 新增 | 基础 ErrorBoundary 类组件（从 section-error-boundary.tsx 抽取） |
| `src/shared/components/ui/stats-grid.tsx` | 新增 | StatsGrid 容器，基于 StatCard 渲染网格 |
| `src/shared/components/ui/skeleton.tsx` | 扩展 | 新增 SkeletonCard variant（保留原 Skeleton 原语） |
| `src/shared/components/section-error-boundary.tsx` | 修改 | 内部改用 ErrorBoundary 基础组件 |
| `src/shared/components/route-error.tsx` | 修改 | 内部改用 ErrorBoundary 基础组件 |
| `src/shared/components/widget-boundary.tsx` | 修改 | 内部改用 ErrorBoundary 基础组件 |

### Phase 2 模块层（按批次）

每批次删除模块层 `*-filters.tsx`/`*-stats-cards.tsx`/`*-skeleton.tsx`/`*-error-boundary.tsx`，迁移到底座。巨型文件拆为容器+子组件。

---

## Phase 1：底座收敛与补全

### Task 1: 抽取 ErrorBoundary 基础组件

**Files:**
- Create: `src/shared/components/ui/error-boundary.tsx`

- [ ] **Step 1: 创建 error-boundary.tsx**

```tsx
"use client"

import { Component, type ErrorInfo, type ReactNode } from "react"

/**
 * 基础 ErrorBoundary 类组件。
 * 不直接使用，请使用 SectionErrorBoundary / RouteErrorBoundary / WidgetBoundary 等 preset。
 *
 * 支持两种降级形式：
 * 1. `fallback`（函数 `(error, reset) => ReactNode`）— 完全自定义降级 UI（优先级最高）
 * 2. `fallback`（ReactNode）— 静态降级 UI
 */
interface ErrorBoundaryProps {
  children: ReactNode
  /** 自定义降级 UI：可为静态 ReactNode 或函数式 (error, reset) => ReactNode */
  fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode)
  /** 错误回调（用于埋点/监控） */
  onError?: (error: Error, info: ErrorInfo) => void
}

interface ErrorBoundaryState {
  hasError: boolean
  error: Error | null
}

export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
  constructor(props: ErrorBoundaryProps) {
    super(props)
    this.state = { hasError: false, error: null }
  }

  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
    return { hasError: true, error }
  }

  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
    console.error("[ErrorBoundary]", error, errorInfo)
    this.props.onError?.(error, errorInfo)
  }

  private handleReset = (): void => {
    this.setState({ hasError: false, error: null })
  }

  render(): ReactNode {
    if (this.state.hasError && this.state.error) {
      const { fallback } = this.props
      if (typeof fallback === "function") {
        return fallback(this.state.error, this.handleReset)
      }
      if (fallback !== undefined) {
        return fallback
      }
      return null
    }
    return this.props.children
  }
}
```

- [ ] **Step 2: 验证 tsc + lint**

Run: `npx tsc --noEmit`
Expected: 零错误

Run: `npm run lint -- --filter src/shared/components/ui/error-boundary.tsx`
Expected: 零错误

- [ ] **Step 3: Commit**

```bash
git add src/shared/components/ui/error-boundary.tsx
git commit -m "feat(shared): 新增 ErrorBoundary 基础组件"
```

---

### Task 2: 收敛 SectionErrorBoundary 为 preset

**Files:**
- Modify: `src/shared/components/section-error-boundary.tsx`

- [ ] **Step 1: 重写 section-error-boundary.tsx**

将原文件（148 行）改写为：删除内部 `SectionErrorBoundaryBase` 类，改用 `ErrorBoundary` 基础组件。保留外部 API（`SectionErrorBoundary` 函数式 + i18n）不变。

```tsx
"use client"

import type { JSX } from "react"
import type { ReactNode, ErrorInfo } from "react"
import { useTranslations } from "next-intl"
import { AlertCircle, RefreshCw } from "lucide-react"

import { Button } from "@/shared/components/ui/button"
import { ErrorBoundary } from "@/shared/components/ui/error-boundary"

interface SectionErrorBoundaryProps {
  children: ReactNode
  /** i18n namespace，默认 "common" */
  namespace?: string
  /** 自定义降级 UI（函数形式，优先级最高） */
  fallback?: (error: Error, reset: () => void) => ReactNode
  /** 显式覆盖标题 */
  title?: string
  /** 显式覆盖描述 */
  description?: string
  /** 显式覆盖重试按钮文案 */
  retryLabel?: string
  /** 错误回调 */
  onError?: (error: Error, info: ErrorInfo) => void
}

/**
 * 组件级 Error Boundary preset：包裹独立数据区块，防止单区块错误导致整页崩溃。
 * 自动使用 next-intl 提供本地化文案；如需完全自定义可传入 `fallback` 函数。
 *
 * @example
 * <SectionErrorBoundary namespace="coursePlans">
 *   <CoursePlanProgress plan={plan} />
 * </SectionErrorBoundary>
 */
export function SectionErrorBoundary({
  children,
  namespace = "common",
  fallback,
  title,
  description,
  retryLabel,
  onError,
}: SectionErrorBoundaryProps): JSX.Element {
  const t = useTranslations(namespace)
  const effectiveTitle = title ?? t("error.boundaryTitle")
  const effectiveDescription = description ?? t("error.boundaryDescription")
  const effectiveRetryLabel = retryLabel ?? t("error.retry")

  const defaultFallback = (_error: Error, reset: () => void): ReactNode => (
    <div
      role="alert"
      aria-live="assertive"
      className="flex flex-col items-center justify-center space-y-3 rounded-lg border border-dashed p-8 text-center"
    >
      <AlertCircle className="h-8 w-8 text-muted-foreground" aria-hidden="true" />
      <div className="space-y-1">
        <p className="text-sm font-medium">{effectiveTitle}</p>
        <p className="text-xs text-muted-foreground">{effectiveDescription}</p>
      </div>
      <Button
        variant="outline"
        size="sm"
        onClick={reset}
        aria-label={effectiveRetryLabel}
      >
        <RefreshCw className="mr-1.5 h-3.5 w-3.5" aria-hidden="true" />
        {effectiveRetryLabel}
      </Button>
    </div>
  )

  return (
    <ErrorBoundary fallback={fallback ?? defaultFallback} onError={onError}>
      {children}
    </ErrorBoundary>
  )
}
```

- [ ] **Step 2: 验证外部 API 不变**

Run: `npx tsc --noEmit`
Expected: 零错误

Run: `npm run lint`
Expected: 零新增错误

- [ ] **Step 3: Grep 确认引用未受影响**

Run Grep: `SectionErrorBoundary` in `src/`
Expected: 所有引用文件（modules 层 error-boundary preset、各模块页面）类型检查通过

- [ ] **Step 4: Commit**

```bash
git add src/shared/components/section-error-boundary.tsx
git commit -m "refactor(shared): SectionErrorBoundary 收敛为 ErrorBoundary preset"
```

---

### Task 3: 收敛 RouteErrorBoundary 为 preset

**Files:**
- Modify: `src/shared/components/route-error.tsx`

- [ ] **Step 1: 重写 route-error.tsx**

`RouteErrorBoundary` 当前不使用类组件（仅函数式 + EmptyState），但其语义是路由级错误边界。为保持一致性，改为基于 `ErrorBoundary` 的 preset，但保留 `reset` prop（来自 Next.js `error.tsx` 的 `reset()` 函数）。

```tsx
"use client"

import type { ReactNode } from "react"
import { AlertCircle } from "lucide-react"
import { useTranslations } from "next-intl"

import { EmptyState } from "@/shared/components/ui/empty-state"
import { ErrorBoundary } from "@/shared/components/ui/error-boundary"

/**
 * 通用路由错误边界组件 preset。
 * 供各模块 error.tsx 复用。
 *
 * @example
 * // app/(dashboard)/admin/attendance/error.tsx
 * "use client"
 * import { RouteErrorBoundary } from "@/shared/components/route-error"
 * export default function Error({ reset }: { error: Error; reset: () => void }) {
 *   return <RouteErrorBoundary reset={reset} namespace="attendance" />
 * }
 */
export function RouteErrorBoundary({
  reset,
  namespace = "attendance",
}: {
  reset: () => void
  namespace?: string
}): ReactNode {
  const t = useTranslations(namespace)
  return (
    <ErrorBoundary
      fallback={() => (
        <div className="flex h-full flex-col items-center justify-center space-y-4 p-8">
          <EmptyState
            icon={AlertCircle}
            title={t("errors.unexpected")}
            description={t("errors.unexpected")}
            action={{
              label: t("actions.retry"),
              onClick: () => reset(),
            }}
            className="border-none shadow-none h-auto"
          />
        </div>
      )}
    >
      {/* RouteErrorBoundary 作为 error.tsx 的渲染组件，children 不适用，直接渲染 fallback */}
      {null}
    </ErrorBoundary>
  )
}
```

注意：`RouteErrorBoundary` 实际上是在 `error.tsx` 中被调用渲染错误 UI，而非包裹 children。因此这里 `children` 为 `null`，仅用 `ErrorBoundary` 渲染 fallback。若未来需要包裹式用法，可扩展。

- [ ] **Step 2: 验证**

Run: `npx tsc --noEmit`
Expected: 零错误

Run: `npm run lint`
Expected: 零新增错误

- [ ] **Step 3: Commit**

```bash
git add src/shared/components/route-error.tsx
git commit -m "refactor(shared): RouteErrorBoundary 收敛为 ErrorBoundary preset"
```

---

### Task 4: 收敛 WidgetBoundary 为 preset

**Files:**
- Modify: `src/shared/components/widget-boundary.tsx`

- [ ] **Step 1: 重写 widget-boundary.tsx**

删除内部 `WidgetErrorBoundary` 类，改用 `ErrorBoundary`。保留 `WidgetSkeleton` 和 `Suspense` 三合一能力。

```tsx
"use client"

import { Suspense, type ReactNode } from "react"
import { AlertCircle } from "lucide-react"
import { useTranslations } from "next-intl"

import { Button } from "@/shared/components/ui/button"
import { Skeleton } from "@/shared/components/ui/skeleton"
import { ErrorBoundary } from "@/shared/components/ui/error-boundary"

interface WidgetBoundaryProps {
  children: ReactNode
  title?: string
  skeletonHeight?: number
  fallbackDescription?: string
  retryLabel?: string
}

function WidgetSkeleton({
  height,
  loadingAriaLabel,
}: {
  height: number
  loadingAriaLabel: string
}): ReactNode {
  return (
    <div
      role="status"
      aria-label={loadingAriaLabel}
      aria-live="polite"
      className="space-y-3 p-4"
      style={{ minHeight: height }}
    >
      <Skeleton className="h-6 w-1/3" />
      <Skeleton className="h-4 w-full" />
      <Skeleton className="h-4 w-2/3" />
      <Skeleton className="h-32 w-full" />
    </div>
  )
}

export function WidgetBoundary({
  children,
  title,
  skeletonHeight = 200,
  fallbackDescription,
  retryLabel,
}: WidgetBoundaryProps): ReactNode {
  const t = useTranslations("common")
  const effectiveTitle = title ?? t("widget.block")
  const effectiveFallbackDescription = fallbackDescription ?? t("widget.defaultFallback")
  const effectiveRetryLabel = retryLabel ?? t("widget.retry")
  const loadFailedMessage = t("widget.loadFailed", { title: effectiveTitle })
  const retryAriaLabel = t("widget.retryAriaLabel", { title: effectiveTitle })
  const loadingAriaLabel = t("widget.loadingAriaLabel", { title: effectiveTitle })

  const errorFallback = (_error: Error, reset: () => void): ReactNode => (
    <div
      role="alert"
      aria-live="assertive"
      className="flex h-full min-h-[200px] flex-col items-center justify-center gap-3 rounded-lg border border-destructive/30 bg-destructive/5 p-6 text-center"
    >
      <AlertCircle className="h-8 w-8 text-destructive" aria-hidden="true" />
      <div className="space-y-1">
        <p className="text-sm font-medium text-foreground">{loadFailedMessage}</p>
        <p className="text-xs text-muted-foreground">{effectiveFallbackDescription}</p>
      </div>
      <Button
        size="sm"
        variant="outline"
        onClick={reset}
        aria-label={retryAriaLabel}
      >
        {effectiveRetryLabel}
      </Button>
    </div>
  )

  return (
    <ErrorBoundary fallback={errorFallback}>
      <Suspense
        fallback={<WidgetSkeleton height={skeletonHeight} loadingAriaLabel={loadingAriaLabel} />}
      >
        {children}
      </Suspense>
    </ErrorBoundary>
  )
}
```

- [ ] **Step 2: 验证**

Run: `npx tsc --noEmit`
Expected: 零错误

Run: `npm run lint`
Expected: 零新增错误

- [ ] **Step 3: Commit**

```bash
git add src/shared/components/widget-boundary.tsx
git commit -m "refactor(shared): WidgetBoundary 收敛为 ErrorBoundary preset"
```

---

### Task 5: 新增 StatsGrid 容器

**Files:**
- Create: `src/shared/components/ui/stats-grid.tsx`

- [ ] **Step 1: 创建 stats-grid.tsx**

```tsx
import type { ComponentType, ReactNode } from "react"

import { cn } from "@/shared/lib/utils"
import { StatCard } from "@/shared/components/ui/stat-card"

/**
 * 统计卡片网格容器：基于 StatCard 渲染响应式网格。
 *
 * 覆盖以下重复模式：
 * - attendance-stats-cards / error-book-stats-cards / elective-stats-cards
 * - practice-stats-cards / practice-overview-stats-cards
 * - grade-stats-card / analytics-stats-cards
 */
interface StatItem {
  /** 卡片标题 */
  label: string
  /** 统计数值 */
  value: string | number
  /** 图标组件 */
  icon?: ComponentType<{ className?: string }>
  /** 描述文本 */
  description?: string
  /** 图标颜色类名 */
  color?: string
  /** 是否高亮 */
  highlight?: boolean
  /** 点击跳转链接 */
  href?: string
  /** 数值自定义类名 */
  valueClassName?: string
}

interface StatsGridProps {
  /** 统计项列表 */
  items: StatItem[]
  /** 列数（默认响应式：mobile=1, md=2, lg=4） */
  columns?: 2 | 3 | 4
  /** 加载态 */
  isLoading?: boolean
  /** 容器额外类名 */
  className?: string
}

const columnsClass: Record<2 | 3 | 4, string> = {
  2: "grid-cols-1 md:grid-cols-2",
  3: "grid-cols-1 md:grid-cols-2 lg:grid-cols-3",
  4: "grid-cols-1 md:grid-cols-2 lg:grid-cols-4",
}

export function StatsGrid({
  items,
  columns = 4,
  isLoading = false,
  className,
}: StatsGridProps): ReactNode {
  return (
    <div className={cn("grid gap-4", columnsClass[columns], className)}>
      {items.map((item) => (
        <StatCard
          key={item.label}
          title={item.label}
          value={item.value}
          icon={item.icon}
          description={item.description}
          color={item.color}
          highlight={item.highlight}
          href={item.href}
          isLoading={isLoading}
          valueClassName={item.valueClassName}
        />
      ))}
    </div>
  )
}
```

- [ ] **Step 2: 验证**

Run: `npx tsc --noEmit`
Expected: 零错误

Run: `npm run lint`
Expected: 零新增错误

- [ ] **Step 3: Commit**

```bash
git add src/shared/components/ui/stats-grid.tsx
git commit -m "feat(shared): 新增 StatsGrid 容器组件"
```

---

### Task 6: 扩展 Skeleton（新增 SkeletonCard variant）

**Files:**
- Modify: `src/shared/components/ui/skeleton.tsx`

- [ ] **Step 1: 扩展 skeleton.tsx**

保留原 `Skeleton` 原语，新增 `SkeletonCard` 配置驱动变体。

```tsx
import type { ReactNode } from "react"

import { cn } from "@/shared/lib/utils"
import { Card, CardContent, CardHeader } from "@/shared/components/ui/card"

function Skeleton({
  className,
  ...props
}: React.HTMLAttributes<HTMLDivElement>) {
  return (
    <div
      className={cn("animate-pulse rounded-md bg-muted", className)}
      {...props}
    />
  )
}

interface SkeletonCardProps {
  variant: "table" | "list" | "chart" | "form" | "stats-grid"
  rows?: number
  className?: string
}

/**
 * 配置驱动骨架卡片：按 variant 渲染不同布局的骨架占位。
 *
 * 覆盖以下重复模式：
 * - message-list-skeleton / announcement-list-skeleton → variant="list"
 * - audit-log-table-skeleton → variant="table"
 * - class-skeleton / school-skeleton → variant="form"
 * - ai-skeleton → variant="chart"
 * - dashboard-loading-skeleton → variant="stats-grid"
 * - lesson-plan-skeleton → variant="form"（备课编辑器布局）
 */
export function SkeletonCard({
  variant,
  rows = 5,
  className,
}: SkeletonCardProps): ReactNode {
  switch (variant) {
    case "table":
      return (
        <Card className={className}>
          <CardHeader>
            <Skeleton className="h-5 w-1/4" />
          </CardHeader>
          <CardContent className="space-y-3">
            {Array.from({ length: rows }).map((_, i) => (
              <div key={i} className="flex gap-4">
                <Skeleton className="h-4 flex-1" />
                <Skeleton className="h-4 w-20" />
                <Skeleton className="h-4 w-16" />
              </div>
            ))}
          </CardContent>
        </Card>
      )
    case "list":
      return (
        <div className={cn("space-y-3", className)}>
          {Array.from({ length: rows }).map((_, i) => (
            <Card key={i}>
              <CardContent className="flex items-center gap-4 p-4">
                <Skeleton className="h-10 w-10 rounded-full" />
                <div className="flex-1 space-y-2">
                  <Skeleton className="h-4 w-1/3" />
                  <Skeleton className="h-3 w-1/2" />
                </div>
                <Skeleton className="h-8 w-20" />
              </CardContent>
            </Card>
          ))}
        </div>
      )
    case "chart":
      return (
        <Card className={className}>
          <CardHeader>
            <Skeleton className="h-5 w-1/3" />
          </CardHeader>
          <CardContent>
            <Skeleton className="h-[200px] w-full" />
          </CardContent>
        </Card>
      )
    case "form":
      return (
        <Card className={className}>
          <CardContent className="space-y-4 p-6">
            {Array.from({ length: rows }).map((_, i) => (
              <div key={i} className="space-y-2">
                <Skeleton className="h-4 w-1/4" />
                <Skeleton className="h-10 w-full" />
              </div>
            ))}
            <Skeleton className="h-10 w-32" />
          </CardContent>
        </Card>
      )
    case "stats-grid":
      return (
        <div className={cn("grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-4", className)}>
          {Array.from({ length: 4 }).map((_, i) => (
            <Card key={i}>
              <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
                <Skeleton className="h-4 w-[100px]" />
                <Skeleton className="h-4 w-4 rounded-full" />
              </CardHeader>
              <CardContent>
                <Skeleton className="mb-2 h-8 w-[60px]" />
                <Skeleton className="h-3 w-[140px]" />
              </CardContent>
            </Card>
          ))}
        </div>
      )
  }
}

export { Skeleton, SkeletonCard }
```

- [ ] **Step 2: 验证**

Run: `npx tsc --noEmit`
Expected: 零错误

Run: `npm run lint`
Expected: 零新增错误

- [ ] **Step 3: Grep 确认原 Skeleton 引用未受影响**

Run Grep: `from "@/shared/components/ui/skeleton"` in `src/`
Expected: 所有引用仍可正常导入 `Skeleton`（原 named export 保留）

- [ ] **Step 4: Commit**

```bash
git add src/shared/components/ui/skeleton.tsx
git commit -m "feat(shared): Skeleton 新增 SkeletonCard variant"
```

---

### Task 7: Phase 1 整体验证 + 架构文档同步

**Files:**
- Modify: `docs/architecture/004_architecture_impact_map.md`
- Modify: `docs/architecture/005_architecture_data.json`
- Modify: `docs/troubleshooting/known-issues.md`

- [ ] **Step 1: 全量验证**

Run: `npx tsc --noEmit`
Expected: 零错误

Run: `npm run lint`
Expected: 零新增错误

- [ ] **Step 2: 同步 004 架构图**

在 `docs/architecture/004_architecture_impact_map.md` 的 `shared/components` 章节，新增条目：

```markdown
| 组件 | 路径 | 职责 |
|------|------|------|
| ErrorBoundary | ui/error-boundary.tsx | 基础 ErrorBoundary 类组件，preset 的底座 |
| StatsGrid | ui/stats-grid.tsx | 统计卡片网格容器，基于 StatCard |
| SkeletonCard | ui/skeleton.tsx | 配置驱动骨架卡片（table/list/chart/form/stats-grid） |
```

并在文末新增"组件化重构专项"章节标题（内容随批次补充）。

- [ ] **Step 3: 同步 005 JSON**

在 `docs/architecture/005_architecture_data.json` 的 `sharedComponents` 节点新增：

```json
{
  "errorBoundary": {
    "path": "shared/components/ui/error-boundary.tsx",
    "type": "class",
    "exports": ["ErrorBoundary"],
    "role": "基础 ErrorBoundary，preset 底座"
  },
  "statsGrid": {
    "path": "shared/components/ui/stats-grid.tsx",
    "type": "function",
    "exports": ["StatsGrid"],
    "role": "统计卡片网格容器"
  },
  "skeletonCard": {
    "path": "shared/components/ui/skeleton.tsx",
    "type": "function",
    "exports": ["Skeleton", "SkeletonCard"],
    "role": "骨架原语 + 配置驱动变体"
  }
}
```

更新 `lastUpdate` 字段，追加"组件化重构 Phase 1：底座收敛与补全"。

- [ ] **Step 4: known-issues.md 新增章节**

在 `docs/troubleshooting/known-issues.md` 末尾新增：

```markdown
## 组件化重构专项 - Phase 1（2026-07-06）

### 底座组件使用规则

| 规则 | 正确写法 | 错误写法 |
|------|---------|---------|
| 错误边界必须用 preset | `<SectionErrorBoundary namespace="x">` | 自行实现类组件 |
| 统计卡片必须用 StatsGrid | `<StatsGrid items={[...]} />` | 手写 grid + StatCard 循环 |
| 骨架卡片必须用 SkeletonCard | `<SkeletonCard variant="table" />` | 手写 Card + Skeleton 布局 |
| 新增 *-filters.tsx 禁止 | 用 `<FilterBar>` 组合 | 新建模块专属筛选器文件 |
```

- [ ] **Step 5: Commit**

```bash
git add docs/architecture/004_architecture_impact_map.md docs/architecture/005_architecture_data.json docs/troubleshooting/known-issues.md
git commit -m "docs(architecture): 同步组件化重构 Phase 1 底座节点"
```

---

## Phase 2 - 第 1 批：低风险模块（grades / attendance / error-book / elective）

### Task 8: grades 模块闭环

**Files:**
- Modify: `src/modules/grades/components/batch-grade-entry.tsx` (>450 行)
- Modify: `src/modules/grades/components/grade-record-list.tsx` (>450 行)
- Delete: `src/modules/grades/components/grade-stats-card.tsx`
- Delete: `src/modules/grades/components/grade-filters.tsx`
- Delete: `src/modules/grades/components/grade-query-filters.tsx`
- Delete: `src/modules/grades/components/analytics-filters.tsx`

- [ ] **Step 1: 模块审计**

Read 以下文件，记录外部 API 与依赖关系：
- `src/modules/grades/components/batch-grade-entry.tsx`
- `src/modules/grades/components/grade-record-list.tsx`
- `src/modules/grades/components/grade-stats-card.tsx`
- `src/modules/grades/components/grade-filters.tsx`
- `src/modules/grades/components/grade-query-filters.tsx`
- `src/modules/grades/components/analytics-filters.tsx`

Grep 所有引用上述文件的 import 语句，记录调用方清单。

- [ ] **Step 2: 拆分 batch-grade-entry.tsx**

按职责拆为容器 + 子组件（保持 `batch-grade-entry.tsx` 作为容器，外部 API 不变）：
- `batch-grade-entry.tsx` — 容器，负责状态编排与 Server Action 调用
- `batch-grade-entry-form.tsx` — 表单子组件（学生列表 + 分数输入网格）
- `batch-grade-entry-toolbar.tsx` — 工具栏子组件（保存/取消/导入按钮）

目标：容器 ≤300 行，子组件各 ≤200 行。

- [ ] **Step 3: 拆分 grade-record-list.tsx**

按职责拆为：
- `grade-record-list.tsx` — 容器，列表查询与分页
- `grade-record-row.tsx` — 行渲染子组件
- `grade-record-detail.tsx` — 详情弹窗子组件

目标：容器 ≤300 行，子组件各 ≤200 行。

- [ ] **Step 4: 迁移 grade-stats-card 到 StatsGrid**

在调用 `grade-stats-card.tsx` 的页面中，替换为：

```tsx
import { StatsGrid } from "@/shared/components/ui/stats-grid"

const items = [
  { label: "平均分", value: avg, icon: TrendingUp, color: "text-emerald-500" },
  { label: "最高分", value: max, icon: ArrowUp, color: "text-blue-500" },
  // ...
]

<StatsGrid items={items} isLoading={isLoading} />
```

删除 `grade-stats-card.tsx`。

- [ ] **Step 5: 迁移 grade-filters / grade-query-filters / analytics-filters 到 FilterBar**

在调用方页面中，替换为 `<FilterBar>` + `<FilterSearchInput>` + Select 组件组合：

```tsx
import { FilterBar, FilterSearchInput } from "@/shared/components/ui/filter-bar"
import { Select } from "@/shared/components/ui/select"

<FilterBar hasFilters={hasFilters} onReset={handleReset} layout="wrap">
  <FilterSearchInput value={search} onChange={setSearch} placeholder="搜索学生..." />
  <Select value={classId} onValueChange={setClassId}>
    {/* options */}
  </Select>
</FilterBar>
```

删除 `grade-filters.tsx`、`grade-query-filters.tsx`、`analytics-filters.tsx`。

- [ ] **Step 6: 验证**

Run: `npx tsc --noEmit`
Expected: 零错误

Run: `npm run lint`
Expected: 零新增错误

Run Grep: `grade-stats-card|grade-filters|grade-query-filters|analytics-filters` in `src/`
Expected: 仅在删除的文件中出现（已删除则无匹配）

手动回归：访问成绩列表页、批量录入页、分析页，确认筛选/统计/列表行为正常。

- [ ] **Step 7: Commit**

```bash
git add src/modules/grades/
git commit -m "refactor(grades): 组件化重构 - 拆分巨型文件 + 迁移到底座"
```

---

### Task 9: attendance 模块闭环

**Files:**
- Delete: `src/modules/attendance/components/attendance-stats-cards.tsx`
- Delete: `src/modules/attendance/components/attendance-stats-card.tsx`（单数，与复数重复）
- Delete: `src/modules/attendance/components/attendance-filters.tsx`

- [ ] **Step 1: 模块审计**

Read 上述 3 个文件 + 调用方页面，记录外部 API。

- [ ] **Step 2: 迁移 attendance-stats-cards / attendance-stats-card 到 StatsGrid**

合并单数与复数版本，统一替换为 `<StatsGrid>`。删除 `attendance-stats-cards.tsx` 与 `attendance-stats-card.tsx`。

- [ ] **Step 3: 迁移 attendance-filters 到 FilterBar**

调用方替换为 `<FilterBar>` 组合。删除 `attendance-filters.tsx`。

- [ ] **Step 4: 验证**

Run: `npx tsc --noEmit` + `npm run lint`
Expected: 零新增错误

Run Grep: `attendance-stats-cards|attendance-stats-card|attendance-filters` in `src/`
Expected: 无匹配

手动回归：考勤列表页、统计页。

- [ ] **Step 5: Commit**

```bash
git add src/modules/attendance/
git commit -m "refactor(attendance): 组件化重构 - 迁移到 StatsGrid/FilterBar 底座"
```

---

### Task 10: error-book 模块闭环

**Files:**
- Delete: `src/modules/error-book/components/error-book-stats-cards.tsx`
- Delete: `src/modules/error-book/components/analytics-stats-cards.tsx`
- Delete: `src/modules/error-book/components/error-book-filters.tsx`

- [ ] **Step 1: 模块审计**

Read 上述 3 个文件 + 调用方页面。

- [ ] **Step 2: 迁移 stats-cards 到 StatsGrid**

`error-book-stats-cards.tsx` 与 `analytics-stats-cards.tsx` 均替换为 `<StatsGrid>`。删除原文件。

- [ ] **Step 3: 迁移 error-book-filters 到 FilterBar**

调用方替换为 `<FilterBar>` 组合。删除 `error-book-filters.tsx`。

- [ ] **Step 4: 验证**

Run: `npx tsc --noEmit` + `npm run lint`
Expected: 零新增错误

Run Grep: `error-book-stats-cards|analytics-stats-cards|error-book-filters` in `src/`
Expected: 无匹配

手动回归：错题本列表页、分析页。

- [ ] **Step 5: Commit**

```bash
git add src/modules/error-book/
git commit -m "refactor(error-book): 组件化重构 - 迁移到 StatsGrid/FilterBar 底座"
```

---

### Task 11: elective 模块闭环

**Files:**
- Delete: `src/modules/elective/components/elective-stats-cards.tsx`
- Delete: `src/modules/elective/components/elective-filters.tsx`

- [ ] **Step 1: 模块审计**

Read 上述 2 个文件 + 调用方页面。

- [ ] **Step 2: 迁移 elective-stats-cards 到 StatsGrid**

调用方替换为 `<StatsGrid>`。删除 `elective-stats-cards.tsx`。

- [ ] **Step 3: 迁移 elective-filters 到 FilterBar**

调用方替换为 `<FilterBar>` 组合。删除 `elective-filters.tsx`。

- [ ] **Step 4: 验证**

Run: `npx tsc --noEmit` + `npm run lint`
Expected: 零新增错误

Run Grep: `elective-stats-cards|elective-filters` in `src/`
Expected: 无匹配

手动回归：选修课列表页、统计页。

- [ ] **Step 5: Commit**

```bash
git add src/modules/elective/
git commit -m "refactor(elective): 组件化重构 - 迁移到 StatsGrid/FilterBar 底座"
```

---

### Task 12: 第 1 批收尾 - 文档同步

**Files:**
- Modify: `docs/architecture/004_architecture_impact_map.md`
- Modify: `docs/architecture/005_architecture_data.json`
- Modify: `docs/troubleshooting/known-issues.md`

- [ ] **Step 1: 同步 004 / 005**

更新 grades/attendance/error-book/elective 模块的 `exports` 清单（删除旧组件、新增子组件）。更新 `lastUpdate`。

- [ ] **Step 2: known-issues.md 补充第 1 批章节**

记录第 1 批遇到的拆分模式与底座使用规则（速查手册风格）。

- [ ] **Step 3: Commit**

```bash
git add docs/
git commit -m "docs(architecture): 同步组件化重构第 1 批（grades/attendance/error-book/elective）"
```

---

## Phase 2 - 第 2 批：中风险模块（homework / exams / textbooks）

### Task 13: homework 模块闭环

**Files:**
- Modify: `src/modules/homework/components/homework-take-view.tsx` (428 行)
- Modify: `src/modules/homework/components/homework-grading-view.tsx` (>450 行)
- Delete: `src/modules/homework/components/assignment-filters.tsx`

- [ ] **Step 1: 模块审计**

Read 上述 3 个文件 + 调用方页面。

- [ ] **Step 2: 拆分 homework-take-view.tsx**

按作答流程拆为：
- `homework-take-view.tsx` — 容器（题目导航 + 自动保存 + 提交）
- `homework-take-question.tsx` — 单题作答子组件
- `homework-take-sidebar.tsx` — 题目导航侧边栏

目标：容器 ≤300 行，子组件各 ≤200 行。

- [ ] **Step 3: 拆分 homework-grading-view.tsx**

按批改流程拆为：
- `homework-grading-view.tsx` — 容器（学生切换 + 评分 + 保存）
- `homework-grading-panel.tsx` — 单题评分面板
- `homework-grading-toolbar.tsx` — 工具栏（上/下学生、保存、批改进度）

- [ ] **Step 4: 迁移 assignment-filters 到 FilterBar**

删除 `assignment-filters.tsx`，调用方替换为 `<FilterBar>` 组合。

- [ ] **Step 5: 验证**

Run: `npx tsc --noEmit` + `npm run lint`
Expected: 零新增错误

Run Grep: `assignment-filters` in `src/`
Expected: 无匹配

手动回归：作业作答页、批改页、列表页。

- [ ] **Step 6: Commit**

```bash
git add src/modules/homework/
git commit -m "refactor(homework): 组件化重构 - 拆分作答/批改视图 + 迁移 FilterBar"
```

---

### Task 14: exams 模块闭环

**Files:**
- Modify: `src/modules/exams/components/exam-assembly.tsx` (>450 行)
- Delete: `src/modules/exams/components/exam-filters.tsx`

- [ ] **Step 1: 模块审计**

Read 上述 2 个文件 + 调用方页面。

- [ ] **Step 2: 拆分 exam-assembly.tsx**

按组卷流程拆为：
- `exam-assembly.tsx` — 容器（题目池 + 已选题目 + 试卷配置）
- `exam-assembly-question-pool.tsx` — 题目池子组件
- `exam-assembly-selected.tsx` — 已选题目子组件
- `exam-assembly-config.tsx` — 试卷配置子组件

目标：容器 ≤300 行，子组件各 ≤200 行。

- [ ] **Step 3: 迁移 exam-filters 到 FilterBar**

删除 `exam-filters.tsx`，调用方替换为 `<FilterBar>` 组合。

- [ ] **Step 4: 验证**

Run: `npx tsc --noEmit` + `npm run lint`
Expected: 零新增错误

手动回归：组卷页、试卷列表页。

- [ ] **Step 5: Commit**

```bash
git add src/modules/exams/
git commit -m "refactor(exams): 组件化重构 - 拆分组卷组件 + 迁移 FilterBar"
```

---

### Task 15: textbooks 模块闭环

**Files:**
- Modify: `src/modules/textbooks/components/textbook-reader.tsx` (>450 行)
- Modify: `src/modules/textbooks/components/knowledge-graph-inner.tsx` (411 行)
- Delete: `src/modules/textbooks/components/textbook-filters.tsx`
- Delete: `src/modules/textbooks/components/section-error-boundary.tsx`（与 shared 同名）

- [ ] **Step 1: 模块审计**

Read 上述 4 个文件 + 调用方页面。参考 `docs/architecture/003_ui_refactoring_plan.md` 的拆分方案。

- [ ] **Step 2: 拆分 textbook-reader.tsx**

按 003 计划拆为：
- `textbook-reader.tsx` — 容器（目录 + 内容区 + 知识点面板）
- `textbook-reader-content.tsx` — 内容区子组件
- `textbook-reader-toc.tsx` — 目录子组件

目标：容器 ≤300 行，子组件各 ≤200 行。

- [ ] **Step 3: 拆分 knowledge-graph-inner.tsx**

按职责拆为：
- `knowledge-graph-inner.tsx` — 容器（图渲染 + 节点交互）
- `knowledge-graph-node.tsx` — 节点渲染子组件
- `knowledge-graph-controls.tsx` — 控制面板子组件

- [ ] **Step 4: 迁移 textbook-filters 到 FilterBar**

删除 `textbook-filters.tsx`，调用方替换为 `<FilterBar>` 组合。

- [ ] **Step 5: 删除 textbooks 同名 section-error-boundary.tsx**

`src/modules/textbooks/components/section-error-boundary.tsx` 与 `shared/components/section-error-boundary.tsx` 同名。删除模块层版本，调用方改为直接 import shared 层 `SectionErrorBoundary`。

- [ ] **Step 6: 验证**

Run: `npx tsc --noEmit` + `npm run lint`
Expected: 零新增错误

Run Grep: `textbook-filters|modules/textbooks/components/section-error-boundary` in `src/`
Expected: 无匹配

手动回归：教材阅读页、知识图谱页、教材列表页。

- [ ] **Step 7: Commit**

```bash
git add src/modules/textbooks/
git commit -m "refactor(textbooks): 组件化重构 - 拆分阅读器/知识图谱 + 迁移底座"
```

---

### Task 16: 第 2 批收尾 - 文档同步

**Files:**
- Modify: `docs/architecture/004_architecture_impact_map.md`
- Modify: `docs/architecture/005_architecture_data.json`
- Modify: `docs/troubleshooting/known-issues.md`

- [ ] **Step 1: 同步 004 / 005**

更新 homework/exams/textbooks 模块的 `exports` 清单。更新 `lastUpdate`。

- [ ] **Step 2: known-issues.md 补充第 2 批章节**

记录拆分模式（编辑器/组卷类组件拆分注意事项）。

- [ ] **Step 3: Commit**

```bash
git add docs/
git commit -m "docs(architecture): 同步组件化重构第 2 批（homework/exams/textbooks）"
```

---

## Phase 2 - 第 3 批：高风险模块（lesson-preparation / ai / dashboard）

### Task 17: lesson-preparation 模块闭环

**Files:**
- Modify: `src/modules/lesson-preparation/components/lesson-plan-editor.tsx` (>450 行)
- Delete: `src/modules/lesson-preparation/components/lesson-plan-filters.tsx`
- Delete: `src/modules/lesson-preparation/components/lesson-plan-skeleton.tsx`
- Delete: `src/modules/lesson-preparation/components/lesson-plan-error-boundary.tsx`

- [ ] **Step 1: 模块审计**

Read 上述 4 个文件 + 调用方页面。lesson-plan-editor 是核心交互组件，需特别关注 Tiptap 编辑器集成。

- [ ] **Step 2: 拆分 lesson-plan-editor.tsx**

按三列布局拆为：
- `lesson-plan-editor.tsx` — 容器（三列布局编排 + 状态管理）
- `lesson-plan-sidebar.tsx` — 左侧结构树子组件
- `lesson-plan-paper.tsx` — 中间纸张区子组件（含 Tiptap 编辑器）
- `lesson-plan-detail-panel.tsx` — 右侧详情面板子组件

目标：容器 ≤300 行，子组件各 ≤200 行。注意 `immediatelyRender: false` SSR 配置必须保留。

- [ ] **Step 3: 迁移 lesson-plan-filters 到 FilterBar**

删除 `lesson-plan-filters.tsx`，调用方替换为 `<FilterBar>` 组合。

- [ ] **Step 4: 迁移 lesson-plan-skeleton 到 SkeletonCard**

调用方替换为 `<SkeletonCard variant="form" />`。删除 `lesson-plan-skeleton.tsx`。

- [ ] **Step 5: 迁移 lesson-plan-error-boundary 到 SectionErrorBoundary**

调用方替换为 `<SectionErrorBoundary namespace="lessonPreparation">`。删除 `lesson-plan-error-boundary.tsx`。

- [ ] **Step 6: 验证**

Run: `npx tsc --noEmit` + `npm run lint`
Expected: 零新增错误

Run Grep: `lesson-plan-filters|lesson-plan-skeleton|lesson-plan-error-boundary` in `src/`
Expected: 无匹配

手动回归：备课编辑器（节点展开/折叠、右键菜单、AI 辅助、保存重载）。

- [ ] **Step 7: Commit**

```bash
git add src/modules/lesson-preparation/
git commit -m "refactor(lesson-preparation): 组件化重构 - 拆分编辑器 + 迁移底座"
```

---

### Task 18: ai 模块闭环

**Files:**
- Modify: `src/modules/ai/components/ai-chat-panel.tsx` (417 行)
- Delete: `src/modules/ai/components/ai-skeleton.tsx`
- Delete: `src/modules/ai/components/ai-error-boundary.tsx`

- [ ] **Step 1: 模块审计**

Read 上述 3 个文件 + 调用方页面。

- [ ] **Step 2: 拆分 ai-chat-panel.tsx**

按对话交互拆为：
- `ai-chat-panel.tsx` — 容器（消息列表 + 输入框 + 状态管理）
- `ai-chat-messages.tsx` — 消息列表子组件
- `ai-chat-input.tsx` — 输入框子组件（含发送、停止、附件）

目标：容器 ≤300 行，子组件各 ≤200 行。注意对话状态保持，拆分后不能破坏流式响应。

- [ ] **Step 3: 迁移 ai-skeleton 到 SkeletonCard**

调用方替换为 `<SkeletonCard variant="chart" />`。删除 `ai-skeleton.tsx`。

- [ ] **Step 4: 迁移 ai-error-boundary 到 SectionErrorBoundary**

`ai-error-boundary.tsx` 已是薄包装（委托给 SectionErrorBoundary）。直接删除，调用方改为 `<SectionErrorBoundary namespace="ai">`。

- [ ] **Step 5: 验证**

Run: `npx tsc --noEmit` + `npm run lint`
Expected: 零新增错误

Run Grep: `ai-skeleton|ai-error-boundary` in `src/`
Expected: 无匹配

手动回归：AI 对话面板（发送消息、流式响应、停止、错误重试）。

- [ ] **Step 6: Commit**

```bash
git add src/modules/ai/
git commit -m "refactor(ai): 组件化重构 - 拆分聊天面板 + 迁移底座"
```

---

### Task 19: dashboard 模块闭环

**Files:**
- Delete: `src/modules/dashboard/components/dashboard-loading-skeleton.tsx`
- Modify: `src/modules/dashboard/components/admin-dashboard/admin-dashboard.tsx`
- Modify: `src/modules/dashboard/components/parent-dashboard/parent-dashboard.tsx`
- Create: `src/modules/dashboard/components/dashboard-shell.tsx`（仅布局壳抽象）

- [ ] **Step 1: 模块审计**

Read 4 个角色 dashboard 子组件 + dashboard-loading-skeleton。记录各角色布局差异。

- [ ] **Step 2: 抽象 DashboardShell 布局壳**

仅抽象布局壳（PageHeader + StatsGrid 区 + 内容区），业务逻辑保持各角色独立：

```tsx
import type { ReactNode, ComponentType } from "react"
import { PageHeader } from "@/shared/components/ui/page-header"
import { StatsGrid, type StatItem } from "@/shared/components/ui/stats-grid"

interface DashboardShellProps {
  title: string
  description?: string
  stats: StatItem[]
  statsLoading?: boolean
  children: ReactNode
  actions?: ReactNode
}

export function DashboardShell({
  title,
  description,
  stats,
  statsLoading,
  children,
  actions,
}: DashboardShellProps): ReactNode {
  return (
    <div className="space-y-6">
      <PageHeader title={title} description={description} actions={actions} />
      <StatsGrid items={stats} isLoading={statsLoading} />
      {children}
    </div>
  )
}
```

- [ ] **Step 3: 改造 4 个角色 dashboard 使用 DashboardShell**

各角色 dashboard 子组件改为：
```tsx
<DashboardShell title="..." stats={stats} statsLoading={isLoading}>
  {/* 角色专属内容区 */}
</DashboardShell>
```

- [ ] **Step 4: 迁移 dashboard-loading-skeleton 到 SkeletonCard**

调用方替换为 `<SkeletonCard variant="stats-grid" />`。删除 `dashboard-loading-skeleton.tsx`。

- [ ] **Step 5: 验证**

Run: `npx tsc --noEmit` + `npm run lint`
Expected: 零新增错误

Run Grep: `dashboard-loading-skeleton` in `src/`
Expected: 无匹配

手动回归：4 个角色（admin/teacher/student/parent）分别登录，确认 dashboard 卡片渲染与数据正确。

- [ ] **Step 6: Commit**

```bash
git add src/modules/dashboard/
git commit -m "refactor(dashboard): 组件化重构 - 抽象 DashboardShell + 迁移底座"
```

---

### Task 20: 第 3 批收尾 - 文档同步 + 专项完成

**Files:**
- Modify: `docs/architecture/004_architecture_impact_map.md`
- Modify: `docs/architecture/005_architecture_data.json`
- Modify: `docs/troubleshooting/known-issues.md`

- [ ] **Step 1: 同步 004 / 005**

更新 lesson-preparation/ai/dashboard 模块的 `exports` 清单。更新 `lastUpdate`。在 004 文末"组件化重构专项"章节写完成总结。

- [ ] **Step 2: known-issues.md 补充第 3 批章节**

记录高风险模块拆分注意事项（编辑器 SSR 配置、AI 流式响应状态保持、dashboard 布局壳抽象边界）。

- [ ] **Step 3: 全量验证**

Run: `npx tsc --noEmit`
Expected: 零错误

Run: `npm run lint`
Expected: 零新增错误

Run Grep: 验证 9 个巨型文件行数：
- `src/modules/textbooks/components/textbook-reader.tsx`
- `src/modules/lesson-preparation/components/lesson-plan-editor.tsx`
- `src/modules/grades/components/batch-grade-entry.tsx`
- `src/modules/grades/components/grade-record-list.tsx`
- `src/modules/homework/components/homework-take-view.tsx`
- `src/modules/homework/components/homework-grading-view.tsx`
- `src/modules/exams/components/exam-assembly.tsx`
- `src/modules/ai/components/ai-chat-panel.tsx`
- `src/modules/textbooks/components/knowledge-graph-inner.tsx`

Expected: 全部 ≤500 行

Run Grep: 验证 49 个重复组件已删除（按附录清单逐项 grep）。

- [ ] **Step 4: Commit**

```bash
git add docs/
git commit -m "docs(architecture): 组件化重构专项完成 - 同步全部文档"
```

---

## 自审清单

### Spec 覆盖
- [x] Phase 1 底座补全：Task 1-6 覆盖 ErrorBoundary/StatsGrid/SkeletonCard
- [x] Phase 1 文档同步：Task 7
- [x] 第 1 批（低风险）：Task 8-12 覆盖 grades/attendance/error-book/elective
- [x] 第 2 批（中风险）：Task 13-16 覆盖 homework/exams/textbooks
- [x] 第 3 批（高风险）：Task 17-20 覆盖 lesson-preparation/ai/dashboard
- [x] 9 个巨型文件拆分：Task 8/13/14/15/17/18/19
- [x] 49 个重复组件迁移：分布在各批次任务中

### 类型一致性
- `StatItem` 在 Task 5 定义，Task 19 `DashboardShellProps.stats: StatItem[]` 一致
- `ErrorBoundaryProps` 在 Task 1 定义，Task 2/3/4 preset 使用一致
- `SkeletonCardProps.variant` 在 Task 6 定义为联合类型，Task 17/18/19 使用 `variant="form"/"chart"/"stats-grid"` 一致

### 占位符扫描
- 无 TBD/TODO
- Phase 2 各任务的拆分代码示例为策略性描述（拆分方向 + 目标行数），实际代码需在审计后编写。这是必要的，因为巨型文件的具体内容需先 Read 才能给出精确拆分代码。每个 Step 都有具体动作（Read/拆分/删除/Grep 验证）。

---

## 执行选择

**Plan complete and saved to `docs/superpowers/plans/2026-07-06-component-refactoring.md`. Two execution options:**

**1. Subagent-Driven (recommended)** - 每个 Task 派发独立 subagent，Task 间 review，快速迭代

**2. Inline Execution** - 在当前会话顺序执行，批量执行 + 检查点 review

**Which approach?**