1.1 问题背景#

业务里有一类需求非常典型：同一套内容模板，要投放到不同场景（不同数据源、主题、语言），适配不同画幅（横屏 16:9、竖屏 9:16、方屏 1:1、异形分辨率的设备屏）。

最直觉的写法是每个组合写一份布局代码。组合数量是 模板 N × 场景 M × 画幅 K——我们当时 N=12、M=5、K=8，理论组合 480 种。即使大量组合共享逻辑，代码里也长满了这种分支：

1
// 反例：组合爆炸的分支代码
2
if (template === 'poster' && scene === 'retail') {
3
  if (ratio === '9:16') { /* 一套布局逻辑 */ }
4
  else if (ratio === '16:9') { /* 又一套 */ }
5
}

后果是：新增一个画幅要改 12 个模板；一个布局 bug 要在多个分支里修多次；测试矩阵没法穷举，线上适配问题层出不穷。

1.2 设计思路：把组合从代码空间搬到配置空间#

核心决策：代码只实现”渲染规则”，配置描述”具体组合”。架构分四层：

1
┌─────────────────────────────────────────────┐
2
│ Schema 层   元素结构 + 可变属性声明           │
3
├─────────────────────────────────────────────┤
4
│ 约束层     画幅适配规则（对齐/伸缩/溢出策略）  │
5
├─────────────────────────────────────────────┤
6
│ 场景层     数据源/主题/语言 变量注入           │
7
├─────────────────────────────────────────────┤
8
│ 运行时     统一渲染管线（Konva / DOM 双渲染器）│
9
└─────────────────────────────────────────────┘

1.3 关键设计细节#

① Schema：声明”有什么”，不声明”怎么摆”

1
{
2
  "template": "poster-v2",
3
  "elements": [
4
    {
5
      "id": "title",
6
      "type": "text",
7
      "binding": "$.data.productName",   // 数据绑定表达式
8
      "style": { "fontSize": 64, "fontWeight": 700 },
9
      "constraints": { "align": "top-stretch", "minScale": 0.6, "overflow": "shrink-to-fit" }
10
    },
11
    {
12
      "id": "qrcode",
13
      "type": "image",
14
      "constraints": { "align": "bottom-right", "fixedRatio": true, "minSize": 120 }
15
    }
16
  ]
17
}

② 约束求解：画幅变化 ≠ 等比缩放

这是最容易做错的地方。等比缩放会导致竖屏上标题小到不可读、二维码超出安全区。我们为每个元素声明伸缩优先级和溢出策略：

• align：锚定规则（吸顶、吸底、拉伸、居中）；
• priority：空间不足时的压缩顺序——先压缩装饰元素的留白，再缩文字（不低于 minScale），最后才对非关键元素执行 overflow: hide；
• safeArea：画幅级的安全区声明，任何元素不得溢出。

求解器在渲染前跑一遍，输出一套针对当前画幅的绝对布局结果，渲染器只负责画，不含任何适配逻辑：

1
function solve(schema: TemplateSchema, viewport: Viewport): LayoutResult {
2
  const anchored = applyAnchors(schema.elements, viewport);      // 锚定
3
  const fitted = resolveOverflow(anchored, viewport.safeArea);   // 按优先级压缩/裁切
4
  return assertConstraints(fitted, viewport);                    // 约束校验，违反即构建期报错
5
}

③ 场景注入：模板不感知场景

场景差异（数据接口、主题色板、语言、字体栈）全部收敛为一份 SceneContext，在 Schema 解析阶段完成变量替换。模板作者永远只面对一份 Schema。

④ 类型与校验前置

Schema、约束、场景上下文全部有 TypeScript 类型定义，配置错误在编译期暴露；发布流水线里增加一步”全画幅渲染快照比对”，任何组合渲染异常直接拦截发布。

1.4 收益与复盘#

