# 家谱 APP 设计资产生产流水线规范

> 状态：已批准并完成 A01 卷轴祥云四件套 v3 的本机 H5 试点；仍待 Android/HBuilderX、跨电脑复现和用户正式验收。
> 更新日期：2026-07-16。
> 适用范围：本项目后续页面重设计、独立视觉资产生产、跨电脑恢复与质量审计。
> 当前边界：manifest v2、Python/Pillow 质量门和 A01 主按钮、次按钮、Toast、验证弹窗四张 v3 资产已经落地并通过本机 H5 四尺寸检查；这不代表 Android 已复核、用户已验收或流水线可以推广到其他页面。

## 1. 目标

本项目采用“混合落地”方式，不把所有视觉都做成整张位图，也不把复杂国风装饰退化为临时 CSS 或手绘 SVG。

目标是：

1. 设计稿中的布局、文字、间距、状态和普通结构由 Vue/SCSS 负责。
2. 复杂水墨、宗祠、品牌印、专用图标和难以代码复现的装饰由真实位图资产负责。
3. 可复用且需要伸缩的装饰框优先进入经过 Android/H5 验证的九宫格或组件化资产方案。
4. Node.js、Sharp 与 Python 读取同一份 JSON manifest，禁止在脚本、页面和文档中重复维护尺寸规则。
5. 自动化负责消除机械错误；真实运行截图和用户逐页审核仍是最终视觉判断来源。

流水线不能保证任意扁平设计图自动拆成一比一资产。要获得稳定质量，页面设计阶段必须同时明确组件边界、目标槽位、伸缩策略和独立资产任务。

## 2. 已有雏形与升级原则

仓库现有可复现雏形：

- `design-pipeline/package.json`
- `design-pipeline/package-lock.json`
- `design-pipeline/manifests/a01.json`
- `design-pipeline/scripts/build-a01.mjs`
- `tests/a01-code-pipeline-contract.ps1`

原 schema v1 雏形已经具备 Node.js、Sharp、JSON 清单、路径约束、尺寸/Alpha/体积检查和 A01 预览组合能力，但单独使用时仍不是合格的资产生产线，原因包括：

- 对所有资产统一使用 `fit: 'fill'`，不能阻止比例拉伸。
- manifest 只记录文件像素，不记录页面真实槽位和允许的缩放策略。
- 没有检查白边、绿边、半透明脏边、预乘 Alpha、色彩空间和边缘污染。
- 代码预览不是 uni-app 真实运行截图。
- `source === output` 主要保证换机可验证，不能替代新资产的生产与质量处理。

升级时保留已有目录、Node/Sharp 依赖和清单入口，不另建一条互相冲突的流水线。新合同升级为 manifest v2；A01 试点通过前不得批量迁移其他页面。

2026-07-16 已实现的 v2 试点包括：

- `design-pipeline/manifests/a01-buttons-v2.json`：尺寸、槽位、缩放、透明边、质量阈值和消费者的单一机器合同。
- `design-pipeline/scripts/rebuild-a01-buttons.mjs` 与 `rebuild_a01_buttons.py`：Node 编排、Pillow 横向三段式离线重建。
- `design-pipeline/scripts/verify-assets.mjs`、`verify-assets.py` 与 `asset_quality.py`：尺寸、Alpha 外圈、绿边、浅色半透明边、透明 RGB、体积和色彩声明检查。
- `design-pipeline/requirements.txt`：锁定 `Pillow==12.3.0`。
- Node/Python 单元测试、A01 静态契约、资产审计和四档 H5 运行时检查。

在双按钮试点基础上，用户选择“方案 2：卷轴祥云”并批准扩展为四件套 v3：

- `design-pipeline/manifests/a01-scroll-skins-v3.json`：四件套源母图、输出槽位、缩放、透明边、体积和消费者的唯一机器合同。
- `build-a01-scroll-skins.mjs`、`build_scroll_skins.py`：Node 编排与 Pillow 确定性构建；构建会清除外缘绿边、浅色半透明脏边和透明 RGB 残留。
- 主／次按钮和弹窗按固定比例等比输出；Toast 输出可切片透明 PNG，由页面 `border-image` 承担自适应宽度。
- 弹窗采用带透明度表的索引 PNG 控制体积，质量门读取真实透明通道，不通过放宽阈值换取通过。

