# 接入说明

了解 BioTech 开放平台的调用边界、接入角色和基本约定。

## BioTech 开放平台是什么

BioTech 开放平台是一套面向外部系统的接口访问层。平台通过应用凭证识别调用方，通过 Access Token 完成认证，并对每个应用精确授权可访问的接口。

它不是把后台所有 `/api/*` 路由直接暴露出去。只有同时满足以下条件的接口才能调用：

1. 代码中使用 `#[OpenApiEndpoint]` 明确发布。
2. 路径位于 `/openapi/*`，且不是公共认证路径。
3. 平台管理员已在“接口管理”中登记并启用。
4. 当前应用已获得该接口授权。

## 接入角色

| 角色       | 负责内容                                                    |
| ---------- | ----------------------------------------------------------- |
| 平台管理员 | 创建应用、保存一次性 Secret、登记接口、配置频控、给应用授权 |
| 接口调用方 | 安全保存凭证、换取和刷新令牌、调用业务接口、处理错误与频控  |

## 调用链路

1. 管理员向调用方交付 `app_key` 和 `app_secret`。
2. 调用方通过 `POST /openapi/auth/token` 获取令牌。
3. 调用方携带 Access Token 请求业务接口。
4. 服务端依次校验令牌、发布状态、应用授权和接口频控。
5. 业务接口执行后返回统一 JSON 响应和 `X-Request-Id`。

## 生产请求地址

BioTech 开放平台的生产基础地址是：

```text
https://backend.biotech-mkt.com
```

例如，获取令牌的完整请求 URL 是 `https://backend.biotech-mkt.com/openapi/auth/token`。在服务端统一配置：

```text
OPENAPI_BASE_URL=https://backend.biotech-mkt.com
```

接口详情页会同时列出完整请求 URL 和接口路径。非生产环境的基础地址由平台管理员另行提供。

## 通用响应

成功和失败均使用统一 JSON 外层结构：

```json
{
  "code": 200,
  "message": "成功",
  "data": {}
}
```

- `code`：业务码。OpenAPI 中间件会把常见错误业务码同步为相同的 HTTP 状态码。
- `message`：面向调用方的结果说明。
- `data`：接口数据；失败时通常为空数组。

## 当前发布范围

代码中当前发布了以下两个受保护接口：

| 方法  | 路径                                                | 用途                           |
| ----- | --------------------------------------------------- | ------------------------------ |
| `GET` | `/openapi/profile`                                  | 验证令牌并查看当前调用方上下文 |
| `GET` | `/openapi/v1/doudian/order/union-settlement-orders` | 分页查询抖音精选联盟订单       |

:::caution[发布不等于已授权]
代码中存在接口并不代表每个应用都能调用。若接口未登记、被禁用或未授权，调用仍会被拒绝。
:::