夜雨聆风Excel文件同步功能支持将Excel数据与系统数据库进行双向同步，适用于以下场景：
业务人员在Excel中维护数据，需要自动同步到数据库
系统数据库中的数据需要定期导出到Excel报表
多台电脑上的Excel文件需要与同一数据库保持同步
核心特性
增量同步
只传输变化的数据行，传输量减少99%
双向同步
支持推送(A=>B)和拉取(B=>A)两个方向
加密传输
AES-CBC加密 + 会话密钥协商 + Token认证
_sync_id主键对应
通过数据库主键ID建立Excel行与数据库行的稳定对应，修改/删除精准识别
查重更新
基于指定字段判断重复，支持只更新变化字段（_sync_id缺失时退化匹配）
定时执行
支持定时任务和文件监听自动同步
Web配置界面
双击即可启动浏览器配置，无需手动编辑配置文件
两种方案
方案A：服务器本地同步
当Excel文件位于服务器本地（或局域网共享目录）时，Go后端直接读取文件并入库，无需客户端。
适用场景：服务器Windows运行，Excel文件在同一台机器或共享目录上。
方案B：远程客户端同步
当Excel文件不在服务器上时，使用Go编译的同步客户端，通过加密通道与服务器通信。
适用场景：远程电脑上的Excel文件需要与服务器数据库同步。
方案A使用方法
1. 配置同步
进入项目表的配置页面，切换到"Excel文件同步"标签页：
输入服务器本地Excel文件路径（如 D:\data\report.xlsx）
点击"测试文件"验证路径是否正确
选择工作表
勾选需要同步的字段
配置字段映射（Excel列名 → 数据库字段名）
保存配置
2. 手动同步
点击"立即同步"按钮，后端直接读取Excel文件并入库。
3. 定时同步
在计划任务中添加Excel同步类型的任务，选择要同步的项目，设置执行周期。
方案B使用方法
1. 生成同步链接
在项目表的"Excel文件同步"标签页中，点击"生成同步链接"按钮，系统会生成：
推送地址(A=>B)：用于客户端向服务端推送数据
拉取地址(B=>A)：用于客户端从服务端拉取数据
同步Token：客户端认证凭证
项目表名：目标数据表标识
2. 配置客户端
根据同步方向，点击"复制推送配置(A=>B)"或"复制拉取配置(B=>A)"，将内容保存为客户端目录下的 config.json 文件，修改 filePath 为本地Excel路径：
{”serverUrl”: ”https://your-server.com/v1/SyncExcelRows”,”syncToken”: ”从后台复制的Token”,”tablename”: ”从后台复制的表名”,”filePath”: ”C:\\data\\report.xlsx”,”sheet”: ””,”fields”: ””,”mapping”: ””,”interval”: 300,”cacheDir”: ””,”syncDirection”: ”push”}
配置项说明
源列=目标字段，逗号分隔，留空默认同名 | ||
push(A=>B推送) 或 pull(B=>A拉取)，默认push |
3. 运行客户端
直接双击 excelsyncclient.exe，程序会：
读取当前目录下的 config.json
如果 filePath 为空，自动搜索当前目录下的xlsx文件（只有一个时自动使用）
如果缺少必要配置（serverUrl/syncToken），自动打开浏览器配置界面
Web配置界面
当配置不完整或使用 -gui 参数启动时，自动打开浏览器配置界面：
excelsyncclient.exe配置不完整时自动进入Web UIexcelsyncclient.exe -gui# 强制启动Web配置界面excelsyncclient.exe -port 18280# 指定Web界面端口（默认18280）
Web界面功能：
📊 同步状态面板：实时显示总行数、已同步、新插入、已更新、已删除、已跳过
⚙️ 连接配置：填写服务器地址、Token、表名、同步方向、定时间隔
📄 Excel文件选择：自动列出当前目录下的xlsx文件，点击即选
📋 同步日志：实时显示同步结果
🔄 一键操作：立即同步 / 启动定时同步 / 停止定时
命令行方式
单次同步excelsyncclient.exe -config config.json# 定时同步（每5分钟）excelsyncclient.exe -config config.json -interval 300# 监听文件变化自动同步excelsyncclient.exe -config config.json -watch# 强制全量同步（忽略缓存）excelsyncclient.exe -config config.json -full
命令行参数
同步方向详解
A=>B 推送模式 (syncDirection: "push")
以客户端Excel数据为准，将本地xlsx的变化推送到服务端数据库。
流程：
客户端读取Excel文件，对每行数据计算SHA256哈希
与本地SQLite缓存对比，找出新增和变化的行
对比缓存与当前Excel的 _sync_id 集合，找出被删除的行
只发送变化行和删除行到服务端（加密传输）
服务端优先按 _sync_id 精确更新，无 _sync_id 时按查重字段处理；删除行按 _sync_id 物理删除
同步成功后更新本地缓存
适用场景：Excel是数据源，业务人员在Excel中维护数据。
B=>A 拉取模式 (syncDirection: "pull")
以服务端数据库为准，将数据库的变化写回客户端xlsx。
流程：
客户端发送上次同步的数据哈希到服务端
服务端对比当前数据哈希，无变化则返回空
有变化时返回全部数据行（含 _sync_id 字段，即数据库主键ID）
客户端读取本地xlsx，优先按 _sync_id 匹配已有行，无 _sync_id 时按查重字段退化匹配
更新变化的单元格，新增行追加到末尾
Excel中存在但服务端已不存在的 _sync_id 对应的行被删除
保存xlsx文件并更新缓存
适用场景：数据库是数据源，需要将数据更新到本地Excel报表。
如果文件正被excel软件打开，则不可写入，会先写到临时文件中，在关闭excel后再写入到正式文件：
_sync_id 主键对应机制
为什么需要 _sync_id
传统基于查重字段(cczd)匹配存在两个根本缺陷：
修改变新建：查重字段值被修改后，匹配失败导致旧行残留+新行追加
删除无法识别：无任何机制判断哪些行被删除，导致已删除行永久残留
_sync_id 列存储数据库行主键ID，作为Excel行与数据库行的稳定唯一对应关系，不受业务字段修改影响。
_sync_id 列的维护
拉取模式：服务端 PullExcelRows 返回数据时自动包含 _sync_id 字段，客户端写入Excel时自动维护该列（放在最后一列）
推送模式：客户端读取Excel时自动读取 _sync_id 列，发送给服务端按主键更新/删除
匹配优先级
服务端 SyncExcelRows 和客户端 writeRowsToExcel 均按以下优先级匹配：
优先按 _sync_id 匹配（最稳定，按数据库主键精确对应）退化按查重字段匹配（当 _sync_id 缺失时，如首次同步或旧Excel文件）追加为新行（无任何匹配时）
首次使用建议
推送模式下首次同步时Excel无 _sync_id 列，会全量推送插入。建议首次使用时先执行一次拉取让Excel获得 _sync_id 列，之后推送/拉取都能精确识别修改和删除。
若不便先拉取，推送模式也会在后续同步中通过查重字段建立对应关系，但修改/删除的识别精度会降低（依赖查重字段值不变）。
增量同步原理
传统全量同步每次传输整个Excel文件（base64编码→JSON→AES加密），即使只改了几行也要传输完整文件。
增量同步使用SQLite本地缓存+行级SHA256哈希对比：
每行数据 → 字段名排序拼接 → SHA256 → 与缓存对比 → 只发送变化行无数据变化时零传输，直接跳过。
安全机制
Token认证：每个项目生成唯一的同步Token，请求时通过 X-Sync-Token 头部验证
会话密钥协商：客户端请求 /v1/getsession 获取临时会话密钥
AES-CBC加密：请求体和响应体均使用AES-CBC加密，每次请求生成随机IV
无JWT依赖：同步接口使用独立的Token认证，不依赖用户登录JWT
API接口
SyncExcelRows 请求结构
{”rows”: [{”_sync_id”: 1, ”姓名”: ”张三”, ”年龄”: ”25”}, ...],”deletedRows”: [{”_sync_id”: 5}, {”_sync_id”: 8}],”mode”: ”increment”,”totalRows”: 100}
rows：新增/修改的行数据，含 _sync_id 时按主键更新，否则按查重字段处理
deletedRows：被删除的行，仅含 _sync_id，服务端按主键物理删除
mode：full(全量) / increment(增量)
totalRows：Excel文件总行数（用于日志）
PullExcelRows 响应结构
{”changed”: true,”dataHash”: ”abc123...”,”rows”: [{”_sync_id”: 1, ”姓名”: ”张三”, ”年龄”: ”25”}, ...],”totalRows”: 100,”cczdFields”: [”姓名”],”gxsjFields”: [”年龄”]}
rows：中每行含 _sync_id 字段（数据库主键ID），客户端据此建立行对应
cczdFields：gxsjFields 为中文名，供客户端无 _sync_id 时退化匹配
常见问题
Q: 首次同步很慢？
A: 首次同步SQLite缓存为空，会自动退化为全量同步，后续同步只传输变化行。
Q: Excel列名和数据库字段名不一致怎么办？
A: 在配置中使用mapping字段映射，格式为Excel列名=数据库字段名，多个用逗号分隔。
Q: 如何处理重复数据？
A: 系统优先按 _sync_id（数据库主键）精确匹配。无 _sync_id 时退化按查重字段(cczd)判断。可在项目表配置中设置查重字段和更新字段(gxsj)。
Q: 修改行的数据为什么以前会变成新建？
A: 旧版本基于查重字段匹配，查重字段值被修改后匹配失败导致旧行残留+新行追加。新版引入 _sync_id 主键列，按数据库主键精确对应，不受业务字段修改影响。建议首次使用时先执行一次拉取让Excel获得 _sync_id 列。
Q: 删除的行会如何处理？
A: 推送模式：Excel删除的行，客户端检测到 _sync_id 缺失，发送删除请求，服务端按主键物理删除。拉取模式：服务端删除的行，客户端检测到 _sync_id 不在服务端返回数据中，从Excel删除对应行。
Q: 客户端缓存损坏怎么办？
A: 删除缓存目录中的 .db 文件，或使用 -full 参数强制全量同步，客户端会自动重建缓存。
Q: 多个客户端同步同一项目会冲突吗？
A: 服务端通过 _sync_id 主键和查重字段保证数据一致性，多个客户端推送的数据会按对应逻辑合并，不会产生重复记录。
Q: 双击exe后没有同步？
A: 双击运行时，如果config.json中缺少filePath，程序会自动搜索当前目录下的xlsx文件；如果缺少serverUrl或syncToken，会自动打开浏览器配置界面，在界面中完成配置后即可同步。
Q: Web配置界面端口被占用怎么办？
A: 程序会自动从默认端口18280开始递增寻找可用端口，无需手动处理。
Q: _sync_id 列可以手动编辑吗？
A: 不建议手动编辑。_sync_id 由系统自动维护，手动修改会导致行对应关系错乱。若不慎损坏，删除该列后执行一次拉取即可重建。
