1390 lines
61 KiB
Markdown
1390 lines
61 KiB
Markdown
# 镭射卡功能重构技术方案（总方案）
|
||
|
||
> **文档版本：** v3.3
|
||
> **状态：** 待评审
|
||
> **创建日期：** 2026-05-25
|
||
> **更新日期：** 2026-05-27
|
||
> **所属项目：** TopFans 铸爱 — 镭射卡（Laser Card）
|
||
> **关联服务：** `assetService`（Dubbo-go）、`gateway`（Gin）、`frontend`（uni-app）
|
||
>
|
||
> **文档定位：** 本文档为镭射卡重构**唯一总方案**。实施、评审、DDL、接口均以本文为准。
|
||
> **辅助材料（非总方案，不重复维护表结构）：**
|
||
> - `docs/specs/2026-05-15-lenticular-card-multi-material-architecture-design.md` — 光栅多素材规范基线（只读参考）
|
||
> - `docs/specs/2026-05-24-rembg-segmentation-feasibility-study.md` — 通用抠图后续调研（本期不实施）
|
||
> - `docs/specs/2026-05-18-laser-card-refactor-design.md` — **已废止**，仅作历史 diff
|
||
|
||
### 文档目录
|
||
|
||
| 章节 | 内容 |
|
||
|---|---|
|
||
| §一～二 | 背景、现状与目标路径 |
|
||
| §三 | 魔搭抠图、Dify、**aiWorkflowService**、MiniMax 边界 |
|
||
| §四 | 整体逻辑架构 |
|
||
| §五 | 前端目录、**组件隔离**、**五图生成（无后端）** |
|
||
| §六 | 数据库完整设计（含 **§6.3.1 tags 约定，不新增列**） |
|
||
| §七 | 后端 API、铸造、页面职责、死代码 |
|
||
| §八～十 | 计划、风险、验收 |
|
||
| §十一 | 附录（预设种子、代码索引、**组件迁移步骤**） |
|
||
|
||
---
|
||
|
||
## 版本变更摘要
|
||
|
||
### v3.3（相对 v3.2）
|
||
|
||
| 变更项 | 说明 |
|
||
|---|---|
|
||
| 品类 / 工艺标识 | **不在 `assets` / `asset_registry` 新增列**；铸爱大类（星卡/吧唧/海报）与工艺小类（镭射/光栅等）统一写入既有 **`assets.tags`（JSONB 数组）** 约定字符串，见 §6.3.1 |
|
||
| 镭射铸造 tags | 铸造成功时 `tags` 必须含 **`cast:star_card`** + **`craft:laser`**（与光栅 `craft:lenticular` 对称） |
|
||
| 前端常量 | `castloveMintForm.js` 增加 `CAST_TAG_*` / `CRAFT_TAG_LASER`；`buildCastloveFormSnapshot` / `useLaserMint` 按工艺写入 |
|
||
| Phase 1 进度 | 前端已落地 `laser-thinking`、`laser-result`、`LaserVariantPyramid`、`useLaserBatchGenerate` 等；**tags 双写与多素材铸造**仍待 §十一附录 C 步 6 收尾 |
|
||
|
||
### v3.2（相对 v3.1）
|
||
|
||
| 变更项 | 说明 |
|
||
|---|---|
|
||
| 前端组件隔离 | 新增 §5.4 组件目录、职责、数据流、迁移步骤 |
|
||
| 五图生成说明 | 新增 §5.5：无后端接口、JPG 格式、Storage 协议 |
|
||
| AI 平台服务 | 新增 §3.5 `aiWorkflowService`（Dify/魔搭统一编排，供多模块接入） |
|
||
| Dify 工作流 | 新增 §3.6 镭射五图工作流 `laser_card_variants_v1` 节点级设计 |
|
||
|
||
### v3.0 相对 v2.0 的核心变更
|
||
|
||
| 变更项 | v2.0 | v3.0（本版） |
|
||
|---|---|---|
|
||
| 用户主路径 | `create` → **镭射工坊** `laser-card-studio` → 保存铸造 | `create` → **Thinking** → **五图选卡** → 铸造（与产品截图一致） |
|
||
| 五图生成 | 计划废弃 `laserBatchExport` | **保留并强化**五图批量合成；Phase 2 可迁 Dify 工作流 |
|
||
| 抠图 | 阿里云 IVPD | **魔搭社区 RMBG-2.0**（服务端代理） |
|
||
| 生成编排 | 未定义 | **Dify 工作流**（Phase 2 服务端五图生成；Phase 1 仍用客户端合成） |
|
||
| 铸造 | `craftMintSubmit` 多素材 | 同左；选卡后与光栅卡一致走 `estimateMintCost` + `ConfirmModal` |
|
||
| 草稿 / 转赠 | 已舍弃 | 继续舍弃 |
|
||
| 前端目录 | `pages/castlove/laser/laser-studio.vue` | `pages/castlove/laser/laser-thinking.vue` + `laser-result.vue`（对齐光栅 `lenticular/*`） |
|
||
|
||
---
|
||
|
||
## 一、背景与目标
|
||
|
||
### 1.1 项目背景
|
||
|
||
当前镭射卡存在以下问题：
|
||
|
||
| 问题 | 说明 |
|
||
|---|---|
|
||
| **双轨入口混乱** | 线上同时存在「工坊保存」与「生成五图选卡」两套入口，产品只保留后者，前者造成维护与安全风险 |
|
||
| **铸造链路落后** | 选卡结果页仍走单图 `material_url` + `createMintOrderApi`，未对齐光栅卡多素材模型 |
|
||
| **抠图不安全** | 客户端直连阿里云 IVPD，存在 AK 泄露风险 |
|
||
| **目录不规范** | 镭射逻辑散落在 `discover/generation-*` 与 `laser-card-studio`，未与光栅 `lenticular/*` 对仗 |
|
||
| **服务端无编排** | 五图合成纯客户端 Canvas，无法统一审计、限流与 A/B 预设 |
|
||
|
||
### 1.2 业务目标
|
||
|
||
- 用户路径与产品稿一致：**上传照片 → Thinking → 五图金字塔选卡 → 确认铸造**
|
||
- 铸造后资产可回溯 **source / cutout / backdrop / composite** 分层素材
|
||
- 与光栅卡体验一致：同一套「生成 → 选卡 → 费用确认 → 铸造成功」心智
|
||
- 为吧唧生成器等后续场景预留 `scene` 路由（魔搭抠图）
|
||
|
||
### 1.3 技术目标
|
||
|
||
| 目标 | 说明 |
|
||
|---|---|
|
||
| **路径收敛** | 下线镭射工坊；`create.vue` 镭射仅走 `startCraftGenerationFlow(STUDIO_LASER)` |
|
||
| **规范对齐** | 页面 `pages/castlove/laser/*`、组件 `components/laser/*`、铸造走 `craftMintSubmit.js` |
|
||
| **魔搭抠图** | 服务端代理魔搭 RMBG-2.0，客户端无密钥 |
|
||
| **Dify 编排** | Phase 2 将五图生成迁入 Dify Workflow；Phase 1 客户端 `laserBatchExport` 快速上线 |
|
||
| **2 周交付** | Phase 1 优先打通选卡 + 多素材铸造 + 魔搭抠图 |
|
||
|
||
### 1.4 本期明确不做
|
||
|
||
- ❌ 镭射工坊（`laser-card-studio.vue` 及入口 `handleSingleCraftLaserEntry`）
|
||
- ❌ **相册导出**：不提供「保存到相册 / 下载到本地」；**禁止** `uni.saveImageToPhotosAlbum` 及任何面向用户的导出能力（现工坊 `laser-card-studio` 中的保存相册逻辑一并删除）
|
||
- ❌ 草稿实例、转赠、领取中心、管理端模板 CRUD
|
||
- ❌ rembg 自建部署（见独立调研文档）
|
||
- ❌ 阿里云 IVPD 直连（客户端 AK 全部删除）
|
||
- ❌ 陀螺仪驱动镭射预览（晃动手机变光效）
|
||
|
||
**仍允许（非「相册导出」）：**
|
||
|
||
| 能力 | 说明 |
|
||
|---|---|
|
||
| 从相册**选图** | `create` 页 `chooseImage` 选用户照片作为输入，属于上传源，不是导出 |
|
||
| 离屏 Canvas **临时文件** | `laserBatchExport` → `canvasToTempFilePath` 仅用于五图候选与 **OSS 上传 / 铸造**，不对用户暴露「保存」 |
|
||
| WebGL **屏上动画** | `LaserPreviewCanvas` 仅页面内实时预览，不落相册 |
|
||
|
||
---
|
||
|
||
## 二、现状与目标路径对比
|
||
|
||
### 2.1 现状（As-Is）
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph online [线上实际可触达]
|
||
A[create.vue 点生成] --> B[startCraftGenerationFlow laser]
|
||
B --> C[generation-loading.vue]
|
||
C --> D[laserBatchExport 客户端5图]
|
||
D --> E[generation-result.vue 金字塔选卡]
|
||
E --> F[单图 OSS + createMintOrderApi]
|
||
end
|
||
subgraph dead [应下线]
|
||
G[create 或旧入口] --> H[laser-card-studio.vue 3600行]
|
||
H --> I[castloveAfterLaserMint 单图]
|
||
end
|
||
```
|
||
|
||
| 路径 | 入口 | 行为 | 处置 |
|
||
|---|---|---|---|
|
||
| **A. 五图选卡（保留）** | `create` → `startCraftGenerationFlow` | 客户端批量 5 预设 → `generation-result` | **主路径，重构增强** |
|
||
| **B. 镭射工坊（废弃）** | `handleSingleCraftLaserEntry` → `laser-card-studio` | WebGL 预览 + 单图铸造 | **删除** |
|
||
|
||
### 2.2 目标（To-Be）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as 用户
|
||
participant C as create.vue
|
||
participant T as laser-thinking.vue
|
||
participant R as laser-result.vue
|
||
participant API as Gateway
|
||
participant MS as 魔搭 RMBG
|
||
participant OSS as OSS
|
||
participant Mint as craftMintSubmit
|
||
|
||
U->>C: 上传照片 + 藏品信息 + 点「生成」
|
||
C->>T: startCraftGenerationFlow(STUDIO_LASER)
|
||
opt 智能抠图 Phase1可选
|
||
T->>API: POST /api/v1/segment scene=portrait
|
||
API->>MS: RMBG-2.0
|
||
MS-->>T: cutout_url
|
||
end
|
||
T->>T: 生成5张镭射变体 Phase1客户端 / Phase2 Dify
|
||
T->>R: 金字塔选卡 UI
|
||
U->>R: 选一张 + 开始铸造
|
||
R->>API: estimateMintCost
|
||
R->>U: ConfirmModal 水晶确认
|
||
U->>R: 确认
|
||
R->>OSS: 上传 source/cutout/backdrop/composite
|
||
R->>API: POST /laser/instances
|
||
R->>Mint: submitCraftMintFromPath 多素材
|
||
Mint-->>U: success 页
|
||
```
|
||
|
||
---
|
||
|
||
## 三、Dify + 魔搭 技术架构
|
||
|
||
### 3.1 职责划分
|
||
|
||
| 平台 | 职责 | 本期 |
|
||
|---|---|---|
|
||
| **魔搭社区 ModelScope** | 人像抠图（RMBG-2.0 等），输入 HTTP 图 URL，输出透明 PNG | **Phase 1 落地**（`POST /api/v1/segment`） |
|
||
| **Dify** | 镭射卡五图生成工作流编排：接收用户图 + 预设参数 → 调用合成/风格节点 → 输出 5 张图 OSS URL | **Phase 2 落地**；Phase 1 用客户端 `laserBatchExport` |
|
||
| **TopFans Gateway** | 鉴权、限流、审计、统一错误码；**不**向客户端暴露魔搭/Dify 密钥 | Phase 1 |
|
||
| **assetService** | 实例 CRUD、铸造编排、操作流水 | Phase 1 |
|
||
|
||
### 3.2 魔搭抠图（Segment Service）
|
||
|
||
**接口：** `POST /api/v1/segment`
|
||
**本期仅实现：** `scene=portrait` → 魔搭 `RMBG-2.0`（或团队已申请的同系列模型）
|
||
|
||
**推荐调用链：**
|
||
|
||
```
|
||
客户端 multipart 上传
|
||
→ Gateway segment_controller
|
||
→ 临时上传 OSS（或内存限制 3MB 直传魔搭）
|
||
→ ModelScope Inference API（服务端 AK）
|
||
→ 结果写入用户 OSS：laser-card/{star_id}/{user_id}/{date}/{uuid}_cutout.png
|
||
→ 返回 cutout_oss_key + cutout_url_signed
|
||
```
|
||
|
||
**降级：** 魔搭失败 / 超时 → `LC_SEGMENT_FAILED` → 前端椭圆 mask（与现 `laser-card-studio` 注释一致，逻辑迁到 `laser-thinking`）
|
||
|
||
**限流：** 单用户 10 次/分钟；单 IP 30 次/分钟
|
||
|
||
**`scene` 预留（本期返回 400）：** `bajis` / `sticker` / `portrait_hd` — 见 rembg 调研文档
|
||
|
||
### 3.3 Dify 镭射五图生成工作流（Phase 2）
|
||
|
||
**目标：** 将 `laserBatchExport.js` 的 5 预设合成迁到服务端，便于统一预设、监控与后续 AI 增强。
|
||
|
||
**建议工作流（Dify Workflow）：**
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
IN[输入: image_url, preset_codes, user_id] --> SEG{需要抠图?}
|
||
SEG -->|是| MS[HTTP: 魔搭 RMBG]
|
||
SEG -->|否| COMP[合成节点 x5]
|
||
MS --> COMP
|
||
COMP --> OSS[上传 OSS x5]
|
||
OSS --> OUT[输出: variant_urls 数组]
|
||
```
|
||
|
||
| 节点 | 说明 |
|
||
|---|---|
|
||
| **开始** | `image_url`、`preset_codes`（默认 5 个）、`use_cutout`（bool） |
|
||
| **条件分支** | `use_cutout=true` 时调魔搭（与 Segment 服务复用同一 HTTP 封装） |
|
||
| **代码/HTTP 节点** | 调用 TopFans 内部 `laser-compositor` 服务（Go 复刻 `PRESET_VARIANTS`）或 GPU 容器 |
|
||
| **结束** | `variants: [{ preset_id, oss_key, signed_url, width, height }]` |
|
||
|
||
**对外 API（Phase 2 新增）：**
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| POST | `/api/v1/laser/generate` | 创建五图生成任务（异步） |
|
||
| GET | `/api/v1/laser/generate/{job_id}` | 轮询状态；完成返回 5 张图 URL |
|
||
|
||
**Phase 1 不实现上述 API**，`laser-thinking` 继续调用 `generateLaserVariantBatch(imagePath, canvasId)`，与现网一致。
|
||
|
||
### 3.4 与现有 MiniMax 图生图接口的关系
|
||
|
||
| 接口 | 用途 | 镭射卡是否使用 |
|
||
|---|---|---|
|
||
| `POST /api/v1/assets/mints/image/generation` | 星卡等 **AI 文生图/图生图** 四宫格 | **否** |
|
||
| 镭射五图 | 本地 Canvas 合成（Phase 1）或 Dify（Phase 2） | **是** |
|
||
|
||
镭射卡**不**走 MiniMax `imageGenerationApi`，避免与星卡共用 Loading 页时逻辑混淆；Phase 1 镭射**不再进入** `discover/generation-loading`（见 §5.4）。
|
||
|
||
### 3.5 AI 编排服务（aiWorkflowService，Phase 2 起）
|
||
|
||
> **定位：** 平台级 AI 能力微服务，与 `laserService`（镭射业务实例）、`assetService`（铸造/素材）分离。Dify、魔搭等密钥**仅**在此服务内；业务方只认 `workflow_key` + `run_id`。
|
||
|
||
| 职责 | 说明 |
|
||
|---|---|
|
||
| 工作流注册 | `workflow_key` → Dify `app_id` / 版本 / 默认 inputs |
|
||
| 异步运行 | `CreateRun` / `GetRun` / `CancelRun` |
|
||
| Provider 适配 | Dify（编排）、魔搭（Segment / 可选图生图）、后续可收敛 MiniMax |
|
||
| 统一限流与审计 | 按 `user_id`、`workflow_key` 配额 |
|
||
|
||
**不负责：** 镭射实例 CRUD、水晶扣费、`materials` 写入（仍属 `laserService` / `assetService`）。
|
||
|
||
**Gateway 对外（建议）：**
|
||
|
||
| 方法 | 路径 | Phase |
|
||
|---|---|---|
|
||
| POST | `/api/v1/ai/runs` | P2 |
|
||
| GET | `/api/v1/ai/runs/:run_id` | P2 |
|
||
| POST | `/api/v1/segment` | P1（实现可暂放 Gateway，逻辑归属 ai 服务） |
|
||
|
||
**镭射五图 Phase 2：** `workflow_key = laser_card_variants_v1`，由 `useLaserBatchGenerate` 在开关打开时改为轮询 `/ai/runs`，关闭时仍走 §5.5 客户端 batch。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph biz [业务]
|
||
LT[laser-thinking]
|
||
LS[laserService]
|
||
AS[assetService]
|
||
end
|
||
subgraph ai [aiWorkflowService]
|
||
RUN[workflow_runs]
|
||
DIFY[Dify Adapter]
|
||
MS[ModelScope Adapter]
|
||
end
|
||
LT -->|P2 CreateRun| ai
|
||
LT -->|P1 batch 本地| LT
|
||
LS --> AS
|
||
ai --> DIFY
|
||
ai --> MS
|
||
```
|
||
|
||
### 3.6 Dify 工作流详设：`laser_card_variants_v1`（Phase 2）
|
||
|
||
> **原则：** Dify 只做**编排**；像素级镭射合成调内部 **laser-compositor** HTTP（Go 复刻 `laserBatchExport`），**不用**魔搭通用图生图替代 compositor（效果不可控，见评审结论）。
|
||
|
||
**工作流类型：** Workflow（API 触发，非 Chatbot）
|
||
|
||
**开始节点 — 输入变量：**
|
||
|
||
| 变量 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `source_image_url` | string | ✅ | 用户原图可访问 URL（OSS 签名） |
|
||
| `use_cutout` | boolean | ✅ | 是否人像抠图 |
|
||
| `preset_codes` | array[string] | 否 | 默认 `["dream","classic","holoFull","ice","sunset"]` |
|
||
| `star_id` / `user_id` | number | ✅ | 隔离与审计 |
|
||
| `export_width` / `export_height` | number | 否 | 默认 1080 / 1440 |
|
||
|
||
**节点链路：**
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
START[开始] --> NORM[代码: 补全 preset + render_config]
|
||
NORM --> BR{use_cutout?}
|
||
BR -->|是| SEG[HTTP POST TopFans /segment]
|
||
BR -->|否| LOOP[循环 preset_codes]
|
||
SEG --> SEGF{成功?}
|
||
SEGF -->|否| WARN[warnings += SEGMENT_FAILED]
|
||
SEGF -->|是| LOOP
|
||
WARN --> LOOP
|
||
LOOP --> COMP[HTTP POST laser-compositor /compose]
|
||
COMP --> AGG[代码: 聚合 variants]
|
||
AGG --> END[结束 JSON]
|
||
```
|
||
|
||
| 步骤 | 节点 | 说明 |
|
||
|---|---|---|
|
||
| 1 | 代码 | `preset_codes` 为空则填默认 5 个；展开为带 `render_config` 的列表（与 `laserPresets.js` / DB 模板一致） |
|
||
| 2 | 条件 | `use_cutout=true` → HTTP `POST /api/v1/segment`（`scene=portrait`），失败**不中断**，`cutout_url=""` 并记 warning |
|
||
| 3 | 循环 | 对每个 preset 调 `POST /v1/compose`（或一次 `POST /v1/compose/batch`） |
|
||
| 4 | 结束 | 输出统一 JSON（见下） |
|
||
|
||
**结束节点 — 输出 JSON：**
|
||
|
||
```json
|
||
{
|
||
"workflow_key": "laser_card_variants_v1",
|
||
"status": "succeeded",
|
||
"cutout_oss_key": "",
|
||
"variants": [
|
||
{
|
||
"preset_id": "holoFull",
|
||
"oss_key": "laser-card/.../variant_holoFull.jpg",
|
||
"signed_url": "https://...",
|
||
"width": 1080,
|
||
"height": 1440
|
||
}
|
||
],
|
||
"warnings": [],
|
||
"engine_version": "compositor-1.0.0"
|
||
}
|
||
```
|
||
|
||
`aiWorkflowService` 将 outputs 写入 `ai_workflow_runs`，`laser-thinking` / `useLaserBatchGenerate` 轮询完成后写入 `GENERATED_IMAGES_KEY`（URL 数组，与 Phase 1 本地 path 数组对前端透明）。
|
||
|
||
---
|
||
|
||
## 四、整体逻辑架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 客户端 (uni-app) │
|
||
│ create.vue ──► laser-thinking.vue ──► laser-result.vue │
|
||
│ │ │ │ │
|
||
│ │ laserBatchExport (P1) │ craftMintSubmit │
|
||
│ │ Dify job poll (P2) │ │
|
||
└───────┼──────────────┼──────────────────────┼─────────────────┘
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ API Gateway (Gin) │
|
||
│ /api/v1/segment 魔搭抠图代理 │
|
||
│ /api/v1/laser/templates 模板/预设只读 │
|
||
│ /api/v1/laser/instances 实例创建/查询 │
|
||
│ /api/v1/laser/instances/:id/mint │
|
||
│ /api/v1/assets/* 复用 OSS 签名、素材、铸造估价 │
|
||
└───────────────────────────────┬─────────────────────────────┘
|
||
│ Dubbo
|
||
┌───────────────────────────────▼─────────────────────────────┐
|
||
│ assetService │
|
||
│ LaserCardService │ MaterialService │ MintService │
|
||
└───────────────────────────────┬─────────────────────────────┘
|
||
│
|
||
┌───────────────┬───────────────┬───────────────────┐
|
||
▼ ▼ ▼
|
||
PostgreSQL 阿里云 OSS aiWorkflowService (P2)
|
||
laser_* 三表 素材与成品图 Dify + 魔搭
|
||
```
|
||
|
||
---
|
||
|
||
## 五、前端架构（目录、组件隔离、五图生成）
|
||
|
||
### 5.1 目录对仗（页面 + 组件 + composable）
|
||
|
||
| 光栅卡（基线） | 镭射卡（目标） |
|
||
|---|---|
|
||
| `pages/castlove/create.vue`（分流） | 同左，`studioKind=laser` → `laser-thinking` |
|
||
| `pages/castlove/lenticular/lenticular-thinking.vue` | **`pages/castlove/laser/laser-thinking.vue`** |
|
||
| `pages/castlove/lenticular/lenticular-result.vue` | **`pages/castlove/laser/laser-result.vue`** |
|
||
| `components/lenticular/LenticularCard.vue` | **`components/laser/LaserPreviewCanvas.vue`**（动态预览） |
|
||
| — | **`components/laser/LaserVariantPyramid.vue`**（五图金字塔） |
|
||
| — | **`components/laser/LaserVariantThumb.vue`**（静态缩略图） |
|
||
| — | **`components/laser/LaserBatchCanvasHost.vue`**（离屏 batch canvas） |
|
||
| `composables/useLenticularCraftTiltPreview.js` | **`composables/useLaserPreview.js`**（WebGL/2D 动画） |
|
||
| — | **`composables/useLaserBatchGenerate.js`**（五图 batch + Storage） |
|
||
| — | **`composables/useLaserResultSelection.js`**（选中 ↔ preset ↔ 铸造 path） |
|
||
| — | **`composables/useLaserMint.js`**（估价 + ConfirmModal + craftMintSubmit） |
|
||
| — | **`composables/useLaserSegment.js`**（魔搭抠图，P1 可选） |
|
||
| `utils/craftMintSubmit.js` | **直接复用**，扩展 `material_type` |
|
||
| `utils/lenticular-engine.js` | **`utils/laser-card/laserBatchExport.js`**、`laserPreviewWebgl.js`、**`laserPresets.js`** |
|
||
|
||
### 5.2 路由与 Storage 约定
|
||
|
||
| Key / 常量 | 说明 |
|
||
|---|---|
|
||
| `GENERATION_FLOW_KEY` + `FLOW_MODE_LASER` | 不变；`navigateToStudioLoading` 改为跳转 `/pages/castlove/laser/laser-thinking` |
|
||
| `GENERATED_IMAGES_KEY` | 存 5 张变体本地路径或 URL |
|
||
| `GENERATION_RESULT_META_KEY` | `{ displayMode: 'laser', imageCount: 5, selectedPresetId }` |
|
||
| `CASTLOVE_FORM_KEY` | 与光栅共用表单快照 |
|
||
| `CASTLOVE_LASER_ENTRY_KEY` | **删除**（工坊专用） |
|
||
|
||
### 5.3 强制原则
|
||
|
||
1. 镭射**禁止**新增 `laser-card-studio.vue` 路由与 pages.json 注册
|
||
2. **`discover/generation-loading`、`generation-result` 不得再含镭射 `v-if` 分支**；镭射仅走 `pages/castlove/laser/*`
|
||
3. 页面**薄编排**：`laser-thinking` / `laser-result` 各 **< 200 行**，业务在 `components/laser` + composable
|
||
4. 素材绑定**必须**经 `uploadMaterialApi` + `bindAssetMaterialsApi`
|
||
5. 选卡页铸造**必须**与光栅一致：`estimateMintCostApi` → `ConfirmModal` → `submitCraftMintFromPath`
|
||
6. **禁止** `uni.saveImageToPhotosAlbum`（见 §1.4）
|
||
7. 铸造时 `assets.tags` 写入 **`cast:star_card`**（铸爱大类）+ **`craft:laser`**（工艺小类）；**禁止**为品类/工艺新增 `cast_category` / `craft_type` 列（见 §6.3.1）
|
||
8. `material_type` 仍为表单「素材类型」文案（如粉丝自制），**不等于** 工艺；工艺只认 `tags` 中 `craft:*`
|
||
|
||
### 5.4 前端组件隔离设计
|
||
|
||
#### 5.4.1 隔离原则
|
||
|
||
| 原则 | 做法 |
|
||
|---|---|
|
||
| 按工艺分包 | 镭射 UI 仅在 `components/laser/`，不 import `components/lenticular/*` |
|
||
| 引擎与 UI 分离 | Canvas/WebGL 在 `utils/laser-card/`；组件只通过 composable 调用 |
|
||
| 预览动 / 铸造静 | 动画仅 `LaserPreviewCanvas`；铸造用 batch 静态 JPG（§5.5） |
|
||
| 与 discover 脱钩 | 星卡/AI 四图仍用 `generation-loading`；镭射已迁出 |
|
||
|
||
#### 5.4.2 组件与 composable 职责
|
||
|
||
| 模块 | 职责 | 禁止包含 |
|
||
|---|---|---|
|
||
| **LaserBatchCanvasHost** | 隐藏 `canvas-id="laserBatchCanvas"` | 业务逻辑、进度 UI |
|
||
| **useLaserBatchGenerate** | 调 `generateLaserVariantBatch` → `persistLaserPreviewImages` | HTTP 五图接口（P1 无） |
|
||
| **LaserPreviewCanvas** | 单 WebGL/2D 实例，`u_time` 驱动动画 | 陀螺仪、保存相册 |
|
||
| **useLaserPreview** | RAF 生命周期、preset 切换、降级 | 铸造、OSS |
|
||
| **LaserVariantPyramid** | 金字塔布局、`getCardStyle`、选中态；中央 slot 放 Preview | batch 合成 |
|
||
| **LaserVariantThumb** | 单张静态 `<image>` | 动画 |
|
||
| **useLaserResultSelection** | `selectedIndex` ↔ `presetId` ↔ `paths[i]` | 扣费 |
|
||
| **useLaserMint** | `estimateMintCost` + `ConfirmModal` + `submitCraftMintFromPath` | 五图生成 |
|
||
| **useLaserSegment** | `POST /segment`（可选） | 实例写库 |
|
||
|
||
#### 5.4.3 页面编排（薄层）
|
||
|
||
**`laser-thinking.vue`**
|
||
|
||
```
|
||
LaserThinkingShell（礼盒 + 进度 + "Thinking"，从 generation-loading 抽取）
|
||
└── LaserBatchCanvasHost
|
||
onMounted → useLaserBatchGenerate().run() → navigateTo laser-result
|
||
```
|
||
|
||
**`laser-result.vue`**
|
||
|
||
```
|
||
LaserCraftRewardBanner（可选）
|
||
LaserVariantPyramid(:paths :selected @select)
|
||
└── #hero → LaserPreviewCanvas(:source-path :preset :paused)
|
||
底部：重新生成 | 选择作品
|
||
ConfirmModal ← useLaserMint
|
||
```
|
||
|
||
#### 5.4.4 组件数据流
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph pages [pages/castlove/laser]
|
||
TH[laser-thinking]
|
||
RS[laser-result]
|
||
end
|
||
subgraph comp [components/laser]
|
||
BH[LaserBatchCanvasHost]
|
||
PV[LaserPreviewCanvas]
|
||
PY[LaserVariantPyramid]
|
||
end
|
||
subgraph hooks [composables]
|
||
BG[useLaserBatchGenerate]
|
||
LP[useLaserPreview]
|
||
SEL[useLaserResultSelection]
|
||
MT[useLaserMint]
|
||
end
|
||
subgraph util [utils/laser-card]
|
||
BE[laserBatchExport]
|
||
WG[laserPreviewWebgl]
|
||
end
|
||
|
||
TH --> BG --> BE
|
||
TH --> BH
|
||
RS --> PY --> PV
|
||
PV --> LP --> WG
|
||
RS --> SEL --> MT
|
||
```
|
||
|
||
#### 5.4.5 与共享模块边界
|
||
|
||
| 模块 | 关系 |
|
||
|---|---|
|
||
| `castloveGenerationFlow.js` | `navigateToStudioLoading('laser')` → **`/pages/castlove/laser/laser-thinking`** |
|
||
| `create.vue` | 仅 `startCraftGenerationFlow(STUDIO_LASER)`，不 import `components/laser` |
|
||
| `craftMintSubmit.js` | 扩展多素材；由 `useLaserMint` 调用 |
|
||
|
||
### 5.5 五图生成（Phase 1：无后端接口）
|
||
|
||
> **结论：** 五图**不调用** TopFans 后端生成接口；与星卡 `POST /api/v1/assets/mints/image/generation`（MiniMax）完全分离。
|
||
|
||
#### 5.5.1 调用链
|
||
|
||
```
|
||
create.vue → startCraftGenerationFlow(STUDIO_LASER)
|
||
→ CASTLOVE_FORM_KEY + GENERATION_FLOW_KEY { mode: 'laser' }
|
||
→ laser-thinking.vue
|
||
→ useLaserBatchGenerate.run()
|
||
→ generateLaserVariantBatch(imagePath, 'laserBatchCanvas')
|
||
→ persistLaserPreviewImages(paths)
|
||
→ laser-result.vue 读取 GENERATED_IMAGES_KEY
|
||
```
|
||
|
||
**输入：** `formData.image` 或 `formData.uploadedImage`（`chooseImage` 本地路径，非 URL）
|
||
|
||
**核心实现：** `frontend/utils/laser-card/laserBatchExport.js` — 循环 5 次 `PRESET_VARIANTS`，2D Canvas 合成（底纹 + 人像 + 镭射叠层）
|
||
|
||
#### 5.5.2 输出格式
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| API | **无**；仅 `uni.canvasToTempFilePath` |
|
||
| 文件类型 | JPEG（`fileType: 'jpg'`, `quality: 0.96`） |
|
||
| 逻辑尺寸 | 450 × 600 |
|
||
| 输出像素 | 900 × 1200（`destWidth/Height = 2×`） |
|
||
| 返回类型 | `string[]` 本地临时路径 |
|
||
|
||
#### 5.5.3 Storage 协议
|
||
|
||
| Key | 内容 |
|
||
|---|---|
|
||
| `generated_images` | `JSON.stringify(["path0","path1",...])` |
|
||
| `generation_result_meta` | `{"displayMode":"laser","imageCount":5}` |
|
||
| `castlove_form_data` | 铸造前保留；含 `image` / `uploadedImage` 等 |
|
||
|
||
**五图阶段不上传 OSS**；选卡确认铸造后再 `getOssSignatureApi` 上传。
|
||
|
||
#### 5.5.4 与动画预览的关系
|
||
|
||
| 用途 | 实现 |
|
||
|---|---|
|
||
| 用户看到的「会动的镭射」 | `LaserPreviewCanvas`（WebGL，`laserPreviewWebgl.js`） |
|
||
| 选卡/铸造用的图 | batch 生成的 **静态 JPG**（`paths[selectedIndex]`） |
|
||
|
||
切换缩略图时：更新 Preview 的 `preset`（光效变），铸造仍绑定对应静态文件。
|
||
|
||
#### 5.5.5 Phase 2 切换点
|
||
|
||
`useLaserBatchGenerate` 内根据 `feature_laser_dify_compose`：
|
||
|
||
- `false`（默认）：§5.5.1 客户端 batch
|
||
- `true`：`POST /api/v1/ai/runs` + 轮询 → `variants[].signed_url` 写入 `GENERATED_IMAGES_KEY`
|
||
|
||
---
|
||
|
||
## 六、数据库设计（完整）
|
||
|
||
> **设计原则**
|
||
> 1. **本期仅新增 3 张镭射业务表**；素材主数据与资产绑定**完全复用**既有 `materials` + `asset_material_relations`。
|
||
> 2. **禁止**新增 `laser_card_instance_materials` 中间表；铸造前临时素材仅存 `laser_card_instances.materials_snapshot`（JSONB）。
|
||
> 3. **禁止**在 `laser_card_service` 内私写 `materials` / `asset_material_relations` SQL；铸造成功后统一走既有 `MaterialService.UploadMaterial` + `BindAssetMaterials` RPC。
|
||
> 4. 旧版单图镭射资产仍可读 `assets.material_url`；新资产以 `asset_material_relations` 为准。
|
||
> 5. **品类（星卡/吧唧/海报）与工艺（镭射/光栅等）本期不新增 DDL 列**；统一用既有 **`assets.tags`（JSONB）** 约定前缀 `cast:*` / `craft:*`（§6.3.1）。若未来按大类高频筛选成为瓶颈，再单独立项增加 `cast_category` 列并自 `tags` 回填。
|
||
|
||
### 6.1 表清单与职责
|
||
|
||
| 表名 | 类型 | 职责 |
|
||
|---|---|---|
|
||
| `laser_card_templates` | **新增** | 镭射预设模板（5 条种子，只读） |
|
||
| `laser_card_instances` | **新增** | 用户一次「选卡→铸造」业务实例 |
|
||
| `laser_card_operation_logs` | **新增** | 实例写操作审计流水 |
|
||
| `materials` | **复用** | 素材文件元数据（OSS key、hash、尺寸） |
|
||
| `asset_material_relations` | **复用** | 资产 ↔ 素材角色绑定（`main`/`source`/`cutout`/`backdrop`） |
|
||
| `assets` | **复用** | 铸造产出的藏品主表 |
|
||
| `mint_orders` | **复用** | 铸造订单、水晶扣费 |
|
||
| `users` | **复用** | `owner_user_id` 逻辑关联（库内可不建物理 FK） |
|
||
| `stars` | **复用** | `star_id` 多星隔离 |
|
||
|
||
**明确不建表：** `laser_card_instance_materials`、`laser_card_drafts`、`laser_card_transfers`。
|
||
|
||
### 6.2 全库 ER 关系
|
||
|
||
```mermaid
|
||
erDiagram
|
||
laser_card_templates ||--o{ laser_card_instances : "1:N template_id"
|
||
laser_card_instances ||--o{ laser_card_operation_logs : "1:N instance_id"
|
||
laser_card_instances }o--o| assets : "0..1 asset_id"
|
||
laser_card_instances }o--o| mint_orders : "0..1 mint_order_id"
|
||
assets ||--o{ asset_material_relations : "1:N asset_id"
|
||
materials ||--o{ asset_material_relations : "1:N material_id"
|
||
|
||
laser_card_templates {
|
||
bigint id PK
|
||
varchar template_code UK
|
||
jsonb render_config
|
||
jsonb backdrop_options
|
||
}
|
||
laser_card_instances {
|
||
bigint id PK
|
||
varchar instance_no UK
|
||
varchar instance_ulid UK
|
||
bigint template_id FK
|
||
bigint owner_user_id
|
||
bigint star_id
|
||
varchar status
|
||
jsonb materials_snapshot
|
||
bigint asset_id FK
|
||
varchar mint_order_id FK
|
||
}
|
||
laser_card_operation_logs {
|
||
bigint id PK
|
||
bigint instance_id FK
|
||
varchar action
|
||
}
|
||
assets {
|
||
bigint id PK
|
||
bigint owner_uid
|
||
varchar cover_url
|
||
varchar material_url
|
||
jsonb tags
|
||
}
|
||
materials {
|
||
bigint id PK
|
||
varchar oss_key UK
|
||
varchar hash
|
||
}
|
||
asset_material_relations {
|
||
bigint id PK
|
||
bigint asset_id FK
|
||
bigint material_id FK
|
||
varchar material_type UK
|
||
int layer_order UK
|
||
}
|
||
mint_orders {
|
||
varchar order_id PK
|
||
bigint user_id
|
||
bigint asset_id
|
||
}
|
||
```
|
||
|
||
### 6.3 表间关系说明（基数 + 关联键 + 时机）
|
||
|
||
| 关系 | 基数 | 关联字段 | 写入时机 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `templates` → `instances` | 1 : N | `instances.template_id` → `templates.id` | `POST /laser/instances` | 用户选中的预设；`template_code` / `template_version` 冗余便于列表查询 |
|
||
| `instances` → `operation_logs` | 1 : N | `logs.instance_id` → `instances.id` | 每次写实例 | 只追加，不更新 |
|
||
| `instances` → `assets` | N : 0..1 | `instances.asset_id` → `assets.id` | `POST .../mint` 成功 | 铸造前 `asset_id` 为 NULL |
|
||
| `instances` → `mint_orders` | N : 0..1 | `instances.mint_order_id` → `mint_orders.order_id` | 发起铸造时 | 与光栅共用 `InitMintOrder` 返回的 `order_id` |
|
||
| `assets` → `asset_material_relations` | 1 : N | `amr.asset_id` → `assets.id` | 铸造成功事务末 | **仅**在 `status=minted` 后写入 |
|
||
| `materials` → `asset_material_relations` | 1 : N | `amr.material_id` → `materials.id` | 同上 | 同一 `oss_key` 可对应一条 `materials` 行 |
|
||
| `instances.materials_snapshot` | — | JSONB 内 `oss_key` | `POST /instances` | 铸造前**唯一**素材暂存；不指向 `materials.id` |
|
||
| `instances` → `users` | N : 1 | `owner_user_id` | 创建实例 | 鉴权：`owner_user_id = JWT user_id` |
|
||
| `instances` → `stars` | N : 1 | `star_id` | 创建实例 | 与 Attachment `star_id` 一致 |
|
||
|
||
**与旧字段兼容：**
|
||
|
||
| 字段 | 新镭射资产 | 旧镭射资产（单图） |
|
||
|---|---|---|
|
||
| `assets.cover_url` | = 选中 `composite` 的 CDN URL | 同 |
|
||
| `assets.material_url` | 可写 composite URL 作降级 | **唯一**素材来源 |
|
||
| `assets.tags` | 含 **`cast:star_card`** + **`craft:laser`** | 可能仅 `craft:laser` 或为空；读路径需兼容 |
|
||
| `GetAssetMaterials` | 4 条 `amr` | 空则降级读 `material_url` |
|
||
|
||
### 6.3.1 `assets.tags` 品类与工艺约定（本期不新增列）
|
||
|
||
> **决策（v3.3）：** 铸爱「大类」与「工艺小类」均写入 **`assets.tags`**，与现网光栅 `craft:lenticular` 一致；**不**在 `assets` / `asset_registry` 增加 `cast_category`、`craft_type` 等列。
|
||
|
||
#### 6.3.1.1 与 `star_id` / `material_type` 的区分
|
||
|
||
| 字段 / 概念 | 含义 | 镭射卡示例 |
|
||
|---|---|---|
|
||
| `assets.star_id` | 所属**明星/星球**（多星隔离） | `1001` |
|
||
| `assets.material_type`（可选列） | 表单「素材类型」**文案**（粉丝自制等） | `粉丝自制` |
|
||
| `tags` 中 `cast:*` | 铸爱**大类**：星卡 / 吧唧 / 海报 | `cast:star_card` |
|
||
| `tags` 中 `craft:*` | **工艺小类**：镭射 / 光栅 / 拍立得等 | `craft:laser` |
|
||
| `laser_card_instances.template_code` | 五套**预设**（dream/classic/…） | `holoFull` |
|
||
|
||
#### 6.3.1.2 约定枚举（常量须在前后端统一定义）
|
||
|
||
**大类 `cast:*`（与 `craft-select.vue` 左侧分类对齐）：**
|
||
|
||
| tag 值 | 产品名 |
|
||
|---|---|
|
||
| `cast:star_card` | 星卡 |
|
||
| `cast:badge` | 吧唧 |
|
||
| `cast:poster` | 海报 |
|
||
|
||
**工艺 `craft:*`（与工艺卡片对齐）：**
|
||
|
||
| tag 值 | 产品名 | 现网写入情况 |
|
||
|---|---|---|
|
||
| `craft:laser` | 镭射卡 | Phase 1 铸造时**必须**写入 |
|
||
| `craft:lenticular` | 光栅卡 | 已写入（`castloveMintForm.js`） |
|
||
| `craft:polaroid` | 拍立得 | 待产品开通时写入 |
|
||
| `craft:tear_off` | 撕拉片 | 待产品开通时写入 |
|
||
| `craft:plain` | 普通单图星卡（无特殊工艺） | 可选 |
|
||
|
||
**镭射卡铸造成功时 `tags` 示例：**
|
||
|
||
```json
|
||
["cast:star_card", "craft:laser"]
|
||
```
|
||
|
||
**光栅卡对照：**
|
||
|
||
```json
|
||
["cast:star_card", "craft:lenticular"]
|
||
```
|
||
|
||
#### 6.3.1.3 写入时机与链路
|
||
|
||
| 阶段 | 写入位置 | 说明 |
|
||
|---|---|---|
|
||
| create / 选卡页 | `CASTLOVE_FORM_KEY` 快照字段 `tags: string[]` | `buildCastloveFormSnapshot` 或镭射专用快照按 `pageName` / 工艺注入 |
|
||
| `POST /api/v1/assets/mints` | `CreateMintOrderRequest.tags` → `mint_service` → `assets.tags` | 与光栅相同，**铸造事务内**落库 |
|
||
| `laser_card_instances` | **不重复存 tags** | 工艺由业务表 + 关联 `assets` 表达；实例表只存 `template_code`、`materials_snapshot` |
|
||
|
||
**前端常量（`frontend/utils/castloveMintForm.js`）：**
|
||
|
||
```javascript
|
||
export const CAST_TAG_STAR_CARD = 'cast:star_card'
|
||
export const CAST_TAG_BADGE = 'cast:badge'
|
||
export const CAST_TAG_POSTER = 'cast:poster'
|
||
export const CRAFT_TAG_LASER = 'craft:laser'
|
||
// 已有：export const CRAFT_TAG_LENTICULAR = 'craft:lenticular'
|
||
```
|
||
|
||
**`buildCastloveFormSnapshot` 规则（摘要）：**
|
||
|
||
- 从 `craft-select` 进入且大类为星卡、工艺为镭射：`tags = [CAST_TAG_STAR_CARD, CRAFT_TAG_LASER]`
|
||
- 光栅：`tags = [CAST_TAG_STAR_CARD, CRAFT_TAG_LENTICULAR]`（在现有仅 `craft:lenticular` 基础上**补** `cast:star_card`）
|
||
- 禁止把 `craft_name` 中文名（如「镭射卡」）直接写入 `tags`
|
||
|
||
#### 6.3.1.4 查询与索引
|
||
|
||
**推荐 SQL（与画廊光栅判断一致）：**
|
||
|
||
```sql
|
||
-- 是否镭射工艺
|
||
(a.tags @> '["craft:laser"]') AS is_laser
|
||
|
||
-- 是否星卡大类下的藏品（可选，用于广场/星册筛大类）
|
||
(a.tags @> '["cast:star_card"]') AS is_star_card_cast
|
||
```
|
||
|
||
**本期不强制** 为 `tags` 建 GIN 索引；若 `cast:*` / `craft:*` 筛选 QPS 升高，再评估：
|
||
|
||
```sql
|
||
CREATE INDEX idx_assets_tags_gin ON assets USING GIN (tags) WHERE deleted_at IS NULL;
|
||
```
|
||
|
||
**明确不做：**
|
||
|
||
- 不在 `asset_registry` 冗余 `cast_category`（避免双写）；星册按大类筛时 JOIN `assets` 或读 API 层聚合。
|
||
- 不用 `tags` 存五图预设 id（预设走 `laser_card_instances.template_code` / `GENERATION_RESULT_META_KEY.selectedPresetId`）。
|
||
|
||
#### 6.3.1.5 历史数据与兼容
|
||
|
||
| 数据 | 读逻辑 |
|
||
|---|---|
|
||
| 仅有 `craft:lenticular` | 视为工艺光栅；大类可推断为 `cast:star_card`（仅展示层，不回填库表除非做迁移脚本） |
|
||
| `tags` 为空的老镭射单图 | `GetAssetMaterials` 空则降级 `material_url`；**不**根据 tags 阻断展示 |
|
||
| 回填（可选运维脚本） | `UPDATE assets SET tags = tags \|\| '"cast:star_card"'::jsonb WHERE ...` 需谨慎去重 |
|
||
|
||
### 6.4 复用表结构（实施须对齐现网）
|
||
|
||
#### 6.4.0 `assets.tags`（已上线，本期扩展约定即可）
|
||
|
||
```sql
|
||
-- 来源：docker/init-db.sql
|
||
tags jsonb -- 字符串数组，如 ["cast:star_card","craft:laser"]
|
||
```
|
||
|
||
| 属性 | 说明 |
|
||
|---|---|
|
||
| 类型 | JSONB，元素为 `string` |
|
||
| 本期变更 | **无 DDL**；仅扩展写入约定（§6.3.1） |
|
||
| 与迁移关系 | `migrate_laser_card_v3_tables.sql` **不包含** `ALTER TABLE assets ADD COLUMN` |
|
||
|
||
#### 6.4.1 `materials`（素材主表，已上线）
|
||
|
||
```sql
|
||
-- 来源：docker/init-db.sql V6 / supabase/migrations/20260515_*
|
||
CREATE TABLE materials (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
oss_key VARCHAR(255) NOT NULL,
|
||
original_name VARCHAR(255) NOT NULL,
|
||
file_size BIGINT NOT NULL,
|
||
mime_type VARCHAR(100) NOT NULL,
|
||
width INT,
|
||
height INT,
|
||
hash VARCHAR(64) NOT NULL,
|
||
created_by BIGINT NOT NULL,
|
||
star_id BIGINT NOT NULL DEFAULT 0,
|
||
created_at BIGINT NOT NULL,
|
||
updated_at BIGINT NOT NULL,
|
||
deleted_at BIGINT
|
||
);
|
||
CREATE UNIQUE INDEX uk_materials_oss_key ON materials(oss_key);
|
||
CREATE INDEX idx_materials_hash ON materials(hash);
|
||
CREATE INDEX idx_materials_created_by ON materials(created_by);
|
||
CREATE INDEX idx_materials_star_id ON materials(star_id);
|
||
```
|
||
|
||
| 字段 | 类型 | 镭射卡用途 |
|
||
|---|---|---|
|
||
| `oss_key` | VARCHAR(255) UK | `laser-card/{star_id}/{user_id}/{date}/{uuid}_{role}.ext` |
|
||
| `hash` | VARCHAR(64) | 客户端 SHA256，用于去重与幂等 |
|
||
| `created_by` | BIGINT | = `owner_user_id` |
|
||
| `star_id` | BIGINT | 多星隔离 |
|
||
|
||
#### 6.4.2 `asset_material_relations`（资产-素材关联，已上线）
|
||
|
||
```sql
|
||
CREATE TABLE asset_material_relations (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
asset_id BIGINT NOT NULL,
|
||
material_id BIGINT NOT NULL,
|
||
material_type VARCHAR(50) NOT NULL,
|
||
layer_order INT NOT NULL DEFAULT 0,
|
||
pos_x DOUBLE PRECISION,
|
||
pos_y DOUBLE PRECISION,
|
||
opacity DOUBLE PRECISION DEFAULT 1.0,
|
||
rotation DOUBLE PRECISION DEFAULT 0,
|
||
scale_x DOUBLE PRECISION DEFAULT 1.0,
|
||
scale_y DOUBLE PRECISION DEFAULT 1.0,
|
||
version INT NOT NULL DEFAULT 1,
|
||
created_at BIGINT NOT NULL,
|
||
updated_at BIGINT NOT NULL,
|
||
deleted_at BIGINT
|
||
);
|
||
ALTER TABLE asset_material_relations
|
||
ADD CONSTRAINT fk_amr_material
|
||
FOREIGN KEY (material_id) REFERENCES materials(id) ON DELETE RESTRICT;
|
||
-- asset_id → assets(id) ON DELETE CASCADE 以现网 migration 为准
|
||
|
||
CREATE INDEX idx_amr_asset_id ON asset_material_relations(asset_id) WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_amr_material_id ON asset_material_relations(material_id) WHERE deleted_at IS NULL;
|
||
CREATE UNIQUE INDEX uk_amr_asset_type_active
|
||
ON asset_material_relations(asset_id, material_type) WHERE deleted_at IS NULL;
|
||
CREATE UNIQUE INDEX uk_amr_asset_layer_active
|
||
ON asset_material_relations(asset_id, layer_order) WHERE deleted_at IS NULL;
|
||
```
|
||
|
||
**镭射卡 `material_type` 与 `layer_order`（铸造成功后写入）：**
|
||
|
||
| material_type | layer_order | 对应 snapshot.role | 说明 |
|
||
|---|---|---|---|
|
||
| `backdrop` | 0 | `backdrop` | 最底层：液态底纹 |
|
||
| `source` | 1 | `source` | 用户原图（可选展示） |
|
||
| `cutout` | 2 | `cutout` | 魔搭抠图 PNG；无抠图时可省略该行 |
|
||
| `main` | 3 | `composite` | 用户选中的五图之一，**封面** |
|
||
|
||
> 光栅卡使用 `main`(1) + `bg`(0)；镭射与光栅 **material_type 不混用**于同一资产。
|
||
> 常量须定义在 `backend/pkg/models/material.go`，禁止业务层硬编码字符串。
|
||
|
||
#### 6.4.3 `assets` / `mint_orders`（逻辑关联）
|
||
|
||
| 表 | 镭射关联字段 | 说明 |
|
||
|---|---|---|
|
||
| `assets` | `laser_card_instances.asset_id` | 铸造成功后回填；`cover_url` = composite 签名 URL |
|
||
| `mint_orders` | `laser_card_instances.mint_order_id` = `order_id` | `status`: PENDING → PROCESSING → SUCCESS/FAILED |
|
||
|
||
### 6.5 新增表：`laser_card_templates`
|
||
|
||
**职责：** 内置 5 套预设（与 `laserBatchExport.js` → `PRESET_VARIANTS` 一一对应），本期仅种子数据，无管理端 CRUD。
|
||
|
||
```sql
|
||
CREATE TABLE laser_card_templates (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
template_code VARCHAR(64) NOT NULL,
|
||
name VARCHAR(100) NOT NULL,
|
||
description TEXT,
|
||
status VARCHAR(20) NOT NULL DEFAULT 'published',
|
||
version INT NOT NULL DEFAULT 1,
|
||
thumbnail_oss_key VARCHAR(255),
|
||
backdrop_options JSONB NOT NULL DEFAULT '[]',
|
||
render_config JSONB NOT NULL,
|
||
engine_min_version VARCHAR(32) NOT NULL DEFAULT 'compositor-1.0.0',
|
||
sort_order INT NOT NULL DEFAULT 0,
|
||
star_id BIGINT NOT NULL DEFAULT 0,
|
||
created_by BIGINT NOT NULL DEFAULT 0,
|
||
created_at BIGINT NOT NULL,
|
||
updated_at BIGINT NOT NULL,
|
||
deleted_at BIGINT
|
||
);
|
||
|
||
CREATE UNIQUE INDEX uk_lct_code_version
|
||
ON laser_card_templates(template_code, version)
|
||
WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_lct_status_star
|
||
ON laser_card_templates(status, star_id)
|
||
WHERE deleted_at IS NULL;
|
||
```
|
||
|
||
| 字段 | 类型 | 空 | 说明 |
|
||
|---|---|---|---|
|
||
| `id` | BIGSERIAL | N | 主键 |
|
||
| `template_code` | VARCHAR(64) | N | 业务编码：`dream`/`classic`/`holoFull`/`ice`/`sunset` |
|
||
| `name` | VARCHAR(100) | N | 展示名 |
|
||
| `description` | TEXT | Y | 描述 |
|
||
| `status` | VARCHAR(20) | N | `published` \| `archived` |
|
||
| `version` | INT | N | 模板版本；与 `uk_lct_code_version` 联合唯一 |
|
||
| `thumbnail_oss_key` | VARCHAR(255) | Y | 列表缩略图 OSS |
|
||
| `backdrop_options` | JSONB | N | `[{ "id": "liquidBlue", "label": "...", "oss_key": "static/laser-bg/..." }]` |
|
||
| `render_config` | JSONB | N | 默认滑杆、beam、`style_preset_id` 等，< 16KB |
|
||
| `engine_min_version` | VARCHAR(32) | N | 最低合成器版本 |
|
||
| `sort_order` | INT | N | 列表排序 |
|
||
| `star_id` | BIGINT | N | `0` = 全站通用 |
|
||
| `created_by` | BIGINT | N | 种子填 `0` |
|
||
| `created_at` / `updated_at` | BIGINT | N | 毫秒时间戳 |
|
||
| `deleted_at` | BIGINT | Y | 软删除 |
|
||
|
||
**种子数据（5 条）：** 见 §十附录 A。
|
||
|
||
### 6.6 新增表：`laser_card_instances`
|
||
|
||
**职责：** 一次「上传 → 五图选卡 → 铸造」的业务实体；铸造前素材在 `materials_snapshot`，铸造后回填 `asset_id` 并写 `asset_material_relations`。
|
||
|
||
```sql
|
||
CREATE TABLE laser_card_instances (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
instance_no VARCHAR(32) NOT NULL,
|
||
instance_ulid VARCHAR(40) NOT NULL,
|
||
template_id BIGINT NOT NULL,
|
||
template_code VARCHAR(64) NOT NULL,
|
||
template_version INT NOT NULL,
|
||
owner_user_id BIGINT NOT NULL,
|
||
star_id BIGINT NOT NULL,
|
||
status VARCHAR(20) NOT NULL DEFAULT 'rendered',
|
||
client_request_id VARCHAR(64),
|
||
render_config JSONB,
|
||
materials_snapshot JSONB NOT NULL DEFAULT '[]',
|
||
composite_oss_key VARCHAR(255),
|
||
composite_material_id BIGINT,
|
||
asset_id BIGINT,
|
||
mint_order_id VARCHAR(100),
|
||
idempotency_key VARCHAR(64),
|
||
version INT NOT NULL DEFAULT 1,
|
||
created_at BIGINT NOT NULL,
|
||
updated_at BIGINT NOT NULL,
|
||
deleted_at BIGINT,
|
||
|
||
CONSTRAINT fk_lci_template
|
||
FOREIGN KEY (template_id) REFERENCES laser_card_templates(id),
|
||
CONSTRAINT fk_lci_asset
|
||
FOREIGN KEY (asset_id) REFERENCES assets(id) ON DELETE SET NULL,
|
||
CONSTRAINT fk_lci_mint_order
|
||
FOREIGN KEY (mint_order_id) REFERENCES mint_orders(order_id) ON DELETE SET NULL,
|
||
CONSTRAINT fk_lci_composite_material
|
||
FOREIGN KEY (composite_material_id) REFERENCES materials(id) ON DELETE SET NULL,
|
||
CONSTRAINT chk_lci_status
|
||
CHECK (status IN ('rendered', 'minting', 'minted'))
|
||
);
|
||
|
||
CREATE UNIQUE INDEX uk_lci_instance_no ON laser_card_instances(instance_no);
|
||
CREATE UNIQUE INDEX uk_lci_instance_ulid ON laser_card_instances(instance_ulid);
|
||
CREATE UNIQUE INDEX uk_lci_user_client_req
|
||
ON laser_card_instances(owner_user_id, client_request_id)
|
||
WHERE deleted_at IS NULL AND client_request_id IS NOT NULL;
|
||
CREATE INDEX idx_lci_owner_status
|
||
ON laser_card_instances(owner_user_id, status)
|
||
WHERE deleted_at IS NULL;
|
||
CREATE INDEX idx_lci_asset
|
||
ON laser_card_instances(asset_id)
|
||
WHERE asset_id IS NOT NULL AND deleted_at IS NULL;
|
||
CREATE INDEX idx_lci_star_created
|
||
ON laser_card_instances(star_id, created_at DESC)
|
||
WHERE deleted_at IS NULL;
|
||
```
|
||
|
||
| 字段 | 类型 | 空 | 说明 |
|
||
|---|---|---|---|
|
||
| `id` | BIGSERIAL | N | 主键；对外可用 `instance_ulid` |
|
||
| `instance_no` | VARCHAR(32) | N | `LC` + `yyyyMMddHHmmss` + 6 位随机；UK |
|
||
| `instance_ulid` | VARCHAR(40) | N | 对外 ID，如 `lc_inst_01HXYZ...`；UK |
|
||
| `template_id` | BIGINT | N | FK → `laser_card_templates.id` |
|
||
| `template_code` | VARCHAR(64) | N | 冗余，避免 JOIN |
|
||
| `template_version` | INT | N | 创建时模板版本快照 |
|
||
| `owner_user_id` | BIGINT | N | 持有者 |
|
||
| `star_id` | BIGINT | N | 多星隔离 |
|
||
| `status` | VARCHAR(20) | N | 见下表状态机 |
|
||
| `client_request_id` | VARCHAR(64) | Y | 客户端 UUID；与 `owner_user_id` 联合幂等 |
|
||
| `render_config` | JSONB | Y | 用户最终渲染参数快照 |
|
||
| `materials_snapshot` | JSONB | N | 铸造前素材 OSS 清单（**不存 material_id**） |
|
||
| `composite_oss_key` | VARCHAR(255) | Y | 选中合成图 OSS key（= snapshot 中 composite） |
|
||
| `composite_material_id` | BIGINT | Y | 铸造后回填 `materials.id`（main 层） |
|
||
| `asset_id` | BIGINT | Y | 铸造成功后回填 |
|
||
| `mint_order_id` | VARCHAR(100) | Y | FK → `mint_orders.order_id` |
|
||
| `idempotency_key` | VARCHAR(64) | Y | 最后一次写操作幂等键 |
|
||
| `version` | INT | N | 乐观锁 |
|
||
| `created_at` / `updated_at` / `deleted_at` | BIGINT | — | 审计 |
|
||
|
||
**状态机：**
|
||
|
||
| status | 含义 | 允许操作 |
|
||
|---|---|---|
|
||
| `rendered` | 已选卡、素材已上传、实例已创建，未铸造 | `POST .../mint` |
|
||
| `minting` | 铸造进行中 | 幂等查询；失败可回到 `rendered` |
|
||
| `minted` | 铸造完成，`asset_id` 已回填 | 只读 |
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> rendered: POST /laser/instances
|
||
rendered --> minting: POST /mint
|
||
minting --> minted: CreateMintOrder SUCCESS
|
||
minting --> rendered: CreateMintOrder FAILED
|
||
```
|
||
|
||
### 6.7 新增表：`laser_card_operation_logs`
|
||
|
||
```sql
|
||
CREATE TABLE laser_card_operation_logs (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
instance_id BIGINT NOT NULL,
|
||
instance_no VARCHAR(32) NOT NULL,
|
||
operator_user_id BIGINT NOT NULL,
|
||
action VARCHAR(50) NOT NULL,
|
||
status_before VARCHAR(20),
|
||
status_after VARCHAR(20),
|
||
request_id VARCHAR(64),
|
||
payload_json JSONB,
|
||
result_json JSONB,
|
||
ip_address VARCHAR(45),
|
||
user_agent VARCHAR(255),
|
||
latency_ms INT,
|
||
err_code VARCHAR(32),
|
||
created_at BIGINT NOT NULL,
|
||
|
||
CONSTRAINT fk_lclog_instance
|
||
FOREIGN KEY (instance_id) REFERENCES laser_card_instances(id) ON DELETE CASCADE
|
||
);
|
||
|
||
CREATE INDEX idx_lclog_instance_time
|
||
ON laser_card_operation_logs(instance_id, created_at DESC);
|
||
CREATE INDEX idx_lclog_operator_time
|
||
ON laser_card_operation_logs(operator_user_id, created_at DESC);
|
||
CREATE INDEX idx_lclog_action_time
|
||
ON laser_card_operation_logs(action, created_at DESC);
|
||
```
|
||
|
||
| action | 触发接口 | status 变化 |
|
||
|---|---|---|
|
||
| `create_instance` | `POST /laser/instances` | → `rendered` |
|
||
| `generate_variants` | Thinking 页五图完成（可选记日志） | — |
|
||
| `mint_start` | `POST .../mint` | `rendered` → `minting` |
|
||
| `mint_success` | 铸造事务提交成功 | `minting` → `minted` |
|
||
| `mint_fail` | 铸造失败 | `minting` → `rendered` |
|
||
|
||
### 6.8 `materials_snapshot` JSON Schema
|
||
|
||
铸造前写入 `laser_card_instances.materials_snapshot`，**数组长度 3–4**（无抠图时无 `cutout` 项）：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"role": "source",
|
||
"oss_key": "laser-card/1001/42/20260525/uuid_source.jpg",
|
||
"hash": "sha256...",
|
||
"width": 1080,
|
||
"height": 1440,
|
||
"mime_type": "image/jpeg",
|
||
"file_size": 245760,
|
||
"preset_id": null
|
||
},
|
||
{
|
||
"role": "cutout",
|
||
"oss_key": "laser-card/1001/42/20260525/uuid_cutout.png",
|
||
"hash": "sha256...",
|
||
"width": 1080,
|
||
"height": 1440,
|
||
"mime_type": "image/png",
|
||
"file_size": 180000,
|
||
"preset_id": null
|
||
},
|
||
{
|
||
"role": "backdrop",
|
||
"oss_key": "static/laser-bg/laser-bg-1.png",
|
||
"hash": "static...",
|
||
"preset_id": "liquidBlue"
|
||
},
|
||
{
|
||
"role": "composite",
|
||
"oss_key": "laser-card/1001/42/20260525/uuid_variant_holoFull.jpg",
|
||
"hash": "sha256...",
|
||
"width": 1080,
|
||
"height": 1440,
|
||
"preset_id": "holoFull"
|
||
}
|
||
]
|
||
```
|
||
|
||
| snapshot 字段 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `role` | Y | `source` \| `cutout` \| `backdrop` \| `composite` |
|
||
| `oss_key` | Y | OSS 对象键 |
|
||
| `hash` | Y | 文件哈希 |
|
||
| `width` / `height` | 图必填 | 像素尺寸 |
|
||
| `preset_id` | N | 仅 `backdrop` / `composite` 关联模板预设 |
|
||
|
||
### 6.9 跨表生命周期（数据落库顺序）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant FE as 前端
|
||
participant OSS as OSS
|
||
participant LCI as laser_card_instances
|
||
participant MAT as materials
|
||
participant AMR as asset_material_relations
|
||
participant AST as assets
|
||
participant MO as mint_orders
|
||
|
||
FE->>OSS: 上传 source/cutout/backdrop/composite
|
||
FE->>LCI: INSERT status=rendered, materials_snapshot=[...]
|
||
Note over LCI: materials 表尚无记录
|
||
FE->>MO: InitMintOrder (既有)
|
||
FE->>LCI: UPDATE status=minting, mint_order_id
|
||
FE->>AST: CreateMintOrder (既有)
|
||
loop 每条 snapshot.role
|
||
FE->>MAT: UploadMaterial(oss_key) → material_id
|
||
FE->>AMR: BindAssetMaterials(asset_id, type, layer_order)
|
||
end
|
||
FE->>LCI: UPDATE status=minted, asset_id, composite_material_id
|
||
```
|
||
|
||
| 阶段 | 写入表 | 关键字段 |
|
||
|---|---|---|
|
||
| 选卡确认 | `laser_card_instances` | `status=rendered`, `materials_snapshot`, `composite_oss_key`, `render_config` |
|
||
| 发起铸造 | `laser_card_instances` + `mint_orders` | `status=minting`, `mint_order_id` |
|
||
| 铸造成功 | `assets` + `materials` × N + `asset_material_relations` × N | `instances.asset_id`, `instances.composite_material_id` |
|
||
| 完成 | `laser_card_instances` | `status=minted` |
|
||
| 全程 | `laser_card_operation_logs` | 每个写操作追加一行 |
|
||
|
||
### 6.10 OSS 路径与表字段映射
|
||
|
||
| 文件角色 | OSS 路径模式 | 写入 snapshot.role | 铸造后 material_type |
|
||
|---|---|---|---|
|
||
| 用户原图 | `laser-card/{star_id}/{user_id}/{yyyyMMdd}/{uuid}_source.jpg` | `source` | `source` |
|
||
| 抠图 PNG | `laser-card/.../{uuid}_cutout.png` | `cutout` | `cutout` |
|
||
| 内置底纹 | `static/laser-bg/laser-bg-{n}.png` | `backdrop` | `backdrop` |
|
||
| 选中合成图 | `laser-card/.../{uuid}_composite.jpg` | `composite` | `main` |
|
||
| 模板缩略图 | `laser-card/templates/{code}/thumb.jpg` | — | — |
|
||
|
||
**禁止：** 在 PostgreSQL 存 BLOB / base64；`payload_json` 禁止存大图。
|
||
|
||
### 6.11 迁移脚本与索引汇总
|
||
|
||
**迁移文件（已落库）：**
|
||
|
||
| 文件 | 用途 |
|
||
|---|---|
|
||
| `backend/scripts/migrations/migrate_laser_card_v3_tables.sql` | 三表 DDL + **全量 COMMENT** + 5 条模板种子 |
|
||
| `backend/scripts/migrations/migrate_laser_card_v3_comments.sql` | 仅备注片段（被主迁移 `\ir` 引用） |
|
||
| `backend/scripts/migrations/migrate_laser_card_v3_comments_only.sql` | **已建表**时单独补备注 |
|
||
| `backend/scripts/migrations/migrate_laser_card_tags_optional.sql` | **可选** 历史 `assets.tags` 补 `cast:star_card`（无 DDL） |
|
||
|
||
```sql
|
||
-- 1. laser_card_templates
|
||
-- 2. laser_card_instances (+ FK + CHECK)
|
||
-- 3. laser_card_operation_logs (+ FK)
|
||
-- 4. INSERT 5 rows INTO laser_card_templates (附录 A)
|
||
-- 5. pkg/models 新增 MaterialTypeSource / Cutout / Backdrop 常量
|
||
-- 注意：本期不对 assets / asset_registry 做 ALTER（品类与工艺走 tags 约定，§6.3.1）
|
||
```
|
||
|
||
**本期新增索引一览：**
|
||
|
||
| 表 | 索引名 | 列 | 类型 |
|
||
|---|---|---|---|
|
||
| `laser_card_templates` | `uk_lct_code_version` | `template_code, version` | UNIQUE (partial) |
|
||
| `laser_card_templates` | `idx_lct_status_star` | `status, star_id` | INDEX (partial) |
|
||
| `laser_card_instances` | `uk_lci_instance_no` | `instance_no` | UNIQUE |
|
||
| `laser_card_instances` | `uk_lci_instance_ulid` | `instance_ulid` | UNIQUE |
|
||
| `laser_card_instances` | `uk_lci_user_client_req` | `owner_user_id, client_request_id` | UNIQUE (partial) |
|
||
| `laser_card_instances` | `idx_lci_owner_status` | `owner_user_id, status` | INDEX (partial) |
|
||
| `laser_card_instances` | `idx_lci_asset` | `asset_id` | INDEX (partial) |
|
||
| `laser_card_operation_logs` | `idx_lclog_instance_time` | `instance_id, created_at DESC` | INDEX |
|
||
|
||
### 6.12 Phase 2 可选表（Dify 五图任务，本期不建）
|
||
|
||
若服务端生成五图上线，可另立迁移增加 `laser_card_generate_jobs`（`job_id`、`owner_user_id`、`status`、`variant_urls JSONB`），与 `instances` 通过 `generate_job_id` 关联。**本期不实施，不写入迁移脚本。**
|
||
|
||
---
|
||
|
||
## 七、后端 API 与其它详细设计
|
||
|
||
### 7.1 接口一览（6 个，Phase 1）
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| GET | `/api/v1/laser/templates` | 预设列表（含 render_config） |
|
||
| GET | `/api/v1/laser/templates/:code` | 预设详情 |
|
||
| POST | `/api/v1/laser/instances` | 选卡并确认素材后创建实例 |
|
||
| POST | `/api/v1/laser/instances/:id/mint` | 铸造 |
|
||
| GET | `/api/v1/laser/instances/:id` | 实例详情 |
|
||
| POST | `/api/v1/segment` | 魔搭抠图代理 |
|
||
|
||
**Phase 2 追加：** `POST/GET /api/v1/laser/generate[/{job_id}]`（Dify 五图任务）
|
||
|
||
### 7.2 选卡页铸造流程（对齐光栅 `lenticular-result`）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant R as laser-result.vue
|
||
participant API as Gateway
|
||
participant Mint as craftMintSubmit
|
||
|
||
R->>R: 用户选中 variant[index]
|
||
R->>API: estimateMintCostApi
|
||
R->>R: ConfirmModal 展示水晶
|
||
R->>R: 上传 source + cutout + backdrop + composite
|
||
R->>API: POST /laser/instances
|
||
R->>Mint: submitCraftMintFromPath 扩展多素材
|
||
Note over Mint: main=composite<br/>source/cutout/backdrop 额外 bind
|
||
Mint->>API: createMintOrder + bindAssetMaterials
|
||
```
|
||
|
||
**`submitCraftMintFromPath` 扩展要点：**
|
||
|
||
- 新增参数 `laserMaterials: [{ role, oss_key, material_id? }]`
|
||
- `main` = 用户选中的合成图
|
||
- 铸造成功后 `bindAssetMaterialsApi` 绑定 4 层
|
||
- 复用现有水晶扣费与 `order_id` 幂等
|
||
- **`createMintOrderApi` 请求体 `tags`**：必须含 `cast:star_card` + `craft:laser`（来自 `CASTLOVE_FORM_KEY` 快照，§6.3.1）；`mint_service` 已支持 `req.Tags` → `asset.Tags`，**无需**改表结构
|
||
|
||
### 7.3 页面职责摘要（细节见 §5.4、§5.5）
|
||
|
||
| 页面 | 职责 |
|
||
|---|---|
|
||
| **`laser-thinking.vue`** | `useLaserBatchGenerate` + `LaserBatchCanvasHost`；礼盒进度 UI；完成后跳 result |
|
||
| **`laser-result.vue`** | `LaserVariantPyramid` + `LaserPreviewCanvas` + `useLaserMint`；**删除** `createMintOrderApi` 单图路径 |
|
||
|
||
**展示原则（§5.4）：** 预览可动（WebGL）、铸造用静图（batch JPG）、**无相册导出**、**无陀螺仪**。
|
||
|
||
### 7.4 死代码清理（实施时必须删除）
|
||
|
||
| 项 | 处置 |
|
||
|---|---|
|
||
| `pages/castlove/laser-card-studio.vue` | 删除（含 `saveImageToPhotosAlbum` 保存相册逻辑） |
|
||
| `pages.json` 中 laser-card-studio 路由 | 删除 |
|
||
| `handleSingleCraftLaserEntry`、`CASTLOVE_LASER_ENTRY_KEY` 写入 | 删除 |
|
||
| `castloveAfterLaserMint.js` | Phase 1 末删除（由扩展后的 craftMintSubmit 替代） |
|
||
| `aliyunPortraitUni.js`、`segmentApi.js` AK、`segmentationCloud.js` direct 分支 | 删除 |
|
||
| `components/lenticular/HolographicCard.vue` | 删除 |
|
||
| `lenticular-thinking.vue` 误引 `laserBatchExport` | 删除误引 |
|
||
| `discover/generation-loading` 镭射分支 | 迁出后删除分支，仅保留 API/星卡模式 |
|
||
|
||
---
|
||
|
||
## 八、分阶段实施计划（14 天）
|
||
|
||
| 阶段 | 时间 | 交付 |
|
||
|---|---|---|
|
||
| **Phase 1** | 第 1–10 天 | 魔搭 Segment 代理；三表 + 实例/铸造 API；`laser-thinking` / `laser-result` 迁目录；`craftMintSubmit` 多素材 + **`tags` 双写**（§6.3.1）；下线工坊；客户端五图 |
|
||
| **Phase 2** | 第 11–14 天 | Dify 五图工作流 + `/laser/generate` 接口；灰度切换客户端/服务端生成；死代码清零；监控告警 |
|
||
|
||
| 里程碑 | 日期 |
|
||
|---|---|
|
||
| 后端接口可联调 | D5 |
|
||
| 选卡 → 多素材铸造 E2E | D10 |
|
||
| 灰度 10% | D12 |
|
||
| 全量 + 删工坊 | D14 |
|
||
|
||
**灰度：** `feature_flag_laser_v3` 按 `user_id` 尾号；关闭时回退旧五图+单图铸造（仅灰度期，全量后删旧逻辑）。
|
||
|
||
---
|
||
|
||
## 九、风险与应对
|
||
|
||
| 风险 | 等级 | 应对 |
|
||
|---|---|---|
|
||
| 魔搭额度/稳定性 | 中 | 椭圆降级；购买额度包；超时 2s 重试 |
|
||
| 客户端/服务端五图不一致 | 中（Phase 2） | Phase 2 灰度对比；验收截图 diff |
|
||
| 选卡页改造引入回归 | 中 | 与光栅共用 ConfirmModal；E2E 用例 |
|
||
| 删除工坊误伤入口 | 低 | 全局搜 `laser-card-studio`；产品确认无工坊入口 |
|
||
| Dify 工作流延迟 | 低（P2） | 异步 job + 轮询；Loading 最短展示 1.6s |
|
||
|
||
---
|
||
|
||
## 十、验收标准
|
||
|
||
### 10.1 功能
|
||
|
||
- [ ] create 上传 → Thinking → 五图展示 → 选卡 → 费用确认 → 铸造成功
|
||
- [ ] 魔搭抠图成功/失败椭圆降级
|
||
- [ ] 铸造后 `GetAssetMaterials` 含 main/source/cutout/backdrop
|
||
- [ ] 铸造成功后 `assets.tags` 含 **`cast:star_card`** 与 **`craft:laser`**
|
||
- [ ] **无** `laser-card-studio` 路由可访问
|
||
- [ ] 光栅流程无回归
|
||
|
||
### 10.2 性能
|
||
|
||
- [ ] 五图生成（Phase 1 中端机）< 8s
|
||
- [ ] 抠图 P95 < 3s
|
||
- [ ] 选卡页滑动流畅
|
||
|
||
### 10.3 安全
|
||
|
||
- [ ] 正式包无 AK
|
||
- [ ] `/segment` 鉴权 + 限流生效
|
||
|
||
### 10.4 规范
|
||
|
||
- [ ] 页面位于 `pages/castlove/laser/*`，单页 < 200 行
|
||
- [ ] 镭射逻辑仅在 `components/laser/` + `composables/useLaser*`，`discover/generation-*` 无镭射分支
|
||
- [ ] 无 `saveImageToPhotosAlbum`、无 `laser-card-studio` 路由
|
||
- [ ] 五图 Phase 1 无后端生成接口（仅 `canvasToTempFilePath`）
|
||
- [ ] 无 `laser_card_instance_materials` 表
|
||
- [ ] 无私写 `materials` SQL
|
||
- [ ] **未** 为品类/工艺新增 `cast_category` / `craft_type` 列；仅用 `tags` 约定（§6.3.1）
|
||
|
||
---
|
||
|
||
## 十一、附录
|
||
|
||
### A. Phase 1 五图预设与模板种子映射
|
||
|
||
| 序号 | PRESET_VARIANTS.style | template_code | 底纹 backdrop |
|
||
|---|---|---|---|
|
||
| 0 | dream | dream | liquidBlue |
|
||
| 1 | classic | classic | liquidLavender |
|
||
| 2 | holoFull | holoFull | liquidPearl |
|
||
| 3 | ice | ice | liquidBlue |
|
||
| 4 | sunset | sunset | liquidLavender |
|
||
|
||
**种子 SQL 示例（每条需补全 `render_config` / `backdrop_options` JSON）：**
|
||
|
||
```sql
|
||
INSERT INTO laser_card_templates (
|
||
template_code, name, status, version,
|
||
backdrop_options, render_config, engine_min_version,
|
||
sort_order, star_id, created_by, created_at, updated_at
|
||
) VALUES
|
||
('dream', '梦幻', 'published', 1, '[{"id":"liquidBlue","oss_key":"static/laser-bg/laser-bg-1.png"}]', '{}', 'compositor-1.0.0', 0, 0, 0, EXTRACT(EPOCH FROM NOW())*1000, EXTRACT(EPOCH FROM NOW())*1000),
|
||
('classic', '经典', 'published', 1, '[{"id":"liquidLavender","oss_key":"static/laser-bg/laser-bg-2.png"}]', '{}', 'compositor-1.0.0', 1, 0, 0, EXTRACT(EPOCH FROM NOW())*1000, EXTRACT(EPOCH FROM NOW())*1000),
|
||
('holoFull', '全息', 'published', 1, '[{"id":"liquidPearl","oss_key":"static/laser-bg/laser-bg-3.png"}]', '{}', 'compositor-1.0.0', 2, 0, 0, EXTRACT(EPOCH FROM NOW())*1000, EXTRACT(EPOCH FROM NOW())*1000),
|
||
('ice', '冰蓝', 'published', 1, '[{"id":"liquidBlue","oss_key":"static/laser-bg/laser-bg-1.png"}]', '{}', 'compositor-1.0.0', 3, 0, 0, EXTRACT(EPOCH FROM NOW())*1000, EXTRACT(EPOCH FROM NOW())*1000),
|
||
('sunset', '晚霞', 'published', 1, '[{"id":"liquidLavender","oss_key":"static/laser-bg/laser-bg-2.png"}]', '{}', 'compositor-1.0.0', 4, 0, 0, EXTRACT(EPOCH FROM NOW())*1000, EXTRACT(EPOCH FROM NOW())*1000);
|
||
```
|
||
|
||
### B. 参考代码索引
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `frontend/utils/castloveGenerationFlow.js` | `startCraftGenerationFlow`、`persistLaserPreviewImages` |
|
||
| `frontend/utils/laser-card/laserBatchExport.js` | Phase 1 五图合成（§5.5） |
|
||
| `frontend/utils/laser-card/laserPreviewWebgl.js` | 动态预览着色器 |
|
||
| `frontend/pages/discover/generation-loading.vue` | **迁出** `runLaserFlow` → `laser-thinking` |
|
||
| `frontend/pages/discover/generation-result.vue` | **迁出** 金字塔 UI → `LaserVariantPyramid` |
|
||
| `frontend/pages/castlove/laser-card-studio.vue` | **删除**（WebGL 逻辑迁入 `useLaserPreview`） |
|
||
| `frontend/pages/castlove/lenticular/lenticular-result.vue` | 铸造确认交互基线 |
|
||
| `frontend/utils/craftMintSubmit.js` | 多素材铸造基线 |
|
||
| `frontend/utils/castloveMintForm.js` | **`CAST_TAG_*` / `CRAFT_TAG_*`**、`buildCastloveFormSnapshot`（§6.3.1） |
|
||
| `frontend/composables/useLaserMint.js` | 镭射估价 + 铸造；须透传 `tags` |
|
||
| `docs/specs/2026-04-07-minimax-image-generation-design.md` | 星卡 AI 四图（镭射不用） |
|
||
|
||
### C. 前端组件迁移步骤（建议顺序）
|
||
|
||
| 步 | 任务 | 产出 |
|
||
|---|---|---|
|
||
| 1 | 抽出 `utils/laser-card/laserPresets.js`（`PRESET_VARIANTS`） | 预设单源 |
|
||
| 2 | `useLaserBatchGenerate` + `LaserBatchCanvasHost` | Thinking 可生成五图 |
|
||
| 3 | 新建 `laser-thinking.vue`、`pages.json`；`castloveGenerationFlow` 改跳转 | 脱离 discover/loading |
|
||
| 4 | `useLaserPreview` + `LaserPreviewCanvas`（从 studio 迁移 RAF/WebGL） | 动态预览组件 |
|
||
| 5 | `LaserVariantPyramid` + `useLaserResultSelection` | 金字塔选卡 |
|
||
| 6 | `laser-result.vue` + `useLaserMint` | 多素材铸造 E2E；**`tags`: `cast:star_card` + `craft:laser`**（§6.3.1） |
|
||
| 6b | `castloveMintForm.js`：补 `CAST_TAG_STAR_CARD`、`CRAFT_TAG_LASER`；光栅快照补 `cast:star_card` | tags 双轨对齐 |
|
||
| 7 | 删除 `generation-*` 镭射分支、`laser-card-studio`、死代码 | 单轨维护 |
|
||
| 8 | Phase 2：`aiWorkflowService` + `useLaserBatchGenerate` Dify 分支 | 可选服务端五图 |
|
||
|
||
---
|
||
|
||
**文档结束。** 评审通过后，实施任务可拆至 `docs/superpowers/plans/2026-05-25-laser-card-refactor-plan.md`。
|