dyp/框架使用文档.md

# Delphi 代码框架文档

## 概述

本文档描述了为 MES 客户端应用创建的代码框架，包括配置管理、业务服务、异常处理、日志管理和单元测试等模块。

---

## 1. 配置管理框架 (uConfigManager.pas)

### 1.1 主要组件

| 组件 | 说明 |
|-----|------|
| `TConfigManager` | 通用配置管理器，支持INI和JSON格式 |
| `TAppConfig` | 应用配置单例，提供预定义的配置项 |

### 1.2 TConfigManager 核心方法

```pascal
// 读取配置
function GetString(const Section, Key, Default: string): string;
function GetInteger(const Section, Key: string; Default: Integer): Integer;
function GetBoolean(const Section, Key: string; Default: Boolean): Boolean;
function GetFloat(const Section, Key: string; Default: Double): Double;

// 写入配置
procedure SetString(const Section, Key, Value: string);
procedure SetInteger(const Section, Key: string; Value: Integer);
procedure SetBoolean(const Section, Key: string; Value: Boolean);
procedure SetFloat(const Section, Key: string; Value: Double);
```

### 1.3 TAppConfig 预定义配置

```pascal
// 网络配置
Config.GetServerURL: string;       // 服务器地址
Config.GetServerPort: Integer;      // 服务器端口
Config.GetTimeout: Integer;         // 超时时间(ms)
Config.GetRetryCount: Integer;      // 重试次数
Config.GetCORSOrigin: string;      // CORS允许源
Config.GetAPIPath: string;         // API路径
Config.GetAdminAPIPath: string;    // 管理API路径

// 设备配置
Config.GetPLCHost: string;         // PLC主机地址
Config.GetPLCPort: Integer;        // PLC端口
Config.GetSerialPort: string;      // 串口号
Config.GetBaudRate: Integer;       // 波特率

// 文件服务器配置
Config.GetFileServerPath: string;   // 文件服务器路径
Config.GetBackupServerPath: string; // 备份服务器路径

// 数据同步配置
Config.GetSyncInterval: Integer;    // 同步间隔(ms)
Config.GetMaxRetryCount: Integer;  // 最大重试次数

// 日志配置
Config.GetLogFileDir: string;       // 日志文件目录
Config.GetLogFileMaxSize: Integer; // 日志文件最大大小(bytes)
Config.GetLogLevel: Integer;       // 日志级别(0-5)
```

### 1.4 使用示例

```pascal
// 读取配置
ServerURL := Config.GetServerURL;
Timeout := Config.GetTimeout;

// 修改配置
Config.System.SetString('Network', 'ServerURL', 'http://new-server:8080');
Config.Save; // 保存配置
```

---

## 2. 业务服务框架 (uBusinessServices.pas)

### 2.1 服务工厂

```pascal
class function TBusinessServiceFactory.GetAuthService(): TAuthService;
class function TBusinessServiceFactory.GetWorkOrderService(const Token: string): TWorkOrderService;
class function TBusinessServiceFactory.GetDeviceService(): TDeviceService;
class function TBusinessServiceFactory.GetSyncService(const Token: string): TSyncService;
class function TBusinessServiceFactory.GetDeviceConfigService(): TDeviceConfigService;
class function TBusinessServiceFactory.GetProductionReportingService(const Token: string): TProductionReportingService;
class function TBusinessServiceFactory.GetDataAccessService(): TDataAccessService;
```

### 2.2 认证服务 (TAuthService)

```pascal
// 登录
function Login(const UserID, Password: string): TAuthResult;

// 注销
function Logout(const Token: string): Boolean;

// 刷新令牌
function RefreshToken(const Token: string): string;

// 验证令牌
function ValidateToken(const Token: string): Boolean;
```

### 2.3 工单服务 (TWorkOrderService)

```pascal
// 获取工单列表
function GetWorkOrderList(const Status: string = ''): TArray<TWorkOrderInfo>;

// 获取工单详情
function GetWorkOrderDetail(const OrderID: string): TWorkOrderInfo;

// 获取工单工序
function GetWorkOrderEntries(const OrderID: string): TArray<TWorkOrderEntry>;

// 创建工单
function CreateWorkOrder(const OrderInfo: TWorkOrderInfo): string;

// 更新工单状态
function UpdateWorkOrderStatus(const OrderID, Status: string): Boolean;

// 生产报工
function ReportProduction(const OrderID, ProcessID, Quantity: string): Boolean;
```

