PicMe 开发、代码审查与任务标记规范（Development, CR & Task Markup）

// Spec: <文档路径>#<章节/锚点>
// Implements: <AC-ID>（如 AC-P0-3）
// Related: <关联文档路径>#<章节>
// ChangeLog: <日期> <变更描述>（可选）

// Spec: docs/03-TECHNICAL-SPECS/FRAME_SYNC_TECH_SPEC.md#5-frame-sync
// Implements: AC-P0-3
// Related: beauty-engine/AGENTS.md
// ChangeLog: 2026-06-30 新增 missingThresholdFrames 字段
class FrameSyncManager(
    private val config: FrameSyncConfig = FrameSyncConfig.DEFAULT
) {
    // ...
}

# .github/workflows/doc-sync-check.yml（参考）
doc-sync-check:
  script:
    # 检查 PR 中修改了 beauty-engine 内部实现时是否同步修改了 AGENTS.md
    - python scripts/check_doc_sync.py \
        --code-path beauty-engine/src/main/java/ \
        --doc-path beauty-engine/AGENTS.md
    
    # 检查 PR 中修改了 api/ 接口时是否同步修改了技术文档
    - python scripts/check_doc_sync.py \
        --code-path beauty-api/src/main/java/ \
        --doc-path docs/03-TECHNICAL-SPECS/BEAUTY_ENGINE_TECH_SPEC.md
    
    # 检查文档间内部链接有效性
    - python scripts/check_doc_links.py \
        --root docs/
    
    # 检查 AGENTS.md 中提到的模块在代码中是否存在
    - python scripts/check_spec_completeness.py \
        --spec beauty-engine/AGENTS.md \
        --src beauty-engine/src/

# 代码风格
./gradlew ktlintCheck

# 静态分析
./gradlew detekt

# 组合检查（CI 推荐）
./gradlew :app:compileDebugKotlin :app:testDebugUnitTest ktlintCheck detekt

# 启动时间基准测试（需真机/模拟器）
adb shell am start -W com.mamba.picme/.MainActivity

# 与历史基线对比（退化 > 5% 需关注）
# python scripts/compare_perf_baseline.py \
#     --current benchmark-results.json \
#     --baseline perf-baseline.json \
#     --threshold 5%

// api/ 包不依赖 egl/
@ArchTest
val `api package should not depend on egl package` = noClasses()
    .that().resideInAPackage("..api..")
    .should().dependOnClassesThat().resideInAPackage("..egl..")

// App 层不直接实例化 egl/ 内部类
@ArchTest
val `app should not instantiate egl classes directly` = noClasses()
    .that().resideInAPackage("..features..")
    .should().callConstructorWhere(
        target(owner(resideInAPackage("..egl..")))
    )

// 禁止在构造函数中启动渲染线程
class NoRenderThreadInConstructor : Rule() {
    override fun visitClass(klass: KtClass) {
        if (klass.hasAnnotation("GlThread") || klass.name?.contains("Renderer") == true) {
            // 检查构造函数中是否启动 Thread
        }
    }
}

perf-baseline-check:
  script:
    # 启动时间基准测试
    - ./gradlew benchmark:coldStartupBenchmark
    
    # 单帧处理耗时基准测试
    - ./gradlew benchmark:frameProcessingBenchmark
    
    # 与基线对比，退化 > 5% 则失败
    - python scripts/compare_perf_baseline.py \
        --current benchmark-results.json \
        --baseline perf-baseline.json \
        --threshold 5%

doc-sync-check:
  script:
    # 检查 PR 中修改了 egl/ 实现时是否同步修改了 AGENTS.md
    - python scripts/check_doc_sync.py \
        --code-path beauty-engine/src/main/java/com/picme/beauty/egl/ \
        --doc-path beauty-engine/AGENTS.md
    
    # 检查 PR 中修改了 api/ 接口时是否同步修改了技术文档
    - python scripts/check_doc_sync.py \
        --code-path beauty-engine/src/main/java/com/picme/beauty/api/ \
        --doc-path docs/03-TECHNICAL-SPECS/BEAUTY_ENGINE_TECH_SPEC.md
    
    # 检查文档间内部链接有效性
    - python scripts/check_doc_links.py \
        --root docs/
    
    # 检查 AGENTS.md 中提到的模块在代码中是否存在
    - python scripts/check_spec_completeness.py \
        --spec beauty-engine/AGENTS.md \
        --src beauty-engine/src/

## CR 结果：✅ Approved

### 亮点
- 代码结构清晰，命名规范
- 单元测试覆盖完善
- 性能优化到位

### 建议（非阻塞）
- 可考虑提取公共逻辑为扩展函数
- 日志标签可更统一

## CR 结果：❌ Request Changes

### 阻塞问题

