- 前端: 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)
86 lines
6.2 KiB
Markdown
86 lines
6.2 KiB
Markdown
# 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) |
|