feat(editor): AI 编辑助手悬浮面板、插件权限体系与时间线渲染管线（M4–M6.3） (#411)

* feat(editor): 编辑器实施 M0-M1 - 剪辑入口占位与插件 SDK v2 垂直切片 - detail.tsx 新增剪辑成片视图（editor tab，常驻），概览页插入剪辑步骤卡 - plugin-types.ts 新增 v2 类型（EditorSlotKind/EditorPluginPermission/PluginManifestV2），修复权限数组交叉归约 bug - editor-slot-registry.ts 插槽注册表（优先级排序、幂等注册、订阅机制） - plugin-registry.ts 注册器 v1/v2 分支校验，v1 路径零改动 - editor-shell.tsx 垂直切片插件：timeline-panel 插槽真实渲染，验证插件链路全通 - 测试：插槽注册表 5 用例 + 命令测试骨架，v1 插件回归 21 例零回归 * feat(editor): 命令协议黄金文件 - editor-commands 纯函数 reducer + 8 个黄金 op * feat(editor): 快照撤销历史 - editor-history 有界 200 层 undo/redo * feat(editor): 命令状态机 store - dispatch/手势预览/1.5s 防抖保存/串行保存链 * fix(editor): createEditorStore 返回 zustand hook 类型修复 typecheck * feat(editor): 手势 echo 最小件 - 时间线面板拖拽移动/裁剪 + store 接线与本地持久化 * docs(editor): M2 完成状态记录 * feat(editor): M3.1 时间线面板选中联动 - store 选中状态 + 片段高亮/点击取消 * feat(editor): M3.2 预览监视器 - preview-renderer 插槽 + 真实媒体帧/播放头/时间码 * feat(editor): M3.3 片段检查器 - inspector 插槽 + 属性编辑入队可撤销 * feat(editor): M3.4 asset-ingest 素材库插件（addClip 命令入轨） * feat(editor): M3.4 补充 - host 上下文（项目信息+资产）、editor.tsx 接线、asset-ingest 纯函数、死代码清理 * feat(editor): M3.5 subtitle-tools - SRT import/export + rebuild from node snapshot * feat(editor): M3.6 transcription - deterministic mock ASR to subtitle track * feat(editor): M3.7 export - render plan + ffmpeg.wasm fallback export * feat(editor): M3.8 - render all 8 editor slots in three-pane layout + ai-assistant placeholder * docs(editor): M3 完成状态 - 8 插件 + 全插槽接线，冒烟待确认 * feat(editor): 编辑器媒体与时间线打磨 - 资产来源分组筛选、时间线全宽布局、拖拽末片段修复、OSS 降级本地存储、Concat 风格控制条与检查器 * fix(plugins): 合并上游后修复插件分类筛选对 v2 清单的类型兼容 * feat(editor): 时间线工具态与轨道操作打磨 - 工具按钮选中仅图标变色、监视器 Concat 式控制条、removeTrack 黄金命令与轨道行头移除按钮、maskClosable 迁移 * fix(api): 资源上传超 MaxBytesReader 上限时报中文大小限制而非英文裸 400 * fix(editor): 监视器控制条 - 修复播放按钮 JSX 模板闭合花括号缺失导致的编译错误 * feat(api): 本地媒体导入分片化对齐 Concat - >50MB 视频不再失败 - 分片会话三接口(POST开始/PUT单片/complete合并)、前端超50MB自动切8MB分片并失败整传重试、默认配额放宽(日200MB→2GB、总2GB→20GB)、UploadResourceFile 豁免单文件限 * feat(editor): 轨道行头新增可见性/静音开关按钮 - 复用现有图标资源，按轨道类型显隐；命令层新增 setTrackFlag 黄金命令（flag 白名单 fail-closed）并补单测 * docs(progress): 记录轨道可见/静音开关改动与复测项 * docs(editor): M4 转写与渲染任务设计 - 复用 Task 表与状态机、独立创建 API、worker 领取类型过滤、whisper HTTP provider（OpenAI 兼容 /v1/audio） * fix(api): OSS 上传失败自动降级本地存储时 body 已被 Transport 关闭 - newOSSRequest 用 NopCloser 包装请求体,服务端提前返回(签名 403)时不再关闭调用方持有的文件,降级分支 Seek 重读生效;补回归测试 * docs(progress): 记录媒体导入根治(分片+OSS 降级修复)复测项 * feat(api): 视频播放副本转码 H.265→H.264 + variant=playback 服务与启动回填 - 上传视频后异步探测 codec，H.265/AV1 走 moov 快速探测并转码 H.264 播放副本；GET /api/user-data/...?variant=playback 就绪时服务副本（独立 ETag :pb），未就绪回退原件并撤销后缀防 304 黑屏；storeResource 触发、启动幂等回填存量；前端播放失败自动轮询副本就绪后刷新 * fix(editor): 轨道至少保留一条 - 不可移除轨道点击 X 时居中浮现原因提示(2.2s 自动消失, aria-live)；修正可见性 toggle 传参 (visible===false 语义) ；轨道行内移除按钮改为常驻(不可移除时点击给提示) * feat(timeline): M4.1 字幕转写后台任务 - whisper.cpp 本地执行 - 新增 timeline_transcription 任务类型，worker 按类型分叉独立执行器（不走计费与模型渠道）；输入 resourceId+language，读取用户资源后 ffmpeg 预处理 16k 单声道 wav，POST 本地 whisper.cpp /inference，结果写回 segments+srt+language；未配置 CANVAS_WHISPER_BASE_URL 等失败均落明确终态；feature 门控；进度分阶段；含解析/SRT/快速失败单元测试 * feat(media): 素材卡片时长与媒体面板打磨 - 导入媒体解析时长（前端 media-metadata + 后端 project_asset durationMs 透出）随卡片展示；媒体面板/监视器/时间线相关样式细节收尾 * docs(progress): 阶段 C 监视器播放复检清单 - H.265 播放副本/真实播放驱动/时长链路待浏览器确认 * feat(timeline): M4.1 转写任务创建 API - POST /api/timeline/transcriptions - service CreateTimelineTranscriptionTask：IsDraining 守护 + feature 门控 + 资源归属与可转写类型校验 + 排队计 active 限额(含任务级/项目级存储估算)；local/whisper.cpp 标记，任务不经过模型路由与计费；createTaskWithinStorageQuota 复用与 ErrActiveTaskLimit 用户可读映射；测试覆盖排队成功(owner/type/provider 断言)、跨用户资源拒绝、非音视频拒绝 * feat(timeline): M4.3 字幕转写前端接线 - 真实任务替换 mock - 新增 services/api/timeline-tasks.ts（POST /timeline/transcriptions，复用 apiClient+request）；EditorTranscription 改为创建任务→waitForGenerationTask 轮询(25min)→结果 segments 映射 SrtEntry[]→rebuildSubtitleClips 写入字幕轨道；实时展示 stage/progress，失败/空识别/无字幕轨道分别提示；素材选择支持音频与视频（取 storageKey 中的 resource id 提交） * fix(media): 播放副本状态收敛与轮询终态 - 无ffmpeg/远端存储/编码不可处理落 none 避免重复探测;前端 none 停轮询回原生播放并加 processing 上限 * feat(timeline): M4.2 时间线渲染任务 - POST /api/timeline/renders 创建（buildRenderPlan 校验含可渲染媒体、配额入队、local/ffmpeg、60min 超时）；worker 顶部按类型分叉 processTimelineRender；ffmpeg 合成产物写资源存储并经 ResultJSON 记 resourceId；render 计划/结果测试 PASS * fix(resource): 转码原子抢占与 OSS 请求体加固 - ClaimPlaybackTranscode 空/none→processing 单实例抢占避免重复转码，runPlaybackTranscode defer recover 落 failed；If-Range 与带 :pb 后缀的 serveETag 比较；无请求体的 OSS 请求不再包 NopCloser(nil)（防 Go 1.26 body 探测 nil 解引用） * style(editor): 修正字幕回写面板缩进 * docs(timeline): M4 设计文档按实现回写 - 单一 worker 池 + processClaimedTask 顶部按类型分叉（决策 3/4），端点统一为复数 /api/timeline/transcriptions 与 /api/timeline/renders（注册于 RegisterTaskRoutes），ResultJSON/feature gate/ffmpeg env 同步；Runbook M4 表格与状态行更新；auth.go API 前缀白名单补 timeline * fix(service): 修复上游 v1.2.5 公告配图删除保护自锁与测试夹具缺口上游 #385 资源引用走查器对公告配图/草稿做了硬性引用检查，导致三个问题： - UpdateAnnouncement 在更新公告前对旧配图走查，必然命中当前公告自身引用而自锁，公告替换配图功能实际不可用；DiscardAnnouncementImage 同理被草稿自身引用阻塞。修复：ensureResourceHasNoBusinessReferences 支持忽略指定引用（当前公告/当前草稿），其余引用仍按原语义拦截。 - admin DeleteAdminResources 将公告草稿引用视为阻塞，但删除事务会级联清理草稿与资源绑定，service 层永不进入事务，回滚审计注入测试无法到达预期路径。修复：service 预检时过滤公告草稿引用，与 repository 级联语义对齐。 - project_settings_test.go 夹具未建 ResourceReferenceSnapshot 走查的 Task/Session/ Message/TaskLog/Result/Announcement/AnnouncementImageDraft 表，报 no such table。修复：夹具 AutoMigrate 补齐。后端全量 go test ./... 通过。 * feat(editor): 成片导出接入后端渲染任务（M4.2 前端接线）- timeline-tasks 增 createTimelineRenderTask；editor-export 主路径改 POST /timeline/renders 轮询取 resourceId 内嵌预览/下载，ffmpeg.wasm 降级保留 * feat(editor): M5 插件权限执行（fail-closed）- plugin-permission-check 新建（8 插槽最小权限表/判定/断言）；SlotStack 渲染前过滤缺权限插槽改诊断条；editor-shell manifest 补 timeline.command/export.run；测试 10 用例含 editor-shell 真实回归 * feat(editor): M6.1 AI 命令 schema + M6.2 时间线摘要 - ai-command-schema（parse/dry-run 校验/12-op 提示词契约/版本化+golden）；timeline-summary（确定性中文摘要/折叠上限）；各 20/10 用例全绿 * docs(progress): M6 质检清单 - M6.1 schema/M6.2 摘要标记完成（含测试计数），M6.3 待模型源确认；清理 M5.1 重复条目 * feat(editor): AI 命令 schema 支持只读问答 - commands 空数组合法化（无法执行/纯提问时 reasoning 直接作答），新增 AI_EDITING_MAX_COMMANDS=8 上限防失控编辑，提示词同步 * feat(editor): AI 助手重构为右上悬浮对话面板（M6.3）+ 素材入库原子化收尾 - editor-ai-assistant.tsx: 占位面板替换为 OpenAI Canvas 风格右上悬浮对话面板；面板内文本模型选择器（effective.textModels，选择即持久化并覆写请求模型），消息流 user/assistant/error/preview 四类气泡 + 思考中占位，空态引导示例 chips 一键发送，底部输入条；顶部工具栏常驻 Sparkles 入口（aria-pressed 切换）。修复上一版重复/截断函数声明（appendToEntry 双定义、settleAnswer 三声明等）。宿主链路：buildAiEditingSystemPrompt(summarizeTimeline(project)) 喂上下文 → parseAiCommandPlan → validateAiCommandBatch dry-run（任一非法整批拒绝）→ ≤3 条 dispatch 直执行 / >3 条预览确认卡片；宿主拒绝时 failTurn 回填 FAILED_MARK 可重试。 - editor-asset-ingest/editor-preview-monitor/detail/editor.tsx: 配套接线与打磨（编辑器顶栏 AI 入口、素材导入面板、预览监视、项目页顶栏整理）。 - backend: LinkProjectAsset 事务内原子创建资产 + 项目链接（OnConflict 幂等），资产首次入库不再预落库，失败整体回滚，消除"有资产无链接"孤儿记录。 - docs: pending-test.mdx / runbook M6.3 状态更新（tsc + 测试 + 构建通过，浏览器冒烟待真实文本渠道）。
2026-09-04 14:03:33 +08:00
parent 33c589fd8e
commit 05d1bce876
106 changed files with 10857 additions and 119 deletions
--- a/backend/internal/handler/auth.go
+++ b/backend/internal/handler/auth.go
@@ -849,7 +849,7 @@ func shortSystemProxyPath(rawPath string) (string, string, bool) {
 // as a channel request when a business route returns 404.
 func isReservedAPIPathPrefix(value string) bool {
 	switch strings.ToLower(strings.TrimSpace(value)) {
-	case "admin", "ai", "announcements", "assets", "auth", "canvas-projects", "channels", "diagnostics", "features", "files", "model-catalog", "models", "oauth", "plugins", "projects", "public", "resources", "sessions", "settings", "skills", "style-profiles", "tasks", "user-data", "voice-profiles", "wallet":
+	case "admin", "ai", "announcements", "assets", "auth", "canvas-projects", "channels", "diagnostics", "features", "files", "model-catalog", "models", "oauth", "plugins", "projects", "public", "resources", "sessions", "settings", "skills", "style-profiles", "tasks", "timeline", "user-data", "voice-profiles", "wallet":
 		return true
 	default:
 		return false
--- a/backend/internal/handler/chunk_upload_routes_test.go
+++ b/backend/internal/handler/chunk_upload_routes_test.go
@@ -0,0 +1,32 @@
+package handler
+
+import (
+	"testing"
+
+	"infinite-canvas/backend/internal/service"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestChunkedUploadRoutesAreRegistered(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	group := router.Group("/api")
+	RegisterChunkedUploadRoutes(group, &service.Service{})
+	wanted := map[string]bool{
+		"POST /api/resources/uploads":                  false,
+		"PUT /api/resources/uploads/:id/chunks/:index": false,
+		"POST /api/resources/uploads/:id/complete":     false,
+	}
+	for _, route := range router.Routes() {
+		key := route.Method + " " + route.Path
+		if _, exists := wanted[key]; exists {
+			wanted[key] = true
+		}
+	}
+	for route, found := range wanted {
+		if !found {
+			t.Errorf("route %s is not registered", route)
+		}
+	}
+}
--- a/backend/internal/handler/resource_upload_session.go
+++ b/backend/internal/handler/resource_upload_session.go
@@ -0,0 +1,299 @@
+package handler
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strconv"
+	"sync"
+	"time"
+
+	"github.com/gin-gonic/gin"
+
+	"infinite-canvas/backend/internal/service"
+)
+
+// 分片上传会话：把“导入本地媒体”拆成 开始→逐片→合并 三段，单片上限 8MB，
+// 文件整体不再受 multipart 单请求大小限制（对齐 Concat 桌面端“任意大小直接入库”的体验）。
+// 会话状态只存在内存（重启即失效 → 前端整传重试），磁盘暂存在系统临时目录，随会话清理。
+const (
+	chunkUploadChunkSize   = 8 << 20
+	chunkUploadSlackBytes  = 64 << 10 // MaxBytesReader 允许的超片余量
+	chunkUploadTTL         = 90 * time.Minute
+	chunkUploadMaxPerUser  = 32
+	chunkUploadBodyCapJSON = 16 << 10
+)
+
+type chunkedUploadSession struct {
+	ID             string
+	UserID         string
+	FileName       string
+	Kind           string
+	Size           int64
+	Width          int
+	Height         int
+	DurationMs     int64
+	IdempotencyKey string
+	ChunkCount     int
+	Dir            string
+	CreatedAt      time.Time
+}
+
+var chunkUploadSessions = struct {
+	sync.Mutex
+	m map[string]*chunkedUploadSession
+}{m: make(map[string]*chunkedUploadSession)}
+
+func newUploadSessionID() string {
+	raw := make([]byte, 12)
+	if _, err := rand.Read(raw); err != nil {
+		return fmt.Sprintf("%d", time.Now().UnixNano())
+	}
+	return hex.EncodeToString(raw)
+}
+
+func (s *chunkedUploadSession) chunkPath(index int) string {
+	return filepath.Join(s.Dir, fmt.Sprintf("chunk-%d", index))
+}
+
+func (s *chunkedUploadSession) hasAllChunks() bool {
+	for i := 0; i < s.ChunkCount; i++ {
+		info, err := os.Stat(s.chunkPath(i))
+		if err != nil || info.Size() != s.chunkSizeAt(i) {
+			return false
+		}
+	}
+	return true
+}
+
+// chunkSizeAt 返回第 index 片的期望字节数（末片按文件余量，其余固定 chunkSize）。
+func (s *chunkedUploadSession) chunkSizeAt(index int) int64 {
+	if index == s.ChunkCount-1 {
+		rest := s.Size - int64(index)*chunkUploadChunkSize
+		if rest < 0 {
+			return 0
+		}
+		return rest
+	}
+	return chunkUploadChunkSize
+}
+
+func removeExpiredChunkSessions() {
+	now := time.Now()
+	chunkUploadSessions.Lock()
+	defer chunkUploadSessions.Unlock()
+	for id, sess := range chunkUploadSessions.m {
+		if now.Sub(sess.CreatedAt) > chunkUploadTTL {
+			_ = os.RemoveAll(sess.Dir)
+			delete(chunkUploadSessions.m, id)
+		}
+	}
+}
+
+func takeChunkSession(id string) *chunkedUploadSession {
+	removeExpiredChunkSessions()
+	chunkUploadSessions.Lock()
+	defer chunkUploadSessions.Unlock()
+	return chunkUploadSessions.m[id]
+}
+
+func dropChunkSession(id string) {
+	chunkUploadSessions.Lock()
+	defer chunkUploadSessions.Unlock()
+	if sess := chunkUploadSessions.m[id]; sess != nil {
+		_ = os.RemoveAll(sess.Dir)
+		delete(chunkUploadSessions.m, id)
+	}
+}
+
+// RegisterChunkedUploadRoutes 注册本地媒体分片上传三条接口（POST 开始 / PUT 上传片 / POST 合并）。
+func RegisterChunkedUploadRoutes(r *gin.RouterGroup, svc *service.Service) {
+	r.POST("/resources/uploads", func(c *gin.Context) {
+		user, err := currentUser(c, svc)
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		policy, available := loadRuntimePolicy(c, svc)
+		if !available || !enforceRateLimit(c, "resources-upload:"+user.ID, policy.Request.ResourceUploadPerMinute, time.Minute) {
+			return
+		}
+		c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, chunkUploadBodyCapJSON)
+		var req struct {
+			FileName       string `json:"fileName"`
+			Kind           string `json:"kind"`
+			Size           int64  `json:"size"`
+			Width          int    `json:"width"`
+			Height         int    `json:"height"`
+			DurationMs     int64  `json:"durationMs"`
+			IdempotencyKey string `json:"idempotencyKey"`
+		}
+		if err := c.ShouldBindJSON(&req); err != nil {
+			fail(c, http.StatusBadRequest, err)
+			return
+		}
+		if req.FileName == "" || len(req.FileName) > 255 {
+			fail(c, http.StatusBadRequest, fmt.Errorf("文件名不能为空且不能超过 255 个字符"))
+			return
+		}
+		if req.Size <= 0 {
+			fail(c, http.StatusBadRequest, fmt.Errorf("文件大小必须大于 0"))
+			return
+		}
+		// 超账号存储总量的文件无论如何都会失败，提前给出明确提示。
+		if policy.Resource.StoredFileGB > 0 && req.Size > int64(policy.Resource.StoredFileGB)<<30 {
+			fail(c, http.StatusBadRequest, fmt.Errorf("文件超过账号存储总量上限 %dGB", policy.Resource.StoredFileGB))
+			return
+		}
+		// 同一用户并发会话数兜底，防内存占用失控。
+		active := 0
+		chunkUploadSessions.Lock()
+		for _, sess := range chunkUploadSessions.m {
+			if sess.UserID == user.ID {
+				active++
+			}
+		}
+		chunkUploadSessions.Unlock()
+		if active >= chunkUploadMaxPerUser {
+			fail(c, http.StatusTooManyRequests, fmt.Errorf("同时进行中的上传过多，请稍后重试"))
+			return
+		}
+		dir, err := os.MkdirTemp("", "canvas-chunk-upload-*")
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		session := &chunkedUploadSession{
+			ID:             newUploadSessionID(),
+			UserID:         user.ID,
+			FileName:       req.FileName,
+			Kind:           req.Kind,
+			Size:           req.Size,
+			Width:          req.Width,
+			Height:         req.Height,
+			DurationMs:     req.DurationMs,
+			IdempotencyKey: req.IdempotencyKey,
+			ChunkCount:     int((req.Size + chunkUploadChunkSize - 1) / chunkUploadChunkSize),
+			Dir:            dir,
+			CreatedAt:      time.Now(),
+		}
+		chunkUploadSessions.Lock()
+		chunkUploadSessions.m[session.ID] = session
+		chunkUploadSessions.Unlock()
+		ok(c, gin.H{"uploadId": session.ID, "chunkSize": chunkUploadChunkSize, "chunkCount": session.ChunkCount})
+	})
+
+	r.PUT("/resources/uploads/:id/chunks/:index", func(c *gin.Context) {
+		user, err := currentUser(c, svc)
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		session := takeChunkSession(c.Param("id"))
+		if session == nil || session.UserID != user.ID {
+			fail(c, http.StatusNotFound, fmt.Errorf("上传会话不存在或已过期，请重新导入"))
+			return
+		}
+		index, err := strconv.Atoi(c.Param("index"))
+		if err != nil || index < 0 || index >= session.ChunkCount {
+			fail(c, http.StatusBadRequest, fmt.Errorf("非法的分片序号"))
+			return
+		}
+		expected := session.chunkSizeAt(index)
+		if expected <= 0 {
+			fail(c, http.StatusBadRequest, fmt.Errorf("非法的分片序号"))
+			return
+		}
+		// 单片限长（期望长度 + 少量余量），超长直接中断，避免内存/磁盘被恶意占用。
+		body := http.MaxBytesReader(c.Writer, c.Request.Body, expected+chunkUploadSlackBytes)
+		dst, err := os.OpenFile(session.chunkPath(index), os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o600)
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		written, copyErr := io.CopyN(dst, body, expected)
+		closeErr := dst.Close()
+		var probe [1]byte
+		extra, readErr := body.Read(probe[:])
+		if copyErr != nil || closeErr != nil {
+			_ = os.Remove(session.chunkPath(index))
+			fail(c, http.StatusBadRequest, fmt.Errorf("分片 %d 上传不完整，请重试", index))
+			return
+		}
+		if readErr == nil || extra > 0 {
+			_ = os.Remove(session.chunkPath(index))
+			fail(c, http.StatusBadRequest, fmt.Errorf("分片 %d 超过大小限制", index))
+			return
+		}
+		_ = written
+		ok(c, gin.H{"index": index})
+	})
+
+	r.POST("/resources/uploads/:id/complete", func(c *gin.Context) {
+		user, err := currentUser(c, svc)
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		id := c.Param("id")
+		session := takeChunkSession(id)
+		if session == nil || session.UserID != user.ID {
+			fail(c, http.StatusNotFound, fmt.Errorf("上传会话不存在或已过期，请重新导入"))
+			return
+		}
+		if !session.hasAllChunks() {
+			fail(c, http.StatusBadRequest, fmt.Errorf("上传文件不完整，请重新导入"))
+			return
+		}
+		mergedPath := filepath.Join(session.Dir, "merged")
+		merged, err := os.OpenFile(mergedPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, 0o600)
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		total := int64(0)
+		for i := 0; i < session.ChunkCount; i++ {
+			part, openErr := os.Open(session.chunkPath(i))
+			if openErr != nil {
+				_ = merged.Close()
+				failService(c, openErr)
+				return
+			}
+			n, copyErr := io.Copy(merged, part)
+			_ = part.Close()
+			if copyErr != nil {
+				_ = merged.Close()
+				failService(c, copyErr)
+				return
+			}
+			total += n
+		}
+		if closeErr := merged.Close(); closeErr != nil {
+			failService(c, closeErr)
+			return
+		}
+		if total != session.Size {
+			dropChunkSession(id)
+			fail(c, http.StatusBadRequest, fmt.Errorf("上传文件不完整，请重新导入"))
+			return
+		}
+		fh, err := os.Open(mergedPath)
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		defer fh.Close()
+		resource, svcErr := svc.UploadResourceFile(user.ID, session.FileName, session.Size, session.Kind, session.Width, session.Height, session.DurationMs, fh, session.IdempotencyKey)
+		// 无论成败都结束会话：失败时前端会整传重试，不需要保留残片。
+		dropChunkSession(id)
+		if svcErr != nil {
+			failService(c, svcErr)
+			return
+		}
+		ok(c, gin.H{"resource": resource})
+	})
+}
--- a/backend/internal/handler/routes.go
+++ b/backend/internal/handler/routes.go
@@ -52,6 +52,52 @@ func RegisterTaskRoutes(r *gin.RouterGroup, svc *service.Service) {
 		}
 		ok(c, task)
 	})
+	r.POST("/timeline/transcriptions", func(c *gin.Context) {
+		user, err := currentUser(c, svc)
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		policy, available := loadRuntimePolicy(c, svc)
+		if !available || !enforceRateLimit(c, "timeline-ts:"+user.ID, policy.Request.TaskCreatePerMinute, time.Minute) {
+			return
+		}
+		c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, 1<<20)
+		var req service.TimelineTranscriptionCreateRequest
+		if err := c.ShouldBindJSON(&req); err != nil {
+			fail(c, http.StatusBadRequest, err)
+			return
+		}
+		task, err := svc.CreateTimelineTranscriptionTask(user.ID, req)
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		ok(c, task)
+	})
+	r.POST("/timeline/renders", func(c *gin.Context) {
+		user, err := currentUser(c, svc)
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		policy, available := loadRuntimePolicy(c, svc)
+		if !available || !enforceRateLimit(c, "timeline-render:"+user.ID, policy.Request.TaskCreatePerMinute, time.Minute) {
+			return
+		}
+		c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, 64<<20)
+		var req service.TimelineRenderCreateRequest
+		if err := c.ShouldBindJSON(&req); err != nil {
+			fail(c, http.StatusBadRequest, err)
+			return
+		}
+		task, err := svc.CreateTimelineRenderTask(user.ID, req)
+		if err != nil {
+			failService(c, err)
+			return
+		}
+		ok(c, task)
+	})
 	r.GET("/tasks", func(c *gin.Context) {
 		user, err := currentUser(c, svc)
 		if err != nil {
--- a/backend/internal/handler/user_data.go
+++ b/backend/internal/handler/user_data.go
@@ -2,6 +2,7 @@ package handler

 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -171,6 +172,12 @@ func RegisterUserDataRoutes(r *gin.RouterGroup, svc *service.Service) {
 		c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, (policy.Resource.ResourceUploadMB<<20)+(1<<20))
 		file, err := c.FormFile("file")
 		if err != nil {
+			var maxErr *http.MaxBytesError
+			if errors.As(err, &maxErr) {
+				// 超 MaxBytesReader 上限时 FormFile 返回英文 http 错误，转成与 service 配额校验一致的中文文案。
+				fail(c, http.StatusBadRequest, fmt.Errorf("单个上传文件必须小于 %dMB", policy.Resource.ResourceUploadMB))
+				return
+			}
 			fail(c, http.StatusBadRequest, err)
 			return
 		}
@@ -271,24 +278,56 @@ func RegisterUserDataRoutes(r *gin.RouterGroup, svc *service.Service) {
 		}
 		resource := delivery.Resource
 		etag := resourceResponseETag(resource)
+		// variant=playback：serve 浏览器兼容播放副本（H.265→H.264 转码）。
+		// 副本就绪时用独立 ETag 后缀，避免浏览器拿原件缓存命中 304 而继续黑屏。
+		usePlayback := c.Query("variant") == "playback" && resource.Provider == "local" &&
+			resource.PlaybackStatus == model.PlaybackStatusReady && resource.PlaybackObjectKey != ""
+		serveETag := etag
+		if usePlayback {
+			serveETag = etag + ":pb"
+		}
 		// 私有资源允许浏览器保存响应，但每次复用前必须重新鉴权；304 会在读取 OSS 前返回。
 		c.Header("Cache-Control", "private, no-cache")
-		c.Header("ETag", etag)
+		c.Header("ETag", serveETag)
 		c.Header("Accept-Ranges", "bytes")
 		c.Header("X-Content-Type-Options", "nosniff")
 		if resource.Kind == "file" {
 			c.Header("Content-Disposition", "attachment")
 			c.Header("Content-Security-Policy", "sandbox")
 		}
-		if ifNoneMatch(c.GetHeader("If-None-Match"), etag) {
+		if ifNoneMatch(c.GetHeader("If-None-Match"), serveETag) {
 			c.Status(http.StatusNotModified)
 			return
 		}
 		rangeHeader := c.GetHeader("Range")
-		if ifRange := strings.TrimSpace(c.GetHeader("If-Range")); ifRange != "" && ifRange != etag {
+		if ifRange := strings.TrimSpace(c.GetHeader("If-Range")); ifRange != "" && ifRange != serveETag {
 			rangeHeader = ""
 		}
-		stream, err := svc.OpenResourceRange(user.ID, resource.ID, rangeHeader)
+		var stream *service.ResourceStream
+		if usePlayback {
+			stream, err = svc.OpenResourcePlaybackRange(user.ID, resource.ID)
+			if err == nil {
+				resource = stream.Resource // MimeType 已置 video/mp4
+			} else if errors.Is(err, service.ErrPlaybackNotReady) {
+				// 副本尚未就绪：回退原件，并撤销 :pb 后缀，保证副本就绪后
+				// 浏览器不会拿原件缓存命中 304 而继续黑屏。
+				c.Header("ETag", etag)
+				stream, err = svc.OpenResourceRange(user.ID, resource.ID, rangeHeader)
+				if err != nil {
+					failService(c, err)
+					return
+				}
+			} else {
+				failService(c, err)
+				return
+			}
+		} else {
+			stream, err = svc.OpenResourceRange(user.ID, resource.ID, rangeHeader)
+			if err != nil {
+				failService(c, err)
+				return
+			}
+		}
 		if err != nil {
 			failService(c, err)
 			return