test(media): 覆盖转码保持原始宽高比

docs/plans/2026-10-22-transcode-preserve-aspect.md

@@ -0,0 +1,27 @@
+# 转码保持原始宽高比
+
+## 目标
+
+- 横屏源按档位短边作为高度，竖屏源按档位短边作为宽度。
+- 源短边小于档位短边时按源短边输出，不放大。
+- 输出宽高均为偶数，SAR 固定为 1。
+- rendition 的 width/height 使用 ffprobe 探测到的实际值。
+
+## 实施
+
+1. ffprobe 读取源显示方向尺寸，旋转 90/270 度时交换宽高。
+2. `effectiveShort = min(sourceShort, rungShort)` 并向下取偶数。
+3. 横屏使用 `scale=-2:<effectiveShort>:flags=lanczos,setsar=1`；
+   竖屏使用 `scale=<effectiveShort>:-2:flags=lanczos,setsar=1`。
+4. 转码完成后 ffprobe variant playlist，写入实际输出尺寸。
+5. master playlist 的 RESOLUTION 同步使用实际尺寸。
+
+## 不放大策略
+
+选用“用源尺寸输出”：高于源短边的档位仍保留原 quality 标识和码率，
+但分辨率封顶到源短边，避免所有档位都被跳过导致无产物。
+
+## 验证
+
+- 先补横屏、竖屏、小源码片、偶数、SAR=1 与实际尺寸回写测试。
+- 门禁：`mvn -pl fruitshorts-module-media,fruitshorts-transcode-worker test`。

docs/plans/PROGRESS.md

@@ -25390,3 +25390,34 @@ $ mvn test
 解读：admin 51、app 109、worker 32 个测试均通过，P1 入队/重转与 worker
 链路未回归。
 
+## 2026-10-22 转码保持原始宽高比
+
+- 分支：`feature/transcode-preserve-aspect`
+- 基线：`develop` / `origin/develop` = `40a884c`
+- 隔离工作树：`/private/tmp/fruitserver-preserve-aspect`
+- 计划：`docs/plans/2026-10-22-transcode-preserve-aspect.md`
+
+按 TDD 先扩展真实 ffmpeg smoke，覆盖横屏、竖屏、源码短边小于档位、
+输出偶数尺寸、SAR=1、ffprobe 实际尺寸与 master RESOLUTION。
+生产代码暂不修改，下一步记录红测输出。
+
+### TDD 红测
+
+```text
+$ mvn -pl fruitshorts-transcode-worker -am \
+  -Dtest=FfmpegTranscodeRunnerSmokeTest \
+  -Dsurefire.failIfNoSpecifiedTests=false test
+[ERROR] should_keep_portrait_orientation_and_even_dimensions:
+expected: 202
+ but was: 640
+[ERROR] should_not_upscale_when_source_short_edge_is_below_rung:
+expected: "1:1"
+ but was: "1280:1281"
+[ERROR] Tests run: 4, Failures: 2, Errors: 0, Skipped: 0
+[INFO] BUILD FAILURE
+```
+
+解读：竖屏实际输出为 202x360，却把名义 640x360 回写到 rendition；
+小源码片仍被放大，且未固定 SAR。横屏基础尺寸用例已通过，说明测试片生成、
+ffprobe 探测与 HLS 链路本身正常。
+