qhmes/yy-admin-master/doc/桌面端后端数据交互通用模板（以车辆管理为例）.md

# 桌面端后端数据交互通用模板（以车辆管理为例）

## 1. 目的与适用范围

本文将“车辆管理”已落地的同步能力抽象为可复用模板，适用于后续任意业务模块（如供应商、订单、库存、质检等）快速实现：

- 桌面端 CRUD 与后端数据交互
- 正向同步（桌面端 -> 后端）
- 反向同步（后端 -> 桌面端）
- 断线续传（离线可操作，重连自动补偿）
- 本地缓存（保证离线可查、可改）

---

## 2. 总体架构模板

建议统一采用“**信号触发 + REST 拉取 + Outbox 补偿**”架构：

1. 后端业务变更后，广播 STOMP 信号（只发变更事件，不强依赖完整数据包）。
2. 桌面端接收信号后，不直接写本地业务表，而是触发“拉取接口”同步最新数据。
3. 桌面端本地操作时，在线优先调用后端；失败或离线则先写本地缓存 + 记录待同步操作（Outbox）。
4. 网络恢复后自动回放 Outbox，成功后清理队列并全量回拉一次做一致性对齐。

**核心原则**：  
- 在线追求实时，离线保证可用，重连追求最终一致。  
- 任何“回传动作”必须幂等。  
- 同步链路必须有完整日志（请求、结果、回放、失败原因）。

---

## 3. 后端接口模板（推荐样式）

以车辆管理为例，接口分两类：业务 CRUD 接口 + 同步辅助接口。

### 3.1 业务 CRUD（给桌面端直接调用）

建议统一路径风格（示例）：

- `GET /{module}/{entity}/anon/list?pageNo=1&pageSize=10000&tenantId=1002`
- `GET /{module}/{entity}/anon/queryById?id=xxx&tenantId=1002`
- `POST /{module}/{entity}/anon/add?tenantId=1002`
- `POST /{module}/{entity}/anon/edit?tenantId=1002`
- `DELETE /{module}/{entity}/anon/delete?id=xxx&tenantId=1002`
- `POST /{module}/{entity}/anon/updateStatus?id=xxx&status=1&tenantId=1002`

返回建议统一：

```json
{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "result": {}
}
```

分页 `result` 建议统一包含：
- `records`
- `total`
- `current`
- `size`

### 3.2 后端推送信号（反向同步触发）

后端每次成功增删改后，广播 STOMP：

- Topic：`/topic/sync/{entity-topic}`
- Payload 示例：

```json
{
  "cmd": "MES_VEHICLE_CHANGED",
  "action": "add|edit|delete|status",
  "entityId": "xxx",
  "timestamp": 1710000000000
}
```

说明：
- `cmd` 必须唯一且稳定，桌面端按它路由处理。
- `action` 用于日志和增量策略判断。
- `entityId` 可选但建议提供。

### 3.3 桌面端正向回传批量接口（可选增强）

若使用统一 Outbox 回传通道，建议后端提供：

- `POST /sys/sync/batch`

请求体示例：

```json
[
  {
    "messageId": "outbox-id-1",
    "aggregateType": "VEHICLE",
    "aggregateId": "vehicle-id",
    "eventType": "CREATE|UPDATE|DELETE|TOGGLE_STATUS",
    "payload": "{...}",
    "occurredAt": "2026-01-01T10:00:00Z"
  }
]
```

后端必须做 `messageId` 幂等去重。

---

## 4. 桌面端数据层模板

## 4.1 必备组件

每个模块建议固定四层：

1. `EntityService`（例：`VehicleService`）  
   - CRUD 入口  
   - 本地缓存 + 离线队列  
   - 重连回放逻辑

2. `SyncCoordinator`（例：`VehicleSyncCoordinator`）  
   - 监听 STOMP 信号  
   - 识别 `cmd` 并发布本地事件或触发同步

3. `OutboxProcessor`（全局复用）  
   - 持久化消息  
   - 在线实时发、离线补发  
   - 失败重试 + 指数退避

4. `NetworkMonitor`（全局复用）  
   - 网络状态检测  
   - 状态变化事件发布

## 4.2 本地缓存与待同步队列

推荐本地文件结构（示例）：

- `%LocalAppData%/YY.Admin/sync-cache/{entity}-cache.json`
- `%LocalAppData%/YY.Admin/sync-cache/{entity}-pending-ops.json`

建议数据结构：

- `cache`: 最新本地快照（可直接查询）
- `pendingOps`: 离线期间操作日志，按时间顺序回放

`pendingOps` 字段建议：
- `id`
- `opType`（Add/Edit/Delete/UpdateStatus）
- `entityId`
- `payload`
- `createdAt`

---

## 5. 同步逻辑模板（标准流程）

### 5.1 查询流程（Page/List）

1. 在线：先拉远端数据 -> 刷新本地缓存。  
2. 远端失败：回退本地缓存。  
3. 将 `pendingOps` 叠加到查询结果（保证 UI 看到“离线后的最新本地状态”）。

### 5.2 新增/编辑/删除/状态修改

1. 若在线，优先调用远端接口。  
2. 远端成功：更新本地缓存。  
3. 远端失败或离线：写入 `pendingOps`，并立即更新本地缓存（保证可用）。  