旧 schema v1 仍保留给现有 A01 预览流程；不得把它的 `fit: 'fill'` 规则复制到 v2 固定比例资产。

## 3. 资产分类与唯一落地方式

每个设计元素在 manifest 中只能属于以下一种主要类型：

| 类型 | `assetClass` | 正确落地 | 典型内容 |
| --- | --- | --- | --- |
| 代码原生 | `code-native` | Vue/SCSS | 布局、文字、间距、纯色、普通分隔线、状态与交互 |
| 固定比例位图 | `fixed-bitmap` | 精确槽位比例的 PNG/WebP，不允许变形 | 宗祠头图、复杂水墨、固定比例品牌视觉面 |
| 透明叠加资产 | `transparent-overlay` | 干净 RGBA PNG/WebP | Logo、印章、云纹、专用图标、结饰 |
| 可伸缩装饰框 | `nine-slice` | 经 H5/Android 验证的九宫格或等价组件 | 多宽度按钮框、卡片框、弹窗框 |
| 平铺纹理 | `tile-texture` | 明确的重复或覆盖策略 | 小尺寸宣纸纹、无方向噪声纹理 |

禁止：

- 把整页设计截图或局部页面截图直接裁入运行页面。
- 用 emoji、文本符号、临时第三方 SVG、CSS 拼画代替缺失的品牌装饰或图标。
- 同一资产既声明固定比例又在页面中随意拉伸。
- 未经 manifest 授权使用 `scaleToFill` 或 Sharp `fit: 'fill'`。
- 把候选图、审阅图、runtime 截图或 `generated/` 中间文件当成唯一正式源。

## 4. 单一 manifest v2 合同

manifest 是资产生产、页面接入和质量验证的唯一机器可读所有者。建议结构：

```json
{
  "schemaVersion": 2,
  "page": "A01",
  "assets": [
    {
      "id": "a01-primary-button-v2",
      "assetClass": "fixed-bitmap",
      "source": "static/assets/foundation/transparent/a01-primary-button-v2.png",
      "output": "static/assets/foundation/transparent/a01-primary-button-v2.png",
      "logicalSlot": {
        "widthRpx": 622,
        "heightRpx": 92
      },
      "outputPixels": {
        "width": 1866,
        "height": 276
      },
      "render": {
        "scalePolicy": "uniform-only",
        "uniMode": "aspectFit",
        "allowDistortion": false
      },
      "alpha": {
        "required": true,
        "transparentOutsideFrame": true,
        "cornerMaxAlpha": 0
      },
      "edge": {
        "forbidChromaResidue": true,
        "forbidLightFringe": true,
        "premultipliedAlphaCheck": true
      },
      "quality": {
        "maxBytes": 500000,
        "symmetry": "horizontal",
        "colorSpace": "sRGB"
      },
      "consumers": [
        "pages/auth/a01-entry.vue"
      ]
    }
  ]
}
```

正式实现时应为 schema v2 编写 JSON Schema 或等价的严格校验器。未知字段、缺失字段、越出工作区的路径、重复 ID 和未登记消费者都应尽早失败。

## 5. Node.js 与 Sharp 的职责

Node.js 是流水线编排层，继续复用当前 `design-pipeline/`：

1. 解析并校验 manifest。
2. 检查路径只能位于工作区内。
3. 调用 Sharp 读取元数据、裁切、等比缩放、格式转换、压缩和预览组合。
4. 根据 `scalePolicy` 选择算法；`uniform-only` 禁止 `fit: 'fill'`。
5. 扫描 Vue/SCSS 中的资产引用、`mode` 和显示槽位。
6. 检查资源比例与页面逻辑槽位比例，默认容差不超过 0.5%。
7. 禁止页面引用未进入 manifest 的新视觉资产。
8. 生成包含 SHA-256、尺寸、字节数、Alpha、消费者和检查结果的构建报告。
9. 使用现有 Chrome CDP 9222 对真实 H5 页面做尺寸、资源加载和局部截图验证。

Node/Sharp 不负责艺术判断，也不把代码组合预览当作用户验收证据。

