yinji/docs/DEVELOPMENT_PLAN.md

# 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 周）
- [x] 文件大小限制
- [x] 懒加载实现
- [x] 内存泄漏修复
- [x] Toast 通知系统
- [x] 加载指示器

### v1.5.0（第 4 周）
- [ ] 撤销/重做功能
- [ ] 印章库管理
- [ ] 印章透明度
- [ ] 键盘快捷键

### v1.8.0（第 6 周）
- [ ] 模块化架构
- [ ] 单元测试
- [ ] 代码文档

### v2.0.0（第 8 周）
- [ ] 移动端支持
- [ ] 批量操作
- [ ] 高级编辑
- [ ] 安全增强

---

## 🔄 迭代策略

### 每周迭代
1. **周一**：计划本周任务
2. **周二-周四**：开发实现
3. **周五**：测试、修复、代码审查
4. **周末**：可选的探索性开发

### 每个 Phase 结束
1. 完整功能测试
2. 性能基准测试
3. 用户体验评审
4. 发布版本
5. 收集反馈

---

## 📚 参考资源

### 技术文档
- [PDF.js Documentation](https://mozilla.github.io/pdf.js/)
- [Fabric.js Documentation](http://fabricjs.com/docs/)
- [pdf-lib Documentation](https://pdf-lib.js.org/)

### 最佳实践
- [JavaScript Clean Code](https://github.com/ryanmcdermott/clean-code-javascript)
- [Web Performance Best Practices](https://web.dev/performance/)
- [Accessibility Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)

---

## 🎯 下一步行动

**立即开始**：Phase 1 - Week 1 - Day 1
- 创建 `src/utils/validators.js`
- 实现文件大小验证
- 添加错误提示

**命令**：
```bash
# 创建目录结构
mkdir -p src/{modules,ui,utils}

# 开始开发
# 从 validators.js 开始
```

---

**最后更新**：2026-01-07
**负责人**：开发团队
**审核人**：项目负责人