docs: 添加剪映导出算法详细文档

- 新增剪映导出算法详细说明文档 (jianying-export-algorithm.md) - 新增算法流程图和可视化文档 (jianying-export-flowchart.md) - 详细描述数据转换、路径处理、时间轴映射等核心算法 - 包含性能优化、错误处理、测试验证等完整说明 - 提供Mermaid流程图展示算法执行流程 - 涵盖扩展性设计和故障排除指南文档内容: - 算法概述和核心组件 - 详细的步骤分解和代码示例 - 数据结构转换映射关系 - 性能基准和优化策略 - 完整的流程图和可视化说明
2025-07-16 22:45:09 +08:00
parent fb6b345188
commit 70e502be93
2 changed files with 833 additions and 0 deletions
--- a/docs/algorithms/jianying-export-flowchart.md
+++ b/docs/algorithms/jianying-export-flowchart.md
@@ -0,0 +1,269 @@
+# 剪映导出算法流程图
+
+## 总体流程
+
+```mermaid
+flowchart TD
+    Start([开始导出]) --> Input[输入参数验证]
+    Input --> GetData[获取匹配结果详情]
+    GetData --> CheckData{数据是否有效?}
+    CheckData -->|否| Error1[返回错误]
+    CheckData -->|是| InitDraft[初始化草稿结构]
+    
+    InitDraft --> CalcDuration[计算总时长]
+    CalcDuration --> GenMaterials[生成素材列表]
+    GenMaterials --> GenTracks[生成轨道结构]
+    GenTracks --> Serialize[序列化JSON]
+    Serialize --> WriteFile[写入文件]
+    WriteFile --> Success[返回文件路径]
+    
+    Error1 --> End([结束])
+    Success --> End
+```
+
+## 素材生成详细流程
+
+```mermaid
+flowchart TD
+    StartMat[开始生成素材] --> InitMap[初始化ID映射表]
+    InitMap --> LoopStart{遍历匹配片段}
+    
+    LoopStart -->|有片段| QuerySegment[查询MaterialSegment]
+    QuerySegment --> CheckSegment{片段是否存在?}
+    CheckSegment -->|否| LogError[记录错误并跳过]
+    CheckSegment -->|是| NormalizePath[标准化文件路径]
+    
+    NormalizePath --> GenUUID[生成随机素材ID]
+    GenUUID --> MapID[建立ID映射关系]
+    MapID --> CreateVideo[创建JianYingVideo对象]
+    CreateVideo --> AddToList[添加到素材列表]
+    
+    AddToList --> LoopStart
+    LogError --> LoopStart
+    LoopStart -->|无片段| ReturnMaterials[返回素材列表和映射表]
+```
+
+## 轨道生成详细流程
+
+```mermaid
+flowchart TD
+    StartTrack[开始生成轨道] --> CreateTrack[创建主视频轨道]
+    CreateTrack --> InitSegments[初始化片段列表]
+    InitSegments --> LoopSegments{遍历匹配片段}
+    
+    LoopSegments -->|有片段| LookupID[查找素材ID映射]
+    LookupID --> CheckMapping{映射是否存在?}
+    CheckMapping -->|否| SkipSegment[跳过此片段]
+    CheckMapping -->|是| CreateSegment[创建JianYingSegment]
+    
+    CreateSegment --> SetTimeRange[设置时间轴映射]
+    SetTimeRange --> SetProperties[设置播放属性]
+    SetProperties --> SetEffects[设置视觉效果]
+    SetEffects --> AddSegment[添加到片段列表]
+    
+    AddSegment --> LoopSegments
+    SkipSegment --> LoopSegments
+    LoopSegments -->|无片段| AssignTrack[分配轨道结构]
+    AssignTrack --> ReturnTracks[返回轨道列表]
+```
+
+## 路径处理流程
+
+```mermaid
+flowchart TD
+    InputPath[输入文件路径] --> CheckUNC{是否包含\\\\?\\前缀?}
+    CheckUNC -->|是| RemovePrefix[移除UNC前缀]
+    CheckUNC -->|否| KeepOriginal[保持原路径]
+    RemovePrefix --> ValidatePath[验证路径格式]
+    KeepOriginal --> ValidatePath
+    ValidatePath --> ReturnPath[返回标准化路径]
+```
+
+## 时间轴映射机制
+
+```mermaid
+flowchart LR
+    subgraph "模板时间轴"
+        TS1[片段1: 0-5s]
+        TS2[片段2: 5-10s]
+        TS3[片段3: 10-15s]
+    end
+    
+    subgraph "素材文件"
+        MS1[素材A: 0-5s]
+        MS2[素材B: 0-5s]
+        MS3[素材C: 0-5s]
+    end
+    
+    subgraph "剪映时间轴"
+        JS1[片段1: 0-5s]
+        JS2[片段2: 5-10s]
+        JS3[片段3: 10-15s]
+    end
+    
+    TS1 --> MS1
+    TS2 --> MS2
+    TS3 --> MS3
+    
+    MS1 --> JS1
+    MS2 --> JS2
+    MS3 --> JS3
+```
+
+## 数据转换映射
+
+```mermaid
+flowchart LR
+    subgraph "输入数据"
+        TMR[TemplateMatchingResult]
+        MSR[MatchingSegmentResult[]]
+        MS[MaterialSegment]
+    end
+    
+    subgraph "中间处理"
+        IDMap[ID映射表]
+        PathNorm[路径标准化]
+        TimeCalc[时长计算]
+    end
+    
+    subgraph "输出数据"
+        JDC[JianYingDraftContent]
+        JV[JianYingVideo[]]
+        JT[JianYingTrack[]]
+        JSeg[JianYingSegment[]]
+    end
+    
+    TMR --> TimeCalc
+    MSR --> IDMap
+    MS --> PathNorm
+    
+    IDMap --> JV
+    PathNorm --> JV
+    TimeCalc --> JDC
+    
+    JV --> JDC
+    JT --> JDC
+    JSeg --> JT
+```
+
+## 错误处理流程
+
+```mermaid
+flowchart TD
+    Operation[执行操作] --> CheckError{是否发生错误?}
+    CheckError -->|否| Continue[继续执行]
+    CheckError -->|是| ErrorType{错误类型}
+    
+    ErrorType -->|数据不存在| LogWarning[记录警告]
+    ErrorType -->|系统错误| LogError[记录错误]
+    ErrorType -->|致命错误| Abort[中止执行]
+    
+    LogWarning --> Skip[跳过当前项]
+    LogError --> Retry{是否重试?}
+    Retry -->|是| Operation
+    Retry -->|否| Skip
+    
+    Skip --> Continue
+    Abort --> ReturnError[返回错误]
+    Continue --> Success[操作成功]
+```
+
+## 性能优化策略
+
+```mermaid
+flowchart TD
+    subgraph "数据库优化"
+        BatchQuery[批量查询]
+        IndexOpt[索引优化]
+        ConnPool[连接池]
+    end
+    
+    subgraph "内存优化"
+        PreAlloc[预分配容量]
+        ObjectPool[对象池]
+        LazyLoad[延迟加载]
+    end
+    
+    subgraph "算法优化"
+        HashMap[HashMap查找]
+        PathCache[路径缓存]
+        ParallelProc[并行处理]
+    end
+    
+    subgraph "I/O优化"
+        AsyncIO[异步I/O]
+        BufferWrite[缓冲写入]
+        Compression[压缩输出]
+    end
+```
+
+## 质量保证流程
+
+```mermaid
+flowchart TD
+    StartQA[开始质量检查] --> ValidateInput[验证输入数据]
+    ValidateInput --> CheckMaterials[检查素材完整性]
+    CheckMaterials --> ValidateTime[验证时间轴]
+    ValidateTime --> CheckPaths[检查文件路径]
+    CheckPaths --> ValidateJSON[验证JSON格式]
+    ValidateJSON --> TestImport[测试剪映导入]
+    TestImport --> QAPass{质量检查通过?}
+    
+    QAPass -->|是| DeployReady[准备部署]
+    QAPass -->|否| FixIssues[修复问题]
+    FixIssues --> StartQA
+```
+
+## 监控和日志
+
+```mermaid
+flowchart LR
+    subgraph "性能监控"
+        ExecTime[执行时间]
+        MemUsage[内存使用]
+        DBQuery[数据库查询次数]
+    end
+    
+    subgraph "业务监控"
+        SuccessRate[成功率]
+        ErrorCount[错误计数]
+        FileSize[输出文件大小]
+    end
+    
+    subgraph "日志记录"
+        InfoLog[信息日志]
+        WarnLog[警告日志]
+        ErrorLog[错误日志]
+    end
+    
+    ExecTime --> InfoLog
+    MemUsage --> InfoLog
+    DBQuery --> InfoLog
+    SuccessRate --> InfoLog
+    ErrorCount --> WarnLog
+    FileSize --> InfoLog
+```
+
+## 扩展性设计
+
+```mermaid
+flowchart TD
+    CurrentImpl[当前实现] --> Extensions[扩展点]
+    
+    Extensions --> MultiTrack[多轨道支持]
+    Extensions --> Effects[特效支持]
+    Extensions --> Templates[模板参数化]
+    Extensions --> Formats[多格式导出]
+    
+    MultiTrack --> AudioTrack[音频轨道]
+    MultiTrack --> SubtitleTrack[字幕轨道]
+    
+    Effects --> Transitions[转场效果]
+    Effects --> Filters[滤镜效果]
+    
+    Templates --> CustomCanvas[自定义画布]
+    Templates --> FrameRate[帧率设置]
+    
+    Formats --> FinalCut[Final Cut Pro]
+    Formats --> Premiere[Adobe Premiere]
+```