From 32172bec2df644d66ae02fd53b882d146c889a3d Mon Sep 17 00:00:00 2001 From: ittoview Date: Sun, 1 Mar 2026 14:38:27 +0000 Subject: [PATCH] =?UTF-8?q?docs(=E7=BB=83=E4=B9=A0):=20=E6=B7=BB=E5=8A=A0?= =?UTF-8?q?=E8=BF=87=E7=A8=8B=E8=83=8C=E8=AF=B5=E7=BB=83=E4=B9=A0=E6=A8=A1?= =?UTF-8?q?=E5=9D=97=E9=9C=80=E6=B1=82=E4=B8=8E=E5=AE=9E=E7=8E=B0=E8=AE=B0?= =?UTF-8?q?=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit via [HAPI](https://hapi.run) Co-Authored-By: HAPI --- docs/过程背诵练习-需求与实现.md | 293 ++++++++++++++++++++++++++++++++ 1 file changed, 293 insertions(+) create mode 100644 docs/过程背诵练习-需求与实现.md diff --git a/docs/过程背诵练习-需求与实现.md b/docs/过程背诵练习-需求与实现.md new file mode 100644 index 0000000..e11f7eb --- /dev/null +++ b/docs/过程背诵练习-需求与实现.md @@ -0,0 +1,293 @@ +# 过程背诵练习模块 - 需求与实现记录 + +## 项目信息 +- **创建日期**: 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 + +// 当前焦点 +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） +- ✅ 创建本需求记录文档 + +--- + +**备注**: 本模块已完成核心功能开发和移动端优化，可以正常使用。后续可根据用户反馈进行功能增强和体验优化。