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

6.2 KiB
Raw Blame History

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 通过。

三、复现步骤

# 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)