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

526 lines
35 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 有 `查询失败` 文案备用)