跳到主要内容

架构方案

表达面 (Expression Surface) - 技术架构设计文档 v2.0​

1. 项目概述 (Overview)​

表达面 是一个基于 AI 的 Web 端图像创作工具,专注于“面部表达”场景(头像、表情包)。 核心设计理念是 “画布 + 工具箱” 模式:用户上传或生成图片后,所有的 AI 能力(智能居中、去底、风格化)均作为独立工具,由用户按需触发,而非强制性的线性工作流。

2. 技术选型 (Tech Stack)​

模块技术方案理由
应用框架Next.js 14 (App Router)React 生态标准,Server Actions 简化后端逻辑。
语言TypeScript强类型约束,保证复杂的 Canvas 逻辑不崩坏。
画布引擎Fabric.js (v6)强大的 Canvas 对象模型库,支持交互、图层、序列化。
状态管理Zustand轻量级,适合处理 Canvas 实例与 UI 组件的解耦同步。
面部识别MediaPipe Tasks Vision谷歌出品,WASM 运行在浏览器端,免费且极快。
去背景@imgly/background-removal浏览器端运行的 AI 去底,保护用户隐私,节省服务器成本。
AI 生图Replicate API (Flux/SDXL)通过 Next.js Server Actions 调用,高质量文生图。
UI 组件库Shadcn/UI + Tailwind快速构建现代化的编辑器界面。

3. 系统架构设计 (System Architecture)​

系统采用 分层架构,强调“视图”与“逻辑”的分离。

graph TD
User[用户交互层] --> UI[React UI Components]
UI --> Store[Zustand Store (状态管理)]

subgraph Core[核心逻辑层]
Store --> CM[Canvas Manager (Fabric.js 封装)]
Store --> TM[Tool Manager (AI 工具集)]
end

subgraph LocalAI[浏览器端 AI 引擎]
TM --> MP[MediaPipe (面部识别)]
TM --> RB[Imgly (去背景)]
end

subgraph Server[服务端基础设施]
TM --> API[Next.js Server Actions]
API --> Replicate[外部 GenAI 服务]
end

CM -- 渲染 --> Canvas[HTML5 Canvas]

3.1 核心模块职责​

  1. Canvas Manager (画布管理器):
    • 持有 Fabric.js 实例。
    • 负责底层的 CRUD(添加图片、删除对象、图层上移下移)。
    • 负责导出图片(Export to PNG/JPG)。
  2. Tool Manager (工具管理器):
    • 实现具体的业务逻辑。
    • 例如:applySmartCrop(),applyRemoveBackground()。
    • 它不直接操作 DOM,而是调用 Canvas Manager 修改对象属性。
  3. Editor Store (Zustand):
    • 连接 UI 和 Canvas。
    • 记录当前选中的对象(例如:用户选中了图片,UI 里的“去底”按钮才变亮)。

4. 核心功能实现逻辑 (Core Features Implementation)​

这是本次重构的重点。所有的 AI 功能都设计为原子化操作 (Atomic Operations)。

4.1 智能居中工具 (Smart Center Tool)​

触发方式: 用户点击工具栏的“智能居中”按钮。 逻辑: 不裁剪原图,而是调整图片在画布中的位置 (Position) 和 缩放 (Scale),使面部视觉居中。

算法流程:

  1. 获取输入: 获取当前选中的图片对象 (Fabric.Image)。
  2. 快照分析: 将该图片临时导出为 Base64 或 ImageData。
  3. 识别: 输入 MediaPipe Face Detector,获取人脸 Bounding Box (x, y, w, h)。
  4. 计算变换矩阵:
    • 目标: 人脸中心 = 画布中心。
    • 目标: 人脸宽度 = 画布宽度的 50% (可配置系数)。
    • 计算缩放差(ScaleDelta): (CanvasWidth * 0.5) / FaceWidth。
    • 计算位移(Offset): 根据缩放后的尺寸,反向计算 Left/Top 坐标。
  5. 应用变换: 调用 Fabric 对象的 animate 方法,平滑过渡到新位置。

4.2 智能去底工具 (Remove BG Tool)​

触发方式: 用户点击“一键抠图”。 逻辑: 浏览器端计算,替换对象。

