# file-sync-platform

**Repository Path**: liuwenya/file-sync-platform

## Basic Information

- **Project Name**: file-sync-platform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 银行文件同步平台

这是面向四节点部署的生产工程基线。文件、Job 和 Outbox 均通过数据库条件更新（CAS）竞争所有权，并使用租约和心跳处理节点宕机；下载和整文件解析不持有长事务，文件成功状态与成功事件在同一短事务提交。

## 环境要求

- JDK 8（建议使用仍由供应商维护的最新 Java 8 CPU 版本）
- MySQL 8.0（InnoDB，数据库时区与应用统一为 `Asia/Shanghai`）
- 四台服务器时间同步
- 每台服务器可写的独立文件目录
- OAuth2/OIDC 身份服务提供 JWK Set 地址

## 必填环境变量

| 变量 | 说明 |
| --- | --- |
| `DB_URL` | MySQL JDBC 地址，四个节点连接同一主库 |
| `DB_USERNAME` | 数据库账号，按最小权限授权 |
| `DB_PASSWORD` | 数据库密码，由密钥系统注入 |
| `FILE_STORAGE_ROOT` | 本节点下载文件目录，不要使用系统临时目录 |
| `FILE_WORKER_ID` | 节点唯一且稳定的标识，例如 `filesync-node-1` |
| `FILESYNC_ENDPOINT_MASTER_KEY` | Base64 编码的 32 字节 AES 主密钥，四节点保持一致 |
| `FILESYNC_JWK_SET_URI` | OAuth2/OIDC 身份服务的 JWK Set 地址 |

`FILE_WORKER_ID` 在四台服务器上必须分别设置为不同值。`FILESYNC_ENDPOINT_MASTER_KEY` 必须一致，否则节点之间无法互相解密端点凭据。

## 建库与升级

全新环境在空库执行 `src/main/resources/schema.sql`。已有旧版数据库按顺序执行 `migration-v2-distributed.sql`、`migration-v3-notify-idempotency.sql`、`migration-v4-trade-date.sql`、`migration-v5-table-comments.sql`、`migration-v6-csv-controls.sql`，不要在同一数据库重复执行脚本。执行 v3 前先确认同一 `system_code` 下不存在重复 `callback_id`；执行 v4 时必须核对历史记录的真实交易日，脚本按通知创建日期生成的值仅用于辅助回填。v5 仅补充表级中文注释，不修改业务数据。生产环境应由数据库变更平台执行并留存审批记录，应用保持 `SQL_INIT_MODE=never`。

## 接口权限

- `/sync/**`：JWT 需要 `filesync.write` scope
- `/monitor/**`、`/actuator/prometheus`：JWT 需要 `filesync.read` scope
- `/actuator/health/**`：允许负载均衡器匿名探活

生产环境保持 `FILESYNC_SECURITY_ENABLED=true`。本地联调才允许显式关闭。

## 四节点启动

四个节点使用相同应用包、数据库、JWT 配置和端点主密钥，只调整 `SERVER_PORT`（如同机部署）、`FILE_STORAGE_ROOT` 与唯一的 `FILE_WORKER_ID`。建议租约时长至少为心跳间隔的三倍，默认 600 秒与 30 秒满足该约束。

健康检查：`GET /actuator/health/readiness`。Prometheus 指标：`GET /actuator/prometheus`。

通知请求必须提供 ISO 格式交易日字段 `tradeDate`（例如 `2026-07-25`）。通知幂等键为 `systemCode + tradeDate + callbackId`；工作流、人工重跑和监控均以 `tradeDate + batchNo` 作为业务隔离边界。批次监控接口为 `GET /sync/monitor/{tradeDate}/{batchNo}`。

## CSV文件规范

`CUSTOMER`固定表头为`customer_id,customer_name`；`ACCOUNT`固定表头为`account_id,customer_id,balance`。文件必须使用合法UTF-8编码，可包含UTF-8 BOM，支持RFC 4180双引号、字段内逗号和双引号转义；空记录、未闭合或未转义引号、列数变化、控制字符、超长字段及科学计数法金额均拒绝。

通知中的每个`CUSTOMER`和`ACCOUNT`文件必须提供`recordCount`（不包含表头），`ACCOUNT`还必须提供`totalAmount`。解析完成前会核对实际记录数及ACCOUNT余额合计；不一致时文件进入`FAIL`，已经短事务提交的该文件暂存数据会被清理，不会进入后续工作流。单文件字节数、记录数、单列字符数和批量提交大小由`filesync.csv`配置控制。

## 上线门禁

本地单元测试不能代替银行生产验收。上线前至少完成：安全与密钥管理评审、数据库 SQL/索引评审、真实文件规模压测、四节点宕机与网络分区演练、Outbox 失败补偿演练、备份恢复和灾备切换验证、日志脱敏与审计留存检查。