rain
98 lines
7.8 KiB
Markdown
98 lines
7.8 KiB
Markdown
# 视觉资产与构建基线
|
||
|
||
> 状态：当前有效
|
||
> 更新日期：2026-07-22
|
||
> 适用范围：正式运行时图片、可重建视觉资产、构建清单、质量报告与 MuMu 视觉验收
|
||
|
||
## 一、所有权边界
|
||
|
||
视觉资产分为两类，不能用同一套字段混写：
|
||
|
||
1. 已提交二进制：由业务域运行时清单锁定路径、像素尺寸、透明度、字节数与 SHA-256；它们的 `provenance` 必须为 `committed-binary`，且 `rebuildable` 必须为 `false`。
|
||
2. 可重建资产：由 schema v3 生成清单锁定母版、处理参数、物理输出尺寸和质量阈值；运行时清单只导入它，不复制物理规格。
|
||
|
||
schema v3 注册入口是 `design-pipeline/manifests/runtime-assets.json`。任何新增的 `runtime-asset-inventory` 或 `asset-build-manifest` 都必须进入该注册表的导入闭包；未注册 owner、重复资产 `id` 与重复正式输出都会被拒绝。当前 `static/assets` 中的每个文件都必须恰好属于一个正式 owner，并至少存在一个真实运行时消费者。
|
||
|
||
认证直接资产由 `design-pipeline/manifests/auth-runtime-assets.json` 管理，其余无法重建但仍被产品消费的直接二进制由 `design-pipeline/manifests/application-runtime-assets.json` 管理。四张共享卷轴、六张长页面背景和 G01 空态边框的生成事实依次只属于 `design-pipeline/manifests/shared-scroll-skins-v3.json`、`design-pipeline/manifests/page-backgrounds-v3.json` 与 `design-pipeline/manifests/g01-state-frame-v3.json`。
|
||
|
||
页面、组件、样式、数据映射和工具代码本身是消费者关系的唯一事实源。生成清单不得保存槽位、Vue 组件、选择器、`uni-app mode`、消费者列表或其他运行时渲染语义；这些规则只能由实际消费者源码及对应合同拥有。
|
||
|
||
## 二、schema v3 生成清单
|
||
|
||
生成清单只允许以下职责：
|
||
|
||
- `source`：仓库内可追溯母版；
|
||
- `processing`：实际由构建器消费的色键、端帽、调色板等处理参数；
|
||
- `output` 与 `outputPixels`：正式输出路径和像素尺寸；
|
||
- `alpha`、`edge`、`quality`：由质量分析器真实执行的透明边、边缘污染、体积和色彩空间约束。
|
||
|
||
清单、资产及其嵌套对象均拒绝未知字段。不能用近似字段名重新塞入旧合同，也不能声明构建器或质量分析器没有执行的规则。
|
||
|
||
## 三、Python 与依赖
|
||
|
||
Python 依赖由 `design-pipeline/requirements.txt` 锁定，当前 Pillow 版本为 `12.3.0`。唯一解释器解析逻辑位于 `design-pipeline/scripts/python-runtime.mjs`，顺序为：
|
||
|
||
1. 显式 `PYTHON`；
|
||
2. `design-pipeline/.venv`；
|
||
3. Windows Python Manager 的真实入口；
|
||
4. 可实际执行的系统命令。
|
||
|
||
所有 Python 构建和测试都通过统一执行器加入 `-B`，禁止在源码目录生成 `__pycache__` 或 `.pyc`。不透明缩放、居中 cover 裁切与暖金边框提取统一由 `design-pipeline/scripts/build_raster_assets.py` 实现，Node 入口只负责严格清单校验、解释器编排和质量审计，不再保留 G01、模块背景或 Sharp 专用分支。
|
||
|
||
## 四、当前验证命令
|
||
|
||
在 `design-pipeline/` 目录运行：
|
||
|
||
```powershell
|
||
npm.cmd test
|
||
npm.cmd run validate:shared-scroll-skins
|
||
npm.cmd run validate:page-backgrounds
|
||
npm.cmd run validate:g01-state-frame
|
||
npm.cmd run validate:runtime-assets
|
||
npm.cmd run build:shared-scroll-skins
|
||
npm.cmd run build:page-backgrounds
|
||
npm.cmd run build:g01-state-frame
|
||
npm.cmd run verify:shared-scroll-skins
|
||
```
|
||
|
||
其中 `npm.cmd test` 同时执行 Node 和 Python 测试。质量报告只允许保存工作区相对路径；同一母版与相同参数连续构建必须产生相同字节哈希和相同报告。
|
||
|
||
在项目根目录运行：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File tests/runtime-assets-contract.ps1
|
||
powershell -ExecutionPolicy Bypass -File tests/retired-asset-removal-contract.ps1
|
||
powershell -ExecutionPolicy Bypass -File tests/a01-retired-pipeline-removal-contract.ps1
|
||
powershell -ExecutionPolicy Bypass -File tests/a01-no-photoshop-pipeline-contract.ps1
|
||
powershell -ExecutionPolicy Bypass -File tests/mumu-visual-acceptance-boundary-contract.ps1
|
||
powershell -ExecutionPolicy Bypass -File tests/project-responsive-layout-contract.ps1
|
||
powershell -ExecutionPolicy Bypass -File tests/compile-audit.ps1
|
||
```
|
||
|
||
## 五、视觉验收
|
||
|
||
- 当前只维护用户确认的浅色国风主题；深色与跟随系统延期到后续独立版本，不能在页面内散落未生效的主题入口或覆盖样式。
|
||
- 内部响应式基线为 `320×568`、`360×640`、`360×800`、`412×915`；G01 连续长背景另做 `412×1000` 压力检查。这些内部尺寸不能替代最终 MuMu 证据。
|
||
- 浏览器截图只可用于逻辑调试，不能作为视觉通过证据。
|
||
- 仓库不再维护自动浏览器截图助手、联系表或截图自证合同；浏览器运行时测试只保留 CDP、DOM、状态、溢出和内容可达性断言，不写入截图。确需临时截图调试时应使用仓库外命令，不能提交为长期证据。
|
||
- 最终视觉复核只能使用用户当前在线的 MuMu 安卓模拟器，不得由代理启动、关闭或调整模拟器。
|
||
- 生成成功和像素质量通过不等于页面视觉通过；相关页面仍需在 MuMu 检查默认、错误、取消、完成和重复进入等实际状态。
|
||
- 不通过压缩字号、行高、控件尺寸或单设备补丁掩盖布局问题。
|
||
- 普通页面、卡片、表单和说明由内容自然撑高；只有弹窗和明确独立滚动区域可以使用视口 `max-height` 与内部滚动。
|
||
- 九宫格和 `border-image-slice` 的唯一所有者是 `styles/adaptive-frame-profiles.scss`；Vue 页面和组件只能消费其公开混入，不能直接重复声明。
|
||
- 响应式扫描范围只属于 `tests/responsive-layout-coverage.json`，固定尺寸例外只属于 `tests/responsive-layout-allowlist.json`。
|
||
- 安全区、软键盘、约 `1.3` 倍系统字号、长文本和 Android 返回手势必须在对应页面验证；主要触控目标不小于约 `44dp`。
|
||
- G 系列共享连续家谱背景，T、F、R、N、M 使用各自模块背景；具体消费者、渲染方式和当前视觉数值只由源码及机器合同拥有，本文件不复制尺寸、哈希、透明度或选择器。
|
||
- G 系列背景映射只由 `components/GenealogyPageBackground.vue` 消费，当前正式运行图是 `static/assets/modules/genealogy/opaque/genealogy-page-background-long.png`；T、F、R、N、M 的映射只由 `components/ModulePageBackground.vue` 消费。等比、裁切、贴底和透明度等渲染数值继续由这两个组件拥有。
|
||
- 复杂水墨、品牌装饰和完整视觉面使用正式位图；文字、布局、状态与交互由代码承担。整页截图不得成为运行时资产，可变高度装饰不得绕过共享九宫格所有者。
|
||
- 用户可见示例姓名统一使用“某某某”等通用表达；fixture 和 mock 数据可以保留真实感测试样本，但不能把样本姓名写成产品提示。
|
||
|
||
## 六、参考图与正式资产边界
|
||
|
||
以下两张图片是用户已批准的 A01 选型证据，只用于后续人工视觉复核，标记为 `reference-only / non-runtime`，不进入运行时注册表，也不能因零代码引用被删除：
|
||
|
||
- `docs/design/assets/a01-vnext/A01-shared-scroll-skins-with-dialog-approved.png`
|
||
- `docs/design/assets/a01-vnext/A01-shared-skin-family-option-2-selected.png`
|
||
|
||
G01 的 A/B/C 方向候选、无确定变换的 add-sheet/close 色键源、重复的旗舰 ImageGen 源、旧 `static/icons` 和未接入业务的 TAC 文件已经退役。正式 add-sheet 与 close 位图作为 `committed-binary` 由 `application-runtime-assets.json` 锁定；六张长背景及 G01 空态边框则保留可执行母版和 schema v3 构建链。不得重新引入候选入口、虚构可重建关系或在文档复制正式输出哈希。
|