# materials-workshop

**Repository Path**: albeline/materials-workshop

## Basic Information

- **Project Name**: materials-workshop
- **Description**: https://gitee.com/albeline/materials-workshop
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 素材工厂 — Materials Workshop

AI 驱动的电商视频素材生成平台。通过 6 步自动化工作流，从商品信息生成爆款视频脚本。

## 技术栈

- **框架**: Next.js 16 (App Router, Turbopack)
- **数据库**: SQLite + Prisma 7 (libsql adapter)
- **实时通信**: WebSocket (ws)
- **语言**: TypeScript 5

## 前置条件

- Node.js 20.9+
- pnpm 11+

## 安装

```bash
cd materials-workshop

# 安装依赖（首次需要批准构建脚本）
pnpm install
# 如遇 ERR_PNPM_IGNORED_BUILDS，执行：
pnpm approve-builds sharp unrs-resolver @prisma/engines prisma esbuild
pnpm install

# 初始化数据库（首次）
npx prisma migrate dev --name init

# 生成 Prisma Client
npx prisma generate
```

## 启动

项目需要同时运行两个服务，已聚合到单一命令：

```bash
pnpm dev
# → Next.js:  http://localhost:3000
# → WebSocket: ws://localhost:8080
```

如需单独启动：

```bash
# 仅 Next.js
pnpm dev:next

# 仅 WebSocket
pnpm dev:ws
```

### 端口说明

| 服务 | 端口 | 用途 |
|------|------|------|
| Next.js | 3000 | API 路由 + 前端页面 |
| WebSocket | 8080 | 工作流实时事件推送 |

## 架构

```
浏览器 (前端)
    │
    ├── HTTP REST → Next.js (3000)
    │                ├── /api/upload          图片上传
    │                ├── /api/workflow        工作流 CRUD
    │                └── /api/library/scripts 脚本库
    │
    └── WebSocket → WS Server (8080)
                     ├── subscribe   订阅工作流事件
                     ├── resync      断线重连同步状态
                     └── cancel      取消工作流

Next.js (3000) ── HTTP POST ──→ WS Server (8080)
                 /internal/broadcast
                 (引擎事件 → WS 客户端)

WS Server (8080) ── HTTP GET/DELETE ──→ Next.js (3000)
                  (resync/cancel 转发到 API)
```

## API 端点

| 方法 | 路由 | 用途 |
|------|------|------|
| `POST` | `/api/upload` | 上传商品图片 |
| `POST` | `/api/workflow` | 启动新工作流 |
| `GET` | `/api/workflow` | 列出所有工作流 |
| `GET` | `/api/workflow/[runId]` | 获取工作流详情 |
| `DELETE` | `/api/workflow/[runId]` | 取消工作流 |
| `POST` | `/api/workflow/[runId]/select` | 提交情报选择（恢复工作流） |
| `POST` | `/api/workflow/[runId]/retry` | 重试失败步骤 |
| `GET` | `/api/library/scripts` | 列出已保存脚本 |

## 工作流步骤

1. **爆款素材情报** — 搜索同类商品 TikTok 爆款视频 → 暂停等待用户选择
2. **目标受众分析** — 基于选中情报分析购买人群
3. **角色卡生成** — 生成匹配角色 + 形象图
4. **商品六视图** — 生成 6 个角度描述 + 图片
5. **多镜头视频脚本** — 生成 15s 中英文脚本（5 镜头）
6. **聚合输出** — 生成提示词框架，创建 Script 记录

## 测试

### 集成测试（WS + 引擎全链路）

```bash
# 确保两个服务都在运行，然后：
npx tsx scripts/test-ws.ts
```

测试覆盖：WS 连接订阅 → 创建工作流 → Step 1 暂停 → 用户选择 → Steps 2-6 自动执行 → 数据落库验证 → resync 同步。

### 手动 API 测试

```bash
# 创建工作流
curl -X POST http://localhost:3000/api/workflow \
  -H "Content-Type: application/json" \
  -d '{"productName":"LED灯带","imagePaths":[]}'

# 列出工作流
curl http://localhost:3000/api/workflow
```

## 数据库

```bash
# 可视化浏览数据（浏览器打开）
npx prisma studio

# 重新生成迁移
npx prisma migrate dev --name <描述>
```

## 项目结构

```
materials-workshop/
├── app/                          # Next.js App Router
│   ├── api/                      # API 路由
│   │   ├── upload/route.ts       #   图片上传
│   │   ├── workflow/             #   工作流 CRUD
│   │   └── library/scripts/      #   脚本库
│   ├── layout.tsx                # 根布局
│   └── page.tsx                  # 首页
├── lib/                          # 核心库
│   ├── db.ts                     #   Prisma Client 单例
│   ├── config.ts                 #   工作流配置常量
│   ├── ws/                       #   WebSocket 层
│   │   ├── ws-server.ts          #     WS 服务（独立进程）
│   │   ├── ws-broadcaster.ts     #     WS 侧房间管理
│   │   └── broadcaster.ts        #     引擎侧 HTTP 广播
│   └── workflow/                 #   工作流引擎
│       ├── engine.ts             #     引擎（6 步编排）
│       ├── manager.ts            #     全局实例管理
│       ├── types.ts              #     类型定义
│       └── steps/mock-data.ts    #     模拟数据（开发阶段）
├── prisma/
│   ├── schema.prisma             # 数据模型（8 个表）
│   └── migrations/               # 迁移文件
├── scripts/
│   └── test-ws.ts                # 集成测试脚本
├── .docs/                        # 项目文档
│   ├── 0.requirements.md         #   需求文档
│   ├── 1.tech-solution.md        #   技术方案
│   ├── 2.script-making-design.md #   功能设计（主文档）
│   ├── 2.script-making-frontend.md # 前端设计
│   ├── 2.script-making-backend.md  # 后端设计
│   ├── 3.project-structure.md    #   全链路架构
│   ├── 4.database-design.md      #   数据库设计
│   ├── .task/                    #   开发任务规划
│   └── .test/                    #   测试规划与记录
├── prisma.config.ts              # Prisma 7 配置
├── package.json
└── tsconfig.json
```

## 文档索引

| 文档 | 内容 |
|------|------|
| [需求文档](.docs/0.requirements.md) | 系统功能定义、AI 工作流描述 |
| [技术方案](.docs/1.tech-solution.md) | 技术选型、架构设计、成本估算 |
| [功能设计](.docs/2.script-making-design.md) | Use Case、流程图（导航到其他设计文档） |
| [前端设计](.docs/2.script-making-frontend.md) | 组件结构、状态管理、UI 流程 |
| [后端设计](.docs/2.script-making-backend.md) | API 设计、引擎架构、Provider 抽象 |
| [全链路架构](.docs/3.project-structure.md) | 端到端时序图、通信架构、WS 协议 |
| [数据库设计](.docs/4.database-design.md) | Prisma Schema、ER 图、字段说明 |