### 2.4 设备服务 (TDeviceService)

```pascal
// 获取设备状态
function GetDeviceStatus(const DeviceID: string): TDeviceStatus;

// 获取所有设备
function GetAllDevices(): TArray<TDeviceStatus>;

// 连接设备
function ConnectDevice(const DeviceID: string): Boolean;

// 断开设备
function DisconnectDevice(const DeviceID: string): Boolean;

// 发送命令
function SendCommand(const DeviceID, Command: string): string;
```

### 2.5 同步服务 (TSyncService)

```pascal
// 同步数据
function SyncData(const Data: TJSONObject): Boolean;

// 批量同步
function SyncBatchData(const DataArray: TJSONArray): Boolean;

// 获取同步状态
function GetSyncStatus(): TJSONObject;

// 重试失败同步
function RetryFailedSyncs(): Integer;
```

### 2.6 设备配置服务 (TDeviceConfigService)

```pascal
// 加载设备配置
function LoadDeviceConfig(): Boolean;

// 保存设备配置
function SaveDeviceConfig(): Boolean;

// 验证配置
function ValidateConfig(): TValidationResult;

// 获取服务器URL
function GetServerURL(): string;

// 获取工厂代码
function GetFactoryCode(): string;

// 获取生产线
function GetProductionLine(): string;

// 获取操作工位
function GetOperatorStation(): string;
```

### 2.7 生产报工服务 (TProductionReportingService)

```pascal
// 报工
function ReportProduction(const OrderID, ProcessID, Quantity, LotNo: string): Boolean;

// 报不良
function ReportDefective(const OrderID, ProcessID, DefectType, Quantity: string): Boolean;

// 查询生产状态
function QueryProductionStatus(const OrderID: string): TJSONObject;

// 验证用户
function ValidateUser(const UserID: string): Boolean;

// 获取工单信息
function GetWorkOrderInfo(const LotNo: string): TJSONObject;

// 获取工序列表
function GetProcessList(const LotNo: string): TJSONArray;

// 验证二维码
function ValidateGoodsNo(const ItemCode, ProcessCode, WorkOrderNumber: string): Boolean;

// 提交生产数据
function SubmitProductionData(const UserID, LotNo, ProcessID, GoodsNo: string): Boolean;
```

### 2.8 数据访问服务 (TDataAccessService)

```pascal
// 读取配置值
function ReadConfigValue(const ASection, AKey: string; const ADefault: string = ''): string;

// 写入配置值
procedure WriteConfigValue(const ASection, AKey, AValue: string);

// 读取设备信息
function ReadDeviceInfo(const AKey: string): string;

// 读取生产参数
function ReadProductionParams(const AKey: string): string;

// 读取报警配置
function ReadAlarmConfig(const AKey: string): string;
```

---

## 3. 异常处理框架 (uExceptionHandler.pas)

### 3.1 异常类型层次

```
EBaseException
├── ENetworkException    (网络错误)
├── EDataException       (数据错误)
├── EBusinessException   (业务错误)
├── EDeviceException     (设备错误)
└── EValidationException (验证错误)
```

### 3.2 EBaseException 属性

```pascal
property ErrorCode: Integer;     // 错误码
property ErrorType: string;      // 错误类型
property Cause: string;         // 错误原因
property Context: TStrings;      // 错误上下文
property Timestamp: TDateTime;   // 时间戳
```

### 3.3 快捷抛出函数

```pascal
procedure RaiseNetworkException(const AMsg: string; AErrorCode: Integer = 0);
procedure RaiseDataException(const AMsg: string; AErrorCode: Integer = 0);
procedure RaiseBusinessException(const AMsg: string; AErrorCode: Integer = 0);
procedure RaiseDeviceException(const AMsg: string; AErrorCode: Integer = 0);
procedure RaiseValidationException(const AFieldName, AFieldValue, AMsg: string);
```

### 3.4 使用示例

```pascal
// 抛出特定类型异常
RaiseNetworkException('连接失败: %s', [E.Message], 1001);
RaiseBusinessException('工单不存在', 2001);

// 全局异常处理
TExceptionHandler.Instance.HandleException(E);
```

---

## 4. 日志管理框架 (uLogManager.pas)

### 4.1 日志级别

