> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 爱发电对接

> 适用版本 1.0.0 ｜ 后台路径：插件 → 打赏插件 → 设置 → 爱发电

爱发电是可选渠道：开启后平台订单可以通过 Webhook 自动入库，也可以手动同步补录历史订单。插件只通过开放接口读取订单数据，不托管任何资金。

## 前置条件

1. 爱发电账号已开通创作者
2. 能访问开发者后台 [https://afdian.com/dashboard/dev](https://afdian.com/dashboard/dev)
3. 站点使用 HTTPS，且能被爱发电的服务器访问（Webhook 需要公网可达）

## 配置步骤

### 1. 获取开发者凭据

在爱发电开发者后台获取 `user_id` 与 `api token`。

### 2. 填写插件设置

打开「插件 → 打赏插件 → 设置 → 爱发电」：

- 打开「启用爱发电」
- 填入开发者 `user_id`
- 「API 凭据」新建一个 Halo 密钥：**键名填 `token`，值填爱发电 api token**；也可以直接选择已有密钥
- 填写「爱发电主页」后，前台打赏页会显示「前往爱发电」入口卡片

### 3. 配置 Webhook

把下面的地址填入爱发电开发者后台的 Webhook 通知地址：

```
https://你的域名/apis/api.reward.nanzhiy.cn/v1alpha1/afdian/webhook
```

> 该路径需要匿名可访问，Halo 会把「有名称段的 POST」按非资源请求处理，插件已在匿名角色中显式放行。若站点前置了 CDN / WAF（如阿里云 ESA），要把这个路径加入白名单，否则爱发电的请求会被人机校验拦截。

### 4. 补录历史订单

「内容 → 打赏」点击「同步爱发电」，最多拉取最近 250 条订单。后台手动同步**不会**发送通知，适合一次导入大量历史记录。

## 回调校验

爱发电的回调**没有签名机制**，所以插件不会直接信任请求内容：

1. 收到回调后立即返回成功结构（不返回时平台判定为失败）
2. 异步调用 `query-order` 反查订单，确认单号一致、真实存在且支付成功
3. 只有校验通过的订单才会入库，伪造请求会被丢弃
4. 记录以 `afdian-{订单号}` 为唯一标识，重复推送不会重复创建

订单昵称与头像通过 `query-sponsor` 反查，带 10 分钟缓存；查不到时昵称显示为「匿名读者」，头像留空。

## 注意事项

- 回调反查不到时（刚支付就回调、凭据未配置等）不会入库，但会在日志里留一条 `warn`；平台收到成功响应后不会重推，这类订单需要在后台点「同步爱发电」补齐
- 订单号含大写、空格等不适合作为资源名的字符时会被规整并附短哈希，不影响唯一性
- 「订单自动确认并展示」关闭时，平台订单入库为待确认，仍需人工确认
- 启用爱发电后，插件会向 `afdian.com`（备用 `ifdian.net`）请求订单与打赏者数据，传输内容为开发者身份标识、请求签名、分页参数与订单号，不含站点内容与访客数据
- 所有外部请求都有 15 秒超时与重试上限，失败时降级；最坏情况（超时 + 重试 + 备用域名）单次调用约 60 秒，只影响爱发电相关操作，不阻塞站点访问
- Token 保存在 Halo 密钥中，不会明文出现在插件设置或前台

## 相关

- [打赏记录与确认](/reward/records.md)
- [常见问题](/reward/faq.md)