# 后端接口契约 · tool.xpcool.com

后端为 `service.xpcool.com`（GoFrame v2）。前端统一走 `src/api/client.ts`，
已实现的接口封装在 `src/api/openTools.ts`。

> ⚠️ 本文件曾经是一份"待实现清单"（`/api/tools/*`）。2026-09-14 已按**线上实际部署**重写：
> 落地在 `/api/service/open/tools/*` 的 5 个接口**已经上线可用**，其余仍是待实现。

## 通用约定

- **Base URL**：环境变量 `VITE_API_BASE`，默认 `https://service.xpcool.com`（见 `.env.example`）。
  未配置时前端仍可用默认值，不会白屏。
- **统一响应格式**（GoFrame `MiddlewareHandlerResponse` 信封）：
  ```json
  { "code": 0, "message": "OK", "data": { ... } }
  ```
  - `code = 0` 成功；非 0 失败，`message` 为可读错误信息（前端直接展示给用户）。
- **方法**：**一律 POST**，URL 不带任何参数（查询参数、路径参数都禁止），入参全部走 JSON Body。
  这是本项目 2026-08-27 起的强制接口设计规范。
- **鉴权**：无（公开工具站）。
- **CORS**：后端 `CORS` 中间件已开启，允许跨域。
- **超时**：前端 `DEFAULT_TIMEOUT = 10000ms`，超时与网络不可达在 `describeStatus()` 中区分提示。

---

## 一、已实现接口（5 个）

前缀：`/api/service/open/tools`

| # | 路径 | 说明 | 前端封装 |
| --- | --- | --- | --- |
| 1 | `POST /api/service/open/tools/ip` | 客户端 IP + 内网判定 | `fetchClientIp()` |
| 2 | `POST /api/service/open/tools/time` | 服务端当前时间 | `fetchServerTime()` |
| 3 | `POST /api/service/open/tools/uuid` | 唯一 ID | `fetchUuid(short)` |
| 4 | `POST /api/service/open/tools/md5` | 文本 MD5 | `fetchMd5(text)` |
| 5 | `POST /api/service/open/tools/random` | 随机字符串 | `fetchRandomString(length, type)` |

后端源码位置：`api/open/tools/<name>/<name>.go` + `internal/controller/open/<name>.go`。
路由挂载：`internal/cmd/cmd.go` 中 `s.Group("/api/service/open", ...)`。

### 1. `POST /tools/ip`

请求体：`{}`

```json
{ "code": 0, "message": "OK", "data": { "ip": "1.2.3.4", "internal": false } }
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| ip | string | 服务端看到的来源 IP |
| internal | bool | 是否为内网/私网地址 |

> 注意：**不返回归属地**（国家/省/市/ISP）。前端「IP 信息查询」页对此如实说明，不做猜测。
> 若要补归属地，需后端接入离线 IP 库后新增字段，前端预留位置。

### 2. `POST /tools/time`

请求体：`{}`

```json
{
  "code": 0,
  "message": "OK",
  "data": { "timestamp": 1757788000, "dateTime": "2026-09-14 01:45:00", "date": "2026-09-14" }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| timestamp | int | Unix 秒 |
| dateTime | string | `2006-01-02 15:04:05`（时区取决于服务端配置，前端不推断） |
| date | string | `2006-01-02` |

前端用它做两件事：显示服务端时间、估算本机时钟偏移。
偏移量基于 `timestamp`（Unix 秒，与时区无关），并补偿半个往返耗时，误差上界为 `rtt/2`。

### 3. `POST /tools/uuid`

请求体：`{ "short": false }`

```json
{ "code": 0, "message": "OK", "data": { "uuid": "a1b2c3d4e5f6..." } }
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| short | bool | true 返回 8 位短码；false 返回 32 位 ID |

前端服务端模式下一律**并发**调用 n 次（接口一次只返回一个），因此数量上限压到 10。

### 4. `POST /tools/md5`

请求体：`{ "text": "ping" }`（`text` 非空，后端有校验）

```json
{ "code": 0, "message": "OK", "data": { "md5": "b6f3a1..." } }
```

用于「哈希计算」页的**两端口径对比**：同一段文本前端（spark-md5）与后端各算一次。
比对统一折成小写，大小写只是展示层选择。

### 5. `POST /tools/random`

请求体：`{ "length": 8, "type": "alnum" }`

```json
{ "code": 0, "message": "OK", "data": { "value": "aB3xK9Qz" } }
```

| 字段 | 类型 | 约束 |
| --- | --- | --- |
| length | int | `1 - 128`（`v:"min:1|max:128"`，前端常量 `RANDOM_MAX_LENGTH = 128`） |
| type | string | `alnum` \| `digits` \| `letters`（`v:"in:alnum,digits,letters"`） |

---

## 二、待实现接口

以下工具在「在线服务」分类中，但后端尚无对应接口。
前端已用 `BackendPending` 组件如实标注「接口尚未上线」，**不会伪装成可用**；
后端实现后把对应页面的 `BACKEND_*_READY` 常量改为 `true`（或去掉开关）即可自动生效。

| 工具 | 建议路径 | 说明 |
| --- | --- | --- |
| 汇率换算 | `POST /api/service/open/tools/exchange-rate` | `{ from, to, amount }` |
| 快递查询 | `POST /api/service/open/tools/express-query` | `{ no }` |
| 手机号归属地 | `POST /api/service/open/tools/phone-locate` | `{ phone }` |
| 网络测试 | `POST /api/service/open/tools/network-test` | `{ type: ping\|tcp\|dns, host, port, timeout }` |
| 网络测速 | `POST /api/service/open/tools/speedtest/*` | 下载返回随机二进制流，上传接收二进制流 |

上述字段设计沿用旧契约（见 git 历史中的 2026-08-24 版本），仅路径前缀从 `/api/tools/*` 迁到
`/api/service/open/tools/*`，并统一改为 POST + 纯 body 传参。

## 三、连通性自检

前端内置「服务端接口状态」页（`/api-status`），逐个探测上面 5 个已实现接口的
可用性与响应耗时。接口清单来自 `OPEN_TOOL_ENDPOINTS`，**新增接口只需在 `openTools.ts`
补一条元数据**，「接口状态」页与首页的接口计数会自动同步。

2026-09-14 实测（`curl` 直连线上）：

| 接口 | 结果 |
| --- | --- |
| `/tools/ip` | HTTP 200 |
| `/tools/time` | HTTP 200 |
| `/tools/uuid` | HTTP 200 |
| `/tools/md5` | HTTP 200 |
| `/tools/random` | HTTP 200 |

## 四、前端接入说明

1. 复制 `.env.example` 为 `.env`，按需覆盖 `VITE_API_BASE`（不填也能跑，默认线上地址）。
2. `pnpm dev` / `pnpm build`。
3. 新增后端接口时：
   - 在 `src/api/openTools.ts` 补 `OpenEndpoint` 元数据 + 调用函数；
   - 在对应工具页接入，并补 `src/i18n/locales/*.ts` 的 `page.*` 文案（**四语言都要补**）。