| 级别 | 值 | 说明 |
|-----|---|------|
| `llTrace` | 0 | 跟踪信息 |
| `llDebug` | 1 | 调试信息 |
| `llInfo` | 2 | 一般信息 |
| `llWarn` | 3 | 警告信息 |
| `llError` | 4 | 错误信息 |
| `llFatal` | 5 | 致命错误 |

### 4.2 日志分类

| 分类 | 说明 |
|-----|------|
| `lcSystem` | 系统日志 |
| `lcNetwork` | 网络日志 |
| `lcDatabase` | 数据库日志 |
| `lcBusiness` | 业务日志 |
| `lcDevice` | 设备日志 |
| `lcUI` | 界面日志 |
| `lcSecurity` | 安全日志 |
| `lcPerformance` | 性能日志 |

### 4.3 日志方法

```pascal
// 基础日志
procedure Log(Level: TLogLevel; Category: TLogCategory; const Message: string; const Args: array of const);

// 分级日志
procedure Trace(const Message: string; const Args: array of const = []);
procedure Debug(const Message: string; const Args: array of const = []);
procedure Info(const Message: string; const Args: array of const = []);
procedure Warn(const Message: string; const Args: array of const = []);
procedure Error(const Message: string; const Args: array of const = []);
procedure Fatal(const Message: string; const Args: array of const = []);

// 分类日志
procedure InfoCategory(Category: TLogCategory; const Message: string; const Args: array of const = []);
procedure ErrorCategory(Category: TLogCategory; const Message: string; const Args: array of const = []);
```

### 4.4 性能日志

```pascal
// 方式1: 使用TPerformanceLogger
var Logger := TPerformanceLogger.Create('数据查询');
try
  // 执行操作
finally
  Logger.Free;
end;

// 方式2: 使用静态方法
TPerformanceLogger.Measure<T>(
  '数据查询',
  function: T begin
    // 执行操作
    Result := ...;
  end,
  'Tag信息'
);
```

### 4.5 使用示例

```pascal
// 记录日志
LogManager.InfoCategory(lcNetwork, '连接成功: %s', ['192.168.1.100']);
LogManager.ErrorCategory(lcDevice, 'PLC通信失败: %s', [E.Message]);

// 记录异常
LogManager.LogException(E, lcNetwork, '额外的上下文信息');

// 性能监控
var PerfLogger := TPerformanceLogger.Create('耗时操作');
// ... 执行代码 ...
PerfLogger.Finish;
```

### 4.6 UI操作和网络请求监控

```pascal
// UI操作监控
LogManager.LogUIOperation('Click', 'Button1', 50);
LogManager.LogUIOperation('Select', 'ComboBox1', -1);

// 网络请求监控
LogManager.LogNetworkRequest('http://example.com/api', 'GET', 200, 150);
LogManager.LogNetworkRequest('http://example.com/api', 'POST', 500, 300);

// 表单监控
LogManager.LogFormShow('MainForm', 100);
LogManager.LogFormClose('MainForm', 50);

// 数据操作监控
LogManager.LogDataOperation('INSERT', 10, 25);
LogManager.LogDataOperation('UPDATE', 5, -1);
```

---

## 5. 通用工具 (uCommonUtils.pas)

### 5.1 数据验证 (TValidator)

```pascal
class function TValidator.IsEmpty(const AValue: string): Boolean;
class function TValidator.IsInteger(const AValue: string): Boolean;
class function TValidator.IsFloat(const AValue: string): Boolean;
class function TValidator.IsEmail(const AValue: string): Boolean;
class function TValidator.IsPhone(const AValue: string): Boolean;
class function TValidator.IsIPAddress(const AValue: string): Boolean;
class function TValidator.ValidateBarcode(const ABarcode: string): TValidationResult;
```

### 5.2 字符串扩展 (TStringHelperEx)

```pascal
function IsInteger: Boolean;
function IsFloat: Boolean;
function ToIntegerDef(ADefault: Integer): Integer;
function ToFloatDef(ADefault: Double): Double;
function Contains(const ASubStr: string): Boolean;
function StartsWith(const AStr: string): Boolean;
function EndsWith(const AStr: string): Boolean;
function ReplaceAll(const AFrom, ATo: string): string;
```

### 5.3 日期时间工具 (TDateTimeHelper)