## 6. Python 的职责

Python 是像素质量层，建议使用 Pillow；只有 Pillow 无法稳定完成的边缘分析再引入 OpenCV，避免不必要的重依赖。

职责：

1. 验证 PNG/WebP 解码、实际尺寸、通道数和 sRGB 色彩空间。
2. 检查透明角、外框外 Alpha、可见内容边界和空白边距。
3. 检测绿幕残留、异常高亮边缘和半透明脏边。
4. 对透明边缘执行去污染与正确的 Alpha 处理，避免 Android 缩放后出现白边或绿边。
5. 检查预乘 Alpha 风险；完全透明像素不得保留会渗出的异常 RGB。
6. 对要求对称的按钮和装饰框检查左右差异。
7. 生成局部边缘放大图、资产联系表和机器可读报告。
8. 质量不达标时返回非零退出码，禁止继续接入页面。

白边检测不能简单地“禁止白色”，因为次按钮内部可能本来就是暖白宣纸。检查必须只针对外框外区域、半透明边界和 manifest 声明的允许色板。

## 7. 资产生产流程

### 7.1 设计阶段

设计或 ImageGen 输出页面方向时，同时登记：

- 页面逻辑尺寸和目标视口。
- 组件边界与逻辑槽位。
- 哪些内容必须由代码渲染。
- 哪些内容需要独立透明资产。
- 哪些装饰允许伸缩以及不可伸缩安全区。
- 字体、字号、颜色和状态。

不接受只有一张扁平页面图而没有资产任务单的“最终设计”。

### 7.2 候选生产

1. 只有缺少完整位图资产时使用 ImageGen。
2. 输入图必须明确角色：编辑目标、风格参考或组合参考。
3. 生成内容不包含应由代码渲染的按钮文字、表单文字和状态文案。
4. 中间候选进入忽略目录，不覆盖正式资产。
5. 选择一个母图后再进入确定性处理；候选图不长期堆入仓库。

ImageGen 的艺术输出不能保证跨电脑逐像素复现。跨电脑可复现的是“已选择母图之后的处理、验证和页面接入”。需要长期重建的唯一母图必须进入受控正式路径或由最终资产本身承担稳定输入。

### 7.3 确定性处理

1. 按 manifest 裁切或补透明边距。
2. 以目标槽位比例导出 2×/3×文件。
3. 清理 Alpha、白边、绿边和异常 RGB。
4. 转为 sRGB，使用高质量等比缩放。
5. 输出新的版本化文件，不直接覆盖当前正式资产。
6. Python 质量门通过后，才允许更新页面引用。

### 7.4 页面接入

1. 先写或调整资产合同并看到预期失败。
2. 页面使用 manifest 指定的渲染模式。
3. 文字、图标和交互状态保持独立可访问节点。
4. 只在真正需要叠层的地方使用定位；普通内容保持正常布局流。
5. 禁止为了匹配截图而恢复错误比例或无依据的定位。

### 7.5 运行验证

最低验证层级：

1. manifest/schema 合同。
2. Python 像素质量检查。
3. Node/Sharp 构建和引用检查。
4. H5 Chrome 真实运行：320×568、360×640、360×800、412×915。
5. 一张代表图或一张复杂状态联系表。
6. Android/HBuilderX 真机或模拟器复核。
7. 用户明确逐页验收。

H5、自动截图差异、内部 smoke 和 GPT 审视都不能替代第 6、7 层。

## 8. 质量门槛

### 8.1 通用门槛

- 输出像素必须与 manifest 完全一致。
- 固定比例资产与逻辑槽位比例误差默认不超过 0.5%。
- `uniform-only` 资产不得出现非等比缩放。
- PNG 声明透明时必须真正包含 Alpha 通道。
- 声明透明角时，指定角点 Alpha 必须为 0。
- 禁止绿幕残留和未授权的浅色外缘。
- 文件必须为 sRGB；不得依赖另一台电脑上的专有字体、PSD 或本机临时目录。
- 体积超过 `maxBytes` 时失败，不通过降低清晰度或删除证据掩盖。

### 8.2 固定按钮门槛

