# 生产环境检查清单 (/zh/docs/pix-processamento/best-practices/checklist)

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/best-practices/idempotency" title="幂等性" />

  <QuickLink href="/docs/pix-processamento/webhooks" title="Webhooks" />

  <QuickLink href="/docs/pix-processamento/best-practices/errors" title="错误处理" />

  <QuickLink href="/docs/pix-processamento/best-practices/security" title="安全" />
</QuickLinks>

上线生产前请完成所有项。每项都链接到对应的章节。

## 幂等性 [#幂等性]

| 项目                                                                                              |
| ----------------------------------------------------------------------------------------------- |
| 所有创建请求均使用唯一且确定性的 `clientReference`。参见[幂等性](/docs/pix-processamento/best-practices/idempotency)。 |
| 按 `id` 加事件对 callback 去重，而非仅按 `id`。                                                              |
| 去重存储持久化（Redis/DB），不要放在本地内存中。                                                                    |
| 去重 TTL ≥ 30 天。                                                                                  |

## 回调 [#回调]

| 项目                                                                            |
| ----------------------------------------------------------------------------- |
| 所有 `POST /pix`、`POST /withdraw`、`POST /internal-transfer` 都已配置 `callbackUrl`。 |
| Handler 在 5 秒内返回 `2xx`。重负载处理交给队列/worker。                                      |
| 已通过 curl + ngrok 用模拟 payload 测试。                                              |
| Endpoint 限制为 PayZu 官方 IP（向支持团队索取）。                                            |
| 已配置 `GET /user/callbacks` 用于审计排查。                                             |

## 多租户（如适用） [#多租户如适用]

| 项目                                              |
| ----------------------------------------------- |
| 所有创建请求中均传递 `virtualAccount`。                    |
| 列表查询按 `virtualAccount` 过滤。                      |
| Callback 路由使用 `tx.virtualAccount`，并对未知租户设有兜底处理。 |
| 新租户接入无需重新部署（通过 DB 映射或动态配置完成）。                   |

## 资金 [#资金]

| 项目                                               |
| ------------------------------------------------ |
| 金额以分为单位的整数或 `NUMERIC(15,2)` 存储，绝不使用 `FLOAT`。     |
| 分 ↔ 雷亚尔的换算封装在 helper 中，并已测试。                     |
| Callback 中校验：收到的金额与订单预期金额一致。                     |
| 手续费（`serviceFeeCharged`）已纳入对账。                   |
| 遵守最低限额（收款 ≥ R$ 1，Pix 付款 ≥ R$ 0.01，QR ≥ R$ 0.10）。 |

## 安全 [#安全]

| 项目                                                        |
| --------------------------------------------------------- |
| Token 存放于 Secret Manager，而非版本控制中的 `.env`。                 |
| Token 绝不暴露给前端。                                            |
| 日志对 `Authorization` 头及敏感字段（`payerDocument`、`pixKey`）进行脱敏。 |
| 沙箱与生产使用各自独立的 token。                                       |
| 轮换计划已文档化（何时、何人、如何执行）。                                     |
| 大额按 Pix 密钥付款前先查询 DICT。                                    |

## 错误处理 [#错误处理]

| 项目                                    |
| ------------------------------------- |
| 仅在 `5xx`、`429` 与 `424` 时重试，使用指数退避加抖动。 |
| `4xx`（`424` 与 `429` 除外）**不**重试。       |
| 超时时先通过 `clientReference` 查询，再决定是否重建。  |
| PayZu 的 `requestId` 在所有错误中均被记录。       |
| 错误信息已翻译给终端用户（不直接暴露原始 `message`）。      |

## 分页与对账 [#分页与对账]

| 项目                                                                                    |
| ------------------------------------------------------------------------------------- |
| 列表遍历按各端点的停止条件：交易用 `pages`，回调用 `pagination.hasNextPage`，违规记录用 `pagination.totalPages`。 |
| `limit` 不超过该端点的最大值：`/user/transactions` 为 1000，其余为 100。                               |
| 每日对账任务交叉比对 `GET /user/transactions` 与本地订单表。                                           |
| 大数据量场景定时调用 `POST /user/report`。                                                       |
| 状态差异触发告警。                                                                             |

## 可观测性 [#可观测性]

| 项目                                                              |
| --------------------------------------------------------------- |
| 结构化日志包含本地 `id` + PayZu `id` + `endToEndId` + `clientReference`。 |
| 指标：创建成功率、p95 延迟、按类型分类的错误数。                                      |
| 告警：短窗口内 5xx 与 424 错误 > X%、callback 未处理超过 N 分钟。                  |
| 分布式追踪（OpenTelemetry）传播 PayZu 的 `requestId`。                     |

## 环境 [#环境]

| 项目                                      |
| --------------------------------------- |
| 开发与测试均使用沙箱。                             |
| 生产仅用于真实金额与真实客户。                         |
| 环境变量分离（`PAYZU_TOKEN`、`PAYZU_BASE_URL`）。 |
| 生产 webhook 使用稳定 URL（非临时隧道）。             |

## 运营 [#运营]

| 项目                                                |
| ------------------------------------------------- |
| 故障 runbook：callback 停止到达、5xx 与 424 错误持续、余额不一致。    |
| 与 PayZu 支持的直接联系方式（渠道、SLA）。                        |
| Callback 重发流程已文档化（`POST /user/callbacks/resend`）。 |
| 涉及 Pix 付款或转账的功能均有回滚预案。                            |