• 新增一个画幅：从”改 N 个模板 + 全量回归”变成”写一份画幅约束配置 + 快照验证”；
• 模板代码量下降约 60%，布局 bug 修复从多处收敛为求解器单点；
• 最重要的经验：配置驱动的边界要划清——规则进代码，组合进配置。曾有人提议把”元素的动画时序”也做成配置，结果配置 DSL 复杂到没人会写，后来退回代码层用预设动画承接。配置化不是越多越好，配置的复杂度也是一种代码。

2.1 需求场景#

用户在设计器里编辑 2D 画面（Konva 画布），需要实时预览”这个画面贴到 3D 样机/屏幕/展架上”的效果，并且可以直接在 3D 视图里点选、拖拽 2D 元素——所见即所得的 2D↔3D 联动。

2.2 技术方案：CanvasTexture 单向数据流 + UV 反向交互#

① 2D → 3D：CanvasTexture

Konva 的 Layer 本质是 <canvas> 元素，可直接作为 Three.js 纹理源：

1
const konvaCanvas = konvaLayer.getCanvas()._canvas;
2
const texture = new THREE.CanvasTexture(konvaCanvas);
3
texture.colorSpace = THREE.SRGBColorSpace;
4
mesh.material = new THREE.MeshBasicMaterial({ map: texture });

② 更新节流：一帧最多上传一次

每次 Konva 重绘都置 texture.needsUpdate = true 会把 GPU 带宽打满（纹理上传是同步开销）。正确做法是用 rAF 合并脏标记：

1
let dirty = false;
2
stage.on('draw', () => { dirty = true; });
3

4
renderer.setAnimationLoop(() => {
5
  if (dirty) {
6
    texture.needsUpdate = true;
7
    dirty = false;
8
  }
9
  renderer.render(scene, camera);
10
});

同时按 3D 场景的实际展示尺寸对画布降采样——2D 编辑画布可能是 4K 的，3D 预览里贴图 1080p 足够，显存直接省 4 倍。

③ 3D → 2D：射线检测 + UV 反算

在 3D 场景点击模型表面时：

1
raycaster.setFromCamera(pointerNdc, camera);
2
const hit = raycaster.intersectObject(mesh)[0];
3
if (hit.uv) {
4
  // UV(0~1) 反算到 2D 画布坐标系
5
  const x = hit.uv.x * konvaStage.width();
6
  const y = (1 - hit.uv.y) * konvaStage.height();  // 注意 V 轴翻转
7
  // 把点击事件转发给 Konva 命中系统
8
  const shape = konvaLayer.getIntersection({ x, y });
9
  shape?.fire('click', { evt: syntheticEvent });
10
}

拖拽同理：射线持续求交，把 UV 位移量换算成 Konva 节点的 dragBoundFunc 约束内位移。

2.3 踩坑记录#

1. UV 翻转：Canvas 的 Y 轴向下、纹理 V 轴向上，忘了翻转会导致交互位置上下镜像；
2. 纹理色偏：不做 SRGBColorSpace 声明，贴图颜色在 3D 光照下明显发灰；
3. 大画布显存：mipmap 开启后显存 +33%，非正交视角下建议开、正视 UI 场景可以关；
4. 双渲染循环打架：早期版本 Konva 和 Three.js 各跑各的 rAF，帧率互相抖动。合并为单一动画循环驱动两者后稳定。

2.4 架构原则#

这套协同能长期维护的关键是职责单向：2D 画布是内容的唯一真相源（single source of truth），3D 只是它的一个”观察者 + 交互代理”；交互事件可以回流，但 3D 层永远不直接改内容数据。一旦允许双向随意写，状态同步会变成噩梦。

3.1 整体架构#

产品形态是”Web 技术栈的桌面应用 + 外接硬件（UVC 摄像头等外设）“，同一份前端产物还要跑在浏览器和移动 WebView 里做降级体验。架构分三层：

1
┌────────────────────────────────────────┐
2
│ 业务层（React）—— 只依赖统一能力接口      │
3
├────────────────────────────────────────┤
4
│ Bridge SDK —— 能力探测 / 协议版本协商     │
5
├──────────┬──────────┬──────────────────┤
6
│ WebView  │ 桌面IPC   │ 浏览器降级        │
7
│ Adapter  │(N-API)   │(WebRTC/WebAPI)   │
8
└──────────┴────┬─────┴──────────────────┘
9
                │
