交付出件箱

← 返回出件箱

原型图（效果图）规范与标准

适用：赵阳智脑 / 结算系统所有原型图、效果图、UI 方案图
来源：全部是真返工换来的，每条后面都标了触发它的那次事故。不是通用设计规范，别当参考读物。
版本：2026-08-15（在 2026-08-13 长官验收定稿版上，补入 08-15 新踩的 4 个坑）

0. 先记住三句话

1. 原型图不是画给自己看的，是给实施照着做的 —— 图和代码对不上，实施就会做错，返工算图的账
2. 没扒过现网代码，画出来的一定是"想象中的现状" —— 3 次返工，根因全是这个
3. 没真渲染看过一眼，就不许说"图做好了" —— 源码改对 ≠ 显示正常

一、动手前必做（跳过 = 必返工）

1.1 先看现有样板，别从零画

⚠️ 下面是 dev2 这台云机的路径，你那台不一定一样。
先各跑一次确认存在；找不到就问，别硬画 —— 从零画必返工。

⚠️ 代码路径同理：本文档写的 settlement/web/app/... 是仓库内相对路径，
先 git rev-parse --show-toplevel 拿到仓库根，别硬编码别人的绝对路径。

1.2 🔴 扒真实令牌，禁止自己配色（最容易犯的一条）

🔴 PC 端和手机端是两套色系，别拿 PC 色画手机端（第 2 版效果图就栽在这）

碰到现有规则覆盖不到的新状态值：如实按现有规则渲染 + 标注"需扩展"，不擅自配色。
（这么做反而挖出过真 bug：已支付/已退款 在 statusClass() 里双双落兜底灰、颜色分不出来
——那不是画图问题，是实施必须补的两行代码。）

1.3 🔴 画之前先 grep 现网代码（08-15 新增）

触发：进度页效果图上画了「原价划线 + 现价」的价格块，实际代码里从来没有过价格
——代码里是一句话 + 一个按钮。图跟现网差了十万八千里，谁照着图做谁错。

每画一个界面块，先回答三个问题（回答不了就别画）：

# ① 这个块现在真实长什么样？
grep -n "<关键文案>" settlement/web/app/<对应页面>/page.tsx

# ② 它现在什么条件下才显示？
grep -n "canGoPayment\|<控制它的变量>" <同上>

# ③ 我要画的字段，后端真给得出来吗？
grep -rn "<字段名>" settlement/backend/app/api/

图上每个"改动"都要能说清是相对什么的改动。说不清 = 你不知道现状 = 停下来先查。

二、出图规范

2.1 不做局部撑破版式

触发：为了让弹窗宽一点，用负 margin 强行撑到 1440，结果内容溢出屏幕左侧、字段被切。

整页维持 1180 基准。放不下就收窄内容或换布局，不许用负 margin / 绝对定位硬撑。

2.2 同一个元素，全图只能有一种样式（08-15 新增）

触发：同一个价格块，进度页写「赵阳智脑 ¥2,880」，支付页写「原价 ¥2,880 + ≈¥198/月」
——两处不一致，实施时不知道该照哪个。

改一处样式，grep 全图找出所有同类块，一起改。改完自查：

grep -c "<该元素特征串>" <图文件>   # 数量对得上才算改全

三、交付前必跑（无证据 = 没做）

3.1 🔴 真渲染，并且用 Read 把图真看一遍

# 先确认工具在不在（不在就走下面的降级路径）
ls ~/render-env/browse.js 2>/dev/null && node ~/render-env/browse.js <file> --desktop --script <steps.js>

⚠️ 不是所有云机都有 Chromium。没有的话如实说"我渲染不了"，
把图交给长官或去 test 环境看 —— 绝不允许没渲染却说"已验收"。
（踩过：文档写着"验收通过"，实际图根本没人打开过。）

⚠️ innerText 看不出间距（ml-2 的空隙在 innerText 里不存在），
别据此判断"文案粘一起了" —— 间距/字号只能看截图或 getComputedStyle。

3.2 文字溢出量化自查

脚本比 scrollWidth > clientWidth（排除绝对定位装饰造成的假阳性），必须报出：

真内容溢出 0 / 手机帧宽度集合 [360] / 溢出 0

