Files
perler-lab/docs/WIREFRAME-MODALS.md
Sisyphus (主代理) 02762400fb chore: 项目基线提交 - 拼豆图纸生成器 V1.0 核心代码
- 前端: React+Vite 首页/AI专区, 算法库(MARD色板/量化/背景去除), API对接
- 后端: Express+SQLite, 兑换码/订单/支付/chibi生成, 风控+云端同步
- CI/CD: GitHub Actions + Docker + nginx 配置
- 文档: PRD/DESIGN/LAUNCH/ROADMAP/E2E/竞品对照等 15 份
- 工程: 任务看板(taskboard) + 健康巡检(agent-health) + Git流程(gitflow)
2026-08-13 21:40:27 +08:00

35 KiB
Raw Permalink Blame History

PERLER LAB 弹窗线框文档(WIREFRAME-MODALS.md)

版本: 1.0 | 适用范围: 兑换码 / 订单 / 支付结果 / 代理合作 弹窗 + 核心状态流 依据: docs/DESIGN.md §3.5 弹窗规范 + competitor-analysis/copy-library.md §7 弹窗文案 文案均直接引用 copy-library.md,实现时不得改动原文


0. 弹窗通用规范(继承 DESIGN.md §3.5)

┌────────────────────────────────────────────┐
│  遮罩(全屏, 点击遮罩可关闭)                  │
│  背景: rgba(23,23,19,.4)                    │
│                                            │
│      ┌────────────────────────────┐        │
│      │  内容卡  max-width: 380px   │        │
│      │  圆角: 12px (--radius-lg)   │        │
│      │  阴影: 0 8px 32px rgba(23,  │        │
│      │        23,19,.14)           │        │
│      │  白底 #fff · 居中 fixed     │        │
│      │  右上角 [ ✕ ] 关闭按钮      │        │
│      └────────────────────────────┘        │
│                                            │
│  动画: 淡入 + 轻微上移(transform/opacity)   │
│  移动端: 内容卡贴底滑出, 保留 ✕ 与遮罩      │
└────────────────────────────────────────────┘
属性 值
遮罩 rgba(23,23,19,.4) 全屏覆盖,点击遮罩关闭
内容卡 max-width: 380px,白底,圆角 12px,--shadow-modal
关闭 右上角 ✕;遮罩点击;Esc(桌面端)
触控 按钮最小高度 40px(--touch-min)

1. 兑换码弹窗(redeem)

触发: 点击锁定卡的 输入兑换码解锁(DESIGN.md §3.4) 文案来源: copy-library.md §7.1

1.1 初始状态(idle)

┌────────────────────────────────────────────┐
│  输入兑换码                               ✕ │
├────────────────────────────────────────────┤
│                                            │
│  兑换后可解锁:                            │
│  • 完整 MARD 色号清单                      │
│  • 每色颗数与总颗数统计                    │
│  • 10% 备豆建议                            │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │  请输入兑换码                          │  │
│  └──────────────────────────────────────┘  │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │                兑 换                 │  │
│  └──────────────────────────────────────┘  │
│                                            │
└────────────────────────────────────────────┘
  • 输入框: 全宽,占位 请输入兑换码,圆角 10px,边框 --border
  • 兑换按钮: 橙底白字 兑换(--accent),圆角 10px,高度 44px,全宽
  • 触发: 弹窗打开即为此状态

1.2 加载中(loading)

┌────────────────────────────────────────────┐
│  输入兑换码                               ✕ │
├────────────────────────────────────────────┤
│  ┌──────────────────────────────────────┐  │
│  │  ABCD-1234-EFGH                       │  │
│  └──────────────────────────────────────┘  │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │  (◠)  兑换中…                        │  │
│  └──────────────────────────────────────┘  │
│                                            │
└────────────────────────────────────────────┘
  • 触发: 点击 兑换 且输入框非空
  • 按钮态: 转圈 spinner + 兑换中…,按钮禁用(防重复提交),输入框同时只读

1.3 错误状态(error)

┌────────────────────────────────────────────┐
│  输入兑换码                               ✕ │
├────────────────────────────────────────────┤
│  ┌──────────────────────────────────────┐  │
│  │  ABCD-1234-EFGH        (红边)      │  │
│  └──────────────────────────────────────┘  │
│  ⚠ 兑换失败 / 兑换码不存在,请检查后重试    │
│     ↑ 红色小字(--danger),输入框下方        │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │                兑 换                 │  │
│  └──────────────────────────────────────┘  │
│                                            │
└────────────────────────────────────────────┘
  • 触发: 提交的兑换码无效(服务端返回 兑换失败)
  • 文案(两行): 兑换失败 / 兑换码不存在,请检查后重试
  • 样式: 输入框红边(--danger),提示红字 12px(--text-sm)
  • 行为: 输入框可继续编辑;修改内容后错误提示消除;兑换 按钮恢复可用

