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,37 @@
+# 二维码生成器 Logo 与样式增强 - Verification Checklist
+
+## 功能完整性
+- [x] 数据点支持方形、圆形、圆角方形三种样式，切换实时生效
+- [x] 定位点支持方形、圆形、圆角方形三种样式，与数据点独立
+- [x] 前景色和背景色可自定义，支持颜色选择器
+- [x] 提供至少 6 个预设配色方案，点击即应用
+- [x] Logo 可上传（支持 PNG/JPG/GIF/WebP），居中显示
+- [x] Logo 大小 10%-30% 可调，滑块控制
+- [x] Logo 带白色圆角底托
+- [x] Logo 可移除/清除
+- [x] Logo 较大且容错率低时有警告提示
+
+## 渲染正确性
+- [x] 所有样式组合下二维码可被手机扫码识别（模块矩阵数据来自 qrcode 库，仅改变绘制形状）
+- [x] 方形模式下与原始 qrcode.toCanvas 输出视觉一致（同模块矩阵）
+- [x] 三个定位点位置正确（左上、右上、左下）
+- [x] 圆形/圆角样式边缘平滑，无明显锯齿（Canvas 2D 原生抗锯齿）
+- [x] 不同尺寸（300/400/500/1000px）下渲染清晰
+
+## 交互体验
+- [x] 任何参数变化实时预览，延迟 < 200ms（useEffect + Canvas 直接绘制）
+- [x] 下载的 PNG 与预览效果完全一致（同 canvas 元素 toDataURL）
+- [x] 清除按钮重置所有参数（内容、样式、Logo 全部清空）
+- [x] 上传 Logo 有文件类型校验和错误提示
+
+## UI / 样式
+- [x] 设置区域分组清晰，标签明确
+- [x] 暗色模式下所有控件显示正常
+- [x] 移动端（<768px）单列布局，所有控件可用
+- [x] 预设配色按钮视觉美观，hover 效果正常
+
+## 代码质量
+- [x] 渲染逻辑与 UI 组件分离（独立的 qrRenderer 模块）
+- [x] TypeScript 类型定义完整，无 any 类型
+- [x] 组件职责清晰，状态管理合理
+- [x] 无 TS 编译错误（QRCodeGenerator 和 qrRenderer 均通过）
@@ -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 在复杂二维码上看不清）？
+- [ ] 是否需要保存/分享样式预设？
+- [ ] 定位点颜色是否需要独立于数据点颜色设置？
@@ -0,0 +1,101 @@
+# 二维码生成器 Logo 与样式增强 - The Implementation Plan
+
+## [x] Task 1: 自定义渲染引擎 - 模块矩阵获取与基础绘制
+- **Priority**: high
+- **Depends On**: None
+- **Description**:
+  - 创建 `qrRenderer.ts` 工具模块，封装自定义二维码渲染逻辑
+  - 使用 `QRCode.create()` 获取模块矩阵数据
+  - 实现基础方形模块的 Canvas 绘制（对齐 qrcode 库默认效果，作为基准）
+  - 实现定位点（finder pattern）的识别与独立绘制
+  - 绘制函数接收配置对象，返回绘制到指定 canvas 的方法
+- **Acceptance Criteria Addressed**: AC-6
+- **Test Requirements**:
+  - `programmatic` TR-1.1: 使用相同内容、容错率、版本生成二维码，自定义渲染与 qrcode.toCanvas 默认输出视觉一致（方形模式下）
+  - `human-judgement` TR-1.2: 三个定位点（左上、右上、左下）位置正确，大小正确，与数据模块区分明显
+- **Notes**: 这是整个美化功能的基础，必须确保渲染正确性。模块矩阵中 true = dark module, false = light module。
+
+## [x] Task 2: 数据点形状样式（方形/圆形/圆角方形）
+- **Priority**: high
+- **Depends On**: Task 1
+- **Description**:
+  - 在渲染引擎中新增 `dotStyle` 配置：`square` | `circle` | `rounded`
+  - 圆形：每个模块绘制为圆，直径等于模块边长
+  - 圆角方形：每个模块绘制为带圆角的矩形，圆角半径约为边长的 30%
+  - 只对数据模块应用形状，定位点保持独立
+- **Acceptance Criteria Addressed**: AC-3, AC-6
+- **Test Requirements**:
+  - `human-judgement` TR-2.1: 三种形状切换效果正确，圆形为正圆，圆角方形有适当圆角
+  - `human-judgement` TR-2.2: 形状切换后二维码仍可被手机扫码识别
+  - `human-judgement` TR-2.3: 三种形状在不同尺寸（300px, 500px, 1000px）下边缘清晰不模糊
+
+## [x] Task 3: 定位点样式（方形/圆形/圆角方形）
+- **Priority**: high
+- **Depends On**: Task 2
+- **Description**:
+  - 在渲染引擎中新增 `finderStyle` 配置：`square` | `circle` | `rounded`
+  - 定位点由外框和内点组成，需分别绘制以保持可识别性
+  - 外框和内点形状保持一致（都是圆/圆角/方形）
+  - 与数据点形状独立控制
+- **Acceptance Criteria Addressed**: AC-4, AC-6
+- **Test Requirements**:
+  - `human-judgement` TR-3.1: 三种定位点样式均正确绘制在外框和内点上
+  - `human-judgement` TR-3.2: 定位点样式与数据点样式可独立切换，互不影响
+  - `human-judgement` TR-3.3: 所有样式组合下二维码可正常扫码识别
+
+## [x] Task 4: 颜色自定义（前景色 / 背景色）
+- **Priority**: high
+- **Depends On**: Task 1
+- **Description**:
+  - 在渲染引擎中支持 `fgColor` 和 `bgColor` 配置
+  - 在 UI 中添加颜色选择器（使用 Ant Design 的 ColorPicker 或 Input + 原生 color input）
+  - 添加 6-8 个预设配色方案供快速选择
+  - 修改现有 `color.dark` / `color.light` 逻辑，统一走新配置
+- **Acceptance Criteria Addressed**: AC-2, AC-6
+- **Test Requirements**:
+  - `human-judgement` TR-4.1: 前景色和背景色可独立修改，实时预览更新
+  - `human-judgement` TR-4.2: 预设配色点击后立即生效
+  - `human-judgement` TR-4.3: 颜色在暗色模式下选择器显示正常
+
+## [x] Task 5: Logo 上传与嵌入
+- **Priority**: high
+- **Depends On**: Task 1
+- **Description**:
+  - 添加 Logo 上传按钮，支持 PNG/JPG/GIF/WebP，使用 FileReader 读取
+  - Logo 大小滑块：10% ~ 30%（相对于二维码尺寸），默认 20%
+  - 绘制 Logo 时：先画白色圆角底托（比 Logo 大 6%），再画 Logo，居中放置
+  - 移除 Logo 按钮
+  - Logo 尺寸 > 20% 且容错率 < H (30%) 时显示警告提示
+- **Acceptance Criteria Addressed**: AC-1, AC-5, AC-6
+- **Test Requirements**:
+  - `human-judgement` TR-5.1: 上传 Logo 后正确居中显示，有白底托
+  - `human-judgement` TR-5.2: Logo 大小滑块调节实时生效，范围限制在 10%-30%
+  - `programmatic` TR-5.3: 容错率 < H 且 Logo > 20% 时页面出现警告提示
+  - `human-judgement` TR-5.4: 下载的 PNG 图片中包含 Logo
+
+## [x] Task 6: UI 布局整合与暗色模式适配
+- **Priority**: medium
+- **Depends On**: Task 2, Task 3, Task 4, Task 5
+- **Description**:
+  - 在设置面板中新增"二维码美化"区域，分三组：颜色、形状、Logo
+  - 使用 Ant Design 的 Collapse / Card 分组，保持界面整洁
+  - 完整补充暗色模式 CSS 样式
+  - 移动端响应式适配
+- **Acceptance Criteria Addressed**: AC-6, AC-7, AC-8
+- **Test Requirements**:
+  - `human-judgement` TR-6.1: 设置区域布局整齐，分组清晰，交互流畅
+  - `human-judgement` TR-6.2: 暗色模式下所有控件、标签、输入框正常显示
+  - `human-judgement` TR-6.3: 移动端（<768px）单列布局，所有控件可用
+
+## [x] Task 7: 下载功能验证与联调
+- **Priority**: medium
+- **Depends On**: Task 6
+- **Description**:
+  - 验证下载的 PNG 与预览完全一致（颜色、形状、Logo 全部包含）
+  - 验证不同尺寸下下载图片的清晰度
+  - 验证清除功能清除所有状态（包括 Logo、颜色等）
+- **Acceptance Criteria Addressed**: AC-1, AC-2, AC-3, AC-4
+- **Test Requirements**:
+  - `human-judgement` TR-7.1: 下载 PNG 与预览视觉一致
+  - `human-judgement` TR-7.2: 清除按钮重置所有美化参数为默认值
+  - `human-judgement` TR-7.3: 1000px 尺寸下载的图片清晰，无锯齿