# 接入指南（给 AI 看的实施说明）

本文档面向**要接入兑换码功能的另一个项目**（下称「接入方」）。请按文档在接入方项目里新增两处代码：

1. `CouponRedeemButton`组件：兑换按钮 + 兑换弹窗（输入兑换码 → 兑换）。
2. 服务端接口：接收兑换码，调用**本平台**的开放接口核销，拿到券的详情后在接入方的用户表上**累加**积分（point）和时长（duration）。

> 接入方不要直接在前端调用管理后台的开放接口：凭证（token）只能放在服务端环境变量里，浏览器端只调接入方自己的接口。

---

## 一、管理后台开放接口契约（必须先读懂）

- 方法：`POST`
- 地址：`https://redeem.zzz.sarl/api/open/redeem`
- 请求头：
  - `Content-Type: application/json`
  - `Authorization: Bearer ${REDEEMSHIP_API_KEY}`
- 请求体（JSON）：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `code` | string | 是 | 兑换码（UUID，接口内部按原值精确匹配） |
| `remark` | string | 否 | 备注；**不传就跳过**，传了才写入 |

- 成功响应（`200`）：

```json
{
  "success": true,
  "message": "兑换成功",
  "data": {
    "code": "d3f0...-...",
    "point": 100,
    "duration": null,
    "status": "used"
  }
}
```

关键点：
- 积分券：`point` 为数字。
- 时长券：`duration` 为 `1_day / 3_day / 1_week / 1_month / 3_month / 1_year` 之一。

- 失败响应（都带 `success: false` 与 `message`）：

| 状态码 | 含义 |
| --- | --- |
| `401` | Authorization 校验失败（token 不对或缺失） |
| `400` | 参数不合法 / 券已被使用 / 券已失效 / 请求体非 JSON |
| `404` | 兑换码不存在 |
| `500` | 管理后台服务端错误 |

---

## 二、接入方需要准备的环境变量

写入接入方的环境变量：

```bash
REDEEMSHIP_API_KEY=xxxxxx
```

---

## 三、步骤 1：新建 `CouponRedeemButton` 组件

要求：

- 页面上一个「兑换」按钮，点击后弹出 Modal；
- Modal 内包含一个兑换码输入框和一个「立即兑换」按钮；
- 点击「立即兑换」调用接入方自己的接口，body 为 `{ code }`；
- 未登录时提示先登录；输入框为空时禁用按钮；请求中显示 loading 并禁用；
- 成功后提示并清空输入、关闭弹窗；失败展示接口返回的 `message`。

以nextjs为例参考实现（Next.js App Router + Tailwind，UI 可按接入方风格调整）：

```jsx
'use client';

import { useState } from 'react';
import { message } from 'antd';
import apiClient from '@/lib/api'; // 接入方的 axios 实例；没有就用 fetch('/api/coupon')

export default function CouponRedeemButton({ className = '' }) {
  const [open, setOpen] = useState(false);
  const [code, setCode] = useState('');
  const [loading, setLoading] = useState(false);

  const handleRedeem = async () => {
    const value = code.trim();
    if (!value) {
      message.warning('请输入兑换码');
      return;
    }

    setLoading(true);
    try {
      const res = await apiClient.post('/api/coupon', { code: value });

      if (res?.success) {
        message.success(res.message || '兑换成功');
        setCode('');
        setOpen(false);
      } else {
        message.warning(res?.message || '兑换失败');
      }
    } catch (error) {
      message.warning(error?.response?.data?.message || '兑换失败，请稍后再试');
    } finally {
      setLoading(false);
    }
  };

  return (
    <>
      <button
        onClick={() => setOpen(true)}
        className={`px-4 py-2 rounded-xl bg-sky-500 text-white font-bold hover:opacity-90 transition ${className}`}
      >
        兑换码
      </button>

      {open && (
        <div className="fixed inset-0 z-50 flex items-center justify-center">
          <div className="absolute inset-0 bg-black/50" onClick={() => setOpen(false)} />

          <div className="relative bg-white rounded-2xl shadow-2xl w-full max-w-md mx-4 overflow-hidden">
            <div className="flex items-center justify-between p-6 border-b border-neutral-100">
              <h3 className="text-xl font-bold">兑换码</h3>
              <button onClick={() => setOpen(false)} className="w-8 h-8 rounded-full hover:bg-neutral-100">
                ✕
              </button>
            </div>

            <div className="p-6 space-y-4">
              <input
                type="text"
                value={code}
                onChange={(e) => setCode(e.target.value)}
                placeholder="请输入兑换码"
                className="w-full px-4 py-3 bg-neutral-50 border border-neutral-200 rounded-xl focus:outline-none focus:ring-2 focus:ring-sky-400"
              />

              <button
                onClick={handleRedeem}
                disabled={!code.trim() || loading}
                className="w-full py-3 px-6 bg-sky-500 text-white font-bold rounded-xl disabled:opacity-50 disabled:cursor-not-allowed"
              >
                {loading ? '兑换中...' : '立即兑换'}
              </button>
            </div>
          </div>
        </div>
      )}
    </>
  );
}
```

把它挂到接入方任意页面上即可（如导航栏、个人中心）：

```jsx
import CouponRedeemButton from '@/components/CouponRedeemButton';

<CouponRedeemButton />
```

---

## 四、步骤 2：新建服务端接口

职责：

1. 校验登录态，拿到当前用户 id；
2. 以服务端身份调用管理后台开放接口（带上 token，绝不暴露给前端）；
3. 拿到 `data.point` / `data.duration`；
4. 根据接入方网站设计实际情况**直接赋值**还是**在原有基础上累加**接入方用户表的积分和时长；
5. 把结果返回给前端。

---

## 五、字段与边界说明（避免踩坑）

- 一张券只能成功核销一次，重复提交会返回 `400 该兑换码已被使用`。
- api key 错误会返回 `401`，此时请检查 `REDEEMSHIP_API_KEY`。
- 前端拿到的错误信息直接用接口返回的 `message` 展示即可。

## 六、验收清单

- [ ] 未登录点击兑换提示「请先登录」。
- [ ] 输入错误兑换码 → 提示「兑换码不存在」。
- [ ] 输入正确兑换码 → 用户积分/时长在接入方网站实现业务，平台该券状态变为 `used`。
- [ ] 同一张券再次提交 → 提示「该兑换码已被使用」。
- [ ] 浏览器 Network 里看不到 `REDEEMSHIP_API_KEY`。
