128 lines
5.9 KiB
Markdown
128 lines
5.9 KiB
Markdown
# 二维码生成器 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 在复杂二维码上看不清）？
|
||
- [ ] 是否需要保存/分享样式预设？
|
||
- [ ] 定位点颜色是否需要独立于数据点颜色设置？
|