Refactor README.md to streamline project overview and features; remove outdated documentation files; enhance structure and clarity for better user guidance; update project features and technology stack sections.

2 months ago · 1fcc3dbbc0
parent d90fc5a034
commit 1fcc3dbbc0
9 changed files with 493 additions and 70 deletions
--- a/README.md
+++ b/README.md
@ -1,90 +1,61 @@
-# MyQrCode - SwiftUI 版本
+# MyQrCode
-## 项目概述
+## 📱 项目简介
-这是一个使用 SwiftUI 构建的条码扫描器应用，支持二维码和多种条形码格式，已经从原来的 UIKit 版本完全转换为 SwiftUI。
+MyQrCode 是一个功能完整的二维码和条形码扫描应用，采用 SwiftUI 和 AVFoundation 技术栈开发。
-## 主要变化
+## ⭐ 主要特性
-### 从 UIKit 转换为 SwiftUI
+- **多格式支持**: QR码、条形码等多种格式
 - **多码识别**: 同时识别多个条码并允许用户选择
 - **微信风格界面**: 暂停预览和用户选择功能
 - **多样化扫描线**: 5种不同风格的扫描线动画
 - **多语言支持**: 中英文双语界面
 - **权限管理**: 完整的相机权限管理
 - **日志系统**: 详细的调试和监控日志
- **ScannerViewController.swift** → **ScannerView.swift**
+## 🚀 快速开始
  - 使用 `@StateObject` 管理扫描器状态
  - 使用 `UIViewRepresentable` 包装相机预览层
  - 采用 MVVM 架构模式
-### 新特性
+1. 克隆项目到本地
 2. 使用 Xcode 15+ 打开项目
 3. 在真机上运行和测试
 4. 确保在 Info.plist 中添加相机权限描述
-1. **现代化的 UI 设计**
+## 🛠️ 技术栈
   - 扫描框覆盖层，提供视觉引导
   - 美观的按钮和文本样式
   - 响应式布局
-2. **改进的状态管理**
+- **UI框架**: SwiftUI
-   - 使用 `@Published` 属性包装器
+- **相机功能**: AVFoundation
-   - 通过通知中心传递扫描结果
+- **架构模式**: MVVM
-   - 更好的错误处理
+- **状态管理**: Combine + @Published
 - **最低版本**: iOS 15.0+
-3. **用户体验优化**
+## 📚 详细文档
   - 扫描成功后的震动反馈
   - 清晰的扫描指导文本
   - 优雅的模态展示
-4. **多格式条码支持**
+项目的详细文档和开发说明请查看：
   - 二维码 (QR Code)
   - EAN-8 和 EAN-13 条形码
   - Code 128 和 Code 39 条形码
   - UPC-E 条形码
   - PDF417 和 Aztec 码
-5. **微信风格扫描界面**
+**[📖 完整项目文档](docs/README.md)**
   - 扫描线动画效果
   - 检测到条码时短暂暂停预览
   - 条码位置中心点标记（绿色圆圈）
   - 点击标记直接选择条码
   - 支持重新扫描
-## 文件结构
+包含以下内容：
 - 🚀 核心功能实现说明
 - 🔧 问题修复文档
 - 📱 架构设计说明
 - 🧪 测试指南
 - 🛠️ 开发工具配置
 ## 📂 项目结构
 ```
 MyQrCode/
-├── ScannerView.swift          # 新的 SwiftUI 扫描器视图
+├── MyQrCode/           # 应用主目录
-├── ContentView.swift          # 更新的主内容视图
+├── docs/              # 📚 项目文档
-├── MyQrCodeApp.swift         # 应用入口点
+├── MyQrCodeTests/     # 🧪 测试文件
-└── ...其他文件
+└── README.md          # 📖 项目说明
 ```
