YZWater3/docs/AutoFMA借鉴实施计划.md

AutoFMA 借鉴实施计划

项目背景

基于对 AutoFMA（自动光学量测机上位机）项目的分析，提取可借鉴的架构设计和实现模式，应用到 YZWater3（污水处理厂监控系统）中，提升系统的健壮性、可维护性和性能。

借鉴点清单

序号	功能	来源	优先级	状态
1	数据库在线备份增强	DatabaseBackupService	P0	✅
2	数据保留清理服务	DataRetentionService	P0	✅
3	配置服务热加载	ConfigService	P1	✅
4	审计日志 Channel 异步写入	AuditService	P1	✅
5	日志缓冲服务	LogBufferService	P2	✅
6	表驱动状态机	SessionStateMachine	P1	⏭️ 跳过（Stateless 已覆盖）
7	连接状态集中管理	ConnectionStatusService	P2	✅
8	用户锁定持久化	UserService	P3	✅
9	报警历史 Channel 写入	AlarmMonitorService	P3	✅
10	在线升级委托注入	UpdateService	P3	✅

第二批实施说明

6. 表驱动状态机 — 跳过

YZWater3 已使用 Stateless 库实现 DeviceStateMachine（Configure().Permit() 即转移表）。 AutoFMA 的 SessionStateMachine 是为"扫码→驱动→测量→MES"多阶段会话定制，YZWater3 无对应业务流程，不重复引入。

7. 连接状态集中管理

• PlcService/HubServer/HubClient 添加状态变更事件
• 新增 ConnectionStatusService 单例：订阅各服务事件，统一存储，提供显示文本 + 状态变更通知

8. 用户锁定持久化

• User 模型新增 FailedLoginAttempts/LockoutUntil 字段
• AuthService 锁定逻辑从内存字典改为数据库持久化（重启不丢失）

9. 报警历史 Channel 写入

• AlarmService 两处直接 Insertable 改为 Channel<AlarmRecord> 后台串行写入
• 退出时 flush（复用 AuditService 模式）

10. 在线升级委托注入

• 新增 UpdateService（Core 层）：版本管理 + SetTriggerAction 委托注入
• UI 层实际更新逻辑后续接入（Avalonia 无 AutoUpdater.NET 官方支持，先搭架子）

---

P0 - 数据安全与维护

1. 数据库在线备份增强

当前实现: BackupService.cs - 简单的 VACUUM INTO 备份

借鉴来源: AutoFMA.Core/Services/DatabaseBackupService.cs

改进内容:

• ✅ WAL checkpoint (TRUNCATE) - 合并未落盘数据
• ✅ 临时文件写入 → 验证 → 原子替换（避免备份失败时损坏旧备份）
• ✅ Interlocked.CompareExchange 防重入
• ✅ 定时备份（每 24 小时）
• ✅ 启动时自动备份

实施文件:

• src/YZWater.Core/Services/BackupService.cs - 增强现有实现

---

2. 数据保留清理服务

当前实现: 无

借鉴来源: AutoFMA.Core/Services/DataRetentionService.cs

新增内容:

• ✅ 启动时立即清理一次 + 每 24 小时定时清理
• ✅ 支持多表独立配置保留天数
• ✅ Interlocked 防重入
• ✅ 配置化保留天数

清理范围:

• alarm_records - 报警记录（默认 90 天）
• flow_records - 流量记录（默认 360 天）
• analog_records - 模拟量记录（默认 360 天）
• audit_logs - 审计日志（默认 365 天）

实施文件:

• src/YZWater.Core/Services/DataRetentionService.cs - 新增
• src/YZWater.Core/Models/SystemConfig.cs - 新增保留天数配置

---

P1 - 架构升级

3. 配置服务热加载

当前实现: ConfigService.cs - 手动加载/保存

借鉴来源: AutoFMA.Core/Services/ConfigService.cs

改进内容:

• ✅ FileSystemWatcher 监听配置文件变更
• ✅ _isSaving 标记避免自己触发的变更
• ✅ 原子写入（临时文件 → 覆盖）
• ✅ SemaphoreSlim 读写互斥
• ✅ ConfigChanged 事件通知
• ✅ 权限校验（Engineer 以上才可修改）

实施文件:

• src/YZWater.Core/Services/ConfigService.cs - 增强现有实现

---

4. 审计日志 Channel 异步写入

