# Git 直连架构补充方案

## 1. 背景变化

旧方案依赖：

- 开发环境 -> FTP -> 生产环境

当前条件已经变为：

- FTP 不再使用
- 生产环境可以直接访问开发 Git
- 生产侧继续通过 `pushConfig/pullConfig/login` 接口与业务系统交互

因此当前架构已经收敛为：

- **单端代理 + Git 直连 + 本地状态库**

## 2. 新架构结论

当前推荐只在生产环境部署一套同步服务：

- `prod-agent`

整体拓扑：

```text
开发 Git 仓库 <----> 生产环境 prod-agent <----> 生产系统 push/pull 接口
```

## 3. Git 仓库模型

### 3.1 版本分支

当前需求下：

- **每个待下发版本对应一个 Git 分支**
- `git.repo.scan-branch` 指向当前待同步的版本分支
- **分支名本身就是 `configVersion`**

例如：

- `R_XXX_V3.0.3_XXX`
- `R_XXX_V3.0.4_XXX`

### 3.2 分支内目录结构

每个版本分支内目录必须为：

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

示例：

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

### 3.3 当前快照分支

当前实现使用“固定前缀 + 动态版本段”的快照分支：

- `git.repo.snapshot-branch`

`PROD -> Git` 会把生产拉回的配置写入：

```text
git.repo.snapshot-branch/<configVersion>
```

分支内目录结构同样为：

```text
<airportId>/<appName>/<fileName>
```

说明：

- `git.repo.snapshot-branch` 当前表示分支前缀，不再是唯一固定目标分支
- 实际写入目标由 `sourceVersion/configVersion` 动态展开

## 4. 两条核心链路

### 4.1 Git -> PROD

流程：

1. `prod-agent` 拉取 `git.repo.scan-branch` 指定的版本分支
2. 读取当前 `HEAD revision`，仅用于日志和 staging 隔离
3. 以 **分支名** 作为 `sourceVersion/configVersion`
4. 导出分支工作树
5. 按 `airportId/appName/fileName` 解析所有配置文件
6. 调用生产 `pushConfig`
7. 成功后更新本地检查点和任务状态

### 4.2 PROD -> Git

流程：

1. `prod-agent` 调用生产 `pullConfig`
2. 读取返回项中的 `airportId/appName/fileName`
3. 恢复到本地 staging 目录
4. 计算内容哈希和来源版本
5. 提交到 `git.repo.snapshot-branch/<configVersion>`
6. 成功后更新本地检查点和任务状态

## 5. 当前实现细节

### 5.1 Git -> PROD 版本语义

当前代码已经调整为：

- `sourceVersion = git.repo.scan-branch`
- 不再使用 `commit SHA` 作为业务版本号

`HEAD revision` 仍然保留，但仅用于：

- staging 目录命名
- 日志排查

### 5.2 增量推送

当前实现：

- 首次推送走全量
- 后续和本地 baseline 做对比
- 无删除时只推变更文件
- 检测到删除时自动回退为全量

并且 baseline 已按版本分支隔离，避免不同版本分支之间相互污染。

### 5.3 pushConfig 参数映射

当前映射关系如下：

- `airportId` = Git 路径第 1 段
- `appName` = Git 路径第 2 段
- `fileName` = 模块内相对路径
- `configVersion` = 当前版本分支名

### 5.4 pullConfig 回写结构

当前回写目录：

```text
<airportId>/<appName>/<fileName>
```

因此 `snapshotBranch` 应当被视为快照分支前缀，不建议在该前缀下混入其他开发分支。

## 6. 状态管理

当前继续保留：

- `sync_checkpoint`
- `sync_task`
- `prod_pull_ack`

作用分别是：

- `sync_checkpoint`：记录某个方向最后一次成功版本和哈希
- `sync_task`：记录同步任务生命周期和重试状态
- `prod_pull_ack`：记录下次 `pullConfig` 需要回传的 `ackSuc/ackFail`

## 7. 幂等设计

当前幂等键仍然是：

```text
direction + sourceVersion + contentHash
```

在 Git -> PROD 场景下：

- `sourceVersion` = 版本分支名

在 PROD -> Git 场景下：

- `sourceVersion` 优先取 `pullConfig` 返回的统一 `configVersion`
- 如果返回多版本混合数据，则退回为内容哈希

## 8. 当前配置口径

### 8.1 Git 配置

```properties
git.repo.scan-branch=R_XXX_V3.0.3_XXX
git.repo.snapshot-branch=config-prod-snapshot
```

说明：

- `scan-branch` 当前应直接配置为待同步版本分支名
- `snapshot-branch` 当前表示动态快照分支前缀

### 8.2 生产接口配置

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

说明：

- `prod.api.airport-id`、`prod.api.app-name` 不再用于 Git -> PROD 参数解析
- 它们当前只作为 `pullConfig` 的可选过滤参数
- `prod.api.pull-config-version`、`prod.api.pull-file-name` 可用于精细过滤拉取范围

## 9. 当前仍保留的 TODO

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

## 10. 结论

当前最重要的变化不是“继续抽象通用分支”，而是先把仓库约定和接口参数映射对齐：

- 版本用分支表达
- 机场和模块用目录表达
- 生产接口参数由路径直接解析

这一层已经进入正式实现口径，后续文档和代码都应以此为准。