-## 使用方法
+## 🤝 贡献
 1. 启动应用后，点击"开始扫描"按钮
 2. 将二维码或条形码放入扫描框内
 3. 扫描成功后：
   - 短暂暂停预览并显示条码覆盖层
   - 在相机预览上显示条码位置标记（绿色圆圈）
 4. 在预览暂停时：
   - 在相机预览上显示条码位置标记（绿色圆圈）
   - 单个条码：1秒后自动显示结果
   - 多个条码：点击绿色标记选择要解码的条码
   - 点击"重新扫描"继续扫描
 5. 单个条码自动选择，多个条码手动选择
 6. 可以重复扫描新的条码
 ## 技术特点
 - **SwiftUI**: 现代化的声明式 UI 框架
 - **AVFoundation**: 相机和条码扫描功能
 - **MVVM 架构**: 清晰的代码分离和状态管理
 - **通知中心**: 组件间的松耦合通信
 ## 兼容性
- iOS 14.0+
+欢迎提交 Issue 和 Pull Request 来帮助改进项目！
 - Xcode 12.0+
 - Swift 5.3+
-## 注意事项
+## 📄 许可证
- 需要在真机上测试相机功能
+此项目遵循 MIT 许可证。 
 - 确保在 Info.plist 中添加相机权限描述
 - 扫描器支持屏幕旋转和尺寸变化
 - 条码位置标记会自动适应屏幕变化 
