视觉资产与构建基线

状态：当前有效
更新日期：2026-07-22
适用范围：正式运行时图片、可重建视觉资产、构建清单、质量报告与 MuMu 视觉验收

一、所有权边界

视觉资产分为两类，不能用同一套字段混写：

已提交二进制：由业务域运行时清单锁定路径、像素尺寸、透明度、字节数与 SHA-256；它们的 provenance 必须为 committed-binary，且 rebuildable 必须为 false。
可重建资产：由 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，顺序为：

显式 PYTHON；
design-pipeline/.venv；
Windows Python Manager 的真实入口；
可实际执行的系统命令。

所有 Python 构建和测试都通过统一执行器加入 -B，禁止在源码目录生成 __pycache__ 或 .pyc。不透明缩放、居中 cover 裁切与暖金边框提取统一由 design-pipeline/scripts/build_raster_assets.py 实现，Node 入口只负责严格清单校验、解释器编排和质量审计，不再保留 G01、模块背景或 Sharp 专用分支。

四、当前验证命令

在 design-pipeline/ 目录运行：

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 -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 构建链。不得重新引入候选入口、虚构可重建关系或在文档复制正式输出哈希。

7.8 KiB Raw Blame History Unescape Escape