feat(web-admin): add image preview transform helpers for fit/zoom.

Pure functions for AttachmentUploadField image preview rotate/zoom math, with a Node assert script.

Co-authored-by: Cursor <cursoragent@cursor.com>

web-admin/src/utils/image-preview-transform.js

@@ -0,0 +1,65 @@
+/** @typedef {{ x: number, y: number }} PreviewOffset */
+
+export const IMAGE_PREVIEW_ZOOM_MIN = 0.5
+export const IMAGE_PREVIEW_ZOOM_MAX = 5
+export const IMAGE_PREVIEW_ZOOM_STEP = 0.15
+
+/**
+ * @param {number} value
+ * @returns {number}
+ */
+export function clampPreviewZoom(value) {
+  const n = Number(value)
+  if (!Number.isFinite(n)) return 1
+  const clamped = Math.min(IMAGE_PREVIEW_ZOOM_MAX, Math.max(IMAGE_PREVIEW_ZOOM_MIN, n))
+  return Math.round(clamped * 100) / 100
+}
+
+/**
+ * 旋转后外接矩形完整装入 stage 的基础缩放（zoom=1 时使用）。
+ * @param {number} naturalWidth
+ * @param {number} naturalHeight
+ * @param {number} angleDeg
+ * @param {number} stageWidth
+ * @param {number} stageHeight
+ * @returns {number}
+ */
+export function computeFitBaseScale(
+  naturalWidth,
+  naturalHeight,
+  angleDeg,
+  stageWidth,
+  stageHeight
+) {
+  const natW = Math.max(Number(naturalWidth) || 1, 1)
+  const natH = Math.max(Number(naturalHeight) || 1, 1)
+  const stageW = Math.max(Number(stageWidth) || 1, 1)
+  const stageH = Math.max(Number(stageHeight) || 1, 1)
+  const rad = ((Number(angleDeg) || 0) * Math.PI) / 180
+  const cos = Math.abs(Math.cos(rad))
+  const sin = Math.abs(Math.sin(rad))
+  const boundW = natW * cos + natH * sin
+  const boundH = natW * sin + natH * cos
+  return Math.min(stageW / boundW, stageH / boundH)
+}
+
+/**
+ * @param {number} offsetX
+ * @param {number} offsetY
+ * @param {number} angleDeg
+ * @param {number} scale
+ * @returns {string}
+ */
+export function buildPreviewTransformCss(offsetX, offsetY, angleDeg, scale) {
+  return (
+    'translate(' +
+    offsetX +
+    'px, ' +
+    offsetY +
+    'px) rotate(' +
+    angleDeg +
+    'deg) scale(' +
+    scale +
+    ')'
+  )
+}