wushu/docs/superpowers/specs/2026-04-03-poetry-theme-refactor-design.md

诗词答题页面主题色支持与代码重构设计文档

日期： 2026-04-03
状态： 待实现
作者： AI Assistant

1. 概述

1.1 目标

将诗词答题相关页面重构以支持动态主题色，并将代码分流到 poetry-page.dart，实现 UI 和逻辑的分离。

1.2 范围

涉及文件：

• lib/views/profile/level/poetry.dart - 主页面（状态管理、网络请求）
• lib/views/profile/level/poetry-page.dart - UI 组件（选项、标签、布局）
• lib/views/profile/level/flow-anim.dart - 流动边框动画
• lib/views/profile/level/distinguish.dart - 答题记录页面
• lib/views/profile/level/level-jilu.dart - 业务逻辑管理器（无需修改）

2. 架构设计

2.1 文件结构

lib/views/profile/level/
├── poetry.dart                    # 主页面（状态管理、网络请求）
├── poetry-page.dart               # UI 组件（选项、标签、布局）
├── level-jilu.dart                # 业务逻辑管理器
├── flow-anim.dart                 # 流动边框动画
└── distinguish.dart               # 答题记录页面

2.2 职责划分

poetry.dart 职责：

• PoetryLevelPage 类（StatefulWidget）
• _PoetryLevelPageState 类
• 状态变量管理
• 生命周期方法
• 业务逻辑方法（网络请求、数据处理）
• build 方法的主框架

poetry-page.dart 职责：

• UI 组件定义
• 主题色支持
• 深色模式适配
• 组件复用

3. 组件设计

3.1 PoetryOptionItem 组件

功能： 单个答题选项组件

参数：

• option: dynamic - 选项数据
• isSelected: bool - 是否被选中
• isCorrect: bool - 是否正确
• isWrong: bool - 是否错误
• isSubmitting: bool - 是否正在提交
• showFeedback: bool - 是否显示反馈
• isAnswerCorrect: bool - 答案是否正确
• onTap: Function(int) - 点击回调

主题色支持：

• 使用 ThemeColors.getThemeColor(themeController.themeColorIndexRx.value) 获取主题色
• 正确答案使用 Colors.green
• 错误答案使用 Colors.red
• 背景色根据深色模式动态调整

3.2 PoetryOptionsLayout 组件

功能： 选项布局组件（支持 2x2 和 1x4 布局）

参数：

• options: List - 选项列表
• selectedAnswer: int? - 选中的答案
• showFeedback: bool - 是否显示反馈
• isAnswerCorrect: bool - 答案是否正确
• isSubmitting: bool - 是否正在提交
• onTap: Function(int) - 点击回调

布局逻辑：

• 检查所有选项是否都少于等于4个字
• 如果是且选项数>=4，使用 2x2 布局
• 否则使用 1x4 布局

3.3 PoetryTag 组件

功能： 标签组件（显示题目类型、年级、朝代）

参数：

• label: String - 标签名称
• value: String - 标签值

主题色支持：

• 使用主题色作为背景色和文字颜色

4. 主题色支持策略

4.1 颜色替换规则

替换：

• AppConstants.primaryColor → ThemeColors.getThemeColor(themeController.themeColorIndexRx.value)

保留：

• 正确答案：Colors.green / AppColors.iosGreen
• 错误答案：Colors.red / AppColors.iosRed
• 背景色：根据深色模式动态调整

4.2 深色模式支持

判断方式：

• 使用 themeController.isDarkModeRx.value 判断深色模式

颜色调整：

• 背景色：isDark ? Color(0xFF1A1A1A) : Colors.white
• 文字颜色：isDark ? Colors.grey[300] : Colors.grey[700]
• 边框颜色：isDark ? Colors.white.withAlpha(20) : Colors.black.withAlpha(10)

5. 实现步骤

5.1 创建 poetry-page.dart

1. 创建 PoetryOptionItem 组件
2. 创建 PoetryOptionsLayout 组件
3. 创建 PoetryTag 组件
4. 添加主题色支持
5. 添加深色模式支持

5.2 修改 poetry.dart

1. 移除 _buildOptionItem 方法
2. 移除 _buildOptionsLayout 方法
3. 移除 _buildTag 方法
4. 导入 poetry-page.dart
5. 使用新组件替换原有方法
6. 添加主题色支持

5.3 修改 flow-anim.dart

1. 添加主题色支持
2. 使用 ThemeColors.getThemeColor() 替换硬编码颜色

5.4 修改 distinguish.dart

1. 添加主题色支持
2. 使用 ThemeColors.getThemeColor() 替换硬编码颜色

6. 测试要点

6.1 功能测试

• 选项点击正常
• 答案提交正常
• 反馈显示正常
• 布局切换正常（2x2 和 1x4）

6.2 主题色测试

• 主题色切换正常
• 所有组件颜色同步更新
• 深色模式切换正常

6.3 兼容性测试

• 关怀模式正常显示
• 底部导航栏不遮挡内容
• 动画效果正常

7. 注意事项

1. 保持布局不变：重构过程中不修改页面布局
2. 代码平衡：确保两个文件代码量相近
3. 性能优化：使用 Obx 进行响应式更新，避免不必要的重建
4. 向后兼容：确保现有功能不受影响

8. 后续优化

1. 考虑将更多组件提取到 poetry-page.dart
2. 添加单元测试
3. 优化性能，减少不必要的重建
4. 添加更多主题色选项