--- a/docs/CAMERA_PERMISSION_README.md
+++ b/docs/CAMERA_PERMISSION_README.md
@ -0,0 +1,289 @@
 # 相机授权功能实现说明
 ## 🎯 功能概述
 为 MyQrCode 应用添加了完整的相机权限管理功能，包括权限检查、权限请求、权限状态显示和用户引导。
 ## 🔧 技术实现
 ### 1. **权限状态管理**
 在 `ScannerViewModel` 中添加了权限相关的状态：
 ```swift
@Published var cameraAuthorizationStatus: AVAuthorizationStatus = .notDetermined
@Published var showPermissionAlert = false
 ```
 ### 2. **权限检查流程**
 #### **初始化时权限检查**
 ```swift
 override init() {
    super.init()
    checkCameraPermission() // 替换原来的 setupCaptureSession()
 }
 ```
 #### **权限状态检查方法**
 ```swift
 private func checkCameraPermission() {
    switch AVCaptureDevice.authorizationStatus(for: .video) {
    case .authorized:
        // 已授权，设置相机会话
        setupCaptureSession()
    case .notDetermined:
        // 未确定，请求权限
        requestCameraPermission()
    case .denied, .restricted:
        // 被拒绝或受限，显示权限提示
        showPermissionAlert = true
    @unknown default:
        // 未知状态
        break
    }
 }
 ```
 ### 3. **权限请求处理**
 #### **自动权限请求**
 ```swift
 private func requestCameraPermission() {
    AVCaptureDevice.requestAccess(for: .video) { [weak self] granted in
        DispatchQueue.main.async {
            if granted {
                self?.cameraAuthorizationStatus = .authorized
                self?.setupCaptureSession()
            } else {
                self?.cameraAuthorizationStatus = .denied
                self?.showPermissionAlert = true
            }
        }
    }
 }
 ```
 #### **手动权限刷新**
 ```swift
 func refreshCameraPermission() {
    checkCameraPermission()
 }
 ```
 ### 4. **设置页面跳转**
 ```swift
 func openSettings() {
    if let settingsUrl = URL(string: UIApplication.openSettingsURLString) {
        UIApplication.shared.open(settingsUrl) { success in
            // 处理跳转结果
        }
    }
 }
 ```
 ## 📱 用户界面
 ### 1. **权限状态视图**
 创建了 `CameraPermissionView` 来显示不同权限状态下的UI：
 #### **未确定状态**
 - 显示相机图标和说明文字
 - 提供"授予相机权限"按钮
 - 点击后自动请求权限
 #### **被拒绝状态**
 - 显示权限被拒绝的说明
 - 提供"打开设置"按钮
 - 引导用户到系统设置中手动开启
 #### **受限状态**
 - 显示权限受限的说明
 - 提供相应的解决方案
 ### 2. **UI 组件结构**
 ```swift
 struct CameraPermissionView: View {
    let authorizationStatus: AVAuthorizationStatus
    let onRequestPermission: () -> Void
    let onOpenSettings: () -> Void
    var body: some View {
        VStack(spacing: 30) {
            // 相机图标
            Image(systemName: "camera.fill")
            // 标题和描述
            Text("camera_permission_title".localized)
            Text(getDescriptionText())
            // 操作按钮
            VStack(spacing: 15) {
                if authorizationStatus == .notDetermined {
                    // 请求权限按钮
                } else if authorizationStatus == .denied || authorizationStatus == .restricted {
                    // 打开设置按钮
                }
            }
        }
    }
 }
 ```
 ### 3. **权限状态集成**
 在 `ScannerView` 中根据权限状态显示不同的UI：
 ```swift
 var body: some View {
    ZStack {
        if scannerViewModel.cameraAuthorizationStatus == .authorized {
            // 相机预览和扫描UI
            CameraPreviewView(...)
            ScanningOverlayView(...)
            // ... 其他扫描相关组件
        } else {
            // 权限相关UI
            CameraPermissionView(...)
        }
    }
 }
 ```
 ## 🌐 多语言支持
 ### 1. **英文本地化**
 ```strings
 "camera_permission_title" = "Camera Permission Required";
 "camera_permission_description" = "This app needs access to your camera to scan QR codes and barcodes. Please grant camera permission to continue.";
 "camera_permission_denied" = "Camera access has been denied. Please enable camera permission in Settings to use the scanner.";
 "request_camera_permission" = "Grant Camera Access";
 "open_settings" = "Open Settings";
 ```
 ### 2. **中文本地化**
 ```strings
 "camera_permission_title" = "需要相机权限";
 "camera_permission_description" = "此应用需要访问您的相机来扫描二维码和条形码。请授予相机权限以继续使用。";
 "camera_permission_denied" = "相机访问被拒绝。请在设置中启用相机权限以使用扫描器。";
 "request_camera_permission" = "授予相机权限";
 "open_settings" = "打开设置";
 ```
 ## 🔄 权限状态监听
 ### 1. **自动状态更新**
 ```swift
 .onReceive(scannerViewModel.$cameraAuthorizationStatus) { status in
    if status == .authorized {
        logInfo("🎯 相机权限已授权，启动扫描", className: "ScannerView")
        scannerViewModel.startScanning()
    }
 }
 ```
 ### 2. **扫描控制**
 ```swift
 .onAppear {
    // 只有在相机权限已授权时才启动扫描
    if scannerViewModel.cameraAuthorizationStatus == .authorized {
        scannerViewModel.startScanning()
    }
 }
 ```
 ## 📋 权限状态类型
 ### 1. **AVAuthorizationStatus 枚举**
 - **`.notDetermined`**: 用户尚未做出选择
 - **`.authorized`**: 用户已授权访问相机
 - **`.denied`**: 用户拒绝访问相机
 - **`.restricted`**: 相机访问受限（如家长控制）
 ### 2. **状态转换流程**
 ```
 notDetermined → 请求权限 → authorized/denied
 denied → 用户手动开启 → authorized
 restricted → 需要管理员操作 → authorized
 ```
 ## 🧪 测试场景
 ### 1. **首次安装**
 - 应用启动时自动请求权限
 - 用户可以选择允许或拒绝
 ### 2. **权限被拒绝**
 - 显示权限被拒绝的说明
 - 提供打开设置的按钮
 - 用户可以从设置中重新开启
 ### 3. **权限恢复**
 - 用户从设置返回后自动检测权限状态
 - 权限恢复后自动启动扫描功能
 ### 4. **权限受限**
 - 显示相应的说明和解决方案
 - 引导用户联系管理员或检查设备设置
 ## 🔒 隐私和安全
 ### 1. **最小权限原则**
 - 只请求必要的相机权限
 - 不收集或存储相机数据
 - 权限仅用于扫描功能
 ### 2. **用户控制**
 - 用户可以随时在设置中关闭权限
 - 应用会优雅地处理权限变化
 - 提供清晰的权限说明
 ### 3. **错误处理**
 - 权限被拒绝时提供友好的错误信息
 - 引导用户解决问题的方法
 - 不会因为权限问题导致应用崩溃
 ## 🚀 部署说明
 ### 1. **Info.plist 配置**
 确保在 `Info.plist` 中添加相机权限描述：
 ```xml
 <key>NSCameraUsageDescription</key>
 <string>此应用需要访问相机来扫描二维码和条形码</string>
 ```
 ### 2. **权限测试**
 - 在真机上测试权限流程
 - 验证不同权限状态下的UI显示
 - 测试权限恢复后的功能
 ### 3. **用户体验**
 - 权限请求时机合理
 - 错误信息清晰易懂
 - 操作流程简单直观
 ## 📊 功能特性总结
 - ✅ **自动权限检查**: 应用启动时自动检查相机权限
 - ✅ **智能权限请求**: 只在必要时请求权限
 - ✅ **友好错误提示**: 权限被拒绝时提供清晰的说明
 - ✅ **设置页面跳转**: 一键跳转到系统设置
 - ✅ **状态自动更新**: 权限状态变化时自动更新UI
 - ✅ **多语言支持**: 支持中英文界面
 - ✅ **优雅降级**: 无权限时显示相应的提示界面
 - ✅ **权限恢复**: 权限恢复后自动启动扫描功能
 通过这些功能，用户可以获得完整的相机权限管理体验，确保应用能够正常使用相机功能，同时尊重用户的隐私选择。 
