dark c22eff8950 feat(sync): 将 pullConfig 的 ACK 确认拆分为独立请求

- 正常 pullConfig 请求不再夹带 ackSuc/ackFail，只保留业务过滤参数
- 在本轮生产数据处理完成后，新增一次 ACK-only 的 pullConfig 确认调用
- ACK 确认请求仅回传 ackSuc/ackFail，不再携带 airportId/appName/configVersion/fileName
- 保持本地 ackFail 落库与定向重拉机制不变，确认成功后再标记 reported
- 更新相关 HTTP/集成测试，并同步 current.md 与 prod-api-v1.md 文档

2026-04-29 11:25:41 +08:00

8.5 KiB

Raw Permalink Blame History

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

1. 文档目的

本文档基于 testapi.txt 的正式协议，说明 Git 直连同步工具如何对接生产侧接口。

当前文档同时覆盖两层内容：

接口协议本身
当前代码如何把 Git 仓库结构映射成接口参数

2. 当前 Git 仓库约定

2.1 Git -> PROD 输入约定

当前实现约定：

优先使用 git.repo.scan-branch-pattern 批量匹配版本分支
如需定向同步单个版本，也可以显式配置 git.repo.scan-branch
分支名本身就是 configVersion
分支内目录结构必须为：

<airportId>/<appName>/<模块内文件相对路径>

示例：

R_XXX_V3.0.3_XXX
├─ PEK
│  └─ monitor
│     ├─ application.yml
│     └─ jobs/sync-job.json
└─ SHA
   └─ gate
      └─ gate-rule.json

映射规则：

airportId = 路径第 1 段
appName = 路径第 2 段
fileName = 从第 3 段开始的模块内相对路径
configVersion = 当前 Git 分支名

例如文件：

PEK/monitor/jobs/sync-job.json

会被映射为：

{
  "airportId": "PEK",
  "appName": "monitor",
  "configVersion": "R_XXX_V3.0.3_XXX",
  "fileName": "jobs/sync-job.json"
}

2.2 PROD -> Git 输出约定

当前实现会把 pullConfig 返回项按版本分组后落到本地 staging 目录，目录结构同样为：

<airportId>/<appName>/<fileName>

之后按动态分支提交到 git.repo.snapshot-branch/<configVersion>。

3. 统一接口约定

3.1 编码与格式

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

3.2 成功判定

接口成功时返回：

code = "0"
msg = "ok"

3.3 失败响应格式

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

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

4.1 基本信息

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

4.2 请求参数

无 URL 参数。

4.3 请求体

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

[
  {
    "airportId": "PEK",
    "appName": "monitor",
    "configVersion": "R_XXX_V3.0.3_XXX",
    "configContent": "配置内容",
    "fileName": "jobs/sync-job.json"
  }
]

字段说明：

字段	必填	说明
`airportId`	是	机场编码，来自 Git 路径第 1 段
`appName`	是	模块名，来自 Git 路径第 2 段
`configVersion`	是	配置版本号，当前实现取 Git 分支名
`configContent`	是	文件内容，当前实现按 UTF-8 文本直接读取
`fileName`	是	模块内文件相对路径，不包含 `airportId/appName` 前缀

4.4 响应体

{
  "code": "0",
  "data": {
    "ackFail": [
      {
        "airportId": "PEK",
        "appName": "monitor",
        "configVersion": "R_XXX_V3.0.3_XXX",
        "fileName": "jobs/sync-job.json"
      }
    ]
  },
  "msg": "ok"
}

字段说明：

ackFail：本次推送失败的配置项列表
如果 ackFail 为空或不存在，可视为本次推送成功
如果 ackFail 非空，当前代码直接抛错，视为本次同步失败

4.5 当前实现说明

第一次推送走全量
后续优先走最小增量
如果检测到文件删除，会自动回退到全量推送
基线目录按版本分支隔离保存
configContent 当前已统一经过 ConfigCryptoService
默认实现仍为透传，正式加密算法待补

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

5.1 基本信息

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

5.2 请求参数

接口协议中的字段如下：

{
  "airportId": "PEK",
  "appName": "monitor",
  "configVersion": "R_XXX_V3.0.3_XXX",
  "fileName": "jobs/sync-job.json",
  "ackSuc": "1,2",
  "ackFail": "9"
}

说明：

由于接口是 GET，当前实现按 query string 传参
正常拉取请求当前已经支持：
- airportId 可选过滤
- appName 可选过滤
- configVersion 可选过滤
- fileName 可选过滤
ACK 确认请求当前已经支持：
- ackSuc 自动回传
- ackFail 自动回传

