#REST API

适用版本 1.0.0 ｜ 面向主题与二次开发

插件提供三组接口：

#公共 API

#端点列表

所有响应均不包含联系方式、交易单号等后台字段。

公共接口按来源 IP 独立限流：

「启用打赏页面」开关只影响 /reward 页面、GET /public/config、GET /public/captcha 与 POST /records；GET /public/wall 与 GET /public/stats 不受该开关影响，便于主题在其它页面展示数据。

#获取页面配置

GET /apis/api.reward.nanzhiy.cn/v1alpha1/public/config

{
  "title": "打赏支持",
  "intro": "您的打赏将用于服务器维护、内容创作和功能开发…",
  "currencySymbol": "¥",
  "wechatQr": "/upload/wechat.png",
  "alipayQr": "/upload/alipay.png",
  "paymentTip": "扫码后请手动输入金额…",
  "afdianPageUrl": "https://afdian.com/a/yourname",
  "enableRecordSubmit": true,
  "requireLogin": false,
  "allowMessage": true,
  "wallEnabled": true,
  "enableCaptcha": true,
  "enableTransactionNo": false,
  "enableAvatar": false,
  "loggedIn": false
}

loggedIn 用于前台判断是否允许提交（配合「仅登录用户可提交」开关）。

#获取赞助者墙

GET /apis/api.reward.nanzhiy.cn/v1alpha1/public/wall?page=1&size=10

{
  "items": [
    {
      "nickname": "张三",
      "initial": "张",
      "amount": 18.0,
      "avatar": "https://cdn.example.com/a.png",
      "message": "文章很有帮助",
      "createdAt": "2026-10-31"
    }
  ],
  "total": 12,
  "page": 1,
  "size": 10
}

• 只返回状态为「已确认」的记录
• amount 为 null 表示后台关闭了「墙面显示金额」
• avatar、message 为 null 表示访客未填写

#获取统计

GET /apis/api.reward.nanzhiy.cn/v1alpha1/public/stats

统计结果在服务端缓存 60 秒，写操作后缓存立即失效。

金额字段不受「在赞助者墙显示金额」开关控制，且接口匿名可访问；不需要公开收入数据时，请不要在主题中调用它。

{
  "totalCount": 12,
  "monthCount": 3,
  "totalAmount": 234.0,
  "monthAmount": 54.0
}

#获取图形验证码

GET /apis/api.reward.nanzhiy.cn/v1alpha1/public/captcha

{
  "id": "8f3c9a2e-5b1d-4c6a-9f30-2a7e5d8c1b44",
  "image": "data:image/png;base64,iVBORw0KGgo..."
}

#提交打赏记录

POST /apis/api.reward.nanzhiy.cn/v1alpha1/records
Content-Type: application/json

{
  "amount": 18,
  "nickname": "张三",
  "method": "wechat",
  "message": "加油",
  "contact": "zhangsan@qq.com",
  "transactionNo": "4200001234202610311234567890",
  "avatar": "https://cdn.example.com/avatar.png",
  "captchaId": "8f3c9a2e-5b1d-4c6a-9f30-2a7e5d8c1b44",
  "captchaCode": "A3KP"
}

打赏时间由服务端按提交时刻写入，不接受访客指定，避免把记录伪造成历史日期；需要补录历史打赏请走管理接口。

成功响应：

{
  "status": "PENDING",
  "message": "已提交，等待站长确认后展示"
}

若后台开启了「提交后自动通过」，status 为 CONFIRMED。

#错误响应

公开接口的业务错误统一返回 message 字段：

{
  "message": "验证码错误或已过期"
}

#爱发电回调

POST /apis/api.reward.nanzhiy.cn/v1alpha1/afdian/webhook

供爱发电平台调用，固定返回：

{ "ec": 200, "em": "" }

该路径需要匿名可访问：Halo 会把「有名称段的 POST」按非资源请求处理，只认 nonResourceURLs 规则，插件已在匿名角色中显式放行该路径。若站点前置了 CDN / WAF，还需把该路径加入白名单。

处理逻辑：

1. 立即返回成功结构（未返回时平台判定为失败）
2. 异步调用 query-order 反查订单，确认单号一致、真实存在且 status = 2
3. 以 afdian-{订单号} 为记录名入库，天然幂等
4. 请求体按原始字节解析，不依赖 Content-Type；结构异常、单号查不到、未支付、凭据缺失都会记一条 warn 日志，且不会入库
5. 平台收到成功响应后不会重推，漏掉的订单需在后台点「同步爱发电」补齐

#管理 API

前缀 /apis/console.api.reward.nanzhiy.cn/v1alpha1。列表需要「打赏记录查看」权限（plugin-reward-role-view）；新增、编辑、批量变更、删除、同步与导出需要「打赏记录管理」权限（plugin-reward-role-manage）。

这些接口主要服务于插件自带的后台页面，不承诺对外兼容，字段与方法可能随版本调整。

status 取值：PENDING、CONFIRMED、REJECTED。

金额上限 1000000，最多两位小数；字段超长按原始值校验并返回 400，不会静默截断。

带名称段的接口（/records/{name}/status、/records/batch-status、/records/batch-delete、/afdian/sync）使用 PUT 而不是 POST：Halo 会把「有名称段的 POST」降级为非资源请求，此时资源型权限规则不生效，非超级管理员会被拒绝。

keyword 会匹配昵称、留言、交易单号三个字段。

#标准 CRUD

Halo 会为自定义模型自动生成标准端点：

GET    /apis/reward.nanzhiy.cn/v1alpha1/records
GET    /apis/reward.nanzhiy.cn/v1alpha1/records/{name}
POST   /apis/reward.nanzhiy.cn/v1alpha1/records
PUT    /apis/reward.nanzhiy.cn/v1alpha1/records/{name}
DELETE /apis/reward.nanzhiy.cn/v1alpha1/records/{name}

使用这些端点需要相应的 RBAC 权限，且请求体必须是完整的 Kubernetes 风格资源对象（含 apiVersion、kind、metadata、spec）。一般场景建议使用上面的管理 API，字段更简单。

#相关文档

• 主题 API：模板变量、Finder API、模态框引用
• 爱发电对接：后台配置与回调说明