jiapuapp/docs/superpowers/specs/2026-07-15-code-first-asset-pipeline-design.md

家谱 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. 唯一所有者与目录边界

新流水线使用以下边界：

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 流水线和页面，不修改其他页面。