```

feat(Quick): 优化RegionCameraView裁剪算法

重构RegionImageCropper裁剪逻辑，改用纯几何aspect-fill反算方法，
将屏上小框坐标直接映射到照片像素rect，避免使用
metadataOutputRectConverted导致的坐标轴对调问题。

主要变更:
- 移除基于归一化rect的裁剪方式
- 新增cropRect函数进行几何反算
- 修复传感器横向坐标与竖屏照片方向不一致的问题
- 保持裁剪精度的同时提升算法稳定性
```

康康/Features/Quick/RegionCameraView.swift

@@ -7,8 +7,9 @@ import Combine
 /// 实时预览 + 居中小框 + 快门 → **裁剪到小框区域**的 UIImage 回调。
 /// 只在真机可用(模拟器无相机,QuickRegionCaptureFlow 退化到 PhotoPicker)。
 ///
-/// 裁剪原理:`previewLayer.metadataOutputRectConverted(fromLayerRect:)` 把屏上小框换算成
-/// 归一化(0-1)裁剪 rect;先把拍到的照片方向 bake 成 `.up`,再按归一化 rect 裁 CGImage。
+/// 裁剪原理:先把拍到的照片 bake 成 `.up`(竖屏),再用纯几何 aspect-fill 反算把屏上小框
+/// (view 点坐标)映射到照片像素 rect(见 `RegionImageCropper`)。
+/// 不用 `metadataOutputRectConverted` —— 它返回传感器横向坐标,套到竖屏照片会轴对调裁出竖条。
 struct RegionCameraView: View {
     let onCapture: (UIImage) -> Void
     let onCancel: () -> Void
@@ -198,16 +199,37 @@ enum RegionFraming {
 // MARK: - 裁剪纯函数
 
 enum RegionImageCropper {
-    /// 按归一化 rect(原点左上、范围 0-1、与显示方向一致)裁剪 `.up` 方向的图。
-    /// 入参 image 须已 bake 成 `.up`(见 `UIImage.normalizedUp()`)。越界自动夹紧;失败回退原图。
-    static func crop(_ image: UIImage, normalizedRect: CGRect) -> UIImage {
+    /// 把屏上小框(view 点坐标)按 `.resizeAspectFill` 反算到 `.up` 照片的像素裁剪 rect。
+    /// 前提:预览以 aspect-fill 铺满 viewSize,照片与预览同源、同为竖屏方向。
+    /// 纯几何、方向自洽 —— 不用 `metadataOutputRectConverted`(它返回传感器**横向**坐标,
+    /// 套到竖屏照片会 x/y 轴对调,把宽框裁成竖窄条,见 RegionImageCropperTests)。越界自动夹紧。
+    static func cropRect(photoPixelSize p: CGSize, box: CGRect, in viewSize: CGSize) -> CGRect {
+        guard p.width > 0, p.height > 0, viewSize.width > 0, viewSize.height > 0 else { return .zero }
+        // aspect-fill:取较大缩放系数让照片铺满视图,溢出部分被裁。
+        let scale = max(viewSize.width / p.width, viewSize.height / p.height)
+        let scaledW = p.width * scale
+        let scaledH = p.height * scale
+        // 缩放后照片相对视图居中,溢出维度的原点为负。
+        let ox = (viewSize.width - scaledW) / 2
+        let oy = (viewSize.height - scaledH) / 2
+        // 视图点 → 照片像素:先减去居中偏移,再除以缩放系数。
+        var x = (box.minX - ox) / scale
+        var y = (box.minY - oy) / scale
+        var w = box.width / scale
+        var h = box.height / scale
+        // 夹紧到照片范围内。
+        x = max(0, min(p.width, x))
+        y = max(0, min(p.height, y))
+        w = max(0, min(p.width - x, w))
+        h = max(0, min(p.height - y, h))
+        return CGRect(x: x, y: y, width: w, height: h).integral
+    }
+
+    /// 按屏上小框裁 `.up` 照片(`box` / `viewSize` 同为 view 点坐标);失败回退原图。
+    static func crop(_ image: UIImage, box: CGRect, viewSize: CGSize) -> UIImage {
         guard let cg = image.cgImage else { return image }
-        let w = CGFloat(cg.width), h = CGFloat(cg.height)
-        let nx = max(0, min(1, normalizedRect.origin.x))
-        let ny = max(0, min(1, normalizedRect.origin.y))
-        let nw = max(0, min(1 - nx, normalizedRect.size.width))
-        let nh = max(0, min(1 - ny, normalizedRect.size.height))
-        let rect = CGRect(x: nx * w, y: ny * h, width: nw * w, height: nh * h).integral
+        let rect = cropRect(photoPixelSize: CGSize(width: cg.width, height: cg.height),
+                            box: box, in: viewSize)
         guard rect.width >= 1, rect.height >= 1, let cropped = cg.cropping(to: rect) else { return image }
         return UIImage(cgImage: cropped, scale: image.scale, orientation: .up)
     }
@@ -334,15 +356,16 @@ final class RegionPreviewUIView: UIView, AVCapturePhotoCaptureDelegate {
             return
         }
         let upright = image.normalizedUp()
-        guard let preview = previewLayer else {
+        guard previewLayer != nil else {
             deliver(upright)
             return
         }
-        // metadataOutputRectConverted 读 previewLayer 几何,回主线程算更稳。
+        // 裁剪走纯几何映射:预览以 .resizeAspectFill 铺满 bounds,照片与预览同源同为竖屏,
+        // 故屏上小框可按 aspect-fill 反算到照片像素 rect。读 bounds 几何回主线程更稳。
         DispatchQueue.main.async {
-            let box = RegionFraming.box(in: self.bounds.size)
-            let normalized = preview.metadataOutputRectConverted(fromLayerRect: box)
-            let cropped = RegionImageCropper.crop(upright, normalizedRect: normalized)
+            let viewSize = self.bounds.size
+            let box = RegionFraming.box(in: viewSize)
+            let cropped = RegionImageCropper.crop(upright, box: box, viewSize: viewSize)
             completion?(cropped)
         }
     }

康康Tests/RegionImageCropperTests.swift

@@ -0,0 +1,61 @@
+import XCTest
+import CoreGraphics
+@testable import 康康
+
+/// 异常项快拍的局部裁剪几何。
+/// 回归用例:屏上「宽而矮」的小框,必须裁出「宽 > 高」的照片 rect。
+/// 旧实现用 `metadataOutputRectConverted`(传感器横向坐标)套到竖屏照片 → x/y 轴对调,
+/// 把宽框裁成竖窄条(2026-05-31 真机 bug)。本组用例钉住正确的纯几何映射。
+final class RegionImageCropperTests: XCTestCase {
+
+    /// 竖屏照片 + 竖屏屏幕 + 宽框 → 裁出的 rect 必须是横向(宽 > 高)。
+    func testWideBoxYieldsLandscapeCropRect() {
+        let photo = CGSize(width: 3024, height: 4032)   // 竖屏照片(像素)
+        let view = CGSize(width: 393, height: 852)       // 竖屏屏幕(点)
+        let box = RegionFraming.box(in: view)            // 宽 84% / 矮 160
+
+        let rect = RegionImageCropper.cropRect(photoPixelSize: photo, box: box, in: view)
+
+        XCTAssertGreaterThan(rect.width, rect.height,
+            "宽框应裁出宽 rect;若 width<height 说明轴对调 bug 复现")
+        XCTAssertGreaterThan(rect.width, 0)
+        XCTAssertGreaterThan(rect.height, 0)
+    }
+
+    /// 裁出的 rect 必须完整落在照片像素范围内(越界夹紧)。
+    func testCropRectStaysInsidePhotoBounds() {
+        let photo = CGSize(width: 3024, height: 4032)
+        let view = CGSize(width: 393, height: 852)
+        let box = RegionFraming.box(in: view)
+
+        let rect = RegionImageCropper.cropRect(photoPixelSize: photo, box: box, in: view)
+
+        XCTAssertGreaterThanOrEqual(rect.minX, 0)
+        XCTAssertGreaterThanOrEqual(rect.minY, 0)
+        XCTAssertLessThanOrEqual(rect.maxX, photo.width)
+        XCTAssertLessThanOrEqual(rect.maxY, photo.height)
+    }
+
+    /// 宽框宽高比应与照片裁剪 rect 宽高比一致(aspect-fill 等比映射,不拉伸)。
+    func testCropRectPreservesBoxAspectRatio() {
+        let photo = CGSize(width: 3024, height: 4032)
+        let view = CGSize(width: 393, height: 852)
+        let box = RegionFraming.box(in: view)
+
+        let rect = RegionImageCropper.cropRect(photoPixelSize: photo, box: box, in: view)
+
+        let boxAspect = box.width / box.height
+        let rectAspect = rect.width / rect.height
+        XCTAssertEqual(rectAspect, boxAspect, accuracy: 0.05,
+            "等比映射下,裁剪 rect 宽高比应与屏上小框一致")
+    }
+
+    /// 退化输入:零尺寸不应崩溃,返回 .zero。
+    func testZeroInputsReturnZero() {
+        XCTAssertEqual(
+            RegionImageCropper.cropRect(photoPixelSize: .zero,
+                                        box: CGRect(x: 0, y: 0, width: 10, height: 10),
+                                        in: CGSize(width: 100, height: 200)),
+            .zero)
+    }
+}