1.4 成功状态(success)

┌────────────────────────────────────────────┐
│  输入兑换码                               ✕ │
├────────────────────────────────────────────┤
│                 ✓                          │
│             (成功绿 --success)            │
│                                            │
│     已确认到账,兑换码已自动解锁            │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │                关 闭                 │  │
│  └──────────────────────────────────────┘  │
│                                            │
└────────────────────────────────────────────┘
  • 触发: 兑换码校验通过
  • 文案: 已确认到账,兑换码已自动解锁(成功绿 ✓ 图标 + 14px 正文)
  • 按钮: 变为 关闭(次按钮:白底 + --border 描边)
  • 行为: 点击 关闭/✕/遮罩关闭后,备料清单立即解锁(见 §5.2 状态流),且页面刷新后仍保持解锁(本地持久化)

2. 订单弹窗(order)

触发: 点击套餐 CTA 购买 / 兑换 →(DESIGN.md §2.5) 文案来源: copy-library.md §3 权益套餐 + §7.2 订单弹窗

2.0 步骤总览

① 选择套餐 ──点击[去支付]──> ② 支付方式 ──切换tab──> ③ 确认付款(备注+复制订单号) ──点击[去支付]──> ④ 生成订单 → 支付结果弹窗

顶部步骤指示器(贯穿 ②③ 步,当前步橙色高亮):

① 选择套餐    ② 支付方式    ③ 确认付款
   ○ 已完成     ● 当前         ○ 未开始

2.1 步骤①:选择套餐

┌────────────────────────────────────────────┐
│  购买 AI 生成次数                         ✕ │
├────────────────────────────────────────────┤
│  ① 选择套餐       ② 支付方式   ③ 确认付款  │
├────────────────────────────────────────────┤
│  ┌──────────────┐ ┌──────────────┐ ┌─────┐ │
│  │ 体验包       │ │ 常用包  推荐 │ │进阶包│ │
│  │ ¥4.9        │ │ ¥12.9        │ │¥29.9 │ │
│  │ 3 次生成     │ │ 10 次生成    │ │30次  │ │
│  │ 适合先体验…  │ │ 适合个人…    │ │适合接│ │
│  │              │ │(橙边框+角标) │ │单…  │ │
│  └──────────────┘ └──────────────┘ └─────┘ │
│                                            │
│  权益说明:                                  │
│  成功生成 1 张作品,消耗 1 次                │
│  该作品转拼豆图纸及首次高清下载免费          │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │            去 支 付 →                │  │
│  └──────────────────────────────────────┘  │
└────────────────────────────────────────────┘
  • 三档卡片(横向排布,等宽): 体验包 ¥4.9/3次 · 常用包 ¥12.9/10次(推荐,默认选中,橙边框+推荐角标) · 进阶包 ¥29.9/30次
  • 选中态: 橙边框(--accent)+ 内部单选框
  • 底部: 权益说明小字(--text-sm 灰)
  • CTA: 去支付 → 橙底白字

状态 A — 套餐未选(按钮禁用)

  ┌──────────────────────────────────────┐
  │        去 支 付 →      (禁用)        │
  └──────────────────────────────────────┘
  • 触发: 所有套餐卡片均未选中(默认态)
  • 样式: 按钮灰底(--text-disabled)+ 白字,cursor: not-allowed
  • 行为: 点击无响应;选中任一卡片后立即变橙可点

2.2 步骤②:支付方式(ASCII)

┌────────────────────────────────────────────┐
│  购买 AI 生成次数                         ✕ │
├────────────────────────────────────────────┤
│  ① 选择套餐       ② 支付方式   ③ 确认付款  │
├────────────────────────────────────────────┤
│  应付金额 · ¥12.9 · 10 次生成               │
│  ┌──────────────┐ ┌──────────────┐         │
│  │  微信收款码  │ │ 支付宝收款码 │  (tab)  │
│  │  ● 选中      │ │  ○ 未选      │         │
│  └──────────────┘ └──────────────┘         │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │        ▓▓▓ 收款码二维码 ▓▓▓           │  │
│  │     (当前选中支付方式的收款码)         │  │
│  │        ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓            │  │
│  └──────────────────────────────────────┘  │
│                                            │
│  提示: 截图或长按保存收款码,再打开对应      │
│  支付应用扫码支付                           │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │        去 支 付 →                    │  │
│  └──────────────────────────────────────┘  │
└────────────────────────────────────────────┘
  • 金额行: 应付金额 · ¥12.9 · 10 次生成(当前所选套餐动态更新,¥ 数字加粗放大)
  • 支付方式: 微信收款码 / 支付宝收款码 两个 tab,选中态橙底白字
  • 二维码区: 跟随 tab 切换,显示对应收款码 + 截图或长按保存收款码 提示
  • 提示文案: 截图或长按保存收款码,再打开对应支付应用扫码支付

