9.9 KiB
9.9 KiB
修改评估文档
项目：在线点名抽奖 (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）
- 新增弹窗 HTML 结构：在
- 依赖关系：
- 依赖 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 弹窗位置 ─────── 独立
建议实施顺序：
- M001 → 名单编辑（最基础，无依赖）
- M002 → 概率后门（核心逻辑变更，需先完成 M001）
- M003 → 滚动动画（独立，可与 M004/M005 并行开发）
- M004 → 弹窗显示（依赖 M003 完成）
- 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