SharpSCADA.Data.Controller 项目功能参考文档

本文档详细总结了 SharpSCADA.Data.Controller 库的功能、架构设计及核心 API 使用方法。该库主要作为 SCADA/HMI 系统的业务逻辑核心，封装了数据库访问、用户权限、审计追踪、配方管理及多语言支持等功能。

1. 项目概览

• 命名空间: Data.Controller
• 用途: 工业自动化系统的业务逻辑层 (BLL)。
• 核心依赖:
  • SqlSugar: 用于所有数据库交互 (ORM)。
  • SharpSCADA.Core / Common: 基础模型定义。
  • PropertyChanged.Fody: 实现 MVVM 数据绑定通知。

2. 核心模块与功能

2.1 全局系统管理 (SystemData)

这是库的静态入口点，负责初始化环境、维护数据库连接及缓存全局状态。

• 数据库初始化
  • Init(string dbtype, string connstr, ILogger logger): 启动系统。支持 sqlite, mysql, mssql。会自动执行 CodeFirst 初始化表结构。
  • 表结构: UserModel, AuditTrailModel, RecipeOverviewModel, ParaItemData, DictionaryModel 等。
• 数据访问
  • Db: 全局静态 SqlSugarScope 对象。外部代码应通过此属性进行复杂的 LINQ 查询或事务处理。
• 配置管理 (KV存储)
  • LoadConfig<T>(): 将数据库 ParaItemData 表中的键值对加载为强类型对象（如 DataConfig）。
  • Save<T>(T data): 将对象属性保存回数据库配置表。
• 运行时状态
  • CurrentUser: 当前登录的 User 对象。
  • Recipes: 缓存的配方列表。
  • Trends: 缓存的趋势组配置。

2.2 用户与权限系统 (MemberShip & User)

提供完整的基于角色的访问控制 (RBAC) 和账户安全策略。

• 认证
  • Authenticate(string name, string password): 用户登录验证。
  • 安全特性: 支持 MD5 加密、连续输错锁定账户、密码过期强制修改、首次登录改密。
• 权限检查
  • User.IsInRole(RoleType role): 检查当前用户是否拥有特定权限（基于位运算）。
• 账户管理
  • CreateUser(User user): 新建用户。
  • CommitPassword(string user, string password): 修改密码（含历史密码查重）。
  • EnableUser(...) / DeleteUser(...): 账户生命周期管理。
  • UpdateRole(...): 动态调整用户权限。

2.3 审计追踪 / 电子签名 (AuditTrail)

满足工业合规性（如 FDA 21 CFR Part 11）的关键操作记录系统。

• 日志记录
  • Save(string type, string command): 记录一条操作日志。系统自动捕获：操作人、机器名 (Node)、时间 (Local/UTC)、旧值/新值。
• 日志查询
  • GetAuditTrails(DateTime start, DateTime end, ...): 查询历史审计记录。
• 数据结构: 包含 Class (类别), Event (事件), Comment (备注), BatchNumber (批次号) 等字段。

2.4 配方管理 (Recipe)

用于管理生产参数集合，支持版本控制。

• 版本机制: 采用 Mainversion (主版本) + Underversion (修订号) 结构。标识为 "A" 的修订号代表当前激活/可用版本。
• 操作
  • Create(...): 创建新配方。
  • Save(...): 保存配方。如果修改了已激活配方，系统会自动递增版本号。
  • Delete(...): 删除配方头信息及关联的参数值表。
• 查询
  • GetActiveRecipes(string recType): 获取指定类型下所有处于激活状态的最新版本配方。

2.5 多语言翻译 (Translation)

基于数据库字典的动态翻译引擎。

• 核心属性: Translation.Current (枚举 Region：EN, ZT, DE, RU, JP)。设置此属性会重新加载内存字典。
• API:
  • string.Translate(): 扩展方法，将 Key 转换为当前语言的 Value。
  • 分段翻译: 支持 @ 分隔符。例如 "Error@NoConnect".Translate() 会分别查找 "Error" 和 "NoConnect" 的翻译并拼接。

2.6 系统工具 (WinAPI)

封装底层 Windows API 操作。

• Shutdown(): 强制关机。
• AdjustTime(DateTime t): 修改系统本地时间。
• GetLastInputTime(): 获取系统空闲时间（毫秒），常用于检测用户超时自动注销。

3. 代码集成模式 (Usage Patterns)

3.1 系统启动

// 在 App.xaml.cs 或 Program.cs 中
public async Task StartUp() {
    string connStr = "Data Source=hmi.db";
    // 初始化数据库连接和表结构
    await SystemData.Init("sqlite", connStr, new LoggerFactory().CreateLogger("App"));
}

3.2 用户登录与权限判断

// 登录
var user = await MemberShip.Authenticate("admin", "123456");
if (user.Error == null) {
    SystemData.CurrentUser = user; // 必须赋值给全局上下文
    Console.WriteLine($"用户 {user.UName} 登录成功");
}

// 权限判断
if (SystemData.CurrentUser.IsInRole(RoleType.工程师)) {
    // 允许执行敏感操作
}

3.3 记录关键操作 (审计)

// 记录修改参数的操作
var audit = new AuditTrail {
    Comment = "修改PID参数",
    WWVariable = "PID_SetPoint",
    ValueOld = "50.0",
    ValueNew = "55.0"
};
// 自动保存到数据库
await audit.Save("Parameter", "Update");

3.4 数据库自定义查询 (使用 SqlSugar)

由于 SystemData.Db 暴露了 SqlSugarScope，可以直接使用 ORM 功能：

// 查询最近10条错误日志
var logs = await SystemData.Db.Queryable<AuditTrailModel>()
    .Where(x => x.Class == "Error")
    .OrderBy(x => x.EvtDateTimeLoc, OrderByType.Desc)
    .Take(10)
    .ToListAsync();

3.5 读取和保存配置

// 自定义配置类
public class MySettings {
    public int RefreshRate { get; set; } = 1000;
}

// 加载
var settings = await SystemData.LoadConfig<MySettings>();

// 保存
settings.RefreshRate = 2000;
SystemData.Save(settings);