# 修改评估文档

> 项目：在线点名抽奖 (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*