c1ced1b7b6
- 按 testapi.txt 的正式协议重写生产接口适配 - 将 pushConfig 调整为 POST + JSON 数组方式推送配置 - 将 pullConfig 调整为 GET + JSON 列表方式拉取配置 - 新增 login 接口适配，支持 token 获取与本地缓存 - 新增 prod_pull_ack 表、实体、仓储与服务，支持 ackSuc/ackFail 回传 - 在 ProdSyncCoordinator 中串联 pullConfig 成功/失败回执记录逻辑 - 为 Git -> PROD 链路增加最小增量推送能力，删除文件场景自动回退全量 - 扩展 WorkDirectoryService 与 FileTreeUtils，支持增量基线目录和选择性文件复制 - 更新 application.properties 与 application-prod-agent.properties 的生产接口配置项 - 重写 prod-api-v1.md，使接口文档与真实生产协议一致 - 补充 HTTP 层与主链路测试，覆盖 ack 参数回传和最小增量同步 - 保留 configContent 加解密逻辑为 TODO
273 lines
5.9 KiB
Markdown
273 lines
5.9 KiB
Markdown
# 生产端配置同步接口文档 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` 是否可能包含目录层级
|