# 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//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":""}' curl -X POST http://localhost:8788/api/codes/consume -H "Content-Type: application/json" -d '{"code":"","fileName":"test.png"}' curl -X POST http://localhost:8788/api/chibi/generate -H "Content-Type: application/json" -d '{"code":"","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) |