技术事实清单 (Tech Facts)

定位：一刻工坊 (KKmusic) 的技术架构单一事实源。 原则：基于代码仓库现状，不包含未落地的架构设计。

1. 分层架构

1.1 前端 (Frontend)

• 框架：Vue 3 + Vite.
• UI 库：Element Plus (定制化主题/Glassmorphism 风格).
• 状态管理：Pinia.
• 样式：SCSS (包含自定义动画如 rotate-glow, pulse-badge).
• 路由：Vue Router.

1.2 后端 (Backend)

• 运行时：Node.js.
• Web 框架：Express.
• ORM：Sequelize.
• API 风格：RESTful API.

1.3 AI 引擎层 (AI Engines)

• LangGraph Runner：
  • 语言：Python.
  • 职责：运行复杂的 AI Agent 逻辑 (如 StrategyAgent, MusicVideoAgent).
  • 通信：通过 HTTP/WebSocket 与 Backend 交互。
• ComfyUI：
  • 集成方式：通过 ComfyUIRunnerService 远程调用。
• Flowise / N8N：
  • 集成方式：作为工作流编排引擎被 Backend 调用 (FlowiseRunnerService, N8NRunnerService).

1.4 客户端 (Clients)

• Electron：桌面端壳，封装 Web 前端。
• Miniprogram：移动端（UniApp?），用于拍摄、上传素材、简单任务管理。

2. 外部依赖清单

2.1 AI 模型与服务

• 文本/对话：OpenAI (或其他 LLM 提供商).
• 音频/音乐：
  • Suno (sunoService.js)：音乐生成。
  • Fish Audio (fishAudioService.js)：TTS/配音。
• 视频/图像：
  • ComfyUI：图像/视频生成。
  • 剪映 (Jianying)：JianyingDraftService.js (草稿生成/导出).

2.2 基础设施

• 数据库：PostgreSQL (推断自 Sequelize).
• 缓存/队列：Redis (推断自常见架构，需确认代码中 Queue 的实现).
• 存储：本地文件系统 + 对象存储 (MinIO/S3, 见 storageService.js).

2.3 支付与发布

• 支付：Alipay, WeChat Pay.
• 发布平台：Douyin, Bilibili, Xiaohongshu.

3. 核心数据对象 (Data Objects)

基于 backend/src/models/:

对象名 (Class)	对应表名	描述	关键字段示例
Project	projects	项目	id, name, status
Task	tasks	任务	projectId, status, type
UserCorpus	user_corpora	灵感/语料	content, source_url, related_asset_id
UnifiedAsset	unified_assets	统一素材	file_path, type, related_corpus_id
KnowledgeDocument	knowledge_documents	知识库文档	filename, status
Product/Order	products/orders	商品/订单	price, payment_status

4. 运行方式

• 开发环境：
  • Frontend: vite dev server.
  • Backend: nodemon / node index.js.
  • LangGraph: Python 环境运行 main.py.
• 端口配置 (【TBD】需查看配置文件确认具体端口号):
  • Frontend: 通常 3000 或 5173.
  • Backend: 通常 3001 或 8080.

5. 关键限制与风险点

• 本地依赖：剪映草稿导出功能强依赖于本地安装的剪映应用及其路径配置。
• 显存要求：若本地运行 ComfyUI，对 GPU 显存有较高要求。
• 外部 API 稳定性：Suno, Fish Audio 等服务依赖第三方 API 的稳定性及 Token 配额。

6. 校验清单 (Verification Checklist)

• [ ] 后端是否确实连接了 PostgreSQL？(需检查 config)
• [ ] 剪映服务是否依赖特定操作系统？(通常仅限 Windows/Mac)
• [ ] LangGraph Runner 是否独立部署？

---

最后更新时间：2025-12-21