FtpTool/docs/prod-api-v1.md

生产端配置同步接口文档 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 失败响应格式

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

{
  "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 数组，每个数组元素代表一个配置文件：

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

字段说明：

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

3.4 响应体

{
  "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 请求参数

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

{
  "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 响应体

{
  "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 请求体

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

5.3 响应体

{
  "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

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

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

当前仍保留的 TODO：

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

7. 当前配置项

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

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 是否可能包含目录层级