前端项目初始化提交

docs/superpowers/specs/2026-05-29-paper-compose-redesign-design.md

@@ -0,0 +1,562 @@
+# PaperManagementPanel 题目配置组件重设计
+
+> 日期: 2026-05-29
+> 状态: 待审核
+> 范围: PaperManagementPanel.vue 全面模块化拆分与视觉优化
+
+## 1. 背景与目标
+
+### 1.1 现状问题
+
+`src/components/exam/PaperManagementPanel.vue` 是一个 **2235 行的巨型单文件组件**，包含 6 个独立功能区全部耦合在一起：
+
+| 维度 | 当前数值 |
+|------|----------|
+| Template | 567 行 |
+| Script | ~1065 行 |
+| Style | ~600 行 |
+| 功能区数 | 6+ 个 |
+| 硬编码颜色值 | ~30 处（未使用 design-tokens） |
+| console.log | ~40 处（调试残留） |
+
+### 1.2 设计目标
+
+1. **组件拆分**: 将单文件拆分为 7 个子组件 + 2 个 composable，每个 < 350 行
+2. **代码精简**: 移除冗余逻辑、调试日志、硬编码颜色
+3. **视觉优化**: 延续现有扁平设计风格，统一使用 design-tokens
+4. **交互改进**: 优化组卷配置区控件、预览区展示、弹窗体验
+5. **响应式**: 保持移动端/平板/桌面断点适配
+
+## 2. 组件架构
+
+### 2.1 文件结构
+
+```
+src/components/exam/
+├── PaperManagementPanel.vue          # 主容器 (~80行)
+├── ComposePanel.vue                  # 智能组卷面板 - 左右分栏容器 (~50行)
+│   ├── ComposeConfigSidebar.vue      # 左侧配置栏 (~200行)
+│   └── ComposePreviewPane.vue        # 右侧预览区 (~180行)
+├── PaperListTab.vue                  # 草稿/已发布列表 - 复用型 (~150行)
+├── PaperDetailModal.vue              # 试卷详情弹窗 (~250行)
+├── PublishDialog.vue                 # 发布弹窗 (~300行)
+├── EntityPickerModal.vue             # 通用实体选择器弹窗 (~180行)
+├── composables/
+│   ├── usePaperManagement.js         # 共享状态管理 (~400行)
+│   └── useQuestionParser.js          # 题目数据解析工具 (~150行)
+└── common/                           # 已有公共组件 (不变更)
+    ├── PageHeader.vue
+    ├── StatsRow.vue
+    └── ContentCard.vue
+```
+
+### 2.2 组件树与数据流
+
+```
+PaperManagementPanel (主容器)
+  │
+  ├─ usePaperManagement (composable: 全局状态中心)
+  │
+  ├─► Tab Navigation (内置: 智能组卷 / 我的草稿 / 已发布试卷)
+  │
+  ├─► [activeTab='compose'] ComposePanel
+  │     ├─► ComposeConfigSidebar
+  │     │     props: form, selectedFiles, allFiles, loadingFiles
+  │     │     emit: generate, update:form
+  │     └─► ComposePreviewPane
+  │           props: result, composing, totalScore
+  │           emit: save
+  │
+  ├─► [activeTab='drafts'] PaperListTab(mode='drafts')
+  │     props: papers, loading
+  │     emit: view, publish, delete
+  │
+  ├─► [activeTab='published'] PaperListTab(mode='published')
+  │     props: papers, loading
+  │     emit: view, revoke
+  │
+  ├─► PaperDetailModal (Teleport to body)
+  │     v-model: visible
+  │     props: rawData
+  │
+  ├─► PublishDialog (Teleport to body)
+  │     v-model: visible
+  │     props: paperId
+  │     emit: confirm
+  │     └─► EntityPickerModal (Teleport to body)
+  │           v-model: visible
+  │           props: type, mode, sourceList, selectedIds
+  │           emit: confirm
+  └─► EntityPickerModal (独立使用场景预留)
+```
+
+### 2.3 通信原则
+
+- **单向数据流**: 父 → 子通过 props，子 → 父通过 emits
+- **状态提升**: 所有业务状态集中在 `usePaperManagement` composable
+- **v-model 模式**: 弹窗类组件支持 `v-model:visible` 双向绑定
+- **接口最小化**: 每个子组件只暴露必要的 props/emits
+
+## 3. 各组件详细设计
+
+### 3.1 PaperManagementPanel.vue — 主容器
+
+**职责**: Tab 导航 + 子组件编排 + 状态初始化
+
+**Template 结构**:
+```html
+<div class="pmp-panel">
+  <PageHeader title="智能组卷" description="..." />
+  <div class="pmp-tabs"> <!-- 3个Tab按钮 --> </div>
+
+  <ComposePanel v-if="activeTab==='compose'" ... />
+  <PaperListTab v-else-if="activeTab==='drafts'" mode="drafts" ... />
+  <PaperListTab v-else-if="activeTab==='published'" mode="published" ... />
+
+  <PaperDetailModal v-model="detailVisible" :raw-data="previewRaw" />
+  <PublishDialog v-model="publishVisible" :paper-id="pubPaperId" @confirm="confirmPublish" />
+</div>
+```
+
+**Script**: 仅做 composable 解构和事件转发，< 80 行
+
+---
+
+### 3.2 ComposeConfigSidebar.vue — 组卷配置栏
+
+**职责**: 数据源选择、难度设置、题型数量配置、生成触发
+
+#### Props
+
+```typescript
+{
+  modelValue: {                    // composeForm 对象
+    difficulty: Number,            // 1-5
+    include_personal: Boolean,
+    single_choice_count: Number,
+    multiple_choice_count: Number,
+    true_false_count: Number,
+    fill_blank_count: Number,
+    subjective_count: Number
+  },
+  selectedFiles: Array,            // 已选文件列表
+  allFiles: Array,                 // 全量文件列表
+  loadingFiles: Boolean,
+  totalCount: Number               // 计算属性：各题型数量之和
+}
+```
+
+#### Emits
+
+```typescript
+{
+  'update:modelValue': [form],    // 表单变更
+  'toggle-file': [file],          // 文件选择切换
+  'remove-file': [id],            // 移除已选文件
+  'open-picker': [],              // 打开文件选择器
+  'close-picker': [],             // 收起文件选择器
+  'generate': []                  // 触发生成试卷
+}
+```
+
+#### 视觉改进点
+
+| 改进项 | 当前实现 | 新设计 |
+|--------|----------|--------|
+| Step 标识 | 圆形数字 badge (1/2/3) | 分隔线 + 小标题，减少视觉噪音 |
+| 题型数量控件 | `[-] 数字 [+]` 按钮 | Native `<select>` 下拉 (0-50)，更紧凑 |
+| 难度选择 | 5 个并排按钮 | 保持按钮组，使用 design-tokens 颜色 |
+| 文件选择器 | 展开内嵌列表 | 限制 max-height: 180px，滚动溢出 |
+| 总计行 | 底部小字 "共 N 题" | 加粗数字 + `--bg-subtle` 色块突出 |
+| 生成按钮 | 全宽黑色 `#212529` | 使用 `--color-primary` token |
+
+#### 布局草图
+
+```
+┌──────────────────────────────┐
+│  📋 配置                      │
+├──────────────────────────────┤
+│                              │
+│  ── 数据源 ──────────────    │
+│  [从知识库选择文件]           │
+│  [chip: 制度A ×] [chip: 规范B ×] │
+│  💡 不选则从全部题库出题      │
+│                              │
+│  ── 难度等级 ────────────    │
+│  [简单] [中等✓] [较难] [困难]  │
+│                              │
+│  ── 题型配置 ────────────    │
+│  单选题    [▼ 5 ▲]           │
+│  多选题    [▼ 3 ▲]           │
+│  判断题    [▼ 0 ▲]           │
+│  填空题    [▼ 2 ▲]           │
+│  简答题    [▼ 0 ▲]           │
+│                              │
+│  ┌──────────────────────┐   │
+│  │   共 10 题            │   │
+│  └──────────────────────┘   │
+│                              │
+│  ┌──────────────────────┐   │
+│  │   ✨ 生成试卷          │   │
+│  └──────────────────────┘   │
+└──────────────────────────────┘
+```
+
+---
+
+### 3.3 ComposePreviewPane.vue — 组卷预览区
+
+**职责**: 展示组卷结果（空态/加载态/题目预览）+ 保存操作
+
+#### Props
+
+```typescript
+{
+  result: Object | null,        // composeResult
+  composing: Boolean,
+  totalScore: Number
+}
+```
+
+#### Emits
+
+```typescript
+{ save: [] }
+```
+
+#### 三态设计
+
+1. **空态** (`!result && !composing`):
+   - SVG 图标 + 引导文案 "选择文件（可选）、设置题型数量 → 点击「生成试卷」"
+   - 使用 `--text-muted` 颜色
+
+2. **加载态** (`composing`):
+   - Spinner + "正在从题库中选题组卷..."
+
+3. **结果态** (`result && !composing`):
+   - 试卷预览卡片:
+     - 标题 + 统计信息（题目数、总分）
+     - 题目列表（每题：序号圆圈 + 类型标签 + 难度 + 题干）
+     - hover 时边框高亮
+   - 保存区域: 保存按钮 + 提示文字
+
+#### 视觉改进
+
+| 改进项 | 当前 | 新设计 |
+|--------|------|--------|
+| 预览卡边框 | `2px solid #228BE6` (蓝色粗边框) | `1px solid var(--border-default)` + 微妙阴影 |
+| 预览卡头部 | 渐变蓝背景 | `var(--bg-subtle)` 纯色背景 |
+| 题号圆圈 | `#F1F9FA` 灰底 | `var(--color-primary)` 主色底 + 白字 |
+| 保存按钮 | 黑色全宽 | `var(--color-primary)` token |
+
+---
+
+### 3.4 PaperListTab.vue — 复用型列表组件
+
+**职责**: 通过 mode prop 切换草稿/已发布两种列表模式
+
+#### Props
+
+```typescript
+{
+  mode: 'drafts' | 'published',
+  papers: Array,
+  loading: Boolean
+}
+```
+
+#### Emits
+
+```typescript
+{
+  view: [paper],
+  publish: [paperId],       // 仅 drafts 模式
+  delete: [paperId],        // 仅 drafts 模式
+  revoke: [paperId]         // 仅 published 模式
+}
+```
+
+#### 视觉改进
+
+| 改进项 | 当前 | 新设计 |
+|--------|------|--------|
+| 行左侧 | 无标识 | 彩色竖条（草稿=`--color-warning`, 发布=`--color-success`） |
+| 操作按钮 | 文字按钮 ("查看"/"发布"/"删除") | 图标按钮 + hover tooltip |
+| Badge 样式 | 自定义 CSS | 使用 design-token 颜色 |
+| 空态 | 内联 SVG | 统一空态组件风格 |
+
+#### 条件渲染逻辑
+
+```html
+<!-- 草稿模式独有 -->
+<button v-if="mode === 'drafts'" @click="$emit('publish', id)">发布</button>
+<button v-if="mode === 'drafts'" @click="$emit('delete', id)">删除</button>
+
+<!-- 已发布模式独有 -->
+<button v-if="mode === 'published'" @click="$emit('revoke', id)">撤回</button>
+```
+
+---
+
+### 3.5 PaperDetailModal.vue — 试卷详情弹窗
+
+**职责**: 展示试卷完整题目列表（选项/答案/解析/难度）
+
+#### Props
+
+```typescript
+{
+  modelValue: Boolean,         // 弹窗显隐
+  rawData: Object | null       // 原始 API 返回数据
+}
+```
+
+#### 内部处理
+
+- 使用 `useQuestionParser()` composable 解析原始数据
+- 解析逻辑包括: content 多格式兼容、选项提取、答案匹配、类型判断
+
+#### 展示区块
+
+1. **发布信息区** (如有): 目标部门/用户/时间/截止
+2. **概要行**: 总题数 + 总分
+3. **题目列表** (每题):
+   - 头部: 序号(主色圆圈) + 类型标签 + 分数
+   - 题干文本
+   - 选择题: 选项列表 (正确选项绿色左边框 + ✓)
+   - 判断题: 正确/错误文本
+  填空/简答: 参考答案文本
+   - 解析区: `--color-warning` 背景 (与 ExamPanel.vue 统一)
+   - 难度标签 (如有)
+4. **Fallback 区**: 原始数据兜底展示 (当自动解析失败时)
+
+---
+
+### 3.6 PublishDialog.vue — 发布弹窗
+
+**职责**: 设置发布参数（部门/用户范围/时间）
+
+#### Props
+
+```typescript
+{
+  modelValue: Boolean,
+  paperId: String | Number
+}
+```
+
+#### Emits
+
+```typescript
+{
+  'update:modelValue': [Boolean],
+  confirm: [payload]           // { deptIds, userIds, excludeUserIds, publishTime?, deadline? }
+}
+```
+
+#### 内部状态管理
+
+所有发布相关状态（部门列表、用户列表、选择状态、模式等）从 `usePaperManagement` 中获取。
+
+#### 子组件调用
+
+- 部门选择 → 调用 `<EntityPickerModal type="dept" />`
+- 用户选择 → 调用 `<EntityPickerModal type="user" :mode="userMode" />`
+
+#### 布局保持: 两列网格 (Grid 1fr 1fr)
+
+---
+
+### 3.7 EntityPickerModal.vue — 通用实体选择器
+
+**职责**: 通用的部门/用户多选弹窗，可复用
+
+#### Props
+
+```typescript
+{
+  modelValue: Boolean,
+  type: 'dept' | 'user',
+  mode: 'target' | 'exclude',   // 仅 type='user' 时有效
+  sourceList: Array,             // 可选数据源
+  selectedIds: Set,              // 当前已选 ID 集合
+  loading: Boolean,
+  searchPlaceholder: String
+}
+```
+
+#### Emits
+
+```typescript
+{
+  'update:modelValue': [Boolean],
+  confirm: [selectedItems]       // 选中的完整对象数组
+}
+```
+
+#### 功能特性
+
+- 搜索过滤 (实时)
+- 全选 / 清空
+- 已选计数显示
+- Checkbox 列表 + hover 高亮
+- 部门模式下显示部门名称
+- 用户模式下显示姓名 + 所属部门
+
+## 4. Composables 设计
+
+### 4.1 usePaperManagement.js
+
+**定位**: PaperManagementPanel 的全局状态中心
+
+**状态分组**:
+
+```
+┌─ Tab 状态
+│   activeTab, tabs
+│
+├─ 组卷状态
+│   composeForm, composeResult, composing
+│   selectedFiles, allFiles, loadingFiles, showFilePicker
+│
+├─ 列表状态
+│   drafts, publishedPapers, loadingDrafts
+│
+├─ 详情状态
+│   previewRaw, previewQuestions, previewPaperTitle, previewPublishInfo
+│
+├─ 发布状态
+│   publishDialog, pubPaperId, publishing
+│   pub (reactive), pubUI (reactive)
+│   pickerDialog (reactive)
+│
+└─ 缓存
+    _deptCache, _deptCacheTime, _userCache, CACHE_TTL
+```
+
+**方法分组**:
+
+| 分类 | 方法 |
+|------|------|
+| Tab | switchTab |
+| 组卷 | handleGeneratePaper, handleSavePaper, increment, decrement |
+| 文件 | toggleFile, removeFile, openFilePicker |
+| 列表 | loadPapers, deleteDraft, revokePublishedPaper |
+| 详情 | viewPaperDetail, clearPreview |
+| 发布 | openPublishDialog, closePublish, confirmPublish |
+| Picker | openPicker, closePicker, confirmPicker |
+| 部门 | loadDeptList, filterDeptList, toggleDept, removeDept, selectAllDepts, clearAllDepts |
+| 用户 | loadUserListForPicker, refreshUsersForDepts, toggleCurrentUser, removeUser, selectAllUsers, clearAllUsers |
+| 工具 | getId, getPaperTitle, formatQType, formatPubTime, isDeadlineNear |
+
+### 4.2 useQuestionParser.js
+
+**定位**: 从 viewPaperDetail() 中提取的纯函数集合，供 PaperDetailModal 使用
+
+**导出函数**:
+
+```javascript
+export function useQuestionParser() {
+  function parseQuestionContent(rawQ) → { stem, options, answer, explanation, ... }
+  function extractStem(q) → string
+  function extractOptions(q) → Array<{ key, text }>
+  function extractAnswer(q) → string
+  function isChoiceQuestion(q) → boolean
+  function isTextQuestion(q) → boolean
+  function isOptionAnswer(opt, q) → boolean
+  function formatTfAnswer(q) → string
+  function formatDifficulty(d) → string
+  function formatQType(t) → string
+
+  return { parseQuestionContent, extractStem, extractOptions, extractAnswer,
+           isChoiceQuestion, isTextQuestion, isOptionAnswer,
+           formatTfAnswer, formatDifficulty, formatQType }
+}
+```
+
+## 5. 样式规范
+
+### 5.1 Design Token 映射
+
+所有新组件必须使用项目 `design-tokens.css` 中定义的 CSS 变量，禁止硬编码颜色值：
+
+| 当前硬编码 | 替换 Token | 用途 |
+|------------|-----------|------|
+| `#212529` | `var(--text-primary)` | 主文字 |
+| `#495057` | `var(--text-secondary)` | 次要文字 |
+| `#868E96` | `var(--text-muted)` | 辅助文字 |
+| `#ADB5BD` / `#6C757D` | `var(--text-muted)` | 占位符/提示 |
+| `#E9ECEF` | `var(--border-light)` | 浅边框 |
+| `#DEE2E6` / `#CED4DA` | `var(--border-default)` | 默认边框 |
+| `#F8F9FA` | `var(--bg-subtle)` | 浅背景 |
+| `#F1F3F5` | `var(--bg-hover)` | Hover 背景 |
+| `#FFF5F5` | `var(--bg-danger-subtle)` | 危险背景 |
+| `#EBFBEE` / `#D3F9D8` | `var(--bg-success-subtle)` | 成功背景 |
+| `#FFFBEB` / `#FFF9DB` | `var(--bg-warning-subtle)` | 警告背景 |
+| `#C92A2A` | `var(--color-danger)` | 危险色 |
+| `#2B8A3E` | `var(--color-success)` | 成功色 |
+| `#228BE6` / `#1C7ED6` | `var(--color-primary)` | 主色调 |
+| `#E67700` | `var(--color-warning)` | 警告色 |
+
+### 5.2 CSS 命名规范
+
+使用 BEM 变体命名，前缀按组件缩写：
+
+```
+.pmp-{主容器}__{元素}--{修饰符}
+.cps-{ComposePanel}__{元素}--{修饰符}
+.ccs-{ComposeConfigSidebar}__{元素}--{修饰符}
+.cpp-{ComposePreviewPane}__{元素}--{修饰符}
+.plt-{PaperListTab}__{元素}--{修饰符}
+.pdm-{PaperDetailModal}__{元素}--{修饰符}
+.pbd-{PublishDialog}__{元素}--{修饰符}
+.epm-{EntityPickerModal}__{元素}--{修饰符}
+```
+
+### 5.3 响应式断点
+
+复用项目已有断点体系：
+
+| 断点 | 宽度 | 布局调整 |
+|------|------|----------|
+| Mobile | ≤767px | 组卷分栏→上下堆叠；弹窗全屏；列表单列 |
+| Tablet | 768-1023px | 组卷侧栏收窄至 280px |
+| Desktop | 1024-1439px | 标准布局 |
+| Large | ≥1440px | 侧栏放宽至 380px；预览区更大 |
+
+### 5.4 清理项
+
+以下原样式将在拆分时移除（属于其他组件或冗余）：
+
+- `.answer-comparison`, `.your-answer`, `.correct-answer` — TrainingPanel 残留
+- `.wrong`, `.correct` — 错题本遗留（已删除功能）
+- `.explanation` — 与新 `.dqc-explanation` 重复
+- 重复定义的 `.loading-spinner` 和 `@keyframes spin` — 统一到公共样式中
+- 所有 `console.log` / `console.warn` 调试语句 — 移除或改为条件编译
+
+## 6. 实施顺序建议
+
+1. **Phase 1 - 基础设施**
+   - 创建 `useQuestionParser.js`（纯函数，无依赖）
+   - 创建 `usePaperManagement.js`（从原组件提取状态和方法）
+
+2. **Phase 2 - 核心组件**
+   - 创建 `ComposeConfigSidebar.vue`
+   - 创建 `ComposePreviewPane.vue`
+   - 创建 `ComposePanel.vue`（组合上述两个）
+   - 创建 `PaperListTab.vue`
+
+3. **Phase 3 - 弹窗组件**
+   - 创建 `EntityPickerModal.vue`（通用，无业务依赖）
+   - 创建 `PublishDialog.vue`（依赖 EntityPickerModal）
+   - 创建 `PaperDetailModal.vue`（依赖 useQuestionParser）
+
+4. **Phase 4 - 主容器整合**
+   - 重构 `PaperManagementPanel.vue` 为薄容器
+   - 接入所有子组件
+   - 样式清理与 token 替换
+
+5. **Phase 5 - 验证**
+   - 功能回归测试（组卷/保存/发布/查看/删除/撤回）
+   - 响应式布局测试
+   - 构建验证 (npm run build)