# WPF_FRAM

**Repository Path**: vs/wpf_-fram

## Basic Information

- **Project Name**: WPF_FRAM
- **Description**: 自用上位机框架
- **Primary Language**: C#
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 5
- **Created**: 2026-10-30
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 通用 WPF 框架

基于 **.NET 8 WPF** 的桌面上位机起始框架，提供可直接运行的主窗口、角色权限、系统设置、日志、Modbus TCP/RTU 和 Excel 导出示例，便于后续项目复用。

## 功能

- **主界面与导航**：默认最大化启动；顶部操作栏、可隐藏的两级侧栏导航；系统设置包含菜单栏设置和参数设置子菜单。
- **可视化监控**：提供设备总览、实时趋势、仪表盘、状态看板、数值大屏和柱状对比六种展示模式；可配置通用 Modbus 点位，或使用内置模拟数据预览。
- **角色权限**：内置操作员、管理员、超级管理员。未授权的导航入口和操作会隐藏；Modbus 写操作也会在服务层校验权限。
- **系统设置**：参数设置编辑 TCP/RTU 通信参数、日志和 Excel 保存目录及主题颜色；菜单栏设置编辑菜单名称、排序、显隐和侧栏显隐。
- **SQLite 菜单配置**：可新增、编辑、删除顶级菜单和子菜单，设置父级、图标、排序和显隐；数据库保存在项目根目录，页面路由仍从框架已注册页面中选择，权限由代码检查。
- **通用分页 CRUD 表格**：封装搜索、表格列、分页和新增/子项/编辑/删除操作入口；业务页面通过命令自行实现对应数据操作。
- **Modbus 主站**：封装 TCP 与串口 RTU 的连接、断开、线圈和寄存器读写接口。
- **日志**：Serilog 按天保存文本日志，同一天使用一个文件；默认写到应用输出目录的 `Logs` 文件夹，日志页每秒自动更新。
- **Excel 导出**：使用 ClosedXML 将对象集合导出为 `.xlsx`，附有示例数据页。
- **依赖注入**：容器统一创建共享服务；Modbus、日志、配置、用户会话和权限服务在应用内复用同一实例。

## 技术栈

| 组件 | 用途 |
| --- | --- |
| .NET 8 WPF | 桌面应用平台 |
| WPF-UI 4.3.0 | Fluent 风格控件和主题强调色 |
| LiveCharts2 2.0.4 | 实时趋势图和图表交互 |
| CommunityToolkit.Mvvm 8.4.2 | MVVM 属性通知和命令 |
| Microsoft.Extensions.DependencyInjection 8.0.1 | 服务与页面 ViewModel 的依赖注入和生命周期管理 |
| Microsoft.Data.Sqlite 8.0.32 | 本地导航菜单配置持久化 |
| NModbus / NModbus.Serial 3.0.83 | Modbus TCP 和串口 RTU |
| ClosedXML 0.105.1 | Excel 文件生成 |
| Serilog 4.4.0 | 日志记录 |
| Serilog.Sinks.File 7.0.0 | 日志文件输出 |

## 环境要求

- Windows 10 version 2004 (build 19041) or later
- .NET 8 SDK（包含 Windows Desktop 开发支持）
- Visual Studio 2022（可选，安装“.NET 桌面开发”工作负载）

## 构建和运行

在仓库根目录打开终端：

```powershell
dotnet restore wpf_-fram.sln
dotnet build wpf_-fram.sln
dotnet run --project wpf_-fram.csproj
```

也可以在 Visual Studio 中打开 `wpf_-fram.sln`，将 `wpf_-fram` 设为启动项目后运行。

## 默认账号与权限

| 账号 | 初始密码 | 权限 |
| --- | --- | --- |
| `operator` | 无需密码 | 查看业务示例和日志；连接、读取 Modbus；导出 Excel |
| `admin` | `CHANGE_ME_ADMIN` | 操作员权限，并可写 Modbus、进入系统设置 |
| `superadmin` | `123456` | 全部权限 |

管理员和超级管理员的占位密码定义在 `Config/users.json`。使用前请替换为自己的密码；分发应用前也应替换。账号 JSON 是本地示例方案，不适合作为生产环境的安全认证机制。

## 配置和数据文件

- `framework.settings.json`：首次运行时在应用程序目录生成，保存通信参数、日志目录、Excel 目录、主题颜色和侧栏整体显隐状态。
- `framework-menu.db`：SQLite 菜单数据库，开发运行时保存在 `.csproj` 项目文件所在目录，保存侧栏菜单层级、标题、排序和单项显隐设置；发布运行时若不包含 `.csproj`，则保存在应用程序目录。
- `Config/users.json`：固定账号及密码配置，构建时复制到输出目录。
- `Logs/framework-YYYYMMDD.txt`：默认日志文件；按日期滚动，同一天的实例共用当天文件。可在 `Config/FrameworkFeatures.cs` 中将 `LogFileExtension` 改为 `.log`。
- Excel 文件：默认保存到“文档”目录下的 `WpfFramework/Exports`，可在系统设置修改目录。

程序运行目录和配置目录需要允许应用写入。Modbus 真实通信需要可连接的 TCP 设备或串口设备。

## 项目结构

```text
Config/       固定用户和代码级功能开关
Models/       设置、通信参数和数据模型
Services/     JSON 配置、权限、日志、Modbus、Excel、主题和 SQLite 菜单服务
ViewModels/   页面状态和命令
Views/        主业务页、日志页、菜单栏设置页和参数设置页
docs/         使用说明、复用指南和实施计划
.agents/      面向 AI 助手的框架 Skill
```

## 在后续项目中复用

建议先复制起始工程，再替换 `HomeView` / `HomeViewModel` 中的示例业务内容。新增页面时，在 `Views` 和 `ViewModels` 创建对应文件，然后只需在 `Services/FrameworkPageRegistry.cs` 登记页面路由、名称、View、ViewModel 和权限要求。框架会自动完成 DI 注册、页面导航和菜单路由选项。可复用的基础服务通过接口调用，避免业务页面直接依赖 NModbus 或 ClosedXML 类型。

详细文档：

- [用户使用说明](docs/使用说明.md)
- [开发者指南：基于框架进行项目开发](docs/后续项目复用指南.md)
- [通用 WPF 框架实施计划](docs/通用WPF框架实施计划.md)
- [AI Skill：wpf-framework](.agents/skills/wpf-framework/SKILL.md)

## 调整框架选项

在 `Config/FrameworkFeatures.cs` 中配置代码级选项：

```csharp
public const bool EnableLeftMenu = true;
public const string LogFileExtension = ".txt";
```

`EnableLeftMenu` 控制是否启用左侧菜单；启用后，用户可在界面中切换菜单显隐。日志扩展名支持 `.txt` 或 `.log`。