# 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。

## 常用命令

```bash
# 还原依赖
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<string, string>，key 为 PlcConfig 中的标签名）

## 日志

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