## 🔧 鉴权到期治理 + 多素材时间轴稳定性修复 (Day 24)

### 概述

本日主要完成两条主线：

1. **账号与鉴权治理**：会员到期改为请求时自动失效（登录/鉴权接口触发），并统一返回续费提示。
2. **视频生成稳定性**：围绕多素材时间轴、截取语义、拼接边界冻结、画面比例与字幕标题适配进行一轮端到端修复。

---

## 🔐 会员到期请求时失效 — 第一阶段 (Day 24)

### 目标

避免依赖定时任务，用户在触发登录或访问受保护接口时即可完成到期判定与账号停用。

### 行为调整

- 到期判断基于 `users.expires_at`。
- 判定到期后：
  - 将 `is_active` 自动置为 `false`
  - 删除该用户全部 session
  - 返回 `403`，提示：`会员已到期，请续费`

### 实现点

- `users.py` 新增 `deactivate_user_if_expired()`，并补充 `_parse_expires_at()` 统一时区解析。
- `deps.py` 在 `get_current_user` / `get_current_user_optional` 中统一接入到期检查。
- `auth/router.py` 在登录路径增加到期停用逻辑；`/api/auth/me` 统一走 `Depends(get_current_user)`。

---

## 🖼️ 画面比例控制 + 字幕标题适配 — 第二阶段 (Day 24)

### 2.1 输出画面比例可配置

- 时间轴顶部新增“画面比例”下拉：`9:16` / `16:9`。
- 默认值 `9:16`，并持久化到 localStorage。
- 生成请求携带 `output_aspect_ratio`，后端在单素材与多素材流程中统一按目标分辨率处理。

### 2.2 标题/字幕在窄屏画布防溢出

为减少“预览正常、成片溢出”的差异，统一了预览与渲染策略：

- 根据 composition 宽度进行响应式缩放。
- 开启可换行：`white-space: normal` + `word-break` + `overflow-wrap`。
- 描边、字距、上下边距同步按比例缩放。

### 2.3 片头标题显示模式（短暂/常驻）

- 在“标题与字幕”面板的“片头标题”行尾新增下拉，支持：`短暂显示` / `常驻显示`。
- 默认模式为 `短暂显示`，短暂模式默认时长为 4 秒。
- 用户选择会持久化到 localStorage，刷新后保持上次配置。
- 生成请求新增 `title_display_mode`，短暂模式透传 `title_duration=4.0`。
- Remotion 端到端支持该参数：
  - `short`：标题在设定时长后淡出并结束渲染；
  - `persistent`：标题全程常驻（保留淡入动画，不执行淡出）。

---

## 🎥 方向归一化 + 多素材拼接稳定性 — 第三阶段 (Day 24)

### 3.1 MOV 旋转元数据导致横竖识别错误

问题场景：编码分辨率是横屏，但依赖 rotation side-data 才能正确显示为竖屏（常见于手机 MOV）。

修复方案：

- `get_video_metadata()` 扩展返回 `rotation/effective_width/effective_height`。
- 新增 `normalize_orientation()`，在流程前对带旋转元数据素材做物理方向归一化。
- 单素材和多素材下载后统一执行方向归一化，再做分辨率决策。

### 3.2 多素材“只看到第一段”与边界冻结

针对拼接可靠性补了两类保护：

- **分配保护**：`custom_assignments` 与素材数量不一致时，后端回退自动分配，避免异常输入导致仅首段生效。
- **编码一致性**：
  - 片段准备阶段统一重编码；
  - concat 阶段不再走拷贝；
  - 进一步统一为 `25fps + CFR`，并在 concat 增加 `+genpts`，降低段边界时间基不连续导致的“画面冻结口型还动”风险。

---

## ⏱️ 时间轴截取语义对齐修复 — 第四阶段 (Day 24)

### 背景

时间轴设计语义是：

- 每段可以设置 `sourceStart/sourceEnd`；
- 总时长超出音频时，仅保留可见段，末段截齐音频；
- 总时长不足时，由最后可见段循环补齐。

本日将前后端对齐到这一语义。

### 4.1 `source_end` 全链路打通

此前仅传 `source_start`，导致后端无法准确知道“截到哪里”。

本次改动：

- 前端 `toCustomAssignments()` 增加可选 `source_end`。
- 后端 `CustomAssignment` schema 增加 `source_end`。
- workflow 将 `source_end` 透传到 `prepare_segment()`（单素材/多素材均支持）。
- `prepare_segment()` 增加 `source_end` 参数，按 `[source_start, source_end)` 计算可用片段，并在需要循环时先裁剪再循环，避免循环范围错位。

