# 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 警告待处理 |