5.9 KiB
5.9 KiB
二维码生成器 Logo 与样式增强 - Product Requirement Document
Overview
- Summary: 为现有的二维码生成器增加 Logo 上传嵌入功能，以及多种二维码美化样式（前景色、背景色、定位点样式、数据点形状等），使用户可以生成更具个性化和品牌感的二维码。
- Purpose: 解决当前二维码只有默认黑白方形样式、无法嵌入品牌 Logo、缺乏个性化美化选项的问题，提升工具的实用性和美观度。
- Target Users: 需要生成品牌二维码、营销二维码、个性化二维码的普通用户和运营人员。
Goals
- 支持上传 Logo 图片并嵌入二维码中心，自动调整容错率确保可扫描
- 支持自定义二维码前景色和背景色
- 支持多种数据点形状（方形、圆点、圆角方形等）
- 支持多种定位点（三个大角块）样式
- 样式变化时二维码实时预览更新
- 保持现有二维码生成功能（容错率、码版本、尺寸、边距）不被破坏
- 完整支持暗色模式
Non-Goals (Out of Scope)
- 不支持动态/渐变色二维码（先做纯色，后续可扩展）
- 不支持二维码背景图（仅支持纯色背景）
- 不支持 Logo 旋转、边框形状等高级 Logo 编辑
- 不支持 SVG / EPS 等矢量格式下载（仅 PNG）
- 不做服务端生成，所有逻辑在前端完成
Background & Context
- 二维码生成器刚完成基础功能升级：容错率、码版本(1-40)、码边距(1-4)、尺寸预设+自定义
- 当前使用
qrcode库 + Canvas 渲染，可在 Canvas 上进行二次绘制实现 Logo 和样式 qrcode库本身只输出基础方形模块，样式美化需要通过读取模块数据后自行在 Canvas 上绘制- 项目已有 Ant Design、i18n、暗色模式基础设施
Functional Requirements
- FR-1: Logo 上传与嵌入
- 用户可上传本地图片作为 Logo（支持 PNG / JPG / GIF / WebP）
- Logo 自动居中放置在二维码上
- Logo 大小可调（占二维码尺寸的 10% ~ 30%）
- Logo 可移除
- 开启 Logo 时自动提示用户将容错率调到 25% 或更高（H 级）
- FR-2: 颜色自定义
- 前景色（数据点颜色）选择器，默认黑色
- 背景色选择器，默认白色
- 提供若干预设颜色方案快速选择
- FR-3: 数据点形状样式
- 方形（默认）
- 圆形（圆点）
- 圆角方形
- FR-4: 定位点样式
- 方形（默认）
- 圆形
- 圆角方形
- 定位点颜色可与数据点一致或单独设置
- FR-5: 实时预览
- 任何参数变化（颜色、形状、Logo、容错率等）均实时重新渲染二维码
- 下载的图片与预览效果一致
- FR-6: 界面布局
- 新增"二维码美化"设置区域，放在现有高级设置下方
- 采用分组：颜色设置、形状设置、Logo 设置
- 移动端响应式适配
Non-Functional Requirements
- NFR-1: 二维码在所有样式组合下必须保持可扫描性（Logo 覆盖不超过 30% 面积）
- NFR-2: 样式切换渲染延迟 < 200ms（400px 尺寸下）
- NFR-3: 支持暗色模式，所有控件在暗色模式下正常显示
- NFR-4: 代码模块化，样式绘制逻辑与组件 UI 分离，便于后续扩展
Constraints
- 技术: React + TypeScript +
qrcode库 + Canvas 2D，不引入额外大型依赖 - 业务: 纯前端实现，不上传任何数据到服务器
- 依赖: 已安装
qrcode库，Ant Design 组件库
Assumptions
qrcode库的QRCode.create()方法可以返回模块矩阵数据供自定义渲染- Logo 覆盖面积在 30% 以内时，配合 H 级容错率可正常识别
- 浏览器 Canvas 2D API 足以绘制各种形状（圆、圆角矩形）
Acceptance Criteria
AC-1: Logo 上传与嵌入
- Given: 用户已生成一个二维码
- When: 用户上传一张 Logo 图片并调整大小
- Then: Logo 居中显示在二维码上，大小符合设定比例，下载图片中包含 Logo
- Verification:
human-judgment
AC-2: 颜色自定义
- Given: 用户在颜色设置中修改前景色和背景色
- When: 颜色值改变
- Then: 二维码预览实时更新为新的颜色组合，下载图片颜色一致
- Verification:
human-judgment
AC-3: 数据点形状切换
- Given: 用户在形状设置中切换数据点样式（方形/圆形/圆角方形）
- When: 选中新样式
- Then: 二维码数据模块形状立即变化，定位点保持默认方形
- Verification:
human-judgment
AC-4: 定位点样式切换
- Given: 用户切换定位点样式
- When: 选中新样式
- Then: 三个角的定位方块形状变化，与数据点样式独立
- Verification:
human-judgment
AC-5: 可扫描性保障
- Given: 用户上传了较大的 Logo 且容错率较低
- When: Logo 尺寸超过建议范围
- Then: 系统给出提示建议提高容错率，且 Logo 最大不超过 30%
- Verification:
programmatic
AC-6: 实时预览
- Given: 二维码已生成
- When: 用户修改任何样式参数（颜色、形状、Logo、容错率等）
- Then: 预览区二维码在 200ms 内更新
- Verification:
human-judgment
AC-7: 暗色模式兼容
- Given: 系统处于暗色模式
- When: 打开二维码生成器
- Then: 所有设置控件、标签、输入框均适配暗色主题，预览区边界清晰
- Verification:
human-judgment
AC-8: 移动端响应式
- Given: 在移动设备（宽度 < 768px）上打开页面
- When: 查看设置区域
- Then: 设置项变为单列布局，所有控件可正常点击和使用
- Verification:
human-judgment
Open Questions
- Logo 是否需要支持白色背景底托（避免透明 Logo 在复杂二维码上看不清）？
- 是否需要保存/分享样式预设？
- 定位点颜色是否需要独立于数据点颜色设置？