# 生产端配置同步接口文档 V1

## 1. 文档目的

本文档基于 `testapi.txt` 中给出的正式接口协议，定义生产端配置同步相关接口，供 Git 直连同步工具使用。

本文档覆盖三类接口：

1. `pushConfig`：把 Git 配置推送到生产
2. `pullConfig`：把生产配置拉回到 Git
3. `login`：获取调用接口所需 token

## 2. 统一约定

### 2.1 编码与格式

- 编码：`UTF-8`
- 返回格式：`JSON`
- 鉴权方式：请求头中携带 `token`

### 2.2 成功判定

接口成功时返回：

- `code = "0"`
- `msg = "ok"`

### 2.3 失败响应格式

所有接口失败时的响应格式统一如下：

```json
{
  "code": "XXX-00-00-XXX",
  "data": null,
  "msg": "errmsg!",
  "timestamp": "1776735560594"
}
```

## 3. 接口一：推送 Git 配置到生产

### 3.1 基本信息

- 地址：`http://ip:port/pic_bus_manage_monitor/configSync/pushConfig`
- 方法：`POST`
- 内容格式：`JSON`
- 鉴权：Header 中携带 `token`

### 3.2 请求参数

无 URL 参数。

### 3.3 请求体

请求体为 JSON 数组，每个数组元素代表一个配置文件：

```json
[
  {
    "airportId": "test",
    "appName": "XXX",
    "configVersion": "R_XXX_V3.0.3_XXX",
    "configContent": "配置内容",
    "fileName": "配置文件名"
  }
]
```

字段说明：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `airportId` | 是 | 机场编码 |
| `appName` | 是 | 应用名称 |
| `configVersion` | 是 | 配置版本号 |
| `configContent` | 是 | 配置内容 |
| `fileName` | 是 | 配置文件名 |

### 3.4 响应体

```json
{
  "code": "0",
  "data": {
    "ackFail": [
      {
        "airportId": "test",
        "appName": "XXXx",
        "configVersion": "R_XXX_V3.0.35.6.1_XXX",
        "fileName": "配置文件名"
      }
    ]
  },
  "msg": "ok"
}
```

字段说明：

- `ackFail`：本次推送失败的配置项列表
- 如果 `ackFail` 为空或不存在，可视为本次推送成功
- 如果 `ackFail` 非空，应视为部分失败或失败

### 3.5 业务说明

- 第一次推送为全量
- 之后按增量推送
- 如果全量配置过大，需要视情况拆分多次推送
- `configContent` 需要加密
- **加密方式当前留为 `TODO`**

## 4. 接口二：从生产拉取配置到 Git

### 4.1 基本信息

- 地址：`http://ip:port/pic_bus_manage_monitor/configSync/pullConfig`
- 方法：`GET`
- 内容格式：`JSON`
- 鉴权：Header 中携带 `token`

### 4.2 请求参数

接口文档给出的请求参数如下：

```json
{
  "airportId": "test",
  "appName": "XXXx",
  "configVersion": "R_XXX_V3.0.35.6.1_XXX",
  "fileName": "配置文件名",
  "ackSuc": "id,id",
  "ackFail": "id,id"
}
```

说明：

- 由于该接口是 `GET`，当前实现按查询参数方式理解这些字段
- 当前代码只使用 `airportId`、`appName` 做基础过滤
- `ackSuc`、`ackFail` 暂未纳入当前实现
- 这部分如果后续要完全对齐，可继续补充

### 4.3 响应体

```json
{
  "code": "0",
  "data": [
    {
      "id": "1",
      "airportId": "test",
      "appName": "XXXx",
      "configVersion": "R_XXX_V3.0.35.6.1_XXX",
      "configContent": "配置内容（加密）",
      "fileName": "配置文件名"
    }
  ],
  "msg": "ok"
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `id` | 配置记录标识 |
| `airportId` | 机场编码 |
| `appName` | 应用名称 |
| `configVersion` | 配置版本号 |
| `configContent` | 配置内容 |
| `fileName` | 配置文件名 |

### 4.4 业务说明

- 不带请求参数时，返回所有“未同步到 Git 且已审核通过”的配置
- `configContent` 为加密内容
- **解密方式当前留为 `TODO`**

## 5. 接口三：获取 token

### 5.1 基本信息

- 地址：`http://ip:port/pic_bus_manage_monitor/pam-monitor/login`
- 方法：`POST`
- 内容格式：`JSON`
- 说明：该接口已存在，用于获取配置同步接口所需 token

### 5.2 请求体

```json
{
  "name": "XXXxx",
  "password": ""
}
```

### 5.3 响应体

```json
{
  "code": "0",
  "data": {
    "token": "tetttwe",
    "expireTime": "2026-07-11 11:11:11"
  },
  "msg": "ok"
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `token` | 鉴权 token |
| `expireTime` | token 过期时间 |

### 5.4 业务说明

- 如果 token 过期，需要重新调用登录接口获取新 token

## 6. 当前代码实现对齐情况

当前代码实现文件：

- [ProdConfigApiService.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/service/ProdConfigApiService.java)

当前实现已经对齐到以下协议：

- `pushConfig` 使用 `POST + JSON 数组`
- `pullConfig` 使用 `GET + JSON 响应`
- `login` 使用 `POST + JSON`
- 请求头默认使用 `token` 作为 token 头名称
- `token` 未静态配置时，会自动调用登录接口获取并缓存

当前仍保留的 `TODO`：

- `configContent` 推送前加密
- `configContent` 拉取后解密
- `pullConfig` 中 `ackSuc/ackFail` 参数的完整处理

## 7. 当前配置项

为配合上述接口，当前配置项建议如下：

```properties
prod.api.base-url=https://prod.example.com
prod.api.push-path=/pic_bus_manage_monitor/configSync/pushConfig
prod.api.pull-path=/pic_bus_manage_monitor/configSync/pullConfig
prod.api.login-path=/pic_bus_manage_monitor/pam-monitor/login
prod.api.token=replace-me
prod.api.token-header-name=token
prod.api.airport-id=replace-me
prod.api.app-name=replace-me
prod.api.login-name=
prod.api.login-password=
```

说明：

- 如果 `prod.api.token` 已直接配置，则当前实现优先使用静态 token
- 如果没有配置 token，则走 `login` 接口获取 token

## 8. 联调建议

联调时建议优先确认以下几点：

1. `token` 请求头名称是否就是 `token`
2. `pullConfig` 的 GET 请求参数是否确实按 query string 传递
3. `ackFail` 非空时是否要整体视为失败
4. `configContent` 加密/解密算法何时补齐
5. `fileName` 是否可能包含目录层级