### 4.2 时间轴有效时长计算修复

修复 `sourceStart > 0 且 sourceEnd = 0` 时的有效时长错误：

- 旧逻辑会按整段素材时长计算；
- 新逻辑改为 `materialDuration - sourceStart`。

该修复同时用于：

- `recalcPositions()` 的段时长计算；
- TimelineEditor 中“循环补足”可视化比例计算。

### 4.3 可见段分配优先级修复

修复“可见段数 < 已选素材数时，custom_assignments 被丢弃回退自动分配”的问题：

- 生成请求优先以时间轴可见段的 `assignments` 为准；
- 超出时间轴的素材不参与本次生成。

### 4.4 单素材截取触发条件补齐

单素材模式下，若只改了终点（`sourceEnd > 0`）也会发送 `custom_assignments`，确保截取生效。

---

## 🧭 页面交互与体验细节 — 第五阶段 (Day 24)

- 页面刷新后自动回到顶部，避免从历史滚动位置进入页面。
- 素材列表与历史视频列表滚动增加“跳过首次自动滚动”保护，减少恢复状态时页面跳动。
- 时间轴比例区移除多余文案，保持信息简洁。

---

## 涉及文件汇总

### 后端修改

| 文件 | 变更 |
|------|------|
| `backend/app/repositories/users.py` | 新增 `deactivate_user_if_expired()` 与 `_parse_expires_at()` |
| `backend/app/core/deps.py` | `get_current_user` / `get_current_user_optional` 接入到期失效检查 |
| `backend/app/modules/auth/router.py` | 登录时到期停用 + `/api/auth/me` 统一鉴权依赖 |
| `backend/app/modules/videos/schemas.py` | `CustomAssignment` 新增 `source_end`；保留 `output_aspect_ratio` |
| `backend/app/modules/videos/workflow.py` | 多素材/单素材透传 `source_end`；多素材 prepare/concat 统一 25fps；标题显示模式参数透传 Remotion |
| `backend/app/services/video_service.py` | 旋转元数据解析与方向归一化；`prepare_segment` 支持 `source_end/target_fps`；concat 强制 CFR + `+genpts` |
| `backend/app/services/remotion_service.py` | render 支持 `title_display_mode/title_duration` 并传递到 render.ts |

### 前端修改

| 文件 | 变更 |
|------|------|
| `frontend/src/features/home/model/useTimelineEditor.ts` | `CustomAssignment` 新增 `source_end`；修复 sourceStart 开放终点时长计算 |
| `frontend/src/features/home/model/useHomeController.ts` | 多素材以可见 assignments 为准发送；单素材截取触发条件补齐 |
| `frontend/src/features/home/ui/TimelineEditor.tsx` | 画面比例下拉；循环比例按截取后有效时长计算 |
| `frontend/src/features/home/model/useHomePersistence.ts` | `outputAspectRatio` 与 `titleDisplayMode` 持久化 |
| `frontend/src/features/home/ui/HomePage.tsx` | 页面进入滚动到顶部；ClipTrimmer/Timeline 交互保持一致 |
| `frontend/src/features/home/ui/FloatingStylePreview.tsx` | 标题/字幕样式预览与成片渲染策略对齐 |
| `frontend/src/features/home/ui/TitleSubtitlePanel.tsx` | 标题行新增“短暂显示/常驻显示”下拉 |

### Remotion 修改

| 文件 | 变更 |
|------|------|
| `remotion/src/components/Title.tsx` | 标题响应式缩放与自动换行；新增短暂/常驻显示模式控制 |
| `remotion/src/components/Subtitles.tsx` | 字幕响应式缩放与自动换行，减少预览/成片差异 |
| `remotion/src/Video.tsx` | 新增 `titleDisplayMode` 透传到标题组件 |
| `remotion/src/Root.tsx` | 默认 props 增加 `titleDisplayMode='short'` 与 `titleDuration=4` |
| `remotion/render.ts` | CLI 参数新增 `--titleDisplayMode`，inputProps 增加 `titleDisplayMode` |

---

## 验证记录

- 后端语法检查：`python -m py_compile backend/app/modules/videos/schemas.py backend/app/modules/videos/workflow.py backend/app/services/video_service.py backend/app/services/remotion_service.py`
- 前端类型检查：`npx tsc --noEmit`
- 前端 ESLint：`npx eslint src/features/home/model/useHomeController.ts src/features/home/model/useHomePersistence.ts src/features/home/ui/HomePage.tsx src/features/home/ui/TitleSubtitlePanel.tsx`
- Remotion 渲染脚本构建：`npm run build:render`