sync from local backup

2026-08-05 23:59:22 +08:00
commit a59f46b894
409 changed files with 166027 additions and 0 deletions
@@ -0,0 +1,127 @@
+# 二维码生成器 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 在复杂二维码上看不清）？
+- [ ] 是否需要保存/分享样式预设？
+- [ ] 定位点颜色是否需要独立于数据点颜色设置？