#### 1. 文档不同步
- **位置**: `beauty-engine/src/main/java/com/picme/beauty/egl/CameraPreviewRenderer.kt`
- **问题**: 修改了 `render()` 实现但未更新 `AGENTS.md`
- **修复**: 同步更新 `beauty-engine/AGENTS.md#render-pipeline` 章节

#### 2. 性能退化
- **位置**: `FrameSyncManager.query()`
- **问题**: 新增锁导致单帧耗时从 12ms → 18ms
- **修复**: 改用 `ConcurrentHashMap` 替代 synchronized

#### 3. I18N 缺失
- **位置**: `strings.xml`
- **问题**: 新增文案 "美颜总开关" 未覆盖英文和繁体
- **修复**: 补充三语翻译

### <功能标题> [kimi-task:<task_id>]
- **Assignee**: <RD | QA | CR | PM>
- **Scope**: `<文件路径1>`, `<文件路径2>`
- **Expected Change**:
  1. <具体变更描述>
  2. <具体变更描述>
- **DependsOn**: <task_id_1>, <task_id_2>
- **EstimatedEffort**: <Xd | Xh | Xw>
- **Priority**: <P0 | P1 | P2>
- **Acceptance**: <AC-P0-X | AC-P1-X>

### FR-5：严格缺失处理 [kimi-task:fsm-005]
- **Assignee**: RD
- **Scope**: `beauty-engine/src/main/java/com/picme/beauty/internal/framesync/FrameSyncManager.kt`, `beauty-engine/src/main/java/com/picme/beauty/egl/CameraPreviewRenderer.kt`
- **Expected Change**:
  1. 在 `FrameSyncConfig` 中新增 `missingThresholdFrames: Int = 3` 字段
  2. 修改 `FrameSyncManager.query()`，当 `syncMode = STRICT` 且帧差 > `missingThresholdFrames` 时返回 `SyncStatus.MISSING`
  3. 在 `CameraPreviewRenderer.applySyncResultToRenderer()` 中，当 `syncStatus = MISSING` 时设置 `uHasFace = 0f`
  4. 更新 `BeautyPerfStats`，增加 `framesSinceDetection` 字段
- **DependsOn**: fsm-001, fsm-002
- **EstimatedEffort**: 2d
- **Priority**: P0
- **Acceptance**: AC-P0-3

python scripts/parse_kimi_tasks.py \
  --input docs/03-TECHNICAL-SPECS/FRAME_SYNC_TECH_SPEC.md \
  --output tasks/frame-sync-tasks.json

{
  "source": "docs/03-TECHNICAL-SPECS/FRAME_SYNC_TECH_SPEC.md",
  "extracted_at": "2026-05-14T10:00:00Z",
  "tasks": [
    {
      "task_id": "fsm-005",
      "title": "FR-5：严格缺失处理",
      "assignee": "RD",
      "scope": [
        "beauty-engine/src/main/java/com/picme/beauty/internal/framesync/FrameSyncManager.kt",
        "beauty-engine/src/main/java/com/picme/beauty/egl/CameraPreviewRenderer.kt"
      ],
      "expected_change": [
        "在 FrameSyncConfig 中新增 missingThresholdFrames: Int = 3 字段",
        "修改 FrameSyncManager.query()...",
        "在 CameraPreviewRenderer.applySyncResultToRenderer()...",
        "更新 BeautyPerfStats..."
      ],
      "depends_on": ["fsm-001", "fsm-002"],
      "estimated_effort": "2d",
      "priority": "P0",
      "acceptance": "AC-P0-3",
      "status": "pending"
    }
  ]
}

## 6. 版本规划（含 [kimi-task]）

### Phase 1：基础设施（1~2 周）

#### FrameId 体系 [kimi-task:fsm-001]
- **Assignee**: RD
- **Scope**: `beauty-engine/src/main/java/com/picme/beauty/api/FrameId.kt`
- **Expected Change**:
  1. 创建 `@JvmInline value class FrameId(val value: Long)`
  2. 实现 `AtomicLong` 计数器，`next()` 方法
  3. 定义 `INVALID = FrameId(0L)`
- **EstimatedEffort**: 4h
- **Priority**: P0
- **Acceptance**: AC-P0-1

#### FrameSyncManager 骨架 [kimi-task:fsm-002]
- **Assignee**: RD
- **Scope**: `beauty-engine/src/main/java/com/picme/beauty/internal/framesync/FrameSyncManager.kt`
- **Expected Change**:
  1. 创建 `FrameSyncManager` 单例类
  2. 实现 `ResultStore`（`ConcurrentHashMap<FrameId, DetectionResult>`）
  3. 实现 `MatchEngine`：精确匹配 → 历史回退 → 预测补偿 → 缺失隐藏
  4. 实现 `query(currentFrameId)` 公共 API
