# Git 直连架构详细设计

## 1. 文档说明

本文档用于承接主方案文档，说明在“FTP 下线、生产环境可直接访问开发 Git”条件下的详细设计。

当前目标是把系统收敛为：

- 单 `prod-agent`
- Git 直连
- 生产 `push/pull` 接口驱动
- H2 本地状态控制

## 2. 架构变化摘要

旧架构：

```text
开发环境 <-> FTP <-> 生产环境
```

新架构：

```text
开发 Git <-> 生产环境 Sync-Agent-Prod <-> 生产 push/pull 接口
```

关键变化：

- FTP 中转取消
- `dev-agent` 不再是必需部署节点
- 生产环境成为唯一同步执行节点
- ACK 文件机制不再作为主流程依赖

## 3. 当前推荐部署

推荐只部署：

- `prod-agent`

运行要求：

- 能访问开发 Git
- 能 push 指定 Git 分支
- 能访问生产 `push/pull` 接口
- 能写本地 H2 文件数据库

## 4. 配置文件策略

当前配置文件仍使用 `properties`：

```text
src/main/resources/
  |- application.properties
  |- application-prod-agent.properties
  |- schema.sql
```

说明：

- `application-dev-agent.properties` 现阶段仅保留为退役标记文件
- `application-prod-agent.properties` 已开始收敛到新架构

## 5. 当前配置口径

### 5.1 仍然保留的核心配置

公共配置：

- `spring.datasource.*`
- `spring.jpa.*`
- `spring.sql.init.*`

同步配置：

- `sync.node-id`
- `sync.role`
- `sync.work-dir`
- `sync.package-temp-dir`
- `sync.dev-to-prod-staging-dir`
- `sync.prod-to-dev-staging-dir`
- `sync.max-retry-count`

Git 配置：

- `git.repo.remote-uri`
- `git.repo.username`
- `git.repo.password`
- `git.repo.scan-branch`
- `git.repo.snapshot-branch`
- `git.repo.commit-message-prefix`

生产接口配置：

- `prod.api.base-url`
- `prod.api.push-path`
- `prod.api.pull-path`
- `prod.api.token`

### 5.2 新的生产侧调度配置

当前已调整为：

- `sync.jobs.prod-git-to-prod.cron`
- `sync.jobs.prod-to-git.cron`

对应文件：

- [application-prod-agent.properties](e:/AIcoding/FtpTool/src/main/resources/application-prod-agent.properties)

### 5.3 遗留 FTP 配置

当前 `application.properties` 中已经移除了 `ftp.*` 相关公共配置。

当前状态：

- FTP 调度主路径已退出运行面
- FTP 相关主类已从当前源码树中移除

## 6. H2 状态设计

当前主表保留为：

- `sync_checkpoint`
- `sync_task`

对应脚本：

- [schema.sql](e:/AIcoding/FtpTool/src/main/resources/schema.sql)

### 6.1 保留原因

即使 FTP 已下线，状态库仍然必须保留，用于：

- 幂等控制
- 检查点管理
- 失败重试
- 审计追踪

### 6.2 当前建议

- `sync_checkpoint` 和 `sync_task` 继续作为主表
- `sync_ack` 已退出当前主 schema

## 7. 当前代码结构与新架构对应关系

### 7.1 已经可继续复用的核心类

- [GitClientService.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/service/GitClientService.java)
- [ProdConfigApiService.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/service/ProdConfigApiService.java)
- [PackageService.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/service/PackageService.java)
- [SyncTaskService.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/service/SyncTaskService.java)
- [CheckpointService.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/service/CheckpointService.java)

### 7.2 当前生产侧主协调器

- [ProdSyncCoordinator.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/orchestrator/ProdSyncCoordinator.java)

当前生产侧主流程已经切到新架构：

- `syncLatestGitToProd()`：Git -> 生产 `push`
- `syncProdSnapshotToGit()`：生产 `pull` -> Git snapshot 分支

### 7.3 当前生产侧正式调度类

- [GitToProdSyncJob.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/job/GitToProdSyncJob.java)
- [ProdToGitSnapshotJob.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/job/ProdToGitSnapshotJob.java)

说明：

- 这两个类是当前推荐使用的正式调度入口
- 已分别对应 `Git -> PROD` 和 `PROD -> Git`

### 7.4 当前遗留占位类

这批旧调度类已经从当前源码树中删除：

说明：

- 已不再作为正式运行入口
- 当前代码树只保留 Git 直连架构需要的正式 job

### 7.5 当前遗留代码

以下内容仍然存在于代码库，但属于旧架构遗留：

- `application-dev-agent.properties` 退役标记文件
- 少量文件名或文档中的 `ftp` 语义残留

这些不是当前推荐运行路径。

## 8. 新架构下的两条任务流

### 8.1 Git -> 生产

当前推荐实现步骤：

1. 拉取 `config-dev-main`
2. 获取最新 commit 作为 `sourceVersion`
3. 导出工作树快照
4. 计算内容哈希
5. 生成标准 zip 包
6. 调用生产 `push` 接口
7. 更新 `sync_task` 和 `sync_checkpoint`

### 8.2 生产 -> Git

当前推荐实现步骤：

1. 调用生产 `pull` 接口
2. 保存返回配置到本地 staging 目录
3. 计算哈希和版本号
4. 写入 `config-prod-snapshot`
5. commit + push
6. 更新 `sync_task` 和 `sync_checkpoint`

## 9. 当前接口假设

当前生产接口仍按以下假设实现：

- `push` 使用 `POST + multipart/form-data`
- `pull` 使用 `GET`
- `pull` 返回原始 JSON 字节流
- 版本号优先取 `X-Config-Version`，其次 `ETag`

详细协议文档见：

- [prod-api-v1.md](e:/AIcoding/FtpTool/docs/prod-api-v1.md)

## 9.1 管理接口

当前已新增一组只读管理接口，用于查看最近同步状态和失败任务：

- `GET /api/admin/sync/overview`
- `GET /api/admin/sync/tasks/recent`
- `GET /api/admin/sync/tasks/failed`

对应实现：

- [SyncManagementController.java](e:/AIcoding/FtpTool/src/main/java/com/ftptool/sync/web/SyncManagementController.java)

## 10. 当前主要风险

### 10.1 Git 写权限

如果生产环境对 Git 没有 push 权限，则“生产 -> Git”链路无法完成。

### 10.2 旧代码残留

当前主运行面已经切到 Git 直连，但源码树里仍保留少量退役占位类。

当前状态：

- 文件名和类名仍可能误导维护者
- 旧架构源码主体已经删除
- 主要剩余问题转为命名和文档口径统一

### 10.3 双向同步闭环

如果误把生产回写分支也作为下发分支扫描，会造成循环同步。

## 11. 推荐的下一轮改造

建议按下面顺序继续：

1. 删除或隔离 `dev-agent` 运行路径
2. 删除退役标记文件 `application-dev-agent.properties`
3. 统一清理残留的 `ftp` 命名
4. 补充管理接口和健康检查接口
5. 增加集成测试

## 12. 结论

当前系统已经从“FTP 中转”开始转向“Git 直连”。

现阶段最重要的不是继续增强旧链路，而是彻底收敛到：

- 单 `prod-agent`
- 两个核心任务
- 一个 Git 仓库入口
- 一组生产 `push/pull` 接口