**注意**：新增时若本地临时 ID（如 `local-xxx`）不符合后端主键规则，回放前需清空 ID 让后端生成。

### 5.3 网络恢复（断线续传）

触发条件：`NetworkMonitor` 从离线 -> 在线。

流程：
1. 串行回放 `pendingOps`。  
2. 回放中任意失败立即停止，等待下次重试。  
3. 回放完成后再做一次全量拉取，覆盖本地缓存。  
4. 发布 UI 刷新事件（避免用户手动点查询）。

### 5.4 后端 -> 桌面反向同步

流程：
1. STOMP 收到 `cmd`。  
2. `SyncCoordinator` 解析命令。  
3. 触发本地“拉取并刷新缓存”。  
4. UI 订阅变更事件刷新列表。

---

## 6. 可复用方法模板

后续新模块可直接复用以下模式（名称替换即可）：

- `FetchRemoteListAsync()`
- `RemoteAddAsync() / RemoteEditAsync() / RemoteDeleteAsync() / RemoteUpdateStatusAsync()`
- `ApplyFilters()`
- `ApplyPendingOpsSnapshotUnsafe()`
- `EnqueuePendingOperation()`
- `ReplayPendingOperationsAsync()`
- `ExecutePendingOperationAsync()`
- `LoadPendingOpsFromDisk() / SavePendingOpsToDiskUnsafe()`
- `LoadCacheFromDisk() / SaveCacheToDiskUnsafe()`
- `CloneEntity()`

建议抽一个通用基类（后续可做）：

- `OfflineSyncEntityServiceBase<TEntity, TPendingOp>`
  - 负责缓存、队列、回放、网络事件订阅
  - 业务子类只实现远端接口和过滤逻辑

---

## 7. 日志模板（强制建议）

每个模块建议统一日志前缀，便于检索。  
车辆管理示例前缀可复用为模块名替换：

- `[车辆同步]` 服务初始化
- `[车辆列表]` 查询链路
- `[车辆新增]` `[车辆修改]` `[车辆删除]` `[车辆状态]` 本地/远端操作
- `[车辆远端]` 实际 HTTP 请求与结果
- `[车辆入队]` 离线入队
- `[车辆回放]` 重连回放
- `[车辆重连]` 全量对齐
- `[车辆推送]` STOMP 信号处理
- `[车辆网络]` 网络状态变化

每条日志建议最少包含：
- 操作类型
- 业务主键
- 在线/离线状态
- 是否成功
- 失败原因（异常 message）
- 队列长度（适用时）

---

## 8. 新模块落地清单（开发步骤）

按以下顺序复制模板最稳：

1. 后端先准备 `anon` CRUD 接口（或授权接口）+ 统一返回结构。  
2. 后端在 CRUD 成功后广播 STOMP 变更信号。  
3. 桌面端新增 `EntityService`（先把在线 CRUD 跑通）。  
4. 增加本地缓存与 `pendingOps` 持久化。  
5. 加入网络状态监听与重连回放。  
6. 新增 `SyncCoordinator` 处理 STOMP -> 本地刷新。  
7. 全链路日志补齐。  
8. 按“联调测试矩阵”逐项验证。

---

## 9. 联调测试矩阵（建议）

每个模块至少跑完以下用例：

1. 在线新增 -> 后端可见。  
2. 在线编辑 -> 后端可见。  
3. 在线删除 -> 后端可见。  
4. 在线状态切换 -> 后端可见。  
5. 离线新增/编辑/删除 -> 本地立即可见。  
6. 重连后自动回放 -> 后端最终一致。  
7. 后端直接改数据 -> 桌面端自动刷新。  
8. 异常网络抖动 -> 不崩溃，回放可恢复。

---

## 10. 车辆管理对应实现参考（当前项目）

桌面端：
- `YY.Admin.Services/Service/Vehicle/VehicleService.cs`
- `YY.Admin.Services/Service/Vehicle/VehicleSyncCoordinator.cs`
- `YY.Admin.Core/Core/Services/IVehicleService.cs`

后端：
- `jeecg-module-xslmes/.../MesXslVehicleController.java`（业务接口 + 变更推送）
- `jeecg-module-device-sync/.../SyncController.java`（如启用统一回传通道）

基础设施：
- `YY.Admin/Infrastructure/Sync/OutboxProcessor.cs`
- `YY.Admin/Infrastructure/Network/NetworkMonitor.cs`
- `YY.Admin/Infrastructure/Hubs/StompWebSocketService.cs`

---

## 11. 推荐统一规范（后续团队约定）

1. 所有新模块都按“在线优先 + 离线入队 + 重连回放 + 全量对齐”实现。  
2. 所有模块都使用统一日志前缀和字段。  
3. 后端变更推送统一 `cmd` 命名：`{SYSTEM}_{ENTITY}_CHANGED`。  
4. 回传消息统一带 `messageId` 幂等键。  
5. 同步失败不阻塞主流程，但必须可观测（日志 + 队列长度）。  
6. 任意新模块上线前必须跑完“联调测试矩阵”。

---

> 结论：  
> 车辆管理已经提供了完整的可复制样板。后续新模块只需替换“实体、接口、过滤字段、命令字”，其余同步骨架可直接复用，从而快速实现稳定的桌面端/后端数据交互能力。