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)
This commit is contained in:
Sisyphus (主代理) committed 2026-08-13 21:40:27 +08:00
commit 02762400fb
174 files changed
+28059

No files matched your search

+115
View File
@@ -0,0 +1,115 @@
# PERLER LAB 代理合作方案(AGENT.md)
> 版本: 1.0 | 关联: LAUNCH.md §3(代理合作方案) | 定价基准: 代理套餐见 §4
> 用途: 代理招募、培训、答疑、续费的标准话术与流程,直接复制可用
---
## 1. 代理招募话术
### 1.1 微信私聊版
```
【开场破冰】
你好,我是拼豆图纸生成工具 PERLER LAB 的运营。
看到你在做拼豆接单,有个降成本的方法想跟你聊聊:)
我们这边代理价拿图纸生成权益,单次成本不到 7 毛钱。
【介绍产品】
PERLER LAB 可以上传照片/图片,30 秒自动出拼豆图纸,
色号、颗数、备料清单全部标好,你只管出图接单,不用自己画图纸。
手机电脑都能用,出图快、效果好,同行现在都在用。
【报套餐 + 算账】
代理价三档,按需选:
- ¥139 可用 200 次(单次 0.70 元)
- ¥299 可用 500 次(单次 0.60 元)
- ¥499 可用 1000 次(单次 0.50 元)
你接一单代出图收 3-10 元,成本不到 1 块,利润很可观。
按 200 次全接单算,最多能产出 600-2000 元流水。
【临门一脚】
权益长期有效、用不完不心疼,推广还送专属链接返佣。
方便的话我把价目表和接单流程发你,先存着,需要了直接开工?
```
### 1.2 社群发布版
```
🔥 PERLER LAB 拼豆图纸代理招募中
✅ 出图快:上传照片 30 秒出图纸,色号颗数全标好
✅ 成本低:¥139 用 200 次,单次低至 5 毛
✅ 好变现:代出图 3-10 元/张、卖图纸模板、接定制都行
✅ 长期有效:权益不过期,囤了慢慢用
✅ 专属推广链接:朋友通过你链接购买,你拿返佣
📊 代理价目表
¥139 → 200 次(适合个人接单)
¥299 → 500 次(适合工作室)
¥499 → 1000 次(适合店铺/团队,量大可谈阶梯价)
👇 私聊我领取【代理价目表 + 接单流程】,前 10 名送体验码试试手感
```
---
## 2. 代理合作流程
```
咨询 → 选套餐 → 付款 → 开通 → 接单 → 续费
```
| 步骤 | 动作 | 说明 | 责任人 |
|---|---|---|---|
| 1. 咨询 | 解答产品/价格/权益疑问 | 用 §1 话术沟通,确认代理有明确接单场景 | 运营 |
| 2. 选套餐 | 确认档位(¥139/200次、¥299/500次、¥499/1000次) | 按预估单量推荐,200次起步,量大建议 500/1000 | 运营 |
| 3. 付款 | 微信/支付宝转账 | 收款后截图确认,登记付款凭证 | 代理 |
| 4. 开通 | 发放对应档位代理兑换码(大额) | 兑换码 7-10 位大写字母数字混合,走代理通道 | 运营 |
| 5. 接单 | 代理用兑换码出图、交付客户 | 每成功出图 1 张扣 1 次;失败不扣次 | 代理 |
| 6. 续费 | 次数用尽或预感不足时续费 | 续费同价,量 ≥1000 次可谈阶梯价 | 代理 |
> 开通时效承诺:付款确认后 30 分钟内发放兑换码(工作日)。
> 到期提醒:兑换码剩余次数 ≤50 次时,由运营主动提醒续费。
---
## 3. 代理 FAQ
| # | 问题 | 回答 |
|---|---|---|
| 1 | 代理码能接多少单? | 一张图纸算 1 次(含首次高清下载)。¥139 的 200 次 ≈ 200 单;¥299 的 500 次 ≈ 500 单;¥499 的 1000 次 ≈ 1000 单。同一订单重复下载不扣次 |
| 2 | 代理码会过期吗? | 不会。兑换码长期有效,无有效期限制,用多少扣多少,用不完的权益一直保留 |
| 3 | 能开发票吗? | 可以。月累计消费 ≥¥500 可开具电子普通发票(内容:信息技术服务费/软件服务费),需提供开票抬头与税号,次月 10 日前统一开具 |
| 4 | 如何查询剩余次数? | 方式一:公众号/客服后台回复兑换码即可查询;方式二:产品首页输入兑换码解锁后页面直接显示剩余次数;方式三:联系运营人工查询。建议接单前自查,避免超售 |
| 5 | 能否升级套餐? | 可以。已购权益保留,升级按差价补齐即可(如 ¥139 升 ¥299 补 ¥160,叠加已有 200 次权益) |
| 6 | 出图失败扣次数吗? | 不扣。只有成功生成图纸才消耗 1 次,失败可重试 |
| 7 | 代理码和个人码能混用吗? | 不能。代理码走代理通道,个人码走个人通道,两者权益独立、不可互相抵扣 |
| 8 | 退款政策? | 虚拟权益一经使用不支持退款;未使用的可联系客服协商处理 |
| 9 | 我的客户要发票怎么开? | 由代理统一申请(见第 3 条),代理开给客户的分销发票需自理,平台不开具给终端用户 |
| 10 | 怎么拿到专属推广链接? | 开通代理后向运营领取。链接带代理标识,客户通过链接购买个人套餐,转化可追踪并按约定返佣 |
---
## 4. 代理价目表
| 套餐 | 价格 | 生成次数 | 单次成本 | 适用场景 |
|---|---|---|---|---|
| 入门代理 | **¥139** | 200 次 | ¥0.70/次 | 个人接单(约 200 单) |
| 标准代理 | **¥299** | 500 次 | ¥0.60/次 | 工作室(约 500 单) |
| 核心代理 | **¥499** | 1000 次 | ¥0.50/次 | 店铺/团队(约 1000 单) |
> 补充规则:
> 1. 批量采购 ≥1000 次可谈阶梯价(例:累计采购 1000 次,单价降至 ¥0.45/次 档位,具体一事一议)
> 2. 以上价格与 LAUNCH.md §3.1 及产品 `PACKAGE_DEFINITIONS`(代理200=¥139/200次、代理500=¥299/500次、代理1000=¥499/1000次)保持一致
> 3. 代理权益:按次生成(长期有效)、专属推广链接、优先技术支持、新功能内测资格
---
## 5. 代理开通常规提示(运营自用)
1. 开通前确认代理已阅读 §4 价目表并明确选档
2. 付款需以运营收款确认为准,杜绝口头承诺
3. 发放兑换码后务必让代理当场兑换一次验证权益到账
4. 留存付款凭证 + 兑换码发放记录,形成台账(订单号建议用 `AG-YYYYMMDD-序号` 登记)
+271
View File
@@ -0,0 +1,271 @@
# PERLER LAB 数据分析与事件埋点规范(ANALYTICS.md)
> 版本: 1.0 | 关联: LAUNCH.md(§5 运营指标)· PRD.md
> 说明: 本规范定义全站事件埋点、转化漏斗、上报方式与关键指标看板,所有目标值对齐 LAUNCH.md §5.1/§5.2/§5.3。
---
## 1. 数据口径与用户标识
| 字段 | 类型 | 说明 |
|---|---|---|
| `device_id` | `string` (uuid) | 存于 `localStorage._pl_device_id`,首次访问生成,永久复用。权益与回访均按此维度统计(与兑换权益的本地存储机制一致) |
| `session_id` | `string` (uuid) | 存于 `sessionStorage._pl_session_id`,一次会话一个,关闭标签页即失效 |
| `page` | `"/"` \| `"/chibi"` | 事件发生时所在页面 |
| `ts` | `number` (ms) | 事件时间戳(`Date.now()`) |
**去重规则**:漏斗与转化率类指标按 `device_id` 去重,且同一 `session_id` 内同一环节只计首次命中,避免重复点击抬高转化率。
---
## 2. 事件总表(38 个事件)
> 命名约定:全小写 snake_case;每行含 事件名 / 触发时机 / 参数(全部标注类型)/ 页面。
### 2.1 访问 / 页面浏览(5 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `session_start` | 页面首次加载(会话开始) | `referrer: string`(来源页), `landing_page: "/"\|"/chibi"`, `utm_source: string?` | / /chibi |
| `page_view` | 每次页面浏览(SPA 路由切换同样触发) | `page: "/"\|"/chibi"`, `referrer: string` | / /chibi |
| `home_view` | 首页完成渲染 | `-` | / |
| `chibi_view` | /chibi 专区完成渲染 | `-` | /chibi |
| `first_visit` | 无 `device_id` 记录时首次访问 | `landing_page: "/"\|"/chibi"`, `referrer: string` | / /chibi |
### 2.2 图片上传(5 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `upload_start` | 用户点击/选择文件 | `file_type: "jpg"\|"png"\|"webp"`, `file_size_bytes: number` | / |
| `upload_success` | 图片读取并校验通过 | `file_type: string`, `file_size_bytes: number`, `width_px: number`, `height_px: number`, `aspect_ratio: number`(宽/高,保留 2 位) | / |
| `upload_fail` | 读取/解析失败 | `file_type: string`, `file_size_bytes: number`, `error_code: "read_error"\|"parse_error"\|"corrupt"` | / |
| `upload_size_exceed` | 文件超过 12MB 被拦截 | `file_size_bytes: number`, `limit_mb: 12` | / |
| `upload_type_invalid` | 文件格式不受支持 | `file_type: string`, `allowed: ["jpg","png","webp"]` | / |
### 2.3 参数调整(4 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `param_change` | 任意参数变更(通用兜底) | `param: "size"\|"colors"\|"bg_removal"\|"style"`, `value: string\|number\|boolean`, `prev_value` | / /chibi |
| `param_size_change` | 图纸尺寸变更 | `size: "32x32"\|"48x48"\|"64x64"` | / |
| `param_color_change` | 色数变更 | `colors: 12\|24\|36` | / |
| `param_bg_removal_toggle` | 背景去除开关切换 | `value: boolean` | / /chibi |
### 2.4 重新生成(1 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `regenerate_click` | 点击"重新生成"按钮 | `trigger: "auto"\|"manual"`, `size: string`, `colors: number` | / |
### 2.5 兑换码(5 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `redeem_modal_open` | 打开兑换弹窗 | `entry: "download_lock"\|"nav"\|"banner"\|"limit_hit"` | / |
| `redeem_submit` | 提交兑换码(调用 `/api/codes/redeem`) | `code_length: number`, `code_prefix: string`(脱敏,仅取前 4 位) | / |
| `redeem_success` | 兑换成功(redeem 返回成功) | `balance_added: number`, `total_balance: number`, `channel: "personal"\|"agent"` | / |
| `redeem_fail` | 兑换失败 | `error_code: "invalid"\|"used"\|"expired"\|"rate_limited"`, `channel: "personal"\|"agent"` | / |
| `redeem_balance_checked` | 用户查看剩余次数 | `balance: number` | / |
### 2.6 订单 / 支付(5 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `order_create` | 创建订单(调用 `/api/orders`) | `order_id: string`, `package: "experience"\|"standard"\|"pro"`, `price_yuan: 4.9\|12.9\|29.9`, `times: 3\|10\|30` | / |
| `order_pay_method_select` | 选择支付方式 | `order_id: string`, `method: "wechat"\|"alipay"\|"mock"` | / |
| `order_pay_success` | 支付成功 | `order_id: string`, `package: string`, `price_yuan: number`, `method: string`, `pay_amount: number` | / |
| `order_pay_fail` | 支付失败 | `order_id: string`, `error_code: string`, `method: string` | / |
| `order_pay_cancel` | 用户取消支付 | `order_id: string`, `duration_ms: number`(从创建到取消) | / |
### 2.7 下载(3 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `download_click` | 点击下载图纸 | `work_id: string`, `size: string`, `colors: number`, `is_chibi: boolean` | / /chibi |
| `download_success` | 下载完成(触发 `/api/codes/consume` 扣次成功) | `work_id: string`, `size: string`, `colors: number`, `consume_used: boolean` | / /chibi |
| `download_fail` | 下载失败 | `work_id: string`, `error_code: "blob_error"\|"browser_blocked"\|"consume_fail"` | / /chibi |
### 2.8 AI 生成(6 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `ai_generate_start` | 开始 AI 生成(调用 `/api/chibi/generate`) | `source: "photo"\|"chibi"`, `size: string`, `colors: number`, `style: string?`(仅 chibi 源) | / /chibi |
| `ai_generate_success` | 生成成功 | `source: string`, `size: string`, `colors: number`, `latency_ms: number`, `cost_yuan: number` | / /chibi |
| `ai_generate_fail` | 生成失败 | `source: string`, `error_code: "model_error"\|"timeout"\|"rate_limit"`, `latency_ms: number` | / /chibi |
| `ai_generate_retry` | 用户点击重试生成 | `source: string`, `retry_count: number`, `prev_error_code: string` | / /chibi |
| `generation_limit_hit` | 剩余次数不足被拦截 | `balance: number`, `required: 1` | / |
| `chibi_convert_click` | 将 AI 结果转为正式图纸 | `size: string`, `colors: number` | /chibi |
### 2.9 代理合作(2 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `agent_modal_open` | 打开代理合作弹窗 | `entry: "footer"\|"banner"\|"faq"` | / |
| `agent_consult_click` | 点击"咨询/领取价目表" | `contact_channel: "wechat"\|"qq"`, `package_interest: "entry"\|"standard"\|"core"` | / |
### 2.10 分享 / 增长(2 个)
| 事件名 | 触发时机 | 参数 | 页面 |
|---|---|---|---|
| `share_click` | 点击分享 / 晒图纸 | `channel: "xiaohongshu"\|"douyin"\|"wechat"\|"copy_link"`, `work_id: string` | / |
| `refer_link_click` | 通过代理推广链接进入 | `agent_id: string`, `page: "/"\|"/chibi"` | / /chibi |
---
## 3. 转化漏斗定义
对齐 LAUNCH.md §5.1:`访问 → 上传图片 → 生成预览 → 兑换解锁 → 下载完成`(100% / 45% / 25% / 8% / 6%)。
| 步骤 | 名称 | 事件口径(去重) | 计算 | 目标 |
|---|---|---|---|---|
| 1 | 访问 | `page_view`(当日去重 `device_id` 数) | 分母 = 100% | - |
| 2 | 上传 | `upload_success`(同一 session 首次) | 上传转化率 = 步骤2 / 步骤1 | ≥45% |
| 3 | 生成 | `ai_generate_success`(同一 session 首次) | 生成转化率 = 步骤3 / 步骤1 | ≥25% |
| 4 | 兑换 | `redeem_success`(同一 session 首次) | 兑换率 = 步骤4 / 步骤1 | ≥8%(付费转化,对齐 §5.2 目标 5%) |
| 5 | 下载 | `download_success`(同一 session 首次) | 下载完成率 = 步骤5 / 步骤4 | ≥75% |
**漏斗细分口径**:
- 上传→生成转化率 = 步骤3 / 步骤2,用于衡量生成功能本身的流失(含次数不足拦截 `generation_limit_hit`)。
- 兑换→下载转化率 = 步骤5 / 步骤4,异常时应排查 `download_fail` 与浏览器下载拦截。
- 分渠道查看(小红书 / 抖音 / 代理链接 / 直接访问):以 `session_start.referrer` 与 `utm_source`、`refer_link_click.agent_id` 为维度拆分,T+7 复盘按渠道对齐。
---
## 4. 埋点实现建议
### 4.1 前端事件采集(window.__analytics 全局函数)
采用轻量全局函数方案,不引入第三方 SDK。业务代码只需一行调用:
```js
// 埋点调用示例
window.__analytics('ai_generate_success', { source: 'photo', size: '64x64', colors: 24, latency_ms: 1823 });
```
实现骨架(建议放于公共 bundle 首位):
```js
(function () {
var DKEY = '_pl_device_id', SKEY = '_pl_session_id', QUEUE = '_pl_queue';
function uuid() {
return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
var r = Math.random() * 16 | 0;
return (c === 'x' ? r : (r & 0x3 | 0x8)).toString(16);
});
}
function get(key, gen) {
var v = localStorage.getItem(key);
if (!v) { v = gen(); localStorage.setItem(key, v); }
return v;
}
var deviceId = get(DKEY, uuid);
var sessionId = sessionStorage.getItem(SKEY) || (sessionStorage.setItem(SKEY, uuid()), sessionStorage.getItem(SKEY));
function flush() {
var batch = [];
try { batch = JSON.parse(localStorage.getItem(QUEUE) || '[]'); localStorage.removeItem(QUEUE); } catch (e) {}
if (!batch.length) return;
var body = new Blob([JSON.stringify(batch)], { type: 'application/json' });
// 优先 sendBeacon,降级 fetch keepalive
if (navigator.sendBeacon) { navigator.sendBeacon('/api/analytics/collect', body); return; }
fetch('/api/analytics/collect', { method: 'POST', body: body, keepalive: true, headers: { 'Content-Type': 'application/json' } }).catch(function () {});
}
window.__analytics = function (event, properties) {
properties = properties || {};
var payload = {
event: event,
ts: Date.now(),
device_id: deviceId,
session_id: sessionId,
page: location.pathname,
properties: properties
};
var queue = [];
try { queue = JSON.parse(localStorage.getItem(QUEUE) || '[]'); } catch (e) {}
queue.push(payload);
localStorage.setItem(QUEUE, JSON.stringify(queue));
if (queue.length >= 10) flush();
document.addEventListener('visibilitychange', function () {
if (document.visibilityState === 'hidden') flush();
});
window.addEventListener('pagehide', flush);
};
})();
```
### 4.2 上报方式
| 项 | 方案 | 说明 |
|---|---|---|
| 上报通道 | `navigator.sendBeacon` | 页面关闭不丢包,优先使用;不支持时降级 `fetch(..., { keepalive: true })` |
| 聚合 | 本地 `localStorage` 队列批量上报 | 满 10 条立即上报;`pagehide` / `visibilitychange(hidden)` 兜底刷新 |
| 接口 | `POST /api/analytics/collect` | 后端仅落库,返回 204,不参与业务逻辑;失败静默不重试(防阻塞主流程) |
| 采样 | 全量采集 | MVP 规模小,全量采集便于调试;日事件量超过 20 万再引入采样 |
### 4.3 上报数据结构示例
单事件:
```json
{
"event": "ai_generate_success",
"ts": 1755090000000,
"device_id": "9f1c3a2e-7b84-4d2e-9f1c-3a2e7b844d2e",
"session_id": "b3d2f5a1-6c9e-4f30-b3d2-f5a16c9e4f30",
"page": "/",
"properties": {
"source": "photo",
"size": "64x64",
"colors": 24,
"latency_ms": 1823,
"cost_yuan": 0.03
}
}
```
批量上报(sendBeacon body):
```json
[
{ "event": "page_view", "ts": 1755089999000, "device_id": "9f1c...", "session_id": "b3d2...", "page": "/", "properties": { "referrer": "https://www.xiaohongshu.com" } },
{ "event": "upload_start", "ts": 1755090001000, "device_id": "9f1c...", "session_id": "b3d2...", "page": "/", "properties": { "file_type": "png", "file_size_bytes": 2097152 } }
]
```
### 4.4 埋点与后端接口对照
| 事件 | 关联接口 | 触发说明 |
|---|---|---|
| `redeem_success` / `redeem_fail` | `/api/codes/redeem` | 按接口返回结果上报,`channel` 取返回值 |
| `download_success` / `download_fail` | `/api/codes/consume` | `consume_used=true` 表示本次首次下载扣次 |
| `order_create` / `order_pay_success` | `/api/orders` | 支付回调确认成功后再上报 `order_pay_success`,金额以订单为准 |
| `ai_generate_start` / `ai_generate_success` / `ai_generate_fail` | `/api/chibi/generate` | 开始即上报 `start`,结束按结果上报成功/失败,`cost_yuan` 由后端返回或按模型单价估算 |
---
## 5. 关键指标看板(每日 10 指标)
> 数据源:事件表聚合 + 订单表。所有比率按「去重用户数」计算,统计窗口为自然日(UTC+8)。首月目标值引用 LAUNCH.md §5.1/§5.2。
| # | 指标 | 计算公式 | 首月目标 |
|---|---|---|---|
| 1 | 日活 UV | `COUNT(DISTINCT device_id)`(当日有任意事件) | 300 |
| 2 | 新增用户 | `COUNT(first_visit)`(当日) | 观察值,随渠道投入变化 |
| 3 | 上传转化率 | `COUNT(DISTINCT upload_success.device_id) / COUNT(DISTINCT page_view.device_id)` | ≥45% |
| 4 | 生成转化率 | `COUNT(DISTINCT ai_generate_success.device_id) / COUNT(DISTINCT page_view.device_id)` | ≥25% |
| 5 | 兑换率(付费转化) | `COUNT(DISTINCT redeem_success.device_id) / COUNT(DISTINCT page_view.device_id)` | ≥8%(首月按 5% 起步) |
| 6 | 下载完成率 | `COUNT(DISTINCT download_success.device_id) / COUNT(DISTINCT redeem_success.device_id)` | ≥75% |
| 7 | AI 生成失败率 | `COUNT(ai_generate_fail) / (COUNT(ai_generate_success) + COUNT(ai_generate_fail))` | ≤5%(超线告警,§5.3) |
| 8 | 次日回访率 | `COUNT(昨日UV ∩ 今日UV) / COUNT(昨日UV)` | ≥15% |
| 9 | 日均营收(GMV) | `SUM(order_pay_success.pay_amount)`(当日) | 首月约 ¥1,900/月 |
| 10 | 客单价 | `SUM(order_pay_success.pay_amount) / COUNT(DISTINCT order_pay_success.device_id)` | ¥12.9(以常用包为主) |
**辅助指标**(非每日必看,周度复盘):
- AI 生成成本 = `SUM(ai_generate_success.cost_yuan)` / `COUNT(ai_generate_success)`,单张目标 ¥0.02–0.05(§5.3)。
- 复购率 = 当月发生过 ≥2 次 `redeem_success` 的 device_id / 当月兑换用户数,T+7/T+30 复盘用。
- 分渠道转化率 = 各渠道漏斗第 4 步 / 第 1 步,评估投放 ROI 与代理链接效果。
**看板展示建议**:首页放指标 1/3/4/5/7/9,第二屏放 2/6/8/10 及辅助指标;每日 09:00 生成前一日报告,异常指标(失败率>5%、兑换率低于 4%)自动标注并推送。
+213
View File
@@ -0,0 +1,213 @@
# PERLER LAB 竞品功能对照文档(COMPETITOR-COMPARISON.md)
| 项目 | 内容 |
|---|---|
| 文档版本 | v1.0 |
| 编写日期 | 2026-08-13 |
| 编写角色 | 产品经理(PM-Agent) |
| 竞品 | xylpindou.com(已完成逆向:接口、文案、定价、算法) |
| 我方 | PERLER LAB 拼豆图纸生成器 |
| 事实来源 | `docs/PRD.md`、`docs/DESIGN.md`、`competitor-analysis/copy-library.md` |
| 文档状态 | 评审中 |
---
## 1. 功能对照总表
优先级定义:**P0** = 第一期必须上线;**P1** = 第二期上线;**P2** = 观察数据后迭代。
差距判定口径:
- **一致**:功能形态对齐竞品,无功能缺口。
- **领先**:我方有、竞品没有或更弱。
- **落后**:双方都有,但竞品覆盖更完整。
- **缺失**:竞品有、我方当前未规划。
### 1.1 页面与导航
| # | 功能 | 竞品 | 本项目 | 差距 | 优先级 |
|---|---|---|---|---|---|
| 1 | 品牌 Logo 与导航结构 | P 字母方块 + PERLER LAB,导航含「图片转拼豆 / AI拼豆专区 / 代理合作」 | 同左(DESIGN 2.3) | 一致 | P0 |
| 2 | AI 专区入口 + PRO 标签 | 导航项带 PRO 橙底胶囊标签 | 同左 | 一致 | P0 |
| 3 | 代理合作入口 | 导航按钮,打开代理合作弹窗 | 同左,弹窗展示三档代理套餐 | 一致 | P0 |
| 4 | 状态徽标 | 「● 普通预览免费 · AI生成按次付费」 | 同左 | 一致 | P0 |
| 5 | Hero 宣传区 | IMAGE TO BEADS + 主标题 + 副标题 + 大数字统计 | 同左 | 一致 | P0 |
| 6 | Footer | PERLER LAB · 让每一颗颜色都有位置 | 同左 | 一致 | P0 |
### 1.2 上传
| # | 功能 | 竞品 | 本项目 | 差距 | 优先级 |
|---|---|---|---|---|---|
| 7 | 上传格式 | JPG / PNG / WEBP | JPG / PNG / WebP | 一致 | P0 |
| 8 | 上传方式 | 点击上传(虚线上传区) | 拖拽 + 点击上传 | 领先(新增拖拽) | P0 |
| 9 | 图片大小限制 | ≤ 12MB(错误提示文案) | ≤ 10MB(PRD 3.1) | 落后(上限更小) | P1 |
| 10 | 内置示例图 | 「像素猫咪 · 示例」内置演示图案 | 未规划 | 缺失 | P1 |
### 1.3 图纸参数
| # | 功能 | 竞品 | 本项目 | 差距 | 优先级 |
|---|---|---|---|---|---|
| 11 | 图纸尺寸(格数) | 滑杆 16~128,刻度 16/48/80/128 | 固定档位 48/64/80/96 | 落后(无 16/32 小图、无 128 大图) | P1 |
| 12 | 最大颜色数 | 滑杆 8~48,默认推荐 24 | 固定档位 16/24/32/40 | 落后(无 8/12 低色档) | P2 |
| 13 | 背景去除开关 | 一键去除背景,不计算背景豆 | 去背景开关(PRD 3.1) | 一致 | P0 |
| 14 | 背景识别强度滑杆 | 「背景残留就调高,人物边缘被误删就调低」 | 未规划 | 缺失 | P1 |
| 15 | 背景色设置 | 无 | 支持设置背景色(PRD 3.1) | 领先 | P2 |
| 16 | 辅助网格开关 | 显示辅助网格,默认开 | 未规划(预览固定带网格标尺) | 缺失 | P1 |
| 17 | 重置按钮 | 重置上传与参数 | 未规划 | 缺失 | P1 |
| 18 | 重新生成按钮 | 「↻ 重新生成图纸」 | 调整参数后重新生成 | 一致 | P0 |
### 1.4 预览
| # | 功能 | 竞品 | 本项目 | 差距 | 优先级 |
|---|---|---|---|---|---|
| 19 | 实时预览(免费) | 02 实时预览面板,免费完整预览 | 免费完整预览,预览不耗权益 | 一致 | P0 |
| 20 | 网格标尺 | 每 5 格加粗 · 每 10 格标号 | 同左 | 一致 | P0 |
| 21 | 预览缩放 | 未体现 | 预览画布可缩放(PRD 3.1) | 领先 | P2 |
| 22 | 文件信息展示 | 名称 / 尺寸 / 实际使用颗数 | 预览区展示文件名与规格 | 一致 | P0 |
| 23 | 移动端更换图片 | 「+ 更换图片」按钮 | 移动端基本可用(未细规划) | 落后 | P1 |
### 1.5 MARD 备料清单
| # | 功能 | 竞品 | 本项目 | 差距 | 优先级 |
|---|---|---|---|---|---|
| 24 | 锁定遮罩 | 🔒 受保护,统计数字用 •••• 遮罩 | 同左(DESIGN 3.4) | 一致 | P0 |
| 25 | 分色明细解锁后展示 | 完整 MARD 色号、每色颗数解锁可见 | 同左 | 一致 | P0 |
| 26 | 多备 10% 建议 | 「建议多备 10% · 约 •••• 颗」 | 同左 | 一致 | P0 |
| 27 | 总颗数 / 颜色数统计 | 遮罩下展示 •••• 实际总颗数 / •• 使用颜色 | 同左 | 一致 | P0 |
| 28 | 解锁引导 | 锁定卡 + 「输入兑换码解锁」 | 同左(DESIGN 3.4) | 一致 | P0 |
### 1.6 下载与权益
| # | 功能 | 竞品 | 本项目 | 差距 | 优先级 |
|---|---|---|---|---|---|
| 29 | 高清图纸下载 | 兑换后下载完整图纸 PNG | PNG 含图纸 + 备料单(PRD 4.2) | 一致 | P0 |
| 30 | 首次下载免费 | 「首次下载免费 / 消耗 1 次」 | downloadGrant 判定,同一图纸重复下载不扣 | 一致 | P0 |
| 31 | 兑换码兑换 | 兑换码弹窗,localStorage 绑定 | redeem 接口 + localStorage(perler-download-code) | 一致 | P0 |
| 32 | 权益剩余次数展示 | 「剩余 N 次生成权益」 | 顶部常驻剩余/已用次数 | 一致 | P0 |
| 33 | 未解锁下载引导 | 下载按钮 → 兑换引导 | 无权益时弹兑换弹窗,突出 ¥4.9 体验包 | 一致 | P0 |
| 34 | 支付方式 | 微信收款码 / 支付宝收款码 + 付款备注校验 | MVP 为模拟支付(PRD 9.1) | 落后(MVP 后接入真实渠道) | P0 |
| 35 | 订单查询 | 订单号复制 + 订单状态查询 | 订单查询(PRD 3.1 P1) | 一致 | P1 |
### 1.7 套餐与代理
| # | 功能 | 竞品 | 本项目 | 差距 | 优先级 |
|---|---|---|---|---|---|
| 36 | 个人三档套餐 | 体验 ¥4.9/3、常用 ¥12.9/10、进阶 ¥29.9/30 | 同左,价格逐档对齐 | 一致 | P0 |
| 37 | 代理三档套餐 | 初级 ¥139/200、标准 ¥299/500、核心 ¥499/1000 | 代理 A/B/C 三档同价 | 一致 | P0 |
| 38 | 代理合作弹窗 | 三档套餐 + 采购说明 | 同左(展示 + 模拟下单入口) | 一致 | P0 |
| 39 | 代理兑换码管理 | 名下兑换码、库存、核销记录 | 规划 P2(兑换码管理/分发/核销) | 缺失(P2 补) | P2 |
| 40 | 兑换码批量分发/口令 | 通过代理采购链路分发 | 规划 P2(生成可分发兑换码/口令) | 缺失(P2 补) | P2 |
### 1.8 AI 拼豆专区
| # | 功能 | 竞品 | 本项目 | 差距 | 优先级 |
|---|---|---|---|---|---|
| 41 | 5 大类 × 3 细分 | 风景/人物/宠物/物品/食物,共 15 种风格 | 同左,分类与提示词已复刻 | 一致 | P0 |
| 42 | AI 生成计费 | 成功生成扣 1 次,失败不扣 | 同左 | 一致 | P0 |
| 43 | AI 生成参数 | 格数 48/64/80/96、色数 16/24/32/40、主体构图 3 种 | 同左 + 默认 64/24 | 一致 | P0 |
| 44 | 细节标签 + 自定义描述 | 每类 6 个标签(最多选 5)+ 160 字补充文本 | detailTags 最多 5 + customPrompt | 一致 | P0 |
| 45 | 参考图上传 | 上传需要转换的原图 | referenceImage 可选上传 | 一致 | P0 |
| 46 | 大类对比图(原图 VS 像素成品) | 每类展示对比示例图 | 规划 P1(PRD 5.1 素材已抓取) | 落后 | P1 |
| 47 | 生成前确认 | 规格摘要(类别/细分/格数/预计颗数) | 未规划 | 缺失 | P1 |
| 48 | 结果防丢失 | 未保存时锁住切换,关闭前提醒 | 未规划 | 缺失 | P2 |
| 49 | 长按保存 / 分享 | 长按保存到手机,系统分享不可用降级 | 未规划 | 缺失 | P2 |
### 1.9 账号、扩展与移动端
| # | 功能 | 竞品 | 本项目 | 差距 | 优先级 |
|---|---|---|---|---|---|
| 50 | 历史记录 | 未体现 | 规划 P2(我的生成/下载记录) | 领先 | P2 |
| 51 | 账号体系 / 权益云同步 | 无(依赖设备 localStorage) | 规划 P2(手机/微信登录,跨设备同步) | 领先 | P2 |
| 52 | 批量生成 | 未体现 | 未规划(画像场景提及,可作为差异化) | 缺失(机会项) | P2 |
| 53 | 色号购物清单 | 未体现 | 未规划(可作为差异化) | 缺失(机会项) | P2 |
| 54 | 移动端适配 | 长按保存、更换图片、移动端上传框 | 保证基本可用,桌面优先(PRD 9.2) | 落后 | P1 |
| 55 | 响应式断点 | 移动端适配 | 三档断点:≥1024 三栏 / 768~1023 两栏 / ≤767 单栏 | 一致 | P0 |
| 56 | 移动端底部固定 CTA | 未明确 | 底部固定「购买/兑换」CTA 条(DESIGN 6) | 领先 | P2 |
| 57 | 错误提示文案 | 全站 11 类错误文案已提取 | 复用竞品文案库 | 一致 | P0 |
| 58 | 数据埋点 | 未体现 | 规划 P1 全链路埋点(PRD 8.3) | 领先 | P1 |
> 汇总:共 58 行。**一致 33 项 / 领先 7 项 / 落后 7 项 / 缺失 11 项**(其中 #52 批量生成、#53 色号购物清单作为差异化机会,见第 3 章)。
---
## 2. 差距分析(落后 / 缺失项)
### 2.1 落后项
| # | 落后项 | 影响 | 补救方案 | 优先级 |
|---|---|---|---|---|
| L1 | 真实支付渠道(竞品微信/支付宝收款码,我方模拟支付) | 无真实支付,用户无法实际付费,转化指标无法验证 | 后端订单接口按真实支付形态设计,仅网关可替换;MVP 用模拟支付跑通链路,上线前接入微信/支付宝扫码支付 | P0 |
| L2 | 图纸尺寸范围(竞品滑杆 16~128,我方仅 48/64/80/96) | 缺少 16/32 小尺寸,亲子与手机端轻量场景无法选;缺 128 大尺寸,精细玩家流失 | 参数面板改为滑杆 + 快捷档位(32/64/96/128),保留 48/80 中间档;小尺寸配「简单模式」标签 | P1 |
| L3 | 移动端适配深度(竞品有长按保存、更换图片,我方仅基本可用) | 核心画像中手机/电脑混合使用,移动端体验差直接损失转化 | 移动端单栏布局 + 底部固定 CTA 条;下载后弹「保存图片」引导;预览区提供更换图片按钮 | P1 |
| L4 | AI 大类对比图(竞品已上线,我方 P1) | AI 专区缺少「原图 VS 像素成品」信任锚点,转化说服力弱 | 素材已抓取(competitor-analysis/assets_chibi_*),P1 直接接入;上线前先用静态图占位 | P1 |
| L5 | 图片大小限制(竞品 12MB,我方 10MB) | 高清手机照片常超 10MB,上传失败率高于竞品 | 上限放宽到 12MB 对齐竞品;超出时前端压缩后再传 | P1 |
| L6 | 最大颜色数范围(竞品 8~48,我方 16/24/32/40) | 缺 8/12 低色档,「省豆省钱」场景(亲子、大图)无方案 | 增加 8/12 档位或改滑杆,默认仍 24 | P2 |
| L7 | 移动端更换图片交互 | 换图需重新走上传流程,路径长 | 预览区增加「+ 更换图片」按钮,直接回到上传态 | P1 |
### 2.2 缺失项
| # | 缺失项 | 影响 | 补救方案 | 优先级 |
|---|---|---|---|---|
| M1 | 背景识别强度滑杆 | 去背景效果不可调,主体被误删/背景残留无补救,专业用户不满 | 增加强度滑杆(低=保守保留边缘,高=激进去背景),默认中档 | P1 |
| M2 | 辅助网格开关 | 儿童/新手不需要网格,专业用户又要开,无法自选 | 预览设置增加网格开关,默认开(对齐竞品) | P1 |
| M3 | 重置按钮 | 参数调乱后只能手动逐项恢复 | 参数面板右上角「重置」,恢复默认值并清空上传 | P1 |
| M4 | 内置示例图 | 新用户无素材可用,无法第一时间体验效果 | 内置「像素猫咪」等 2~3 张演示图,首屏即用 | P1 |
| M5 | AI 生成前确认 | 生成即扣权益,无确认环节易引发「被扣费」投诉 | 生成前弹确认卡:类别/细分/格数/预计颗数 + 付费说明 | P1 |
| M6 | AI 结果防丢失 / 长按保存 / 分享降级 | 生成结果误关丢失,移动端保存路径不完整 | 结果未保存时锁定切换 + 关闭前提醒;下载后引导长按保存;系统分享不可用时降级为图片预览 | P2 |
| M7 | 代理兑换码管理 / 核销记录 | 代理无法管理名下库存与核销情况,分销链路断裂 | 代理后台:兑换码列表、剩余库存、核销记录(PRD 3.1 已规划 P2),配合订单支付后自动生成兑换码 | P2 |
| M8 | 兑换码批量分发 / 口令 | 代理只能手动逐个发放,规模化分销效率低 | 生成可分发兑换码/口令,支持一键批量导出(PRD 3.1 已规划 P2) | P2 |
---
## 3. 差异化机会(竞品没有,我们可领先)
| # | 机会项 | 说明 | 对应画像 | 建议优先级 |
|---|---|---|---|---|
| D1 | **批量生成** | 一次上传多张图片,逐个或整批转图纸,按张扣权益。竞品单图单流程,手工博主囤稿需重复操作 10 次。 | 手工博主/代理(US-06、场景 3) | P1 |
| D2 | **色号购物清单** | 解锁后将备料清单一键转换为「按色号 + 颗数」的采购清单,可导出文本/图片,直达电商搜索词。竞品只有每色颗数,无采购场景延伸。 | 手工爱好者(省豆省钱) | P1 |
| D3 | **历史记录 + 权益云同步** | 竞品权益存设备 localStorage,换设备即丢且无任何记录。我们提供登录后历史记录与云端权益(P2),直接解决竞品最大客诉点。 | 全部用户(US-08) | P2 |
| D4 | **背景色设置 / 自定义色板** | 竞品只能一键去背景;我们支持指定背景色,适配「白底作品」「透明贴纸风」等延展玩法。 | 深度用户 | P2 |
| D5 | **新手模式一键预设** | 一键切换「48 格 / 16 色」亲子预设 + 引导文案,竞品无低门槛入口。 | 亲子家长(US-04) | P2 |
选择建议:**D1 批量生成** 与 **D2 色号购物清单** 是成本最低、与现有算法链完全同构的两个机会(都复用单图生成管线),建议作为首发差异化卖点;D3 解决竞品结构性缺陷(本地存储),作为 P2 长期壁垒。
---
## 4. 定价对照
我方定价策略为「对齐竞品、同价竞争」,避免价格战,用体验与差异化取胜。
### 4.1 个人套餐
| 套餐 | 竞品价格 | 竞品次数 | 单次成本 | 我方价格 | 我方次数 | 我方单次成本 | 结论 |
|---|---|---|---|---|---|---|---|
| 体验包 | ¥4.9 | 3 次 | ¥1.63 | ¥4.9 | 3 次 | ¥1.63 | 一致 |
| 常用包 | ¥12.9 | 10 次 | ¥1.29 | ¥12.9 | 10 次 | ¥1.29 | 一致 |
| 进阶包 | ¥29.9 | 30 次 | ¥1.00 | ¥29.9 | 30 次 | ¥1.00 | 一致 |
策略:单价随量递减,引导向上购买;「¥4.9 体验 3 次」作为首单钩子,与竞品完全相同。
### 4.2 代理套餐
| 套餐 | 竞品名称 | 竞品价格/次数 | 单次成本 | 我方名称 | 我方价格/次数 | 我方单次成本 | 结论 |
|---|---|---|---|---|---|---|---|
| A | 初级代理 | ¥139 / 200 次 | ¥0.70 | 代理套餐 A | ¥139 / 200 次 | ¥0.70 | 一致(建议改名「初级代理」对齐认知) |
| B | 标准代理 | ¥299 / 500 次 | ¥0.60 | 代理套餐 B | ¥299 / 500 次 | ¥0.60 | 一致 |
| C | 核心代理 | ¥499 / 1000 次 | ¥0.50 | 代理套餐 C | ¥499 / 1000 次 | ¥0.50 | 一致 |
### 4.3 定价差异结论
- 价格、次数、单次成本三档个人 + 三档代理全部与竞品一致,无价差。
- **差异点仅在权益口径**:竞品 AI 生成与下载统一按次扣减,我方完全对齐,避免「定价高于竞品」的用户感知。
- 代理套餐边界说明:代理套餐的核心差异在「次数量级」与「分发属性」(批量兑换码,P2),价格本身不构成竞争壁垒。
- 建议:MVP 上线后观察竞品是否调价(埋点关注竞品页面),若竞品降价,我方用 D1/D2 差异化功能而非降价应对。
---
## 5. 结论
1. 我方与竞品在核心链路(上传 → 生成 → 预览 → 兑换 → 下载)与定价上完全对齐,P0 目标是把 38 项「一致」项稳定复刻上线。
2. 真实支付(L1)是唯一 P0 级落后项,决定商业闭环能否落地,需在 M5 上线前接入。
3. P1 阶段补齐 6 项差距(尺寸范围、移动端、强度滑杆、网格开关、重置、示例图),使基础体验不低于竞品。
4. 差异化主攻 D1 批量生成 + D2 色号购物清单,两者复用现有算法管线,成本低、对手短期难跟进。
5. 长期壁垒靠 D3 历史记录 + 云同步,直接化解竞品 localStorage 权益易丢失的结构性缺陷。
+738
View File
@@ -0,0 +1,738 @@
# PERLER LAB 拼豆图纸生成器 · 部署架构文档
> 文档版本:v1.0 | 编写角色:架构师(Oracle-Architect-Agent)
> 适用范围:开发环境 / 预发布环境 / 生产环境
---
## 目录
1. [部署架构图](#1-部署架构图)
2. [环境规划](#2-环境规划)
3. [Docker 镜像设计](#3-docker-镜像设计)
4. [域名与 HTTPS 方案](#4-域名与-https-方案)
5. [数据库备份策略](#5-数据库备份策略)
6. [监控告警方案](#6-监控告警方案)
7. [上线 Checklist](#7-上线-checklist)
---
## 1. 部署架构图
```
┌─────────────────────────────────────────────────────────────────────┐
│ 用户浏览器 (Browser) │
│ https://perlerlab.com ← 用户访问入口 │
└──────────────────────────┬──────────────────────────────────────────┘
│
╔═════╧══════════════════════════════╗
║ Cloudflare CDN (可选) ║
║ - DDoS 防护 ║
║ - SSL 证书托管 ║
║ - 缓存静态资源 ║
╚═════╤══════════════════════════════╝
│
┌────────┴────────┐
│ HTTPS :443 │
└────────┬────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 主机 Nginx │ │ Certbot 证书 │ │ 监控脚本 │
│ (Let's Encrypt) │ │ 自动续期 │ │ (cron) │
└──────┬───────┘ └──────────────┘ └──────────────┘
│ 反向代理 / 80→8080(frontend) /api→8788(server)
│
▼
┌───────────────────────────────────┐
│ Docker Compose (同一台主机) │
│ │
│ ┌──────────────────────────┐ │
│ │ perler-lab-frontend │ │
│ │ (nginx:1.27-alpine) │ │
│ │ 端口 :8080 │ │
│ │ - 静态资源 (dist/ + public/)│ │
│ │ - SPA 路由回退 │ │
│ │ - /api 反向代理 → server │ │
│ └──────────┬───────────────┘ │
│ │ 内部网络 perler-net │
│ ┌──────────▼───────────────┐ │
│ │ perler-lab-server │ │
│ │ (node:20-slim) │ │
│ │ 端口 :8788 │ │
│ │ Express + better-sqlite3│ │
│ ├──────────────────────────┤ │
│ │ Volume: db-data:/app/data│ │
│ │ ┌──────────────────┐ │ │
│ │ │ perler-lab.db │ │ │
│ │ │ perler-lab.db- │ │ │
│ │ │ wal (WAL) │ │ │
│ │ │ perler-lab.db- │ │ │
│ │ │ shm (WAL) │ │ │
│ │ └──────────────────┘ │ │
│ └──────────────────────────┘ │
└───────────────────────────────────┘
```
### 请求流程
```
用户访问 https://perlerlab.com
│
▼
Let's Encrypt → 主机 Nginx (443) → 解密 TLS
│
├── /api/* → 反代 localhost:8788 → server 容器
│ → Express 路由 → better-sqlite3
│ → 返回 JSON
│
└── /* → 反代 localhost:8080 → frontend 容器
→ nginx 内部
├── /assets/* → 强缓存 (30d)
├── /dist/* → 强缓存 (30d)
├── /favicon → 缓存 (7d)
└── /* → try_files → /index.html (SPA)
```
---
## 2. 环境规划
### 2.1 环境矩阵
| 维度 | 开发环境 (dev) | 预发布 (staging) | 生产 (prod) |
|------|---------------|------------------|-------------|
| **目的** | 本地开发调试 | 联调 / 验收测试 | 正式对外服务 |
| **机器** | 开发者笔记本 | 轻量云服务器 (2C4G) | 云服务器 (4C8G) |
| **域名** | `localhost:8080` | `staging.perlerlab.com` | `perlerlab.com` |
| **HTTPS** | 无(HTTP) | Let's Encrypt(自动) | Let's Encrypt(自动) |
| **数据库** | SQLite 本地文件 | SQLite + 每日备份 | SQLite + 每小时备份 |
| **Docker** | 可选(直接 node 启动) | 必选(docker compose) | 必选(docker compose) |
| **日志级别** | debug | info | warn |
| **支付** | 模拟接口 | 沙箱环境 | 正式支付对接 |
| **监控** | 无 | 基础健康检查 | 完整告警链 |
### 2.2 开发环境快速启动
```bash
# 终端 1:启动后端
cd perler-lab-server
npm install
npm run dev # tsx watch src/server.ts → http://localhost:8788
# 终端 2:前端库(编译 + 测试)
cd perler-lab
npm install
npm test # 运行测试
npm run typecheck # 类型检查
```
### 2.3 生产环境最低要求
| 资源 | 最低配置 | 推荐配置 |
|------|---------|---------|
| CPU | 2 核 | 4 核 |
| 内存 | 4 GB | 8 GB |
| 磁盘 | 20 GB SSD | 50 GB SSD |
| 带宽 | 5 Mbps | 20 Mbps |
| OS | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS |
| Docker | 24+ | 27+ |
---
## 3. Docker 镜像设计
### 3.1 前端镜像 (`perler-lab/Dockerfile`)
```
┌─────────────────────────────────────────────┐
│ Stage 1: build (node:20-alpine) │
│ ┌───────────────────────────────────────┐ │
│ │ COPY package.json + tsconfig.json + src │ │
│ │ RUN npm install │ │
│ │ RUN npx tsc → dist/ │ │
│ └───────────────────────────────────────┘ │
│ ▼ │
│ Stage 2: serve (nginx:1.27-alpine) │
│ ┌───────────────────────────────────────┐ │
│ │ COPY nginx.conf → /etc/nginx/conf.d/ │ │
│ │ COPY --from=build /app/dist → html/dist│ │
│ │ COPY public/ → html/ (静态资源) │ │
│ │ EXPOSE 80 │ │
│ │ HEALTHCHECK: wget /healthz │ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```
**构建命令:**
```bash
docker build -t perler-lab-frontend:latest perler-lab
```
**关键设计决策:**
- 使用 `npx tsc` 而非 `npm run build`(package.json 中无 build 脚本,不修改源码)
- 无 package-lock.json → 使用 `npm install` 而非 `npm ci`
- `dist/` 与 `public/` 合并至 nginx 根目录,统一对外服务
- 若未来前端迁移至 Next.js,需改为 `next build` + `node server.js` 模式,此 Dockerfile 需重构
### 3.2 后端镜像 (`perler-lab-server/Dockerfile`)
```
┌──────────────────────────────────────────────────┐
│ Stage 1: build (node:20-slim) │
│ ┌────────────────────────────────────────────┐ │
│ │ apt-get: python3, make, g++ (原生模块编译) │ │
│ │ COPY package.json + package-lock.json │ │
│ │ RUN npm ci (含 devDeps) │ │
│ │ COPY src/ + tsconfig.json │ │
│ │ RUN npm run build (tsc → dist/) │ │
│ └────────────────────────────────────────────┘ │
│ ▼ │
│ Stage 2: runtime (node:20-slim) │
│ ┌────────────────────────────────────────────┐ │
│ │ COPY node_modules/ (含 devDeps,需 tsx) │ │
│ │ COPY dist/ (编译产物) │ │
│ │ COPY src/ (tsx 运行时需要源码) │ │
│ │ COPY package.json │ │
│ │ RUN mkdir /app/data + useradd perler │ │
│ │ ENV PORT=8788 │ │
│ │ EXPOSE 8788 │ │
│ │ HEALTHCHECK: fetch /health │ │
│ │ CMD npm run start (tsx src/server.ts) │ │
│ └────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘
```
**构建命令:**
```bash
docker build -t perler-lab-server:latest perler-lab-server
```
**为什么用 `slim` 而非 `alpine`:**
better-sqlite3 提供 glibc (Debian/Ubuntu) 的预编译二进制,在 alpine (musl) 上则需从源码编译。slim 镜像体积比 alpine 大 ~50MB,但构建更快、更可靠,且原生模块兼容性更好。
**为什么运行时依赖 devDeps (tsx):**
`server.ts` 中的 `isMain` 检查通过 `process.argv[1].endsWith("server.ts")` 判断是否为入口文件。编译后的 `dist/server.js` 不满足此条件,因此必须使用 `tsx` 直接运行 .ts 源码。这与 `package.json` 中定义的 `start` 脚本一致。
### 3.3 Docker Compose 启动
**完整启动命令:**
```bash
# 从项目根目录
docker compose -f perler-lab-server/docker-compose.yml up -d --build
# 查看日志
docker compose -f perler-lab-server/docker-compose.yml logs -f
# 停止
docker compose -f perler-lab-server/docker-compose.yml down
```
**服务端口映射:**
| 服务 | 容器内端口 | 宿主机端口 | 说明 |
|------|-----------|-----------|------|
| frontend | 80 | 8080 | 通过主机 Nginx 反代 443→8080 |
| server | 8788 | 不暴露 | 仅 frontend 内部网络访问 |
---
## 4. 域名与 HTTPS 方案
### 4.1 架构概览
采用 **主机 Nginx 反代 Docker Compose** 的经典模式:
```
互联网 → 主机 Nginx (443) → 反代到 Docker Compose 服务
↑
Let's Encrypt (Certbot 自动续期)
```
### 4.2 主机 Nginx 配置
创建 `/etc/nginx/sites-available/perlerlab.com`:
```nginx
server {
listen 80;
server_name perlerlab.com staging.perlerlab.com;
# Let's Encrypt 验证目录
location /.well-known/acme-challenge/ {
root /var/www/certbot;
}
# 其余 HTTP 请求重定向到 HTTPS
location / {
return 301 https://$host$request_uri;
}
}
server {
listen 443 ssl http2;
server_name perlerlab.com;
ssl_certificate /etc/letsencrypt/live/perlerlab.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/perlerlab.com/privkey.pem;
# SSL 配置(Mozilla 推荐)
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1h;
# 安全头
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
# 前端静态资源 → Docker frontend 服务
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# API 请求直接反代到后端(绕过前端 nginx 的 /api 代理)
# 如果希望走前端 nginx 的 /api 代理,可将此 blocks 注释,仅保留上面 /
location /api/ {
proxy_pass http://127.0.0.1:8788;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 120s;
}
# 健康检查
location /healthz {
access_log off;
return 200 "OK";
}
# 日志
access_log /var/log/nginx/perlerlab-access.log;
error_log /var/log/nginx/perlerlab-error.log;
}
```
### 4.3 Let's Encrypt 证书申请与自动续期
```bash
# 安装 Certbot
sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx
# 申请证书(自动配置 Nginx)
sudo certbot --nginx -d perlerlab.com -d staging.perlerlab.com
# 测试自动续期
sudo certbot renew --dry-run
```
Certbot 自动在 `/etc/cron.d/certbot` 中配置每日续期检查。可手动添加 crontab 确认:
```bash
# 每天凌晨 3 点检查续期
0 3 * * * /usr/bin/certbot renew --quiet && systemctl reload nginx
```
### 4.4 防火墙配置
```bash
# 开放 80/443 端口(Ubuntu UFW)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 22/tcp # SSH
sudo ufw enable
# 确认状态
sudo ufw status verbose
```
---
## 5. 数据库备份策略
### 5.1 备份方案
PERLER LAB 使用 SQLite(单文件),备份策略简单直接:
```
备份策略矩阵:
┌──────────────┬────────────┬────────────┬───────────────┐
│ 环境 │ 频率 │ 保留天数 │ 方式 │
├──────────────┼────────────┼────────────┼───────────────┤
│ 开发 (dev) │ 不备份 │ - │ - │
│ 预发布 (stg) │ 每日 04:00 │ 7 天 │ docker cp │
│ 生产 (prod) │ 每小时 │ 30 天 │ sqlite3 .backup│
└──────────────┴────────────┴────────────┴───────────────┘
```
### 5.2 生产环境备份脚本
创建 `/opt/perler-lab/scripts/backup-db.sh`:
```bash
#!/bin/bash
# ============================================================
# PERLER LAB SQLite 数据库备份脚本
# - 使用 sqlite3 .backup 命令在线热备(WAL 模式下安全)
# - 压缩后上传到备份目录 / 对象存储
# - 保留最近 30 天备份
# ============================================================
set -euo pipefail
# 配置
BACKUP_ROOT="/opt/perler-lab/backups"
DB_VOLUME_NAME="perler-lab-server_db-data"
DB_FILE="perler-lab.db"
TIMESTAMP=$(date +"%Y%m%d-%H%M%S")
BACKUP_DIR="${BACKUP_ROOT}/${TIMESTAMP}"
RETENTION_DAYS=30
# 创建备份目录
mkdir -p "${BACKUP_DIR}"
# 方法 1:通过临时容器使用 sqlite3 .backup(推荐——WAL 安全,不停机)
# 启动临时容器挂载 volume,执行 .backup 命令,完成后自动删除
docker run --rm \
-v "${DB_VOLUME_NAME}:/data:ro" \
-v "${BACKUP_DIR}:/backup" \
alpine:3.20 \
sh -c "
apk add --no-cache sqlite > /dev/null
# 使用 sqlite3 .backup 命令进行在线热备
sqlite3 /data/${DB_FILE} \".backup /backup/${DB_FILE}\"
echo 'sqlite3 .backup 完成'
"
# 方法 2:退路——直接复制文件(如果 .backup 不可用)
# 注意:WAL 模式下直接复制文件可能不完整,.backup 更可靠
# docker run --rm -v ${DB_VOLUME_NAME}:/data:ro -v ${BACKUP_DIR}:/backup alpine cp /data/perler-lab.db* /backup/
# 压缩备份
cd "${BACKUP_ROOT}"
tar czf "${TIMESTAMP}.tar.gz" "${TIMESTAMP}"
rm -rf "${TIMESTAMP}"
# 清理过期备份
find "${BACKUP_ROOT}" -name "*.tar.gz" -mtime +${RETENTION_DAYS} -delete
echo "备份完成:${BACKUP_ROOT}/${TIMESTAMP}.tar.gz"
# 可选:上传到对象存储(OSS / S3 兼容)
# if command -v rclone &> /dev/null; then
# rclone copy "${BACKUP_ROOT}/${TIMESTAMP}.tar.gz" remote:perler-lab-backups/
# fi
```
### 5.3 定时任务配置
```bash
# 每小时备份(生产环境)
sudo crontab -e -u root
# 添加以下行:
0 * * * * /opt/perler-lab/scripts/backup-db.sh >> /var/log/perler-db-backup.log 2>&1
```
### 5.4 恢复流程
```bash
# 从备份恢复数据库
# 1. 停止服务
docker compose -f perler-lab-server/docker-compose.yml down
# 2. 从备份 tar.gz 恢复
RESTORE_FILE="/opt/perler-lab/backups/20260813-120000.tar.gz"
TEMP_DIR=$(mktemp -d)
tar xzf "${RESTORE_FILE}" -C "${TEMP_DIR}"
# 3. 恢复数据到 volume
# 先删除旧 volume 内容
docker run --rm -v perler-lab-server_db-data:/data alpine rm -f /data/perler-lab.db*
# 复制备份
docker run --rm \
-v "${TEMP_DIR}:/backup:ro" \
-v perler-lab-server_db-data:/data \
alpine cp /backup/perler-lab.db /data/
# 4. 重启服务
docker compose -f perler-lab-server/docker-compose.yml up -d
# 5. 验证
curl http://localhost:8788/health
# 6. 清理临时目录
rm -rf "${TEMP_DIR}"
```
---
## 6. 监控告警方案
### 6.1 健康检查体系
Docker Compose 中配置了自动健康检查:
| 服务 | 检查方式 | 间隔 | 超时 | 重试 | 启动宽限 |
|------|---------|------|------|------|---------|
| frontend | `wget /healthz` | 30s | 5s | 3 | 10s |
| server | `fetch /health` | 30s | 5s | 3 | 15s |
当服务连续 3 次健康检查失败时,Docker 将标记容器为 `unhealthy`(不会自动重启——`restart: unless-stopped` 只在容器退出时重启,不因健康检查失败重启)。
### 6.2 监控命令速查
```bash
# 查看所有服务状态
docker compose -f perler-lab-server/docker-compose.yml ps
# 查看健康检查状态
docker inspect --format='{{json .State.Health}}' perler-lab-server
docker inspect --format='{{json .State.Health}}' perler-lab-frontend
# 实时日志
docker compose -f perler-lab-server/docker-compose.yml logs -f
# 查看资源使用
docker stats perler-lab-server perler-lab-frontend
# 查看数据库文件大小
docker run --rm -v perler-lab-server_db-data:/data alpine du -sh /data/
```
### 6.3 简易监控脚本
创建 `/opt/perler-lab/scripts/health-check.sh`:
```bash
#!/bin/bash
# ============================================================
# PERLER LAB 简易健康巡检脚本
# 配合 crontab 每 5 分钟执行,失败时发送告警
# ============================================================
set -euo pipefail
ALERT_EMAIL="admin@perlerlab.com" # 替换为实际告警邮箱
COMPOSE_DIR="/opt/perler-lab/perler-lab-server"
SLACK_WEBHOOK="" # 可选:Slack Webhook URL
check_service() {
local name=$1
local url=$2
local status_code
status_code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 10 "${url}" || echo "000")
if [ "${status_code}" != "200" ]; then
echo "[ALERT] ${name} 健康检查失败 (HTTP ${status_code})"
# 邮件告警
echo "${name} 健康检查失败 (HTTP ${status_code}) at $(date)" \
| mail -s "[PERLER LAB] ${name} 服务异常" "${ALERT_EMAIL}"
return 1
fi
echo "[OK] ${name} 健康检查通过 (HTTP ${status_code})"
return 0
}
# 检查前端
check_service "frontend" "http://localhost:8080/healthz"
# 检查后端
check_service "server" "http://localhost:8788/health"
# 检查磁盘使用
DISK_USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')
if [ "${DISK_USAGE}" -gt 85 ]; then
echo "[WARN] 磁盘使用率 ${DISK_USAGE}% 超过 85%"
fi
# 检查内存使用
MEM_USAGE=$(free | grep Mem | awk '{printf "%.0f", $3/$2 * 100}')
if [ "${MEM_USAGE}" -gt 90 ]; then
echo "[WARN] 内存使用率 ${MEM_USAGE}% 超过 90%"
fi
```
### 6.4 告警规则
| 指标 | 阈值 | 动作 | 响应时间 |
|------|------|------|---------|
| 前端健康检查 | 连续 2 次失败 | 邮件告警 | 5 分钟内 |
| 后端健康检查 | 连续 2 次失败 | 邮件告警 | 5 分钟内 |
| 磁盘使用率 | > 85% | 邮件告警 | 1 小时内 |
| 内存使用率 | > 90% | 邮件告警 | 1 小时内 |
| 证书过期 | 距到期 < 30 天 | 邮件告警 | 每日检查 |
| 备份失败 | 最后一次备份 > 2 小时 | 邮件告警 | 2 小时内 |
### 6.5 日志管理
```bash
# Nginx 日志(主机层)
/var/log/nginx/perlerlab-access.log
/var/log/nginx/perlerlab-error.log
# Docker 容器日志
docker logs perler-lab-server
docker logs perler-lab-frontend
# 日志轮转配置(/etc/logrotate.d/perler-lab)
/var/log/nginx/perlerlab-*.log {
daily
rotate 30
compress
delaycompress
missingok
notifempty
postrotate
systemctl reload nginx > /dev/null 2>&1 || true
endscript
}
```
---
## 7. 上线 Checklist
### 7.1 部署前检查
- [ ] **代码检查**
- [ ] `perler-lab` 与 `perler-lab-server` 全部测试通过
- [ ] 类型检查无错误 (`npm run typecheck`)
- [ ] 所有 `.env` 示例文件已提交,敏感值通过 GitHub Secrets 注入
- [ ] 代码已合并到 `main` 分支
- [ ] **基础设施**
- [ ] 服务器已开通,SSH 密钥已配置
- [ ] Docker 已安装 (`docker --version`)
- [ ] Docker Compose 已安装 (`docker compose version`)
- [ ] 域名 DNS 已解析到服务器 IP
- [ ] 80/443 端口防火墙已开放
- [ ] 磁盘空间 > 10 GB (`df -h`)
- [ ] **数据库**
- [ ] 确认 SQLite 数据目录 `data/` 已创建
- [ ] 首次启动时 initDatabase() 自动创建表
- [ ] 备份脚本已部署并测试
- [ ] **HTTPS**
- [ ] Let's Encrypt 证书已申请
- [ ] 自动续期 cron 已配置
- [ ] 主机 Nginx 配置已加载 (`nginx -t && systemctl reload nginx`)
- [ ] **部署**
- [ ] 首次部署建议手动执行 `docker compose up -d --build`
- [ ] 验证所有服务健康检查通过
- [ ] 验证 API 端点可用 (`curl /health`)
- [ ] 验证前端页面可访问
- [ ] 验证兑换码流程完整
### 7.2 部署步骤(首次)
```bash
# 1. SSH 登录服务器
ssh root@perlerlab.com
# 2. 安装 Docker
curl -fsSL https://get.docker.com | bash
sudo usermod -aG docker $USER
# 退出重连使生效
# 3. 克隆代码
git clone <仓库地址> /opt/perler-lab
cd /opt/perler-lab
# 4. 启动服务
docker compose -f perler-lab-server/docker-compose.yml up -d --build
# 5. 验证
curl http://localhost:8080/healthz
curl http://localhost:8788/health
```
### 7.3 部署步骤(更新)
```bash
# 方式一:自动(CI/CD)
# 推送 main 分支 → GitHub Actions 自动执行 deploy 步骤
# 方式二:手动
ssh root@perlerlab.com
cd /opt/perler-lab
git pull origin main
docker compose -f perler-lab-server/docker-compose.yml up -d --build
docker image prune -f
```
### 7.4 回滚方案
```bash
# 回滚到上一个版本
# 1. 查看历史提交
git log --oneline -10
# 2. 回退代码
git reset --hard <上一个正常提交的 SHA>
# 3. 重新构建部署
docker compose -f perler-lab-server/docker-compose.yml up -d --build
# 4. 如果 Docker 镜像有问题,拉取之前构建的版本
# docker tag perler-lab-frontend:previous perler-lab-frontend:latest
# docker compose -f perler-lab-server/docker-compose.yml up -d
```
### 7.5 上线后验证清单
- [ ] 访问 `https://perlerlab.com` → 页面正常加载
- [ ] 访问 `https://perlerlab.com/api/codes` → 返回 401/404 而非 502
- [ ] 上传图片 → 生成拼豆图纸 → 预览正常
- [ ] 兑换码输入 → 解锁成功 → 下载正常
- [ ] 移动端适配 → 响应式布局正常
- [ ] SSL 证书 → 浏览器地址栏显示安全锁
- [ ] 页面加载速度 → Lighthouse 分数 > 70
- [ ] 备份脚本手动执行一遍 → 确认备份文件生成
---
## 附录:常见问题
### Q1: 为什么后端用 `tsx` 而非 `node dist/server.js`?
因为 `server.ts` 中的 `isMain` 检查使用 `process.argv[1].endsWith("server.ts")` 判断是否为主入口。编译后的 `dist/server.js` 不满足此条件,无法自动启动 Express 服务。使用 `tsx` 直接运行 TypeScript 源码与此检查兼容,且与 `package.json` 的 `start` 脚本一致。
若未来重构 `server.ts` 的入口判断逻辑,可将启动方式改为 `node dist/server.js` 并移除 devDeps (tsx)。
### Q2: 数据丢失怎么办?
按照第 5 节的恢复流程操作。如果 backup 不可用,可以尝试从 WAL 文件恢复(`sqlite3` 会在启动时自动回放 WAL 日志)。
### Q3: 如何迁移到 MySQL/PostgreSQL?
当前架构设计为 SQLite 单文件模式,适合 MVP 阶段。后续若需迁移:
1. 将 Express 路由层与数据库层解耦(使用 Repository 模式)
2. 引入 Prisma / Drizzle ORM 替代参数化 SQL
3. 数据库连接信息通过环境变量注入
4. 迁移数据后更新 Dockerfile 无需 node:20-slim(无原生模块依赖)
### Q4: 如何扩展多节点?
当前设计为单机部署。若需横向扩展:
1. 将 SQLite 替换为 PostgreSQL(支持并发读写)
2. 引入 Redis 存储会话和缓存
3. frontend nginx 作为反向代理分发到多个 backend 实例
4. 使用 Docker Swarm 或 Kubernetes 编排容器
+286
View File
@@ -0,0 +1,286 @@
# PERLER LAB 设计规范(DESIGN.md)
> 版本: 1.0 | 适用: 首页(图片转拼豆) + AI专区(/chibi) + 弹窗
> 参考竞品: xylpindou.com(已逆向)· 风格: 温暖纸张质感 + 高级极简
---
## 1. 设计令牌 (Design Tokens)
### 1.1 色彩系统
```css
:root {
/* 背景层级 */
--bg-page: #f4f3ef; /* 页面底色:米白纸张 */
--bg-card: #ffffff; /* 卡片底色 */
--bg-subtle: #f0ede4; /* 次级底色:标签/计数 */
--bg-hover: #faf9f4; /* 悬停底色 */
/* 文字层级 */
--text-primary: #171713; /* 主文字:墨黑 */
--text-secondary: #66645d; /* 次文字 */
--text-tertiary: #8a877d; /* 辅助文字 */
--text-disabled: #b0aca0; /* 禁用文字 */
--text-on-dark: #ffffff; /* 深色底上的白字 */
/* 功能色 */
--accent: #edb045; /* 强调橙:CTA/推荐标签 */
--success: #3daf80; /* 成功绿:通过/已支付 */
--danger: #e04f4f; /* 危险红:错误/不合格 */
--info: #3677d2; /* 信息蓝:链接/进行中 */
/* 边框 */
--border: #e6e3d9; /* 卡片边框 */
--border-strong: #d2cec4; /* 强调边框 */
--border-dashed: #e0dccd; /* 虚线分隔 */
/* 网格线(图纸) */
--grid-strong: rgba(20,20,18,.78);
--grid-medium: rgba(30,30,28,.45);
--grid-light: rgba(30,30,28,.16);
}
```
### 1.2 字体系统
```css
:root {
--font-sans: "Geist", system-ui, -apple-system, "Segoe UI", "PingFang SC",
"Microsoft YaHei", sans-serif;
--font-mono: "Geist Mono", ui-monospace, "Cascadia Code", Consolas, monospace;
--text-xs: 11px; /* 辅助/标签 */
--text-sm: 12px; /* 次要 */
--text-md: 13px; /* 正文 */
--text-lg: 17px; /* 卡片标题/按钮 */
--text-xl: 20px; /* 区块标题 */
--text-hero: 32px; /* Hero H1 */
--weight-regular: 400;
--weight-medium: 500;
--weight-bold: 700;
}
```
### 1.3 间距 / 圆角 / 阴影
```css
:root {
--space-1: 4px; --space-2: 8px; --space-3: 12px;
--space-4: 16px; --space-5: 24px; --space-6: 32px;
--radius-sm: 8px; /* 小控件/标签 */
--radius-md: 10px; /* 卡片 */
--radius-lg: 12px; /* 面板/弹窗 */
--radius-full: 999px; /* 胶囊/圆形 */
--shadow-card: 0 1px 2px rgba(0,0,0,.04);
--shadow-modal: 0 8px 32px rgba(23,23,19,.14);
--shadow-float: 0 2px 12px rgba(23,23,19,.08);
}
```
### 1.4 触控目标
```css
/* 移动端最小触控区域 */
--touch-min: 40px; /* 按钮 */
--touch-min-sm: 34px; /* 标签按钮/导航 */
```
---
## 2. 首页布局(图片转拼豆)
### 2.1 页面骨架
```
┌────────────────────────────────────────────┐
│ NAV: [P] PERLER LAB | 图片转拼豆 | AI拼豆专区[PRO] | 代理合作 | ● 普通预览免费·AI生成按次付费 │
├────────────────────────────────────────────┤
│ HERO: IMAGE TO BEADS │
│ 把喜欢的图片,变成一颗颗拼豆。 │
│ 免费上传、生成和调整图纸… │
│ [0 颗拼豆] [0 种颜色] │
├────────────────────────────────────────────┤
│ DOWNLOAD PASS: AI生成权益 | 3档套餐卡片 + CTA │
├───────────────────┬──────────┬─────────────┤
│ 01 生成设置 │ 02 实时预览│ 03 MARD备料 │
│ 上传框 │ canvas │ 清单(锁定) │
│ 尺寸滑杆 │ 标尺 │ 色号清单 │
│ 颜色滑杆 │ 下载按钮 │ 10%备豆建议 │
│ 背景去除/网格开关 │ │ │
│ [↻ 重新生成图纸] │ │ │
├───────────────────┴──────────┴─────────────┤
│ FOOTER: PERLER LAB · 让每一颗颜色都有位置 │
└────────────────────────────────────────────┘
```
### 2.2 布局规格
| 区域 | 规格 |
|---|---|
| 页面最大宽 | 1280px 居中,两侧留白 24px |
| 桌面三栏 | `grid-template-columns: 320px 1fr 280px; gap: 16px` |
| Hero | 上 64px 下 48px,左对齐 |
| NAV 高度 | 56px,sticky 顶部,白底+细边框 |
| 移动端 | 单列纵向:Hero → 套餐 → 生成设置 → 预览 → 备料清单;NAV 收起为汉堡/底部 CTA 条 |
### 2.3 NAV 组件
- 品牌:`P` 字母方块(品牌色底)+ "PERLER **LAB**"
- 链接:`图片转拼豆`(激活态:下划线/加粗)、`AI拼豆专区`(带 PRO 标签:橙底白字小胶囊)
- 右侧:`代理合作`(text 按钮)、状态徽标 `● 普通预览免费 · AI生成按次付费`(11px,灰字,绿点)
### 2.4 Hero
- Eyebrow:11px 大写字母间距 `IMAGE TO BEADS`,橙色
- H1:32px bold,关键短语 `变成一颗颗拼豆` 用 `<em>` 橙色斜体
- 副标题:14px 灰字
- 统计:`<strong>0</strong>` 大数字 + 小字标签,竖线分隔
### 2.5 套餐卡片(Download Pass)
| 卡片 | 状态 | 规格 |
|---|---|---|
| 体验包 ¥4.9 3次 | 默认 | 白底+边框 |
| 常用包 ¥12.9 10次 | **推荐**(选中)| 橙边框 + `推荐` 角标 + 橙色 CTA |
| 进阶包 ¥29.9 30次 | 默认 | 白底+边框 |
卡片结构:`套餐名 → 价格(¥X.X 大号) → N 次生成 → [购买]`
CTA 按钮:`购买 / 兑换 →`,主按钮橙底白字,圆角 10px,hover 加深。
### 2.6 工作区三栏
- **01 生成设置**(左):上传框 → 文件行 → 尺寸滑杆 → 颜色滑杆 → 背景开关 → 网格开关 → 主按钮
- **02 实时预览**(中):标题栏(`● 实时预览` 绿点 + `每5格加粗·每10格标号`)+ canvas + 底部(名称/尺寸/实际颗数 + 下载按钮)
- **03 MARD 备料清单**(右):`🔒 受保护` 标签 → 遮罩统计(•••• 实际总颗数 / •• 使用颜色)→ 4 行灰色色块行(`完整色号已隐藏`)→ 锁定卡(🔒 + `完整备料清单已锁定` + [输入兑换码解锁])→ `建议多备 10% · 约 •••• 颗`
---
## 3. 交互规范
### 3.1 上传框
| 状态 | 样式 |
|---|---|
| idle | 虚线边框,`+` 大图标,`上传一张图片` + `支持 JPG、PNG、WEBP` |
| hover | 边框橙色,背景 `--bg-hover` |
| loading | 转圈 spinner,文字 `图片处理中…` |
| error | 红边 + 错误文案(如 `图片读取失败,请换一张`) |
| 成功 | 显示缩略图 + 文件名,出现 `重置` 按钮 |
### 3.2 滑杆(Range)
- 尺寸:min 16 / max 128 / step 8,刻度标签 16/48/80/128 + 快捷按钮 32/64/96/128
- 颜色:min 8 / max 48 / step 4,提示 `颜色越多还原度越高;默认推荐 24 色`
- 实时值显示在右侧 `<strong>32 × 32</strong>`
- 进度条已填充部分用橙色,thumb 白色带橙色描边
### 3.3 Toggle 开关
- 开:橙色背景,圆形滑块右移;关:灰底滑块左移
- 行内结构:`[标签] [说明小字] ... [开关]`
- 背景去除开关默认关;辅助网格开关默认开
### 3.4 锁定清单(未兑换状态)
- 统计数字用 `••••` 遮罩(真实值隐藏)
- 色号行显示 `完整色号已隐藏` + 灰色色块
- 锁定卡:🔒 图标 + `完整备料清单已锁定` + 小字说明 + `输入兑换码解锁` 按钮(次级按钮)
### 3.5 弹窗
| 弹窗 | 触发 | 内容 | 规格 |
|---|---|---|---|
| 兑换码 | 点 `输入兑换码解锁` | 输入框 + `兑换` 按钮 + 错误提示 | 居中 modal,圆角 12px,阴影 modal |
| 订单 | 点套餐 CTA | 套餐信息 + 支付方式选择(微信/支付宝 tab) + `去支付` | 同上 |
| 支付 | 订单确认 | 支付二维码/链接 + `我已支付` + `支付失败?` | 同上 |
弹窗通用:遮罩 rgba(23,23,19,.4),内容卡 max-width 380px,右上角 `×` 关闭。
---
## 4. AI 专区页(/chibi)
### 4.1 页面骨架
```
NAV (chibi 版): [← 普通拼豆] PERLER LAB | ● 每次生成消耗 1 次权益
BEAD HERO: IMAGE TO PERLER | 先选大类,再定细节,生成结果先保存。
BEAD BUILDER:
01 选择拼豆大类 [风景][人物][宠物]✓[物品][食物]
└ 大类对比图 (原图 → 像素拼豆效果)
└ 细分选择 (如宠物: 猫咪头像✓/狗狗全身/双宠互动)
02 图纸格数 48简单 / 64推荐✓ / 80精细 / 96高清
03 最大颜色数 16省豆 / 24均衡✓ / 32细腻 / 40高还原
04 主体构图 主体特写✓ / 半幅构图 / 完整构图
05 细节提示词 标签多选(最多5) + 补充文本域(160字) + 参考图上传
生成前确认:
选中示例图 | 规格摘要(类别/细分/图纸/预计颗数) | [上传原图] | 付费说明 | [兑换后生成→]
PROMISE: 分类更准确 / 生成按次计费 / 结果防丢失
FOOTER
```
### 4.2 分类 Tabs
- 5 个分类:风景(山川、城市和旅行纪念) / 人物(五官、发型和穿搭清楚) / 宠物(毛色、表情和品种特征) / 物品(手办、礼物和纪念物) / 食物(甜品、饮品和特色美食)
- 选中态:橙底白字;默认:白底边框
- 每个分类下方:对比图区(原图 → 像素图)+ 3 个细分按钮
### 4.3 细分与标签
- 每类 3 细分,如宠物:`猫咪头像`(圆润脸型与花纹) / `狗狗全身`(耳朵、四肢和毛色) / `双宠互动`(两只宠物同框)
- 提示词标签:`✓ 眼睛更有神`(已选,橙勾)`+ 保留项圈配饰`(未选,加号)
- 最多选 5 个,超出置灰提示 `最多选 5 项`
### 4.4 参数选项行
- 格数:48简单 / **64推荐** / 80精细 / 96高清(4 等分按钮组)
- 颜色:16省豆 / **24均衡** / 32细腻 / 40高还原
- 构图:主体特写 / 半幅构图 / 完整构图(3 等分)
- 选中态:橙底白字圆角 8px
### 4.5 生成按钮
- 未兑换:`兑换后生成 →`(disabled 灰底),点击弹兑换码窗
- 已兑换:`生成 →`(橙底白字)
- 生成中:spinner + `AI 生成中…`
- 文案提示:`每次 AI 成功生成扣 1 次;本作品转图纸和首次下载免费,失败不扣`
---
## 5. 图纸导出规范(PNG)
### 5.1 画布布局
```
┌──────────────────────────────────────────┐
│ 标题: {作品名} · {N}×{N} · MARD 拼豆图纸 │ (24px bold, 左边距 80px)
├──────────────────────────────────────────┤
│ ┌──────────────────────────────────┐ │
│ │ 拼豆网格 (N×N, 每格 28px/22px) │ │ ← 顶部+左侧 80px 边距
│ │ 每格: 豆圆(半径0.42格) + 色号 │ │
│ └──────────────────────────────────┘ │
│ 标尺: 每10格粗线+数字, 每5格中粗线 │
├──────────────────────────────────────────┤
│ MARD 备豆清单 │ (28px bold)
│ 共 {总颗数} 颗 · {颜色数} 种颜色 · 建议多备 10% (约 {1.1×总} 颗) │
│ [色块] {色号} {颗数} [色块] {色号} {颗数} ... (每行 3-4 个) │
└──────────────────────────────────────────┘
```
### 5.2 尺寸规则
| 项目 | 值 |
|---|---|
| 单元格 | gridSize ≥ 96 用 22px,否则 28px |
| 画布宽 | `gridSize × 28/22 + 160` |
| 画布高 | 标题区 80 + 网格 + 清单区(每行 44px + 留白) |
| 网格起点 | (80, 80) |
| 豆圆半径 | 0.42 × 单元格 |
### 5.3 网格线
| 类型 | 颜色 | 线宽 |
|---|---|---|
| 每 10 格 | `rgba(20,20,18,.78)` | 2.6px + 标号(粗体 14px) |
| 每 5 格 | `rgba(30,30,28,.45)` | 1.7px |
| 其余 | `rgba(30,30,28,.16)` | 1px |
### 5.4 色号文字对比度
- 规则:`lab[0] < 52`(深色底)→ 白字 `#fff`;否则 → 深字 `#171713`
- 字号:`max(7px, 0.28 × 单元格)`,加粗,居中
### 5.5 备豆清单
- 色块:圆形 12px 半径,外圈 `#d2cec4` 描边
- 布局:`[色块] {色号}(17px bold 左对齐) {颗数} 颗(15px 灰)`
- 每行 3-4 个(依据总宽度:>1800px 用 3 列,否则 4 列)
### 5.6 文件名
`{作品名}-{N}x{N}-MARD拼豆图纸.png`
---
## 6. 响应式断点
| 断点 | 行为 |
|---|---|
| ≥ 1024px | 桌面三栏布局 |
| 768–1023px | 两栏(设置+预览),备料清单下移 |
| ≤ 767px | 单栏纵向;NAV 简化;底部固定 `购买/兑换` CTA 条;分页按钮触控 ≥ 40px |
+85
View File
@@ -0,0 +1,85 @@
# PERLER LAB 后端端到端(E2E)验证报告
- **日期**: 2026-08-13
- **环境**: Windows / Node.js + tsx / Express 4 + better-sqlite3
- **服务**: `npx tsx src/server.ts`,端口 `8788`
- **执行方式**: 真实 HTTP 请求(curl.exe,UTF-8 原始字节捕获)
- **结论**: ✅ 全部通过(happy path 5 步 + 错误路径 2 步 + CORS 预检)
## 一、验证结果总览
| # | 步骤 | 请求 | 响应(关键字段) | 通过 |
|---|------|------|------------------|:----:|
| 1 | 健康检查 | `GET /health` | `200 {"status":"ok"}` | ✅ |
| 2 | CORS 预检 | `OPTIONS /api/codes/redeem`(Origin: http://localhost:5173) | `204` + `Access-Control-Allow-Origin: http://localhost:5173` | ✅ |
| 3 | 创建订单 | `POST /api/orders` `{packageName:"体验包", paymentMethod:"wechat"}` | `200`,`orderNo=PL20260813211836731707`,金额 490 分 | ✅ |
| 4 | 支付回调 | `POST /api/orders/PL20260813211836731707/pay-callback` | `200`,订单 `paid`,`accessCode=P74AB97BBYLHJE5X` | ✅ |
| 5 | 兑换码激活 | `POST /api/codes/redeem` `{code:"P74AB97BBYLHJE5X"}` | `200`,`remainingUses=3`(totalUses=3,体验包) | ✅ |
| 6 | 消耗次数 | `POST /api/codes/consume` `{code, fileName:"test.png"}` | `200`,`remainingUses=2`,`freeDownload:true` | ✅ |
| 7 | 生成拼豆图 | `POST /api/chibi/generate`(pet/cat,64×64,24 色,主体特写) | `200`,`image` 以 `data:image/png;base64,` 开头,`downloadGrant` UUID,`remainingUses=1` | ✅ |
| 8 | 无效码兑换 | `POST /api/codes/redeem` `{code:"ZZZZZZZZZZZZZZZZ"}` | `404` `{"error":"兑换码不存在,请检查后重试"}` | ✅ |
| 9 | 次数耗尽生成 | 先耗尽 3 次,再 `POST /api/chibi/generate` | `402` `{"error":"生成次数不足"}` | ✅ |
### 各步骤实际响应原文(UTF-8 校验)
| # | 实际响应 |
|---|----------|
| 3 | `{"order":{"orderNo":"PL20260813211836731707","packageName":"体验包","amountCents":490,"paymentMethod":"wechat","status":"pending","createdAt":"2026-08-13T13:18:36.428Z"},"payment":{"url":"https://pay.mock.local/pay?orderNo=PL20260813211836731707&amount=490&method=wechat","qrCode":"https://pay.mock.local/qr?orderNo=PL20260813211836731707"}}` |
| 4 | `{"ok":true,"order":{"order_no":"PL20260813211836731707","package_name":"体验包","amount_cents":490,"payment_method":"wechat","status":"paid","access_code":"P74AB97BBYLHJE5X","created_at":"...","paid_at":"2026-08-13T13:18:36.470Z"},"accessCode":"P74AB97BBYLHJE5X"}` |
| 5 | `{"access":{"code":"P74AB97BBYLHJE5X","packageType":"体验包","remainingUses":3,"totalUses":3}}` |
| 6 | `{"access":{"code":"P74AB97BBYLHJE5X","packageType":"体验包","remainingUses":2,"totalUses":3},"freeDownload":true}` |
| 7 | `image` 前缀 `data:image/png;base64,...`(长度 262,mock 占位 PNG);`downloadGrant=52e50e06-7218-456f-85e1-3567bf29faa9`;`access:{"code":"P74AB97BBYLHJE5X","packageType":"体验包","remainingUses":1,"totalUses":3}` |
| 8 | `{"error":"兑换码不存在,请检查后重试"}`(HTTP 404) |
| 9 | `{"error":"生成次数不足"}`(HTTP 402) |
## 二、发现并修复的集成问题
### Bug 1:缺少 CORS 中间件(唯一修复项)
- **现象**: 所有响应均无 `Access-Control-Allow-Origin` 头,浏览器端(Vite dev,`http://localhost:5173`)跨域请求会被拦截。
- **修复**: 在 `src/server.ts` 增加**手写 CORS 中间件**(不引入 `cors` 依赖):
- 放行白名单:`http://localhost:5173`、`http://127.0.0.1:5173`(Vite dev server)。
- 对预检请求 `OPTIONS` 直接返回 `204`。
- 设置 `Access-Control-Allow-Origin`(回显白名单内 origin)、`Vary: Origin`、`Access-Control-Allow-Methods`、`Access-Control-Allow-Headers`、`Access-Control-Max-Age`。
- **选型说明**: 前端仅有一个已知来源(Vite dev),显式白名单比 `cors` 包默认的 `*` 更安全,且不新增运行时依赖(与 `package.json` 现有依赖面一致)。
- **验证**: 预检返回 `204`,真实请求带 `Access-Control-Allow-Origin: http://localhost:5173` ✅
### 未发现的其他问题(已重点排查)
- **DB schema 与代码一致**:`codes`(code/package_type/total_uses/used_uses/status)、`orders`(order_no/package_name/amount_cents/payment_method/status/access_code/paid_at)、`redemption_logs`、`chibi_generations` 均与 `src/db/schema.ts` 定义吻合,`CREATE TABLE IF NOT EXISTS` 幂等迁移正常。
- **路由挂载正确**:`/api/codes`、`/api/orders`、`/api/chibi` 全部可达,`/health` 独立可用,404 兜底正常。
- **支付回调幂等**:订单已 `paid` 时重复回调返回 200 且不重复生成兑换码。
- **计数链路正确**:pay-callback 生成体验包码(3 次)→ redeem 校验 → consume 原子扣减 → chibi generate 再扣减,最终 `remainingUses=1`;耗尽后 generate 正确返回 402。
- **中文 UTF-8 输出**:响应体中文(套餐名、错误信息)经原始字节校验完整无损。
- **类型检查**: `tsc --noEmit` 严格模式通过;单元测试 36/36 通过。
## 三、复现步骤
```bash
# 1. 启动服务
cd D:\拼豆\perler-lab-server
npx tsx src/server.ts # 监听 http://localhost:8788
# 2. 健康检查
curl http://localhost:8788/health
# 3. 创建订单
curl -X POST http://localhost:8788/api/orders \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"packageName":"体验包","paymentMethod":"wechat"}'
# 4. 支付回调(替换 orderNo)
curl -X POST http://localhost:8788/api/orders/<orderNo>/pay-callback \
-H "Content-Type: application/json" -d '{}'
# 5. 兑换 / 消耗 / 生成(替换 accessCode)
curl -X POST http://localhost:8788/api/codes/redeem -H "Content-Type: application/json" -d '{"code":"<accessCode>"}'
curl -X POST http://localhost:8788/api/codes/consume -H "Content-Type: application/json" -d '{"code":"<accessCode>","fileName":"test.png"}'
curl -X POST http://localhost:8788/api/chibi/generate -H "Content-Type: application/json" -d '{"code":"<accessCode>","image":"data:image/png;base64,iVBORw0KGgo=","category":"pet","subtype":"cat","gridSize":64,"colorCount":24,"composition":"主体特写","detailTags":["眼睛更有神"]}'
```
## 四、变更文件
| 文件 | 变更 |
|------|------|
| `perler-lab-server/src/server.ts` | 新增手写 CORS 中间件(白名单 + OPTIONS 204) |
+207
View File
@@ -0,0 +1,207 @@
# PERLER LAB 上线与运营方案(LAUNCH.md)
> 版本: 1.0 | 关联: PRD.md | 定价基准: 体验¥4.9/3次 · 常用¥12.9/10次 · 进阶¥29.9/30次
> 说明: 所有增长目标均为假设值,需上线后以真实数据校准
---
## 1. 上线冷启动方案
### 1.1 首发渠道(按优先级)
| 渠道 | 打法 | 目标 |
|---|---|---|
| **小红书** | 图文教程类:`拼豆图纸怎么生成`、`宠物照片转拼豆`,带成品效果图 | 种子用户主要来源 |
| **抖音/视频号** | 15s 短视频:上传照片→生成图纸→拼豆过程延时 | 品牌曝光 + 引流 |
| **拼豆爱好者社群** | 微信群/QQ群/B站专栏投放,直接送体验码 | 高转化核心用户 |
| **淘宝/闲鱼** | 挂"定制拼豆图纸代做"链接,跳转站内 | 变现副线 |
### 1.2 种子用户获取(首批 200 人)
1. 生成 100 个体验包兑换码(¥4.9/3次),定向发给拼豆社群 KOC
2. 发起"晒图纸返现"活动:发布成品图 + 站点链接,返 ¥1 或送 1 次权益
3. 上线首周首页挂"新用户免费生成 1 次"(通过体验码实现)
### 1.3 上线时间线
| 阶段 | 时间 | 动作 |
|---|---|---|
| T-7 | 上线前一周 | 完成技术验收、压力测试、文案定稿 |
| T-3 | 前三天 | 小红书/抖音预热内容排期,社群预告 |
| T-0 | 上线日 | 发布渠道内容,开放体验码领取 |
| T+7 | 一周 | 数据复盘:转化漏斗、兑换率、复购率 |
| T+14 | 两周 | 迭代:按数据优化首页 CTA / 套餐价格 |
| T+30 | 一月 | 启动代理招募,评估付费投放 |
### 1.4 小红书/抖音文案示例
```
【示例1 · 小红书图文】
标题:把猫主子变成拼豆图纸,太治愈了😭
正文:上传一张照片 → 自动生成拼豆图纸(色号+颗数全标好)
我用的是 64×64 格、24 色,还原度绝了!
第一次做拼豆的朋友也能看懂~
📍 评论区留"图纸"免费领体验码
标签:#拼豆 #拼豆图纸 #手工 #宠物 #教程
【示例2 · 抖音视频】
标题:照片转拼豆图纸,30秒学会
脚本:0-3s 上传照片动画 → 3-8s 图纸生成过程 → 8-13s 成品展示 → 13-15s "评论区领体验码"
BGM:轻快手工风
```
---
## 2. SEO 优化方案
### 2.1 关键词表
| 关键词 | 搜索意图 | 难度 | 页面 |
|---|---|---|---|
| 拼豆图纸 | 获取图纸 | 高 | 首页 |
| 图片转拼豆 | 工具需求 | 中 | 首页 |
| 拼豆图案生成 | 工具需求 | 中 | 首页 |
| 拼豆色号表 | 色号查询 | 中 | 新增色号页 |
| MARD 拼豆 | 品牌词 | 低 | 备料清单 |
| 拼豆生成器 | 工具需求 | 低 | 首页 |
| 像素图转拼豆 | 精确需求 | 低 | 首页 |
| 拼豆模板 | 素材需求 | 高 | 素材页 |
### 2.2 页面 Meta 优化
```
首页:
title: 拼豆工坊 · 图片转拼豆图纸 | PERLER LAB
description: 上传图片,自动生成拼豆图纸、色号和用量清单。免费预览,兑换码解锁高清下载。
keywords: 拼豆图纸,图片转拼豆,拼豆图案生成,MARD拼豆,拼豆色号表
/chibi:
title: AI拼豆专区 · 宠物/风景/人物像素拼豆生成 | PERLER LAB
description: 先选大类再定细节,AI 生成像素拼豆效果,一键转正式图纸。
```
### 2.3 结构化数据(JSON-LD)
- 首页挂 `WebApplication` schema(name/url/offers 三档价格)
- 图片资源加 `ImageObject` schema
- 建议新增 `/palette` 色号对照页(纯内容页,吃"拼豆色号表"长尾流量)
### 2.4 技术 SEO
- 全站 HTTPS + 规范 URL(去掉尾斜杠重复)
- 图片懒加载 + 合理 alt(`宠物像素拼豆效果图`)
- sitemap.xml + robots.txt
- 首屏 LCP < 2.5s(算法库代码分割 + 静态资源强缓存)
---
## 3. 代理合作方案
### 3.1 代理套餐定价(沿用竞品结构)
| 套餐 | 价格 | 生成次数 | 适用 |
|---|---|---|---|
| 入门代理 | ¥139 | 200 次 | 个人接单 |
| 标准代理 | ¥299 | 500 次 | 工作室 |
| 核心代理 | ¥499 | 1000 次 | 店铺/团队 |
### 3.2 代理权益
1. 按次生成权益(无有效期限制,长期有效)
2. 专属推广链接(带代理标识,转化可追踪)
3. 代理价拿货:批量采购 ≥1000 次可谈阶梯价
4. 优先技术支持 + 新功能内测资格
### 3.3 招募话术
```
【微信私聊版】
你好,我们是拼豆图纸生成工具 PERLER LAB。
现在开放代理合作:充值一次生成 500 次,可按次帮客户出图,
单张收费 3-10 元,利润率很高。
同行现在都在用,感兴趣可以发你一份报价单?
【社群版】
PERLER LAB 拼豆图纸代理招募中 🔥
- 出图快:上传照片 30 秒出图纸
- 成本低:¥299 可用 500 次,单次不到 6 毛
- 好变现:接单代出图、卖图纸模板都行
私聊领取代理价目表 →
```
### 3.4 合作流程
```
咨询 → 确认套餐 → 付款(微信/支付宝) → 开通代理权限(发放大额兑换码)
→ 开始接单 → 按需续费
```
---
## 4. 客服 FAQ(15+ 条)
### 4.1 兑换码与权益
| # | 问题 | 回答 |
|---|---|---|
| 1 | 兑换码怎么用? | 首页点"输入兑换码解锁",输入后权益自动到账(存于浏览器本地) |
| 2 | 兑换码丢了怎么办? | 浏览器同一环境重新输入会恢复;换设备/清缓存则无法找回,请务必截图保存 |
| 3 | 体验包/常用包/进阶包区别? | 仅生成次数不同(3/10/30 次),功能完全一致 |
| 4 | 权益会过期吗? | 兑换码长期有效,无有效期限制 |
| 5 | 代理码和个人码能混用吗? | 不能,代理码走代理通道,个人码走个人通道 |
| 6 | 用了一半能退吗? | 虚拟权益一经使用不支持退款,未使用可联系客服协商 |
### 4.2 下载与图纸
| # | 问题 | 回答 |
|---|---|---|
| 7 | 下载图纸要扣几次权益? | 一张图纸首次高清下载免费(含在生成内),再次下载不扣次 |
| 8 | 下载的文件在哪? | 浏览器下载目录,文件名为"作品名-NxN-MARD拼豆图纸.png" |
| 9 | 手机上能下载吗? | 支持,会调用系统分享/下载 |
| 10 | 图纸可以商用吗? | 图纸仅供个人手作参考,商用需授权 |
### 4.3 AI 生成
| # | 问题 | 回答 |
|---|---|---|
| 11 | AI 生成失败扣费吗? | 不扣!只有成功生成才消耗 1 次权益 |
| 12 | AI 结果能转正式图纸吗? | 可以,生成结果转图纸和首次下载免费 |
| 13 | 生成结果会丢失吗? | 未保存时切换操作会被锁定,关闭页面前也会提醒 |
| 14 | 支持什么图片格式? | JPG、PNG、WEBP,最大 12MB |
| 15 | 参考图会照搬主体吗? | 不会,参考图只影响风格,不复制主体 |
### 4.4 其他
| # | 问题 | 回答 |
|---|---|---|
| 16 | 图纸尺寸怎么换算成品大小? | 按 5mm 豆计算:N×N 格 ≈ N×0.5cm 见方(如 32 格 ≈ 16cm) |
| 17 | 色号在哪里买豆? | 备料清单标注 MARD 色号,按色号在拼豆店铺购买对应颜色 |
| 18 | 提示多备 10% 是什么? | 制作损耗建议,清单会自动加 10% 备豆量 |
---
## 5. 运营指标
### 5.1 转化漏斗
```
访问 → 上传图片 → 生成预览 → 兑换解锁 → 下载完成
100% 45% 25% 8% 6% (首月目标)
```
| 环节 | 目标值 | 监测方式 |
|---|---|---|
| 上传转化率 | ≥45% | 前端埋点(上传按钮点击 / 成功) |
| 生成转化率 | ≥25% | 生成成功事件 |
| 兑换率 | ≥8% | 兑换码 redeem 调用 |
| 下载完成率 | ≥75% | consume 调用 |
| 次日回访 | ≥15% | localStorage 标记 + 再次访问统计 |
### 5.2 核心指标
| 指标 | 首月目标(假设值) |
|---|---|
| 日活 UV | 300 |
| 付费转化 | 5%(访问→兑换) |
| 客单价 | ¥12.9(以常用包为主) |
| 月营收 | 约 ¥1,900(300UV×8%×¥12.9×~60%兑换) |
### 5.3 成本监控
| 项 | 说明 |
|---|---|
| AI 生成成本 | 每张约 ¥0.02–0.05(按模型计费),30 次进阶包成本约 ¥1,毛利充足 |
| 监控 | 每日统计 generate 成功/失败率,失败率 >5% 告警 |
---
## 6. 风险与对策
| 风险 | 等级 | 对策 |
|---|---|---|
| 竞品(xylpindou.com)更新反制 | 高 | 已建监控脚本 monitor.js,chunk 变更自动告警,48h 内对齐功能 |
| AI 模型成本失控 | 中 | 设置日生成上限 + 单用户频控;失败不扣费逻辑已实现,防刷 |
| 兑换码套利/滥用 | 中 | 兑换码绑定支付订单;异常高频 redeem 触发风控 |
| 服务稳定性 | 中 | Docker 化部署 + 健康检查 + 自动重启;数据库定时备份 |
| 图片版权风险 | 低 | 用户上传即同意仅用于个人生成;首页注明"仅供个人手作参考" |
| 支付通道合规 | 低 | MVP 用模拟支付,正式版接入微信/支付宝官方商户 |
+384
View File
@@ -0,0 +1,384 @@
# PERLER LAB 拼豆图纸生成器 · 产品需求文档(PRD)
| 项目 | 内容 |
|---|---|
| 文档版本 | v1.0 |
| 编写日期 | 2026-08-13 |
| 编写角色 | 产品经理(PM-Agent) |
| 产品名称 | PERLER LAB(拼豆) |
| 竞品基线 | https://xylpindou.com/(已完成逆向分析) |
| 文档状态 | 评审中 |
---
## 1. 产品概述
### 1.1 产品背景
拼豆(Perler Beads / Fuse Beads)是近年流行的手工 DIY 品类:用户将彩色塑料豆按图纸排列在钉板上,熨烫后成型。拼豆图纸的质量直接决定作品成败,而市面现有工具多为英文、功能简陋、图纸精度差。竞品 xylpindou.com 通过「图片一键转图纸 + AI 生成拼豆画」切入该市场,并采用「预览免费、兑换码解锁下载」的付费模式,已跑通完整商业链路。
PERLER LAB 以竞品为基线进行复刻与优化,目标是在中国区提供体验更顺滑、图纸更专业、付费链路更清晰的拼豆图纸生成工具。
### 1.2 产品定位
**一句话定位**:用户上传任意图片,几秒内生成可下载、可照做的专业拼豆图纸;另设 AI 拼豆专区,输入一句话即可生成专属图案。
**平台形态**:Web 应用(桌面端优先,移动端适配),无 App。
### 1.3 核心价值主张
| 价值点 | 说明 |
|---|---|
| 一键成图 | 上传图片 → 自动降采样、量化、匹配专业色板 → 输出带色号和备料清单的图纸 |
| 专业色板 | 内置 MARD 色板(A~H+M 共 8 系 200+ 色),CIE LAB 色差匹配,颜色还原度高 |
| 免费预览 | 解锁前可完整预览图纸效果,确认满意再付费,降低决策门槛 |
| AI 拼豆 | 5 大类 × 3 细分共 15 种风格,免去找图烦恼,输入描述即可生成 |
| 代理分销 | 面向微商/手工博主的高性价比大额套餐,支持二次分发 |
### 1.4 竞品参考(xylpindou.com)
逆向分析结论(作为唯一事实来源,详见 `competitor-analysis/` 与 `TEAM.md`):
- 技术栈:Next.js 19(App Router,纯前端 canvas 算法),无重型依赖
- 核心算法:4× 采样 → 4×4 像素块众数量化 → k-means++(5 轮)→ MARD 色板 LAB 匹配 → canvas 绘制
- 商业模式:预览免费,兑换码解锁高清图纸;体验/常用/进阶三档套餐 + 代理三档套餐
- 已还原接口 5 个:`/api/codes/redeem`、`/api/orders`(POST/GET)、`/api/codes/consume`、`/api/chibi/generate`
### 1.5 产品目标
| 目标 | 指标 |
|---|---|
| 验证付费意愿 | 首月访问 → 兑换码解锁转化率 ≥ 3% |
| 验证 AI 功能吸引力 | 首月 chibi 生成次数占全站权益消耗 ≥ 30% |
| 跑通完整商业闭环 | 支付对接(可先模拟)→ 兑换码 → 权益扣减 → 下载全链路无断裂 |
---
## 2. 目标用户画像
### 2.1 核心画像
| 画像 | 特征 | 需求 | 付费意愿 |
|---|---|---|---|
| **手工爱好者(主画像)** | 25~40 岁女性为主,小红书/抖音手工博主关注者,日常做拼豆、十字绣、羊毛毡等手工;手机/电脑混合使用 | 把喜欢的图(宠物、风景、动漫截图)变成能照做的图纸,图纸要清晰、色号准确 | 高,愿为成品效果买单 |
| **亲子家长** | 30~45 岁,为孩子做手工启蒙,常在周末操作 | 生成简单、引导清晰、图纸适合儿童操作(大格、少色) | 中高,单价敏感 |
| **手工博主/代理** | 有粉丝基础,需要批量图纸做内容,或代理分销赚差价 | 大额套餐、批量生成、可转赠/二次分发的权益 | 高,走代理套餐 |
| **尝鲜用户** | 偶然看到分享/广告,想试试 AI 生成 | 低门槛体验,最好免费或极低价试一次 | 低,靠体验包转化 |
### 2.2 典型使用场景
1. 用户看到好看的宠物照片,上传后生成图纸,预览满意,用体验包兑换高清图纸下载,照着拼出作品发小红书。
2. 亲子家长带孩子选一张卡通图,选 48 格小图纸、16 色,30 分钟内完成一个简单作品。
3. 手工博主一次性生成 10 张主题图纸囤稿,用于连续多期内容更新。
4. 代理采购 500 次套餐,把兑换码发给旗下学员/客户,赚取差价。
---
## 3. 功能清单与优先级
优先级定义:**P0** = 第一期必须上线(MVP);**P1** = 第二期上线;**P2** = 观察数据后迭代。
### 3.1 功能总表
| 模块 | 功能 | 说明 | 优先级 |
|---|---|---|---|
| **图纸生成** | 图片上传 | 支持 JPG/PNG/WebP,≤10MB,拖拽 + 点击上传 | P0 |
| | 参数设置 | 格数(如 48/64/80/96)、色数(16/24/32/40)、是否去背景、背景色 | P0 |
| | 图纸生成 | 4× 采样 → 众数量化 → k-means++ → MARD 色板匹配 | P0 |
| | 图纸预览 | 画布渲染豆圆 + 色号;网格每 5 格加粗、每 10 格标号;可缩放 | P0 |
| | 备料清单 | 总颗数、色数、每色用量、多备 10% 建议 | P0 |
| **下载解锁** | 高清图纸下载 | 未解锁时下载按钮进入兑换弹窗;解锁后输出 PNG(含图纸 + 备料单) | P0 |
| | 免费预览策略 | 预览不消耗权益,仅下载消耗 | P0 |
| **权益体系** | 兑换码兑换 | 输入兑换码 → 绑定权益次数到当前设备(localStorage) | P0 |
| | 权益扣减 | 每次解锁下载 / 每次 AI 生成消耗 1 次权益 | P0 |
| | 权益展示 | 顶部常驻显示剩余次数、已用次数 | P0 |
| **订单支付** | 套餐下单 | 5 档套餐(见第 4 章),MVP 阶段支付流程可模拟 | P0 |
| | 订单查询 | 查询订单状态,支付成功后自动完成兑换 | P1 |
| **AI 拼豆** | 分类选择 | 5 大类 × 3 细分(见第 5 章) | P0 |
| | AI 生成 | 输入描述词 + 参考图 + 参数 → 返回拼豆图纸 | P0 |
| | 风格预览 | 每类展示「原图 VS 像素成品」对比样例 | P1 |
| **代理/分销** | 兑换码管理 | 代理查看名下兑换码、剩余库存、核销记录 | P2 |
| | 兑换码分发 | 生成可分发的兑换码/口令 | P2 |
| **账号体系** | 登录注册 | 手机号/微信登录,权益跨设备同步 | P2(MVP 不做,权益存本地) |
| | 历史记录 | 我的生成/下载记录 | P2 |
### 3.2 核心链路(P0)
```
上传图片 → 设置参数 → 生成预览(免费) → 满意?→ 兑换码解锁 → 高清下载
↓ 不满意
调整参数重新生成(预览免费)
```
```
AI 拼豆:选择分类/细分 → 输入描述 → 生成(消耗 1 次权益)→ 预览 → 解锁下载
```
---
## 4. 权益体系设计
### 4.1 套餐定价(对齐竞品)
| 套餐 | 价格 | 次数 | 单次成本 | 目标用户 | 适用场景 |
|---|---|---|---|---|---|
| 体验包 | ¥4.9 | 3 次 | ¥1.63 | 尝鲜用户 | 首次体验,降低决策门槛 |
| 常用包 | ¥12.9 | 10 次 | ¥1.29 | 手工爱好者 | 个人日常使用 |
| 进阶包 | ¥29.9 | 30 次 | ¥1.00 | 深度用户 | 高频玩家 |
| 代理套餐 A | ¥139 | 200 次 | ¥0.70 | 手工博主/代理 | 内容囤稿 + 分销 |
| 代理套餐 B | ¥299 | 500 次 | ¥0.60 | 中小代理 | 批量分发 |
| 代理套餐 C | ¥499 | 1000 次 | ¥0.50 | 大代理 | 规模化分销 |
定价策略说明:
- 单价随购买量递减,引导用户向上购买大套餐。
- 代理套餐与个人套餐的边界在于「次数量级」与「分发属性」,代理套餐支持兑换码批量生成(P2)。
- 权益按「次」计,不区分用途:解锁下载 1 次与 AI 生成 1 次等价,统一扣减。
### 4.2 预览免费 / 兑换解锁策略
| 环节 | 是否免费 | 说明 |
|---|---|---|
| 图片上传 + 参数调整 | ✅ 免费 | 可反复调整,不限次数 |
| 图纸预览(含缩放) | ✅ 免费 | 完整预览,水印或低清示意,不提供色号明细下载 |
| 备料清单查看 | ✅ 免费 | 展示总颗数/色数,具体分色明细在解锁后给出 |
| 高清图纸下载(PNG) | ❌ 消耗 1 次权益 | 无权益时弹出兑换引导 |
| AI 拼豆生成 | ❌ 消耗 1 次权益 | 生成即消耗(生成结果含图纸与下载权限) |
解锁引导策略:
- 用户点击「下载高清图纸」且无有效权益时,弹出兑换弹窗(见 6.4)。
- 弹窗内展示三档个人套餐 + 兑换码输入框,突出「¥4.9 体验 3 次」作为首单钩子。
- 已解锁图纸下载不重复扣费(同一图纸在同一权益周期内可重复下载)。
### 4.3 兑换码 / 订单 / 权益流转
依据竞品逆向的接口链设计,完整流转如下:
```
┌─────────┐ POST /api/orders ┌─────────┐ GET /api/orders?orderNo= ┌─────────┐
│ 用户下单 │ ───────────────────→ │ 后端创建 │ ──────────────────────────→ │ 支付回调 │
└─────────┘ └─────────┘ (status=paid 后自动兑换) └─────────┘
│
POST /api/codes/redeem │ 返回兑换码
┌─────────┐ POST /api/codes/redeem ┌─────────┐ ◄─────────────────────────┘
│ 输入兑换码│ ─────────────────────────→ │ 兑换成功 │
└─────────┘ {code} └─────────┘ ← access: {code, usesLeft}
│ 写入 localStorage (perler-download-code)
▼
┌─────────┐ POST /api/codes/consume ┌─────────┐
│ 解锁下载 │ ─────────────────────────→ │ 扣减 1 次│ ← access + freeDownload
└─────────┘ {code,fileName,downloadGrant} └─────────┘
▼
┌─────────┐ POST /api/chibi/generate ┌─────────┐
│ AI 生成 │ ─────────────────────────→ │ 扣减 1 次│ ← image(base64) + access + downloadGrant
└─────────┘ └─────────┘
```
**关键规则**:
| 场景 | 规则 |
|---|---|
| 兑换 | 兑换码需未过期、未耗尽;兑换成功即写入本地权益,返回剩余次数 |
| 支付 → 兑换 | 订单支付成功后自动完成 redeem,用户无需手动输入兑换码 |
| 扣减(下载) | 每次高清下载消耗 1 次;同一图纸重复下载不重复扣(凭 downloadGrant 判定) |
| 扣减(AI) | 每次 AI 生成消耗 1 次,返回的 downloadGrant 允许该图纸解锁下载 |
| 核销 | 权益次数用尽后,再次下载/生成回到兑换弹窗 |
| 本地存储 | MVP 阶段权益存 localStorage(键 `perler-download-code`),无账号体系 |
| 防滥用 | 兑换码单设备绑定;服务端记录核销日志,异常频率触发风控(P1) |
---
## 5. AI 拼豆专区(chibi)
### 5.1 分类体系
5 大类 × 3 细分 = 15 种风格,每类配「原图 VS 像素成品」参考对(素材已抓取,见 `competitor-analysis/assets_chibi_*`)。
| 大类 | 细分(3 种) | 典型描述词示例 |
|---|---|---|
| 风景 | 日出/星空/森林、海边/沙滩、城市/街道 | 「童话森林,晨雾中的小屋」 |
| 人物 | 头像、半身、全身 | 「Q 版少女,双马尾,微笑」 |
| 宠物 | 猫、狗、其他小动物 | 「橘猫趴着打哈欠」 |
| 物品 | 美食周边、文具、日常小物 | 「马克杯,上面有星星图案」 |
| 食物 | 甜品、主食、水果 | 「草莓蛋糕切面,多汁」 |
### 5.2 生成参数
| 参数 | 可选值 | 默认 | 说明 |
|---|---|---|---|
| gridSize(格数) | 48 / 64 / 80 / 96 | 64 | 格数越大越精细,用豆越多 |
| colorCount(色数) | 16 / 24 / 32 / 40 | 24 | 色数越多还原度越高,备料越复杂 |
| composition(构图) | 见细分规则 | 居中 | 控制主体在画面中的位置/大小 |
| detailTags(细节标签) | 每类 6 个提示词标签 | - | 追加细节增强 prompt |
| customPrompt(自定义描述) | 自由文本 | 空 | 用户补充描述 |
| referenceImage(参考图) | 可上传 | 空 | 提供风格参考,可选 |
### 5.3 生成流程
1. 用户进入 `/chibi` 页,选择大类 → 细分。
2. 可选:上传参考图、填写自定义描述。
3. 选择格数、色数。
4. 点击生成 → 校验权益 → `POST /api/chibi/generate` → 返回图纸 base64。
5. 预览生成结果,满意则解锁下载(downloadGrant 已随生成返回),不满意可调整参数重新生成(重新扣减)。
> 生成消耗 1 次权益,与下载解锁同等定价。该策略对齐竞品,避免 AI 生成被滥用。
---
## 6. 页面地图
### 6.1 站点结构
```
/ 首页(图纸生成主流程)
/chibi AI 拼豆专区
弹窗(全局,非独立页面):
· 兑换弹窗(兑换码输入 + 套餐购买入口)
· 订单弹窗(套餐选择 + 支付)
· 订单结果弹窗(支付成功/失败 → 自动兑换)
```
### 6.2 首页(/)
| 区块 | 内容 | 说明 |
|---|---|---|
| 顶部导航 | Logo、权益状态(剩余次数)、AI 专区入口、兑换入口 | 权益状态常驻,引导转化 |
| 上传区 | 拖拽/点击上传,支持 JPG/PNG/WebP | 主 CTA |
| 参数面板 | 格数、色数、去背景开关、背景色 | 默认值 64 格 / 24 色 |
| 预览画布 | 图纸渲染(豆圆 + 色号 + 网格标号),缩放控件 | 免费完整预览 |
| 备料清单 | 总颗数、色数、分色用量、多备 10% | 解锁后展示分色明细 |
| 操作区 | 「下载高清图纸」按钮 | 未解锁时触发兑换弹窗 |
### 6.3 /chibi 页(AI 拼豆专区)
| 区块 | 内容 |
|---|---|
| 分类选择 | 5 大类图标/卡片,选中后展开 3 细分 |
| 风格预览 | 当前细分的「原图 VS 像素成品」对比图 |
| 生成表单 | 自定义描述、参考图上传、格数、色数 |
| 生成结果 | 图纸预览 + 下载按钮 |
| 引导 | 未登录/无权益时展示套餐入口 |
### 6.4 弹窗
| 弹窗 | 触发时机 | 内容 |
|---|---|---|
| 兑换弹窗 | 点击下载/生成且无权益 | 兑换码输入框 + 三档个人套餐卡 + 代理套餐入口(P2) |
| 订单弹窗 | 点击套餐「立即购买」 | 套餐确认、价格、支付方式选择(MVP 为模拟支付) |
| 订单结果弹窗 | 支付回调返回 | 成功:展示兑换码 + 剩余次数,自动 redeem;失败:重试/更换支付方式 |
---
## 7. 用户故事
| # | 角色 | 用户故事 | 验收要点 | 优先级 |
|---|---|---|---|---|
| US-01 | 手工爱好者 | 我想把宠物照片变成拼豆图纸,下载高清版照着拼 | 上传 → 生成 → 预览 → 兑换 → 下载全链路 ≤ 30 秒(不含支付);图纸含色号与备料清单 | P0 |
| US-02 | 尝鲜用户 | 我想花最少的钱先试一次,确定图纸质量再决定是否复购 | 首次兑换引导 ¥4.9 体验包;下载后图纸完整可用;无强制注册 | P0 |
| US-03 | 手工爱好者 | 我想调整格数和色数,找到袋子里豆子够用的方案 | 参数修改后重新生成 ≤ 5 秒;备料清单实时反映用量 | P0 |
| US-04 | 亲子家长 | 我想带孩子做一张简单图纸,不想太复杂 | 48 格 / 16 色一键预设;图纸大格清晰易读 | P0 |
| US-05 | 深度用户 | 我想要一张星空主题的 AI 拼豆图,不用自己找图 | 进入 /chibi → 选风景/星空 → 生成 → 下载,全程 ≤ 2 分钟 | P0 |
| US-06 | 手工博主 | 我想分批次少量购买生成次数,控制成本 | 常用包/进阶包按需购买;剩余次数常驻可见 | P1 |
| US-07 | 代理 | 我想批量采购次数并分发给学员,赚差价 | 代理套餐下单;名下兑换码生成、库存、核销记录(P2);分发链接/口令(P2) | P2 |
| US-08 | 全部用户 | 我想换设备后还能用已购权益 | 账号登录后权益云端同步(P2);MVP 阶段权益仅存本地,需在购买设备使用 | P2 |
---
## 8. 成功指标
### 8.1 北极星指标
**周有效解锁次数**(每周成功解锁下载 + AI 生成的权益消费次数),衡量产品核心价值被实际使用的频率。
### 8.2 指标体系
| 类别 | 指标 | 目标值(首月) | 说明 |
|---|---|---|---|
| 转化 | 访问 → 生成转化率 | ≥ 40% | 上传后成功生成图纸的访客占比 |
| 转化 | 生成 → 兑换码解锁转化率 | ≥ 3% | 核心商业指标 |
| 转化 | 兑换码 → 再次消费转化率 | ≥ 20% | 复购率,验证体验包钩子 |
| 下载 | 高清下载成功率 | ≥ 99% | 解锁后下载 PNG 无失败 |
| AI | chibi 生成占权益消耗比 | ≥ 30% | 验证 AI 功能吸引力 |
| 质量 | 图纸平均色差 | ≤ 2.0(ΔE,LAB) | MARD 色板匹配精度 |
| 性能 | 图纸生成耗时(P50) | ≤ 5 秒 | 桌面端;移动端 ≤ 8 秒 |
| 体验 | 兑换全流程成功率 | ≥ 95% | 支付(模拟)→ redeem → 扣减 → 下载无断点 |
| 稳定性 | 全链路无致命错误率 | 100% | 无阻断性 Bug |
### 8.3 埋点需求(P1)
| 事件 | 时机 |
|---|---|
| `upload_start` / `upload_success` | 上传开始/成功 |
| `generate_click` / `generate_success` | 点击生成 / 生成成功 |
| `preview_seen` | 预览渲染完成 |
| `download_click` | 点击下载(含未解锁) |
| `redeem_popup_seen` / `redeem_submit` / `redeem_success` | 兑换弹窗曝光 / 提交 / 成功 |
| `order_submit` / `order_paid` / `order_fail` | 下单 / 支付成功 / 失败 |
| `chibi_category_select` / `chibi_generate` | AI 分类选择 / 生成 |
---
## 9. MVP 范围定义
### 9.1 第一期(P0)做什么
| 范围 | 内容 |
|---|---|
| 图纸生成 | 图片上传、参数设置(格数/色数/去背景)、核心算法(4× 采样 → 众数量化 → k-means++ → MARD 匹配)、预览、备料清单、PNG 下载 |
| 权益体系 | 预览免费;兑换码兑换(`/api/codes/redeem`);下载扣减(`/api/codes/consume`);权益本地存储 |
| 订单支付 | 三档个人套餐下单(`/api/orders`);**支付流程模拟**(不接真实支付渠道,返回模拟支付成功);支付成功后自动 redeem |
| AI 拼豆 | 5 大类 × 3 细分;格数 48/64/80/96;色数 16/24/32/40;`/api/chibi/generate`;生成即扣 1 次权益 |
| 页面 | 首页(上传→生成→预览→下载)、/chibi 页、兑换弹窗、订单弹窗、订单结果弹窗 |
| 数据 | 核心埋点(见 8.3 中 P0 部分)、基础访问统计 |
### 9.2 第一期(P0)不做什么
| 不做项 | 原因/替代方案 |
|---|---|
| 真实支付对接(微信/支付宝) | 先模拟支付跑通全链路,验证转化后再接入真实渠道 |
| 账号体系/登录注册 | 权益存 localStorage(`perler-download-code`),与竞品一致;换设备丢失问题后置 |
| 权益云端同步 | 依赖账号体系,后置到 P2 |
| 代理套餐购买与兑换码管理 | 代理三档套餐 `¥139/¥299/¥499` 仅做展示与下单入口(可模拟),批量分发/核销记录后置 P2 |
| 历史记录/我的生成 | 后置 P2 |
| 移动端深度优化 | 保证基本可用,重点优化桌面端 |
| 兑换码风控/防刷 | 仅做基础核销日志,风控规则后置 P1 |
| 多语言 | 仅中文 |
### 9.3 里程碑
| 阶段 | 内容 | 出口标准 |
|---|---|---|
| M1 | 核心算法 + 首页生成链路 | 上传→预览→下载全通,算法单测通过 |
| M2 | 权益体系 + 模拟支付 + 兑换弹窗 | 兑换→扣减→下载闭环无断点 |
| M3 | AI 拼豆专区 | 15 种风格生成可用,权益扣减正确 |
| M4 | 埋点 + 联调 + 走查 | 全链路测试通过,达标 8.2 指标基线 |
| M5 | 上线 | 部署完成,监控就绪 |
---
## 10. 附录:接口契约参考(逆向基线)
> 以下为竞品逆向还原的接口形态,作为后端设计与联调基线。MVP 阶段需保证请求/响应字段与前端契约一致,具体 Schema 以架构文档为准。
| 接口 | 方法 | 请求关键字段 | 响应关键字段 | 用途 |
|---|---|---|---|---|
| `/api/codes/redeem` | POST | `{code}` | `access: {code, usesLeft, ...}` | 兑换码兑换 |
| `/api/orders` | POST | `{packageName, paymentMethod}` | `order: {orderNo, status, ...}` | 创建订单 |
| `/api/orders?orderNo=` | GET | `orderNo` | `order.status`(paid 后自动 redeem) | 查询订单 |
| `/api/codes/consume` | POST | `{code, fileName, downloadGrant}` | `access` + `freeDownload` | 下载扣减 |
| `/api/chibi/generate` | POST | `{code, image, referenceImage, category, subtype, gridSize, colorCount, composition, detailTags, customPrompt}` | `image(base64)` + `access` + `downloadGrant` | AI 生成 |
算法链路(全前端,MVP 可原样落地):预处理缩放到 4×格数 → 每格 4×4 块 `/24` 量化取众数均值 → 可选背景去除(4-连通 BFS + CIE LAB 阈值 20)→ k-means++ 量化(5 轮)→ MARD 色板 LAB 匹配 → canvas 绘制(豆圆 + 色号 + 每 5 格加粗 + 每 10 格标号 + 备料清单)。
---
## 11. 风险与开放问题
| # | 风险/问题 | 影响 | 应对 |
|---|---|---|---|
| 1 | 竞品算法未完全实测(接口真实响应待验证) | 参数细节可能偏差 | P0.5 阶段完成 5 接口实测后回填 PRD 附录 |
| 2 | AI 生成依赖外部模型,成本与稳定性未知 | 单次成本可能超套餐定价 | MVP 先接简单模型代理,验证后优化;生成前明确提示将扣 1 次权益 |
| 3 | localStorage 权益可被清除,用户投诉换设备丢失 | 客诉风险 | 兑换弹窗与 FAQ 明示「权益保存在当前设备」;P2 引入账号同步 |
| 4 | 模拟支付与真实支付的差异 | 上线前需二次改版 | 后端订单接口按真实支付形态设计,仅支付网关可替换 |
| 5 | 图纸版权风险(用户上传他人图片) | 合规风险 | 用户协议声明责任归属(P1 补) |
+257
View File
@@ -0,0 +1,257 @@
# PERLER LAB 拼豆图纸生成器 · 产品版本路线图(ROADMAP)
| 项目 | 内容 |
|---|---|
| 文档版本 | v1.0 |
| 编写日期 | 2026-08-13 |
| 编写角色 | PM-Agent |
| 关联文档 | PRD.md(功能与优先级唯一事实来源)、LAUNCH.md(运营/SEO 基线) |
| 当前状态 | V1.0 前后端已完成开发、联调中;Docker/CI 就绪;QA 验收通过 18+ 任务 |
---
## 0. 版本总览
| 版本 | 时间 | 主题 | 核心交付 |
|---|---|---|---|
| **V1.0 上线版** | 当前(2026-08) | 跑通 MVP 商业闭环 | PRD P0 全量上线:生成 + 权益 + 模拟支付 + AI 专区 |
| **V1.1 增长版** | 1 个月内 | 流量与留存 | /palette SEO 页、历史记录、批量生成、导出优化、埋点看板、P1 补全 |
| **V1.2 账号版** | 2~3 个月 | 用户资产与生态 | 账号体系 + 云端同步、素材社区、代理管理系统 |
| **V2.0 平台版** | 半年 | 商业平台化 | 图纸交易市场、PWA 移动端、多语言、真实支付 |
优先级定义沿用 PRD:**P0** = 本版本必须上线;**P1** = 本版本内争取;**P2** = 观察数据后进入后续版本。
---
## 1. V1.0 上线版(当前)
### 1.1 目标
把 PRD 第 9 章定义的 MVP(P0)完整落地上线,验证三件事:图纸质量够不够好、付费意愿存不存在、AI 功能有没有吸引力。上线即可开始积累真实转化数据,为 V1.1 决策提供依据。
### 1.2 范围确认清单(对齐 PRD 9.1)
**已就绪(开发 + QA 已验收,18+ 任务通过)**
| 模块 | 验收项 | 状态 |
|---|---|---|
| 图纸生成 | 图片上传(JPG/PNG/WebP,≤10MB,拖拽 + 点击) | ✅ |
| | 参数设置(格数 48/64/80/96、色数 16/24/32/40、去背景、背景色) | ✅ |
| | 核心算法(4× 采样 → 众数量化 → k-means++ → MARD 色板 LAB 匹配) | ✅ |
| | 图纸预览(豆圆 + 色号 + 每 5 格加粗 + 每 10 格标号 + 缩放) | ✅ |
| | 备料清单(总颗数、色数、分色用量、多备 10%) | ✅ |
| 下载解锁 | 未解锁拦截进入兑换弹窗;解锁后输出 PNG(图纸 + 备料单) | ✅ |
| | 预览免费、仅下载消耗权益;同一图纸凭 downloadGrant 重复下载不扣费 | ✅ |
| 权益体系 | 兑换码兑换 `/api/codes/redeem`、下载扣减 `/api/codes/consume`、AI 扣减 `/api/chibi/generate` | ✅ |
| | 权益存 localStorage(键 `perler-download-code`)、顶部常驻剩余次数 | ✅ |
| 订单支付 | 三档个人套餐下单 `/api/orders`、模拟支付回调、支付成功自动 redeem | ✅ |
| | 支付回调幂等、耗尽返回 402、无效码返回 404 | ✅ |
| AI 拼豆 | 5 大类 × 3 细分、格数/色数参数、生成即扣 1 次权益 | ✅ |
| 页面 | 首页、/chibi 页、兑换弹窗、订单弹窗、订单结果弹窗 | ✅ |
| 工程 | Docker 化部署、CI 就绪、CORS 白名单、`tsc --noEmit` 通过、单测 36/36 | ✅ |
**剩余阻塞项(上线前必须清空)**
| # | 阻塞项 | 说明 | 责任方 |
|---|---|---|---|
| 1 | AI 生成接入真实模型 | E2E 报告显示 `/api/chibi/generate` 当前返回 mock 占位 PNG(长度 262);需接入真实图片生成模型代理,并保留失败不扣费逻辑 | 后端 |
| 2 | 前端联调收尾 | 前端真实场景全链路走查:上传 → 生成 → 预览 → 兑换 → 下载;含移动端基本可用 | 前端 |
| 3 | 上线部署验证 | Docker Compose 全量冷启动、健康检查、自动重启、数据库备份、监控告警生效 | 后端/运维 |
| 4 | 埋点 P0 事件确认 | PRD 8.3 中 P0 事件(上传/生成/预览/下载/兑换/订单/AI 选择与生成)真实上报可用 | 前端 |
| 5 | 用户协议与版权声明 | PRD 风险 #5:用户协议声明上传图片责任归属、图纸仅供个人手作参考 | PM/法务 |
| 6 | 生成接口并发压测 | 桌面端 P50 ≤ 5s、移动端 ≤ 8s;确认压测下接口稳定性与超时兜底 | 后端 |
| 7 | 首屏性能确认 | LCP < 2.5s(算法库代码分割 + 静态资源强缓存) | 前端 |
### 1.3 上线标准 Checklist
**验收**
- [ ] 两条核心链路全通:图片生成链路(上传 → 参数 → 预览免费 → 兑换解锁 → 高清下载)与 AI 链路(选类 → 描述 → 生成扣 1 次 → 预览 → 解锁下载)
- [ ] QA 回归 18+ 任务全绿,无 P0/P1 级缺陷残留
- [ ] 错误路径全通:无效兑换码 404、次数耗尽 402、支付回调幂等、重复下载不重复扣费
- [ ] 单测与类型检查通过(`tsc --noEmit`、单测 36/36)
**性能**
- [ ] 图纸生成耗时 P50 ≤ 5s(桌面端)、≤ 8s(移动端)
- [ ] 首页首屏 LCP < 2.5s
- [ ] 高清下载成功率 ≥ 99%
- [ ] 压测结论记录:并发下单/兑换/生成无 DB 锁死、无 5xx 雪崩
**安全**
- [ ] 全站 HTTPS,CORS 白名单(非 `*`)且带 `Vary: Origin`
- [ ] 兑换码不可枚举:输入校验 + 服务端核销日志 + 高频 redeem 风控阈值
- [ ] 输入注入防护(图片格式/大小校验、API 参数白名单)
- [ ] 密钥与数据库不落仓库,Docker 环境变量注入
### 1.4 成功指标(对齐 PRD 8.2,首月基线)
| 类别 | 指标 | 目标值 |
|---|---|---|
| 北极星 | 周有效解锁次数 | 每周 ≥ 30 次(首月爬坡) |
| 转化 | 访问 → 生成转化率 | ≥ 40% |
| 转化 | 生成 → 兑换解锁转化率 | ≥ 3% |
| 转化 | 兑换 → 再次消费转化率 | ≥ 20% |
| 下载 | 高清下载成功率 | ≥ 99% |
| AI | chibi 生成占权益消耗比 | ≥ 30% |
| 质量 | 图纸平均色差 | ≤ 2.0(ΔE,LAB) |
| 体验 | 兑换全流程成功率(模拟支付 → redeem → 扣减 → 下载) | ≥ 95% |
| 稳定性 | 全链路无致命错误率 | 100% |
### 1.5 依赖项
无外部依赖。V1.0 全部建立在现有前后端 + Docker/CI 之上,仅剩第 1.2 节阻塞项收尾。
---
## 2. V1.1 增长版(1 个月内)
### 2.1 目标
用 SEO 长尾页和留存功能放大 V1.0 验证过的核心链路,把埋点数据变成可看的运营看板。不做账号,所有新功能保持本地优先。
### 2.2 核心功能列表
| # | 功能 | 说明 | 优先级 |
|---|---|---|---|
| 1 | 色号对照页 /palette | 纯内容页:MARD 8 系色板全景、每色 HEX/色名/近似实拍、色号换算说明。吃「拼豆色号表」长尾搜索词(LAUNCH 2.1),挂 JSON-LD `WebPage` schema | P0 |
| 2 | 埋点看板上线 | 埋点事件(PRD 8.3 全部)上报可用;搭建看板:转化漏斗(访问 → 上传 → 生成 → 兑换 → 下载)、渠道来源、套餐分布、AI 分类分布;T+1 数据可用 | P0 |
| 3 | 历史记录(本地版) | 生成/下载记录存 localStorage(含参数、缩略图、downloadGrant),支持重新下载与复用参数。无需登录,与 V1.2 账号同步无缝衔接 | P0 |
| 4 | 批量生成 | 一次上传多图或一个图片文件夹,批量出图并打包下载 ZIP;含批量失败重试与单张进度展示 | P1 |
| 5 | 图纸导出优化 | 导出选项:纸张尺寸(A4/A3 等)、网格开关、色号标注开关、纯备料单、无水印版本;ZIP 批量导出 | P1 |
| 6 | P1 功能补全 | 订单查询(`GET /api/orders?orderNo=` 在订单弹窗内展示支付状态轮询)、AI 风格预览对比图、兑换码高频风控规则落地 | P1 |
| 7 | 兑换引导优化 | 根据看板数据优化兑换弹窗:首单体验包钩子位置、未解锁用户回访提醒 | P2 |
### 2.3 成功指标
| 指标 | 目标值(V1.1 内) |
|---|---|
| /palette 页自然搜索月 UV | ≥ 2000,占全站自然流量 ≥ 20% |
| /palette 页 → 首页跳转率 | ≥ 15%(验证 SEO 长尾导流) |
| 埋点事件上报成功率 | ≥ 99%,看板 T+1 可用率 ≥ 95% |
| 历史记录使用率 | 回访用户中点击历史记录 ≥ 30% |
| 次日回访率 | 较 V1.0 提升 ≥ 5pp(历史记录 + 看板驱动的留存优化) |
| 批量生成成功率 | ≥ 98%,单张平均耗时 ≤ 5s |
| 导出优化后下载成功率 | ≥ 99.5%(导出选项不引入新失败) |
### 2.4 依赖项
- V1.0 上线并积累至少 2 周真实数据(埋点看板据此校准漏斗基线)
- /palette 依赖已内置的 MARD 色板数据源(前端算法已有),需补充色名/HEX/实拍素材
- 批量生成依赖后端新增 ZIP 打包接口或前端纯前端打包(jszip 类方案)
- 埋点看板需确认存储方案(自建轻量统计表 vs 第三方,倾向自建,复用现有 SQLite/Postgres)
---
## 3. V1.2 账号版(2~3 个月)
### 3.1 目标
把本地权益升级为云端资产,把一次性用户沉淀为可识别用户;开启素材社区和代理两条生态线。核心解决 PRD 风险 #3(换设备丢权益客诉)与 P2 代理需求。
### 3.2 核心功能列表
| # | 功能 | 说明 | 优先级 |
|---|---|---|---|
| 1 | 账号体系 | 手机号验证码登录(短信服务);Token 会话;登录后权益自动合并(云端为准) | P0 |
| 2 | 云端同步 | 权益、历史记录、收藏同步到服务端;换设备登录即恢复;跨设备权益使用实时扣减 | P0 |
| 3 | 素材社区 | 用户上传自用图纸公开分享:图纸页 + 作者页 + 分类/搜索 + 收藏;社区页挂 SEO 关键词「拼豆模板」(LAUNCH 2.1 高难度词) | P0 |
| 4 | 代理管理系统 | 代理自助充值(代理三档套餐 ¥139/¥299/¥499)、订单查询、名下兑换码库存与核销记录、批量生成兑换码/口令(PRD P2 补全) | P0 |
| 5 | 内容安全 | 社区上传图片审核(敏感内容过滤 + 人工抽检)、用户举报与下架 | P1 |
| 6 | 移动端体验强化 | 基于 V1.1 埋点数据优化移动端布局、上传压缩、弱网兜底 | P1 |
### 3.3 成功指标
| 指标 | 目标值(V1.2 内) |
|---|---|
| 手机号登录转化率 | 老用户(兑换过权益)≥ 30%,新用户 ≥ 8% |
| 云端同步成功率 | ≥ 99.5%;「换设备丢权益」类客诉降为 0 |
| 跨设备权益恢复满意度 | 同步后权益无损率 100%(以服务端账本为准) |
| 社区内容量 | 月新增分享图纸 ≥ 500 张,活跃分享用户 ≥ 100 人 |
| 社区引流 | 社区带来的自然访问占全站 ≥ 15%(吃「拼豆模板」搜索词) |
| 代理自助转化 | 代理下单自助完成率 ≥ 80%;代理渠道营收占总营收 ≥ 30% |
| 代理管理 | 兑换码库存查询/批量生成的代理使用率 ≥ 70% |
### 3.4 依赖项
- 账号体系依赖短信服务商接入与实名合规;Token 安全设计(刷新 + 风控)
- 云端同步依赖数据库迁移(用户表、同步账本表、历史记录表)与既有 localStorage 数据升级路径
- 素材社区依赖对象存储/CDN、图片缩略图处理、内容审核通道
- 代理管理依赖订单系统扩展(代理套餐下单)与兑换码批量生成能力
- V1.1 的本地历史记录需设计向上兼容的数据迁移
---
## 4. V2.0 平台版(半年)
### 4.1 目标
从「工具」升级为「平台」:图纸可交易、移动端可触及、语言可扩展。接入真实支付,把 V1.0 的模拟支付替换为正式渠道。平台化意味着用户既是消费者也是创作者。
### 4.2 核心功能列表
| # | 功能 | 说明 | 优先级 |
|---|---|---|---|
| 1 | 拼豆图纸交易市场 | 图纸商城:作者定价上架、买家按图纸或按权益购买、作者分润结算;接真实支付(微信/支付宝官方商户) | P0 |
| 2 | 移动端 App(PWA 先行) | 先做 PWA(离线缓存核心算法、可安装、推送预告);验证移动端数据后再评估原生壳 | P0 |
| 3 | 真实支付对接 | 替换模拟支付:微信/支付宝官方商户、退款、对账;保留兑换码链路不变 | P0 |
| 4 | 多语言 | i18n 重构 + 英文站;英文版投放海外(拼豆在欧美是成熟品类,SEO 词与中文市场几乎无竞争) | P1 |
| 5 | 创作者体系 | 作者认证、粉丝关注、作品集、数据看板(曝光/销量/收益) | P1 |
| 6 | 平台治理 | 侵权/盗图投诉处理、交易仲裁、作者保证金与评分 | P1 |
### 4.3 成功指标
| 指标 | 目标值(V2.0 上线 2 个月内) |
|---|---|
| 交易市场 | 月 GMV ≥ ¥10,000;图纸商品数 ≥ 300;交易转化率 ≥ 2% |
| 创作者 | 月活作者 ≥ 30 人;头部作者月收益 ≥ ¥500 |
| PWA | 移动端访问占比 ≥ 40%;PWA 安装率(可安装曝光 → 安装)≥ 5% |
| 真实支付 | 支付成功率 ≥ 95%;退款/对账差错率为 0 |
| 多语言 | 英文站自然访问占全站 ≥ 10%;英文版兑换转化 ≥ 1% |
| 整体 | 周有效解锁次数较 V1.0 增长 ≥ 5 倍(作为北极星收敛验证) |
### 4.4 依赖项
- 交易市场依赖 V1.2 账号体系(卖家身份)与素材社区内容沉淀,以及真实支付渠道完成签约
- PWA 依赖 service worker 离线策略设计、算法库体积优化
- 多语言依赖 i18n 重构完成,英文内容(说明文案、FAQ、SEO)准备
- 平台治理依赖投诉与仲裁流程设计,涉及客服人力
---
## 5. 时间线
```
2026-08 2026-09 2026-10~11 2027-02
┌───────────┐ ┌────────────┐ ┌─────────────────────┐ ┌──────────────┐
│ V1.0 │ │ V1.1 │ │ V1.2 │ │ V2.0 │
│ 上线版 │ │ 增长版 │ │ 账号版 │ │ 平台版 │
│ │ │ │ │ │ │ │
│ 生成+权益 │ │ /palette │ │ 手机号登录+云端同步 │ │ 图纸交易市场 │
│ 模拟支付 │ │ 历史记录 │ │ 素材社区 │ │ PWA+移动端 │
│ AI专区 │ │ 批量生成 │ │ 代理管理系统 │ │ 真实支付 │
│ 埋点P0 │ │ 导出优化 │ │ 内容安全 │ │ 多语言 │
│ │ │ 埋点看板 │ │ 移动端体验强化 │ │ 创作者体系 │
│ │ │ P1补全 │ │ │ │ │
└───────────┘ └────────────┘ └─────────────────────┘ └──────────────┘
▲ ▲ ▲ ▲
│ │ │ │
清空7项阻塞 依赖首月数据校准 依赖账号+存储+审核 依赖账号+社区+支付签约
18+QA任务全绿 漏斗基线 与本地数据迁移 与i18n重构
里程碑出口(Gate):
V1.0 → V1.1:QA 全绿 + 上线后≥2周真实数据(访问→生成≥40% 确认)
V1.1 → V1.2:看板漏斗稳定 + /palette 流量验证 SEO 有效 + 复购≥20% 确认
V1.2 → V2.0:账号渗透≥30% + 社区内容月增≥500 + 代理渠道跑通
```
**版本节奏说明**:四个版本为先后依赖关系,但每版内部功能按优先级弹性裁剪。若 V1.0 数据未达转化基线(访问 → 生成 < 40% 或兑换率 < 3%),优先在 V1.1 投入流量与转化优化而非机械推进功能排期;若 V1.1 埋点看板显示 AI 占比低于 30%,V1.2 需加投 AI 专区运营。指标数据是版本间推进与回退的唯一裁决依据。
---
## 6. 附:与 PRD 优先级映射
| 路线图版本 | 承接的 PRD 优先级 | 说明 |
|---|---|---|
| V1.0 | P0 全量 | 即 PRD 9.1 MVP 范围 |
| V1.1 | P1 全量 + P2 局部(历史记录本地版先行) | 埋点、订单查询、风格预览、风控、本地历史 |
| V1.2 | P2 全量 | 账号体系、云端同步、历史记录云端化、代理管理、素材社区 |
| V2.0 | 新增范围(PRD 未覆盖) | 交易市场、PWA、多语言、真实支付,PRD 需在进入前增补章节 |
+143
View File
@@ -0,0 +1,143 @@
# PERLER LAB 待验收任务验收用例(TEST-PLAN.md)
> 版本: 1.0 | 用途: 对最近交付的 6 项成果执行验收 | 执行环境: 本地开发(服务端口 8788)
> 说明: 执行人逐条测试后填写"实际结果"列,通过则填「PASS」,失败填「FAIL + 现象描述」
---
## 1. 验收范围
| 任务编号 | 交付物 | 位置 |
|---|---|---|
| T-024 | 支付模块(建单/查单/模拟支付回调 + 自动发码) | perler-lab-server/src/payment/ |
| T-026 | chibi 提示词模板(5 大类 × 多细分 + 参考图/构图/细节) | perler-lab-server/src/chibi/prompts.ts |
| T-040 | DESIGN.md(设计规范) | docs/DESIGN.md |
| T-041 | LAUNCH.md(上线运营方案) | docs/LAUNCH.md |
| T-042 | copy-library.md(竞品文案库) | competitor-analysis/copy-library.md |
| T-029 | CI/CD 流水线 deploy.yml | .github/workflows/deploy.yml |
**用例总数:22 条**(含 1 条端到端冒烟测试 TC-22)
---
## 2. 支付模块(T-024)
| 用例ID | 验收项 | 测试步骤 | 预期结果 | 实际结果 |
|---|---|---|---|---|
| TC-01 | 创建订单 | `POST /api/orders`,body `{"packageName":"常用包","paymentMethod":"wechat"}` | 返回 200;`order.status="pending"`、`order.amountCents=1290`、`order.orderNo` 以 `PL` 开头;`payment` 含模拟支付参数 | |
| TC-02 | 非法套餐/支付方式校验 | `POST /api/orders`,body `{"packageName":"不存在","paymentMethod":"wechat"}`;再测 `paymentMethod="cash"` | 两次均返回 400,中文错误「套餐不存在」/「不支持的支付方式」,且不落订单 | |
| TC-03 | 支付回调成功并发码 | 对 TC-01 订单执行 `POST /api/orders/{orderNo}/pay-callback` | 返回 200;`order.status="paid"`、`order.access_code` 非空;`GET /api/orders?orderNo={orderNo}` 可见 paid 状态 | |
| TC-04 | 支付回调幂等 | 对 TC-03 同一订单重复执行 pay-callback 2 次 | 第 2、3 次仍返回 200 `{ok:true}`,不重复生成新兑换码(订单 access_code 不变) | |
---
## 3. chibi 提示词模板(T-026)
| 用例ID | 验收项 | 测试步骤 | 预期结果 | 实际结果 |
|---|---|---|---|---|
| TC-05 | 5 大分类模板完整 | 查看 `prompts.ts`,遍历 `landscape/person/pet/object/food` 五个分类 | 每个分类均有≥2 个细分模板,模板含中文描述、风格词、负面提示词结构完整 | |
| TC-06 | 生成接口接受分类+细分 | `POST /api/chibi/generate`,body 含 `category:"pet","subtype":"<有效细分>","image":"<base64>","gridSize":64,"colorCount":24,"composition":"主体特写"` | 返回 200,含 `image`、`access`、`downloadGrant`;有效兑换码时消耗 1 次 | |
| TC-07 | 非法分类/细分拦截 | 同 TC-06,但 `category:"dragon"`;再测合法分类 + 不存在的 subtype | 两次均返回 400,中文错误「未知的分类」/「未知的模板类型」,不扣次数 | |
| TC-08 | 参考图与自定义提示词 | 同 TC-06 且带 `referenceImage:"<base64>"`、`detailTags:["露珠"]`、`customPrompt:"Q版风"` | 返回 200 且生成成功;无 referenceImage 时可省略不报错 | |
---
## 4. DESIGN.md(T-040)
| 用例ID | 验收项 | 测试步骤 | 预期结果 | 实际结果 |
|---|---|---|---|---|
| TC-09 | 设计规范完整性 | 阅读 docs/DESIGN.md | 含色彩体系(主色/辅色/语义色)、字号层级、间距、圆角、阴影等核心规范章节 | |
| TC-10 | 规范与产品实现一致 | 抽查前端 `perler-lab/src` 中首页/生成页的关键样式(主色、按钮圆角、标题字号)对照 DESIGN.md | 页面取值与规范一致,无重大偏离 | |
| TC-11 | 无障碍与可读性 | 按规范检查正文/按钮前景背景对比度 | 正文与主要 UI 文本对比度 ≥4.5:1,提示文案不依赖单一颜色表达 | |
---
## 5. LAUNCH.md(T-041)
| 用例ID | 验收项 | 测试步骤 | 预期结果 | 实际结果 |
|---|---|---|---|---|
| TC-12 | 定价三档一致 | 对照 LAUNCH.md §3.1 与代码 `PACKAGE_DEFINITIONS`(代理200/500/1000)及个人包(体验 4.9/3次、常用 12.9/10次、进阶 29.9/30次) | 价格、次数全部一致,无一处冲突 | |
| TC-13 | 话术可直接使用 | 阅读 §3.3 微信私聊版与社群版话术 | 两份话术均含产品卖点、报价、转化引导,复制后可直接发送 | |
| TC-14 | FAQ 覆盖核心场景 | 核对 §4 客服 FAQ | 覆盖兑换/权益/下载/AI 生成/其他 ≥15 条,且答案与代码行为一致(如"失败不扣费") | |
---
## 6. copy-library.md(T-042)
| 用例ID | 验收项 | 测试步骤 | 预期结果 | 实际结果 |
|---|---|---|---|---|
| TC-15 | 代理价目表对齐 | 检索 copy-library.md 中代理套餐价格 | 含 ¥139/200次、¥299/500次、¥499/1000次,与 LAUNCH.md §3.1 一致 | |
| TC-16 | 文案条目可复用性 | 抽查 3 条文案(如首屏卖点、套餐说明、FAQ 话术) | 每条均为可直接复用的完整话术,非碎片笔记 | |
| TC-17 | 竞品口径标注 | 检查文案来源/用途标注 | 关键条目注明适用渠道或用途(小红书/社群/客服),便于运营取用 | |
---
## 7. CI/CD 流水线(T-029)
| 用例ID | 验收项 | 测试步骤 | 预期结果 | 实际结果 |
|---|---|---|---|---|
| TC-18 | Workflow 语法有效 | 本地执行 `npx actionlint .github/workflows/deploy.yml`(或 yamllint) | 无语法错误 | |
| TC-19 | 触发条件正确 | 阅读 workflow `on:` 配置 | 含 push 到 main(或 tag)触发;PR 不触发生产部署 | |
| TC-20 | 构建+测试阶段完整 | 检查 job 步骤 | 前端 `perler-lab` 与后端 `perler-lab-server` 均执行构建;后端运行 `vitest` 测试且失败即中断 | |
| TC-21 | 部署动作真实 | 检查部署步骤 | 使用 docker/build-push(构建镜像)并按 DEPLOY.md 目标服务器/服务执行部署,含健康检查或 SSM 校验 | |
---
## 8. 端到端冒烟测试(TC-22):建单→支付→redeem→consume
> 前置条件:服务已启动(`cd perler-lab-server && npm run dev`,监听 8788);数据库可写。
> 下方命令可直接复制执行(PowerShell 环境)。
```powershell
$base = "http://localhost:8788"
# Step 1 建单:创建常用包订单
$order = Invoke-RestMethod -Method Post -Uri "$base/api/orders" `
-ContentType "application/json" `
-Body '{"packageName":"常用包","paymentMethod":"wechat"}'
# 断言: $order.order.status == "pending" 且 amountCents == 1290
$orderNo = $order.order.orderNo
Write-Host "订单号: $orderNo, 状态: $($order.order.status)"
# Step 2 支付:触发模拟支付回调
$pay = Invoke-RestMethod -Method Post -Uri "$base/api/orders/$orderNo/pay-callback"
# 断言: $pay.ok == $true 且 $pay.order.status == "paid"
$code = $pay.accessCode
Write-Host "支付完成, 兑换码: $code, 次数: $($pay.order.totalUses)"
# Step 3 redeem:兑换兑换码
$redeem = Invoke-RestMethod -Method Post -Uri "$base/api/codes/redeem" `
-ContentType "application/json" `
-Body (@{ code = $code } | ConvertTo-Json)
# 断言: $redeem.access.remainingUses == 10 且 packageType == "常用包"
Write-Host "兑换成功, 剩余: $($redeem.access.remainingUses)/$($redeem.access.totalUses)"
# Step 4 consume:消耗 1 次
$consume = Invoke-RestMethod -Method Post -Uri "$base/api/codes/consume" `
-ContentType "application/json" `
-Body (@{ code = $code } | ConvertTo-Json)
# 断言: $consume.access.remainingUses == 9 且 freeDownload == $true
Write-Host "消耗 1 次, 剩余: $($consume.access.remainingUses)"
# Step 5 复核:状态查询(可选)
$status = Invoke-RestMethod -Method Get -Uri "$base/api/codes/status?code=$code"
Write-Host "状态复核, 剩余: $($status.access.remainingUses)"
```
| 步骤断言汇总 | 预期结果 | 实际结果 |
|---|---|---|
| 建单 | 200,status=pending,amountCents=1290,orderNo 以 PL 开头 | |
| 支付回调 | 200,ok=true,status=paid,accessCode 非空,totalUses=10 | |
| redeem | 200,access.remainingUses=10,packageType=常用包 | |
| consume | 200,access.remainingUses=9,freeDownload=true | |
| 全链路 | 四步全部 PASS 即端到端验收通过 | |
---
## 9. 执行记录
| 执行日期 | 执行人 | 通过/失败 | 备注 |
|---|---|---|---|
| (待填写) | | | |
> 通过标准:TC-01~TC-22 全部 PASS;任一 FAIL 需记录现象并转对应任务修复后复测。
+525
View File
@@ -0,0 +1,525 @@
# 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 有 `查询失败` 文案备用)
+813
View File
@@ -0,0 +1,813 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>PERLER LAB · AI 拼豆专区(交互原型)</title>
<style>
/* ═══════════════════════════════════════════════════════════════
PERLER LAB · AI 拼豆专区 (/chibi) 交互原型
设计令牌来自 DESIGN.md §1/§4 · 文案来自 copy-library.md §8
═══════════════════════════════════════════════════════════════ */
:root{
--bg-page:#f4f3ef; --bg-card:#ffffff; --bg-subtle:#f0ede4; --bg-hover:#faf9f4;
--text-primary:#171713; --text-secondary:#66645d; --text-tertiary:#8a877d;
--text-disabled:#b0aca0; --text-on-dark:#ffffff;
--accent:#edb045; --success:#3daf80; --danger:#e04f4f; --info:#3677d2;
--border:#e6e3d9; --border-strong:#d2cec4; --border-dashed:#e0dccd;
--font-sans:system-ui,-apple-system,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;
--font-mono:ui-monospace,"Cascadia Code",Consolas,monospace;
--text-xs:11px; --text-sm:12px; --text-md:13px; --text-lg:17px; --text-xl:20px; --text-hero:32px;
--space-1:4px; --space-2:8px; --space-3:12px; --space-4:16px; --space-5:24px; --space-6:32px;
--radius-sm:8px; --radius-md:10px; --radius-lg:12px; --radius-full:999px;
--shadow-card:0 1px 2px rgba(0,0,0,.04);
--shadow-modal:0 8px 32px rgba(23,23,19,.14);
--shadow-float:0 2px 12px rgba(23,23,19,.08);
}
*{box-sizing:border-box;margin:0;padding:0}
body{font-family:var(--font-sans);background:var(--bg-page);color:var(--text-primary);font-size:var(--text-md);line-height:1.6;-webkit-font-smoothing:antialiased}
button{font-family:inherit;cursor:pointer;border:none;background:none;color:inherit}
input,textarea{font-family:inherit}
.page{max-width:880px;margin:0 auto;padding:0 24px}
/* ── NAV (chibi 版) ── */
.nav{position:sticky;top:0;z-index:50;background:var(--bg-card);border-bottom:1px solid var(--border)}
.nav-inner{max-width:960px;margin:0 auto;padding:0 24px;height:56px;display:flex;align-items:center;gap:var(--space-4)}
.nav-back{display:inline-flex;align-items:center;gap:6px;font-size:var(--text-sm);color:var(--text-secondary);text-decoration:none;font-weight:var(--weight-medium);padding:6px 10px;border-radius:var(--radius-sm)}
.nav-back:hover{background:var(--bg-subtle);color:var(--text-primary)}
.brand{display:flex;align-items:center;gap:var(--space-2);text-decoration:none;color:var(--text-primary);font-weight:700;font-size:var(--text-lg)}
.brand-mark{width:26px;height:26px;border-radius:6px;background:var(--accent);color:var(--text-primary);display:inline-flex;align-items:center;justify-content:center;font-weight:700;font-size:14px}
.nav-spacer{flex:1}
.nav-badge{display:inline-flex;align-items:center;gap:6px;font-size:var(--text-xs);color:var(--text-tertiary);background:var(--bg-subtle);padding:4px 10px;border-radius:var(--radius-full)}
.nav-badge-dot{width:7px;height:7px;border-radius:50%;background:var(--success);display:inline-block}
/* ── HERO ── */
.hero{padding:48px 0 28px}
.eyebrow{font-size:var(--text-xs);letter-spacing:.22em;text-transform:uppercase;color:var(--accent);font-weight:700}
.hero h1{font-size:var(--text-hero);font-weight:700;line-height:1.25;margin:12px 0 14px;letter-spacing:-.01em}
.hero h1 em{font-style:italic;color:var(--accent)}
.hero-sub{font-size:14px;color:var(--text-secondary);max-width:640px}
/* ── 卡片 ── */
.card{background:var(--bg-card);border:1px solid var(--border);border-radius:var(--radius-lg);box-shadow:var(--shadow-card);padding:var(--space-5);margin-top:var(--space-4)}
.section-head{display:flex;align-items:center;gap:var(--space-2);margin-bottom:var(--space-4)}
.section-num{font-family:var(--font-mono);font-size:var(--text-xs);color:var(--accent);font-weight:700;background:var(--bg-subtle);padding:2px 7px;border-radius:var(--radius-sm)}
.section-title{font-size:var(--text-lg);font-weight:700}
.section-note{margin-left:auto;font-size:var(--text-xs);color:var(--text-tertiary)}
/* ── 分类 Tabs ── */
.tabs{display:grid;grid-template-columns:repeat(5,1fr);gap:var(--space-2)}
.tab{border:1px solid var(--border);border-radius:var(--radius-md);padding:10px 6px;text-align:center;background:var(--bg-card);transition:border-color .15s,background .15s}
.tab:hover{border-color:var(--border-strong)}
.tab.is-selected{background:var(--accent);border-color:var(--accent)}
.tab-name{display:block;font-size:var(--text-md);font-weight:700}
.tab-note{display:block;font-size:10px;color:var(--text-tertiary);margin-top:2px;line-height:1.4}
.tab.is-selected .tab-note{color:rgba(23,23,19,.65)}
/* 对比图 */
.compare{display:flex;align-items:center;gap:var(--space-4);margin:var(--space-4) 0}
.compare-box{flex:1;border:1px dashed var(--border-strong);border-radius:var(--radius-md);padding:var(--space-3);text-align:center;background:var(--bg-hover)}
.compare-label{display:block;font-size:var(--text-xs);color:var(--text-tertiary);margin-bottom:8px}
.compare-arrow{font-size:20px;color:var(--text-disabled)}
.pixel{display:grid;grid-template-columns:repeat(8,1fr);gap:2px;width:96px;margin:0 auto}
.pixel span{border-radius:50%;aspect-ratio:1;display:block}
.compare-source{width:96px;height:96px;margin:0 auto;border-radius:var(--radius-sm);background:
radial-gradient(circle at 30% 30%, #d2cec4 0%, transparent 60%),
radial-gradient(circle at 70% 65%, #b0aca0 0%, transparent 55%),
linear-gradient(145deg,#f5dfae 0%,#e8e4d8 100%)}
/* 细分 */
.subtype-title{font-size:var(--text-xs);color:var(--text-tertiary);margin:var(--space-4) 0 var(--space-2)}
.subtypes{display:grid;grid-template-columns:repeat(3,1fr);gap:var(--space-2)}
.subtype{border:1px solid var(--border);border-radius:var(--radius-md);padding:10px 12px;text-align:left;background:var(--bg-card)}
.subtype:hover{border-color:var(--border-strong)}
.subtype.is-selected{border-color:var(--accent);background:var(--bg-hover)}
.subtype-name{display:block;font-size:var(--text-md);font-weight:700}
.subtype-note{display:block;font-size:10px;color:var(--text-tertiary);margin-top:2px}
/* 参数选项 */
.options{display:grid;grid-template-columns:repeat(4,1fr);gap:var(--space-2)}
.options.is-3col{grid-template-columns:repeat(3,1fr)}
.option{position:relative;border:1px solid var(--border);border-radius:var(--radius-sm);padding:10px 6px;text-align:center;background:var(--bg-card)}
.option:hover{border-color:var(--border-strong)}
.option.is-selected{background:var(--accent);border-color:var(--accent)}
.option-value{display:block;font-size:var(--text-md);font-weight:700}
.option-hint{display:block;font-size:10px;color:var(--text-tertiary)}
.option.is-selected .option-hint{color:rgba(23,23,19,.65)}
.recommend{position:absolute;top:-8px;right:8px;background:var(--danger);color:#fff;font-size:9px;font-weight:700;padding:1px 6px;border-radius:var(--radius-full)}
/* 提示词标签 */
.tags{display:flex;flex-wrap:wrap;gap:var(--space-2)}
.tag{display:inline-flex;align-items:center;gap:5px;border:1px solid var(--border);border-radius:var(--radius-full);padding:6px 13px;font-size:var(--text-sm);color:var(--text-secondary);background:var(--bg-card)}
.tag:hover{border-color:var(--border-strong);color:var(--text-primary)}
.tag.is-selected{background:var(--bg-subtle);border-color:var(--accent);color:var(--text-primary);font-weight:500}
.tag-marker{font-size:var(--text-xs);font-weight:700}
.tag.is-selected .tag-marker{color:var(--accent)}
.tag.is-disabled{opacity:.45;cursor:not-allowed}
.tag-hint{font-size:var(--text-xs);color:var(--danger);margin-top:8px}
/* 细节行:文本域 + 参考图 */
.detail-row{display:grid;grid-template-columns:1fr 1fr;gap:var(--space-4);margin-top:var(--space-4)}
.field-label{display:block;font-size:var(--text-xs);font-weight:600;color:var(--text-secondary);margin-bottom:6px}
.textarea{width:100%;min-height:96px;border:1px solid var(--border-strong);border-radius:var(--radius-md);padding:10px 12px;font-size:var(--text-md);resize:vertical;outline:none;background:var(--bg-card);color:var(--text-primary)}
.textarea:focus{border-color:var(--accent)}
.char-counter{font-size:var(--text-xs);color:var(--text-tertiary);text-align:right;margin-top:4px;font-family:var(--font-mono)}
/* 上传框 */
.upload-zone{border:1.5px dashed var(--border-strong);border-radius:var(--radius-md);padding:var(--space-4);text-align:center;cursor:pointer;transition:border-color .15s,background .15s}
.upload-zone:hover{border-color:var(--accent);background:var(--bg-hover)}
.upload-zone .plus{font-size:22px;color:var(--text-disabled);line-height:1;display:block}
.upload-zone .ut{font-size:var(--text-sm);font-weight:600;margin-top:4px;display:block}
.upload-zone .uh{font-size:var(--text-xs);color:var(--text-tertiary);margin-top:2px;display:block}
.upload-zone.is-error{border-color:var(--danger);background:#fdf3f0}
.upload-zone.is-error .ut{color:var(--danger)}
.upload-file{display:flex;align-items:center;gap:var(--space-3);background:var(--bg-subtle);border-radius:var(--radius-md);padding:var(--space-2) var(--space-3)}
.upload-thumb{width:40px;height:40px;border-radius:var(--radius-sm);object-fit:cover;border:1px solid var(--border)}
.upload-meta{flex:1;min-width:0}
.upload-name{font-size:var(--text-sm);font-weight:600;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
.upload-size{font-size:var(--text-xs);color:var(--text-tertiary)}
.upload-reset{font-size:var(--text-xs);color:var(--info);padding:4px 8px;border:1px solid var(--border);border-radius:var(--radius-sm);background:var(--bg-card)}
.upload-error{font-size:var(--text-xs);color:var(--danger);margin-top:6px}
/* ── 生成前确认 ── */
.confirm{display:grid;grid-template-columns:200px 1fr;gap:var(--space-5)}
.sample{text-align:center}
.sample-label{font-size:var(--text-xs);color:var(--text-tertiary);display:block;margin-bottom:8px}
.sample-desc{font-size:var(--text-xs);color:var(--text-tertiary);display:block;margin-top:8px}
.spec{border:1px solid var(--border);border-radius:var(--radius-md);overflow:hidden}
.spec-row{display:flex;justify-content:space-between;padding:9px 14px;font-size:var(--text-sm);border-bottom:1px dashed var(--border-dashed)}
.spec-row:last-child{border-bottom:none}
.spec-label{color:var(--text-tertiary)}
.spec-value{font-weight:600}
.spec-value b{font-family:var(--font-mono)}
.confirm-upload-row{margin-top:var(--space-4)}
.confirm-note{font-size:var(--text-xs);color:var(--text-secondary);margin:var(--space-3) 0;background:var(--bg-subtle);border-radius:var(--radius-md);padding:10px 12px}
.confirm-note b{color:var(--text-primary)}
.confirm-actions{display:flex;align-items:center;gap:var(--space-3);margin-top:var(--space-2)}
.btn-primary{flex:1;padding:12px 0;background:var(--accent);color:var(--text-primary);font-size:var(--text-md);font-weight:700;border-radius:var(--radius-md);display:inline-flex;align-items:center;justify-content:center;gap:8px}
.btn-primary:hover{background:#e0a63c}
.btn-primary:disabled{background:var(--border);color:var(--text-disabled);cursor:not-allowed}
.btn-link{font-size:var(--text-sm);color:var(--info);padding:8px 12px}
.btn-link:hover{text-decoration:underline}
.spinner{width:18px;height:18px;border:2px solid var(--border-strong);border-top-color:var(--accent);border-radius:50%;display:inline-block;animation:spin .8s linear infinite}
.btn-primary:disabled .spinner{border-top-color:var(--text-disabled)}
@keyframes spin{to{transform:rotate(360deg)}}
.remain-note{font-size:var(--text-xs);color:var(--success);margin-top:10px;display:flex;align-items:center;gap:6px}
.remain-note .dot{width:7px;height:7px;border-radius:50%;background:var(--success);display:inline-block}
/* 生成结果 */
.result{margin-top:var(--space-5);border:1px solid var(--accent);border-radius:var(--radius-lg);padding:var(--space-4);background:var(--bg-hover)}
.result-head{display:flex;align-items:center;gap:var(--space-2);margin-bottom:var(--space-3)}
.result-title{font-size:var(--text-md);font-weight:700;display:flex;align-items:center;gap:8px}
.result-badge{background:var(--success);color:#fff;font-size:10px;font-weight:700;padding:2px 8px;border-radius:var(--radius-full)}
.result-meta{font-size:var(--text-xs);color:var(--text-tertiary)}
.result-canvas-wrap{display:flex;justify-content:center;background:#fff;border-radius:var(--radius-md);padding:var(--space-3);overflow:auto}
.result-info{display:flex;justify-content:space-between;align-items:center;margin-top:var(--space-3);font-size:var(--text-sm)}
.result-info b{font-weight:600}
.result-actions{margin-top:var(--space-3);display:flex;gap:var(--space-3)}
.result-btn{flex:1;padding:10px 0;border-radius:var(--radius-md);font-size:var(--text-sm);font-weight:600}
.result-btn.save{background:var(--text-primary);color:var(--text-on-dark)}
.result-btn.save:hover{background:#2b2b26}
.result-btn.plan{background:var(--bg-card);border:1px solid var(--border-strong)}
.result-btn.plan:hover{background:var(--bg-subtle)}
/* ── PROMISE ── */
.promises{display:grid;grid-template-columns:repeat(3,1fr);gap:var(--space-4);margin:var(--space-6) 0}
.promise{background:var(--bg-card);border:1px solid var(--border);border-radius:var(--radius-lg);padding:var(--space-5);box-shadow:var(--shadow-card)}
.promise-icon{width:38px;height:38px;border-radius:var(--radius-sm);background:var(--bg-subtle);display:flex;align-items:center;justify-content:center;color:var(--accent)}
.promise-title{font-size:var(--text-md);font-weight:700;margin:12px 0 6px}
.promise-desc{font-size:var(--text-xs);color:var(--text-tertiary);line-height:1.7}
/* ── FOOTER ── */
.footer{border-top:1px solid var(--border);padding:var(--space-5) 0 var(--space-6)}
.footer-inner{max-width:880px;margin:0 auto;padding:0 24px;display:flex;justify-content:space-between;align-items:center;font-size:var(--text-sm)}
.footer-text{color:var(--text-secondary);font-weight:500}
.footer-link{color:var(--info);text-decoration:none;font-size:var(--text-sm)}
.footer-link:hover{text-decoration:underline}
/* ── 移动端底部 CTA ── */
.mobile-bar{display:none;position:fixed;bottom:0;left:0;right:0;background:var(--bg-card);border-top:1px solid var(--border);padding:10px 16px calc(10px + env(safe-area-inset-bottom));z-index:40;gap:var(--space-3);align-items:center}
/* ── MODAL ── */
.modal-mask{position:fixed;inset:0;background:rgba(23,23,19,.4);display:flex;align-items:center;justify-content:center;z-index:100;padding:16px}
.modal{background:var(--bg-card);border-radius:var(--radius-lg);box-shadow:var(--shadow-modal);width:100%;max-width:380px;padding:var(--space-5);position:relative}
.modal-close{position:absolute;top:12px;right:12px;width:32px;height:32px;border-radius:50%;font-size:18px;color:var(--text-tertiary);line-height:1}
.modal-close:hover{background:var(--bg-subtle);color:var(--text-primary)}
.modal-title{font-size:var(--text-lg);font-weight:700;margin-bottom:var(--space-4)}
.modal-input{width:100%;padding:11px 12px;border:1px solid var(--border-strong);border-radius:var(--radius-md);font-size:var(--text-md);outline:none;background:var(--bg-card)}
.modal-input:focus{border-color:var(--accent)}
.redeem-error{font-size:var(--text-sm);color:var(--danger);margin:8px 0 0}
.redeem-ok{font-size:var(--text-sm);color:var(--success);margin:8px 0 0;display:flex;align-items:center;gap:6px}
.redeem-btn{width:100%;margin-top:var(--space-3);padding:11px 0;background:var(--accent);color:var(--text-primary);font-size:var(--text-md);font-weight:700;border-radius:var(--radius-md)}
.redeem-btn:hover{background:#e0a63c}
/* ── TOAST ── */
.toast{position:fixed;left:50%;bottom:80px;transform:translateX(-50%) translateY(20px);background:var(--text-primary);color:#fff;font-size:var(--text-sm);padding:10px 18px;border-radius:var(--radius-full);opacity:0;transition:all .25s;z-index:200;pointer-events:none;max-width:90vw;text-align:center}
.toast.is-show{opacity:1;transform:translateX(-50%) translateY(0)}
/* ── RESPONSIVE ── */
@media (max-width:767px){
.page{padding:0 16px}
.nav-inner{padding:0 16px;gap:var(--space-3)}
.nav-back span.txt{display:none}
.nav-badge span.txt{display:none}
.hero h1{font-size:26px}
.tabs{grid-template-columns:repeat(2,1fr)}
.compare{gap:var(--space-2)}
.pixel{width:72px}
.compare-source{width:72px;height:72px}
.subtypes,.options,.options.is-3col{grid-template-columns:1fr}
.detail-row{grid-template-columns:1fr}
.confirm{grid-template-columns:1fr}
.sample{display:flex;align-items:center;gap:var(--space-4);justify-content:center}
.sample-label{margin-bottom:0}
.promises{grid-template-columns:1fr}
.mobile-bar{display:flex}
.footer-inner{flex-direction:column;gap:8px;text-align:center}
}
</style>
</head>
<body>
<!-- ═══ NAV (chibi 版) ═══ -->
<nav class="nav">
<div class="nav-inner">
<a class="nav-back" href="prototype-home.html"><span>←</span><span class="txt">普通拼豆</span></a>
<a class="brand" href="prototype-chibi.html"><span class="brand-mark">P</span><span>PERLER <b>LAB</b></span></a>
<div class="nav-spacer"></div>
<span class="nav-badge"><span class="nav-badge-dot"></span><span class="txt">每次生成消耗 1 次权益</span></span>
</div>
</nav>
<main class="page">
<!-- ═══ BEAD HERO ═══ -->
<header class="hero">
<span class="eyebrow">IMAGE TO PERLER</span>
<h1>先选大类,再定细节,<em>生成结果先保存。</em></h1>
<p class="hero-sub">每次 AI 成功生成扣 1 次;该作品转成正式拼豆图纸并首次下载免费。只有重新生成新作品才再次扣费。</p>
</header>
<!-- ═══ BEAD BUILDER ═══ -->
<div class="card">
<!-- 01 选择拼豆大类 -->
<div class="section-head">
<span class="section-num">01</span>
<h2 class="section-title">选择拼豆大类</h2>
</div>
<div class="tabs" id="tabs"></div>
<div class="compare">
<div class="compare-box">
<span class="compare-label">原图</span>
<div class="compare-source"></div>
</div>
<span class="compare-arrow">→</span>
<div class="compare-box">
<span class="compare-label">像素拼豆效果</span>
<div class="pixel" id="comparePixel"></div>
</div>
</div>
<p class="subtype-title">细分选择 · 同一种类下不同画风</p>
<div class="subtypes" id="subtypes"></div>
</div>
<div class="card">
<!-- 02 图纸格数 -->
<div class="section-head">
<span class="section-num">02</span>
<h2 class="section-title">图纸格数</h2>
</div>
<div class="options" id="gridOptions"></div>
</div>
<div class="card">
<!-- 03 最大颜色数 -->
<div class="section-head">
<span class="section-num">03</span>
<h2 class="section-title">最大颜色数</h2>
<span class="section-note">颜色越多还原度越高</span>
</div>
<div class="options" id="colorOptions"></div>
</div>
<div class="card">
<!-- 04 主体构图 -->
<div class="section-head">
<span class="section-num">04</span>
<h2 class="section-title">主体构图</h2>
</div>
<div class="options is-3col" id="compOptions"></div>
</div>
<div class="card">
<!-- 05 细节提示词 -->
<div class="section-head">
<span class="section-num">05</span>
<h2 class="section-title">细节提示词</h2>
<span class="section-note">最多选 5 项</span>
</div>
<div class="tags" id="tags"></div>
<p class="tag-hint" id="tagHint" style="display:none"></p>
<div class="detail-row">
<div>
<label class="field-label" for="promptText">补充描述(选填)</label>
<textarea class="textarea" id="promptText" maxlength="160" placeholder="想保留的细节、不想要的元素…"></textarea>
<div class="char-counter"><span id="charCount">0</span>/160</div>
</div>
<div>
<span class="field-label">参考图上传(选填)</span>
<div id="refUploadZone"></div>
<input type="file" id="refFileInput" accept="image/jpeg,image/png,image/webp" style="display:none">
</div>
</div>
</div>
<!-- ═══ 生成前确认 ═══ -->
<div class="card">
<div class="section-head">
<span class="section-num">✓</span>
<h2 class="section-title">生成前确认</h2>
</div>
<div class="confirm">
<div class="sample">
<span class="sample-label">示例</span>
<div class="pixel" id="confirmPixel"></div>
<span class="sample-desc">默认像素效果</span>
</div>
<div>
<div class="spec" id="spec">
<div class="spec-row"><span class="spec-label">类别</span><span class="spec-value" id="specCategory">宠物</span></div>
<div class="spec-row"><span class="spec-label">细分</span><span class="spec-value" id="specSubtype">猫咪头像</span></div>
<div class="spec-row"><span class="spec-label">图纸</span><span class="spec-value"><b id="specGrid">64</b>×<b id="specGrid2">64</b></span></div>
<div class="spec-row"><span class="spec-label">预计颗数</span><span class="spec-value">约 <b id="specBeads">0</b> 颗</span></div>
</div>
<div class="confirm-upload-row">
<span class="field-label">上传需要转换的原图</span>
<div id="originUploadZone"></div>
<input type="file" id="originFileInput" accept="image/jpeg,image/png,image/webp" style="display:none">
</div>
<p class="confirm-note"><b>AI 生成属于付费功能。</b>成功生成扣 1 次;本作品转图纸和首次下载免费,失败不扣。</p>
<div class="confirm-actions">
<button type="button" class="btn-primary" id="genBtn" disabled>兑换后生成 →</button>
<button type="button" class="btn-link" id="codeLinkBtn">输入兑换码</button>
</div>
<p class="remain-note" id="remainNote" style="display:none"><span class="dot"></span><span id="remainText">剩余 10 次生成权益</span></p>
</div>
</div>
<!-- 生成结果 -->
<div class="result" id="resultArea" style="display:none">
<div class="result-head">
<span class="result-title">生成结果 <span class="result-badge">已保存</span></span>
<span class="result-meta" id="resultMeta"></span>
</div>
<div class="result-canvas-wrap">
<canvas id="resultCanvas"></canvas>
</div>
<div class="result-info">
<span><b id="resultName">默认像素效果</b> · <span id="resultSpec"></span></span>
<span id="resultBeads"></span>
</div>
<div class="result-actions">
<button type="button" class="result-btn save" id="saveBtn">保存图片</button>
<button type="button" class="result-btn plan" id="toPlanBtn">下载拼豆图纸</button>
</div>
</div>
</div>
<!-- ═══ 三大承诺 ═══ -->
<section class="promises">
<div class="promise">
<span class="promise-icon">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="8" height="8" rx="2"/><rect x="13" y="3" width="8" height="8" rx="2"/><rect x="3" y="13" width="8" height="8" rx="2"/><rect x="13" y="13" width="8" height="8" rx="2"/></svg>
</span>
<h3 class="promise-title">分类更准确</h3>
<p class="promise-desc">不同主体使用不同提示词,风景、宠物和食物不再套用人物规则。</p>
</div>
<div class="promise">
<span class="promise-icon">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="8.5"/><circle cx="12" cy="12" r="4.5"/><circle cx="12" cy="12" r="1" fill="currentColor"/></svg>
</span>
<h3 class="promise-title">生成按次计费</h3>
<p class="promise-desc">每次成功生成扣 1 次权益,失败不扣,避免无限消耗模型费用。</p>
</div>
<div class="promise">
<span class="promise-icon">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3l7 3v5c0 4.5-3 8.2-7 10-4-1.8-7-5.5-7-10V6l7-3z"/><path d="M9 12l2 2 4-4"/></svg>
</span>
<h3 class="promise-title">结果防丢失</h3>
<p class="promise-desc">未保存时锁住所有切换操作,并在关闭页面前再次提醒。</p>
</div>
</section>
</main>
<!-- ═══ FOOTER ═══ -->
<footer class="footer">
<div class="footer-inner">
<span class="footer-text">PERLER LAB · AI 拼豆专区</span>
<a class="footer-link" href="prototype-home.html">返回图片转拼豆 →</a>
</div>
</footer>
<!-- ═══ 移动端底部 CTA ═══ -->
<div class="mobile-bar">
<button type="button" class="btn-primary" id="mobileGenBtn" disabled style="flex:1">兑换后生成 →</button>
<button type="button" class="btn-link" id="mobileCodeBtn">输入兑换码</button>
</div>
<!-- ═══ 兑换码弹窗 ═══ -->
<div class="modal-mask" id="redeemMask" style="display:none">
<div class="modal" role="dialog" aria-modal="true" aria-label="输入兑换码">
<button type="button" class="modal-close" id="redeemClose" aria-label="关闭">×</button>
<h3 class="modal-title">输入兑换码</h3>
<input class="modal-input" id="redeemInput" placeholder="请输入兑换码" autocomplete="off">
<p class="redeem-error" id="redeemError" style="display:none"></p>
<p class="redeem-ok" id="redeemOk" style="display:none">✓ 已确认到账,兑换码已自动解锁</p>
<button type="button" class="redeem-btn" id="redeemBtn">兑换</button>
</div>
</div>
<div class="toast" id="toast"></div>
<script>
/* ═══════════════════════════════════════════════════════════════
* PERLER LAB AI 专区原型 · 交互逻辑(原生 JS)
* ═══════════════════════════════════════════════════════════════ */
(function(){
'use strict';
/* ── 数据:五大类 + 细分 + 标签 (copy-library.md §8.2) ── */
var CATEGORIES = [
{ id:'landscape', name:'风景', note:'山川、城市和旅行纪念',
pal:['#2e8a5e','#8fbf6f','#3677d2','#f0c06a','#5a4632','#f4f3ef'],
subtypes:[{name:'自然山川'},{name:'城市夜景'},{name:'地标建筑'}],
tags:['突出主体建筑','减少零碎纹理','保留光影氛围','纯色边框','高对比轮廓','云端与远山'] },
{ id:'people', name:'人物', note:'五官、发型和穿搭清楚',
pal:['#edb045','#c8a06b','#e8b4a0','#8c3a2e','#171713','#f4f3ef'],
subtypes:[{name:'萌系大眼',note:'大眼、圆脸、粗轮廓'},{name:'清爽少年',note:'自然五官、利落穿搭'},{name:'复古像素',note:'怀旧配色、游戏感'}],
tags:['五官更清晰','保留衣服细节','保留发型','保留配饰','包含宠物','纯色背景'] },
{ id:'pet', name:'宠物', note:'毛色、表情和品种特征',
pal:['#edb045','#c8a06b','#8a6d4f','#f0c06a','#171713','#f4f3ef'],
subtypes:[{name:'猫咪头像',note:'圆润脸型与花纹'},{name:'狗狗全身',note:'耳朵、四肢和毛色'},{name:'双宠互动',note:'两只宠物同框'}],
tags:['眼睛更有神','保留毛色花纹','突出耳朵轮廓','保留项圈配饰','完整四肢','纯色背景'] },
{ id:'item', name:'物品', note:'手办、礼物和纪念物',
pal:['#3677d2','#e05b5b','#7a5cc2','#f0c06a','#66645d','#f4f3ef'],
subtypes:[{name:'手办玩具',note:'造型轮廓优先'},{name:'生活用品',note:'保留结构与材质'},{name:'礼物纪念',note:'突出包装和装饰'}],
tags:['保留品牌外形','突出结构轮廓','减少反光渐变','保留小配件','居中构图','纯色背景'] },
{ id:'food', name:'食物', note:'甜品、饮品和特色美食',
pal:['#e8b4d0','#d87a9e','#edb045','#3daf80','#c8a06b','#f4f3ef'],
subtypes:[{name:'甜品蛋糕',note:'奶油与装饰清晰'},{name:'咖啡饮品',note:'杯型、分层和配料'},{name:'家常美食',note:'主食材清晰可辨'}],
tags:['突出食物主体','保留食材层次','减少细碎装饰','增强色彩对比','俯拍构图','纯色背景'] }
];
var GRID_OPTIONS = [
{ value:48, hint:'简单' }, { value:64, hint:'推荐', rec:true },
{ value:80, hint:'精细' }, { value:96, hint:'高清' }
];
var COLOR_OPTIONS = [
{ value:16, hint:'省豆' }, { value:24, hint:'均衡' },
{ value:32, hint:'细腻' }, { value:40, hint:'高还原' }
];
var COMPOSITIONS = [
{ id:'特写', label:'主体特写', density:0.7 },
{ id:'半幅', label:'半幅构图', density:0.6 },
{ id:'完整', label:'完整构图', density:0.48 }
];
var MAX_TAGS = 5, MAX_PROMPT = 160, MAX_BYTES = 12*1024*1024;
/* ── 状态 ── */
var categoryId = 'pet';
var subtypeName = '猫咪头像';
var gridSize = 64, maxColors = 24, composition = '特写';
var selectedTags = [];
var promptText = '';
var hasCode = false;
var remainCount = 10;
var generating = false;
var refImage = null, originImage = null;
var $ = function(id){ return document.getElementById(id); };
function fmt(n){ return n.toLocaleString('zh-CN'); }
function toast(msg){
var t = $('toast'); t.textContent = msg; t.classList.add('is-show');
clearTimeout(toast._t); toast._t = setTimeout(function(){ t.classList.remove('is-show'); }, 2600);
}
function cat(){ for (var i=0;i<CATEGORIES.length;i++) if (CATEGORIES[i].id===categoryId) return CATEGORIES[i]; return CATEGORIES[0]; }
/* ── 8×8 像素示例(按分类配色生成) ── */
function buildPixel(c){
var pal = c.pal;
var cells = [];
// 简化:中心主体 + 边框
for (var y=0;y<8;y++) for (var x=0;x<8;x++){
var ci = 0;
var dx = x-3.5, dy = y-3.5, d = Math.sqrt(dx*dx+dy*dy);
if (d < 2.2) ci = 2; // 主体
else if (d < 3.3) ci = 1; // 阴影
else if (Math.random()<0.25) ci = 3; // 噪点
else ci = 5; // 纸色
cells.push(pal[ci]);
}
return cells;
}
function renderPixel(container, colors){
var html = '';
for (var i=0;i<colors.length;i++) html += '<span style="background:'+colors[i]+'"></span>';
container.innerHTML = html;
}
var pixelCache = {};
function getPixelFor(cid){
if (!pixelCache[cid]) pixelCache[cid] = buildPixel(catFromId(cid));
return pixelCache[cid];
}
function catFromId(id){ for (var i=0;i<CATEGORIES.length;i++) if (CATEGORIES[i].id===id) return CATEGORIES[i]; return CATEGORIES[0]; }
/* ── 01 分类 Tabs ── */
function renderTabs(){
var html = '';
for (var i=0;i<CATEGORIES.length;i++){
var c = CATEGORIES[i];
html += '<button type="button" class="tab'+(c.id===categoryId?' is-selected':'')+'" data-cat="'+c.id+'" role="tab" aria-selected="'+(c.id===categoryId)+'">' +
'<span class="tab-name">'+c.name+'</span><span class="tab-note">'+c.note+'</span></button>';
}
$('tabs').innerHTML = html;
Array.prototype.forEach.call($('tabs').querySelectorAll('.tab'), function(t){
t.addEventListener('click', function(){ selectCategory(t.dataset.cat); });
});
}
function renderSubtypes(){
var c = cat();
var html = '';
for (var i=0;i<c.subtypes.length;i++){
var s = c.subtypes[i];
html += '<button type="button" class="subtype'+(s.name===subtypeName?' is-selected':'')+'" data-sub="'+s.name+'">' +
'<span class="subtype-name">'+s.name+'</span>'+(s.note?'<span class="subtype-note">'+s.note+'</span>':'')+'</button>';
}
$('subtypes').innerHTML = html;
Array.prototype.forEach.call($('subtypes').querySelectorAll('.subtype'), function(b){
b.addEventListener('click', function(){ subtypeName = this.dataset.sub; renderSubtypes(); renderSpec(); });
});
}
function selectCategory(id){
if (id === categoryId) return;
categoryId = id;
var c = catFromId(id);
subtypeName = c.subtypes[0].name;
selectedTags = [];
renderTabs(); renderSubtypes(); renderTags();
renderPixel($('comparePixel'), getPixelFor(id));
renderPixel($('confirmPixel'), getPixelFor(id));
renderSpec();
}
/* ── 02/03/04 参数选项 ── */
function renderOptionsInto(containerId, options, getKey, isSelected, onSelect){
var html = '';
for (var i=0;i<options.length;i++){
var o = options[i];
html += '<button type="button" class="option'+(isSelected(o)?' is-selected':'')+'" data-key="'+getKey(o)+'">' +
(o.rec?'<span class="recommend">推荐</span>':'') +
'<span class="option-value">'+o.value+'</span>'+(o.hint?'<span class="option-hint">'+o.hint+'</span>':'')+'</button>';
}
$(containerId).innerHTML = html;
Array.prototype.forEach.call($(containerId).querySelectorAll('.option'), function(b){
b.addEventListener('click', function(){ onSelect(getKey(options[Array.prototype.indexOf.call(b.parentNode.children,b)])); });
});
}
function renderGridOptions(){
renderOptionsInto('gridOptions', GRID_OPTIONS,
function(o){ return o.value; },
function(o){ return o.value === gridSize; },
function(v){ gridSize = Number(v); renderGridOptions(); renderSpec(); });
}
function renderColorOptions(){
renderOptionsInto('colorOptions', COLOR_OPTIONS,
function(o){ return o.value; },
function(o){ return o.value === maxColors; },
function(v){ maxColors = Number(v); renderColorOptions(); });
}
function renderCompOptions(){
renderOptionsInto('compOptions', COMPOSITIONS,
function(o){ return o.id; },
function(o){ return o.id === composition; },
function(v){ composition = v; renderCompOptions(); renderSpec(); });
}
/* ── 05 提示词标签 ── */
function renderTags(){
var c = cat();
var html = '';
for (var i=0;i<c.tags.length;i++){
var tag = c.tags[i];
var sel = selectedTags.indexOf(tag) !== -1;
var dis = !sel && selectedTags.length >= MAX_TAGS;
html += '<button type="button" class="tag'+(sel?' is-selected':'')+(dis?' is-disabled':'')+'" data-tag="'+tag+'">' +
'<span class="tag-marker">'+(sel?'✓':'+')+'</span>'+tag+'</button>';
}
$('tags').innerHTML = html;
Array.prototype.forEach.call($('tags').querySelectorAll('.tag'), function(b){
b.addEventListener('click', function(){
if (this.classList.contains('is-disabled')) return;
var tag = this.dataset.tag;
var idx = selectedTags.indexOf(tag);
if (idx !== -1){ selectedTags.splice(idx,1); }
else {
if (selectedTags.length >= MAX_TAGS){
$('tagHint').textContent = '最多选 ' + MAX_TAGS + ' 项';
$('tagHint').style.display = 'block';
clearTimeout(renderTags._t); renderTags._t = setTimeout(function(){ $('tagHint').style.display='none'; }, 2000);
return;
}
selectedTags.push(tag);
}
$('tagHint').style.display = 'none';
renderTags();
});
});
}
/* ── 生成前确认(规格摘要) ── */
function density(){ for (var i=0;i<COMPOSITIONS.length;i++) if (COMPOSITIONS[i].id===composition) return COMPOSITIONS[i].density; return 0.7; }
function renderSpec(){
var c = cat();
$('specCategory').textContent = c.name;
$('specSubtype').textContent = subtypeName;
$('specGrid').textContent = gridSize; $('specGrid2').textContent = gridSize;
$('specBeads').textContent = fmt(Math.round(gridSize*gridSize*density()));
}
function updateCta(){
var label = generating ? 'AI 生成中…' : (hasCode ? '生成 →' : '兑换后生成 →');
$('genBtn').innerHTML = generating ? '<span class="spinner"></span>'+label : label;
$('mobileGenBtn').innerHTML = generating ? '<span class="spinner"></span>'+label : label;
$('genBtn').disabled = !hasCode || generating;
$('mobileGenBtn').disabled = !hasCode || generating;
$('codeLinkBtn').style.display = hasCode ? 'none' : '';
$('mobileCodeBtn').style.display = hasCode ? 'none' : '';
$('remainNote').style.display = hasCode ? '' : 'none';
if (hasCode) $('remainText').textContent = '剩余 ' + remainCount + ' 次生成权益';
}
/* ── 上传组件(参考图 / 原图 共用) ── */
function makeUpload(zoneId, inputId, state){
var zone = $(zoneId), input = $(inputId);
zone.className = 'upload-zone';
zone.innerHTML = '<span class="plus">+</span><span class="ut">'+state.title+'</span><span class="uh">'+state.hint+'</span>';
zone.addEventListener('click', function(){ input.click(); });
input.addEventListener('change', function(){
var file = this.files[0];
this.value = '';
if (!file) return;
if (!/^image\//.test(file.type)){ showUploadError(zone, '图片读取失败,请换一张重试', state); return; }
if (file.size > MAX_BYTES){ showUploadError(zone, '图片不能超过 12MB', state); return; }
var reader = new FileReader();
reader.onload = function(){
state.value = { name: file.name, url: reader.result, size: file.size };
renderUpload(zone, input, state);
};
reader.onerror = function(){ showUploadError(zone, '图片读取失败,请换一张重试', state); };
reader.readAsDataURL(file);
});
}
function showUploadError(zone, msg, state){
zone.className = 'upload-zone is-error';
zone.innerHTML = '<span class="ut">'+msg+'</span>';
setTimeout(function(){
zone.className = 'upload-zone';
zone.innerHTML = '<span class="plus">+</span><span class="ut">'+state.title+'</span><span class="uh">'+state.hint+'</span>';
}, 2200);
}
function renderUpload(zone, input, state){
if (state.value){
var kb = state.value.size < 1024 ? state.value.size + ' B' : (state.value.size/1024).toFixed(1) + ' KB';
zone.className = '';
zone.innerHTML = '';
zone.style.padding = '0';
zone.style.borderStyle = 'solid';
zone.style.cursor = 'default';
var wrap = document.createElement('div');
wrap.className = 'upload-file';
wrap.innerHTML = '<img class="upload-thumb" src="'+state.value.url+'" alt="'+state.value.name+'">' +
'<div class="upload-meta"><div class="upload-name">'+state.value.name+'</div><div class="upload-size">'+kb+' · 已就绪</div></div>' +
'<button type="button" class="upload-reset">重置</button>';
zone.appendChild(wrap);
zone.querySelector('.upload-reset').addEventListener('click', function(e){
e.stopPropagation();
state.value = null;
zone.style.padding = ''; zone.style.borderStyle = 'dashed'; zone.style.cursor = 'pointer';
zone.innerHTML = '<span class="plus">+</span><span class="ut">'+state.title+'</span><span class="uh">'+state.hint+'</span>';
});
}
}
makeUpload('refUploadZone', 'refFileInput', { title:'上传参考图', hint:'支持 JPG、PNG、WEBP · 不超过 12MB', value:null });
makeUpload('originUploadZone', 'originFileInput', { title:'上传需要转换的原图', hint:'主体清楚、光线自然效果更好 · 不超过 12MB', value:null });
/* ── 文本域计数 ── */
$('promptText').addEventListener('input', function(){
$('charCount').textContent = this.value.length;
});
/* ── 兑换码 ── */
function openRedeem(){ $('redeemMask').style.display='flex'; document.body.style.overflow='hidden'; setTimeout(function(){ $('redeemInput').focus(); }, 50); }
function closeRedeem(){ $('redeemMask').style.display='none'; document.body.style.overflow=''; }
$('codeLinkBtn').addEventListener('click', openRedeem);
$('mobileCodeBtn').addEventListener('click', openRedeem);
$('redeemClose').addEventListener('click', closeRedeem);
$('redeemMask').addEventListener('mousedown', function(e){ if (e.target === this) closeRedeem(); });
document.addEventListener('keydown', function(e){ if (e.key==='Escape' && $('redeemMask').style.display!=='none') closeRedeem(); });
$('redeemInput').addEventListener('input', function(){ $('redeemError').style.display='none'; });
$('redeemBtn').addEventListener('click', doRedeem);
$('redeemInput').addEventListener('keydown', function(e){ if (e.key==='Enter') doRedeem(); });
function doRedeem(){
var code = $('redeemInput').value.trim();
if (!code){
$('redeemOk').style.display = 'none';
$('redeemError').textContent = '兑换失败 / 兑换码不存在,请检查后重试';
$('redeemError').style.display = 'block';
return;
}
hasCode = true;
$('redeemOk').style.display = 'block';
$('redeemError').style.display = 'none';
setTimeout(function(){
closeRedeem();
$('redeemInput').value = '';
$('redeemOk').style.display = 'none';
updateCta();
toast('已确认到账,兑换码已自动解锁');
}, 900);
}
/* ── 生成 ── */
function doGenerate(){
if (!hasCode || generating) return;
generating = true;
updateCta();
setTimeout(function(){
generating = false;
remainCount = Math.max(0, remainCount - 1);
updateCta();
renderResult();
$('resultArea').style.display = 'block';
toast('AI 生成成功,消耗 1 次权益 · 已保存');
$('resultArea').scrollIntoView({ behavior:'smooth', block:'nearest' });
}, 1800);
}
$('genBtn').addEventListener('click', doGenerate);
$('mobileGenBtn').addEventListener('click', doGenerate);
/* ── 生成结果(占位图) ── */
function renderResult(){
var c = cat();
var canvas = $('resultCanvas');
var g = gridSize;
var cell = Math.max(3, Math.floor(480 / g));
var size = g * cell;
var dpr = Math.min(2, window.devicePixelRatio || 1);
canvas.width = size*dpr; canvas.height = size*dpr;
canvas.style.width = size+'px'; canvas.style.height = size+'px';
var ctx = canvas.getContext('2d');
ctx.setTransform(dpr,0,0,dpr,0,0);
ctx.fillStyle = '#f4f3ef'; ctx.fillRect(0,0,size,size);
// 分类配色渐变 + blob
var pal = c.pal.slice();
for (var y=0;y<g;y++) for (var x=0;x<g;x++){
var px = x/(g-1||1), py = y/(g-1||1);
var d = Math.sqrt(Math.pow(px-0.5,2)+Math.pow(py-0.5,2));
var ci;
if (d < 0.28) ci = 1;
else if (d < 0.42) ci = 0;
else if (Math.random()<0.12) ci = 2;
else ci = 5;
ctx.beginPath();
ctx.arc(x*cell+cell/2, y*cell+cell/2, cell*0.42, 0, Math.PI*2);
ctx.fillStyle = pal[ci]; ctx.fill();
}
$('resultMeta').textContent = c.name + ' · ' + subtypeName + ' · 图纸 ' + g + '×' + g;
$('resultName').textContent = subtypeName + ' · 默认像素效果';
$('resultSpec').textContent = g + ' × ' + g;
$('resultBeads').textContent = '实际使用 ' + fmt(g*g) + ' 颗 · 已扣除 1 次';
}
$('saveBtn').addEventListener('click', function(){
toast('图片已保存(原型演示:长按下方图片保存到手机)');
});
$('toPlanBtn').addEventListener('click', function(){
toast('转拼豆图纸已开始生成(原型演示)');
});
/* ── 初始化 ── */
renderTabs();
renderSubtypes();
renderTags();
renderGridOptions();
renderColorOptions();
renderCompOptions();
renderPixel($('comparePixel'), getPixelFor(categoryId));
renderPixel($('confirmPixel'), getPixelFor(categoryId));
renderSpec();
updateCta();
})();
</script>
</body>
</html>
File diff suppressed because it is too large. Load diff