YZWater3/docs/improvement-report-20260901.md

YZWater3 项目改进报告

日期：2026-09-01 执行人：自动化定时任务

---

改进概览

序号	改进项	状态	影响文件
#1	更新 README.md 过时版本号和功能描述	✅ 完成	README.md
#2	创建 yzwater-config.template.json 配置模板	✅ 完成	yzwater-config.template.json, docs/config-reference.md
#3	修复 ViewEViewModel 过时信息和占位方法	✅ 完成	src/YZWater.Core/ViewModels/ViewEViewModel.cs
#4	修复 Converter ConvertBack 方法	✅ 完成	src/YZWater.Avalonia/Converters/BoolToBrushConverter.cs
#5	修复空 catch 块添加注释说明	✅ 完成	HubServer.cs, HubClient.cs
#6	修复 ViewF DataGrid 列标题国际化	✅ 完成	src/YZWater.Avalonia/Views/ViewFView.axaml
#7	消除 SystemConfig/ConfigService 重复默认值	✅ 完成	src/YZWater.Core/Services/ConfigService.cs
#8	AuthService 添加登录失败锁定机制	✅ 完成	AuthService.cs, LanguageService.cs
#9	补充核心服务单元测试	✅ 完成	tests/YZWater.Core.Tests/Services/AuthPasswordTests.cs, tests/YZWater.Core.Tests/Models/SystemConfigTests.cs
#10	清理 .buildcheck-* 残留目录	✅ 完成	删除 9 个目录

---

详细改进记录

#1 README 更新

发现的问题：

• 版本号过时：Avalonia 11→12, FreeSql→SqlSugar, Semi.Avalonia 11→12 等
• 缺少新增功能描述：LoginView、ViewF 审计日志、ProjectView、Hub 模式、MockPlc
• 数据库表列表不完整

修改内容：

• 更新技术栈表格所有版本号为实际值
• 补充完整的 Views/ViewModels/Services/Models 目录结构
• 新增登录认证、运行模式、审计日志、项目管理功能描述
• 更新数据库表列表为 users/alarm_records/flow_records/analog_records/equipment_statuses/audit_logs/persons
• 更新依赖包版本列表
• 补充配置文件字段（RunMode、HubPort、HubServerUrl、HubToken 等）
• 更新版权年份至 2024-2026

#2 配置模板

发现的问题：

• yzwater-config.json 被 gitignore 排除，新部署人员不知道有哪些配置字段
• 无配置文档说明

修改内容：

• 创建 yzwater-config.template.json，包含所有字段和默认值
• 创建 docs/config-reference.md，详细说明每个字段的类型、默认值、用途
• 包含默认账户信息和安全提示

#3 ViewEViewModel 修复

发现的问题：

• TechStack 属性显示 "Avalonia UI 11 | .NET 8 | FreeSql | HslCommunication"，实际已迁移到 Avalonia 12 + SqlSugar
• OpenWebsite() 方法为空
• CheckUpdateAsync() 仅 await Task.Delay(1000)，假功能

修改内容：

• 更新 TechStack 为 "Avalonia UI 12 | .NET 8 | SqlSugar | HslCommunication"
• 实现 OpenWebsite() 使用 Process.Start 打开公司官网
• 实现 CheckUpdateAsync() 调用 OpenWebsite()

#4 Converter ConvertBack 修复

发现的问题：

• BoolToBrushConverter、AlarmToBrushConverter、DeviceStatusToBrushConverter 的 ConvertBack 抛出 NotImplementedException
• 虽然当前仅用于单向绑定，但异常可能在不期望时触发

修改内容：

• 三个 ConvertBack 均改为 return value;（返回原值，不抛异常）
• 添加注释说明仅支持单向绑定

#5 空 catch 块修复

发现的问题：

• HubServer.cs:109、HubClient.cs:83、HubClient.cs:374 有 3 处 catch { } 完全静默

修改内容：

• 均添加注释 /* 正在关闭/断开清理中，忽略关闭异常 */ 说明忽略原因

#6 ViewF 国际化修复

发现的问题：

• ViewFView.axaml 中 DataGrid 列标题硬编码为英文 "Time"/"User"/"Action"/"Detail"/"Target"/"Result"
• ViewModel 中已有对应的国际化属性 TimeHeaderText/UserHeaderText 等

修改内容：

• 将 6 个 Header="..." 改为 Header="{Binding ...HeaderText}"
• 确认 LanguageService 中所有 key 的中英文翻译均存在

#7 DRY 消除重复默认值

发现的问题：

• ConfigService.LoadConfig() 创建默认配置时硬编码了 6 个默认值
• 这些默认值与 SystemConfig 字段初始化器重复

修改内容：

• ConfigService.LoadConfig() 中改为 new SystemConfig()，默认值由模型自身提供

#8 登录失败锁定

发现的问题：

• AuthService 无登录失败次数限制，存在暴力破解风险

修改内容：

• 添加内存级失败计数器 _loginAttempts（Dictionary<string, (Count, Time)>）
• 连续失败 5 次后锁定 15 分钟
• 锁定期满自动解锁
• 登录成功后清除失败记录
• 添加 AccountLocked 国际化 key（中/英文）
• 所有失败路径（用户不存在/账户禁用/密码错误）均记录失败次数

#9 单元测试补充

发现的问题：

• 测试覆盖率 <5%，仅 16 个测试，覆盖 HubMessage/User/WinSize
• 所有核心服务无测试

修改内容：

• 新增 AuthPasswordTests.cs：9 个测试（哈希格式/唯一性/正确密码/错误密码/null/空/无效格式/空密码/中文密码）
• 新增 SystemConfigTests.cs：8 个测试（PLC 默认值/字符串默认值/Hub 默认值/UI 默认值/地址字典/轮询间隔）
• 测试总数从 16 增加到 33

#10 残留目录清理

发现的问题：

• 根目录下 9 个 .buildcheck-* 调试残留目录

修改内容：

• 删除全部 9 个目录：.buildcheck, .buildcheck-3d-layout, .buildcheck-3d-refine, .buildcheck-exit, .buildcheck-layout, .buildcheck-pumpstation, .buildcheck-shutdown, .buildcheck-solid-3d, .buildcheck-ui

---

编译验证

每个任务完成后均执行 dotnet build，全部 0 个错误。

dotnet build → 0 个错误，156 个警告（均为已有的 nullable 警告）
dotnet test  → 33 个测试全部通过

---

仍待改进（未在本次执行中处理）

项目	优先级	说明
CI/CD 流水线	P1	添加 GitHub Actions 自动构建+测试
RunMode 改为枚举	P2	当前字符串比较无编译期检查
测试覆盖 AlarmService/ConfigService	P2	需要 mock 数据库依赖
ViewE OpenWebsite URL	P3	当前硬编码公司网址，应从配置读取
登录失败锁定持久化	P3	当前为内存级，重启后清零
Hub WebSocket TLS	P3	LAN 部署可接受，WAN 部署需加密
编译警告清理	P3	156 个 nullable 警告待处理