Files
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

86 lines
6.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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) |