191 lines
9.9 KiB
Markdown
191 lines
9.9 KiB
Markdown
# 修改评估文档
|
||
|
||
> 项目：在线点名抽奖 (PROJ-20260523012)
|
||
> 评估时间：2026-05-24
|
||
> 版本：v1.0.0 → v1.1.0
|
||
> 评估人：前端架构 Agent
|
||
|
||
---
|
||
|
||
## 修改评估总览
|
||
|
||
| 修改项 ID | 修改内容 | 影响范围 | 目标 Agent | 是否需要架构设计 | 难度 | 说明 |
|
||
|----------|---------|---------|-----------|----------------|------|------|
|
||
| M001 | 名单编辑功能（删除按钮） | 名单管理模块 + CSS | frontend-coding-agent | ❌ | 低 | 在现有 name-tag 上追加 × 按钮和删除逻辑 |
|
||
| M002 | 概率后门（每人概率设置） | 抽奖引擎 + 后门模块 + 状态结构 | frontend-coding-agent | ⚠️ 部分 | 中 | 需扩展状态结构、改造 pickOne 加权随机算法、后门面板新增概率输入 |
|
||
| M003 | 滚动动画改进（左→右滚动 + 快速启动） | 动画模块 + CSS | frontend-coding-agent | ❌ | 中 | 从名字切换改为水平滚动条效果，调整缓动曲线 |
|
||
| M004 | 弹窗显示中奖结果 | 动画模块 + CSS + HTML 结构 | frontend-coding-agent | ❌ | 低 | 用模态弹窗替代当前 result-area 内联显示 |
|
||
| M005 | 烟花效果改进（弹窗周围炸开 + 3秒以上） | 动画模块（Canvas 烟花） | frontend-coding-agent | ❌ | 中 | 移除底部上升阶段，改为弹窗位置直接爆炸，延长持续时间 |
|
||
|
||
---
|
||
|
||
## 详细评估
|
||
|
||
### M001: 名单编辑功能（删除按钮）
|
||
|
||
- **影响模块**：`NameManager` 模块、CSS（`.name-tag` 样式）
|
||
- **需要变更**：
|
||
- `NameManager.renderNameList()`：每个 name-tag 内追加 × 按钮，绑定点击事件
|
||
- 新增 `NameManager.removeByName(name)` 方法：从 `state.pool` 中移除指定名字，更新计数和列表
|
||
- CSS 新增 `.name-tag .delete-btn` 样式（小 × 号，hover 高亮，红色）
|
||
- **依赖关系**：无外部依赖，纯前端 DOM 操作
|
||
- **风险点**：
|
||
- 删除后需同步更新 `state.backdoor.mustWinList` 和 `excludeList`（避免引用已删除的名字）
|
||
- 若当前正在抽奖中（`state.isDrawing === true`），应禁用删除操作
|
||
- **代码量预估**：~50 行 JS + ~15 行 CSS
|
||
- **架构设计变更**：不需要。属于现有模块的功能增强。
|
||
|
||
---
|
||
|
||
### M002: 概率后门（每人概率设置）
|
||
|
||
- **影响模块**：`LotteryEngine` 模块、`Backdoor` 模块、`state` 状态结构、后门面板 HTML/CSS
|
||
- **需要变更**：
|
||
- **状态扩展**：`state.backdoor.probabilities` 新增字段，结构为 `{ name: weight }` 的对象（权重值 0-100）
|
||
- **人员对象扩展**：`person` 对象新增 `weight` 字段（默认 1，表示等概率）
|
||
- **抽奖引擎改造**：`LotteryEngine.pickOne()` 从等概率随机改为**加权随机**：
|
||
```
|
||
1. 候选池 = state.pool 副本
|
||
2. 过滤排除名单
|
||
3. 若必中名单非空：取交集
|
||
4. 计算总权重 = Σ(person.weight)
|
||
5. 随机数 r = Math.random() * totalWeight
|
||
6. 累加权重找到对应人选（加权随机算法）
|
||
```
|
||
- **后门面板**：新增概率设置区域，支持为每个人设置概率百分比（0-100），可输入数值或滑块
|
||
- **Backdoor.renderChecklists()**：每个名字旁新增概率输入框
|
||
- **依赖关系**：
|
||
- 依赖 M001 的删除逻辑（删除人时同步清理概率配置）
|
||
- 与现有必中/排除名单逻辑共存，需明确优先级：必中名单 > 概率权重 > 排除名单
|
||
- **风险点**：
|
||
- 概率总和不为 100% 时的处理策略（建议：按权重比例分配，不强制归一化）
|
||
- 概率为 0 的人是否等同于排除名单（建议：是，概率 0 的人不参与抽奖）
|
||
- 后门面板 UI 复杂度增加，需注意滚动区域和响应式
|
||
- **代码量预估**：~120 行 JS + ~60 行 CSS + HTML 结构变更
|
||
- **架构设计变更**：⚠️ 部分需要。`state` 数据结构需扩展，`LotteryEngine.pickOne()` 核心算法需改造。需更新 `frontend-architecture.md` 的状态设计和抽奖引擎算法部分。
|
||
|
||
---
|
||
|
||
### M003: 滚动动画改进（从左到右滚动 + 快速启动）
|
||
|
||
- **影响模块**：`AnimationEngine` 模块、CSS（`.roll-area`、`.roll-name` 相关样式）
|
||
- **需要变更**：
|
||
- **滚动方式改造**：从当前"中心位置名字切换"改为"水平滚动条"效果
|
||
- 名字在水平方向上连续滚动，类似老虎机/跑马灯
|
||
- 使用 CSS `transform: translateX()` 或 Canvas 实现
|
||
- 滚动方向：从左到右
|
||
- **速度曲线调整**：
|
||
- 初始速度要快（建议：初始间隔 20-30ms，即每秒 30-50 个名字切换）
|
||
- 逐渐减速（缓动函数保持不变或改用更陡峭的 easeOut）
|
||
- 总时长保持 3.5 秒左右
|
||
- **CSS 新增**：滚动容器的 overflow hidden、名字项的水平排列样式
|
||
- **DOM 结构**：可能需要在 roll-area 内新增滚动容器 div
|
||
- **依赖关系**：
|
||
- 与 M004 弹窗显示有 UI 交互关系（弹窗弹出时滚动应已停止）
|
||
- 头像显示区域可能也需要配合调整（头像跟随滚动还是固定居中）
|
||
- **风险点**：
|
||
- 水平滚动的性能：大量 DOM 节点滚动可能卡顿，建议使用 transform 而非改变 left 属性
|
||
- 移动端兼容性：触摸滚动与动画滚动的冲突
|
||
- 头像与名字滚动的同步问题
|
||
- **代码量预估**：~100 行 JS + ~80 行 CSS + HTML 结构调整
|
||
- **架构设计变更**：不需要。属于动画模块内部实现替换，接口不变（`startRollAnimation(winner, callback)` 签名不变）。
|
||
|
||
---
|
||
|
||
### M004: 弹窗显示中奖结果
|
||
|
||
- **影响模块**：动画模块（`AnimationEngine.startRollAnimation` 的 callback）、CSS（弹窗样式）、HTML 结构
|
||
- **需要变更**：
|
||
- **新增弹窗 HTML 结构**：在 `#app` 内新增中奖弹窗 div（类似后门面板的遮罩 + 模态框结构）
|
||
- 遮罩层：全屏半透明黑色
|
||
- 弹窗内容：中奖人头像（大尺寸）、名字、"恭喜"字样
|
||
- 关闭按钮或点击遮罩关闭
|
||
- **CSS 新增**：弹窗遮罩、弹窗容器、动画（弹出缩放 + 淡入效果）
|
||
- **动画模块修改**：`startRollAnimation` 的 callback 中，从设置 `resultArea` 改为打开弹窗
|
||
- **交互**：弹窗可点击关闭，关闭后显示原有的 result-area（或直接用弹窗替代 result-area）
|
||
- **依赖关系**：
|
||
- 依赖 M003 滚动动画停止后才弹出（时序关系）
|
||
- 与 M005 烟花效果配合：弹窗弹出时烟花同时开始
|
||
- 与 M002 概率后门无直接依赖
|
||
- **风险点**：
|
||
- 弹窗的 z-index 需高于烟花 Canvas（当前烟花 z-index: 9999），弹窗 z-index 需设为 10001+
|
||
- 弹窗动画与烟花动画的性能叠加，需注意低端设备
|
||
- **代码量预估**：~60 行 JS + ~70 行 CSS + ~20 行 HTML
|
||
- **架构设计变更**：不需要。属于 UI 层变更，不改变模块接口。
|
||
|
||
---
|
||
|
||
### M005: 烟花效果改进（弹窗周围炸开 + 3秒以上）
|
||
|
||
- **影响模块**：`AnimationEngine.fireFireworks()` 方法、Canvas 粒子系统
|
||
- **需要变更**：
|
||
- **移除上升阶段**：当前 `Firework` 类有 `'rising'` 状态（从底部升到目标位置），需移除
|
||
- 烟花直接在目标位置爆炸，不再从底部发射
|
||
- **爆炸位置**：围绕弹窗位置生成爆炸点
|
||
- 获取弹窗 DOM 元素的中心坐标
|
||
- 在弹窗周围一定半径范围内随机生成爆炸点
|
||
- 爆炸点分布：弹窗的上下左右四个方向
|
||
- **持续时间**：从当前 4 秒改为 3 秒以上（建议 4-5 秒）
|
||
- 修改 `endTime = performance.now() + 5000`
|
||
- **粒子效果优化**：
|
||
- 增加初始爆炸的粒子数量（更密集）
|
||
- 可考虑多波爆炸效果（第一波密集，后续逐渐稀疏）
|
||
- **依赖关系**：
|
||
- 依赖 M004 弹窗的位置信息（需要弹窗 DOM 元素的坐标）
|
||
- 与 M003 无直接依赖
|
||
- 与 M002 无直接依赖
|
||
- **风险点**：
|
||
- 弹窗位置动态变化（响应式）时需重新计算爆炸点
|
||
- 烟花持续 3 秒以上时，粒子数量控制很重要，避免内存泄漏或卡顿
|
||
- 窗口 resize 时的 canvas 尺寸同步
|
||
- **代码量预估**：~80 行 JS 修改
|
||
- **架构设计变更**：不需要。属于动画模块内部实现修改，接口不变（`fireFireworks()` 无参数调用）。
|
||
|
||
---
|
||
|
||
## 修改项依赖关系图
|
||
|
||
```
|
||
M001 (名单编辑) ────────────────────────────── 独立
|
||
M002 (概率后门) ─── 依赖 M001 的删除同步逻辑 ─── 需架构设计更新
|
||
M003 (滚动动画) ────────────────────────────── 独立
|
||
M004 (弹窗显示) ─── 依赖 M003 滚动停止 ─────── 独立
|
||
M005 (烟花改进) ─── 依赖 M004 弹窗位置 ─────── 独立
|
||
```
|
||
|
||
**建议实施顺序**：
|
||
1. **M001** → 名单编辑（最基础，无依赖）
|
||
2. **M002** → 概率后门（核心逻辑变更，需先完成 M001）
|
||
3. **M003** → 滚动动画（独立，可与 M004/M005 并行开发）
|
||
4. **M004** → 弹窗显示（依赖 M003 完成）
|
||
5. **M005** → 烟花改进（依赖 M004 完成）
|
||
|
||
---
|
||
|
||
## 总体影响评估
|
||
|
||
| 维度 | 评估 |
|
||
|------|------|
|
||
| **代码改动量** | 中等（约 400-500 行 JS + 200-250 行 CSS + HTML 结构调整） |
|
||
| **架构变更** | 仅 M002 需要更新状态结构和核心算法，其余为 UI/动画层变更 |
|
||
| **测试重点** | M002 加权随机算法的正确性、M003/M005 动画性能、M001 删除边界情况 |
|
||
| **兼容性影响** | 无新增 API 依赖，保持现有浏览器兼容性 |
|
||
| **文件变更** | 仅 `index.html` 单文件（符合项目约束） |
|
||
|
||
---
|
||
|
||
## 目标 Agent 分配总结
|
||
|
||
| Agent | 负责修改项 | 工作量 |
|
||
|-------|-----------|--------|
|
||
| **frontend-coding-agent** | M001, M002, M003, M004, M005（全部） | 高（5 项全部） |
|
||
| **test-qa-agent** | 全部 5 项的功能测试 + 性能测试 | 中 |
|
||
| **doc-gen-agent** | 更新 README 和使用文档 | 低 |
|
||
| **package-release-agent** | Git 同步 + v1.1.0 版本发布 | 低 |
|
||
|
||
---
|
||
|
||
*文档版本: v1.0*
|
||
*创建时间: 2026-05-24*
|
||
*作者: 前端架构 Agent*
|