```pascal
class function TDateTimeHelper.FormatDateTime(const AFormat: string; ADateTime: TDateTime): string;
class function TDateTimeHelper.ParseDateTime(const AValue: string): TDateTime;
class function TDateTimeHelper.IsToday(ADateTime: TDateTime): Boolean;
class function TDateTimeHelper.IsSameDay(ADate1, ADate2: TDateTime): Boolean;
```

### 5.4 JSON工具 (TJSONHelper)

```pascal
class function TJSONHelper.GetString(AJSON: TJSONObject; const AKey: string; const ADefault: string = ''): string;
class function TJSONHelper.GetInteger(AJSON: TJSONObject; const AKey: string; const ADefault: Integer = 0): Integer;
class function TJSONHelper.TryGetString(AJSON: TJSONObject; const AKey: string; out AValue: string): Boolean;
```

---

## 6. 单元测试 (uUnitTests.pas)

### 6.1 测试套件

| 测试套件 | 测试内容 |
|---------|---------|
| `ExceptionHandler` | 异常处理框架测试 |
| `LogManager` | 日志管理框架测试 |
| `ConfigManager` | 配置管理框架测试 |
| `BusinessServices` | 业务服务框架测试 |
| `CommonUtils` | 通用工具测试 |

### 6.2 运行测试

```bash
# GUI模式
TestRunner.exe

# 控制台模式
TestRunner.exe -console
```

### 6.3 测试示例

```pascal
procedure TTestConfigManager.TestConfigTypes;
var
  Config: TConfigManager;
begin
  Config := TConfigManager.Create('test_config.ini');
  try
    Config.SetString('Test', 'String', 'Hello');
    Config.SetInteger('Test', 'Integer', 123);
    Config.SetBoolean('Test', 'Boolean', True);
    Config.SetFloat('Test', 'Float', 123.45);

    CheckEquals('Hello', Config.GetString('Test', 'String', ''));
    CheckEquals(123, Config.GetInteger('Test', 'Integer', 0));
    CheckEquals(True, Config.GetBoolean('Test', 'Boolean', False));
    CheckEquals(123.45, Config.GetFloat('Test', 'Float', 0.0), 0.01);
  finally
    Config.Free;
  end;
end;
```

---

## 7. 文件结构

```
pas\
├── uConfigManager.pas      # 配置管理框架
├── uBusinessServices.pas    # 业务服务框架
├── uExceptionHandler.pas    # 异常处理框架
├── uLogManager.pas          # 日志管理框架
├── uCommonUtils.pas         # 通用工具
├── uUnitTests.pas           # 单元测试
├── uSafeLog.pas             # 安全日志(已集成新框架)
├── uDM.pas                  # 数据模块(已集成新框架)
├── uFrameBase.pas           # 框架基类(已添加文档)
└── 其他业务框架文件...
```

---

## 8. 迁移指南

### 8.1 使用配置管理器替代硬编码

**Before:**
```pascal
PLCHost := '192.168.1.100';
PLCPort := 502;
```

**After:**
```pascal
PLCHost := Config.GetPLCHost;
PLCPort := Config.GetPLCPort;
```

### 8.2 使用新的异常处理

**Before:**
```pascal
raise Exception.Create('错误信息');
```

**After:**
```pascal
RaiseBusinessException('错误信息', 1001);
// 或
RaiseDeviceException('PLC连接失败: %s', [E.Message], 5001);
```

### 8.3 使用新的日志框架

**Before:**
```pascal
WorkLog.MessageInfo('操作成功');
WorkLog.Error('操作失败: %s', [E.Message]);
```

**After:**
```pascal
LogManager.InfoCategory(lcBusiness, '操作成功');
LogManager.ErrorCategory(lcBusiness, '操作失败: %s', [E.Message]);
```

---

## 9. 最佳实践

1. **配置管理**: 所有硬编码的配置值都应迁移到配置管理器
2. **异常处理**: 使用特定的异常类型，便于分类处理
3. **日志记录**: 在关键业务操作中添加日志和性能监控
4. **单元测试**: 新增功能应同步添加单元测试
5. **代码文档**: 复杂函数应添加文档注释

---

## 10. 版本信息

| 版本 | 日期 | 说明 |
|-----|------|-----
| 1.1 | 2026-04-26 | 扩展生产报工服务，添加用户验证、工单查询、二维码验证等功能 |
| 1.0 | 2026-04-26 | 初始版本，包含核心框架 |

---

*文档最后更新: 2026-04-26*