# 过程背诵练习模块 - 需求与实现记录

## 项目信息
- **创建日期**: 2026-03-01
- **模块名称**: 过程背诵练习 (Process Practice)
- **路由地址**: `/process-practice`
- **提交记录**:
  - 初始实现: `cc8dd1e`
  - 移动端优化: `da04583`

## 需求概述

创建一个交互式背诵练习模块，帮助用户记忆 PMP 项目管理的 10 个知识领域和 49 个过程。

### 核心功能需求

#### 1. 矩阵布局
- 显示知识领域 × 过程组的矩阵（10行 × 5列）
- 表头：5个过程组（启动、规划、执行、监控、收尾）
- 知识领域格子横跨5列
- 过程格子按过程组分列显示
- 空单元格置灰显示（如范围管理-启动过程组）

#### 2. 背诵对象
- **知识领域**（10个）：如"整合管理"（去除"项目"前缀）
- **过程**（49个）：如"制定项目章程"
- 总计：59个格子需要背诵

#### 3. 输入交互
- 动态输入框：根据答案长度显示对应数量的横线
- 实时验证：逐字符验证，错误标红，正确显示绿色
- 答对后自动跳转到下一个格子（延迟300ms）
- 支持中文输入法（监听 compositionStart/End）
- 支持批量粘贴（固定长度数组，避免错位）

#### 4. 辅助信息
- **知识领域格子**：显示敏捷裁剪因素（tailoringFactors）
- **过程格子**：显示主要作用（purpose）
- 位置：固定在底部，输入框下方
- 移动端优化：限高可滚动，只显示前2个裁剪因素

#### 5. 格子切换
- **TAB键**：按顺序切换（KA01 → P1.1 → P1.2 → ... → KA02 → ...）
- **点击格子**：直接切换到目标格子
- **自动跳过**：空单元格不可聚焦
- **允许回顾**：可以点击已答对的格子重新查看

#### 6. 长按显示答案
- 支持触摸、鼠标和键盘（空格键）
- 长按600ms后显示答案
- 松开后隐藏答案
- 3秒后自动隐藏
- 显示答案期间锁定输入区域

#### 7. 进度跟踪
- 顶部显示进度条
- 显示已答对数量 / 总数量
- 进度条动画效果

#### 8. 无障碍支持
- `aria-live` 区域通告答案显示/隐藏
- `tabIndex` 控制键盘导航
- `aria-describedby` 关联辅助信息
- `scrollIntoView` 确保格子可见
- `role="button"` 和 `aria-current` 标记

## 技术实现

### 文件结构

```
src/
├── utils/
│   └── practice.ts                    # 工具函数
├── hooks/
│   └── useLongPress.ts                # 长按 Hook
├── components/
│   └── practice/
│       ├── KnowledgeAreaCell.tsx      # 知识领域格子
│       ├── ProcessCell.tsx            # 过程格子
│       ├── InputArea.tsx              # 输入区域
│       ├── HintInfo.tsx               # 辅助信息
│       └── PracticeMatrix.tsx         # 矩阵组件
├── pages/
│   └── ProcessPracticePage.tsx        # 主页面
├── App.tsx                            # 路由配置
└── components/layout/Sidebar.tsx      # 导航菜单
```

### 核心算法

#### 1. 格子顺序生成 (`generateCellSequence`)
```typescript
// 顺序：KA01 → P1.1 → P1.2 → ... → P1.7 → KA02 → P2.1 → ...
// 总计：10个知识领域 + 49个过程 = 59个格子
```

#### 2. 答案标准化 (`normalizeAnswer`)
```typescript
// 去除空格、标点
// 只对知识领域去除"项目"前缀
// 过程名称保留"项目"字样
```

#### 3. 输入验证逻辑
- 使用原始答案长度渲染横线
- 使用标准化答案进行验证
- 逐字符比对，维护 `charStatuses` 数组
- 完整答案验证后触发跳转或错误提示

#### 4. 长按检测 (`useLongPress`)
- `onPointerDown` 启动600ms定时器
- `onPointerUp/Leave/Cancel` 清理定时器
- 支持键盘空格键长按
- 阻止 `contextMenu` 事件

### 样式设计

#### 桌面端
- 矩阵格子：p-4, gap-3, min-h-60px
- 字体大小：text-sm, text-base
- 输入框：w-10, h-12, text-2xl

#### 移动端优化
- 矩阵格子：p-2, gap-2, min-h-40px
- 字体大小：text-xs, text-sm
- 输入框：保持原大小（便于输入）
- 底部固定区域：分层显示输入框和辅助信息
- 辅助信息：max-h-32, overflow-y-auto

### 状态管理

```typescript
// 格子顺序
cellSequence: CellInfo[]

// 答题记录
answeredCells: Map<string, boolean>

// 当前焦点
currentCellId: string | null

// 输入状态
userInput: string[]
charStatuses: CharStatus[]
isComposing: boolean
lastErrorTimestamp: number | null

// 长按显示答案
showAnswerForCell: { cellId, answer, expiresAt } | null
inputLocked: boolean
```

