refactor(docs): reorganize documentation directory structure
- Create user/ - User guides and configuration documentation - Create features/ - Feature specifications and business flows - Create debugging/ - Debug guides and quick references - Create testing/ - Test infrastructure, reports, and plans - Create internal/ - Internal plans, analyses, and templates - Move cleaner/*.md to cleaner/ directory - Move LOGGING_*.md to developer/guides/ Add docs/README.md as documentation index with category navigation and quick lookup guide. The reorganized structure makes it easier for users and developers to quickly locate relevant documentation.
This commit is contained in:
Misaka_Company
731
docs/internal/Configuration-Architecture-Analysis.md
Normal file
731
docs/internal/Configuration-Architecture-Analysis.md
Normal file
@@ -0,0 +1,731 @@
|
||||
# ERPAuto 配置系统架构分析
|
||||
|
||||
## 1. 概述
|
||||
|
||||
ERPAuto 是一个基于 Electron 的桌面应用程序，采用多层次配置管理系统来支持 ERP 系统自动化数据处理。配置系统采用 `.env` 文件作为持久化存储，通过 `ConfigManager` 统一管理，支持运行时动态修改和持久化保存。
|
||||
|
||||
## 2. 配置系统整体架构
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "配置数据源"
|
||||
ENV[.env 文件]
|
||||
ENV_EXAMPLE[.env.example 模板]
|
||||
CACHE[内存缓存 ConfigCache]
|
||||
end
|
||||
|
||||
subgraph "配置管理层 ConfigManager"
|
||||
CM_LOAD[loadEnvFile]
|
||||
CM_GET[get/getBoolean/getNumber]
|
||||
CM_SET[set]
|
||||
CM_SAVE[save/saveAllSettings]
|
||||
CM_PARTIAL[savePartialSettings]
|
||||
CM_MERGE[deepMerge 深度合并]
|
||||
end
|
||||
|
||||
subgraph "IPC 通信层"
|
||||
SETTINGS_HANDLER[settings-handler.ts]
|
||||
IPC_GET[settings:getSettings]
|
||||
IPC_SAVE[settings:saveSettings]
|
||||
IPC_TEST[settings:testErpConnection/testDbConnection]
|
||||
end
|
||||
|
||||
subgraph "业务服务层"
|
||||
ERP_SVC[ERP 服务]
|
||||
DB_SVC[数据库服务]
|
||||
USER_SVC[用户服务]
|
||||
EXTRACTOR[ExtractorService]
|
||||
CLEANER[CleanerService]
|
||||
end
|
||||
|
||||
subgraph "UI 呈现层"
|
||||
SETTINGS_UI[设置界面]
|
||||
LOGIN_UI[登录界面]
|
||||
MAIN_UI[主界面]
|
||||
end
|
||||
|
||||
ENV -->|读取 | CM_LOAD
|
||||
ENV_EXAMPLE -.->|模板参考 | ENV
|
||||
CM_LOAD -->|填充 | CACHE
|
||||
CACHE --> CM_GET
|
||||
CM_SET --> CACHE
|
||||
CM_PARTIAL --> CM_MERGE --> CM_SAVE --> ENV
|
||||
|
||||
CM_GET --> SETTINGS_HANDLER
|
||||
SETTINGS_HANDLER --> IPC_GET
|
||||
SETTINGS_HANDLER --> IPC_SAVE
|
||||
SETTINGS_HANDLER --> IPC_TEST
|
||||
|
||||
IPC_GET --> SETTINGS_UI
|
||||
IPC_SAVE --> SETTINGS_UI
|
||||
IPC_TEST --> SETTINGS_UI
|
||||
|
||||
CACHE --> ERP_SVC
|
||||
CACHE --> DB_SVC
|
||||
CACHE --> USER_SVC
|
||||
CACHE --> EXTRACTOR
|
||||
CACHE --> CLEANER
|
||||
|
||||
SETTINGS_UI --> MAIN_UI
|
||||
LOGIN_UI --> USER_SVC
|
||||
```
|
||||
|
||||
## 3. 配置文件结构
|
||||
|
||||
### 3.1 .env 文件组织
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "ERP 系统配置"
|
||||
ERP_URL[ERP_URL]
|
||||
ERP_USER[ERP_USERNAME]
|
||||
ERP_PASS[ERP_PASSWORD]
|
||||
ERP_HEADLESS[ERP_HEADLESS]
|
||||
ERP_HTTPS[ERP_IGNORE_HTTPS_ERRORS]
|
||||
ERP_CLOSE[ERP_AUTO_CLOSE_BROWSER]
|
||||
end
|
||||
|
||||
subgraph "数据库配置 - SQL Server"
|
||||
SQL_DRIVER[DB_SQLSERVER_DRIVER]
|
||||
SQL_TRUST[DB_TRUST_SERVER_CERTIFICATE]
|
||||
end
|
||||
|
||||
subgraph "数据库配置 - MySQL"
|
||||
DB_TYPE[DB_TYPE]
|
||||
DB_NAME[DB_NAME]
|
||||
DB_USER[DB_USERNAME]
|
||||
DB_PASS[DB_PASSWORD]
|
||||
MYSQL_HOST[DB_MYSQL_HOST]
|
||||
MYSQL_PORT[DB_MYSQL_PORT]
|
||||
MYSQL_CHARSET[DB_MYSQL_CHARSET]
|
||||
end
|
||||
|
||||
subgraph "订单号解析表配置"
|
||||
TABLE_NAME[DB_TABLE_NAME]
|
||||
FIELD_PROD_ID[DB_FIELD_PRODUCTION_ID]
|
||||
FIELD_ORDER[DB_FIELD_ORDER_NUMBER]
|
||||
end
|
||||
|
||||
subgraph "路径配置"
|
||||
DATA_DIR[PATH_DATA_DIR]
|
||||
PROD_ID_FILE[PATH_PRODUCTION_ID_FILE]
|
||||
DEFAULT_OUT[PATH_DEFAULT_OUTPUT]
|
||||
VALID_OUT[PATH_VALIDATION_OUTPUT]
|
||||
end
|
||||
|
||||
subgraph "数据提取配置"
|
||||
BATCH_SIZE[EXTRACTION_BATCH_SIZE]
|
||||
VERBOSE[EXTRACTION_VERBOSE]
|
||||
AUTO_CONVERT[EXTRACTION_AUTO_CONVERT]
|
||||
MERGE_BATCHES[EXTRACTION_MERGE_BATCHES]
|
||||
DB_PERSIST[EXTRACTION_ENABLE_DB_PERSISTENCE]
|
||||
end
|
||||
|
||||
subgraph "校验配置"
|
||||
DATA_SOURCE[VALIDATION_DATA_SOURCE]
|
||||
USE_DB[VALIDATION_USE_DATABASE]
|
||||
VAL_BATCH[VALIDATION_BATCH_SIZE]
|
||||
ENABLE_CRUD[VALIDATION_ENABLE_CRUD]
|
||||
DEFAULT_MGR[VALIDATION_DEFAULT_MANAGER]
|
||||
MATCH_MODE[VALIDATION_MATCH_MODE]
|
||||
end
|
||||
|
||||
subgraph "UI 配置"
|
||||
FONT_FAMILY[UI_FONT_FAMILY]
|
||||
FONT_SIZE[UI_FONT_SIZE]
|
||||
INPUT_WIDTH[UI_PRODUCTION_ID_INPUT_WIDTH]
|
||||
end
|
||||
|
||||
subgraph "执行配置"
|
||||
DRY_RUN[EXECUTION_DRYRUN]
|
||||
end
|
||||
```
|
||||
|
||||
### 3.2 默认配置值
|
||||
|
||||
| 配置类别 | 配置项 | 默认值 | 说明 |
|
||||
| ---------- | ----------------- | --------------------------- | -------------------- |
|
||||
| ERP | url | `https://68.11.34.30:8082/` | ERP 系统地址 |
|
||||
| ERP | headless | `true` | 无头浏览器模式 |
|
||||
| ERP | ignoreHttpsErrors | `true` | 忽略 HTTPS 证书错误 |
|
||||
| ERP | autoCloseBrowser | `true` | 操作后自动关闭浏览器 |
|
||||
| Database | dbType | `mysql` | 数据库类型 |
|
||||
| Database | mysqlHost | `192.168.31.83` | MySQL 主机地址 |
|
||||
| Database | mysqlPort | `3306` | MySQL 端口 |
|
||||
| Database | database | `BLD_DB` | 数据库名 |
|
||||
| Database | username | `remote_user` | 数据库用户名 |
|
||||
| Paths | dataDir | `D:/python/playwrite/data/` | 数据目录 |
|
||||
| Extraction | batchSize | `100` | 批次大小 |
|
||||
| Extraction | verbose | `true` | 详细日志 |
|
||||
| Validation | dataSource | `database_full` | 校验数据源 |
|
||||
| Validation | batchSize | `2000` | 校验批次大小 |
|
||||
| Validation | matchMode | `substring` | 匹配模式 |
|
||||
| UI | fontFamily | `Microsoft YaHei UI` | 字体 |
|
||||
| UI | fontSize | `10` | 字体大小 |
|
||||
| Execution | dryRun | `false` | 干运行模式 |
|
||||
|
||||
## 4. ConfigManager 核心类设计
|
||||
|
||||
### 4.1 类结构与单例模式
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ConfigManager {
|
||||
-static instance: ConfigManager | null
|
||||
-envPath: string
|
||||
-backupPath: string
|
||||
-configCache: Map<string, string>
|
||||
-initialized: boolean
|
||||
+static getInstance(): ConfigManager
|
||||
+initialize(): Promise<void>
|
||||
+get(key: string): string | undefined
|
||||
+getBoolean(key: string, default: boolean): boolean
|
||||
+getNumber(key: string, default: number): number
|
||||
+set(key: string, value: string|number|boolean): void
|
||||
+save(): Promise<boolean>
|
||||
+getAllSettings(): SettingsData
|
||||
+saveAllSettings(settings: SettingsData): Promise<boolean>
|
||||
+savePartialSettings(settings: Partial<SettingsData>): Promise<Object>
|
||||
+resetToDefaults(): SettingsData
|
||||
+getDefaultSettings(): SettingsData
|
||||
-loadEnvFile(): Promise<void>
|
||||
-backupEnvFile(): Promise<boolean>
|
||||
-restoreBackup(): Promise<boolean>
|
||||
}
|
||||
|
||||
class SettingsData {
|
||||
+erp: ErpConfig
|
||||
+database: DatabaseConfig
|
||||
+paths: PathsConfig
|
||||
+extraction: ExtractionConfig
|
||||
+validation: ValidationConfig
|
||||
+ui: UiConfig
|
||||
+execution: ExecutionConfig
|
||||
}
|
||||
|
||||
ConfigManager --> SettingsData: 返回/接收
|
||||
```
|
||||
|
||||
### 4.2 核心方法流程图
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as 客户端/IPC
|
||||
participant CM as ConfigManager
|
||||
participant Cache as ConfigCache
|
||||
participant FS as 文件系统
|
||||
participant Backup as Backup 文件
|
||||
|
||||
Client->>CM: savePartialSettings(settings)
|
||||
activate CM
|
||||
|
||||
CM->>CM: validateEditableFields()
|
||||
alt 包含非白名单字段
|
||||
CM-->>Client: 返回错误 (不允许修改)
|
||||
else 验证通过
|
||||
CM->>FS: loadEnvFile()
|
||||
FS-->>Cache: 填充缓存
|
||||
CM->>CM: getAllSettings()
|
||||
CM->>Cache: 读取当前配置
|
||||
CM->>CM: deepMerge(current, settings)
|
||||
|
||||
CM->>FS: backupEnvFile()
|
||||
FS-->>Backup: 创建备份
|
||||
|
||||
CM->>FS: saveAllSettings(merged)
|
||||
alt 保存成功
|
||||
FS-->>Cache: 重新加载
|
||||
CM-->>Client: 返回成功
|
||||
else 保存失败
|
||||
CM->>FS: restoreBackup()
|
||||
FS-->>Cache: 恢复配置
|
||||
CM-->>Client: 返回错误
|
||||
end
|
||||
end
|
||||
deactivate CM
|
||||
```
|
||||
|
||||
### 4.3 深度合并算法
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[deepMerge 函数] --> B{遍历 target 键值对}
|
||||
B --> C{targetValue 是对象？}
|
||||
C -->|是 | D{sourceValue 也是对象？}
|
||||
D -->|是 | E[递归调用 deepMerge]
|
||||
D -->|否 | F[直接使用 targetValue]
|
||||
C -->|否 | G{targetValue !== undefined?}
|
||||
G -->|是 | H[更新该键值]
|
||||
G -->|否 | I[跳过该键]
|
||||
E --> J[合并结果存入 result]
|
||||
F --> J
|
||||
H --> J
|
||||
B --> K[遍历完成]
|
||||
K --> L[返回合并后的对象]
|
||||
```
|
||||
|
||||
## 5. 配置读取与使用模式
|
||||
|
||||
### 5.1 环境变量直接读取模式
|
||||
|
||||
各业务服务通过 `process.env` 直接读取配置：
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "环境变量读取点"
|
||||
MAIN[main/index.ts<br/>dotenv.config]
|
||||
end
|
||||
|
||||
subgraph "服务模块"
|
||||
DB_INDEX[database/index.ts]
|
||||
DB_MYSQL[database/mysql.ts]
|
||||
DB_SQL[database/sql-server.ts]
|
||||
BIP_DAO[bip-users-dao.ts]
|
||||
ORDER_RES[order-resolver.ts]
|
||||
EXTRACTOR[extractor-handler.ts]
|
||||
CLEANER[cleaner-handler.ts]
|
||||
VALIDATION[validation-handler.ts]
|
||||
end
|
||||
|
||||
MAIN -->|初始化加载 | ENV[process.env]
|
||||
|
||||
ENV --> DB_INDEX
|
||||
ENV --> DB_MYSQL
|
||||
ENV --> DB_SQL
|
||||
ENV --> BIP_DAO
|
||||
ENV --> ORDER_RES
|
||||
ENV --> EXTRACTOR
|
||||
ENV --> CLEANER
|
||||
ENV --> VALIDATION
|
||||
```
|
||||
|
||||
### 5.2 ConfigManager 获取模式
|
||||
|
||||
通过 IPC 层统一获取：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as 设置界面
|
||||
participant Preload as Preload 脚本
|
||||
participant IPC as IPC Handler
|
||||
participant CM as ConfigManager
|
||||
|
||||
UI->>Preload: window.api.settings.getSettings()
|
||||
Preload->>IPC: ipcRenderer.invoke('settings:getSettings')
|
||||
IPC->>IPC: SessionManager.getUserType()
|
||||
IPC->>CM: getAllSettings()
|
||||
CM->>IPC: SettingsData
|
||||
IPC->>IPC: filterSettingsByUserType()
|
||||
IPC-->>Preload: 过滤后的 SettingsData
|
||||
Preload-->>UI: SettingsData
|
||||
```
|
||||
|
||||
### 5.3 数据库配置工厂模式
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "配置创建"
|
||||
GET_TYPE[getDatabaseType] -->|DB_TYPE env| TYPE_CHECK{数据库类型}
|
||||
TYPE_CHECK -->|mysql| CREATE_MYSQL[createMySqlConfig]
|
||||
TYPE_CHECK -->|sqlserver| CREATE_SQL[createSqlServerConfig]
|
||||
end
|
||||
|
||||
subgraph "服务创建"
|
||||
CREATE_MYSQL --> MYSQL_SVC[MySqlService]
|
||||
CREATE_SQL --> SQL_SVC[SqlServerService]
|
||||
end
|
||||
|
||||
subgraph "单例缓存"
|
||||
MYSQL_SVC --> CACHE[instances Map]
|
||||
SQL_SVC --> CACHE
|
||||
CACHE -->|返回已连接实例 | CLIENT[调用方]
|
||||
end
|
||||
|
||||
CREATE_MYSQL --> CONNECT_MYSQL[service.connect]
|
||||
CREATE_SQL --> CONNECT_SQL[service.connect]
|
||||
|
||||
CONNECT_MYSQL --> CACHE
|
||||
CONNECT_SQL --> CACHE
|
||||
```
|
||||
|
||||
## 6. 用户权限与配置访问控制
|
||||
|
||||
### 6.1 用户类型与权限
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "用户类型 UserType"
|
||||
ADMIN[Admin<br/>管理员]
|
||||
USER[User<br/>普通用户]
|
||||
GUEST[Guest<br/>访客]
|
||||
end
|
||||
|
||||
subgraph "配置访问权限"
|
||||
ADMIN_SETTINGS[全部配置可访问<br/>可修改 ERP 配置<br/>可恢复默认设置]
|
||||
USER_SETTINGS[有限配置访问<br/>可修改 ERP 配置<br/>可查看执行配置]
|
||||
GUEST_SETTINGS[只读访问]
|
||||
end
|
||||
|
||||
ADMIN --> ADMIN_SETTINGS
|
||||
USER --> USER_SETTINGS
|
||||
GUEST --> GUEST_SETTINGS
|
||||
|
||||
subgraph "SessionManager 会话管理"
|
||||
SM_LOGIN[login]
|
||||
SM_SILENT[loginByComputerName]
|
||||
SM_SWITCH[switchUser - Admin only]
|
||||
SM_GET[getUserType/getUserInfo]
|
||||
end
|
||||
|
||||
SM_LOGIN --> USER
|
||||
SM_SILENT --> USER
|
||||
SM_SWITCH --> USER
|
||||
```
|
||||
|
||||
### 6.2 配置过滤机制
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[getSettings 请求] --> B[获取当前用户类型]
|
||||
B --> C{用户类型判断}
|
||||
|
||||
C -->|Admin| D[返回全部配置]
|
||||
|
||||
C -->|User| E[过滤配置]
|
||||
E --> F[返回 ERP 配置<br/>username/password/headless/url/...<br/>paths 配置<br/>execution 配置<br/>最小化其他配置]
|
||||
|
||||
C -->|Guest| G[返回空配置或只读配置]
|
||||
|
||||
D --> H[返回给 UI]
|
||||
E --> H
|
||||
G --> H
|
||||
```
|
||||
|
||||
## 7. 配置修改白名单机制
|
||||
|
||||
### 7.1 可编辑字段白名单
|
||||
|
||||
```javascript
|
||||
const UI_EDITABLE_FIELDS: string[] = [
|
||||
'erp.url',
|
||||
'erp.username',
|
||||
'erp.password'
|
||||
// 可根据需要扩展
|
||||
]
|
||||
```
|
||||
|
||||
### 7.2 白名单验证流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[savePartialSettings 调用] --> B[遍历 settings 中的字段]
|
||||
B --> C[构建字段路径 section.field]
|
||||
C --> D{字段在白名单中？}
|
||||
D -->|否 | E[添加到 invalidFields]
|
||||
D -->|是 | F[继续检查下一字段]
|
||||
E --> B
|
||||
F --> B
|
||||
B --> G{所有字段检查完成}
|
||||
G --> H{invalidFields 为空？}
|
||||
H -->|否 | I[返回错误<br/>包含不允许修改的字段]
|
||||
H -->|是 | J[继续保存流程]
|
||||
```
|
||||
|
||||
## 8. 数据库配置详解
|
||||
|
||||
### 8.1 双数据库支持架构
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "数据库抽象层"
|
||||
IDB[IDatabaseService 接口<br/>connect/disconnect<br/>query/transaction<br/>isConnected]
|
||||
end
|
||||
|
||||
subgraph "MySQL 实现"
|
||||
MYSQL[MySqlService<br/>mysql2/promise<br/>createConnection<br/>execute/transaction]
|
||||
end
|
||||
|
||||
subgraph "SQL Server 实现"
|
||||
MSSQL[SqlServerService<br/>mssql<br/>ConnectionPool<br/>request.query<br/>Transaction]
|
||||
end
|
||||
|
||||
IDB -.->|实现 | MYSQL
|
||||
IDB -.->|实现 | MSSQL
|
||||
|
||||
MYSQL --> ENV_MYSQL[DB_MYSQL_HOST<br/>DB_MYSQL_PORT<br/>DB_NAME<br/>DB_USERNAME<br/>DB_PASSWORD]
|
||||
MSSQL --> ENV_MSSQL[DB_SERVER<br/>DB_SQLSERVER_PORT<br/>DB_NAME<br/>DB_USERNAME<br/>DB_PASSWORD<br/>DB_TRUST_SERVER_CERTIFICATE]
|
||||
```
|
||||
|
||||
### 8.2 数据库配置参数映射
|
||||
|
||||
| 环境变量 | MySQL 用途 | SQL Server 用途 |
|
||||
| --------------------------- | ----------- | ----------------- |
|
||||
| DB_TYPE | mysql | sqlserver/mssql |
|
||||
| DB_NAME | 数据库名 | 数据库名 |
|
||||
| DB_USERNAME | 用户名 | 用户名 |
|
||||
| DB_PASSWORD | 密码 | 密码 |
|
||||
| DB_MYSQL_HOST | 主机地址 | - |
|
||||
| DB_MYSQL_PORT | 端口 (3306) | - |
|
||||
| DB_SERVER | - | 服务器地址 |
|
||||
| DB_SQLSERVER_PORT | - | 端口 (1433) |
|
||||
| DB_TRUST_SERVER_CERTIFICATE | - | 信任证书 (yes/no) |
|
||||
|
||||
## 9. ERP 配置与浏览器自动化
|
||||
|
||||
### 9.1 ERP 认证配置流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as 设置界面
|
||||
participant IPC as settings-handler
|
||||
participant CM as ConfigManager
|
||||
participant ERP_AUTH as ErpAuthService
|
||||
participant PW as Playwright
|
||||
|
||||
UI->>IPC: testErpConnection
|
||||
IPC->>CM: getAllSettings
|
||||
CM-->>IPC: SettingsData(含 erp 配置)
|
||||
|
||||
IPC->>ERP_AUTH: new ErpAuthService(erpConfig)
|
||||
ERP_AUTH->>PW: chromium.launch
|
||||
Note over PW: headless=erpConfig.headless<br/>args=[--ignore-certificate-errors]
|
||||
|
||||
PW-->>ERP_AUTH: Browser Context
|
||||
|
||||
ERP_AUTH->>PW: page.goto(loginUrl)
|
||||
PW-->>ERP_AUTH: 加载登录页面
|
||||
|
||||
ERP_AUTH->>PW: fill username/password
|
||||
ERP_AUTH->>PW: click login button
|
||||
|
||||
PW-->>ERP_AUTH: 登录成功
|
||||
|
||||
ERP_AUTH-->>IPC: ErpSession
|
||||
IPC-->>UI: {success: true}
|
||||
|
||||
ERP_AUTH->>PW: close
|
||||
```
|
||||
|
||||
### 9.2 ERP 配置项说明
|
||||
|
||||
| 配置项 | 类型 | 默认值 | 说明 |
|
||||
| ----------------- | ------- | ------ | -------------- |
|
||||
| url | string | - | ERP 系统 URL |
|
||||
| username | string | - | ERP 用户名 |
|
||||
| password | string | - | ERP 密码 |
|
||||
| headless | boolean | true | 无头模式 |
|
||||
| ignoreHttpsErrors | boolean | true | 忽略 SSL 错误 |
|
||||
| autoCloseBrowser | boolean | true | 自动关闭浏览器 |
|
||||
|
||||
## 10. 订单号解析表配置
|
||||
|
||||
### 10.1 配置结构
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "订单号解析配置"
|
||||
TABLE[DB_TABLE_NAME<br/>表名]
|
||||
FIELD_ID[DB_FIELD_PRODUCTION_ID<br/>总排号字段]
|
||||
FIELD_ORDER[DB_FIELD_ORDER_NUMBER<br/>生产订单号字段]
|
||||
end
|
||||
|
||||
TABLE --> ORDER_RESOLVER[OrderResolverService]
|
||||
FIELD_ID --> ORDER_RESOLVER
|
||||
FIELD_ORDER --> ORDER_RESOLVER
|
||||
|
||||
ORDER_RESOLVER --> DB_QUERY[查询映射关系]
|
||||
DB_QUERY --> PRODUCTION_ID[productionID]
|
||||
DB_QUERY --> ORDER_NUMBER[生产订单号]
|
||||
```
|
||||
|
||||
### 10.2 默认配置示例
|
||||
|
||||
```env
|
||||
DB_TABLE_NAME=productionContractData_26 年压力表合同数据
|
||||
DB_FIELD_PRODUCTION_ID=总排号
|
||||
DB_FIELD_ORDER_NUMBER=生产订单号
|
||||
```
|
||||
|
||||
## 11. 配置持久化与备份机制
|
||||
|
||||
### 11.1 保存流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[saveAllSettings] --> B[设置写入 configCache]
|
||||
B --> C[构建.env 文件内容]
|
||||
C --> D[按分类组织配置<br/>ERP/数据库/路径/提取/校验/UI/执行]
|
||||
D --> E[写入.env 文件]
|
||||
E --> F{写入成功？}
|
||||
F -->|是 | G[返回 true]
|
||||
F -->|否 | H[返回 false]
|
||||
```
|
||||
|
||||
### 11.2 备份与恢复流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Caller as 调用方
|
||||
participant CM as ConfigManager
|
||||
participant ENV as .env
|
||||
participant BAK as .env.backup
|
||||
|
||||
Caller->>CM: savePartialSettings
|
||||
CM->>CM: validateEditableFields
|
||||
|
||||
CM->>ENV: loadEnvFile
|
||||
CM->>CM: deepMerge 合并配置
|
||||
|
||||
CM->>ENV: backupEnvFile
|
||||
ENV->>BAK: copyFileSync
|
||||
|
||||
CM->>ENV: writeFileSync 新配置
|
||||
ENV-->>CM: 保存结果
|
||||
|
||||
alt 保存成功
|
||||
CM->>ENV: loadEnvFile 重新加载
|
||||
CM-->>Caller: success: true
|
||||
else 保存失败
|
||||
CM->>BAK: restoreBackup
|
||||
BAK->>ENV: copyFileSync 恢复
|
||||
CM->>ENV: loadEnvFile
|
||||
CM-->>Caller: success: false + error
|
||||
end
|
||||
```
|
||||
|
||||
## 12. 配置系统初始化时序
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App as Electron App
|
||||
participant Main as main/index.ts
|
||||
participant Dotenv as dotenv
|
||||
participant CM as ConfigManager
|
||||
participant IPC as registerIpcHandlers
|
||||
participant SM as SessionManager
|
||||
|
||||
App->>Main: 应用启动
|
||||
Main->>Dotenv: config .env
|
||||
Dotenv-->>Main: process.env 已加载
|
||||
|
||||
Main->>IPC: registerIpcHandlers
|
||||
Note over IPC: 注册所有 IPC 处理器<br/>settings/extractor/cleaner/auth...
|
||||
|
||||
App->>Main: app.whenReady
|
||||
Main->>SM: silent login 尝试
|
||||
SM->>SM: loginByComputerName
|
||||
|
||||
alt 静默登录成功
|
||||
SM-->>Main: 用户已认证
|
||||
else 静默登录失败
|
||||
Main->>Main: 显示登录对话框
|
||||
end
|
||||
|
||||
Main->>CM: initialize 按需加载
|
||||
```
|
||||
|
||||
## 13. 关键代码模式
|
||||
|
||||
### 13.1 环境变量读取模式
|
||||
|
||||
```typescript
|
||||
// 直接读取 process.env
|
||||
const dbType = process.env.DB_TYPE?.toLowerCase()
|
||||
const mysqlHost = process.env.DB_MYSQL_HOST || 'localhost'
|
||||
const mysqlPort = parseInt(process.env.DB_MYSQL_PORT || '3306', 10)
|
||||
```
|
||||
|
||||
### 13.2 ConfigManager 读取模式
|
||||
|
||||
```typescript
|
||||
// 通过 ConfigManager 获取结构化配置
|
||||
const configManager = ConfigManager.getInstance()
|
||||
const settings = configManager.getAllSettings()
|
||||
const erpUrl = settings.erp.url
|
||||
const batchSize = settings.extraction.batchSize
|
||||
```
|
||||
|
||||
### 13.3 部分保存模式
|
||||
|
||||
```typescript
|
||||
// 只更新允许修改的字段
|
||||
const result = await configManager.savePartialSettings({
|
||||
erp: {
|
||||
url: 'http://new-url.com',
|
||||
username: 'newuser',
|
||||
password: 'newpass'
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## 14. 配置类别与业务模块映射
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "配置类别"
|
||||
ERP_CONF[ERP 配置]
|
||||
DB_CONF[数据库配置]
|
||||
PATH_CONF[路径配置]
|
||||
EXTRACT_CONF[提取配置]
|
||||
VALID_CONF[校验配置]
|
||||
UI_CONF[UI 配置]
|
||||
EXEC_CONF[执行配置]
|
||||
end
|
||||
|
||||
subgraph "业务模块"
|
||||
ERP_AUTH[ErpAuthService]
|
||||
ERP_EXTRACT[ExtractorService]
|
||||
ERP_CLEAN[CleanerService]
|
||||
ERP_ORDER[OrderResolverService]
|
||||
DB_MYSQL[MySqlService]
|
||||
DB_SQL[SqlServerService]
|
||||
DB_DAO[各种 DAO 类]
|
||||
EXCEL[Excel Parser/Exporter]
|
||||
UI[React 界面]
|
||||
end
|
||||
|
||||
ERP_CONF --> ERP_AUTH
|
||||
ERP_CONF --> ERP_EXTRACT
|
||||
ERP_CONF --> ERP_CLEAN
|
||||
|
||||
DB_CONF --> DB_MYSQL
|
||||
DB_CONF --> DB_SQL
|
||||
DB_CONF --> DB_DAO
|
||||
|
||||
PATH_CONF --> EXCEL
|
||||
PATH_CONF --> UI
|
||||
|
||||
EXTRACT_CONF --> ERP_EXTRACT
|
||||
EXTRACT_CONF --> DB_DAO
|
||||
|
||||
VALID_CONF --> ERP_EXTRACT
|
||||
VALID_CONF --> DB_DAO
|
||||
|
||||
UI_CONF --> UI
|
||||
|
||||
EXEC_CONF --> ERP_CLEAN
|
||||
```
|
||||
|
||||
## 15. 配置系统特点总结
|
||||
|
||||
### 15.1 优点
|
||||
|
||||
1. **集中化管理**: ConfigManager 单例模式统一管理所有配置
|
||||
2. **类型安全**: TypeScript 类型定义确保配置结构正确
|
||||
3. **权限控制**: 基于用户类型的配置访问和修改权限控制
|
||||
4. **备份恢复**: 自动备份机制防止配置丢失
|
||||
5. **双数据库支持**: MySQL 和 SQL Server 灵活切换
|
||||
6. **部分更新**: deepMerge 支持配置部分字段更新
|
||||
|
||||
### 15.2 可扩展性
|
||||
|
||||
1. **新增配置项**: 在 `.env.example` 添加 → `DEFAULT_SETTINGS` 定义 → `SettingsData` 类型 → `save` 方法输出
|
||||
2. **新增用户权限**: 扩展 `UserType` → 更新 `filterSettingsByUserType` 逻辑
|
||||
3. **新增白名单字段**: 在 `UI_EDITABLE_FIELDS` 数组添加路径
|
||||
|
||||
### 15.3 注意事项
|
||||
|
||||
1. 修改配置后需要重新加载 `.env` 文件使 `process.env` 生效
|
||||
2. 非白名单字段只能通过 `saveAllSettings` 或 `resetToDefaults` 修改
|
||||
3. 数据库服务使用单例缓存，配置变更需重启应用或手动重连
|
||||
4. ERP 配置变更需重启浏览器才能生效
|
||||
86
docs/internal/cleaner-execution-report-template.md
Normal file
86
docs/internal/cleaner-execution-report-template.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# ERP 物料清理执行报告
|
||||
|
||||
## 执行摘要
|
||||
|
||||
| 项目 | 值 |
|
||||
| -------------- | --------------------------------- |
|
||||
| **执行时间** | `YYYY-MM-DD HH:mm:ss` |
|
||||
| **执行模式** | `正式执行` / `模拟运行 (Dry Run)` |
|
||||
| **操作用户** | `username` |
|
||||
| **处理订单数** | `X` |
|
||||
| **删除物料数** | `X` |
|
||||
| **跳过物料数** | `X` |
|
||||
| **错误数量** | `X` |
|
||||
| **执行耗时** | `X 分 Y 秒` |
|
||||
|
||||
---
|
||||
|
||||
## 执行状态
|
||||
|
||||
| 状态 | 数量 | 百分比 |
|
||||
| ----------- | ---- | ------ |
|
||||
| ✅ 成功订单 | X | XX% |
|
||||
| ❌ 失败订单 | X | XX% |
|
||||
|
||||
---
|
||||
|
||||
## 订单处理详情
|
||||
|
||||
| # | 订单号 | 删除数 | 跳过数 | 状态 | 错误信息 |
|
||||
| --- | -------- | ------ | ------ | ------- | ------------------------ |
|
||||
| 1 | `PO-001` | 5 | 2 | ✅ 成功 | - |
|
||||
| 2 | `PO-002` | 0 | 0 | ❌ 失败 | `Order PO-002: 超时错误` |
|
||||
| 3 | `PO-003` | 3 | 1 | ✅ 成功 | - |
|
||||
| ... | ... | ... | ... | ... | ... |
|
||||
|
||||
---
|
||||
|
||||
## 跳过的物料原因说明
|
||||
|
||||
| 订单号 | 物料代码 | 物料名称 | 行号 | 跳过原因 |
|
||||
| -------- | -------- | -------- | ---- | --------------------------------- |
|
||||
| `PO-001` | `M001` | 物料名称 | 7500 | 行号在 2000-7999 范围内（受保护） |
|
||||
| `PO-001` | `M002` | 物料名称 | 1200 | 累计待发数量不为空 |
|
||||
| `PO-002` | `M003` | 物料名称 | 300 | 物料不在删除清单中 |
|
||||
| ... | ... | ... | ... | ... |
|
||||
|
||||
---
|
||||
|
||||
## 错误详情
|
||||
|
||||
**错误总数**: `X`
|
||||
|
||||
### 错误订单列表
|
||||
|
||||
- `PO-002`
|
||||
- `PO-005`
|
||||
- `PO-008`
|
||||
- ...
|
||||
|
||||
### 错误详细信息
|
||||
|
||||
#### `PO-002`
|
||||
|
||||
```
|
||||
订单号: PO-002
|
||||
错误: 订单不存在或已被锁定，无法访问备料计划
|
||||
```
|
||||
|
||||
#### `PO-005`
|
||||
|
||||
```
|
||||
订单号: PO-005
|
||||
错误: ERP 连接超时：请求在 30000ms 内未得到响应
|
||||
```
|
||||
|
||||
#### `PO-008`
|
||||
|
||||
```
|
||||
订单号: PO-008
|
||||
错误: 备料状态异常：当前状态为"待审批"，无法执行删除操作
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**报告生成时间**: `YYYY-MM-DD HH:mm:ss`
|
||||
**报表版本**: `v1.0`
|
||||
93
docs/internal/optimization-execution-plan.md
Normal file
93
docs/internal/optimization-execution-plan.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# ERPAuto 优化执行计划文档
|
||||
|
||||
基于《ERPAuto 优化建议与规范指南》，本文档规划了具体的分阶段重构与优化执行步骤。每个阶段遵循“渐进式重构”原则，保证在优化期间项目依然可运行、可测试。
|
||||
|
||||
## 阶段一：基础设施建设 (Error & Logging)
|
||||
|
||||
在进行大规模业务逻辑重构前，首先建立坚实的基础设施，以便后续问题排查与数据追踪。
|
||||
|
||||
1. **引入并配置统一日志库**
|
||||
- **目标**: 替换分散的 `console.log`。
|
||||
- **执行**:
|
||||
- 安装 `winston` (针对 Node.js 主进程)。
|
||||
- 在 `src/main/services/logger` 创建单例日志记录器。
|
||||
- 配置双通道输出：Console (Dev 环境) 与 File (生产环境按天切割，如 `%AppData%/ERPAuto/logs/app-%DATE%.log`)。
|
||||
2. **定义全局错误类型与 IPC 拦截器**
|
||||
- **目标**: 规范前后端错误抛出与展示体系。
|
||||
- **执行**:
|
||||
- 在 `src/main/types/errors.ts` 定义 `BaseError`, `ErpConnectionError`, `DatabaseQueryError`。
|
||||
- 在 `src/main/ipc/index.ts` 中封装高阶函数 `withErrorHandling`。所有 IPC Handler 统一用此高阶函数包裹，将捕获的错误统一转为 `{ success: false, error: string, code: string }` 结构。
|
||||
|
||||
## 阶段二：数据层抽象与 ORM 改造
|
||||
|
||||
彻底解决 SQL 语句散落和不同数据库适配成本高的问题。
|
||||
|
||||
1. **选型并引入 ORM**
|
||||
- **目标**: 弃用原生 SQL 拼接。
|
||||
- **执行**:
|
||||
- 引入 `Prisma` 或 `TypeORM`。结合当前多数据源 (MySQL + SQL Server) 需求，推荐 `TypeORM` 因为其在运行时切换数据源更为灵活。
|
||||
2. **创建 Repository 抽象**
|
||||
- **目标**: 隔离数据库实现细节。
|
||||
- **执行**:
|
||||
- 建立 `src/main/services/database/repositories` 目录。
|
||||
- 为业务实体 (如 Users, ExtractedPlans 等) 编写 Repository 类接口。
|
||||
- 将原有 `mysql2` 和 `mssql` 的调用逐步迁移至 Repository 中。
|
||||
3. **Zod 运行时校验**
|
||||
- **目标**: 保护 IPC 边界免受恶意/格式错误的 payload 影响。
|
||||
- **执行**:
|
||||
- 安装 `zod`。
|
||||
- 对所有的 IPC Handler 的入参（如 `ExtractorInput`, `LoginRequest`）添加 `zod` Schema 校验。
|
||||
|
||||
## 阶段三：React 渲染层规范化
|
||||
|
||||
提高前端代码复用率，解耦视图与逻辑。
|
||||
|
||||
1. **提取 IPC Hooks**
|
||||
- **目标**: 清理组件中的大段异步调用。
|
||||
- **执行**:
|
||||
- 在 `src/renderer/src/hooks` 创建 `useExtractor.ts`, `useCleaner.ts`。
|
||||
- 使用 React 的 `useState` 包装 `window.api` 调用，返回 `{ loading, data, error, execute }`。
|
||||
2. **状态管理引入 (Zustand)**
|
||||
- **目标**: 解决跨组件状态共享 (如全局报错信息、用户认证状态)。
|
||||
- **执行**:
|
||||
- 安装 `zustand`。
|
||||
- 创建 `useUserStore` 和 `useAppStore`。
|
||||
3. **UI 组件库/公共样式提取**
|
||||
- **目标**: 统一 Tailwind 设计语言。
|
||||
- **执行**:
|
||||
- 将高频使用的 Button, Input, Modal 抽取到 `src/renderer/src/components/ui/`。
|
||||
|
||||
## 阶段四：自动化服务解耦 (Domain Logic)
|
||||
|
||||
将基于 Playwright 的具体执行细节与业务调度逻辑分离。
|
||||
|
||||
1. **重构 ERP 自动化服务 (`cleaner.ts` / `extractor.ts`)**
|
||||
- **目标**: 遵循单一职责原则。
|
||||
- **执行**:
|
||||
- 抽象出 `ErpBrowserManager` (负责浏览器启动与资源回收)。
|
||||
- 抽象出 `ErpAuthService` (专职处理登录和 Session)。
|
||||
- `extractor.ts` 将只负责调度：调用 Browser -> Auth -> Navigate -> Download -> Excel Parse。
|
||||
2. **加强 TypeScript 严格模式**
|
||||
- **目标**: 提升代码健壮性。
|
||||
- **执行**:
|
||||
- 开启 `tsconfig.json` 中的 `"strict": true` 和 `"noImplicitAny": true`。
|
||||
- 全局清理并替换现存的 `any` 为具体的 Type 或 `unknown` 并添加类型保护。
|
||||
|
||||
## 阶段五：测试覆盖率补充
|
||||
|
||||
确保核心流程不被破坏。
|
||||
|
||||
1. **补充关键服务的单元测试**
|
||||
- **目标**: 防止复杂转换逻辑衰退。
|
||||
- **执行**:
|
||||
- 使用 `Vitest` 测试所有的 Repository (使用内存数据库/Mock) 和工具函数 (如 ExcelParser)。
|
||||
2. **核心业务 E2E 测试**
|
||||
- **目标**: 确保 IPC 及 Electron 整体运行顺畅。
|
||||
- **执行**:
|
||||
- 使用 Playwright 针对 Electron 的测试框架 (`@playwright/test` 的 electron 插件) 编写主流程测试：登录 -> 点击提取 -> 验证本地结果文件生成。
|
||||
|
||||
## 执行建议与回顾
|
||||
|
||||
- 每个阶段应作为一个单独的 Git 分支 (Feature Branch) 开发。
|
||||
- 完成一个阶段后，必须全量运行既有的测试套件并通过 `npm run typecheck`。
|
||||
- 本文档可作为每次 PR Review 的检查清单使用。
|
||||
Reference in New Issue
Block a user