2.3 步骤③:确认付款(应付金额 + 付款备注 + 复制订单号)

┌────────────────────────────────────────────┐
│  购买 AI 生成次数                         ✕ │
├────────────────────────────────────────────┤
│  ① 选择套餐       ② 支付方式   ③ 确认付款  │
├────────────────────────────────────────────┤
│  应付金额 · ¥12.9 · 10 次生成               │
│                                            │
│  付款备注(必须填写)                       │
│  ┌──────────────────────────────────────┐  │
│  │  请输入付款备注                        │  │
│  └──────────────────────────────────────┘  │
│                                            │
│  订单号                                    │
│  ┌──────────────────────────────────────┐  │
│  │  PL-20260813-XXXX   [ 复制订单号 ]   │  │
│  └──────────────────────────────────────┘  │
│                                            │
│  ⚠ 付款金额请与上方一致,付款备注填写完整   │
│    订单号                                   │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │          去 支 付 →                  │  │
│  └──────────────────────────────────────┘  │
└────────────────────────────────────────────┘
  • 付款备注(必须填写): 必填输入框,占位 请输入付款备注
  • 订单号: 展示服务端生成的订单号(等宽字体 --font-mono)+ 复制订单号 按钮(点击复制,短暂提示"已复制")
  • 校验提示: 付款金额请与上方一致,付款备注填写完整订单号(黄色/橙色警示,--text-sm)
  • CTA: 去支付 →;备注为空时按钮禁用(同 §2.1 状态 A 样式)

2.4 状态:生成订单中(loading)与订单创建失败

生成订单中 (loading):
  ┌──────────────────────────────────────┐
  │  (◠)  生成付款订单…                  │
  └──────────────────────────────────────┘
  → 触发: 点击步骤③的 [去支付 →]
  → 按钮转 spinner + `生成付款订单…`,禁用

订单创建失败 (error):
  ┌──────────────────────────────────────┐
  │  ⚠ 订单创建失败                       │
  │  ┌────────────────────────────────┐  │
  │  │            重 试              │  │
  │  └────────────────────────────────┘  │
  └──────────────────────────────────────┘
  → 触发: 服务端下单接口失败
  → 文案: `订单创建失败`(红字)
  → 行为: 停留在步骤③,金额/备注保留;点击 `重试` 重新生成订单

成功路径: 订单生成成功 → 自动进入 §3 支付结果弹窗(待支付态)


3. 支付结果弹窗(payment)

触发: 订单生成成功 / 用户点击 我已支付 / 支付确认 文案来源: copy-library.md §7.1 成功文案 + §7.2 提示2 + §9 错误文案

3.1 待支付(pending)

┌────────────────────────────────────────────┐
│  支付结果                                 ✕ │
├────────────────────────────────────────────┤
│                 ⏳                         │
│            (等待支付 --info 蓝)           │
│                                            │
│     付款金额请与上方一致,付款备注填写完整   │
│     订单号                                 │
│                                            │
│  付款方式: 微信收款码(已生成)             │
│  订单号: PL-20260813-XXXX                  │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │            我 已 支 付              │  │
│  └──────────────────────────────────────┘  │
│  ┌──────────────────────────────────────┐  │
│  │            支付失败?                 │  │
│  └──────────────────────────────────────┘  │
└────────────────────────────────────────────┘
  • 触发: 订单生成成功后弹出(步骤③ 去支付 → 完成时)
  • 主文案(警示): 付款金额请与上方一致,付款备注填写完整订单号
  • 次按钮 支付失败?: 点开失败处理(引导检查金额/备注或重新下单)

3.2 支付成功(success)

┌────────────────────────────────────────────┐
│  支付结果                                 ✕ │
├────────────────────────────────────────────┤
│                 ✓                          │
│            (成功绿 --success)             │
│                                            │
│     已确认到账,兑换码已自动解锁            │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │              完 成                  │  │
│  └──────────────────────────────────────┘  │
│                                            │
└────────────────────────────────────────────┘
  • 触发: 点击 我已支付 后,服务端确认到账(轮询/查询成功)
  • 文案: 已确认到账,兑换码已自动解锁(与兑换码弹窗成功共用文案)
  • 行为: 完成 关闭;权益次数 +N、备料清单解锁、AI 生成按钮可用(全部实时生效)

