wenpai
9587cd8ef4
Sprint 1 - 安全基线修复（5项）: - 修复 DOM XSS 漏洞（seal-library.js, batch-processing.js） - 修复 settings 导入 schema 注入 - CDN 锁版本 + SRI 完整性校验 - 外链添加 rel="noopener noreferrer" - 替换 confirm/prompt 为自定义对话框 Sprint 2 - 状态管理重构（4项）: - 新建 state.js 单例模式管理全局状态 - 解耦 window.* 全局变量 - 修复印章库状态同步 bug - localStorage 添加错误处理 Sprint 3 - 性能优化（4项）: - 删除死代码（loadScript, cleanupDistantCanvases 等） - 实现缩略图懒加载（前3页+可视区） - 添加文件大小限制（PDF 50MB / 图片 5MB） - 完善 Canvas 内存清理 修复总计: 13项（3 P0 + 3 P1 + 6 P2 + 1 P3） [CC] [CX]
9.8 KiB
9.8 KiB
PDF Stamper 开发计划
项目名称：PDF Stamper - 现代化 PDF 盖章工具 当前版本：v1.0.0 计划版本：v2.0.0 制定日期：2026-01-07 开发策略：渐进式改进（方案 A）
📊 项目现状评估
当前评分：6.5/10
| 维度 | 评分 | 说明 |
|---|---|---|
| 功能完整性 | 8/10 | 核心功能完备，缺少高级特性 |
| 代码质量 | 5/10 | 单文件架构，全局状态，需重构 |
| 性能表现 | 5/10 | 大文件卡顿，内存泄漏 |
| 用户体验 | 7/10 | UI 现代，但缺少反馈和移动端支持 |
| 安全性 | 6/10 | 无文件大小限制，缺少 SRI |
| 可维护性 | 5/10 | 760 行单文件，无测试 |
核心问题
Critical（阻塞性问题）
- ❌ 大文件性能问题（>50 页 PDF 卡顿）
- ❌ 内存泄漏（Canvas 和事件监听未清理）
- ❌ 无文件大小限制（可能导致浏览器崩溃）
- ❌ 单文件架构（760 行，难以维护）
High（高优先级）
- ⚠️ 用户反馈不友好（使用 alert）
- ⚠️ 无加载指示器
- ⚠️ 无撤销/重做功能
- ⚠️ 移动端不可用
🎯 开发目标
短期目标（v1.1.0 - 2 周）
解决关键性能和用户体验问题，使应用稳定可用
中期目标（v1.5.0 - 4 周）
模块化重构，添加核心功能，提升可维护性
长期目标（v2.0.0 - 8 周）
完整的功能集，企业级质量，移动端支持
📅 开发路线图
Phase 1: 紧急修复（第 1-2 周）
目标：解决阻塞性问题，提升稳定性
Week 1: 性能优化与错误处理
Day 1-2: 文件限制与验证
- 添加 PDF 文件大小限制（50MB）
- 添加图片文件大小限制（5MB）
- 添加页数限制（500 页）
- 实现文件类型验证
- 添加图片尺寸验证
Day 3-4: 懒加载实现
- 重构页面渲染逻辑
- 实现按需创建 Canvas
- 只渲染当前页 + 前后各 1 页
- 优化缩略图生成（降低分辨率）
- 测试大文件性能（100+ 页）
Day 5: 内存泄漏修复
- 实现 Canvas 销毁方法
- 清理事件监听器
- 释放图片资源（revoke ObjectURL）
- 添加页面切换时的清理逻辑
Week 2: 用户体验改进
Day 1-2: 通知系统
- 创建 Toast 通知组件
- 替换所有 alert() 调用
- 添加成功/错误/警告样式
- 实现自动消失和手动关闭
Day 3-4: 加载指示器
- 创建 Loading 组件
- PDF 加载时显示进度
- 导出时显示进度条
- 添加操作反馈动画
Day 5: 测试与修复
- 完整功能测试
- 修复发现的 Bug
- 性能测试（不同大小 PDF）
- 发布 v1.1.0
交付物：
- ✅ 稳定的性能（支持 100 页 PDF）
- ✅ 友好的用户反馈
- ✅ 无内存泄漏
- ✅ 文件大小保护
Phase 2: 功能增强（第 3-4 周）
目标：添加核心功能，提升用户体验
Week 3: 撤销/重做与印章管理
Day 1-3: 撤销/重做系统
- 设计命令模式架构
- 实现历史记录栈
- 添加撤销/重做按钮
- 实现键盘快捷键（Ctrl+Z / Ctrl+Y）
- 限制历史记录数量（最多 50 步）
Day 4-5: 印章库功能
- 设计印章存储结构（LocalStorage）
- 实现印章保存功能
- 创建印章库 UI
- 实现快速选择印章
- 添加印章删除功能
Week 4: 高级功能
Day 1-2: 印章透明度控制
- 添加透明度滑块
- 实时预览透明度
- 应用到普通章和骑缝章
- 保存透明度设置
Day 3-4: 键盘快捷键
- 实现快捷键系统
- 添加常用操作快捷键
- Delete/Backspace: 删除
- Ctrl+Z: 撤销
- Ctrl+Y: 重做
- Ctrl+S: 导出
- Arrow keys: 微调位置
- 创建快捷键帮助面板
Day 5: 测试与发布
- 功能测试
- 用户体验测试
- 发布 v1.5.0
交付物：
- ✅ 撤销/重做功能
- ✅ 印章库管理
- ✅ 印章透明度控制
- ✅ 键盘快捷键
Phase 3: 架构重构（第 5-6 周）
目标：模块化代码，提升可维护性
Week 5: 代码拆分
Day 1-2: 状态管理模块
src/modules/state.js
- 集中管理全局状态
- 实现状态订阅机制
- 添加状态验证
Day 2-3: 核心功能模块
src/modules/
├── pdf-loader.js # PDF 加载与解析
├── stamp-manager.js # 印章管理逻辑
├── canvas-manager.js # Canvas 操作封装
└── exporter.js # PDF 导出功能
Day 4-5: UI 组件模块
src/ui/
├── notifications.js # 通知系统
├── loading.js # 加载指示器
├── toolbar.js # 工具栏交互
└── sidebar.js # 侧边栏管理
Week 6: 工具与测试
Day 1-2: 工具函数
src/utils/
├── validators.js # 输入验证
├── image-utils.js # 图片处理
├── constants.js # 常量配置
└── helpers.js # 辅助函数
Day 3-4: 单元测试
- 设置测试环境（Vitest）
- 编写核心函数测试
- 验证器测试
- 状态管理测试
Day 5: 重构完成
- 代码审查
- 性能对比测试
- 文档更新
- 发布 v1.8.0
交付物：
- ✅ 模块化代码结构
- ✅ 单元测试覆盖
- ✅ 更好的可维护性
Phase 4: 移动端与高级功能（第 7-8 周）
目标：移动端支持，企业级功能
Week 7: 响应式设计
Day 1-3: 移动端适配
- 响应式布局重构
- 触摸手势支持
- 移动端工具栏优化
- 侧边栏抽屉式设计
Day 4-5: 批量操作
- 多页选择功能
- 批量添加印章
- 批量删除印章
- 批量导出
Week 8: 高级功能与发布
Day 1-2: 高级编辑
- 印章精确定位（坐标输入）
- 印章复制/粘贴
- 印章对齐辅助线
- 印章锁定功能
Day 3-4: 安全增强
- 添加 CDN SRI 哈希
- 文件名安全处理
- 添加 CSP 策略
- 安全审计
Day 5: v2.0.0 发布
- 完整测试
- 性能基准测试
- 文档完善
- 正式发布
交付物：
- ✅ 移动端完整支持
- ✅ 批量操作功能
- ✅ 高级编辑功能
- ✅ 企业级安全性
🛠️ 技术栈
保持不变
- 纯 HTML/CSS/JavaScript（无构建工具）
- PDF.js（PDF 渲染）
- Fabric.js（Canvas 操作）
- pdf-lib（PDF 导出）
新增工具
- Vitest（单元测试）- 可选
- ESLint（代码规范）- 可选
- Prettier（代码格式化）- 可选
📏 成功指标
性能指标
- 100 页 PDF 加载时间 < 3 秒
- 页面切换响应 < 100ms
- 导出 50 页 PDF < 5 秒
- 内存使用稳定（无泄漏）
用户体验指标
- 所有操作有明确反馈
- 移动端可正常使用
- 支持键盘操作
- 错误提示清晰友好
代码质量指标
- 单文件代码 < 300 行
- 核心函数测试覆盖率 > 70%
- 无 ESLint 错误
- 代码注释覆盖率 > 50%
🚨 风险与应对
技术风险
风险 1：模块化后性能下降
- 应对：保持模块轻量，避免过度抽象
- 监控：每次重构后进行性能对比测试
风险 2：懒加载导致用户体验问题
- 应对：预加载相邻页面，添加加载动画
- 监控：测试不同网络条件下的表现
风险 3：兼容性问题
- 应对：保持浏览器兼容性测试
- 监控：支持主流浏览器最近 2 个版本
项目风险
风险 4：开发时间超期
- 应对：优先完成 Phase 1-2，Phase 3-4 可延后
- 监控：每周评估进度，及时调整
风险 5：功能蔓延
- 应对：严格按照计划执行，新需求记录到 backlog
- 监控：每个 Phase 结束时评审
📝 开发规范
代码规范
- 使用 ES6+ 语法
- 函数单一职责，长度 < 50 行
- 必须添加 JSDoc 注释
- 变量命名清晰（camelCase）
- 常量使用 UPPER_SNAKE_CASE
Git 提交规范
feat: 新功能
fix: Bug 修复
refactor: 重构
perf: 性能优化
docs: 文档更新
test: 测试相关
chore: 构建/工具相关
测试规范
- 核心功能必须有单元测试
- 每个 Phase 结束前完整测试
- 性能测试使用标准 PDF 文件
📦 交付清单
v1.1.0（第 2 周）
- 文件大小限制
- 懒加载实现
- 内存泄漏修复
- Toast 通知系统
- 加载指示器
v1.5.0（第 4 周）
- 撤销/重做功能
- 印章库管理
- 印章透明度
- 键盘快捷键
v1.8.0（第 6 周）
- 模块化架构
- 单元测试
- 代码文档
v2.0.0（第 8 周）
- 移动端支持
- 批量操作
- 高级编辑
- 安全增强
🔄 迭代策略
每周迭代
- 周一：计划本周任务
- 周二-周四：开发实现
- 周五：测试、修复、代码审查
- 周末：可选的探索性开发
每个 Phase 结束
- 完整功能测试
- 性能基准测试
- 用户体验评审
- 发布版本
- 收集反馈
📚 参考资源
技术文档
最佳实践
🎯 下一步行动
立即开始：Phase 1 - Week 1 - Day 1
- 创建
src/utils/validators.js - 实现文件大小验证
- 添加错误提示
命令：
# 创建目录结构
mkdir -p src/{modules,ui,utils}
# 开始开发
# 从 validators.js 开始
最后更新：2026-01-07 负责人：开发团队 审核人：项目负责人