5.3 当前请求行为

当前代码发起两类 pullConfig 请求：

正常拉取请求：

只有在配置了过滤条件时才会发送：
- prod.api.airport-id
- prod.api.app-name
- prod.api.pull-config-version
- prod.api.pull-file-name

如果这些配置为空，则不会在请求中携带它们，此时依赖生产端返回所有已审核且未同步的配置。

ACK 确认请求：

在本轮 pull 数据处理完成后额外发起一次
请求只传：
- ackSuc
- ackFail
不再夹带 airportId/appName/configVersion/fileName 过滤参数

5.4 响应体

{
  "code": "0",
  "data": [
    {
      "id": "1",
      "airportId": "PEK",
      "appName": "monitor",
      "configVersion": "R_XXX_V3.0.3_XXX",
      "configContent": "配置内容（加密）",
      "fileName": "jobs/sync-job.json"
    }
  ],
  "msg": "ok"
}

字段说明：

字段	说明
`id`	配置记录标识
`airportId`	机场编码
`appName`	模块名
`configVersion`	配置版本号
`configContent`	配置内容
`fileName`	模块内文件相对路径

5.5 当前实现说明

pullConfig 返回项会先按 configVersion 分组，再分别落盘为 airportId/appName/fileName
如果某组内所有项的 configVersion 相同，则该值作为该组的 sourceVersion
如果某组缺少统一版本号，则该组退回为内容哈希作为 sourceVersion
configContent 当前已统一经过 ConfigCryptoService，默认实现仍为透传
pull 结果本地处理完成后，会再补发一次 ACK-only pullConfig 请求，只带 ackSuc/ackFail
当本地处理失败时，会把失败项写入 ACK 重试表，并在下次按 airportId/appName/configVersion/fileName 定向重拉

6. 接口三：获取 token

6.1 基本信息

地址：http://ip:port/pic_bus_manage_monitor/pam-monitor/login
方法：POST
内容格式：JSON

6.2 请求体

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

6.3 响应体

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

6.4 当前实现说明

如果 prod.api.token 已显式配置，则优先使用静态 token
如果未配置静态 token，则调用 login 接口获取 token
token 会按 expireTime 做本地缓存

7. 当前代码实现对齐情况

当前接口适配实现：

ProdConfigApiService.java

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

pushConfig 使用 POST + JSON 数组
pullConfig 使用 GET + JSON 响应
login 使用 POST + JSON
ackSuc/ackFail 已接入 ACK-only 二次确认请求和本地状态更新
pushConfig 参数已按 airportId/appName/fileName 目录结构解析
pullConfig 响应已按 airportId/appName/fileName 结构恢复到本地目录

当前仍保留的 TODO：

将 ConfigCryptoService 的透传实现替换为正式加解密算法

8. 当前配置项说明

建议配置：

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=
prod.api.app-name=
prod.api.pull-config-version=
prod.api.pull-file-name=
prod.api.login-name=
prod.api.login-password=

说明：

prod.api.airport-id、prod.api.app-name 不再用于 pushConfig 参数组装
它们当前只作为 pullConfig 的可选过滤条件
prod.api.pull-config-version、prod.api.pull-file-name 可用于精细过滤拉取范围
如果希望拉全量已审核数据，建议留空

9. 联调建议

联调时建议优先确认：

token 请求头名称是否就是 token
pullConfig 的 GET 参数是否按 query string 传递
configVersion/fileName 过滤规则是否需要尽快接入
configContent 加密/解密算法何时补齐
fileName 是否始终是模块内相对路径，而不是包含 airportId/appName

8.5 KiB Raw Permalink Blame History Unescape Escape

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

1. 文档目的

2. 当前 Git 仓库约定

2.1 Git -> PROD 输入约定

2.2 PROD -> Git 输出约定

3. 统一接口约定

3.1 编码与格式

3.2 成功判定

3.3 失败响应格式

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

4.1 基本信息

4.2 请求参数

4.3 请求体

4.4 响应体

4.5 当前实现说明

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

5.1 基本信息

5.2 请求参数

5.3 当前请求行为

5.4 响应体

5.5 当前实现说明

6. 接口三：获取 token

6.1 基本信息

6.2 请求体

6.3 响应体

6.4 当前实现说明

7. 当前代码实现对齐情况

8. 当前配置项说明

9. 联调建议

8.5 KiB

Raw Permalink Blame History