[Claude Workbench] Initial commit - preserving existing code

QUICK_REFERENCE.md

@@ -0,0 +1,164 @@
+# RunningHub集成快速参考卡
+
+**版本：** v2.2.0 | **更新：** 2025-10-20
+
+---
+
+## 🎯 一分钟快速了解
+
+### 完成的功能
+- ✅ 集成RunningHub Sora2 API（文生视频 + 图生视频）
+- ✅ 12个预配置模型（竖屏/横屏 × 普通/高清 × 10秒/15秒）
+- ✅ 多厂商架构（OpenAI + RunningHub无缝切换）
+- ✅ 10秒轮询优化（成本降低50%）
+- ✅ 完整URL支持（图生视频无需预先上传）
+- ✅ **并发控制**（最多100个轮询任务）
+- ✅ **队列管理**（超出自动排队）
+
+### 核心配置
+
+```yaml
+# application.yml
+ai.providers.runninghub:
+  polling-interval: 10000      # 10秒轮询
+  max-polling-times: 60        # 最大10分钟
+  max-polling-tasks: 100       # 最多100个并发轮询
+  queue-check-interval: 5000   # 5秒检查队列
+  api-key: "5c44cef12da3470e9f24da70c63787dc"
+```
+
+---
+
+## 📝 快速测试
+
+### 1. 文生视频（竖屏10秒）
+
+```bash
+curl -X POST "http://localhost:8081/user/ai/tasks/submit" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "modelName": "rh_sora2_text_portrait",
+    "prompt": "一个人在海边奔跑"
+  }'
+```
+
+### 2. 图生视频（横屏高清）
+
+```bash
+curl -X POST "http://localhost:8081/user/ai/tasks/submit" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "modelName": "rh_sora2_img_landscape_hd",
+    "prompt": "让场景动起来",
+    "imageUrl": "https://example.com/image.jpg"
+  }'
+```
+
+---
+
+## 📊 模型列表（12个）
+
+| 模型名称 | 类型 | 时长 | 分辨率 | 积分 |
+|---------|------|------|--------|------|
+| rh_sora2_text_portrait | 文生视频 | 10秒 | 竖屏 | 160 |
+| rh_sora2_text_landscape | 文生视频 | 10秒 | 横屏 | 160 |
+| rh_sora2_text_portrait_hd | 文生视频 | 10秒 | 高清竖屏 | 420 |
+| rh_sora2_text_landscape_hd | 文生视频 | 10秒 | 高清横屏 | 420 |
+| rh_sora2_text_portrait_15s | 文生视频 | 15秒 | 竖屏 | 260 |
+| rh_sora2_text_landscape_15s | 文生视频 | 15秒 | 横屏 | 260 |
+| rh_sora2_img_portrait | 图生视频 | 10秒 | 竖屏 | 180 |
+| rh_sora2_img_landscape | 图生视频 | 10秒 | 横屏 | 180 |
+| rh_sora2_img_portrait_hd | 图生视频 | 10秒 | 高清竖屏 | 480 |
+| rh_sora2_img_landscape_hd | 图生视频 | 10秒 | 高清横屏 | 480 |
+| rh_sora2_img_portrait_15s | 图生视频 | 15秒 | 竖屏 | 280 |
+| rh_sora2_img_landscape_15s | 图生视频 | 15秒 | 横屏 | 280 |
+
+---
+
+## 🚀 部署步骤（3步）
+
+```bash
+# 1. 数据库迁移
+mysql -u root -p 1818ai < V5__add_provider_support.sql
+
+# 2. 编译部署
+mvn clean package -DskipTests
+sudo systemctl restart spring_1818_user_server
+
+# 3. 验证
+sudo journalctl -u spring_1818_user_server | grep "注册AI Provider"
+# 应看到：openai + runninghub
+```
+
+---
+
+## 🔍 监控命令
+
+```bash
+# 查看队列状态（管理员接口）
+curl "http://localhost:8081/admin/runninghub/queue/status" \
+  -H "Authorization: Bearer $ADMIN_TOKEN"
+
+# 查看处理中的任务数
+mysql -u root -p 1818ai -e "SELECT COUNT(*) FROM ai_task WHERE status='processing' AND provider_type='runninghub';"
+
+# 查看等待队列中的任务数
+mysql -u root -p 1818ai -e "SELECT COUNT(*) FROM ai_task WHERE status='queued' AND provider_type='runninghub';"
+
+# 实时轮询日志
+sudo journalctl -u spring_1818_user_server -f | grep -E "(RunningHub|队列)"
+
+# 手动处理队列（管理员操作）
+curl "http://localhost:8081/admin/runninghub/queue/process" \
+  -H "Authorization: Bearer $ADMIN_TOKEN"
+```
+
+---
+
+## 📚 完整文档
+
+| 文档 | 说明 |
+|-----|------|
+| `RUNNINGHUB_FINAL_SUMMARY.md` | **总览**（推荐首读） |
+| `RUNNINGHUB_QUEUE_OPTIMIZATION.md` | **队列优化方案**（v2.2.0新增） |
+| `RUNNINGHUB_USAGE_GUIDE.md` | 使用指南（12个模型详解） |
+| `RUNNINGHUB_CONCURRENCY_ANALYSIS.md` | 并发能力分析 |
+| `POLLING_INTERVAL_OPTIMIZATION.md` | 轮询优化说明 |
+| `DEPLOYMENT_CHECKLIST.md` | 部署检查清单 |
+| `MULTI_VENDOR_ADAPTER_DESIGN.md` | 架构设计 |
+
+---
+
+## ⚠️ 注意事项
+
+1. **图生视频不支持真人图像**
+2. **轮询任务上限100个**（超出自动进入等待队列）
+3. **imageUrl支持完整HTTP/HTTPS地址**
+4. **任务失败自动退还积分**
+5. **等待队列自动处理**（每5秒检查一次）
+
+---
+
+## 💡 常见问题
+
+**Q：任务一直processing？**  
+A：正常，RunningHub需要2-5分钟处理。查看轮询日志确认。
+
+**Q：任务卡在queued状态？**  
+A：说明当前轮询任务已满（100个），正在等待队列。任务完成后会自动提交。
+
+**Q：如何查看队列状态？**  
+A：使用管理员接口：`GET /admin/runninghub/queue/status`
+
+**Q：如何调整并发上限？**  
+A：修改 `application.yml` 中的 `max-polling-tasks`（默认100）
+
+**Q：等待队列会堆积吗？**  
+A：不会。任务完成后自动从队列提交新任务，队列持续消化。
+
+---
+
+**快速参考完毕！详细信息请查看完整文档。** 📖
+