3.3 支付失败(error)

┌────────────────────────────────────────────┐
│  支付结果                                 ✕ │
├────────────────────────────────────────────┤
│                 ✕                          │
│            (危险红 --danger)              │
│                                            │
│     支付失败,请重试                        │
│                                            │
│  ┌──────────────────────────────────────┐  │
│  │            重 试                    │  │
│  └──────────────────────────────────────┘  │
│  ┌──────────────────────────────────────┐  │
│  │            返回订单                  │  │
│  └──────────────────────────────────────┘  │
└────────────────────────────────────────────┘
  • 触发: 我已支付 后查询不到到账 / 到账信息不匹配
  • 文案: 支付失败,请重试
  • 行为: 重试 再次查询;返回订单 回到订单弹窗步骤③(金额/备注/订单号保留)

4. 代理合作弹窗(agency)

触发: 点击 NAV 的 代理合作 按钮 文案来源: copy-library.md §3 代理套餐 + §7.3

┌────────────────────────────────────────────┐
│  代理合作                                 ✕ │
├────────────────────────────────────────────┤
│  三档代理套餐,批量采购更划算                │
│                                            │
│  ┌─────────────┐ ┌─────────────┐ ┌───────┐ │
│  │ 初级代理     │ │ 标准代理     │ │核心代理│ │
│  │ ¥139        │ │ ¥299        │ │¥499   │ │
│  │ 200 次      │ │ 500 次      │ │1000次 │ │
│  └─────────────┘ └─────────────┘ └───────┘ │
│  (三档卡片横向排布:等级/价格大号/次数)     │
│                                            │
│  ──────────────────────────────            │
│  【采购说明】(占位: 批量采购流程/发票/      │
│   发货说明,文案待产品确认后补充)            │
│  ──────────────────────────────            │
│                                            │
│  咨询方式                                  │
│  ┌──────────────────────────────────────┐  │
│  │  微信咨询(二维码/账号,占位)        │  │
│  └──────────────────────────────────────┘  │
│  ┌──────────────────────────────────────┐  │
│  │              关 闭                  │  │
│  └──────────────────────────────────────┘  │
└────────────────────────────────────────────┘
  • 三档卡片: 初级代理 ¥139 / 200 次 · 标准代理 ¥299 / 500 次 · 核心代理 ¥499 / 1000 次
  • 卡片结构: 等级名 → ¥ 价格(大号加粗) → N 次
  • 分割线下: 采购说明 + 咨询方式(微信二维码区)
  • 底部 关闭 按钮(次按钮)
  • 无异步状态,纯展示弹窗;卡片暂不可点(仅展示),点击行为待产品确认

5. 状态流线框图(State Flows)

5.1 上传图片(首页 01 生成设置 · DESIGN.md §3.1)

┌─────────┐   选择图片   ┌─────────┐   点击/拖入   ┌──────────┐
│  idle    │ ──────────> │  hover   │ ───────────> │ loading  │
│ 虚线框   │             │ 橙边+浅底 │              │ 图片处理中…│
│ +上传…  │             │ --bg-hover│              │ (spinner) │
└─────────┘             └─────────┘              └────┬─────┘
                                                        │ 成功
                                                        ▼
                                              ┌─────────────────┐
                                              │    ready        │
                                              │ 缩略图+文件名+重置│
                                              └─────────────────┘

  失败分支(loading ──> error):
  ┌──────────────────────────────────────┐
  │  ✕ 图片不能超过 12MB                  │  ← 触发: 文件 > 12MB
  └──────────────────────────────────────┘
  ┌──────────────────────────────────────┐
  │  ✕ 图片读取失败,请换一张重试          │  ← 触发: 解码/读取异常
  └──────────────────────────────────────┘
  错误态: 上传框红边 + 错误文案,可重新上传

5.2 备料清单解锁(MARD · DESIGN.md §3.4)