10
        C++ 设备 SDK（独立子进程）

3.2 N-API 桥接 C++ SDK#

设备 SDK 是 C++ 回调风格，N-API 封装的三个关键点：

① ThreadSafeFunction 跨线程回抛

设备事件（帧数据、状态变化）来自 C++ 工作线程，必须用 napi_threadsafe_function 安全地调度回 JS 主线程，直接在非 JS 线程调 napi 函数会崩溃。

② 回调转 Promise/EventEmitter

1
// 封装后的对外 API：一次性指令走 Promise，持续事件走 EventEmitter
2
const devices = await deviceBridge.enumerate();          // Promise
3
deviceBridge.on('frame', (frame: FrameBuffer) => {});    // 事件流
4
deviceBridge.on('stateChange', (s: DeviceState) => {});

③ 帧数据的背压控制

摄像头 30fps 出帧，JS 侧渲染消费不了 30fps 时，绝不能让帧在队列里堆积（内存暴涨 + 延迟累积）。策略：只保留最新帧（drop-old），共享内存传帧 + 元数据消息通知，JS 侧 rAF 消费。

3.3 设备状态机：热插拔是最大的敌人#

USB 设备随时可能插入、拔出、被其他进程占用、固件异常。我们把设备生命周期建模为显式状态机：

1
disconnected → connecting → ready ⇄ busy
2
                    ↓           ↓
3
                  error ←───────┘
4
                    ↓
5
              reconnecting（指数退避）→ connecting

• 每次状态迁移广播事件，UI 层只做订阅式防御渲染——任何界面元素都假设设备可能在下一帧消失；
• 重连成功后必须重新协商会话（分辨率、帧率、控制参数），不能复用断开前的状态；
• 设备被占用（另一个进程持有）时给出明确错误码和文案，这类”环境问题”占了客服工单的大头。

3.4 崩溃隔离#

C++ SDK 崩溃不能带走客户端主进程：SDK 跑在独立子进程，通过 IPC 通信；主进程心跳监控，异常退出自动拉起并驱动状态机进入 reconnecting。上线后 SDK 崩溃对用户的表现从”应用闪退”降级为”设备短暂断开后自动恢复”。

3.5 复盘#

前端工程师做到这一层的价值：排查半径覆盖全链路。“画面不出来”这种问题，可能出在 USB 枚举、格式协商、N-API 桥、帧消费、渲染层任何一环——只懂 JS 的人只能把问题踢给客户端团队等排期，能读 C++ 日志、能抓 USB 描述符的前端可以当场定位到层。

4.1 为什么需要离线包#

Hybrid 场景下 H5 走线上 URL 有两个死穴：

1. WebView 缓存策略不可控，新版本资源”半新半旧”是常态；
2. 弱网/无网环境（门店、展厅、交通工具）直接白屏。

离线包方案：静态资源打包下发到客户端本地，WebView 通过资源拦截（Android shouldInterceptRequest / iOS WKURLSchemeHandler）读本地文件，加载耗时从秒级降到几十毫秒，且天然支持无网运行。

4.2 差量更新设计#

全量包动辄几十 MB，每次发版全量下载不可接受。差量方案：

① 版本清单（manifest）

1
{
2
  "version": "20260915.3",
3
  "baseVersion": "20260901.1",        // 差量基准
4
  "files": [
5
    { "path": "assets/index.8f3a.js", "hash": "8f3a...", "size": 421337 },
6
    { "path": "assets/vendor.c21b.js", "hash": "c21b...", "size": 892011 }
7
  ],
8
  "signature": "..."                   // 包签名
9
}

② 更新流程

1
客户端上报当前 version + 文件哈希表
2
        ↓
3
服务端 diff → 返回变更文件清单（增/删/改）
4
        ↓