- **DependsOn**: fsm-001
- **EstimatedEffort**: 2d
- **Priority**: P0
- **Acceptance**: AC-P0-1, AC-P0-2

#### DetectionQueue 改造 [kimi-task:fsm-003]

> **⚠️ 审计备注（2026-06）**：DetectionQueue 未落地（`DetectionQueue.kt` 不存在）。此 [kimi-task] 标记的目标文件路径无效。当前使用同步检测路径。如需实施异步检测改造，应先创建 DetectionQueue.kt 再更新此任务标记。

- **Assignee**: RD
- **Scope**: `beauty-engine/src/main/java/com/picme/beauty/internal/framesync/DetectionQueue.kt`（⏳ 设计中，未落地）
- **Expected Change**:
  1. 创建 `DetectionQueue` 类，深度限制 2，超时 200ms
  2. 改造人脸检测线程为消费队列模式
  3. 检测结果携带 `FrameId` 存入 `FrameSyncManager`
- **DependsOn**: fsm-002
- **EstimatedEffort**: 1d
- **Priority**: P0
- **Acceptance**: AC-P0-1

### Phase 2：时序对齐与严格缺失（1~2 周）

#### 渲染管线集成 [kimi-task:fsm-004]
- **Assignee**: RD
- **Scope**: `beauty-engine/src/main/java/com/picme/beauty/egl/CameraPreviewRenderer.kt`, `beauty-engine/src/main/java/com/picme/beauty/egl/BeautyRenderer.kt`
- **Expected Change**:
  1. `CameraPreviewRenderer` 渲染循环中调用 `FrameSyncManager.query(currentFrameId)`
  2. `BeautyRenderer` 新增 `updateSyncedFacePoints106()` + `setHasFace()`
  3. `FaceMakeupPass` 新增 `updateFaceLandmarksSynced()` 入口
- **DependsOn**: fsm-002, fsm-003
- **EstimatedEffort**: 2d
- **Priority**: P0
- **Acceptance**: AC-P0-2, AC-P0-3

#### 严格缺失处理 [kimi-task:fsm-005]
- **Assignee**: RD
- **Scope**: `beauty-engine/src/main/java/com/picme/beauty/internal/framesync/FrameSyncManager.kt`, `beauty-engine/src/main/java/com/picme/beauty/egl/CameraPreviewRenderer.kt`
- **Expected Change**:
  1. `FrameSyncConfig` 新增 `missingThresholdFrames: Int = 3`
  2. `query()` 严格模式：帧差 > 阈值时返回 `MISSING`
  3. `applySyncResultToRenderer()`：`MISSING` 时 `uHasFace = 0`
- **DependsOn**: fsm-004
- **EstimatedEffort**: 1d
- **Priority**: P0
- **Acceptance**: AC-P0-3

#### 调试指标接入 [kimi-task:fsm-006]
- **Assignee**: RD
- **Scope**: `beauty-engine/src/main/java/com/picme/beauty/api/BeautyPerfStats.kt`, `app/src/main/java/com/mamba/picme/features/camera/debug/PerfOverlay.kt`
- **Expected Change**:
  1. `BeautyPerfStats` 增加 `detectionLatencyMs` / `syncStatus` / `predictedOffsetPx` / `framesSinceDetection`
  2. 调试浮层展示新增指标
- **DependsOn**: fsm-004
- **EstimatedEffort**: 1d
- **Priority**: P1
- **Acceptance**: AC-P1-2

### Phase 3：预测补偿与录制专项（1~2 周）

#### MotionTracker 速度外推 [kimi-task:fsm-007]
- **Assignee**: RD
- **Scope**: `beauty-engine/src/main/java/com/picme/beauty/internal/framesync/MotionTracker.kt`
- **Expected Change**:
  1. 创建 `MotionTracker` 类，保留最近 3 帧历史
  2. 实现 `predict(fromFrameId, toFrameId, maxRatio)` 速度外推
  3. 位移约束：不超过上一帧位移的 150%
- **DependsOn**: fsm-002
- **EstimatedEffort**: 2d
- **Priority**: P1
- **Acceptance**: AC-P1-1

#### 录制场景帧同步验证 [kimi-task:fsm-008]
- **Assignee**: QA
- **Scope**: `app/src/androidTest/java/com/mamba/picme/camera/VideoRecordingSyncTest.kt`
- **Expected Change**:
  1. 编写录制快转头测试用例
  2. 编写录制人脸出画入画测试用例
  3. 逐帧分析录制视频，验证妆容偏差
- **DependsOn**: fsm-004, fsm-005
- **EstimatedEffort**: 2d
- **Priority**: P0
- **Acceptance**: AC-P0-5