# 给 AI 编程助手的 FalePay 接入说明

FalePay 提供了版本化接入包：`integration/falepay-ai-integration-v1/`。打包文件会放在 `frontend/downloads/falepay-ai-integration-v1.0.0.zip`，内容只包含公开接口契约、示例和验收说明，不包含任何账号、API Secret、汇付密钥、SSH 信息或生产订单。

## 推荐工作流

1. 商户在 FalePay 工作台创建应用，复制一次性显示的 `api_key` 与 `api_secret` 到自己的服务端密钥管理器。
2. 把 AI 接入包和目标项目一并交给 AI，要求它先识别框架、展示 diff 和测试计划。
3. AI 只实现服务端调用和 Webhook 验签，并用本地 mock 或测试环境验收。不要让 AI 把密钥写入前端、提交到 Git、放进提示词或自动部署。
4. 人工确认域名、通知地址、进件状态、汇付渠道和退款权限，再由有权限的发布流程部署。

## 关键协议

每次业务 API 请求都要发送 `X-9AIPay-Key`、`X-9AIPay-Timestamp`、`X-9AIPay-Nonce`、`X-9AIPay-Signature`。签名原文是：

```text
timestamp.nonce.METHOD.path_with_query.raw_body
```

使用 `api_secret` 做 HMAC-SHA256，并给十六进制结果加上 `sha256=` 前缀。POST 的 `raw_body` 必须是实际发送的原始 UTF-8 JSON，GET 的 body 为空字符串；时间偏差超过 5 分钟或 nonce 重放会被拒绝。

回调必须在解析 JSON 前读取原始 body，按 `timestamp.webhook_id.raw_body` 验证 `X-9AIPay-Webhook-Signature`，再按 webhook id 和商户订单号幂等处理，快速返回 2xx。

## “一键部署”的边界

可以把这个包做成 AI 可读取的标准输入，自动生成适配当前项目的代码和测试；不建议把“一键部署”理解成把凭据交给 AI 后直接改生产。安全的产品交互应是“识别项目 → 生成 diff → 本地/测试环境验收 → 展示人工需要确认的配置 → 明确批准后发布”。当前包实现的是前四步，不会自行调用真实支付或服务器部署。

机器可读契约、三种最小客户端、签名向量和 Webhook 示例见 `integration/falepay-ai-integration-v1/`。
