ADR-001: 大美丽单引擎分层架构

状态: 已接受 (Accepted)
日期: 2026-04-17 最后同步: 2026-06-04（与 beauty-engine/src/main/java/com/picme/beauty/ 代码结构对齐）
决策: RD
PM Review: 已完成

1. 背景与问题陈述

重构前架构

App Layer → 大美丽模块 (混合业务逻辑+GPU实现)

核心问题: 1. 层次越界: 大美丽直接包含 GPU 渲染代码，违反 Clean Architecture 2. 强耦合: App 层直接依赖引擎内部类，无法 Mock 测试 3. 复用阻塞: 渲染逻辑被业务逻辑污染，无法独立作为视觉能力库输出 4. 性能风险: EGL Context 管理分散，线程模型混乱

演进说明: 架构经过多次迭代，最终沉淀为单引擎方案，当前仅保留自研大美丽（BIG_BEAUTY）引擎。

2. 决策目标架构

┌─────────────────────────────────────────────────────────┐
│                    App Layer                            │
│              ↓ 依赖 beauty-engine:api                   │
└────────────────────┬──────────────────────────────────┘
                     │
┌────────────────────▼──────────────────────────────────┐
│  Domain Layer: beauty-engine:api                        │
│  ├─ BeautyPreviewProvider (Interface)                 │
│  ├─ BeautyPreviewEngine (Interface)                   │
│  ├─ PhotoProcessor (Interface)                        │
│  ├─ BeautyParams / FaceData / FilterType              │
│  └─ BeautyPerfStats / FrameSyncResult                 │
└────────────────────┬──────────────────────────────────┘
                     │
┌────────────────────▼──────────────────────────────────┐
│  Data Layer: beauty-engine:render                       │
│  ├─ GlBeautyPreviewProvider (Provider 实现)           │
│  ├─ CameraPreviewRenderer (自研 OpenGL ES 管线)      │
│  ├─ BeautyRenderer (美颜 Shader 渲染器)              │
│  ├─ PhotoProcessorImpl (拍照 GPU 离屏渲染)           │
│  ├─ FaceMakeupPass (唇色/腮红三角网格 Pass)          │
│  └─ EGLCore / WindowSurface                           │
└────────────────────┬──────────────────────────────────┘
                     │
┌────────────────────▼──────────────────────────────────┐
│              BIG_BEAUTY (自研引擎)                      │
└─────────────────────────────────────────────────────────┘

3. 关键决策

4. 技术实现

4.1 模块结构

beauty-engine/src/main/java/com/picme/beauty/
├── api/                    # Domain Layer - 实现层 API（依赖 :beauty-api 共享类型）
│   ├── BeautyPreviewProvider.kt   # 预览 Provider 接口
│   ├── BeautyPreviewEngine.kt     # 组合接口（Provider + Capability）
│   ├── BeautyPreviewCapability.kt # GL 能力扩展（FaceWarp/LipMask）
│   ├── PhotoProcessor.kt          # 拍照后处理接口
│   ├── BeautyParams.kt            # Shader 参数（来自 :beauty-api）
│   ├── BeautyPerfStats.kt         # 性能统计（来自 :beauty-api）
│   ├── FilterTypeExt.kt           # FilterType 扩展（来自 :beauty-api）
│   ├── StyleFilterExt.kt          # StyleFilter 扩展（来自 :beauty-api）
│   ├── FrameId.kt                 # 帧同步标识（来自 :beauty-api）
│   ├── FrameSyncConfig.kt         # 帧同步配置（来自 :beauty-api）
│   └── FrameSyncResult.kt         # 帧同步结果（来自 :beauty-api）
│   > **Note**: `BeautyParams`, `FilterType`, `StyleFilter`, `FaceData`, `FrameId`, `FrameSyncConfig`, `FrameSyncResult`, `BeautyPerfStats` 等类型定义在 `:beauty-api` 模块，`beauty-engine:api/` 仅保留实现相关接口。
└── render/                 # Data Layer - 自研引擎 GL 渲染实现
    ├── GlBeautyPreviewProvider.kt   # Provider 接口实现
    ├── CameraPreviewRenderer.kt     # 渲染管线核心
    ├── BeautyRenderer.kt            # 美颜 Shader 渲染器
    ├── BeautyPass.kt                # 通用渲染 Pass 基类
    ├── FaceMakeupPass.kt            # 唇色/腮红三角网格 Pass
    ├── StyleEffectShader.kt         # 风格特效 Shader
    ├── PhotoProcessorImpl.kt        # 拍照 GPU 离屏渲染实现
    ├── EGLCore.kt                   # EGL 上下文管理
    ├── WindowSurface.kt             # EGL Window Surface 封装
    ├── Framebuffer.kt               # FBO 封装
    ├── FramebufferPool.kt           # FBO 对象池
    └── ShaderProgram.kt             # Shader 编译与链接

4.2 依赖规则 (Gradle)

// App 层（只允许依赖 api 层类型）
dependencies {
    implementation project(':beauty-api')      // 共享类型契约（BeautySettings, FilterType, StyleFilter, Face 等）
    implementation project(':beauty-engine')     // 实现层
    // 禁止: implementation project(':beauty-engine:render')
}

// render 模块（内部实现）
dependencies {
    api project(':beauty-engine:api')
}

4.3 ArchUnit 依赖检查

// 规则: App 层严禁直接依赖 render 内部实现包
noClasses()
    .that().resideInAPackage("..app..")
    .should().dependOnClassesThat()
    .resideInAPackage("..beautyengine.render..")

5. 后果分析

正面影响

• ✅ 接口契约稳定，支持版本化管理
• ✅ 单元测试可 Mock BeautyEngine 接口
• ✅ 引擎实现完全隔离，可独立演进
• ✅ GL 线程独立，不阻塞主线程
• ✅ 4K 大图分块处理，无 OOM 风险

负面影响

• ⚠️ EGL Context 初始化约 50-100ms
• ⚠️ Shader 编译首次加载约 100-200ms

6. 状态

7. 相关文档

• README.md - 项目总览与架构图
• beauty-engine/AGENTS.md - 模块详细规范
• docs/03-TECHNICAL-SPECS/BEAUTY_ENGINE_TECH_SPEC.md - 大美丽引擎技术规范