- 前端: 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)
6.2 KiB
6.2 KiB
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) |