5
并发下载变更文件（大文件可选 bsdiff 二进制差量）
6
        ↓
7
写入 staging 临时目录 → 逐文件哈希校验
8
        ↓
9
全部通过 → 原子切换版本指针 → 清理旧版本（保留上一版）

③ 三个保命设计

• 原子切换：更新过程中 WebView 读到的永远是完整的旧版本，绝不存在”半更新”状态被加载；
• 自动回滚：新版本启动后若崩溃计数超阈值（如 3 次），自动回退上一版本并上报，坏包影响面被限制在一个发布批次内；
• 签名校验 + 防降级：包体签名防篡改；版本号单调递增校验，防止中间人诱导回滚到有漏洞的旧版。

4.3 收益#

• 发版触达：从”用户下次冷启动 + 缓存过期”的天级，变为推送后分钟级；紧急 bugfix 不再依赖 WebView 缓存玄学；
• 流量：典型迭代差量包只有全量的 10%~20%；
• 首屏：本地资源加载让弱网环境首屏时间从 3s+ 降到 500ms 内。

5.1 问题：AI 写代码快，但”不敢合”#

直接用自然语言让 AI 写功能，产出看起来像模像样，合入时却心里没底：边界条件漏了没有？改动有没有波及无关逻辑？测试是谁写的——AI 自己写测试给自己打分，等于没有测试。

AI 辅助研发的瓶颈从来不是生成速度，而是验证成本。

5.2 工作流设计#

我把协作流程规范成四步，核心思想是把人的精力从”审查代码”前移到”审查规范与计划”：

Step 1 — Spec 先行（人主导，AI 起草）

需求先收敛为结构化 spec：

1
## 背景
2
## 目标（可验收的行为描述）
3
## 非目标（明确不做什么）
4
## 边界与异常（空数据/超时/并发/权限）
5
## 验收标准（Given-When-Then 列表）

模糊需求在这一步被逼着显形——写不出验收标准，说明需求本身没想清楚，这时候写代码（无论人写还是 AI 写）都是浪费。

Step 2 — 测试先行（AI 生成，人裁决）

让 AI 把验收标准翻译成测试用例。先审测试再审实现：测试用例是否覆盖边界、断言是否精确、有没有”实现什么就断言什么”的同义反复。测试通过了人的裁决，才允许进入实现。

Step 3 — 实施计划（AI 生成，人审查）

AI 输出改动计划：涉及文件清单、每个文件的改动意图、每步的验证命令。人审查的是计划的合理性（有没有不该动的文件被动了、步骤是否可独立验证），而不是等代码写完再审 diff。

Step 4 — 执行 + 行级归因

AI 按计划实施，每步测试绿灯再进下一步。最终 diff 做行级归因：

• 每一行改动对应 spec 的哪一条？
• 归因不到的改动 = 未经授权的发挥，一律拒收或补 spec；
• 关键路径代码人工重写或逐行确认，AI 负责脚手架、测试和样板。

5.3 工程化配套#

• 自定义 Skill：把团队规范固化为可复用的 AI 技能——按组件模板生成”组件 + 测试 + 文档”三件套、按 commit 规范生成提交信息，保证 AI 产出天然符合团队约定；
• MCP 工具链：接入内部文档库、监控平台、设计稿系统，AI 能直接查线上错误堆栈、读接口文档，减少人工喂上下文的损耗；
• CI 卡口：AI 参与的 PR 走同一套门禁（类型检查、测试覆盖率、性能预算），不因为是 AI 写的就降低标准，也不因为是 AI 写的就额外怀疑。

5.4 效果与认知#

• 在需求清晰的任务上（表单页、接口对接、工具函数、测试补全），从需求到可合入 PR 的周期缩短约 50%~70%；
• 在需求模糊的任务上，流程强制把”想清楚”前置，返工率明显下降——这部分收益比速度更重要；
• 最大的认知转变：AI 时代前端工程师的稀缺能力是”把需求写成无歧义规范”和”设计验证闭环”。生成代码会越来越便宜，定义”什么是对的”永远贵。