- 图片中不包含按钮文字和微信图标。
- 外框之外透明，内部视觉面完整。
- 四角、双边和装饰连续，不得出现切口或拼接缝。
- 3×输出缩小到真实槽位后，金线仍连续且不过度发虚。
- 按钮点击区域由代码控制，不由图片透明区决定。

### 8.3 自动差异的边界

截图差异只比较同视口、同状态和同字体环境。字体抗锯齿、WebView 与 Chrome 的细小差异不能用单一全屏像素阈值判死刑；应优先比较资产局部裁图、尺寸、边缘和结构，再由人工判断整体视觉。

## 9. A01 卷轴祥云资产试点

流水线首先用两张 v2 按钮验证固定槽位，随后按用户选定方向升级为四件套 v3。当前 A01 实际引用：

- `a01-scroll-primary-v3.png`：`1866×276px`，登录主按钮。
- `a01-scroll-secondary-v3.png`：`1866×300px`，微信次按钮。
- `a01-scroll-toast-v3.png`：`1770×246px`，反馈 Toast 九宫格／切片表面。
- `a01-scroll-dialog-v3.png`：`1860×1560px`，安全验证弹窗表面。

当前 `a01-primary-button.png`、`a01-secondary-button.png` 的原始比例与页面槽位不一致，且次按钮外缘存在高亮白/浅绿色像素，不能作为新流水线质量样板。

本机 H5 试点结果：

- 四张 v3 输出通过尺寸、Alpha 外圈、透明 RGB、绿边、浅色半透明边、体积和色彩声明检查；旧资产和 v2 试点资产原样保留。
- A01 主／次按钮与弹窗使用 v3 路径和 `aspectFit`；Toast 使用 v3 切片资产；所有文字、微信图标和交互仍由页面代码独立承载。
- 自动质量门与 `320×568`、`360×640`、`360×800`、`412×915` H5 运行检查通过。
- 412×915 默认态、Toast 和验证弹窗真实运行截图未见原来的外缘白/浅绿边、角饰断裂或整体比例拉伸；仍需 Android/HBuilderX 与用户确认。

试点规则：

1. 保留当前资产，不覆盖、不删除。
2. 新资产使用版本化路径。
3. 先通过 Python/Node 自动质量门，再接入 A01。
4. 接入后只保存一张 412×915 代表图；四尺寸可以自动检查但不连续保存大量相似截图。
5. H5 通过只能写“内部候选”；Android 和用户确认之前，A01 仍为 `[~]`。
6. 只有用户确认试点资产质量达到标准，才把 manifest v2 和混合流水线推广到其他页面。

## 10. 跨电脑环境合同

### G01 列表背景候选扩展

2026-07-16 已把混合流水线扩展到 G 模块公共背景。A/B/C 历史母版、旗舰长屏原稿、1536×3840 归一化母版、准确提示和处理模式保存在 `docs/design/assets/g01-background/masters/` 与 `design-pipeline/manifests/g01-background-candidates.json`；`build-g01-backgrounds.mjs` 使用 Node 内置模块编排，`build_g01_backgrounds.py` 使用锁定的 Pillow 完成绿幕转 Alpha、去绿边、不透明归一化、Lanczos 锁定尺寸缩放、sRGB 写入和确定性 PNG 输出。用户已选择旗舰长屏方向，清单以 `selectedCandidateId` 和 `runtimeOutput` 记录唯一运行方向；正式输出为 `static/assets/modules/genealogy/opaque/genealogy-page-background-long.png`，G01、G03、G05、G06、G08、G09、G10、G11、G12 通过 `GenealogyPageBackground.vue` 共用。图片使用 `widthFix` 按页面宽度等比完整显示并固定贴底，左右不裁剪、不使用 `scaleToFill` 拉伸；1440×3600 长图覆盖当前最高压力档，不再拼接纯色上层。A/B/C 母版与旧 C 运行图仅作为历史输入／输出保留，不进入当前页面。

执行 `npm.cmd --prefix design-pipeline run build:g01-background-candidates` 可在另一台电脑从仓库母版重建 A/B/C 和旗舰长屏四个输出。模型重新生成不能保证逐像素一致；精确重建必须使用仓库内母版。完整步骤、当前哈希和质量基线见 `docs/design/G01_列表背景候选与换机重建.md`。