--- a/docs/README.md
+++ b/docs/README.md
@ -0,0 +1,163 @@
 # MyQrCode 项目文档
 欢迎来到 MyQrCode 项目文档！这里包含了项目开发过程中的所有重要文档和说明。
 ## 📚 文档索引
 ### 🚀 核心功能文档
 1. **[相机授权功能实现说明](CAMERA_PERMISSION_README.md)**
   - 完整的相机权限管理功能
   - 权限检查、请求、状态显示和用户引导
   - 多语言支持的权限界面
 2. **[重构说明文档](REFACTOR_README.md)**
   - ScannerView 代码重构详细说明
   - 组件化拆分和模块化设计
   - 架构优化和代码组织
 3. **[多语言支持实现说明](README_Multilingual.md)**
   - 中英文双语支持
   - 本地化字符串管理
   - 语言切换功能
 4. **[日志系统实现说明](README_Logger.md)**
   - 自定义日志系统
   - 多级别日志管理
   - 调试和监控功能
 ### 🔧 问题修复文档
 1. **[触摸选择点响应问题修复说明](TOUCH_FIX_README.md)**
   - 触摸区域优化
   - 事件处理改进
   - 用户交互体验提升
 2. **[重新扫描后无法扫描问题修复说明](SCANNING_ISSUE_FIX_README.md)**
   - 会话状态管理修复
   - 扫描重启逻辑优化
   - 错误处理机制
 3. **[重新扫描按钮修复说明](RESCAN_BUTTON_FIX_README.md)**
   - 按钮位置重新设计
   - 功能失效问题修复
   - 用户体验优化
 ## 📱 项目概述
 MyQrCode 是一个功能完整的二维码和条形码扫描应用，采用 SwiftUI 和 AVFoundation 技术栈开发。
 ### 🌟 主要特性
 - **多格式支持**: 支持 QR 码、条形码等多种格式
 - **多码识别**: 同时识别多个条码并允许用户选择
 - **微信风格界面**: 暂停预览和用户选择功能
 - **多样化扫描线**: 5种不同风格的扫描线动画
 - **多语言支持**: 中英文双语界面
 - **权限管理**: 完整的相机权限管理
 - **日志系统**: 详细的调试和监控日志
 ### 🏗️ 技术架构
 - **UI框架**: SwiftUI
 - **相机功能**: AVFoundation
 - **架构模式**: MVVM
 - **状态管理**: Combine + @Published
 - **本地化**: .lproj 文件
 - **日志**: 自定义 Logger 系统
 ### 📦 项目结构
 ```
 MyQrCode/
 ├── MyQrCode/                 # 应用主目录
 │   ├── ScannerView.swift    # 主扫描视图（重构后）
 │   ├── ContentView.swift    # 应用入口视图
 │   ├── Logger.swift         # 日志系统
 │   ├── MyQrCodeApp.swift    # 应用入口
 │   ├── en.lproj/           # 英文本地化
 │   ├── zh-Hans.lproj/      # 中文本地化
 │   └── Assets.xcassets/    # 应用资源
 ├── docs/                    # 项目文档
 └── README.md               # 项目主文档
 ```
 ## 🚦 开发历程
 ### 阶段 1: 基础功能实现
 - 基本的二维码扫描功能
 - SwiftUI 界面搭建
 - AVFoundation 集成
 ### 阶段 2: 功能增强
 - 多码识别和选择
 - 微信风格的用户界面
 - 扫描线动画效果
 ### 阶段 3: 用户体验优化
 - 触摸交互优化
 - 权限管理完善
 - 多语言支持
 ### 阶段 4: 代码质量提升
 - 代码重构和模块化
 - 日志系统集成
 - 问题修复和优化
 ## 🧪 测试指南
 ### 基本功能测试
 1. 单个二维码扫描
 2. 多个二维码识别和选择
 3. 不同格式的条码扫描
 ### 权限测试
 1. 首次安装权限请求
 2. 权限拒绝后的处理
 3. 权限恢复功能
 ### 用户体验测试
 1. 触摸选择响应
 2. 重新扫描功能
 3. 语言切换功能
 ### 兼容性测试
 1. 不同 iOS 版本
 2. 不同设备尺寸
 3. 横竖屏切换
 ## 🛠️ 开发工具和环境
 - **开发环境**: Xcode 15+
 - **最低iOS版本**: iOS 15.0
 - **开发语言**: Swift 5.9+
 - **UI框架**: SwiftUI
 - **相机框架**: AVFoundation
 - **依赖管理**: Swift Package Manager
 ## 📋 TODO 和未来计划
 - [ ] 添加扫描历史记录
 - [ ] 支持生成二维码功能
 - [ ] 添加更多扫描线样式
 - [ ] 优化相机性能
 - [ ] 添加扫描音效
 - [ ] 支持批量扫描
 ## 🤝 贡献指南
 1. 代码规范遵循 Swift 官方指南
 2. 新功能需要添加相应的文档
 3. 重要变更需要更新测试用例
 4. 提交前需要通过所有测试
 ## 📞 联系信息
 如果您在使用过程中遇到问题，请通过以下方式联系：
 - 项目仓库: [GitHub Issues]
 - 开发者邮箱: [开发者邮箱]
 ---
 最后更新: 2025年8月20日
--- a/MyQrCode/README_Logger.md
+++ b/MyQrCode/README_Logger.md
--- a/MyQrCode/README_Multilingual.md
+++ b/MyQrCode/README_Multilingual.md
--- a/MyQrCode/REFACTOR_README.md
+++ b/MyQrCode/REFACTOR_README.md
--- a/MyQrCode/RESCAN_BUTTON_FIX_README.md
+++ b/MyQrCode/RESCAN_BUTTON_FIX_README.md
--- a/MyQrCode/SCANNING_ISSUE_FIX_README.md
+++ b/MyQrCode/SCANNING_ISSUE_FIX_README.md
--- a/MyQrCode/TOUCH_FIX_README.md
+++ b/MyQrCode/TOUCH_FIX_README.md