┌────────────────────────┐   点击[输入兑换码解锁]   ┌────────────────────┐
│        锁定            │ ──────────────────────> │ 兑换码弹窗(§1)     │
│  🔒 受保护             │                         │ 输入 → [兑换]      │
│  •••• 实际总颗数       │                         └─────────┬──────────┘
│  •• 使用颜色           │                                   │ 成功
│  完整色号已隐藏        │                                   │ 已确认到账…
│  建议多备10%·约••••颗  │                                   ▼
└────────────────────────┘                    ┌────────────────────────┐
                                              │         解锁           │
                                              │  已解锁                │
                                              │  完整色号清单(每色行:  │
                                              │  色块+色号+颗数)       │
                                              │  建议多备 10% · 约 N 颗 │
                                              └────────────────────────┘
  失败分支: 兑换码无效 → 弹窗内错误文案(§1.3),清单保持锁定
  持久化: 解锁状态本地保存,刷新后仍为解锁

5.3 下载(02 实时预览 · copy §5)

┌──────────────┐ 兑换成功    ┌──────────────┐   点击下载    ┌──────────────┐
│    未兑换     │ ─────────> │    已兑换     │ ───────────> │    下载中     │
│ ↓ 兑换后下载  │            │ 首次下载免费  │              │ (spinner)    │
│  完整图纸     │            │ 下载普通图纸  │              └──────┬───────┘
│  (按钮禁用)   │            │ · 消耗 1 次   │                     │ 完成
└──────────────┘            └──────────────┘                     ▼
                                                    ┌──────────────────────┐
                                                    │       完成           │
                                                    │  保存图片            │
                                                    │  >长按下方图片保存到手机│
                                                    │   (下载结果展示区)     │
                                                    └──────────────────────┘
  触发条件:
  - 未兑换 → 按钮禁用(灰), 点击弹兑换码窗(§1)
  - 已兑换 + 首次下载 → 免费, 不扣次数
  - 已兑换 + 非首次 → 下载普通图纸 · 消耗 1 次
  - 失败分支: 下载授权失败 → 提示 `下载授权失败`(copy §9)

5.4 AI 生成(AI 专区 /chibi · DESIGN.md §4.5)

┌──────────────┐ 点击(弹兑换码窗§1) ┌──────────────┐  点击[生成 →]  ┌──────────────┐
│    未兑换     │ ───────────────> │    已兑换     │ ────────────> │    生成中     │
│ 兑换后生成 →  │                  │ 生成 →        │               │ (◠) AI 生成中…│
│  (disabled)  │                  │ (橙底白字)    │               └──────┬───────┘
└──────────────┘                  └──────────────┘                      │
                                                         ┌──────────────┴──────────────┐
                                                         │ 成功                          │ 失败
                                                         ▼                              ▼
                                              ┌──────────────────────┐   ┌──────────────────────┐
                                              │ 显示生成结果          │   │ 生成失败,请稍后重试   │
                                              │ + 转图纸免费          │   │ (不扣次)              │
                                              │ + 首次下载免费        │   │ [重试]                │
                                              │ (扣 1 次权益)         │   └──────────────────────┘
                                              └──────────────────────┘

  触发条件:
  - 未兑换: 按钮禁用, 点击弹出兑换码弹窗(§1)
  - 已兑换: 按钮可用 `生成 →`
  - 生成中: spinner + `AI 生成中…`, 按钮禁用, 锁定参数切换
  - 成功: 扣 1 次; 该作品转图纸 + 首次下载免费
  - 失败: `生成失败,请稍后重试`, 不扣次数, 可重试
  文案依据: copy §8.1 付费说明 + §9 生成失败

6. 汇总

弹窗 步骤/状态数 触发入口 关键文案
兑换码弹窗 4 状态(初始/加载中/错误/成功) 锁定卡 输入兑换码解锁 兑换码不存在,请检查后重试 / 已确认到账,兑换码已自动解锁
订单弹窗 4 步骤 + 3 状态(未选禁用/生成中/创建失败) 套餐 CTA 购买 / 兑换 → 应付金额 · ¥12.9 · 10 次生成 / 付款备注(必须填写)/ 复制订单号 / 订单创建失败
支付结果弹窗 3 状态(待支付/成功/失败) 订单生成成功 / 我已支付 付款金额请与上方一致,付款备注填写完整订单号 / 支付失败,请重试
代理合作弹窗 1 状态(静态展示) NAV 代理合作 初级代理 ¥139/200次 · 标准代理 ¥299/500次 · 核心代理 ¥499/1000次
状态流 4 条(上传图片/备料解锁/下载/AI生成) — 图片不能超过 12MB / 首次下载免费 / AI 生成中… / 生成失败,请稍后重试

待确认项: ① 代理合作「采购说明」与「咨询方式」具体文案(copy-library 未收录,已标占位)② 代理卡片是否可点击购买 ③ 支付失败弹窗的「查询失败」场景是否需要单独状态(copy §9 有 查询失败 文案备用)