CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

YZWater3 是扬州旭轩科技有限公司开发的跨平台污水处理厂监控系统，基于 Avalonia UI 12 + .NET 8，支持 Windows/Linux/macOS。

常用命令

# 还原依赖
dotnet restore

# 构建
dotnet build

# 运行（默认从 src/YZWater.Avalonia 启动）
dotnet run --project src/YZWater.Avalonia

# 发布单文件（Windows）
dotnet publish src/YZWater.Avalonia -c Release -r win-x64 --self-contained -p:PublishSingleFile=true

项目结构

两个项目，Avalonia 依赖 Core：

YZWater3.sln
src/
├── YZWater.Core/           # 核心业务逻辑（UI 无关）
│   ├── Models/             # 数据模型（SqlSugar ORM）
│   ├── Services/           # 所有业务服务（单例模式为主）
│   ├── ViewModels/         # CommunityToolkit.Mvvm ViewModel
│   └── Utils/              # WinSize、ResolutionManager
│
└── YZWater.Avalonia/       # UI 层
    ├── Views/              # AXAML 视图（ViewA~ViewF + Login + Main）
    ├── Controls/           # 自定义工业控件 + ThemeHelper
    ├── Themes/             # IndustrialTheme / IndustrialThemeLight / IndustrialStyles
    ├── Converters/
    └── Services/

关键架构

运行模式（通过 `yzwater-config.json` → `RunMode` 配置）

模式	行为
`Direct`	直连 PLC（默认）
`Server`	连 PLC + 启动 WebSocket 服务端（HubServer，端口 8765）
`Client`	连接 WebSocket 服务端接收数据，不直连 PLC
`Mock`	无 PLC 时使用 MockPlcService 生成模拟数据

服务层（YZWater.Core/Services）

单例服务（需 ResetInstance() 后重建，用于登出/重登录）：PlcPollingService、AlarmService
静态服务：PlcService（HslCommunication 西门子 S7）、ConfigService（JSON 配置）、DatabaseService（SqlSugar + SQLite）、AuthService、MockPlcService
HubServer / HubClient：WebSocket 中控通信，支持操作锁、远程命令（start_pump/stop_pump）
PlcConfig：所有 PLC 地址映射集中管理，支持配置文件覆盖

启动流程（App.axaml.cs）

LogService.Initialize() → DatabaseService.Initialize() → 加载主题/语言/PLC配置
  → ShowLoginWindow → [登录成功] → StartServices() → ShowMainWindow()

StartServices() 根据 RunMode 选择 Direct/Server/Client，均会调用 StartPlcServices() 启动 PlcPolling + Alarm + DataLogging。

主题系统

双主题通过 ResourceInclude 切换 Application.Resources.MergedDictionaries：

Themes/IndustrialTheme.axaml（深色）
Themes/IndustrialThemeLight.axaml（浅色）

自定义控件不用 DynamicResource，而是订阅 ThemeHelper.ThemeChanged 事件后调用 InvalidateVisual() 重绘。ThemeHelper 内部用静态 IBrush 属性缓存当前主题颜色，供 Render() 方法直接读取。

自定义工业控件（YZWater.Avalonia/Controls）

全部继承 Control 并重写 Render(DrawingContext)，使用 AffectsRender<> 声明触发重绘的属性：

WaterTankControl - 水箱液位
PumpControl - 泵（带旋转动画，OnAttachedToVisualTree 启动 DispatcherTimer）
FanControl - 风扇（同上）
PipeLineControl - 管道（虚线流动动画）
ValveControl - 阀门（三态）
GaugeControl - 仪表
StatusCard - 状态卡片

MVVM 约定

ViewModel 继承 ObservableObject，使用 [ObservableProperty] 和 [RelayCommand]（CommunityToolkit.Mvvm 源生成器）
View 和 ViewModel 在 App.axaml.cs 或 MainViewModel 中通过 DataContext 绑定
MainViewModel 持有所有子 ViewModel 实例，通过 CurrentView 属性切换 Tab

数据库

ORM：SqlSugar（不是 README 中提到的 FreeSql，已迁移）
文件：yzwater.db（SQLite）
初始化：DatabaseService.Initialize() 中逐个建表，单表失败不影响其他表
表：users, alarm_records, flow_records, analog_records, audit_logs, persons, equipment_statuses

认证

AuthService 管理登录状态，支持 4 种角色（Viewer / Operator / Engineer / Admin）。首次启动自动创建默认 admin 账户（admin/admin123）。登出时通过 UserLoggedOut 事件触发 StopServices() 并重新显示登录窗口。

自适应布局

AdaptiveContainer 控件实现等比缩放，设计基准 1280×800，缩放范围 0.6x–1.5x。

配置文件

yzwater-config.json（根目录，被 .gitignore 排除）：

PLC 连接：PlcIp, PlcPort, AutoConnect
报警阈值：LevelHighAlarm, LevelLowAlarm, FlowHighAlarm, FlowLowAlarm
中控：RunMode, HubPort, HubServerUrl, HubToken
主题/语言：IsDarkTheme, IsChinese
PLC 地址覆盖：PlcAddresses（Dictionary，key 为 PlcConfig 中的标签名）

日志

Serilog 输出到 Logs/log-{date}.txt（按天滚动）和控制台。崩溃日志写入根目录 crash.log。

CLAUDE.md 5.1 KB 文件历史 原始文件