dark/FtpTool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
FtpTool/current.md
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

5.4 KiB
Raw Permalink Blame History

当前架构

已从 开发 -> FTP -> 生产 改为 生产环境单 prod-agent -> 开发 Git / 生产 push-pull API 正式启动类是 GitDirectSyncToolApplication.java 已完成

Git -> PROD 主链路已可用 PROD -> Git 主链路已可用 生产真实接口已按 testapi.txt 适配 pushConfig：POST + JSON数组 pullConfig：GET + JSON响应 login：已支持 token 获取与缓存 ackSuc/ackFail：已接入回传与本地落库 ackSuc/ackFail：已改为 pull 数据处理完成后，再补发一次 ACK-only pullConfig 确认请求（只带 ackSuc/ackFail） ConfigCryptoService：已抽出，当前默认透传实现，后续只需替换该服务内算法 Git -> PROD：已支持最小增量推送，删除场景自动回退全量 Git -> PROD：已改为先按 git.repo.scan-branch-pattern 批量扫描版本分支，再逐个按“版本分支 + 机场目录 + 模块目录”解析参数 PROD -> Git：已按 airportId/appName/fileName 目录结构回写到动态 snapshot 分支 Git -> PROD：sourceVersion/configVersion 已改为 Git 分支名，不再用 commit SHA Git -> PROD：baseline 已按版本分支隔离 pullConfig：已支持 configVersion/fileName 可选过滤参数 ackFail：已支持按 airportId/appName/configVersion/fileName 定向重拉 ackFail：失败记录已增加 retryCount/nextRetryAt/lastErrorMsg 元数据 管理接口已加： GET /api/admin/sync/overview GET /api/admin/sync/tasks/recent GET /api/admin/sync/tasks/failed docs 下设计文档和接口文档已同步更新到当前口径

Git 仓库约定

Git -> PROD：

  • 支持两种入口：
    • git.repo.scan-branch：只同步一个指定版本分支
    • git.repo.scan-branch-pattern：批量扫描所有匹配分支，当前默认用于 R_XXX_.*
  • 分支名本身就是 configVersion
  • 分支内目录结构必须为：airportId/appName/模块内文件
  • pushConfig 参数映射：
    • airportId = 路径第1段
    • appName = 路径第2段
    • fileName = 模块内相对路径
    • configVersion = 当前分支名

PROD -> Git：

  • pullConfig 返回项会恢复为：airportId/appName/fileName
  • 当前提交目标分支为：git.repo.snapshot-branch/
  • 例如：config-prod-snapshot/R_XXX_V3.0.3_XXX
  • 若 pullConfig 返回缺少统一版本号，则按当前 result 的 sourceVersion 退化生成动态分支名
  • pull 数据处理完成后，需要再次调用一次 pullConfig 做 ACK 确认，请求只传 ackSuc/ackFail

关键文件

生产接口适配：ProdConfigApiService.java 加解密扩展点：ConfigCryptoService.java 主协调器：ProdSyncCoordinator.java ACK 落库： ProdPullAckRecord.java ProdPullAckService.java 管理接口：SyncManagementController.java 接口文档：prod-api-v1.md 设计文档： git-direct-sync-tool-design.md ftp-sync-tool-design.md ftp-sync-tool-detail-design.md 当前 TODO

configContent 推送前加密 configContent 拉取后解密

本轮评估结论（2026-04-29）

目标补充

最终目标希望 Git 仓库内容与生产接口库保持一致。

当前结论

  • 当前正式模式不变：
    • Git -> PROD：版本分支直推生产
    • PROD -> Git：回写到 git.repo.snapshot-branch/
  • 当前不建议直接把生产回流写回对应版本分支。
  • 原因不是“代码不能写”，而是“当前 pullConfig 语义还不够安全”：
    • pullConfig 不带过滤时，返回的是“未同步到 Git 的已审核配置”
    • 这不是某个 configVersion 的全量快照
    • 但当前 Git 回写语义是“整目录覆盖目标分支”
    • 如果直接覆盖版本分支，可能误删未出现在本次 pull 结果里的文件
  • 当前 snapshot 分支仍然有必要保留，作为生产回流的隔离区和审计区。

保守方案（推荐）

  1. 保持当前双分支职责不变

    • 版本分支：作为 Git -> PROD 的发布源
    • snapshot 动态分支：作为 PROD -> Git 的生产回流镜像分支

  2. 把 snapshot 分支定义为“生产待对账视图”

    • 生产回流继续先写到 git.repo.snapshot-branch/
    • 不直接改动 R_XXX_* 等版本分支

  3. 增加“版本分支 vs snapshot 分支”自动对账能力

    • 对比同一 configVersion 下两边目录差异
    • 差异至少要区分：新增、修改、删除
    • 输出可读结果，供人工确认是否需要把生产变更回收进版本分支

  4. 增加“受控回收”动作，而不是自动覆盖

    • 建议后续增加管理入口或命令：
      • promoteSnapshotToVersion(configVersion)
    • 行为：
      • 读取 snapshot 分支
      • 与对应版本分支做差异确认
      • 经人工确认后再回写版本分支
    • 这样可以避免生产临时变更直接污染发布分支

  5. 明确回环控制

    • Git -> PROD 只扫描版本分支
    • snapshot 前缀分支不得进入 git.repo.scan-branch-pattern
    • 避免生产回流提交再次被推回生产形成闭环

  6. 后续如果要升级成“版本分支直接等于生产态”，前提是：

    • 生产接口能按 configVersion 提供全量数据
    • 或者返回结果具备明确删除语义
    • 在此前，不建议取消 snapshot 隔离层

下一步建议

如果继续推进，最稳妥的下一步是：

  • 先实现“snapshot 分支 与 对应版本分支”的差异对账能力
  • 再决定是否补一个人工确认后的 promote 流程 验证状态

mvn -s build-support/maven-settings.xml test 已通过 如果你是想让我继续下一步，最顺的就是：

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