## 实现进度

### ✅ 已完成功能

1. **基础框架**
   - [x] 创建工具函数和类型定义
   - [x] 创建长按 Hook
   - [x] 创建格子组件
   - [x] 创建输入区域组件
   - [x] 创建辅助信息组件
   - [x] 创建矩阵组件
   - [x] 创建主页面组件

2. **核心功能**
   - [x] 格子顺序生成（59个格子）
   - [x] 答案标准化（知识领域去除"项目"）
   - [x] 动态输入框（根据答案长度）
   - [x] 实时验证（逐字符验证）
   - [x] 自动跳转（答对后300ms延迟）
   - [x] TAB键切换（按顺序，跳过空格）
   - [x] 点击格子切换（允许回顾）
   - [x] 长按显示答案（支持多端）
   - [x] 进度跟踪（顶部进度条）

3. **输入法支持**
   - [x] 监听 compositionStart/End
   - [x] 输入法期间暂停验证
   - [x] 确认后立即验证

4. **批量粘贴**
   - [x] 创建固定长度数组
   - [x] 不足部分保留空字符串
   - [x] 避免输入框数量错位

5. **无障碍支持**
   - [x] aria-live 通告
   - [x] tabIndex 控制
   - [x] aria-describedby 关联
   - [x] scrollIntoView 滚动
   - [x] role 和 aria-current

6. **移动端优化**
   - [x] 压缩间距和内边距
   - [x] 减小字体大小
   - [x] 底部固定区域分层
   - [x] 辅助信息限高可滚动
   - [x] 修复吸顶位置冲突

### 🔧 已修复问题

1. **Codex Review 后的改进**
   - [x] 修复批量粘贴数组长度问题
   - [x] 格子可聚焦（支持键盘长按）
   - [x] 允许回顾已答对的格子
   - [x] 修复表头吸顶位置冲突

2. **移动端样式问题**
   - [x] 底部区域布局重构
   - [x] 压缩矩阵格子尺寸
   - [x] 辅助信息区域优化
   - [x] 主内容区域底部内边距

### 📝 待优化项（可选）

1. **性能优化**
   - [ ] 虚拟滚动（如果格子数量增加）
   - [ ] 使用 React.memo 优化格子渲染
   - [ ] 防抖输入验证（目前已有 requestAnimationFrame）

2. **功能增强**
   - [ ] 添加"重置"按钮（清空所有答题记录）
   - [ ] 添加"跳过"按钮（跳过当前格子）
   - [ ] 保存练习进度到 localStorage
   - [ ] 统计答题时间和错误次数
   - [ ] 提供"只练习知识领域"或"只练习过程"模式

3. **用户体验**
   - [ ] 添加音效反馈（答对/答错）
   - [ ] 添加震动反馈（移动端）
   - [ ] 提供快捷键说明（帮助面板）
   - [ ] 添加"提示"按钮（显示首字母）

## 数据依赖

### 知识领域数据
- 文件：`src/data/knowledge-areas.json`
- 字段：`id`, `name`, `order`, `color`, `tailoringFactors`

### 过程数据
- 文件：`src/data/processes.json`
- 字段：`id`, `code`, `name`, `knowledgeAreaId`, `processGroupId`, `order`, `purpose`

### 过程组数据
- 文件：`src/data/process-groups.json`
- 字段：`id`, `name`, `order`, `color`

## 测试要点

### 功能测试
1. 访问 `/process-practice` 页面
2. 验证矩阵初始状态（所有格子空白占位）
3. 输入"整合管理"，验证格子显示"1.整合管理"
4. 验证自动跳转到下一个格子
5. 测试 TAB 键切换顺序
6. 测试点击格子切换
7. 测试长按显示答案（600ms）
8. 测试输入法输入
9. 测试批量粘贴
10. 完成所有59个格子的答题

### 边界测试
- 第一个格子按 Shift+Tab（不应有反应）
- 最后一个格子按 Tab（不应有反应）
- 长按空单元格（不应有反应）
- 快速连续输入（验证防抖）
- 输入错误后按 Escape（验证清空输入）

### 移动端测试
- 验证底部固定区域不遮挡内容
- 验证辅助信息区域可滚动
- 验证格子尺寸适配小屏幕
- 验证触摸长按功能

## 相关文档

- 需求设计文档：`docs/需求设计文档.md`
- 实现计划：`/root/.claude/plans/iridescent-cooking-bee.md`
- CLAUDE.md：`/home/ittoview/CLAUDE.md`

## 更新日志

### 2026-03-01
- ✅ 完成初始实现（提交 cc8dd1e）
- ✅ 修复 Codex Review 发现的问题
- ✅ 优化移动端布局和样式（提交 da04583）
- ✅ 创建本需求记录文档

---

**备注**: 本模块已完成核心功能开发和移动端优化，可以正常使用。后续可根据用户反馈进行功能增强和体验优化。