### 10.1 当前已可运行的 Node 雏形

新电脑需要 Windows、Node.js 22 或更高版本、npm、HBuilderX、Chrome 和项目完整工作区。当前 Node 24 已验证可用。

```powershell
node --version
npm --version
npm.cmd ci --prefix design-pipeline
npm.cmd --prefix design-pipeline run build:a01
powershell.exe -NoProfile -ExecutionPolicy Bypass -File tests/a01-code-pipeline-contract.ps1
```

这些命令只证明现有 schema v1 雏形可运行，不证明新质量门已经实现。

### 10.2 manifest v2 的 Python 环境

`design-pipeline/` 已提供锁定依赖、统一 Node 入口和 Python 质量脚本；不得要求接管者凭经验安装不确定版本。当前结构：

```text
design-pipeline/
  package.json
  package-lock.json
  requirements.txt
  manifests/
  scripts/
    rebuild-a01-buttons.mjs
    rebuild_a01_buttons.py
    verify-assets.mjs
    verify-assets.py
  generated/          # 忽略，可再生成
```

恢复和验证命令：

```powershell
python --version
python -m venv design-pipeline/.venv
design-pipeline/.venv/Scripts/python.exe -m pip install --upgrade pip
design-pipeline/.venv/Scripts/python.exe -m pip install -r design-pipeline/requirements.txt
npm.cmd ci --prefix design-pipeline
npm.cmd --prefix design-pipeline run test:v2
npm.cmd --prefix design-pipeline run validate:a01-buttons
npm.cmd --prefix design-pipeline run rebuild:a01-buttons
npm.cmd --prefix design-pipeline run verify:assets
npm.cmd --prefix design-pipeline run validate:a01-scroll-skins
npm.cmd --prefix design-pipeline run build:a01-scroll-skins
npm.cmd --prefix design-pipeline run verify:a01-scroll-skins
design-pipeline/.venv/Scripts/python.exe -m unittest discover -s design-pipeline/tests -p "test_*.py" -v
```

Node 入口优先使用 `PYTHON` 环境变量，其次自动使用 `design-pipeline/.venv/Scripts/python.exe`，最后才回退到系统 `python`。本机已按以上依赖完成验证；跨电脑仍必须真实执行并保存输出，不能只因文件齐全就写成换机复现通过。

### 10.3 可迁移文件

至少保留：

- `design-pipeline/package.json`
- `design-pipeline/package-lock.json`
- 实施后新增的 Python 锁定依赖文件
- manifest、JSON Schema、构建/质量脚本和对应测试
- manifest 引用的正式资产
- 页面源码和真实截图工具
- 本规范、`docs/交接记录.md` 与 P00 资产台账

不得依赖：

- `node_modules/`
- Python 虚拟环境
- `design-pipeline/generated/`
- `tmp/`
- 本机 Chrome 用户目录
- Photoshop/PSD
- 未进入仓库的候选图或 runtime 截图

## 11. 失败处理

- 依赖安装失败：停止并报告缺失环境，不绕过锁文件。
- manifest 不合法：修正单一数据源，不在页面里增加例外。
- 比例不匹配：回到目标槽位或重新导出，禁止 `fill` 掩盖。
- 白边/绿边：回到 Alpha 去污染步骤，禁止用页面背景色遮盖。
- H5 与组合预览不同：以真实 H5 为准并查明差异。
- H5 与 Android 不同：不得冻结资产，记录 WebView/字体/缩放差异后修正。
- 自动检查通过但用户认为不好看：状态仍为待审核，视觉判断以用户最新决定为准。

## 12. 推广条件

以下条件全部满足后，才能从 A01 推广：

1. A01 四张 v3 卷轴祥云资产通过 manifest、Python、Node 和四尺寸检查。
2. 412×915 真实 H5 代表图没有白边、绿边、拉伸或模糊。
3. Android/HBuilderX 已复核。
4. 用户明确确认四件套资产质量和 A01 整页达到标准。
5. 新电脑按文档能够从锁文件恢复环境并得到一致的质量报告。

当前仅满足第 1、2 项；第 3、4、5 项尚未满足。因此本规范和 A01 试点仍不是整项目推广或用户验收完成证明。