算法流程:

  1. 锁定状态: UI 显示“处理中...”,锁定画布操作。
  2. 推理: 调用 @imgly/background-removal 处理当前图片资源。
  3. 替换:
    • 生成一张透明背景的 Blob URL。
    • 创建一个新的 Fabric.Image 对象。
    • 关键点: 将新对象继承旧对象的所有属性(位置、旋转、缩放、层级)。
    • 删除旧对象,添加新对象。
  4. 解锁: 恢复 UI 交互。

4.3 AI 生图 (Generative Fill/Create)​

触发方式: 侧边栏输入 Prompt 点击生成。

算法流程:

  1. 服务端调用: 前端发送 Prompt -> Next.js Server Action -> Replicate API。
  2. 接收结果: 获得图片 URL。
  3. 加入画布:
    • 模式 A (新建): 清空画布,将新图作为背景。
    • 模式 B (贴纸): 将新图作为普通图层添加到中心。

5. 数据结构设计 (Data Structures)​

5.1 Zustand Store Interface​

interface EditorState {
canvas: fabric.Canvas | null; // Fabric 实例引用
activeObject: fabric.Object | null; // 当前选中的对象
isProcessing: boolean; // 是否有 AI 任务正在运行

// Actions
initCanvas: (canvasElement: HTMLCanvasElement) => void;
setActiveObject: (obj: fabric.Object | null) => void;

// Tools
triggerSmartCenter: () => Promise<void>;
triggerRemoveBackground: () => Promise<void>;
addImageToCanvas: (url: string) => Promise<void>;
}

5.2 表达面数据模型 (用于保存/加载)​

interface ProjectData {
version: string; // "2.0"
canvasWidth: number;
canvasHeight: number;
// 直接复用 Fabric.js 的 JSON 序列化标准
fabricData: object;
// 额外元数据
metadata: {
projectName: string;
createdAt: number;
thumbnail?: string;
}
}

6. 开发路线图 (Development Roadmap)​

Phase 1: 基础设施 (Infrastructure)​

  • 初始化 Next.js + Tailwind 环境。
  • 封装 CanvasStage 组件,实现 Fabric.js 的初始化与销毁。
  • 实现基础图片上传与拖拽上画布功能。

Phase 2: 视觉算法集成 (Vision Integration)​

  • 集成 MediaPipe 库,编写 FaceDetector 服务类(单例模式)。
  • 开发“智能居中”算法:编写数学逻辑,将 MediaPipe 坐标转换为 Fabric 坐标。
  • 调试居中效果,增加平滑动画。

Phase 3: 高级工具与生图 (Advanced Tools)​

  • 集成 @imgly,实现前端抠图。
  • 配置 Next.js API Route,打通 Replicate 接口。
  • 实现生图后自动添加到画布的逻辑。

Phase 4: 完善与导出 (Polish)​

  • 添加文字工具(Fabric.IText)。
  • 实现 Export 功能(下载为 PNG)。
  • UI 细节打磨(Loading 状态、错误处理)。

7. 关键注意事项 (Design Constraints)​

  1. 坐标系转换陷阱:

    • MediaPipe 返回的是图像内部的相对坐标 (0.0 - 1.0)。
    • Fabric.js 处理的是画布坐标系。
    • 图片可能被旋转或缩放。
    • 解决方案: 计算时必须基于图片的 originalWidth 和 originalHeight,然后乘以图片当前的 scaleX/Y,并考虑图片的 angle。
  2. 性能保护:

    • AI 模型(MediaPipe/Imgly)在第一次加载时较大。
    • 策略: 使用 useEffect 在页面加载后静默预加载模型。
  3. CORS (跨域资源共享):

    • Canvas toDataURL 极其严格,如果图片跨域会“污染”画布。
    • 策略: 所有外部图片(Replicate生成的、用户上传的)建议都通过 Next.js 的 Image Proxy 中转,或者确保源站开启 Access-Control-Allow-Origin: *。

这份文档为你提供了一个清晰的、模块化的开发指引。现在,“智能居中”不再是一个黑盒流程,而是一个你可以精细调节参数的独立工具。