# 家谱 APP 纯代码资产流水线设计规格

> 日期：2026-07-15
> 当前试点：A01 登录页
> 状态：等待用户复核规格，尚未开始实现

## 1. 目标

建立一条不依赖 Photoshop、Figma 或人工反向切图的资产生产链。复杂国风位图只在缺失时由 ImageGen 生成一次原始母图；之后的透明处理、裁切、缩放、组合、预览和运行资产导出全部由代码完成。整页设计预览与 uni-app 使用的独立 PNG 必须来自同一批源像素和同一份布局清单。

首轮只验证 A01，不修改其他 52 页。成功标准不是脚本能够输出图片，而是 A01 的代码预览、独立资产、uni-app 真实运行画面和验收规划中的页面合同能够形成可重复验证的闭环。

## 2. 当前版本范围

- 基础版本固定使用当前浅色国风主题。
- 深色与跟随系统整体延期到下一版本，不阻塞本轮 53 页验收。
- 下一版本增加主题时必须另建全局主题合同，并对已冻结页面执行影响分析和真实截图回归。
- 当前只做页面样式、视觉状态和 Android 兼容性，不对接接口，不宣称 Mock 状态代表功能通过。

## 3. 保留现场

- 现有 `docs/design/assets/a01-vnext/`、PSD、Photoshop 脚本、候选图片和历史证据全部保留。
- 不删除、不移动、不覆盖旧实验文件。
- Photoshop 生产链停止扩展，新流水线不得引用 Photoshop COM、JSX 或 PSD 作为运行依赖。
- 旧文件是否归档必须等 A01 新流水线和真实页面通过后另行决定。

## 4. 唯一所有者与目录边界

新流水线使用以下边界：

```text
design-pipeline/
  manifests/          页面、状态、图层、尺寸和导出合同
  sources/            经确认的原始母资产，只读输入
  scripts/            Node.js 渲染、切图、校验和报告脚本
  generated/          可再生成的设计预览、联系表和检查报告
static/assets/         用户确认后进入页面的正式运行资产
docs/design/screens/  真实运行截图证据，不作为页面资源
```

页面清单是坐标、状态、源文件、目标文件、尺寸和复用关系的唯一机器可读所有者。脚本和页面不得重新硬编码同一套资产规则；uni-app 页面只消费已确认的正式运行资产及必要布局常量。

## 5. 技术结构

- Node.js：命令入口、清单读取、状态遍历、输出隔离和失败报告。
- Sharp/libvips：Alpha、裁切、合成、缩放、PNG 优化、尺寸与体积检查。
- JSON：页面画布、图层顺序、资产槽位、状态差异和导出规格。
- ImageGen：只生成缺失的完整复杂位图母资产；不生成带表单文字的整页截图，不重绘现有 `brand-seal.png`。
- uni-app：最终页面实现与真实交互状态；不把整页设计预览当运行资产。

## 6. A01 首轮输出

同一次构建必须生成：

1. A01 独立透明 PNG 资产及尺寸、Alpha、SHA256 和文件体积报告。
2. 密码登录与短信验证码登录的 412×915 代表图。
3. 复杂状态联系表，至少覆盖密码隐藏、密码显示、短信默认和短信倒计时。
4. 320×568、360×640、360×800、412×915 四尺寸布局预览。
5. 可供 A01 契约测试读取的生成清单。

代码预览必须覆盖 A01 当前合同：现有 `brand-seal.png`、现有锁图标、保留中心瞳孔的闭眼图标、消息气泡加且仅加三点的短信图标、忘记密码位于密码横线下方，以及密码／短信两种独立状态。

## 7. 验收边界

- 代码生成图只用于选择和定位视觉问题，不计为真实运行证据。
- A01 实施后必须从真实路由进入，获取当前浅色国风主题的运行截图。
- 内部检查四档尺寸、默认字号与约 1.3 倍字号、状态栏、安全区、软键盘、返回手势和图片解码表现。
- 320×568 下品牌区、登录方式、当前表单、登录按钮、微信入口、注册、忘记密码和协议入口必须同屏可见且不依赖纵向滚动。
- 默认只向用户展示一张代表图；密码／短信等复杂状态使用一张联系表。
- H5 截图是候选证据，最终仍需 Android/HBuilderX 真机或模拟器复核。
- 用户明确确认前，A01 保持 `[~]`，不得写成已验收或冻结。

## 8. 性能与工程约束

- 正式 PNG 按实际显示槽位输出，不让页面解码无必要的超大位图。
- 同一公共资产只保留一个正式来源；页面状态不得复制公共背景和按钮像素。
- 脚本拒绝覆盖已存在的版本化输出，失败时保留旧结果并返回非零退出码。
- 生成目录与正式运行目录严格分离；只有用户确认的资产才进入 `static/assets/`。
- 不使用整页截图作为运行资产，不用 CSS 或手写 SVG 假造完整卷轴、宗祠、牌匾、按钮和装饰面。
- 所有可见提示继续使用项目自定义组件，禁止以原生 UniApp 提示作为最终视觉。

## 9. 测试与证据

- 先建立纯代码流水线契约测试并确认因入口和清单缺失而失败。
- 最小实现后验证清单、源文件、四尺寸输出、状态输出、PNG 尺寸、Alpha、文件体积和哈希。
- A01 页面实施前先更新页面契约测试并确认 RED，实施后恢复 GREEN。
- 运行受影响测试、运行时 smoke、真实截图人工复核和 `git diff --check`。
- 不执行 `git add`、commit、push、reset、checkout、上传、worktree 或多代理。

## 10. 推广门槛

A01 只有同时满足以下条件，纯代码流水线才可推广：

1. 同一清单能够稳定重复生成全部 A01 候选资产和预览。
2. 独立 PNG 与设计预览来自相同源像素，不再需要人工反向切图。
3. A01 真实运行截图与选定预览达到用户认可的视觉一致性。
4. 四档尺寸、约 1.3 倍字号、软键盘、安全区和 Android 复核有真实证据。
5. 用户明确确认 A01 基础版本通过。

未达到推广门槛时，只修正 A01 流水线和页面，不修改其他页面。