video-flow-b/components/pages/work-flow/video-edit/README.md

🎬 Video Edit Feature

一个完整的视频编辑功能模块，允许用户在视频上添加交互式编辑点，描述修改需求，并与聊天系统集成。

✨ 功能特性

🎯 核心功能

• 交互式编辑点: 点击视频任意位置创建编辑点
• 脉冲动画: 编辑点具有优雅的脉冲动画效果
• 弧线连接: 从编辑点到输入框的优美弧线连接
• 智能输入框: 带有玻璃态效果的输入框，支持键盘操作
• 多点管理: 支持同时存在多个编辑点
• 实时同步: 编辑点数据实时保存和同步

🎨 视觉效果

• 玻璃态设计: 与work-flow页面设计风格一致
• 流畅动画: 使用Framer Motion实现丝滑动画
• 响应式布局: 适配各种屏幕尺寸
• 暗色主题: 完美适配暗色模式

🔧 技术特性

• TypeScript: 完整的类型安全
• React Hooks: 现代化的状态管理
• API集成: 完整的CRUD操作
• 性能优化: 智能渲染和内存管理

🏗️ 架构设计

video-edit/
├── types.ts              # 类型定义
├── useVideoEdit.ts       # 状态管理Hook
├── VideoEditOverlay.tsx  # 主覆盖层组件
├── EditPoint.tsx         # 编辑点组件
├── EditConnection.tsx    # 连接线组件
├── EditInput.tsx         # 输入框组件
├── api.ts               # API接口
├── video-edit.css       # 响应式样式
├── VideoEditDemo.tsx    # 演示组件
└── index.ts             # 模块导出

🚀 快速开始

1. 基础使用

import { VideoEditOverlay } from '@/components/pages/work-flow/video-edit';

function MyVideoPlayer() {
  const videoRef = useRef<HTMLVideoElement>(null);
  
  const handleDescriptionSubmit = (editPoint, description) => {
    console.log('编辑请求:', { editPoint, description });
    // 发送到聊天系统或处理编辑请求
  };

  return (
    <div className="relative">
      <video ref={videoRef} src="your-video.mp4" />
      
      <VideoEditOverlay
        projectId="your-project-id"
        userId={123}
        currentVideo={{
          id: 'video-id',
          url: 'your-video.mp4',
          duration: 30
        }}
        videoRef={videoRef}
        enabled={true}
        onDescriptionSubmit={handleDescriptionSubmit}
      />
    </div>
  );
}

2. 集成到MediaViewer

// 在MediaViewer组件中
<VideoEditOverlay
  projectId={taskObject.project_id}
  userId={currentUser.id}
  currentVideo={{
    id: currentVideo.video_id,
    url: currentVideo.urls[0],
    duration: 30
  }}
  videoRef={mainVideoRef}
  enabled={isVideoEditMode}
  onDescriptionSubmit={handleVideoEditDescriptionSubmit}
  className="rounded-lg"
/>

📱 响应式设计

屏幕适配

• 桌面端 (≥1024px): 完整功能，hover效果
• 平板端 (768-1023px): 增大点击区域
• 手机端 (≤767px): 优化触摸交互，简化界面
• 小屏幕 (≤480px): 最大化可用空间

触摸优化

• 增大点击区域 (最小44px)
• 防止iOS缩放 (font-size: 16px)
• 触摸反馈动画

🎮 交互说明

键盘操作

• ESC: 取消当前编辑
• Ctrl+Enter: 提交描述
• Tab: 在输入框内导航

鼠标操作

• 单击视频: 创建编辑点
• 单击编辑点: 选择并显示输入框
• 点击外部: 自动提交或取消

触摸操作

• 轻触视频: 创建编辑点
• 轻触编辑点: 选择编辑点
• 长按: 显示上下文菜单

🔌 API集成

编辑点CRUD操作

import { 
  createEditPoint, 
  updateEditPoint, 
  deleteEditPoint, 
  getEditPoints 
} from '@/components/pages/work-flow/video-edit';

// 创建编辑点
const editPoint = await createEditPoint({
  videoId: 'video-id',
  projectId: 'project-id',
  position: { x: 50, y: 30 },
  timestamp: 15.5,
  description: '需要添加字幕'
});

// 更新编辑点
await updateEditPoint({
  id: editPoint.id,
  description: '更新后的描述',
  status: 'edited'
});

// 获取编辑点列表
const response = await getEditPoints({
  videoId: 'video-id',
  projectId: 'project-id'
});

🎨 样式定制

CSS变量

.video-edit-input {
  --bg-color: rgba(0, 0, 0, 0.8);
  --border-color: rgba(255, 255, 255, 0.2);
  --text-color: rgba(255, 255, 255, 0.9);
}

主题适配

• 自动检测系统主题
• 支持高对比度模式
• 可访问性优化

🧪 测试

运行测试页面

# 访问测试页面
http://localhost:3000/test/video-edit

测试清单

• 编辑点创建和动画
• 连接线绘制
• 输入框交互
• 键盘操作
• 响应式布局
• 性能测试

🔧 配置选项

VideoEditConfig

interface VideoEditConfig {
  maxEditPoints: number;        // 最大编辑点数量
  autoSave: boolean;           // 自动保存
  animationDuration: number;   // 动画时长
  pointStyle: {
    size: number;
    color: string;
    pulseColor: string;
  };
  connectionStyle: {
    strokeWidth: number;
    color: string;
    dashArray: string;
  };
}

🚨 注意事项

性能优化

• 编辑点数量建议不超过20个
• 使用虚拟化处理大量编辑点
• 及时清理未使用的编辑点

兼容性

• 需要现代浏览器支持 (Chrome 80+, Firefox 75+, Safari 13+)
• 移动端需要iOS 13+, Android 8+
• 需要支持CSS Grid和Flexbox

安全考虑

• 输入内容需要XSS过滤
• API调用需要身份验证
• 编辑点数据需要权限控制

📝 更新日志

v1.0.0 (2024-01-XX)

• ✨ 初始版本发布
• 🎯 基础编辑点功能
• 🎨 玻璃态UI设计
• 📱 响应式适配
• 🔌 API集成
• 🧪 测试套件

🤝 贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

📄 许可证

MIT License - 详见 LICENSE 文件