当前实现: AuditService.cs - 直接写入数据库

借鉴来源: AutoFMA.Core/Services/AuditService.cs

改进内容:

• ✅ Channel<AuditLog> 有界队列（防密集写入时线程池打满）
• ✅ 后台单线程串行写入数据库
• ✅ 退出时 flush（_writerTask.Wait(5s)）
• ✅ FullMode = DropOldest 防止队列满时阻塞

实施文件:

• src/YZWater.Core/Services/AuditService.cs - 重构为实例类

---

P2 - 性能优化

5. 日志缓冲服务

当前实现: 无（各 ViewModel 各自订阅日志）

借鉴来源: AutoFMA.Core/Services/LogBufferService.cs

新增内容:

• ✅ 统一订阅 LogService，维护单一缓冲区
• ✅ Dashboard 和 LogViewer 共用此缓冲
• ✅ 超过阈值（TrimThreshold）再裁剪，减少 O(N) 移动频率
• ✅ LogAdded 事件通知

实施文件:

• src/YZWater.Core/Services/LogBufferService.cs - 新增

---

实施顺序

Phase 1 (P0 - 数据安全) ✅ 已完成
├── 1.1 增强 BackupService ✅
└── 1.2 新增 DataRetentionService ✅

Phase 2 (P1 - 架构升级) ✅ 已完成
├── 2.1 增强 ConfigService ✅
└── 2.2 重构 AuditService ✅

Phase 3 (P2 - 性能优化) ✅ 已完成
└── 3.1 新增 LogBufferService ✅

实施完成日期

2026-09-06

---

配置项扩展

在 SystemConfig 中新增以下配置：

// 数据保留配置
public DataRetentionConfig DataRetention { get; set; } = new();

public class DataRetentionConfig
{
    /// <summary>报警记录保留天数（默认 90 天）</summary>
    public int AlarmRecordRetentionDays { get; set; } = 90;

    /// <summary>流量记录保留天数（默认 360 天）</summary>
    public int FlowRecordRetentionDays { get; set; } = 360;

    /// <summary>模拟量记录保留天数（默认 360 天）</summary>
    public int AnalogRecordRetentionDays { get; set; } = 360;

    /// <summary>审计日志保留天数（默认 365 天）</summary>
    public int AuditLogRetentionDays { get; set; } = 365;
}

// 备份配置
public BackupConfig Backup { get; set; } = new();

public class BackupConfig
{
    /// <summary>是否启用定时备份</summary>
    public bool EnableScheduledBackup { get; set; } = true;

    /// <summary>定时备份间隔（小时，默认 24 小时）</summary>
    public int BackupIntervalHours { get; set; } = 24;

    /// <summary>保留备份数量（默认 7 个）</summary>
    public int KeepBackupCount { get; set; } = 7;
}

---

测试验证

每个功能实施后需验证：

1. BackupService 增强

   • 启动时自动备份
   • 定时备份正常触发
   • 备份失败时不损坏旧备份
   • 并发调用时防重入正常

2. DataRetentionService

   • 启动时立即清理
   • 定时清理正常触发
   • 各表独立保留天数
   • 并发调用时防重入正常

3. ConfigService 热加载

   • 外部修改配置文件后自动加载
   • 保存时原子写入
   • 自己触发的变更不重复加载
   • ConfigChanged 事件正常触发

4. AuditService Channel 写入

   • 高并发写入时不阻塞主线程
   • 退出时数据不丢失
   • 队列满时丢弃旧数据

5. LogBufferService

   • Dashboard 和 LogViewer 共享缓冲
   • 超过阈值自动裁剪
   • LogAdded 事件正常触发

---

注意事项

1. 向后兼容: 所有改进保持现有 API 兼容，现有代码无需修改即可运行
2. 配置可选: 新增配置项都有默认值，无需修改配置文件即可使用
3. 日志规范: 使用 Serilog 记录日志，保持与现有代码一致
4. 异常处理: 所有新功能都有完善的异常处理，不影响主流程

---

参考资料

• AutoFMA 项目: E:\设备\自动光学量测机\AutoFMA
• YZWater3 项目: E:\Source\YZWater3
• SQLite WAL 模式: https://www.sqlite.org/wal.html
• System.Threading.Channels: https://learn.microsoft.com/zh-cn/dotnet/api/system.threading.channels