chore: v1.1.0 - 5项功能优化

2026-05-24 18:28:48 +08:00
parent cd4fcfefa2
commit 84fd33fce1
9 changed files with 3045 additions and 71 deletions
--- a/Code/docs/frontend-architecture.md
+++ b/Code/docs/frontend-architecture.md
--- a/Code/docs/modification-assessment.md
+++ b/Code/docs/modification-assessment.md
@@ -0,0 +1,190 @@
+# 修改评估文档
+
+> 项目：在线点名抽奖 (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*
--- a/Code/docs/team.md
+++ b/Code/docs/team.md
@@ -0,0 +1,21 @@
+# 项目成员表
+
+> 项目：在线点名抽奖 (PROJ-20260523012)
+> 创建时间：2026-05-23
+
+## 成员列表
+
+| 成员 | 职责 | 负责功能 |
+|------|------|---------|
+| frontend-architect | 前端架构设计 | 整体架构设计、技术选型、模块划分 |
+| frontend-coding-agent | 前端编码实现 | HTML/CSS/JS 代码实现 |
+| test-qa-agent | 测试验证 | 功能测试、边界测试 |
+| doc-gen-agent | 文档生成 | README.md、使用文档 |
+| package-release-agent | 打包发布 | Git 同步、版本管理、Release |
+
+## 修改记录
+
+| 版本 | 日期 | 修改内容 | 修改人 |
+|------|------|---------|--------|
+| v1.0.0 | 2026-05-23 | 初始版本 | frontend-coding-agent |
+| v1.1.0 | 2026-05-24 | 功能优化（5项）：名单编辑、概率后门、滚动动画改进、结果弹窗、烟花效果改进 | frontend-coding-agent |