3.3 DOM 闭合标签自查（08-13 血泪）

触发：某节少一个 </div>，把后续所有节都吞进去了。
长官反馈"格式乱、更丑"，查了半天才发现根因不是设计，是缺个闭合标签。

python3 -c "
s=open('<file>',encoding='utf-8').read()
print('div 开/闭:', s.count('<div'), s.count('</div>'), '差', s.count('<div')-s.count('</div>'))"

⚠️ 改动前后各跑一次，比的是差值有没有变——有些图本来就不平衡（浏览器会兜住），
不能拿"不为 0"直接判定是你改坏的。（08-15 实测：改前 -2，改后 -2，说明与本次改动无关。）

3.4 口径一致性

同一个事实，在图和方案文档里的说法必须一致。
（踩过：文档 §五写"已退款(橙)"，与拍板的蓝色冲突。）

3.5 改图前先备份（08-15 新增）

触发：~/reports/ 不是 git 仓库，没有任何版本历史。
长官问"这块什么时候改的"，我只能查到文件时间戳，中间改了几轮永远查不出来。

cp <图> /tmp/<图名>-backup-$(date +%H%M).html    # 改之前

大改建议直接把图纳入 git 管理，别再靠时间戳考古。

四、图与实施的关系（08-15 新增 · 最重要的一节）

4.1 图上画的每个状态，都要标清"什么条件下出现"

触发：效果图画的是「资料待审核 + 未支付」也能看到付款卡片、可以去支付
（体现"付款与审核并行"），但代码里那张卡片只在资料已通过时才显示。
图和代码是两个逻辑，谁也没发现，直到逐条对功能才暴露。

图上每个卡片/区块旁边，要能回答：这个块在什么条件下显示？
条件与现网代码不一致时，必须在图上明确标出"需改显示时机"，
否则实施只会照着改文案，逻辑还是老的 —— 那句"互不影响"就是假的。

4.2 图不是需求，方案文档才是

图用来看效果，口径以方案文档为准。两者冲突时：
1. 先确认哪个是长官最后拍板的
2. 改的是两个，不是一个 —— 图改完，方案文档对应段落同步改

4.3 后端给不出来的字段，图上不许画

画之前 grep 后端接口确认字段真的返回。
（踩过反例：后端 payment_status 做完了、测试都绿了，前端两个页面一行没做
—— 图上画了、后端有了、前端漏了，没人发现，因为接口测试管不着前端有没有渲染。）

五、交付

• 文件名用 ASCII（中文名在 URL 里要编码，容易点不开）
• 放 ~/reports/，用 deliver <文件名> 出公网链接
  ⚠️ deliver 是云机自带脚本，你那台若 which deliver 为空，
  就手动 cp <文件> ~/reports/shared/，公网地址 = https://dev-tokyo.tail3912a6.ts.net/<文件名>
  （根目录直接是文件名，没有 /reports/shared/ 前缀 —— 写错前缀实测 404）
• 🔴 给长官的链接必须是公网域名（https://dev-tokyo.tail3912a6.ts.net/...）
  —— 内网 100.113.74.62 那条要连 tailscale，长官打不开
  （踩过：在云机上自己 curl 返 200 就当没问题了 —— 自己机器上通不等于对方能打开）
• 链接裸写，别包进反引号或代码块（那样在 claude.ai 里点不动）

六、自检清单（交付前逐条打勾）

• [ ] 画之前 grep 过现网代码，知道每个块的真实现状与显示条件
• [ ] 配色全部扒自现有代码，一个色值都没自造
• [ ] PC 色与手机端色没串
• [ ] 标注只有一种（橙虚线 + 新增标签）
• [ ] 同一元素全图只有一种样式（grep 数过）
• [ ] 零外网 CDN
• [ ] DOM 闭合标签差值与改动前一致
• [ ] 真渲染过并用 Read 看过（渲染不了就如实说，不许假称验收）
• [ ] 溢出自查报 0
• [ ] 图与方案文档口径一致
• [ ] 后端给不出的字段没画
• [ ] 改动前备份过
• [ ] 交付给的是公网链接、裸写、ASCII 文件名

附：这份规范的由来